Welcome

VTScada helps you create powerful Supervisory Control and Data Acquisition (SCADA) programs.

All features are built into the core product - there are no extra parts to install.(1) VTScada provides instant recovery, full-system failover, hardware independence, online configuration and all of the tools that you expect in a full-featured SCADA program.

If you are upgrading a legacy application to the current version, review the topics in: Moving to the Current Version

Topics are flagged to help you decide whether they apply to your situation. Most chapters have several topic levels.

  • Level 1 - general operational tools that all VTScada users should know.
  • Level 2 - basic development tools, typically covered in our Operations and Configuration course.
  • Level 3 - advanced development tools that may be covered in our Advanced Configuration course or other specialized courses.
  • Level 4 - these are for programmers and advanced developers.

For sites that log a large number of values, there are steps that you can take to improve performance significantly. Refer to the topic: Optimize Your Configuration

Closed Using VTScadaLIGHT

VTScadaLIGHT is our free version for use by schools, small sites, and hobbyists. Nearly all features are enabled, with the following restrictions:

  • Maximum of 50 input / output (I/O) tags.
    Tags that read and write from hardware, and any that you create yourself, count towards the license limit. There is no limit on other types, including ports, drivers, calculations and alarms.
  • No Alarm Notification by phone, email, text or pager.
    Configuration options for alarm notification are enabled as most have other purposes, but you cannot send an alarm notification to remote operators using VTScadaLIGHT.
    Visual and audible alarm indications on the current workstation are an entirely different feature and are enabled in VTScadaLIGHT.
  • Maximum of one thin client connection.
    Be sure to read the relevant security notes before enabling thin client connections to your application.
    VTScadaLIGHT requires a VPN for mobile access outside your network.
  • Cannot be used as a server or client (or master or subordinate) for an application that also runs on workstations with a full VTScada license.
  • Maximum of 10 free VTScadaLIGHT installations by any individual or organization, after which more licenses are available for purchase.
Closed How VTScada Works...

Developers use tags to represent hardware in VTScada. Tags are designed to work like building blocks so that you can configure them to represent any type of physical system.

  • Communication tags tell VTScada where to find the hardware and how to talk to it. I/O tags represent information being collected by the hardware and allow operators to write values out to the equipment.
  • Alarm tags (and alarms built into I/O tags) tell you when operating conditions go outside of defined bounds.
  • Historian tags record values from all alarms and from selected I/O tags, for later reporting.
  • Pages provide the display screens for information collected from hardware. Some are built in, such as the alarm display, trend viewer, reports, notes, and more. Most, you will create for your unique situation. Drawing tools are provided so that you can create clear and realistic display pages without limit.
  • Security features control who can do what within an application. You can create rules for roles based on job-descriptions, allowing you to create privilege sets that apply to many operators. You can limit the scope of rules so that operators with the same role can access only those controls that relate to the area where they work.
  • Server lists let you easily configure backup servers for fail-over. You can also use server lists to distribute tasks such as logging and alarm management between computers in large systems. The built-in Thin Client Server allows operators to monitor values and acknowledge alarms via a web interface or a mobile device. They can even receive and acknowledge alarms by SMS text message.

(1)Features are activated according to the license key that you have purchased. Adding features means only changing the license key, not integrating new software.

2026 02 13

Trihedral and VTScada are registered trade marks of Trihedral Engineering Limited
© Trihedral Engineering Limited 1987- 2026 All rights reserved.


What's New...

With each new release, Trihedral makes VTScada more powerful, yet at the same time easier to use. Explore each category to learn what new features are available.

If you have legacy applications that you want to run in the new version of VTScada, please take time to read the upgrade notes for every version between what you had been running and the current version. Depending on how your application was created, you may need to take certain steps to ensure that it will continue to run. See: Moving to the Current Version.

New Features in VTScada 12.2

Features for Operators and Developers:

A best-practices guide is included with every copy of VTScada. This is a stand-alone document (not part of these help files), which can be found in the Documents sub-folder of your installation folder.
(C:\VTScada\Documents\VTScada_Security_Guidelines_Manual.html

The manual provides guidance for installing, commissioning, verifying and maintaining the cybersecurity-certified capability of VTScada in accordance with applicable IEC 62443 cybersecurity standards.

SCADA Security Guidelines

Improved security certificate management (12.2.14)

A new UI tool, PSelectCertificate, has been created and implemented in the config folders of TCP Port tags and OPC UA Client tags for the selecting and managing of certificates. You can view, select, create, import, remove and renew certificates from the config folder.

Setup Recommendations to appear on startup (12.2.14)

A new dialog appears when the VAM starts with up-to-date performance best practices and security essentials. View all slides to close the dialog. You may opt to disable this pop-up on VAM startup and the dialog will not automatically reappear until the next update. Setup Recommendations are always accessible from the VAM menu.

Write a custom module to import tags (12.2.14)

GetAlarmList now has the optional parameter CallbackScope. Pass a reference to the desired callback scope in this parameter to receive record updates from subscribed Alarm List(s).

New Driver Multiplexer widgets for identification of the active subordinate (12.2.13)

The widget Active Subordinate identifies the current active subordinate by name and Subordinate Lines Widget provides a visual cue-- two lines that represent the primary and secondary subordinate drivers and indicates which of the two is currently active.

Configure repeating GetBulk commands over SNMP (12.2.13)

Add an SNMPGetBulkDistributor tag to a valid SNMP configuration by linking it to the SNMP driver tag. Use the SNMPGetBulkDistributor tag to specify starting OID, length of sequence and the polling frequency.

Interpolated data points for Analog devices (12.2.11)

When plotting analog data, intermediary values are interpolated (dynamically calculated from surrounding known values). Previously, values recorded at each increment of time remained static unless replaced by a new value. Now, intermediate values between known values are proportionately adjusted. The result is a smoother, more continuous slope that tends to be more closely aligned with real-world analog value changes.

+ (12.2.13) - Interpolated data mode is disabled by default. See InterpolateAnalogPlots

VoIP calls now work with optional spaces or dashes in phone numbers (12.2.11)

You are no longer required to use a strict canonical phone number format when configuring phone numbers. VTScada will now accept phone number configured with spaces or dashes. VTScada will still not accept brackets, i.e. "(", ")".

Added more control for managing Twilio voice recognition (12.2.10)

In applications that use Twilio for alarm call-outs, the setting EnableTwilioVoiceRecognition controls whether or not the user can acknowledge alarm call-outs over the phone by speaking their code out loud (as opposed to dialing it). This feature is now disabled by default. Enabling voice recognition will incur additional fees from Twilio.

OAuth 2.0 Client Credentials flow (12.2.10)

An application can authenticate itself using an OAuth 2.0 Provider. This authentication process does not require user input. Once it has been configured, the process is done machine-to-machine.

New RPC performance monitoring (12.2.09)

A new RPC Metrics section is available from the Workstation Driver tag Address Selector. Monitor local RPC queue length, local RPC queue delay time and remote machine RPC transmission delay.

WorkStation Driver tag can now display processing load as a percentage (12.2.08)

Under a new "Performance" section in the WorkStation Address Selector, processing load is now available. This option returns the current VTScada processing load as a percentage.

Added Disable Control all Alarm Button widgets (12.2.08)

All Alarm Button widgets (Ack Shown Button, Ack All Button, Ack Selected Button, Silence Button and Mute Button.) now feature a Disable Control checkbox in the properties dialog. This checkbox enables or disables the button. The button can be disabled using the checkbox, and through expressions or parameters.

PLC Alarm tag features new support for custom state values (12.2.08)

New configuration parameters in the PLC Alarm tag properties dialog permit values to be inverted or the user may supply custom values.

Toyopuc Driver Tag Expanded (12.2.07)

Added Command Relay support for use with Toyopuc PC3 PLCs. You can set a program number for each intermediate hop, along with source and destination codes.

Roster Control Status Widget (12.2.05)

Monitor the status and notification stage of your rosters. Optionally kick a roster out of a failure state to expedite testing and troubleshooting.

Parameter Selection has been Added to the Import Tag Selector (12.2.04)

The Import Tag Selector has been enhanced and features the ability to pick and choose parameters on a tag by tag basis. The parameter button becomes enabled when a qualifying tag is selected-- or just double-click the tag to open the Parameter Selection dialog.

ABB Totalflow Driver has new Trend parameters(12.2.03)

Configure the span of recorded trends by specifying a maximum number of days or maximum number of records.

Two Factor Authentication with TOTP (12.2.01)

Enable to require two authentication methods to sign in. Users would have to provide their password and a time-sensitive, one-time passcode from an authenticator every time they sign in. Setup is easy and an internet connection is not required.

Make your own Data Entry Forms (12.2.01)

Use new widgets to create your own data entry forms. Values aren't submitted until the form is complete and submitted by the user. Time offset options are available for recording timestamped data after the fact.

Export just a subtree of tags (12.2.01)

Instead of exporting the entire tag hierarchy, you can now specify a tag and VTScada will export that tag and all of its child tags. When you've finished modifying, adding or deleting tags, import the subtree back into VTScada.

SVG File support (12.2.01)

VTScada now supports Scalable Vector Graphics (SVG) image files. SVG images can be resized while still maintaining a sharp appearance. They are ideal for applications that see a lot of rescaling and are a popular format for logos. See Upgrade Notes for important information.

VTScada now supports 64-bit integers (12.2.01)

Most engine-level functions that do math support 64-bit signed integer computation (values from -9223372036854775808 to 9223372036854775807). Exceptions and special considerations for individual functions are noted on their respective reference sheets. This allows for some very high precision performance.

Activate License on Offline machines using QR Code (12.2.01)

Using an internet-connected mobile device with a camera, hover over the QR code and click the URL that appears. This will retrieve your 16-digit activation code. You may still activate your offline machine by manually copying the URL, manually transferring the URL or calling the support number.

Introducing the FBx Series DNP3 Driver (12.2.01)

Emerson FloBoss Flow Computer driver for Oil & Gas applications comes complete with an easy-to-use Address Select feature, the FBx DNP3 Driver File Read Sequence Info widget and FBx Series DNP3 Driver Stats Dialog widget.

More Meter Runs for Oil & Gas Flow Computer (12.2.01)

Meter Run tags have been unleashed from the Flow Computer tag. The Flow Computer tag can still automatically create up to 11 Meter Run tags and offers some convenient configuration convergence, but, you are free to make your Meter Run tags manually anywhere in your application and no longer limited to 11 for a flow computer.

Faster Tag Browser (12.2.01)

The tag browser now opens up to 50x faster for very large applications. Site list page performance has also greatly improved.

New and Improved Help Documentation (12.2.01)

The help documentation has improved in form and function. Navigate with specific documentation or a specific need in mind. Documentation has been organized with different audiences in mind and new information at the top of each topic provides context to get you moving in the right direction.

New tag name and UniqueID dialog with quick copy button (12.2.01)

In every ID tab of every tag properties dialog, click the ellipsis button to open a pop up displaying the full tag name and UniqueID. Add to your clipboard using the copy buttons.

New Keyboard Shortcuts (12.2.01)

VTScada now features intuitive keyboard shortcuts for the VAM, Title bar, Idea Studio, Tag Browser, Properties dialogs of tags, Historical Data Viewer, and the Source Debugger. Keypress search (begin typing what you are looking for to navigate directly to it.) is now available in the tag browser, the source debugger and the tag select dialog.

Numeric keypad for touchscreens (12.2.01)

When a user selects a numeric entry field, a dedicated numeric keypad will pop-up. This feature was designed with touchscreens in mind (but is still compatible with desktops). When this feature is enabled, Windows touch keyboard will still appear for non-numeric entry fields and any existing keyboard and mouse will not be disabled.

Automatic linking of sibling tags (12.2.01)

Tags that link automatically now automatically link to ancestors, uncles and sibling tags. Flatter hierarchies that feature linked siblings produce shorter tag names that are easier to troubleshoot and appear concisely in selectors and on reports.

Automatic linking of Historian tags with [*Historian] (12.2.01)

VTScada now supports automatic linking to ancestor, uncle or sibling historian tags.

Improvements to the Historical Data Viewer (12.2.01)

The display of digital plot lines in the HDV has been improved, removing instances of double lines.

New Publisher Selector Field in IO tags (12.2.01)

There is a new Publisher tag selector in the I/O or Calculations tab of tags that can publish data. This field will display [*Publisher] by default and will link automatically to ancestors, uncles and sibling publisher tags. A check box located beneath the selector tag will enable or disable publishing.

New Publisher List tag (12.2.01)

Configure one or more IO tags to publish with multiple Publisher tags. Link a single Publisher List tag to up to 8 Publisher tags.

Multi-Step recipes, enhanced batch details & new batch history page (12.2.01)

Run recipes with multiple steps. See historical batch information in a filterable batch history page and open a batch details page to display specific information about each batch including a configurable HDV.

Externally start a recipe batch (12.2.01)

Integrate VTScada into your existing system. Start batches from your existing UI while managing and monitoring with VTScada.

Recreate your historian across Data Diode (12.2.01)

Transmit historian data from a high-security application to an external application via Data Diode. A device that can only transmit information in one direction; letting data out while maintaining the invulnerability of the secure network.

Address Assist for workstation status driver (12.2.01)

Once a Workstation driver is linked to an analog I/O & Calculations tag, buttons will appear next to address fields in the device tag. These ellipses buttons open an address assist menu with options for workstation status monitoring.

MQTT network publishing and subscribing using Sparkplug B (12.2.01)

New Sparkplug B Edge Node and Sparkplug B Edge Device tags. Configure your Sparkplug B compatible MQTT network, publish data to a broker and optionally issue commands to devices. The pre-existing MQTT driver remains as a great option for hosting MQTT data.

Refreshed Calendar (12.2.01)

The appearance has a modernized feel and it is now easier to navigate to distant dates by clicking on the month & year at the top. Click once to jump to a month, click twice to jump to a year. The arrows on the right will flip the calendar in single-month increments.

Twilio accepts spoken alternative ID (12.2.01)

When responding to an alarm notification by phone, you can dial it or speak it out loud. (Only for alarm notification configured using Twilio).

+ (12.2.10) Twilio Voice Recognition is disabled by default. See: EnableTwilioVoiceRecognition

New or changed Tags

ABB Totalflow Driver | New settings in the Trend tab to configure trend span by timestamp or sequence length.
Data Diode Client Tag | Data Diode Client tag receives data from Data Diode to recreate in the Historian
Data Diode Publisher Tag | Data Diode Publisher tag publishes data outside a secure network across a Data Diode to be received and recreated by a client application.
Enron Modbus Driver | Use GetLastTimestamp(HistAddress) to obtain the last timestamp for the specified HistAddress
FBx Series DNP3 Driver Tag | Emerson FloBoss Flow Computer driver for Oil & Gas applications.
Flow Computer Tags | No longer limited to 11 meter runs to a flow computer.
Meter Run Tags | Can be created manually anywhere in your application.
PLC Alarm Tag | New configuration options for custom state values.
PublisherListTag | Publish data from one or more IO tags to multiple publisher tags.
Rate of Change Tags | Sync Calculation setting added. Option to perform calculation on one designated machine and broadcast to other machines. Disabled by default.
Report Tags | In the trigger tab, the "Workstation" field is now "Generation Modes". More control over where your reports are generated.
Sparkplug Edge Device | Sparkplug B Edge Device for Publishing with MQTT. Must communicate through an Edge Node. Also accepts write commands.
Sparkplug Edge Node | Sparkplug B Edge Node for Publishing with MQTT. Also accepts write commands.
Toyopuc Driver | Added Command Relay support for use with Toyopuc PC3 PLCs
Workstation Status Tag | New address select for easier configuration.

New or changed Widgets

Ack All Button | A Disable Control checkbox enables or disables the button. The button can be disabled using the checkbox, and through expressions or parameters.
Ack Selected Button | A Disable Control checkbox enables or disables the button. The button can be disabled using the checkbox, and through expressions or parameters.
Ack Shown Button | A Disable Control checkbox enables or disables the button. The button can be disabled using the checkbox, and through expressions or parameters.
Batch Details Widget | Recipes: Displays historical information about a batch that has been run with the option to plot values from I/O tags
Batch History List Widget | Recipes: Displays historical information about all batches that have been run
Batch Setpoints Widget | Recipes: Displays the Recipe Parameter tags of a linked Recipe Book tag and the steps, values and start times for a batch specified by timestamp.
Checkbox Switch Widget | Now with data entry form capabilities.
Clear Button Widget | Clear the fields of a data entry form.
Data Diode Client Statistics Dialog | To be used on the client application. Displays statistics about Data Diode.
Data Diode Publisher Statistics Dialog | To be used on the publishing application. Displays statistics about Data Diode.
Data Diode Start Button Widget | To be used on the publishing application. Initiates a bulk sync until outstanding data is caught up, then switches to normal sync.
Data Diode Start From Date/Time Button | To be used on the publishing application. Initiates a bulk sync from the selected date/time until outstanding data is caught up, then switches to normal sync.
Data Diode Stop Button Widget | To be used on the publishing application. Stops all synchronization over Data Diode.
Date Time Selector | Configure time offset for a data entry form.
Draw HDV Widget | When linked to a Context tag, display a read-only GridList that can be edited with the tag selector.
Droplist Widget | Now with data entry form capabilities.
FBx Series DNP3 Driver File Read Sequence Info | Emerson FloBoss Flow Computer widget for Oil & Gas applications.
FBx Series DNP3 Driver Stats Dialog | Emerson FloBoss Flow Computer widget for Oil & Gas applications.
Form Reset Button Widget | Reset the fields of a data entry form back to the original value at that timestamp.
Mute Button | A Disable Control checkbox enables or disables the button. The button can be disabled using the checkbox, and through expressions or parameters.
Numeric Entry Widget | Now with data entry form capabilities.
Silence Button | A Disable Control checkbox enables or disables the button. The button can be disabled using the checkbox, and through expressions or parameters.
String Entry Widget | Now with data entry form capabilities.
Submit Button Widget | For data entry forms. Submits all data filled out in data entry form enabled widgets on the same page.
Sync Status Indicator Widget | To be used on the client application. Indicates if Data Diode is out of sync including a timestamps of when the missing data was detected and the last time data was in sync.
Well Test Table Widget | New parameter, Digits After Decimal controls the number of decimal places displayed. (Default = 3)

Features for Programmers

.Profile and .CSV Source Debugger file access from Thin Client machines (12.2.09)

When using the Source Debugger on a Thin Client, auto save will always save to the server. You can now manually save a profile to your local machine. This file can be loaded on a machine with an installed Thick Client.

Add custom Help to a custom widget (12.2.07)

Add a custom HelpID accessible from the properties dialog of a custom widget.

Write a custom module to import tags (12.2.04)

Write a custom TagImport module to import tags using the Tag Import Selector via the Tag Browser.

VTScada now allows filtering of custom alarm fields (12.2.01)

Use alarm filter hooks to specify custom alarm fields.

Improved data window in the Source Debugger. (12.2.01)

The pop-up window to show data values has been enhanced with the following tools:

- Expand / Collapse all (useful for arrays and dictionaries).

- Toggle display type for all values.

- Filter for value (and keys in dictionaries), allowing you to locate a specific value (or key) quickly in a large array or dictionary.

Improved SQL Query Alarm tables interface (12.2.01)

Query tables containing records of configured alarms, alarms of a specific status, and locks & tokens records. Table columns have been updated to match current standards. Timestamps now reflect the time an alarm occurred, as opposed to when an alarm was configured.

New or changed Functions

AddToList | An advanced function for adding alarms to specified lists. Typically for custom lists.
Bubble | Starts a new child bubble and launches the given module into a new script thread in that bubble.
DetectFlatline | Returns TRUE if the monitored value has not changed for a specified length of time.
GetAlarmList | New parameter, CallbackScope, pass a reference to this parm to receive record updates from subscribed Alarm List(s).
GetAllTagTypesInGroup | Returns an array of all Tag Types in a Tag Group.
GetCurrentSubordinate | Retrieves the current subordinate driver value of the Driver Multiplexer tag.
GetDisplayValue | Return a tag's value in a displayable format.
GetSubordinateDriver | Returns the subordinate driver object of the Driver Multiplexer tag based on the input parameter.
GetTagList | This function has been optimized for speed.
GetOPCServerRequestRate | Get the OPC Server request rate per second.
ModuleSnapshot | Launched module that draws a module as an image.
NewTagsFullyStarted | Returns TRUE if all tags have started, have run their refresh modules and started their own children.
ODBCColumns | Returns a dictionary of column names grouped by the tables that contain them.
RemoveFromList | An advanced function for removing alarms from a specified list. Typically for custom lists.
RunInBubble | Starts a new thread in the given child bubble and launches the given module into that script thread.
SetShelved | Added parameter, "Config". Set to TRUE to pre-shelve an ad hoc alarm.
WinLocWheel | Returns TRUE when the mouse wheel is rolled while the mouse is over a specified object and a specified modifier key is held down.

New or changed Properties

BristolFailoverCount | Change default failover rate for Bristol drivers if failover is happening too quickly.
DrawQRCode | Draw a QRCode from GenerateQRCode at a given location.
EnableIOSyncOfRequestedValue | Causes clients to retrieve the mismatch status of the IO tag from a server on application startup or servership changes.
EnableSiblingTagAutoLinking | Enable expanded auto linking. Disabled by default in pre-existing applications. Enabled by default in new applications.
EnableTwilioVoiceRecognition | Enable to permit operators to speak their alt ID out loud when responding to a call-out.
HideInaccessiblePages | Hide pages that the user cannot open.
GenerateQRCode | Generate QR code array for DrawQRCode
MaxRecipeBooksInBatchHistoryList | Limits the number of recipe books that will appear in the batch history list. Default = 30
OPCServerRequestRateThreshold | Threshold for suppressing outgoing publishes from our OPC Classic Server to clients.
OPCServerRequestRefreshPeriod | Time interval for OPCServerRequestRateThreshold (default 5s)
OnScreenKeypadNighttimeMode | Night mode for the numeric keypad
OnScreenKeypadSize | Change default size for numeric keypad
SparkplugBEngUnitsProperty | Engineering units identifier label for Sparkplug B/MQTT driver. The default will match any string that contains "Unit".
SparkplugLegacySTATE | Enable if you want the driver to use the legacy pre- 3.0.0 STATE topic and message format.
UseOnScreenKeypad | Enable numeric keypad

New Features in VTScada 12.1

Features for Operators and Developers:

Trend pen info added to HDV graph (12.1.63)

Users can now choose description to be shown in the HDV data windows.

Disable page notes on specific workstations (12.1.62)

Add the property, DisablePageNotes, setting it to 1 for specific workstations.

The Report Button widget now has start and end time parameters (12.1.62)

Note that these require UTC values.

Time Range Mode added to DrawHDV (12.1.60)

Select a custom time span to enable time range mode and display a fixed time range on the DrawHDV widget.

Two-Stage Dialing for VoIP calls (12.1.60)

VTScada now supports VoIP calls dialed in two stages with a pause in the middle. This feature is useful in cases where an extension must be dialed to reach an outside line. The length of the pause is adjustable.

Define HTTP Strict Transport Security (12.1.60)

HTTP Strict Transport Security (HSTS) is an optional security feature that instructs a web browser to communicate with VTScada using only HTTPS.

New support of DV8 Energy’s Pump Off Controller in the Oil and Gas Solutions layer. (12.1.58)

The POC-DV8 parent tag contains drivers that have been pre-configured with the addresses and poll sequences necessary for reading Dynacard data, setpoints and other telemetry values.

Override the Camera Tag Connections Limit (12.1.58)

The default of 15, set with system performance in mind, is now able to be changed up to a hard maximum of 50 connections.

DisableGoToPageAsPopup Setting (12.1.57)

The “Go to Page (Popup)” option in the Alarm Page and Tag Browser context menus can now be disabled using the DisableGoToPageAsPopup setting.

Limit Display of Notes in Note List Widget (12.1.57)

Limit the display of notes by a specified number of days or to just notes from the current day.

Expanded functionality for New Page Button Widget and New Page Hotbox Widget (12.1.57)

Classic Page Button widget and Page Hotbox widget have become legacy widgets for continued support. The new versions have new options for pop-ups, disabling functions, applying font and more options for setting parameters.

Predefined startup pages for multi-monitor configurations (12.1.57)

At sites using multi-monitor configurations, you can now define the startup page for each monitor. Configure for Multiple Monitors

Custom Documentation is now accessible on the Anywhere Client (12.1.55)

Custom help files can now be opened with desktop installations of VTScada, with the VIC thin client and with Anywhere thin clients.

Opacity editing may now be disabled within the color selector (12.1.53)

VTScada now disables opacity editing within the color selector in contexts where it is inapplicable.

New support for the Toyopuc Driver (12.1.53)

The Toyopuc Driver now supports the Relay COmmand function to forward commands to other PLCs on the network.

Expanded support for the Mitsubishi Driver (12.1.53)

The Mitsubishi Driver can now communicate with FX3U series PLCs using 1E frames.

Daylight Savings Time support (12.1.52)

VTScada now supports acquiring Daylight Savings Time information for a given year and time zone name.

Support for placeholders in parameter phrase edit field functions (12.1.52)

Display the user's realm in the application title bar (12.1.52)

By enabling the property ShowUserRealm, the user's realm will display next to their name in the title bar.

The I/O and Calculation tag can now be configured to write values outside of the Scaled Process Min and Max range. (12.1.49)

Generate a .wav file that audibly speaks an alarm (12.1.49)

MakeAlarmRecordSpeechFile() is now available for generating a .wav file that audibly speaks an alarm.

Hide the tag list scroll bar (12.1.49)

You now have the option to hide the scrollbar in the tag list widget. This option may be used to limit the number of widgets displayed.

New method of removing parameter overrides (12.1.49)

GetTagConfiguredParameters() function can be used in conjunction with OPChange or ModifyTags (with merge parameters set to false) to remove parameter overrides.

Expanded Workstation Status Driver Tag reporting (12.1.47)

Now reports current System Total Memory, System Used Memory in bytes, System Used Memory as a percentage, amount of unused RAM on the system in bytes, the amount of RAM available for use by applications and processed in bytes.

OCPP Driver has expanded support for charging events (12.1.47)

Now supports reporting the Name and TransactionID to IO tags for charging events.

Option for enhanced visual alerting when there are unacknowledged alarms (12.1.47)

VTScada now supports flashing the task bar when there are unacknowledged alarms.

Output widgets now have a Disable Control option (12.1.46)

Disable a specific control directly rather than by setting permissions on the linked tag.

The BACnet driver now supports command relinquishing (12.1.46)

BACnet addressing has been enhanced with greater support for specifying a command priority, and two new widgets are available: one for relinquishing a command and one to indicate the priority of a write.

Send SMS alarm notifications over VoIP with supported systems. (12.1.46)

If supported by your system, you can now send SMS alarm notifications over VoIP.

Smoother experience when working in the Idea Studio (12.1.46)

Now, when you click cancel in a properties dialog while working in the Idea Studio, we take your word for it and no longer prompt for confirmation.

Driver Discovery now supports Delta PLC as well as BACnet (12.1.46)

Rapid development for Delta AH, AS and DVP PLCs

Expanded list of addresses for the Workstation Status driver (12.1.47)

The Workstation Status Driver now reports current System Total Memory, System Used Memory in bytes, System Used Memory as a percentage, amount of unused RAM on the system in bytes as well as the amount of RAM available for use by applications and processes in bytes.

Operator changes to a tag's Manual Data value are now logged (12.1.45)

Changes must be made by an authorized user within the tag's Properties dialog.

The Alarm List widget can now ignore Global Tag and Area Filtering (12.1.45)

Ensure that you do not miss alarms while using the filter for other purposes.

Operator changes to a tag's Manual Data value are now logged (12.1.45)

Changes must be made by an authorized user within the tag's Properties dialog.

The Alarm List widget can now ignore Global Tag and Area Filtering (12.1.45)

Ensure that you do not miss alarms while using the filter for other purposes.

SMS Indicator Widget now displays local signal strength. (12.1.43)

This can warn you if signal strength is not adequate to send SMS alarm notifications.

Enhanced ability to edit values in the Color Selector dialog (12.1.43)

Type a new color value in the dialog without needing to navigate to a second page.

Smoother experience when working in the Idea Studio

Now, when you click cancel in a properties dialog while working in the Idea Studio, we take your word for it and no longer prompt for confirmation.

Use a single Twilio account that has multiple numbers for multiple applications. (12.1.40)

A new selection allows you to choose which number an application will use for inbound calls and texts.

User-defined widgets with text or color parameters can now use tag values for those parameters. (12.1.40)

The Delta driver can now import tags from a DIADesigner XML file (12.1.39)

In new applications using the DNP3 driver, addresses without a suffix default to event-based polling. (12.1.39)

Legacy applications upgraded to 12.1.39 are unaffected. Refer to DNP3DefaultNoScan for notes on how to toggle this new behavior.

Control Tokens are now managed as an RPC service (12.1.39)

Stale tokens or requests from disconnected workstations will be removed automatically after a configurable length of time.

Enable rotation of user-defined widgets (12.1.39)

Rotation is not suitable for many widgets, but for those that should be able to do so, a "CanRotate" flag may be added to the widget's source code.

Address Assist dialogs when using a Driver Multiplexer (12.1.39)

The I/O tags that you attach to a Driver Multiplexer tag can now use the address assist feature of the drivers that are subordinate to that DriverMUX.

Updates to the I/O and Calculations tag (12.1.39)

Memory tags can now be configured with default values.

Digital I/O tags with the same read and write address cannot be configured with mismatches Invert options.

Use the new WebSocket interface to connect to EV Charging stations running the Open Charge Point Protocol (12.1.37)

VTScada can be configured as a WebSocket server, allowing your custom modules to accept WebSocket connections.

This allows the new OCPP Driver tag to communicate with electric vehicle charging stations running at least OCPP version 1.6J

Idea Studio -> Tag Browser Improvement (12.1.37)

When linking tags in the Idea Studio, the Tag Browser will now reopen to the last-used location in the tag hierarchy (if one exists). The location is retained for each user doing configuration.

The Driver Redirect tag is now standard. (12.1.37)

Formerly available only to applications built on the Oil and Gas Layer, this container tag is now available for all applications. Driver Redirect Tag

Support for TLS 1.3 for both server and client TCP sockets. (12.1.30)

It remains the installation's responsibility to disable older protocol versions via the operating system as required.

Idea Studio Improvements (12.1.35)

When pasting a graphic into the Idea Studio, the new object will be placed wherever the cursor is currently located. In earlier versions it would be placed in the center of the screen.

The Idea Studio's "Open" dialog can be filtered for pages, widgets, or both (all). It will now remember your choice of filter for the next time you open an existing file.

Historical Data Viewer Improvements (12.1.35)

You now have a choice of text sizes when viewing a plot in the HDV.

The Thin Client/Server Setup dialog now separates servers and connection addresses. (12.1.30)

Easier to use and less prone to misconfiguration. Advanced techniques of server-specific lists, which once required custom code can now be created easily for those who need such things. Configure a VTScada Thin Client Server. Important: See notes in Moving to the Current Version

Improved identification of Driver Multiplexer tags on the Services page. (12.1.34)

The VTScada OPC UA client driver can successfully OpenSecureChannel with an OPC UA Server that does not respond with the corresponding RequestHandle. (12.1.35)

Greatly increased the number of recipes that can be exported to Excel. (12.1.30)

Up to 16,384 recipes can be exported.

Control Lock System (12.1.28)

Control Locks can be used to prevent use and operation of selected equipment via the VTScada screens. Control Locks

Control Tokens (12.1.28)

The Control Token system ensures that only one person at a time has control over a tag or set of tags. It is complimentary to the Control Locks system. Control Tokens

Alarm Suppression (12.1.28)

Separate tracking of alarms that are turned off by an expression or event versus alarms that disabled by a developer.Suppress Alarms

Recipe Import widget

For the convenience of those building their own recipe and batch management page, this duplicates the features of the import button of the built-in Recipe & Batch Management Page. (12.1.30)

Driver Discovery in the Tag Browser (12.1.27)

Initially enabled only for BACnet devices. This will search the specified location on your network for available devices. Driver Discovery

Date and time selection for memory tags. (12.1.26)

Numeric Entry widgets can now be configured to prompt operators for a date and time associated with each value they type. You can use this to record data collected outside VTScada.

Select Before Operate mode for several control widgets (12.1.18)

Set Value Button and Set Value Hotbox have been renamed "Legacy Set Value (Button or Hotbox)".

The new Set Value Button and the updated Numeric Entry Widget have several enhancements including the ability to configure confirmation such that operators must arm the write using this button (or numeric entry), then press another button to either Execute or Cancel the operation.

Set Value Button Widget, Numeric Entry Widget, Execute / Cancel Button Widget

Input tags using the DNP3 driver will now record attributes such as Quality and Comm Failure (12.1.18)

These can be used in graphics and reports.

The Alarm tag now supports "Fail to Operate" and "Unexpected Change of State" modes. (12.1.18)

Applies only for Trip alarms and only when connected to an I/O & Calculations tag. Alarm Tag

The Tag Browser now supports filtering by I/O address. (12.1.17)

Monitor service status and control which computer is the current server for any service 12.1.16

Use the Service Status page, Service Status widget, or the Service Status dialog of the Trace viewer to view the status and the architecture of the services in your multi-server application.

New security privileges protect access to the Service Status page, and the ability to switch servers.

Read strings from register-based addresses in PLCs such Delta and Modbus 12.1.17

Do so by setting the "String stored in registers" flag of the IO tag, along with specifying the length in bytes.

Tag names can now be displayed beside their value in the Historical Data Viewer and the Plot Data widgets. (12.1.15)

Updated License Management

After being activated on a workstation, a license cannot be used on another workstation until deactivated on the first. This eliminates the need for hardware locks.

Reset tag parameters to default values using a right-click. (12.1.14)

Applies only to parameters that have a default value

Toggle Switch Widgets for Digital Controls (12.1.13)

The switch widgets are not just for Selector Switch tags anymore; you can now use them for your digital I/O control tags. A new Toggle Button Widget is also available.

IEC-62443-4-1 Certification

VTScada’s Development Environment is now certified to be in compliance with IEC 62443 Security For Industrial Automation And Control Systems, Part 4-1: Secure Product Development Life-cycle Requirements.

Redesigned Roster Tags

Add a separate delay between each contact (or have none at all), and set rules for how many times one or more contacts should be tried before moving on to the next entry in the list.
Every roster can now configure its own timing for callout delays, etc.
Add up to 39 contacts in each roster. Roster Tags

A new security privilege just for Roster tags.

To allow roster configuration without granting the Tag Modify privilege, use the new Roster Contacts privilege instead of Manual Data or Tag Parameter View. Legacy applications will be updated to migrate existing accounts to use the new privilege.

Custom views of Roster contact lists (12.1.07)

(For advanced developers only) Expression code can now access an array of the contacts in each roster, displaying relevant information about each in a list that you create.

Use parameter expressions to enable / disable Roster contacts. (12.1.11)

Enable or disable one or more contacts without needing to reopen the Roster's properties dialog

Alarm Notification call-outs using Voice over Internet Protocol (VoIP)

Use an analog telephone adapter (ATA) or your existing VoIP phone system to send voice alarm notifications to operators. Using VoIP for Alarm Notification

Improved Twilio Performance

You no longer need a VTScada account as part of your Twilio configuration. Security and performance have both been improved. Using Twilio for Alarm Notifications

Recipe & Batch Processing

Create recipes for batch processes and then run and monitor them from within VTScada. Batch & Recipe Management

Updated Tag Browser

New and more powerful filtering tools make it easier to find your tags in a large application.

Authorized operators can now write to output tags directly from the Tag Browser. The Tag Browser

Updated VTScada Application Manager (12.1.08)

Applications in the VAM will now indicate their progress while loading and whether a restart is required before you can do further configuration work. The application loading indicator will be especially useful to those using a thin client connection.

Page Shuffle (12.1.03)

Create a slide show of pages. Page Shuffling

Camera Tag and Widget

This tag and widget work together to display the video feed from your network-connected cameras within any page. Camera Tag, Camera Viewer Widget

Web Browser Widget

Embed a selected website within any page using the Web Browser Widget. Navigation widgets allow controlled navigation to selected sites.

A Function Selector for those creating expressions

Use this to browse a portion of the VTScada function library for code to use in your expressions. The Function Selection dialog is available from any VTScada Expression Editor dialog. Function Selection Dialog

Programmers can add their own functions for use within the selector. Add Functions to Your Application's Library

Multiple connections from a TCP/IP or UDP/IP port

Where supported by the VTScada driver and the PLC, you can now enable multiple connections on a single TCP/IP or UDP/IP port. While radios support one TCP/IP or UDP/IP connection per device, PLCs in a plant can open dozens (depending on the PLC). This frees PLCs from the limitations of network speed and allows them to use intervals of free time to process outstanding comm messages and achieve up to ten times the throughput per second.

Drivers that support multiple TCP/IP connections include:

  • TI505 Device Driver
  • Delta Driver
  • Enron Modbus Driver
  • Mitsubishi Driver
  • Modbus Compatible Device Driver
  • Toyopuc Driver

Multiple Monitors for VTScada Internet Clients (VICs)

VIC connections can be configured to use multiple monitors. Realm Display Setup Tags
(Note: The Anywhere Client runs within a browser and therefore cannot be divided.)

SQL View tags

For those using ODBC to query VTScada data. Select tags and data attributes that will be available in named views rather than needing to sift through all properties of all tags when building your queries. SQL View Tag

A new security privilege can restrict access to the main History table for those who have the Remote Data View privilege. (12.1.07)

The new privilege is labeled: Remote Tag Value / History Retrieve. The intent is to restrict access to only those SQL Views the account is authorized to view. For backward compatibility, all existing accounts that have Remote Data Access will be granted this new privilege.

Support for POST requests to the REST interface

Allows large queries. To prevent an extremely long query from taking up excessive time and memory, a query size limit is introduced, which defaults to 32KB.

Improved security for the SNMP agent.

Expanded SNMP V3 support improves security. SNMP Driver

Define a default sort key and direction for all alarm lists.

New application properties, AlarmListDefaultSortDir and AlarmListDefaultSortKey can be added to set a default sorting key and direction for all alarm lists except the History list.

Tag attributes available to ODBC queries

Value attribute such as Questionable and Manual Data can now be ready by the ODBC interface when querying VTScada.

Enhanced Rockwell Driver

Formerly CIP, this new driver allows switching between Rockwell device protocols and modes to best suit the need, resulting in significantly faster performance.

Further updated in 12.1.10 to include a PLC Mode that connects to the 1756-DHRIO's DH+ channels, sending DF1 messages directly to the target PLCs. This provides support for customers using older PLC-5 and SLC controllers using routed PCCC over CIP through 1756-DHRIO Interface Modules.

New Delta Driver

As part of the Delta Electrics family, VTScada is being integrated with their hardware around the world. To facilitate this, 12.1 includes a dedicated driver for Delta’s Modbus-based PLCs and VFDs. To maximize throughput, this driver supports multiple PLC port connections.

Faster Installer

VTScada’s new installer is 27% smaller and 18% faster.

Script Bubbles

While VTScada already supports dedicated threads, version 12.1 allows script code to run in parallel “Bubbles” across all PC cores. (For example, the Modbus driver now runs in its own bubble.) The effect on performance is like running multiple copies of VTScada at once.

On-Screen Keyboard Support

Touchscreen PCs are now commonplace and have begun to replace single purpose Operator Interface Terminals (OITs). VTScada seamlessly supports the native Windows onscreen keyboard. Touchscreens

MultiSpeak® Support

The MultiSpeak® protocol facilitates data exchange between SCADA and various services required by electric utilities, such as outage management. Version 12.1 supports a variety of methods required by the Milsoft™ DisSPatch™ outage management system. MultiSpeak Support

Overall Total Report

Similar to the Hourly Total and the Daily Total reports, this calculates an overall total for total for the specified time period.
(Note that the X-Total reports are for values that accumulate, such as pump starts, and do not calculate things like total flow given a flow rate. For that, use a Totalizer tag.) Note that for these to calculate a total for an accumulator that rolls over each time a maximum is reached, you must specify that rollover value in the included tags' scaling parameters.

Choose whether new Tag Widgets get Tag Icon Markers and the Operator Controls menu.

When creating a new Tag Widget, you are likely to remove the Tag Icon Marker and disable the various operator controls. Now you can choose to exclude those features

Alarm Details dialog updated

The Alarm Details dialog now includes entries for both the time when an alarm normalized and when it was acknowledged. (This information has always been available in the History list.) Alarm Details Dialog

Export alarm lists from the Anywhere client (12.1.05)

When the Alarm Page is viewed in a VTScada Anywhere client, the "Copy to Clipboard" button is replaced by an "Export to CSV file" button.

I/O Tags will now write manual data values (12.1.06)

This applies only if the tag has an output address, and only if the person setting the manual data value has the security privilege configured for the tag.

Security roles at the root level can now be made visible in realms. (12.1.26)

Reduces the number of roles required by sharing base role descriptions between realms. Must be enabled on a role-by-role basis.

The BACnet driver can now import tags from your device. (12.1.06)

Additional drivers, including Enron Modbus, CAT M5X, GE Series 90, Honeywell Mercury, Fisher ROC, IEC 6087, and the ABB Totalflow, now show address information in the Address column of the Tag Browser. (12.1.10)

VTScada now supports a user interface in Traditional or Simplified Chinese, in addition to English and French.

The Source Debugger toolbar now includes a View Source button. (12.1.13)

If the source code is available for the module you are viewing, click this to open the file using your default editor.

Oil & Gas Layer Improvements (12.1.16)

When importing gas composition results from a file in the Oil and Gas Solutions layer, the Heating Value is now imported along with the rest of the results if it is available

Non-translatable parameters (12.1.16)

Parameters that you add to your pages and widgets can now be set as non-translatable. This is especially appropriate when the parameter is an I/O address.

Priority 0 (Event) alarms on I/O tags are now logged when they clear as well as when they trigger. (12.1.26)

Source Debugger Step Out feature (12.1.60)

A new break point tool. Start at the breakpoint and run the remainder of the subroutine at full speed.

New and changed tags

ABB Totalflow Driver No longer requires a third party service.
Now reads historical alarm logs.
Camera Tag | Provides a link between your network-connected camera and a Camera Viewer widget.
Delta Driver | The Delta Driver Tag supports both PLC and VFD (variable frequency drive) devices from Delta Electronics.
DNP3 Driver | Added time sync options in a new advanced properties tab.
Flow Computer Tags | Includes a new tab for configuration of CFX reports. (12.1.34)
I/O and Calculations Tag

Default deadband values and the units of input fields are now shown. Improved calculations for the default deadband amount reduce the likelihood of needing to change the value (although you should always check).

Alarms on Discrete I/O tags can now be triggered by state or upon change.

Outputs limited to within Scaled min/max by default, can now be disabled.

GE Series 90 Addressing | The GE Series 90 driver now supports %G (bit) and %GY (byte) addressing.
History Statistics Tag | Includes two new statistics: Change in Value and Change in Value with Rollover.
Honeywell Mercury Driver | This driver can communicate with several types of Honeywell Mercury flow computer devices.
Mitsubishi Driver | Now supports FX3U series PLCs and 1E frame.
Modbus Compatible Device Driver

Redesigned so that I/O reads run on a separate core, resulting in greater responsiveness and the ability to handle large applications when using Modbus.

Now uses a common Modbus Transport service for sending communications, which allows for 16-bit addresses.

Also supports multiple TCP/IP port connections between a single instance of the driver and the RTU.

Motorola ACE Driver | When viewed in the Tag Browser, the RTU ID value configured in this driver will be shown as the address. (12.1.26)
MultiSmart Station | The MultiSmart station can now support up to nine pumps in two wells.
OPC UA Client Driver | ClientCertificateName parameter is now modifiable.
Multi-Write Tags | You can now disable event logging for multi-writes that trigger automatically.
OCPP Driver | New addresses, Name and TransactionId. These will display the current name of the OCPP User Tag entry using a charger as well as the transactionID of the charge session.
POC-DV8 Tag | New DV8 Pump-off Controller compatibility. (12.1.58)
Rockwell Driver Tag

This is an updated and improved version of the CIP/ENIP Driver tag.

For those using DH+ networks, this tag will support Allen Bradley data file addressing via DF1 commands. These commands can then be routed via the PCCC protocol to communicate with PLC5, SLC and Micrologix PLCS that are connected to Control Logix gateways.

12.1.28: CIP message building has been standardized. Extensive cleanup of the related documentation.

Recipe Book Tag | Holds a set of recipe parameters and other configuration settings to be used for batch processing.
Recipe Parameter Tag | Holds the description and value of a recipe parameter.
Recipe Proportions Tag | Modifies the value of recipe parameters used in a batch.
Recipe Trigger Tag | Use to automate the start of a batch run.
SMS Appliance Tags | Added a field to configure the com port number when that information is not otherwise available. (12.1.07)
SNMP Driver | Expanded SNMP V3 support improves security.

TCP/IP Port Tags

UDP/IP Port Tags

For Modbus, Enron Modbus and TI505 drivers, enable multiple connections on a single TCP/IP or UDP/IP port
Toyopuc Driver | The Toyopuc driver provide support for all PLCs in the PC3 and PC10 lines. (12.1.26)

New and changed widgets

Bar Graph Widget | Display the values from a set of tags as a bar graph.
Batch Details Widget | Displays historical information of a completed batch. Part of the new recipe and batch process enhancements.
Batch History List Widget | A table containing entries of historical information for every completed batch. Sortable by recipe book tag, time span and keyword. Part of the new recipe and batch process enhancements.
Batch Setpoints Widget | A table displaying recipe parameters and their recorded steps and values. Part of the new recipe and batch process enhancements.
Call Manager Status Widget | Presents a picture of the current state of voice calls, displaying call attempt, failure, and incoming call counts.
Camera Viewer Widget | New. Display the MJPEG feed from a Camera tag.
Draw HDV Widget

Updated. Included an option to minimize the size of the legend. When selected, the legend will be just tall enough to show the list of pens, up to a maximum of 50% of the overall widget height.

This option is enabled automatically when opening the HDV by clicking on a widget. It does not apply to the Historical Data Viewer page.

Added Time Range Mode. Enable this mode by selecting "Custom" as the Time Span. Set a fixed date and time range to display. When Time Range Mode is enabled, the x axis can be plotted with time elapsed or time stamps by toggling Show Elapsed Time parameter in the Plot settings of the Idea Studio properties dialog.

Folders | Updated. Set the tab number to display, either initially via configuration or dynamically using an expression.
History Stats Value Widget New. Display a selected statistic of a tag's value over a selected time span.
Both can be selected by the operator.
HP Radial Gauge | New. A radial version of the HP Analog Bar widget.
I/O Multi-Text | When the linked tag's value is Invalid, use the label defined in the Style Settings tag (Exceptions tab) or double question marks: "??". (12.1.11)
Linear and Radial, Indicators and Gauges | For tag values that are out of range, an overage of up to LinearIndicatorOverage or RadialIndicatorOverage percent is allowed, and no more.
Numeric Entry Widget | Updated. New options allow horizontal alignment.
Pie Chart Widget | Display the values from a set of tags as a pie chart.
Recipe Import Widget | Allow recipe importing as a feature of your custom recipe screen. (12.1.30)
Tag List Widget | Option to remove the scroll bar, enforcing only the top N widgets being visible. (12.1.49)
Toggle Button Widget | Start on one press. Stop on the next.
Web Browser Widget | New. Display any website within a page.
Web Browser Navigate Button | Button to redirect a Web Browser widget to a new URL.
Web Browser Navigate Hotbox | Hotbox to redirect a Web Browser widget to a new URL.

Features for Programmers

Source Debugger Improvements

Set the font height. (12.1.35)

The Profiler now shows the name of the file being profiled (12.1.35)

Bubbles (CPU-specific threads)

Run modules in bubbles to take advantage of multiple CPU cores. Threads and Bubbles

The Profiler shows the name of the file at the top of the page

Helpful when tabs are open for multiple files.

Alarm Notification Template Hooks

New hooks in the Alarm Manager can be used to create customized notification templates that override existing % codes to create dynamic messages. Alarm Notification Template Hooks

Build a customized view of a Roster's contact list.

The list is view-only, not editable. Script a Custom View of a Roster

Maximum Nested Expression Depth

Limits nested expressions to no more than 200 levels. MaxNestedExpressionDepth

ClientSocket and SocketServerStart now support buffer sizing for UDP receive buffers

VTScada now has the ability to accept external language translations in the form of a dictionary. (12.1.18)

GetPhrase

Calls to Navigator (a tag's right-click menu) now support NavData structures in the parameter list.

If the parameter specifies a module to run, use of the structure provides a way to include parameters for that module. (12.1.29)

New or changed Functions

AddRead | New parameter: Deadband. Sets a minimum amount by which the unscaled values must change before a new value is reported to NewData
AddNote | Adds a note to a notebook tag. This interface is not intended as a means of logging frequent string values. It was designed for occasional notes entered by people.
AlarmCondition | New. Returns TRUE (1) if the monitored tag has an active alarm
AlarmUnAckCondition | New. Returns TRUE (1) if the monitored tag has an unacknowledged alarm.
BinaryToIP | New. Converts an IP address from binary notation to decimal.
Bubble | New. Starts a new child bubble and launches the given module into a new script thread in that bubble.
BubbleList | New. Lists the running child bubbles of the current bubble.
BubbleQueueLength | New. Reports the length of the queue of messages from the current bubble's parent bubble or one of its children.
BubbleReceive | New. Receives a message from the given bubble.
BubbleSend | New. Sends a message to the given bubble.
Case | Updated. Can now be used in steady state.
ClosePopUp | New. Close the current instance of a pop-up page. (12.1.41)
DropTree | New parameter: Optional background color for the control (12.1.63)
Edit | New parameter that when set to TRUE causes the Disable parameter to fully disable all aspects of the control.
GetAdaptersInfo | The output dictionary of the GetAdaptersInfo function now includes an "Addresses" member. (12.1.26)
GetEquipmentColor | Returns a defined Equipment Color that was set in a style tag based on the equipment type of an IO tag (12.1.27)
GetEquipmentLabel | Returns a defined Equipment Label that was set in a style tag based on the equipment type of an I/O tag. (12.1.27)
GetLiveMJPEG | Configured within a camera tag module, returns a reference to the current frame retrieved from the IP camera.
GetPhrase | Can accept external language translations in the form of a dictionary.
RunInBubble | New.
\PortManager\PortConnectSem | Updated. Three new optional parameters supporting multiple driver connections on a single port.
WKSStatus | Updated: The WksStatus function can report values greater than 100% for percentage counters such as "\\@\Process(VTS)\% Processor Time" when (for example) a total of more than one CPU core is being used by the process.
WinEditCtrl and System.Edit | Updated. Two new System parameter bits allow horizontal alignment.
DoOperate | New. Used by tags that can be operated from the Tag Browser, this displays an input dialog where users can enter the new value to write.
GetAlarmStat | New. Returns the number of alarms in the given tag and its descendents, where those alarms match the specified statistic.
GetAllSCADAPoints | New. The GetAllSCADAPoints method provides a way for an OAS Closed Outage Analysis System to request the complete list of SCADA points from a SCADA system.
GetMethods | New. The GetMethods method provides a way for an OAS to request a list of MultiSpeak methods supported by a VTScada.
GetModuleTimeStamp | Returns the timestamp of the module's source file, showing the last time it was synchronized with the application.
GetParmPhrase | Updated. Provide a dictionary instead of individual phrases. (12.1.39)
GetPhraseID | New. Returns the key matching a given phrase.
GetSCADAAnalogByScadaPointID | New. The GetSCADAAnalogByScadaPointID method is used by an OAS Closed Outage Analysis System to request SCADA analog data on demand for a specific SCADA point.
GetSCADAStatusByScadaPointID | New. Similar to GetSCADAAnalogBySCADAPointID but for Digitals. This method is used by an OAS Closed Outage Analysis System to request SCADA digital data on demand for a specific SCADA point
GetTagConfiguredParameters | To be used with OPChange or ModifyTags, this API makes it possible to revert a tag parameter to its default or remove an override by changing some configured parameters while keeping others.
IsTagOperable | New. Returns TRUE if the user is able to operate the selected tag from the Tag Browser using the right-click menu.
LargeSocketWrite | Paces the write speed to prevent exceeding the socket output buffer limit.
ListInstances | Returns a list of all instances of a module.
MakeAlarmRecordSpeechFile | Generates a .wav file from an alarm record to audibly speak an alarm.
MakeParmPhrase | New. Returns a \ParmPhrase structure given a phrase key and parameters.
OilVolumeCorrectionFactor | New. Returns a coefficient to adjust a volume of oil to different temperature and pressure conditions.
OilVolumeCorrectionToBase | New. Wrapper for OilVolumeCorrectionFactor, used to determine the volume correction factor for shifting a fluid at alternate conditions to standard conditions (60°F, 0 psig).
PercentDifference | New. Returns the percentage difference between two numbers
PingURL | New. The PingURL method provides a way for an OAS Closed Outage Analysis System to test that it can communicate with VTScada’s MultiSpeak web service.
RunInBubble | New. Starts a new thread in the given child bubble and launches the given module into that script thread.
SCADAAnalogChangedNotification | New. The SCADAAnalogChangedNotification method provides a way for VTScada to send to an OAS Closed Outage Analysis System such as Milsoft DisSPatch, notifications of changes in VTScada’s analog tag values.
SCADAStatusChangedNotification | New. This method is the same as SCADAAnalogChangedNotification, but for statuses (digitals). The SCADAStatusChangedNotification method provides a way for VTScada to send to an OAS Closed Outage Analysis System such as Milsoft DisSPatch™, notifications for changes in VTScada’s status (digital) tag values.
SetSuppressed | AlarmManager subroutine that handles the suppressing and unsuppressing of alarms.
SetUserLanguage | Changes the display to any of the languages currently enabled in the application.
ShellTemperatureCorrection | New. Returns a coefficient to adjust the calculation of volume within a tank.
SocketAttribs | Returns information about a TCP/IP socket's attributes. Added new options.
SpeakToFile | Updated to restrict the number of characters allowed in a supplied phrase.
TableInterpolation | New. Given a graph described by a CSV file containing X and Y values, this function will interpolate a Y value for any provided X value within the range of the graph.
ToggleVal | New. Toggles between TRUE (1) and FALSE (0), once each given period.
TriggerCounter | New. Returns a count of zero-to-non zero transitions during the current session.
WebBrowser | New. Displays a web browser at the given position in the current VTScada window
WebBrowserNavigate | New. Call this to cause a WebBrowser to change pages.
Zip | New. (12.1.39) Generates a zip archive of a file stream.
Deprecated or Obsolete |
Beep | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations if you have hardware that will produce a beep, but should not be used in new code.
CopyIn | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.
CopyOut | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.
In | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.
InWord | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.
MemIn | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.
MemOut | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.
Out | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.
OutWord | Deprecated. Relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.
PPPDial | Deprecated
PPPHandles | Deprecated
PPPStatus | Deprecated

New or changed Properties

AckAllAcksOnlyVisible | When set to 1 (TRUE), only those alarms that are visible in the list will be acknowledged.
AlarmListDefaultSortDir | Sets a default sort direction for all alarm lists except the History list.
AlarmListDefaultSortKey | Sets a default sorting key for all alarm lists except the History list.
AlarmSnapshotMinInterval | Minimum time to wait until alarm database saves snapshots of their state.
CallManagerAlarmPriority | Defines the Alarm Priority to use when notifying of a Call Manager voice configuration failure alarm.
CallManagerBadCallLimit | Defines the number of bad calls in a row for any voice configuration before activating an alarm.
CallManagerShowCredentials | When set to 1, VTScada will include DTMF Closed Transport Layer Security key values in the logs.
CallMgrMaxLogAge | Defines the number of seconds before log files on the hard drive are deleted. Defaults to one week.
CallMgrTraceInterval | Defines the number of seconds to wait before forcing the log out to the hard drive. Defaults to one day.
CallMgrTraceMax | Defines the number of call manager log entries that will be held internally before writing the log out to the hard drive.
CameraTagConnectionLimit | Change the default camera tag connection limit from 15 up to 50.
CIPMaxNumberofSessions | The maximum numbers of CIP Connections a user can select within the Rockwell Driver Tag.
DefaultDriverDeadbandFractionOfFullScale | Used by analog tags, this is one factor in the calculation of the default deadband used when reading values.
DeltaDigitalMaxBlockSize | For Delta drivers, limits the size of a read block for digitals.
DeltaVTSMaxBlock | For Delta drivers, limits the number of analogs included in a read.
DisableGoToPageAsPopup | Enable to disable pop-up pages.
EnableVOIP | Set 1 (true) if VoIP (Voice over Internet Protocol) is to be enabled.
IncludeAreaNotesWithTrendedTags | Set to 0 to exclude notebooks with a matching area when opening the HDV by clicking on a tag. (12.1.30)
IncludeGroupNotesWithTrendedTags | Set to 0 to exclude notebooks with a matching plot group when opening the HDV by clicking on a tag. (12.1.30)
MakeActiveAlarmUnackedWhenEnabled | TRUE to mark an active alarm as unacked when it becomes enabled
MakeActiveAlarmUnackedWhenUnshelved | TRUE to mark an active alarm as unacked when it becomes unshelved
MakeActiveAlarmUnackedWhenUnsuppressed | TRUE to mark an active alarm as unacked when it becomes unsuppressed
ManualUnshelveDoesNotAckActiveAlarm Renamed to... ManualUnshelveDoesNotAckNormalAlarm | By default a manually unshelved normalized alarm should transition to the acknowledged state unless this variable is set to TRUE
MaxSpeakToFileLength | Maximum number of characters allowed in a phrase supplied to SpeakToFile. (12.1.26)
MercuryDriverAlarmXXXPriority | Where XXX is the item number (only a certain subset of item numbers are alarms)
MercuryDriverEventXPriority | Where XXX is the item number (only a certain subset of item numbers are alarms).
MercuryDriverTAPriority_XXXX | Where XXXX is a particular trigger type
MitsubishiFailoverCount | Number of retries before failing over for all instances of the Mitsubishi type
MitsubishiPortSharedRPC | Controls whether the same RPC service should be used for all instances of the Mitsubishi driver tags that are connected to the same serial port or TCP/IP connection.
MitsubishiSharedRPC | Controls whether the same RPC service should be used for all instances of the Mitsubishi driver.
MultiSpeakLegacyIOPublish | Controls whether Legacy IO tags (Analog Status, Digital Output, etc.) are included as Multispeak tags for ScadaAnalogChangedNotification and ScadaStatusChangedNotification messages.
MultiSpeakMaxMessagePoints | Controls the maximum number of ScadaAnalog, ScadaStatus or ScadaPoint items that VTScada will send in a single message.
MultiSpeakMaxPointIDLength | Imposes a maximum PointID length, measured in characters.
MultiSpeakMessageRetries | Sets the maximum number of PingURL requests to be tried before VTScada will give up and report an error.
MultiSpeakMessageTimeout | The number of seconds that VTScada will wait to receive a response before giving up on the current request.
MultiSpeakMHCompanyAttribute | Outgoing MultiSpeakMsgHeader Company attribute value.
MultiSpeakNotificationDelay | When there is a change in value of tags that are configured to publish, a notification is sent via ScadaAnalogChangedNotification and ScadaStatusChangedNotification.
MultiSpeakPingURLProbingPeriod | Sets the frequency of checks to verify that a MultiSpeak endpoint remains available during long periods of inactivity.
MultiSpeakRealmNames | The realm names that can be used by other MultiSpeak end points to connect into VTScada. If more than one realm name is available, separate those names by semi-colons.
MultiSpeakSubscriptionMethods | A comma-separated value (CSV) list of notification methods that VTScada will send to the configured subscriber. This is equivalent to the MethodsList that would be provided in the RegisterForService method.
MultiSpeakSubscriptionPassword | Password to authenticate notification messages. This is equivalent to the ResponsePwd field in the RegisterForService method. If authentication is not required this property should be left blank (Invalid).
MultiSpeakSubscriptionURL | Destination endpoint where VTScada will send notification messages. This should be the server name (could be fully qualified) of the MultiSpeak endpoint. By default, HTTP and port 80 will be used. Port 443 will be used for HTTPS.
MultiSpeakSubscriptionUsername | Username to authenticate notification messages. This is equivalent to the ResponseUserID field in the RegisterForService method. If authentication is not required this property should be left blank (Invalid).
MultiSpeakTraceFileSize | Maximum size in MB of the MultiSpeak diagnostic trace file. When the file reaches this size, the oldest half is deleted.
MultiSpeakTraceLevel | Diagnostic trace level for the MultiSpeak service. A lower value will log only important messages to the file, while a higher level will log more diagnostic details about the service. Setting it to 0 turns off logging.
MultiSpeakTraceMemorySize | The log records written to the trace file are also stored in memory. This setting controls how many are kept in a FIFO buffer.
OPCUAClientBlockSize | Controls the maximum number of monitored items that will be placed into a single subscription in an OPC UA Server session.
RecordAlarmStatusWhileDisabled | TRUE to record the alarm status while an alarm is disabled
RecordAlarmStatusWhileSuppressed | TRUE to record the alarm status while an alarm is suppressed
RecordSuppressionStatus | TRUE to record the suppression status of an alarm
RockwellMaxUploadIdle | The maximum idle time in seconds for the tag upload procedure during tag importing.
RockwellPollB4BuildComplete | Set to 1 (TRUE) in order to poll before all reads are built.
RockwellReadsBeforeAddressError | Number of reads before setting an address error.
RockwellWriteMode | Set to 1 for Fragmented (0x53) or 2 for Tag (0x4D)
RosterFailureBackoffRate | After each failure to contact anyone on the roster, the delay before trying again is multiplied by this value, progressively increasing the time until the next attempt.
RosterFailureMaxDelay | The maximum delay after experiencing a failure to connect with anyone on a roster before trying again.
RosterFailureMinDelay | Specifies the minimum delay after failing to connect with anyone on a roster before trying again.
DisableControlWidgetIfMismatched | TRUE to disable a control widget if it is currently executing (Select Before Operate)
DisableControlWidgetIfOtherMismatched | TRUE to disable a control widget if another control is currently executing (Select Before Operate)
DisableControlWidgetIfOtherSelected | TRUE to disable a control widget if another control has already "selected" a value (Select Before Operate)
DisableControlWidgetIfSelected | TRUE to disable a control widget if it has already "selected" a value (Select Before Operate)
ShowUserRealm | TRUE to display user's realm next to username in the title bar.
SlippyMapCriticalDiskSpace | The maximum amount of disk space, measured in MB, that VTScada will use for storing map tiles.
SlippyMapMaxTileSize | Maximum allowable size of a tile, measured in bytes.
SNMPAgentSNMPVersion | SNMP version used by the VTScada SNMP Agent.
SNMPAgentTagExposedProperties | Defines a list of tag properties to identify in the SNMP MIB generated by VTScada.
SNMPDriverLegacyV3Notifications | In legacy applications (those built prior to the release of VTScada 12.1), notifications carrying different usernames were accepted if they had the same credentials.
SNMPDriverOctetStringMaxSize | Specifies the expected maximum size in bytes of OCTETSTRING data to be read by any SNMP driver in the application.
SNMPFailoverCount | Controls how many connection attempts will be made before a failure is set and an alternate is recommended.
SNMPv3AgentMinSecurityLevel | This specifies the SNMP security level the VTScada SNMP agent will use when the SNMP version is set to v3.
SNMPv3AgentReadAuthPassword | Encrypted authentication password for the read user. This property can be set only by using the fields provided in the 'Other' tab of the Edit Properties dialog, basic mode
SNMPv3AgentReadAuthProtocol | Specifies the authentication protocol in use for the username defined in SNMPv3AgentReadUser.
SNMPv3AgentReadPrivPassword | Encrypted privacy password for the read user. This property can be set only by using the fields provided in the 'Other' tab of the Edit Properties dialog, basic mode.
SNMPv3AgentReadPrivProtocol | Specifies the privacy protocol in use for the username defined in SNMPv3AgentReadUser.
SNMPv3AgentReadUser | Username for an SNMPv3 user with read-only permission.
SNMPv3AgentTrapAuthPassword | Encrypted authentication password for the trap user.
SNMPv3AgentTrapAuthProtocol | Specifies the authentication protocol in use for the username defined in SNMPv3AgentTrapUser.
SNMPv3AgentTrapPrivPassword | Encrypted privacy password for the trap user.
SNMPv3AgentTrapPrivProtocol | Specifies the privacy protocol in use for the username defined in SNMPv3AgentTrapUser.
SNMPv3AgentTrapUser | Username for an SNMPv3 user for sending traps.
SNMPv3AgentWriteAuthPassword | Encrypted authentication password for the write user.
SNMPv3AgentWriteAuthProtocol | Specifies the authentication protocol in use for the username defined in SNMPv3AgentWriteUser.
SNMPv3AgentWritePrivPassword | Encrypted privacy password for the write user
SNMPv3AgentWritePrivProtocol | Specifies the privacy protocol in use for the username defined in SNMPv3AgentWriteUser.
SNMPv3AgentWriteUser | Username for an SNMPv3 user with read and write permissions.
SQLQueryMaxRequestLength | Sets the maximum payload size (measured in bytes) that will be accepted by the VTScada HTTP server in a REST or SOAP request.
SQLQueryMaxResultCells | Sets a maximum amount of cells, which is the number of rows times the number of columns, that will be returned in response to any SQL query.
SQLQueryParserDepthLimit | Controls how deeply-nested SQL queries may be, when run against the VTScada SQL API.
ThinClientDisclaimer | Specifies the name of an HTML file that will be displayed to operators connecting to the application via a thin client (VIC or Anywhere).
TwilioPickupDelay | Sets the interval in seconds from when a Twilio call is initiated until speech starts.
UseLegacyEventPriorityAlarmBehavior | Records priority 0 alarm transactions as events rather than non-annunciating alarms. (12.1.30)
VICDistributionPath | Path to the distribution file for the VTScada Internet Client. Replaces ClientCabPath.
VOIPPickUpDelay | Sets the interval in seconds from when a VoIP call is initiated until speech starts.
VOIPRegisterTimeout | Defines the preferred registration interval in seconds when connecting to a VoIP provider.

Related information:

Moving to the Current Version


Moving to the Current Version

Your VTScada license entitles you to upgrades for a period of time after purchase. (Maintaining a Support Plus contract provides unlimited upgrades.) You can find the end date of your SupportPlus period in the About dialog, accessible from the VTScada Application Manager. Each new version of VTScada introduces new tools and sometimes changes how older features work.

Notes:

  • Review the lists of changes for each version of VTScada between the one you are upgrading from and the current one, to find additional tasks that you may need to perform.
  • If your application runs on a single server, create a backup before starting.
    (With multi-server applications, it is always better to let VTScada look after backups and redundancy.)
  • In general, it is better to install a new version on top of an older version.
  • VIC clients should be updated with each server update. Older versions may work but will not have newer features or security updates.
  • Text in expressions or custom modules is not added to your languages CSV file automatically. In a multilingual application you must add your own phrases to the language file.
  • If your VAM has an instance of the Training Simulator, uninstall it. The simulation code is subject to change from one version to another and older versions are sometimes not compatible with the current version of VTScada. If you are still using the simulator, then after upgrading reinstall from the newest .Snapshot file in the Examples folder.

General Upgrade Procedure:

In a networked system, upgrade one workstation at a time.

You are advised to update the primary historian last.
You must update I/O clients before I/O servers. Check that the machine you are updating is not a server for any driver.
These two warnings may mean that you will need to adjust your server lists temporarily. The original list may be restored after all servers have been upgraded.

Test the conversion process on an application clone, reviewing the effects in the version log.

If auto-deploy is on at this server, turn it off before stopping the older version of VTScada.

  1. Shut down VTScada on the server you are updating.
  2. Run the installation program, installing to the existing folder.
  3. Restart VTScada and run your application.
    Confirm that the application runs as expected.
  4. Deploy the changes.
    (Auto-deploy may be switched back on if you are using it.)
  5. Proceed to the next workstation.

  6. If you adjusted your server lists (as per the first caution statement), then after all workstations have been upgraded, restore the server lists to the original.

VTScada 12.2

  • As of 12.2.14, VTScada supports scaling page notes. Page notes must have a scope of "This Page" or "All Page Notes of this Page Type" to scale. Page notes that originated on older versions of VTScada must be re-saved to enable scaling. Double-click to open the edit panel, and click save

  • If you are incurring delays when launching the VIC on air-gapped systems, this may be a result of how Windows refreshes its Certificate Revocation Lists (CRLs) from the Windows Update websiteTo mitigate the delay, turn off Automatic Root Certificate Updates in your Group Policy Editor. See Security for more details.

  • As of 12.2.10, Twilio voice recognition is disabled by default. If you are using Twilio and VTScada version 12.2+, we strongly encourage you to update to the latest version. See EnableTwilioVoiceRecognition to enable or for more information.

  • As of 12.2.03, all new applications will have a default minimum password length of 8 characters. (See PasswordMinLen). The minimum password length of pre-existing applications will be unchanged, however, it is recommended that all passwords be at least 8 characters long and to remove stagnant accounts (such as accounts made for testing purposes) especially if they have very short passwords (ex. "a")

  • Tags that have automatically linked to a parent tag (linking to Driver tags, Port tags, Alarm Database tags, Publishers, Historians, Style Settings and so on...) will now be able to automatically link to ancestors and siblings. Direct ancestors will prevail over siblings. The siblings of direct ancestors count as ancestors. This new behavior will be disabled in applications that existed before this update until the setting EnableSiblingTagAutoLinking is enabled. Legacy behavior will likely still be preserved, presuming that tags that are configured to auto-link already have a parent tag that they are linked to. New applications will have EnableSiblingTagAutoLinking enabled by default.

  • Important considerations for using .SVG images: SVGs are resource heavy. Reconsider your file type if the image is larger than 1MB or will be redrawn often. Animated SVGs are not supported. Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load. SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

  • To help distinguish between OPC DA and OPC UA, the OPC Server Setup tag has become the OPC Classic Server tag, representative of OPC DA. Where a distinction would add clarity, "OPC Client" has become "OPC Classic Client", "OPC DA Publisher" has become "OPC Classic Server" and "OPC UA Client Driver" may be called "OPC UA Client".

  • Most engine-level functions that do math support 64-bit signed integer computation (values from -9223372036854775808 to 9223372036854775807). Exceptions and special considerations for individual functions are noted on their respective reference sheets. In an overflow situation, where the result would exceed the 64-bit signed integer range, or if at least one of the values is not within the 64-bit signed integer range, arithmetic is done with the precision of 8-byte IEEE floating point numbers. The legal value range of values is ±10^307, with a precision of approximately 15 decimal places.

  • Bitwise engine-level functions that perform Boolean logic will work with 64-bit signed integers.

  • The #VTypeLong value type now means 64-bit signed integer as opposed to 32-bit signed integer.

  • The number -9223372036854775808 (the smallest 64-bit integer) cannot be compiled like that. The coder needs to use -9223372036854775807 - 1. This is because the smallest 64-bit number -9223372036854775808 compiles as the unary minus operator applied to the positive number 9223372036854775808. That positive number is one more than the largest signed 64-bit integer, so it is handled using a double, and hence precision is lost.

  • Tags that have automatically linked to a parent tag (linking to Driver tags, Port tags, Alarm Database tags, Publishers, Historians, Style Settings and so on...) will now be able to automatically link to ancestors and siblings. Direct ancestors will prevail over siblings. This new behavior will be disabled in pre-existing applications unless EnableSiblingTagAutoLinking is enabled. Legacy behavior will likely still be preserved, presuming that tags that are configured to auto-link already have a parent tag that they are linked to. New applications will have EnableSiblingTagAutoLinking enabled by default.

  • The CRC function now returns positive values rather than negative. The bit sequences are unchanged.
    This is a side effect of the switch to 64-bit values in version 12.2. Versions from 12.1.60 onwards that included the pre-release version of that feature are also affected.

Closed VTScada 12.1

  • Users with the "Tag Parameter View Privilege" and "Control Outputs Privilege" privileges can now operate any tag that they can see in the Tag Browser, where before they would have needed to have access to a page with control widgets.

  • If an outbound socket has more than 64Mb of outstanding data to be transmitted, the socket will be closed to avoid excess resource consumption. For high-volume socket writes, \System. LargeSocketWrite (12.1.57) should be used (12.1.52) and will throttle the write to avoid overrunning the socket. Attempting to write a large stream or buffer that exceeds the limit will fail silently and no data will be transmitted.

  • As of release 12.1.42, logging of I/O tags has changed as follows: Values will be logged on interval OR on change but not both. If both are needed, create a second (free) I/O tag using an expression that watches the value of the first tag. Log the first on interval and the second on change. Attempting to do both on the same tag introduces a small but important risk of values being recorded out of sequence if the remote device is sending timestamped data and its clock is not synchronized with the server.

  • The "V12 Training Simulator.ChangeSet" application is not compatible with version 12.1.
    Do not use. Delete all copies.
    The "Training Simulator.snapshot" application should be used in its place.
    You are advised to replace this application with the newest snapshot after each upgrade.

  • The DNP3 driver has been updated to default to event-based scanning for addresses without a suffix. Refer to notes in

  • (12.1.30) The ThinClient/Server Setup dialog has been redesigned to separate servers and connection addresses. When upgrading, the default address list and associated connection parameters will be populated automatically from the existing server list and connection parameters. Existing VICServerList variables or subroutines at OEM or application layer are still supported. Those will be used preferentially over any coming from the new GUI.

    The ManualVICServerLists option is no longer supported.

  • If an alarm is unacknowledged before being shelved then it will still be unacknowledged when no longer shelved, even if it normalized while shelved.

    This was changed to be consistent with the behavior when disabling / re-enabling or suppressing / unsuppressing an alarm.

  • The Setup.INI property, ThinClientFraming, restricts sites that may place a thin client within an iframe. Reasons to do this include mitigating possible UI redress attacks (clickjacking Closed An attacker uses multiple transparent or opaque layers to trick a user into clicking on a button or link on another page when they were intending to click on the top level page). The default value of 'none' may affect customers who were relying on exactly that behavior.

  • Nested expressions are now limited to 200 levels by MaxNestedExpressionDepth. IfElse expressions with more than 200 cases will not run. (12.1.15)

  • UTF-8 Byte Order Mark (BOM) now added to CSV output (12.1.07)

    CSV output files created from the Reports page and Historical Data Viewer now include a three-character BOM at the beginning of the file to ensure correct display in Microsoft Excel. This may interfere with some third-part programs, which will need to be modified to account for the additional characters at the beginning of the file.

  • Shared Security (Security Provider selection) is flagged as a deprecated feature and will be removed in a future version of VTScada. Windows Security Integration is suggested as an alternative.

  • All analog tags are subject to a new filter on I/O drivers, designed to prevent system noise from slowing your system. This defaults to 1/10 of one percent of the scaled range. Review DefaultDriverDeadbandFractionOfFullScale

  • Drivers other than those in the following list cannot share a port with the updated Modbus driver:

    Enron Modbus, Delta Driver, Bristol Driver in BSAP mode.

  • The WksStatus function can report values greater than 100% for percentage counters such as "\\@\Process(VTS)\% Processor Time" when (for example) a total of more than one CPU core is being used by the process.

  • In VTScada 12.1 the VTScada Internet Client can be launched from any browser. Customers who have a branding arrangement with Trihedral and wish to hide the VTScada Internet Client from the list of connection options should refer to branding page for additional options. In particular, look for the new option, showDisplayVIC.

  • The POC-Weatherford and POC-Unico pump-off controller tags from the Oil & Gas Solutions contained a large number of unused disabled alarms. These alarms have been removed (decommissioned) in 12.1. If you had enabled any of these alarms in order to make use of them, you will need to add (commission) these alarms again by setting the alarm priority to an appropriate value. Otherwise these alarms will never activate.

  • The VTSCPU address from the Workstation Status tag will report 100% when all logical processors are being used their fullest by VTScada. In previous versions, VTSCPU was capped at 1 divided by the number of logical processors.

  • The CIP/ENIP driver has been replaced by the Rockwell driver. All legacy CIP/ENIP tags will be converted automatically.

  • The VTSIO driver is no longer included in the installation file. It will continue to exist in legacy installations that are being upgraded. This affects the following functions, all of which relied on the VTSIO driver and therefore should not be used in new code: Beep, CopyIn, CopyOut, In, InWord, MemIn, MemOut, Out, OutWord.

  • The Parameter View security privilege has been renamed to Tag Parameter View.

  • To update a Roster contact list without the full Tag Modify privilege, you must have the Edit Roster Contacts privilege.

    Legacy applications used the Manual Data or Tag Parameter View privilege. Accounts with those privileges will be granted the Edit Roster Contacts privilege on upgrade. The older privileges will no longer serve to modify the roster.

  • The RosterDelay property no longer sets a delay between contacts in a Roster. Delays are now set explicitly within each Roster's contact list and the RosterDelay property now serves only to provide a default value when defining delay rules.

  • The upgrade process will modify the version log if a workstation was renamed after your application was installed on it. (i.e. the application was installed on a legacy version of VTScada, the machine was later renamed, and now you are upgrading to 12.1)

    What you will see in the application's Version Log will differ as follows: There will be a new entry in the Workstations list for the renamed workstation. The old application history will still be available, but it will be listed under the name the workstation had when the application was first run on it.

    More importantly, if the workstation was on a local branch at the time of the upgrade, then the upgrade process will cause an automatic switch to the most recent deployed revision, discarding the local changes. Those changes will still be available in the version log under the old workstation name, so they can still be merged into the local workstation if needed. If the renamed machine does not have any local changes, then the configuration on the local machine will not change, other than the workstation name, as noted.

  • If upgrading a machine that has local changes and if you suspect that the machine may have been renamed, then examine the version log before running their application. Merge in the local changes listed under the old workstation name, if any.

  • If using OAuth 2.0 ensure that all servers are using 12.1 or 12.0. OAuth tokens will not be handled properly if your servers run a mix of these two versions.

Closed VTScada 12.0
  • 12.0.42 - If an Historian tag was using a machine-specific expression for the Storage Name parameter, the uptime data would only be available for the local machine. This could present an incomplete view of the overall system uptime. In this release, a parameter was added to HistorianConnect that is always set to the Historian tag’s unique ID to avoid this problem. A side effect is a loss of access to uptime data for customers who were using a workstation-specific expression in the “Storage Name” setting of the historian tag.
  • 12.0.38 - The AutoLogon property no longer exists. Those relying on that property for kiosk installations should use more secure method as described in Securing a VTScada Thin Client Server
  • 12.0.29 and all later versions - If upgrading directly from a version of VTS prior to 10.1.03, any users with a password containing either 31 or 32 characters will NOT be able to sign in and will require a manual password reset by a manager.
  • 12.0.22 - Localhost addresses are no longer permitted in the Thin Client Server configuration dialog.
  • 12.0.20 - TCP and UDP ports with neither address nor port number will now do nothing. This differs from the previous behavior where the port would automatically become a listener on a default port.

    TCP and UDP ports that were using the default port numbers (3001 for TCP and 3123 for UDP) will no longer use these port numbers automatically and will no longer function as a listener or a client. To resolve this, they will need to be edited to use these port numbers explicitly.
  • The VTSIO driver continues to be included with VTScada, but is no longer installed. On older systems, this provided support for direct I/O and hardware such as the PC speaker. On modern systems .DLLs are used to access hardware interfaces.

    In the event that you do need the VTSIO driver, you can install it using the following command, using an elevated prompt. Replace the paths as needed for your installation folder. Use an absolute path to the install log and ensure that it is in a writable location.
path\to\VTSIOUpdate.exe -i <path\to\VTSIO.inf> -f <path\to\install log>
  • Support for Windows Vista has ended. Do not attempt to run VTScada on that operating system.
  • For your security, Windows DDE is disabled by default. Sites that make use of this technology may choose to enable the feature. Do so by starting VTScada with the command line switch, /D
  • Historian records now contain an addition field to track edited historical data. If you roll back or synchronize with an older version, you may lose access to the history that was generated by the new server. It is recommended that you update the primary historian last.
  • If creating an AlarmConfiguration structure, which is done by calling GetAlarmConfiguration, note that the Custom field may no longer contain a dictionary.
  • In the redesigned security dialogs, "security realm" replaces "user group". Realm sign-ins can now be enabled using dialogs rather than editing properties.
  • Security rules can no longer be applied to (or, for legacy applications, removed from) roles.

    If your legacy application contains roles, to which rules have been applied, you must remove those rules before moving to the current version. After updating, existing rules will still apply to the roles, but you will have no means of editing those rules.

    Security rules can now be applied only to privileges, gathering those together into appropriately named roles.
  • To avoid breaking any existing ODBC or SOAP interfaces to VTScada data, the new security privilege, "Remote Data Access" is automatically granted to existing accounts. You may wish to remove this privilege from some accounts.
  • As of 12.0, VTScada supports Unicode, UTF-8. Any displayed text that contains special characters (byte values above 127) will be converted to Unicode (UTF-8). The vast majority of installations do not use special characters, therefore there will be no change. Of the sites that do, the most common special character is a degree symbol in a description or engineering unit field. ( °C ).
  • All text in the VTScada user interface (including your tag descriptions, areas, page names, etc.) is stored as phrases in the default language file (<application folder>\Languages\EN.CSV) where each is given a unique identifier. Use the tools provided in the Application Configuration dialog to change this file if needed. Do not edit the file directly.
  • You will not notice any difference while working within VTScada, but those who work with source code will now see the phrase identifier key instead of the text. For example, the title of a new page if viewed in source code, will be similar to:

    Title = "De7DTnP";

    Operators will see the assigned title and never the phrase identifier key.
  • Expressions that refer to text parameters of tags or application properties will be updated for you. For example:
Concat(..\Area, " ", ..\Description),  " position control")

becomes

Concat(..\Area, " ", PickValid(\GetPhrase(..\Description), ..\Description),  " position control")

Note that in this example, " position control" remains English text. If you intend to make your application available in other languages you must create a phrase for those words and substitute the phrase key, or a parameterized phrase (\ParmPhrase).

  • New expressions that refer to text parameters of tags must use \GetPhrase(key). See Multilingual Expressions.
  • Labels and other text that were stored in application properties are now stored in the language file. This includes commonly-used properties such as AlarmDialerTemplate, DialerLocation, AlarmEmailTemplate and others. It is possible (but discouraged) to use these application properties rather than the language file in uni-lingual applications, but to do so, you must now insert them rather than search for the OEM-layer instance to copy and modify.
  • When running a legacy application in 12.0 or later, tag parameters that store text (description, engineering units, etc.) are updated to use phrases. For child tags of user-defined types, these fields will be shaded orange when viewed in the properties dialog, but the tag is not considered to have overrides unless you close the dialog by pressing OK.
  • Anyone who has used the VTScada scripting language to write a custom tag is advised to update their code to use the new phrase functions.
  • When writing VTScada script code, make sure that the text (typically special symbols or non-Latin scripts) are entered in UTF-8. Many editors will allow you to specify that the file be saved in UTF-8 but may default to a different standard.
  • Ensure that your files do not include a byte-order-mark (BOM).
  • All variables names in VTScada script code must continue to use ASCII-standard characters.
  • Any function displaying or accepting text input assumes UTF-8. Functions that work with sub-strings remain unchanged and continue to count bytes, not characters.
  • Displayed text will compress horizontally by up to 35% before being clipped.
  • If you roll back to a pre-12.0 version of VTScada, you will need to re-enter all text. (Or, use the repository to roll back to a version before the 12.0 upgrade.)
  • It may happen that encryption keys and special strings are improperly converted when an application is first imported to 12.0.
  • Code that uses MatchKeys to watch for particular symbols should continue to work but should be tested. (Note that under Unicode, there can be more than one encoding for some characters and symbols.)
  • UTF-8 will allow text to display correctly in non-Latin scripts, but may cause problems if you roll back to an earlier version of VTScada.
  • If you need to roll back to an earlier version, use the version control system to revert the repository changes that were made automatically as a result of upgrading.
  • The VTScada Internet Client (VIC) is not compatible across versions before and after 11.5 / 12.0. If connecting to an 11.5 / 12.0 server, you must use the 11.5 / 12.0 client. If using the 11.3 or earlier server, you must use a pre-11.5 client.
    Clients will function, but symbols and certain characters will not display properly.
  • The [Labels] section of configuration files will become a hidden <Labels> section. Do not work with labels in this section as your edits will be ignored. All labels are now stored as phrases in the default language file.
  • SlippyMapRemoteTileSource1 is no longer a property in the System section of Setup.INI. It is now a section in its own right, containing a set of properties that define the tile source. [SlippyMapRemoteTileSourceN] Section
Closed VTScada 11.3
  • WatchForTagChanges is now marked as deprecated. Use WatchTags in new code.
  • The Profiler is now integrated into the Source Debugger. Users who are upgrading from earlier versions of VTScada are advised to delete the stand-alone Profiler application from their VAM.
  • Version 11.3 introduced support for IPv6. Note the following changes:
    • Network Status tags should be reconfigured to refer to Network Adapter Names instead of Machine IP values.
    • The variable, WkStnIPList, is deprecated but maintained for backward compatibility. It contains only IPv4 addresses.
    • BinIP2Text and TextIP2Bin are deprecated but maintained for backward compatibility. Do not use in new code.
    • TCPIPReset is deprecated and non-functional.
    • Two new options have been added to SocketAttribs for use with UDP datagrams.
  • Version 11.3 introduced support for IPv6. Note the following changes:
    • Network Status tags should be reconfigured to refer to Network Adapter Names instead of Machine IP values.
    • The variable, WkStnIPList, is deprecated but maintained for backward compatibility. It contains only IPv4 addresses.
    • BinIP2Text and TextIP2Bin are deprecated but maintained for backward compatibility. Do not use in new code.
    • TCPIPReset is deprecated and non-functional.
    • Two new options have been added to SocketAttribs for use with UDP datagrams.
Closed VTScada 11.2
  • Activation is now required for all versions of VTScada.
  • Any declarations of TRUE or FALSE as constants in custom code must be removed.
  • Version 11.2.22 improved the performance of network values. All custom application code that makes use of network values should be tested to ensure its correct operation with the new service.

    In particular, the network values service formerly set its "Started" flag after the PC became either a server or a client, at which time a tag could call the Register() function, after which all of its variables setup as network values would be set to match the server’s values. This is no longer the case as the Started flag is now set after the service running with no guarantee that values are setup to match the server’s values. If you custom code requires this still then you may need to monitor the RPCStatus value of the service to ensure synchronization
  • VTScada logo images are now protected by a checksum. VTScada will not start if these files have been removed or modified. If you wish to create a custom-branded application, contact Trihedral Engineering for licensing.
  • The updated SHA-256 signing certificate used for Trihedral drivers will be recognized by older Windows® operating systems, but they will not be able to save your response to the "Always trust content from Trihedral?" prompt. The question will be repeated during each installation.

    This is a known problem with Windows 7 and Windows Server 2008 workstations. A hotfix is available from Microsoft at: https://support.microsoft.com/en-us/kb/2921916
  • The IVONA voice engine is no longer supplied with VTScada. Customers who have this engine from earlier releases may continue to use it with version 11.2 and beyond. Your license will not expire.
  • Wide Area Protocol (WAP) support has been removed from VTScada.
  • CIP driver addressing has changed. All I/O tags with the older style, which used formatted bit addresses, must be manually reconfigured to use the new format. This is a one time only process.

Old system:

  1. Array Tags Of INT or DINT -> TagName[n][b]
  2. Array tags of BOOL -> TagName.n
  3. Simple tags of INT & DINT -> TagName[b]/BIT

New system

  1. Array Tags Of INT or DINT -> TagName[n].b
  2. Array tags of BOOL -> TagName[n]
  3. Simple tags of INT & DINT -> TagName.b

  • Widgets that are invisible (Opacity == 0) no longer start. Some applications may have used invisible widgets to control the trend view that would open in response to a click in a certain area. That technique will no longer work. You can work around this by changing the opacity to an extremely small, but non-zero value for widgets that you do not want to see, but do want to continue to respond in the user-interface.
  • The following punctuation characters are now defined in the speech lexicon to be pronounced as if they were a space character. (That is, treated as a break between words.) Users may define alternate pronunciations, if desired.

    _ @ # $ % + = < > & / \ * ; |
  • Fonts with a weight less than four (4) will be extremely faint on an Anywhere client. Fonts with a weight greater than seven will extremely dark. If using font weights less than four or greater than seven, you may need to adjust these for use with the Anywhere client.
  • The Alarm Manager module, SetShelved, has a new parameter list. All legacy code that used this function must be updated before being used in 11.2
  • Special handling for orange 241 and transparent black is no longer supported for .PNG format files. These colors will work as they always have for .BMP files.
  • The "." character now serves as the equivalent of Scope( , , TRUE). Thus, Obj.Value is equivalent to Scope(Obj, "Value", TRUE).

    Note the following:
    • When writing expressions, the "." character should now be used instead of the backslash operator when the intent is to reference a value that should be in the referenced scope.
    • In earlier versions of VTScada, the "." character was legal within variable names. (No longer true.)
    • To avoid problems that would occur if a legacy application with the "." character in variable names was loaded into version 11.2, the property declaration "LocalScopeSyntax = 0" will be added to Settings.Startup when those legacy applications are added to an 11.2 installation. This will prevent the "." character acting as a local scope operator in those applications.
    • If you are certain that your legacy application does not contain variable names that include the "." character, you may set LocalScopeSyntax to 1 to make use of the "." character as a scope operator in new code.
  • The AlarmManager server list is no longer used in 11.2. You should now use the SystemAlarmHistorian server list in its place.
  • When you first start your legacy application in 11.2, VTScada will copy the "Default for Workstation" section of the AlarmManager server list into the server list of SystemAlarmHistorian. It does not copy the workstation-specific settings because they will probably not apply within the new paradigm. It is not necessary to have workstation-specific lists of servers now that Historian client-storage is enabled in the System Alarm Historian tag.
  • For custom tags, the use of GetAlarmObjVal is now obsolete, as is the requirement to place multiple built-in alarms into their own submodules of the tag structure.
  • Any overrides of Alarm Manager modules may continue to work, but should be tested thoroughly. As of version 11.2, the technique of overriding an Alarm Manager module to add extra functionality has been deprecated in favor of custom hooks.
  • Several Alarm Manager functions are deprecated in favor of new functions and work-methods. Refer to the following in the VTScada Programmer's Guide and Function Reference:
    • Alarm Manager
    • Add Alarms to Custom Tags
    • Alarm Functions
  • Any custom code that is using "AlarmManager" as an RPC service name will no longer work. The AlarmManager no longer has its own service. This code should be updated to use "SystemAlarmHistorian" as the service name.
  • For the sake of backward compatibility, \AlarmManager\ThisService remains but is now set equal to "SystemAlarmHistorian". Similarly, \AlarmManager\RPCStatus is now a pointer to the SystemAlarmHistorian’s RPCStatus.

Alarm History Conversion:

The alarm and event history of your existing application must be converted to use the new alarms database, introduced with version 11.2. Before starting the process, consider the following:

  • The conversion must be run on an Alarm Manager Server.
    • If your application has not been configured with a server list for primary and backup servers, then you can and should run the process on the current workstation.
    • If your application does have primary and backup servers (and, possibly workstations that are not on the server list) then ensure that you are working on an Alarm Manager server.
    • You do not need to run the process on the current primary server, except that the primary server might have a more up-to-date list of alarms.

    • It is not a good idea to change the server list just before running the conversion as VTScada may take a few moments to transfer all records from the old primary to the new one.

    • To be sure of the server configuration, you may leave the conversion dialog open while you open the Application Properties dialog and review the information in the page, Edit Server Lists.
  • Does your application require more AlarmDatabase tags?

Alarm and event history is now stored using the VTScada Historian. In part, AlarmDatabase tags link alarms to Historian tags. There are two main reasons why you might consider adding more:

  • Security in applications that use Realm Filtering. If your alarms are linked to separate databases, Realm Filtering can be applied to the database tags. Operators will be able to see only alarms in databases that they are permitted to see. This is not a requirement for Realm Filtering, merely a possible convenience. Realm Filtering rules still apply based on each tag's area or tag hierarchy.
  • Efficiency in very large applications. The fewer alarms there are in a database, the faster the Alarm Page will load those alarms. This also results in smaller history sets, which means synchronizing and filtering will be faster.

If either of the above is true, then it is possible (but not necessary) that you may want extra Alarm Database tags. If neither is true, then do not add extra Alarm Database tags.

If adding new Alarm Database tags, note that the only method for linking alarms to databases is to make the alarm tag (or status tag containing an alarm) a child of the Alarm Database tag.

The Alarm DrawList widget is obsolete. Any custom code that used this widget must be replaced with the replacement Alarm List. The Alarm List can be extensively customized through code.

Obsolete Alarm Manager Variables

The following publicly-accessible variables within the Alarm Manager became obsolete as of VTScada version 11.2

General

DBSysVal

The current alarm database. This can be used to obtain information from the database using DBListGet and DBListSize.

CurrentServer

A text name indicating the workstation acting as the Alarm Manager server.
RPCStatus

The current RPC connection status. A value returned by the RPC Manager's Register subroutine.

Remote

Set to true when the alarm source is from a remote workstation. This workstation is not the Server.

BitmapDatabase

The object pointer to the Bitmap Database. This is where preloaded images are stored. (For more details, see the "Bitmap" keyword description above.)

ListChange

Value changes or can be changed to indicate a change in the database. It should be set to any valid value that is different from the current value.

AckAll

When set to a non-zero value, all unacknowledged alarms are acknowledged. AckAll is reset to zero after this takes place.

AckFilter

If set to a valid field filter, all alarms meeting the filter condition will be acknowledged. AckFilter is reset to invalid after this takes place.

Alarm Sounds

Silence | When true, alarm sound is turned off for the alarm generating a sound.
SoundPriority | The priority of the alarm generating a sound.
SoundAlarm | The object value of the alarm generating a sound.
Cycles | The number of cycles for which to play tones (< 0 means continuous).

Record Configuration

FieldCount | The number of fields in the alarm.
FieldNames | The names of the fields.
FieldSizes | The field sizes as defined for the Alarm Manager's database.

Filter Dialog Configuration

FilterCount | The number of filters in the filter dialog
FilterName | The text names for the filters
FilterIndex | The field indices for the filters
Closed VTScada 11.1
  • For custom drivers, note that CoalesceRPC is obsolete and has been removed. DriverRPCOptimization should be used instead.
  • If you are using LogNTEvent in custom code, and have been using "VTS" as the third parameter, you should revise this to use "VTScada" instead.
  • If your application has an OEM layer that is marked, "Do not start", the upgrade process will hang. To avoid this problem, do the following:
    • Temporarily allow the OEM layer to be started, then start your application. This enables both the application and the OEM layer to be upgraded.

      After the upgrade you may restore the Do not start property of the OEM layer.

Alternatively, you could skip the upgrade of the OEM layer by manually marking the OEM layer as having been upgraded. Do this by adding the property, "MenuItemsAutoGenerated = 1" to the Application section of Settings.Dynamic. Note that one consequence of not upgrading the OEM layer is that custom images and widgets in that layer will not appear in the palette unless added manually at a later time.

  • The ModifyBitmap function now uses a second bit in the Antialias parameter. Bit 1 controls whether feathering should be applied to stretched images that are also anti-aliased (bit 0 set to TRUE). You may need to set this parameter value to "3" when using ModifyBitmap to keep certain images from bleeding outside their bounding boxes.
  • Improvements to the code underlying the Alarm Notification System have the following repercussions:
    • If your VTScada network includes workstations running versions prior to 11.1 and workstations running version 11.1 or later, then changes to the active roster will not be synchronized across that version divide.
    • If there is no Default area roster, alarms that do not have matching rosters will no longer call out using a randomly selected roster.
    • Support for the area, "GeneralAlarm", has been removed.
  • Operator notes are transferred automatically to the new Operator Notes tag.
  • If using the ODBC interface to perform SQL queries on VTScada data, note that new table structures with UTC timestamps are now available. Legacy tables still exist but are hidden by default using the property, SQLQueryHideLegacyTables.
  • Custom modules for exporting tag data now require the parameter, DataMode, to be added after the TimePerPoint parameter.
  • Calculation tags now have a built-in link to Historian tags. If your legacy system used Logger tags to record the value of Calculation tags, those loggers will still be present, even though the Calculation's configuration panel no longer shows them. Do not attach an Historian to a Calculation tag that is already being logged by a Logger tag.
  • New calculation tags will have logging enabled by default. Existing calculation tags that were not previously logged will continue to not be logged until you decide to attach an Historian.
Closed VTScada 11
  • If you are running Microsoft Vista, and no text appears in the VAM, ensure that you have installed the platform update. See: https://msdn.microsoft.com/en-us/library/windows/desktop/ee663867(v=vs.85).aspx
  • Windows XP™ is no longer supported. Version 11 requires features that are available only in more modern operating systems.
  • The VTScada layer has been fully merged into the standard layer.

    The legacy VTScada layer still exists as a hidden layer, and will be used by legacy VTScada-based applications that are being updated to release 11. One widget (Duplexes) and one font (Notes) have not been merged into the standard layer, but can be found in the legacy layer if required.
  • If you have an OEM layer, and if that layer has custom widgets (formerly called "drawing methods"), then you must run the OEM layer once in version 11 before running applications that use it. This will happen automatically, even if the OEM layer is flagged as "never run."

    This is required to allow VTScada 11 to create menu item tags for the widgets, thus making them available within the palette.

    The OEM layer should not be left running. When started automatically, it will also be stopped automatically.

  • The Call-Out List Page is no longer included. Any page, of your own creation, may be used in its place. Legacy applications that have the Call-Out List page will continue to have that page when imported into VTScada 11.
  • Many legacy images have been dropped from the palette in favor of modern images. The original image files are still included for the sake of backward compatibility.
  • The Mobile Browser interface has several improvements, including the ability to show page graphics. With this new functionality, the mobile client is now licensed as being equivalent to a Internet Client (VIC) connection.

    Customers who need to limit page graphics to conserve bandwidth or server CPU may set the application property, MobileBrowserDisablePageGraphics.

    Existing customers who wish to continue using the older, limited mobile interface and its matching license calculation should contact Trihedral's Technical Support for relevant information.
  • The Thin Client Monitor log is now stored in the file VICMonitorLog.txt, located in the installation folder instead of Log.txt located in the BrowserMon folder.
  • Hand-coded, custom widgets may not look or work correctly until they have been opened in the Idea Studio.

    Click the widget's Set Parameters button, within its Menu Item tag's configuration folder, then click OK.

    The recommended method for defaulting the parameters of a custom-coded widget is to add default values to the parameters in the widget's .SRC code. For example:
(

   MyParm = 100;

   AnotherParm = "Default Text";

)

Alternatively, a GetParmDefaults subroutine could be added to the widget, which will return an array of parameter defaults. An example follows:

<

{======================= CommandButton\GetParmDefaults =======================}

{ Called to determine the default initial parameters for this widget. }

{ Note - this module gets launched with Code as its parent object.            }

{=============================================================================}

GetParmDefaults

[

  PROTECTED ParmDefaults      { Array of parameter defaults to return         };

]

Main [

  If 1;

  [

    { Get the parameter defaults that are used for existing (underspecified) widgets that lack some parameters. }

    ParmDefaults = ListVars(ParentModule(Self()), "*", 0, 0xFFFF, 0b100 {parms}, 0, FALSE, 2 {defaults},   FALSE);

    { Fill in parameter values to be used with new widgets if they differ from the defaults for existing widgets. }

    ParmDefaults[#UseLegacyButtonStyle] = FALSE;

    Return(ParmDefaults);

  ]

]

{ End of CommandButton\GetParmDefaults }

>
  • Pipes are no longer drawn as a separate function (GUIPipe). A variant of the Line (GUIPolygon) command is used instead. Pipes in legacy applications will be converted automatically when either their color or their width is changed. Legacy pipes are not converted upon import, or when moved or re-aligned.
  • The lexicon file, Lexicon.vlx, will not be copied from your older installation during the upgrade process. If you are installing to a new folder, and you have made changes to your lexicon that you want to keep, you must copy the file Lexicon.vlx from the old installation to the new.
  • Four font files will be installed with VTScada, for use by widgets and built-in text styles. Review labels and titles in your application pages for scaling and alignment issues after upgrading to version 11.

    The new fonts are:
    • Open-Sans
    • Sansation
    • Crystal
    • Register
  • The Gradient Color Change is deprecated. This was used to make pipes change color according to pump or valve state, but GUIPipes are no longer created.

    To replace this feature, link the color property of the pipe (or any other object) to an expression that monitors the value of the tag that was monitored by the gradient color change. For example, given a digital status tag, "Motor1_Status" and a color that should be green when on, red when off, the expression would be: [<Motor1_Status>] ? "<FF00FF00>" : "<FFFF0000>"
  • The \Editing flag is no longer used.

    The flag has been replaced by ParentWindow(Self)\Editing. All scripts that used the former version must be updated.
  • Because the toolbox has been replaced by ribbons, custom toolbox buttons are no longer available.
  • The F11 / F12 key now opens the FindPage dialog in all applications.
  • Custom driver code that used the group name, "VTScadaDriver" must now use the group name "LiftstationDrivers".
  • Changes to default property values:
    • AnswerCalls - Now defaults to TRUE.
    • AlarmLogFreq - Now defaults to monthly.
    • OperatorNotesSecurity - Defaults to none.
    • SiteRetries - Defaults to 3.
    • ModemManagerLogSize - Defaults to 1000.
    • AlarmEventDesc labels - Default labels are those used by VTScada rather than VTScada prior to version 11.
  • The following properties are obsolete:
    • AlarmEventDescX
    • AlarmRevUnack
    • AlarmStateDesc0 through Alarm StateDesc5
    • AlmColumn1 through AlmColumn7
    • AlmDBArea
    • AlmDBHPUnits
    • AlmDBHPValue
    • AlmDBMessage
    • AlmDBPointName
    • AlmDBPriority
    • AlmDBTimeStamp
    • AlmDBStatus
    • AlmDBType
    • AlmHdg1 through AlmHdg7
    • AlmPgLineStyle
    • AlmTagsOnly
    • ClientAlarmSoundOn
    • Cycles
    • DataFlowModuleName
    • HTTPWAPport
    • ReportXPos
    • ReportYPos
    • ReportXSize
    • ReportYSize
    • TrendDuration
Closed VTS 10.2
  • PEditField() is no longer supported for tag Name parameter editing and PEditName() should be used instead. Custom tag configuration dialogs created prior to this version should be updated accordingly. If not, the OK and the Apply buttons will be disabled.
  • The ability to rename tags has the following side-effect: The character "]" is no longer legal in a tag name. Existing tags that used this character will display using their immutable name rather than the short name. You can mitigate this by changing TagNameDelimiter in Setup.INI to use an alternative character. ">" is recommended. Short names will then have the form [ShortName> rather than [ShortName]
  • GetSystemColor() and option 10 of VStatus() now return an RGB color string instead of a palette number. Custom code that uses this value as a number will need to be updated to use text instead. Code that simply passes the value to other VTS functions will continue to work.
  • The following functions have been removed. Code using them will still compile, but the functions will do nothing.
    • AnimateState
    • CollapseTree
    • DragState
    • HighlightedModule
    • HighlightState
    • HighlightTree
    • LastSelectedModule
    • LastSelectedState
    • ModuleCollapsed
    • Moduletree
    • ModuleTreeSize
    • MoveSelState
    • MoveSibling
    • MoveState
    • Palette
    • PickModule
    • PickState
    • ReadNum
    • ReadText
    • SelectStates
    • SetStateColor
    • ShadowTree
    • StateDiagram
    • StateHighlighted
Closed VTS 10.1
  • All users will be required to change their password upon first signing in. This is done to ensure that their credentials are stored using the newer encryption algorithm. Note that passwords are now case-sensitive.
  • Tag names may not conflict with VTS function names. When starting an older application in version 10.1, any tags with conflicting names will fail to start and will be listed in an error message. If this occurs, your recourse depends on which version of VTS you are upgrading from. Please contact Trihedral technical support.
  • Now that VTS includes Constructor and Destructor modules, any pre-existing modules that use those names should be re-named. Also, any code that uses the DBTrace Constructor API should be updated.
  • Alternate identification has been decoupled from user-passwords and is now a distinct property that may be assigned to designated users.
  • Tags in an OEM layer will now start in the dependent layer. You may draw and otherwise use the tags in the dependent layer, and may override tag parameters. If you would prefer that new applications based on your OEM layer have independent copies of tags from that layer, continue to use a Template.ChangeSet.
  • Tags that you or a developer have created using VTS script code must contain a refresh module and that module must be called.
  • In custom-coded tags, the statement, Root = Self() must occur before the call to Refresh().
  • Also in custom-coded tags, the expression "Scope(VTSDB, TagName) will still work if the custom tags are used in the same way that they had been. But, if you wish to use those tags in parent-child tag structures, include parameters that refer to tags that are not root-level tags, and wish to copy your tag to a new scope, then you must change the expression to read "Scope(Root, TagName)".
  • Page links, listed in the bottom navigation bar, will not be preserved when your application is upgraded to release 10.1
  • With the release of version 10.1.06, the IVONA™ Salli voice (American English) replaces the IVONA Amy voice (British English). Customers who prefer the Amy voice may contact technical support for the required files.
  • Because tag names now reflect the tag's position in a parent-child structure, full alarm names may become long. This is reflected in the change of AlarmKeySize to 256. The template alarm message length has been increased from 80 to 128 characters. Changes to the Alarm Manager are as follows. Note that, should you choose to set your own values for any of these applications properties, you should do so only after the application has been updated to version 10.1.

    You will need to edit your Settings.Startup file for existing applications. For the change to take effect, the alarm manager (or, more simply, the entire application) must be re-started after you have made the edits.
  • AlarmKeySize setting has been increased from 32 (and 64) to 256 in the VTS/VTScada templates.
  • The template alarm message length has been increased from 80 to 128 characters.
  • DBSystem can now re-size existing DB and LOG files when the Max Key or Text field sizes are changed.
  • The AlarmManager can synchronize between servers with different values for AlarmKeySize or message size or both. In earlier versions of VTScada, these applications would fail to synchronize properly.
  • Existing applications can modify the AlarmKeySize or alarm message size or both with only a restart required. This should always work when increasing the size(s), but might fail if attempting to decrease them should existing fields fail to fit in the decreased space.
  • Code that called HideWAM must be changed to call the newer HideVAM instead. HideWAM is maintained for backward compatibility but is now used only at startup, to set the initial value of HideVAM.
  • The use of the variable UserSession in a module to affect GetUserSession's behavior is no longer supported
Closed VTS 10
  • No more Config.INI, SecurityManager.INI, workstation.INI, etc.

Configuration variables are now stored in Settings.Startup (loaded only on application start) and Settings.Dynamic (able to be reloaded while an application is running). Also note that the term "configuration variables" has been dropped in favor of "application properties".

  • User files are separate from working files.

The files located in an application's root directory and in the Pages directory are "user files". Developers may edit these files, but need to be aware that they must explicitly tell VTS to import the changed files before their edits become part of the working set.

Working files are under version control and are stored in a hidden system folder within the application directory. Any attempt to directly edit a working file will damage your application.

  • Points.MDB is obsolete

Developers can export their tags to a Microsoft Access™ (or other) database, or to Excel™ for offline editing, and may import a tag database into an application. Within a working application, tag instances are now stored in a proprietary database format.

  • In a networked application, all workstations must be running VTS 10. Remote configuration will not function across different versions.
  • The LogManager service is obsolete

Log storage is now handled by Historian tags. These powerful tags allow you to optimize data logging for load balancing and automatic fail-over, even between multiple database storage systems such as Oracle™ and MsSQL Server™.

By default, Trihedral's own proprietary database format will be used for logging. Older applications upgraded to version 10 will automatically be assigned to a default Historian tag.

  • Access to legacy tag history.

Data logging in VTS 10 is far more flexible and powerful than ever before. Because of fundamental changes to the way that logged data is stored, you must configure the application property, LegacyHistoryPath, to point to data logged while the application was running on an earlier version of VTScada.

  • Application template directories are obsolete.

Template information is now stored within specialized ChangeSet files.

  • Changes to the RateOfChange tag.

If you are using these tags, note that they must now reference a Source Tag that is configured for logging.

  • The application property OEMRestrict is no longer supported on the VAM.

For networked applications, note that the RPCManager-Inhibits configuration section is now obsolete.

  • If using the configuration file, RPCService.INI, this file will automatically be converted to the version 10 format, but you may need to re-enter your server lists.
  • There is a Font compatibility issue when the VTS Internet Client (VIC) uses an older version of the Windows™ operating system than the one on the server.

When running VTS 10 as a VTS Internet Server on Windows Vista/7/Server2008, any VICs that are run on Windows XP/Server2003 or older will have many texts clipped. To avoid this, the server must be told to use old fonts by setting UseXPCompatibleFont to 1 in the System section of Setup.INI. If the server is XP/Server2003, the setting is not necessary.

  • Configuration variables from Setup.INI are now read as the lowest priority settings for all applications. They will always be overridden by a matching property in the application's Settings.Startup or Settings.Dynamic.
  • The following script applications are obsolete and are no longer included with VTS:

ResetRemoteClients DBConvert ODBCBrowse

VTS Programmers should note the following changes, which may affect their custom code.

  • Config.INI sections have moved to Settings.Startup & Settings.Dynamic.

All application-level configuration files (those with names ending in .INI) have been replaced with the two files, Settings.Startup and Settings.Dynamic. Workstation-specific configuration files have been replaced by Workstation.Startup and Workstation.Dynamic in the WorkstationSettings folder of the application directory. See: Application Properties.

  • StartTag has a new flag which, if set, will update the tag database. By default, this flag is not set. See: StartTag.
  • If you have a custom tag type, ensure that the tag parameter metadata is in place. (This was not required in older versions and may not be present in legacy applications.) See: Tag Configuration Parameters.
  • The SecurityManager is now in the VAM layer and overrides to it will not take effect for VAM access to security.
  • There is no longer a SecurityManager RPC service. All security accounts and settings are synchronized by the Configuration service.
  • AppRoot.SRC replaces AppMod.SRC & AppMod.Web. The AppMod file in an application that is upgraded to release 10 will not be used, but will be retained for use if the application is converted back to an older version.
  • In 9.1 and earlier, if you included any code for another module in the same source file as the Appmod.SRC, it would be used. Group modules were typically done this way. As of 10.0, the code for other modules must exist in a separate file other than AppRoot.SRC or they will be ignored without warning.
  • PlugIns that use default string values (as shown in the following example) will no longer work.
[ (POINTS)

  MyTag = "VarForGraphicsInMyTag";

]
  • EditLockoutManager functions such as "MarkTagForEdit" are now obsolete. The distributed version control system replaces the Edit Lockout Manager. Any custom code that calls the EditLockoutManager will result in an error dialog.
  • Libraries no longer combine code across layers and now only use the library at the highest defined layer. Widgets that link into libraries are not affected.
  • Web services have a different interface on the script code side. Please see XMLProcessor, and other XML functions for details.
  • ExternalValue is no longer supported in input tags.
  • OEM code references to Logger, LogManager or LogObjVar need to be changed to use the Historian interface. Of special note is any code that waits for LogManager\Started. See: Historian Manager.
  • Modules that are defined outside the scope of the application directory will need to be moved to within the application directory.
  • Security Manager plug-ins only work when the application is running.
  • Plugins that have references to variables in Code must be preceded by Code.
  • Template directories must be converted manually to template ChangeSets. See OEM Template ChangeSet for instructions.
  • DSNName no longer exists as a variable in Code
  • The Security Manager no longer supports OEMEncryptKey and SerEncryptOEM. These have been replaced by integrated higher level encryption.
  • The Notebook tag’s AddNote module interface has changed to support the new Historian.
  • SelectObject and PSelectObject have new parameters, adding new options for your code.
  • SQL module calls no longer allow writing to the default tag database.
  • EditIni and EditIniCheckBox widgets always update the RAM copy and ignore the "Update RAM Copy" parameter.
  • RPCManager\Register no longer supports specifying a file name to read the server list from.
  • RPCService.INI file contents have been transferred to Servers.RPC.
  • ToolExt.INI has been changed to ToolExt.CSV
  • WriteIni will first acquire the working copy lock and update the file asynchronously. Use Layer\RecordProperty instead.
  • ReadIni does not acquire the working copy lock. It is better to use ReadPropertiesFile instead.
  • LogFileName PLUGIN no longer supported.
  • LogAlarm PLUGIN no longer supported.
  • Files with the extensions of .DAT and .LOG that are accessed from custom code need to be moved to the DataPath directory and code modified to match.
  • The default window title will now be the application name rather than "Display".
  • Points.MDB is no longer the primary tag database.
  • The RPC manager now uses the VTS IANA registered port, 5780 instead of 1160.
  • The application property LegacyHistoryPath is required to access older data from upgraded legacy applications.
  • The RPCManager-Inhibits configuration file section is no more.
  • VTS Internet Servers on Vista with clients running XP will need to set the Tahoma font in their Setup.INI files.
  • OEMRestrict is no longer supported on the VAM.
  • Tag names that consist of only the period and space characters will no longer be considered valid.
  • RPCService.INI files will not be converted to the version 10 format automatically. Server lists may need to be re-entered.
  • Setup.INI variables are now read as the lowest priority settings for all applications.
  • The script applications, ResetRemoteClients, DBConvert and ODBCBrowse no longer exist.
  • After updating a legacy application to release 10 and compiling, a full re-compile under the previous version will be required to roll back to that version.
  • Unless AutomaticDeploy is added to the Layer section of Config.INI prior to conversion, all local changes will be deployed automatically when the application is converted to version 10.
  • Existing applications that use VTS as a DDE server and rely on the application window being called "Display" will need one of the following:

    a) Declare DisplayManagerTitle = Display in Settings.Dynamic

    b) Update the links to refer to the application name.
  • VTScada's ODBC interface was modified to use ODBC3.0 drivers, which may cause changes in returned data types and SQLState return codes.
  • Changes to the ODBCStatus function to take the ODBC handle to query for status. This is important to note as otherwise, you will just get the status of the last operation to complete which, given the concurrent nature, might not be the operation you have just executed.
  • The following files are obsolete since the release of VTS version 10.
    • AlarmManager.INI -> now part of Settings.Dynamic
    • Config.DB
    • Config.INI -> replaced by Settings.Startup and Settings.Dynamic
    • GDI.WIF -> now part of Settings.Dynamic
    • Menu.TXT & Menu2.TXT -> replaced by PageMenu.TXT
    • Points.MDB -> replaced by a proprietary data storage system
    • SCT.MDB - obsolete
    • SecurityManager.INI -> now part of Settings.Dynamic
    • Sync.WIF -> obsolete
    • Workstation.INI -> replaced by Workstation.Dynamic
    • ReportTags.GRP -> replaced by a proprietary data storage system.


Installation & Activation

VTScada is distributed as a single installation file that includes all development tools, alarm management, the built-in historian, etc. Your license key, a 25-character code, controls which features are enabled. Following installation, click the License Management icon in the VTScada Application Manager to discover what is enabled under your license.

Topics covered in this section:

  • Licensing - Features enabled by your license key.
  • Requirements - Hardware requirements for small, medium or large installations, and for various VTScada features.
  • Installation - Decisions to make as part of the installation process.
  • About - Where to find the "About" dialog, which will tell you about your VTScada license. See also, App. Config -> Information.
  • Moving to the Current Version - Provides instructions for updating to the current version of VTScada and draws your attention to changes that may affect your system. (New features are listed in What's New...)

An Installation ID is new with version 12.1. Every VTScada license is matched to the machine where it is activated and cannot be activated on a second workstation. Refer to Activation & Deactivation, within this section.

The License Management dialog

VTScada logo images are protected. VTScada will not start if you remove or modify those files. Reinstall VTScada to restore the original images if you disregard this warning.

Disable Windows Controls (Kiosk Installations)

VTScada cannot disable access to Windows controls (file menu, close, minimize...) or keyboard commands (Ctrl-Esc, Alt-Tab, and Ctrl-Alt-Delete). This could be accomplished with a Windows logon script. Refer to:
https://docs.microsoft.com/en-us/windows/configuration/kiosk-single-app


Activation & Deactivation

A simple, one-time process for online or offline installations.

Starting in version 11.2.24, new VTScada and VTScadaLIGHT™ installations, as well as updates to newer versions, require a one-time software activation for the workstation where you are installing. This helps us ensure the fair use of our licenses and provides useful statistics that we use to improve the product. Every VTScada license is matched to the machine where it is activated and cannot be activated on a second workstation. To move your license to another workstation, you must deactivate it on the first before activating it elsewhere. In the event that this is impossible (for example, hardware failure) contact Trihedral Engineering.

After you activate VTScada on a specific computer, you do not need to do it again when you upgrade to a newer version (unless you reinstall VTScada after reformatting your hard drive).

Automatic Activation

If the workstation is connected to the Internet, the Activating dialog opens automatically during installation. If you choose not to activate at that time (for example, you are moving your application from one server to another and want to ensure that it is running on the new machine before deactivating the old), you can reopen the dialog using the License Management dialog. Activation requires no user action once started.

To activate VTScada on a device without an internet connection, click Manual Activation.

Offline / Manual Activation

To activate your device offline you need a 16-character activation code. There are three ways to get this code:

  • Use a smart device to scan the QR code.
  • Copy the URL to a device with an internet connection. (Appears as a URL in a full browser)
  • Call Trihedral on the telephone.

The QR code in the example will not generate a code. It will redirect your device to this web page. Try it yourself!

The following dialog opens automatically to help you manage offline activations

Activation via QR Code

  1. Use a smart device (such as a cell phone or tablet) that has a working camera and an internet connection.
  2. Open the camera and use it to view the QR code.
  3. On your camera screen, a hyperlink will appear adjacent to the QR code. Tap it.
  4. On your smart device, you will be redirected to a web page with your 16-character activation code.
  5. Enter the 16-character activation code into the blank spaces on your offline device. If you have entered it correctly, the activate button will become enabled.
  6. Click the Activate button.

Activation via URL

  1. Under the QR code you will find either a URL or a copy button depending on the kind of device you are viewing it on.
    1. If you see the URL, copy it (possibly manually) into the browser of your internet connected device.
    2. If you see the copy button, clicking it will copy the URL to clipboard. It must still be copied to your internet connected device.
  2. On your internet-connected device, follow the URL in your browser.
    The activation process will proceed and a code will be displayed.
  3. Enter the 16-character activation code into the blank spaces on your offline device. If you have entered it correctly, the activate button will become enabled.
  4. Click the Activate button.

Activation via Phone

  1. Call Trihedral using the number provided in the Activating dialog.
  2. Provide the information shown in the Activating dialog.
  3. Enter the activation code into the space provided in the Activating dialog.
    If entered correctly, the Activate button below the activation code will enable.
  4. Click the Activate button to complete the activation process.

If the license server rejects the request, you will be provided with information to allow you to contact Trihedral to resolve the issue. Record this information before contacting Trihedral, as you will need to provide it when asked.

For paid licenses, there is a 30-day grace period following the first installation of VTScada on your computer. During the grace period you can choose to postpone activation of VTScada. VTScadaLIGHT installations do not have a grace period and must be activated before use.

If you upgrade from VTScada 12.0 to 12.1 or later, you will be required to activate your system again. If you subsequently roll back to version 12.0, you will not need to reactivate your 12.0 license.

Deactivating a License

If moving a license from one machine to another, do not deactivate the license on the old machine before ensuring that you have installed VTScada and are able to run your application on the new machine. You have 30 days grace before activating VTScada on the new machine. VTScada will not run after being deactivated on any machine.

If the future server previously had a copy of VTScada installed, installing the current version does not qualify as a new installation and the grace period does not apply. In this case, deactivate the license on the current server, but leave it running. So long as VTScada is not shut down, it will continue to work for 30 days after deactivation.

A license must be deactivated on one computer before it can be activated on another. To help avoid difficulties, the uninstall program will not proceed until you deactivate the copy of VTScada you are attempting to uninstall.

Start the deactivation process using the button provided in the License Management dialog. Deactivation can be done using the Internet, a URL, or by phone, using a process similar to activation. Deactivation via the Internet or by URL is allowed only a set number of times. Beyond that number, you must deactivate via phone.

You must complete the entire process as described in the Deactivation dialog and according to the method you have chosen, before you can activate the license on a new computer.

A license may be deactivated six (6) times. Contact Trihedral Engineering during business hours if further deactivations are required.

For your protection, the deactivation process resembles the activation process. If connected to the Internet, you can deactivate a license with a click. If not, you can generate a file that contains information unique to your installation or phone Trihedral during working hours with that information in order to obtain a deactivation code that is unique to that particular installation. No one can deactivate your license remotely.

Click Manual Deactivation to see the following dialog:

Usage Information Collection

Like many popular software products, Trihedral periodically collects basic system usage information. This does not include historical data, user account names, or security credentials. Paid VTScada licenses allow you to opt out of this during installation, however, we invite you to help us to improve the experience for operators and developers by sharing these statistics with us. This service is not optional for free VTScadaLIGHT licenses as per the VTScada license agreement.


About...

General information about your installation of VTScada can be reviewed by opening the About box, which can be done from the VTScada Application Manager:

Open the About dialog

From the resulting dialog, you can learn the number of tags (that count towards your license limit*), the memory in use and the total number of thin clients allowed in the server list, of which this machine is a part. (The thin client limit is the sum of the licensed number on each of the workstations that are part of a server list.)

To check whether a license is Runtime or Development / Configuration, refer to the page within App. Config. -> Information

(*) Only I/O tags count against your license usage.

The About dialog


App. Config. -> Information

To review which features are enabled by your license, extra information about your copy of VTScada and more, refer to the Information page of the Application Configuration dialog. (Open the Application Configuration dialog)

Notable details within this display include:

VTScada Run Mode

Check whether this installation is licensed as Runtime or Development / Configuration.

OEM

Shows whether this application runs directly on the VTScada library layer (standard application) or another application.

Windows

Shows which version of Windows is installed on this workstation, including the build number. This and the following section may be helpful if attempting to diagnose why an application is running more slowly than expected.

Hardware

Workstation name, number of CPUs, physical memory installed, etc.


Branding Files

VTScada logo images are protected. VTScada may not start if these files have been removed or modified.

In the event that you would like to create custom-branding for your VTScada installation, you must purchase a license that allows this. Your logo files must be sent to Trihedral Engineering to obtain verification files that will be unique for your custom branding images. Trihedral reserves the right to deny images. Installation instructions will be provided with your approved files.

Custom branding is not available for VTScadaLight installations.


Requirements and Installation

It is possible to install VTScada silently as part of a larger system install. Refer to Command Line Installation and Arguments, later in this topic.

Hardware recommendations when running on Windows operating systems:

We've seen 1000-tag VTScada applications running perfectly on pocket-sized PCs. As a general rule, bigger, newer, and more powerful is better, especially as your application grows in size.

( This is a guide. Actual requirements will depend on your application architecture.)

Small Systems

(Less than 1000 I/O)

Medium Systems

( 1000 to 25,000 I/O)

Large Systems

( Over 25,000 I/O)

Enterprise Systems

( Over 100,000 I/O)

  • 32- or 64-bit Windows OS
  • 2+ GHz Dual-Core x86 or x86-64 processor
  • 500 GB hard drive
  • 8 GB RAM
  • 100 Mb Ethernet or higher
  • 64-bit Windows OS
  • 3+ GHz Dual-Core x86 or x86-64 processor
  • Solid State Drive.
  • 1 TB SSD hard drive
  • 16 GB RAM
  • 1 Gb Ethernet
  • 64-bit Windows OS
  • 4 GHz Quad Core x86-64 processor
  • ≥2 TB SSD hard drive
  • 32 GB RAM
  • 1 Gb Ethernet
  • 64-bit Windows OS
  • 4+ GHz Quad Core x86-64 processor
  • ≥4TB SSD hard drive
  • 48 GB RAM
  • 1 Gb Ethernet

Notes:

  • VTScada versions 12.0 and newer are not supported on Windows Server 2008, Windows Vista, or other earlier versions.
  • Version 12.1 is supported on Windows 11. Earlier versions of VTScada have not been tested on Windows 11 and are not supported.
  • VTScada runs on Windows® 10 IoT Enterprise not IoT Core. Microsoft has ended support for XP®, Vista®, Windows 7®, Windows 8®, Server 2008®, and Server 2008 R2®.
  • Clock speeds reference the Max Turbo Frequency, not the base clock rate.

Do not log data to a network share location.
Keeping a remote copy of data via a backup Historian is a very good idea.
For initial storage, sending your data anywhere other than the current Historian server is a very bad idea, leaving your data at risk of a host of problems that can occur with network connections. Refer to Historian and Logger Configuration

Memory

  • Requirements vary according to the number of tags in your system and several other factors. In general, memory equal to at least twice the number reported in the VAM as being in use under normal operations should be available.
  • For historical data logging, 1K data changes/sec requires 1,500 GB/year.

Alarm Notifications

  • Text-to-speech phone alerts require a voice modem, a VoIP-phone system, or Twilio®.
  • Choosing modems: VTScada.com/modems (url forwards to the VTScada forum.)
  • Connection to an email server required for email alarm notifications.
  • Cell modem, email account, or Twilio® (web-based service) for text notifications.
  • Sound card and speakers required for local alarm annunciation.

Virtualized Servers

  • VTScada is widely used on virtual Servers.
  • Each virtual server instance needs a VTScada license.
  • Do not clone virtual servers with VTScada installed.
  • Ensure host PCs have enough capacity for all VMs, e.g., CPU, RAM, drive space, ports, Ethernet bandwidth.
  • Twilio® and VoIP offer simpler alternatives to configuring voice and/or cell modems in virtual server environments.

System Performance

  • Check your hardware's power settings and switch to high or ultimate performance mode where applicable for optimum performance.
  • Scale to large systems by load sharing services across servers or using Master & Subordinate Apps.
  • VTScada will use up to 4 CPU cores so clock speed should be prioritized. Additional cores can help keep CPU power usage below the TDP to allow busy cores to operate at their turbo speed instead of their base speed.
  • Keep VTScada & History data on a separate drive from the operating system, if supported by your system.

    This is not a suggestion to use a network drive for data storage, which carries its own risks. (Refer to: Optimize Your Configuration for a list of the reasons behind this recommendation.)
  • VTScada's architecture makes RAID drives unnecessary in redundant systems. For performance reasons, they are not ideal (and possibly harmful) for any SCADA historian. If you must use RAID, use SSDs for better performance.

Other Recommendations

  • If you need RS-232 ports to communicate with legacy devices, we recommend Ethernet to serial converters.
  • NetDDE is not available (it was removed in Windows XP Service Pack II).
  • VTScada uses IANA registered TCP/IP port 5780. Set up firewalls to route RPC traffic accordingly. Do not expose port 5780 to the Internet.

  • Do not use Network Address Translation routers (NAT) with multi-server VTScada installations. NAT routers are incompatible with multi-server VTScada installations.

Thin Client Recommendations

Thin Clients require a connection to a running VTScada application, licensed to allow Thin Clients.

HTML5-Compliant Browsers

Access the VTScada Anywhere Client from mobile devices, PCs, and Macs by entering a web address in a browser.

Windows Desktop/Laptop Systems

Access the VTScada Internet Client from networked Windows PCs using the provided stand-alone ActiveX program.

  • Safari® (MacOS, iOS) - Recommended
  • Edge (Windows®) - Recommended
  • Chrome® (Windows®, iOS®, Android®) - Recommended
  • Firefox® (Windows®, iOS®, Android®)
  • Launch by entering a web address into Internet Explorer on Windows 8 or newer. or...
  • Launch from a desktop using a small program downloaded once from your VTScada server via a browser.

The License Key:

If not running VTScadaLIGHT, the installation program requires a 25-character key that will control your tag count and which options of VTScada will be available in the installation. Activation is required within 30 days, either over the Internet or by calling Trihedral for a code. See notes in Installation & Activation

Before Installing

  • You must have administrative privileges on your computer to successfully run the installation program.
  • After installation, DO NOT run VTScada as an administrator.
    Running any program as administrator is a security risk, but this is not the primary reason for this recommendation. If running as Admin, files created by VTScada may not be available to regular users, which can lead to problems later on, especially if you later switch to running under another account.
  • When installing VTScada, check the power plan settings on your computer. Balanced or energy conservation modes may cause your application performance to suffer. Switch to High or Ultimate Performance options.
  • When upgrading, it's standard practice to install the new version over the old version. Your application files will not be affected.

Installation Considerations

  • You may install VTScada into any directory, but C:\VTScada is the default and is recommended. For security, executable files will be installed to your Program Files folder automatically. Attempting to place the entire installation in that folder structure would require you to run VTScada as an administrator in order to maintain access to the files.
  • If the workstation has an Internet connection, choose the option to download maps as required. You can always change this later.
  • You can run VTScada as a Windows service but do not select this option on first installation. Do so only after you create your application using VTScada as a desktop program, then configure it to run automatically upon start up.
  • You can integrate Windows security with VTScada so that operators can sign in using their Windows domain accounts. You must create the application first, configuring the basic security roles, then coordinate efforts with your IT department.

Options and Suggestions During Installation:

  • Registration: Installation key or use VTScadaLIGHT. See notes for Using VTScadaLIGHT.
  • Change the installation folder if required. Some system integrators choose to maintain multiple versions of VTScada by installing each in its own folder.
  • Exclude portions of the program including the documentation and the tools for testing and debugging. Choose this only to save space on servers where no development work will be done.
  • Select either 32-bit or 64-bit architecture. 64-bit is recommended in most cases unless you are installing on older hardware or operating system.
  • Allow reporting of limited usage statistics to Trihedral. Not optional for VTScadaLIGHT licenses. Customers who have purchased an installation key may choose whether to provide statistics to Trihedral.
  • Install VTScada as a Windows Service. Do not choose this option until you have created the application that will run on that server and configured it to run automatically. It is also recommended that you first configure the VTScada Thin Client Server so that you can create thin client connections to your application using the VTScada Internet Client, Mobile Client or Anywhere Client.

  • System administrators can do a silent install of VTScada. Contact Trihedral Technical Support for instructions that will be relevant to your situation.

Adding or Changing License Options:

If you choose to add new features to your license, purchase a new key from Trihedral then run the installation file again, installing to the same location as the original installation. VTScadaLIGHT users who discover a need for more tags can purchase a key and re-install. Nothing needs to be done to update their applications.

Multiple Versions

For developers and System Integrators who have been using VTScada for several years, it is common to have more than one version installed. (Each must be in a separate folder.) Your current license key will work for all older versions that you have installed.

Certain features including OPC, running VTScada as a Windows service, and the ability to double-click a ChangeSet to install it, will look only to the most recently installed version of VTScada, regardless of version number.
If you uninstall any version, then the registry entries for those features are deleted. They will not exist for other versions. You must reinstall a version to get them back.

Installation Folders

Every VTScada installation uses two folders:

  • The installation folder that you specify, usually defaulting to C:\VTScada.

  • A folder under C:\Program Files\Trihedral\VTScada for the binary files (*.exe, *.dll, ...)

The binaries folder for each copy of VTScada that you install will always take the name of the installation folder and cannot be otherwise defined. For a default installation, this will result in the path C:\Program Files\Trihedral\VTScada\VTScada.

If you install one version of VTScada in C:\VTScada and another on a different drive as E:\VTScada, then the binaries folder for both will be C:\Program Files\Trihedral\VTScada\VTScada and the later installation will over-write the executables of the earlier installation.
If installing different versions on different hard drives, ensure that you provide a different installation folder name for each.

Command Line Installation and Arguments

For example, for a silent installation from the command line, run: VTScadaSetup /Q=A

The following command line options are required to enable installing without graphic interface.

Q=

Silent, value should be 'A' for all. Other options don't seem necessary if providing a command line installer as they would still allow some graphic displays.

K=

VTScada key, no spaces or dashes.

DIR=

Installation folder including the drive identifier.

Prior to VTScada 12.1.01, /D= specified the installation folder. This command no longer functions. From VTScada 12.2.04 onward, Use /DIR= instead.

OEMNoTSP=

Value 'Y' prevents installing the voice modem.

OEMComponents=

Only required if trying to install as a service, which requires defining the defaults in addition to the service setting. Defaults to ABCDEFGH

A (Runtime files)

B (Help files)

C (Image files)

D (VIC Support)

E (Tutorial application)

F (Debug tools)

G (Database tools)

H (Sysadmin tools)

K (Install as a service)

L (Don't allow usage reporting)

Course setup...


Touchscreens

On a Windows 10 or 11 machine with a touchscreen that presents itself to Windows as a touchscreen input device (as opposed to using mouse emulation), then clicking on an edit field will cause the Windows Touch Keyboard to appear automatically.

If the machine also has a keyboard plugged-in and you still want the touch keyboard to appear when you touch an edit field on the touchscreen, you may need to enable a Windows setting as described here: https://www.windowscentral.com/auto-display-touch-keyboard-windows-10-desktop-mode.

For some devices, "tablet mode" must be enabled.

Momentary Button

From VTScada 12.1 onward, a Momentary Button (that is configured to show a non-legacy button) will react to touch input. (The Momentary Button does not react to a touchscreen if Show Button is off or if it is configured with an opacity of zero.)

Many touchscreens only support mouse emulation. Those do not have support for the standard Windows Touch Keyboard, in VTScada or any other application. To test, open Notepad and tap its text editing area. If the touch keyboard appears, then you can expect it also to work in VTScada. If not, then it won't work in VTScada either.

Numeric Keypad

C (to clear all input), +/- (to toggle between positive and negative values), backspace for corrections. Press ESC to close the keypad and cancel all entries. Enable nighttime mode to see a dark keypad with light characters.

Numeric-only keypad daytime (default) and nighttime mode with range displayed (optional).

Replace the standard Windows Touch Keyboard with a dedicated numeric-only keypad for numeric-only edit fields. This feature was designed specifically for industrial touchscreen users but it is also available for desktop applications that use a keyboard and mouse.

When enabled, the numeric keypad will display for any edit field that is of the type numeric in pages and configuration menus.

  • Automatically selects current value for overwrite.

  • Option to display valid input ranges directly on the keypad.

  • Option to block out-of-range values with an error message.

  • Optional Nighttime Mode.

  • Optional size configuration.

  • Can be configured as a workstation-specific setting or a Realm specific setting.

  • Pressing the Esc button closes the keypad and reverts the field to its original value.

Enabling the numeric keypad does not disable the keyboard. You maintain the option to use the keyboard while the numeric keypad is being displayed. The numeric keypad does not replace the Windows Touch Keyboard; The Windows Touch Keyboard will appear as it normally does for edit fields that accept text.

Enabling the Numeric Keypad

Numeric keypad can be enabled per workstation through the application configuration or per thin-client using the Realm Display Setup Tag.

Workstation Configuration

Navigate to the Application Configuration > Edit Properties > Advanced Settings. Copy and configure the following settings to enable the numeric keypad, adjust the size or enable nighttime mode: Numeric Keypad Properties

Thin-Client Configuration

Add a Realm Display Setup Tag. Give it a name and description and navigate to the misc tab to find the Numeric Keypad enabling, size and nighttime mode settings:

On thin-client applications, enable numeric keypad, specify a size (optional), enable nighttime mode (optional)

Ranges and Limits

Ranges and limits are not set directly on the numeric keypad. They are inherited from the tag linked to the edit field. If a range or limit has been set in the tag, it will display on the numeric keypad. If the linked tag has the option to limit outputs to within scaled min/max enabled, the operator will not be able to exceed the range using the numeric keypad and a warning will pop up to alert them.

This is an example of a linked tag's range options. The example is an I/O & Calculations tag.

Troubleshooting

Keypad doesn't appear

Confirm the edit field you are editing only accepts numeric values.

Confirm that the user account has the appropriate privileges to edit fields. The numeric keypad will not appear if the user does not have the privilege to edit fields.

For workstation applications, check that UseOnScreenKeypad is enabled. For thin-client applications, check the configuration of the misc tab in your Realm Display Setup Tag.

Keypad appears off screen

Adjust the keypad size (Use the property OnScreenKeypadSize for workstations or the setting in Realm Display Setup Tag > Misc for thin-clients) to better fit your monitor.

If you are using multiple displays, verify your setup following Configure for Multiple Monitors

Keyboard is smaller than specified size

If your monitor is not big enough to display the keypad without obscuring the edit field, the numeric keypad will shrink to fit. Regardless of the specified size. It may be helpful to think of the size setting as the "maximum" size.

Related information:

Use properties for workstation settings and use Realm Display Setup Tag for thin-client settings.

UseOnScreenKeypad

OnScreenKeypadNighttimeMode

OnScreenKeypadSize


VTScada as a Windows® Service

You can install VTScada to run as a Windows® service. After installation, you can stop and then re-start VTScada as either a service or as an interactive program.

User interface items may differ in appearance when rendered within a Windows service. In particular, Windows control buttons will differ in appearance when viewed on a mobile client.
Certain third-party applications may have limited interaction with the service.

Microsoft does not permit Windows services to access SAPI (the built in Windows text-to-speech engine). This means that if you are using the VTScada Alarm Notification System and you configure your application to run as a Windows service, then outgoing alarm calls via voice modem are silent. VOIP and Twilio calls may work, but Microsoft is inconsistent with which versions of Windows will allow services to access SAPI. We cannot guarantee operation of VOIP when running VTScada as a service.

When running VTScada as a Windows service, DO NOT select Excel as an output destination or option from a Report Tag. As noted in the MSDN forums, office applications assume they are being run under an interactive desktop. If Excel attempts to open a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog from a non-interactive service, the result is an invisible dialog that cannot be dismissed, stopping the thread.

Besides the technical problems, you must also consider licensing issues. Microsoft's licensing guidelines prevent Office applications from being used on a server to service client requests, unless those clients themselves have licensed copies of Office. Using server-side Automation to provide Office functionality to unlicensed workstations is not covered by Microsoft's End User License Agreement (EULA).

If you have been running VTScada as an interactive program, it is necessary to install the service objects before you can run the program as a service. You can do this using command line switches, or you may choose to repeat the full installation, selecting the service option.

Use caution if switching VTScada between running as a service and running as an interactive program. Problems will occur if your user account does not have the same permissions as the one under which VTScada runs as a service. If only one account has access to the Data folder or sets elevated permissions on the files it creates, these problems may be severe.

Rather than switch modes, you are advised to configure the VTScada Application Manager script application so that it can be accessed using the VIC or the VTScada Anywhere Client (Access the VAM from a Thin Client).
To do this, your license must allow at least one VTScada Thin Client connection. The VAM can be run from only one Thin Client at a time.

After installation, the service will automatically start when Windows® starts. Note that a delayed start is configured by default. It may be stopped and started through the Windows® Service Control Manager or using the command line, which is the recommended option.

vts.exe /s=start

vts.exe /s=stop

VTScada security permissions are not required to stop the service.

The Windows account used to issue service commands (e.g. starting and stopping the VTScada service) must have administrative privileges (and, if using the command line, the console must be run with administrator privileges).

The account under which VTScada runs when running as a service or interactively must have read / write access to the VTScada installation folder, sub-folders and to any other folders external to the installation folder that might be used for data storage.

If running as a service under a regular user account, then to access Workstation Status Driver values e.g. CPU, the account must be a member of the local "Performance Monitor Users" group.

The application that will be available through your VTScada service must exist on the server, and be configured to auto-start. Because VTScada cannot run as a service and as an interactive program at the same time on the same workstation, the following procedure is suggested.

  1. Install VTScada and run as an interactive program.
  2. Create or install the application.
  3. Configure the VTScada Thin Client Server, to allow VTScada Thin Client connections.
  4. Configure the application to auto-start.
  5. Configure the VAM as described in Access the VAM from a Thin Client.
  6. Stop the interactive VTScada session.
  7. Run VTScada as a service, re-installing to add the service components if this was not done earlier.
    The command-line syntax is recommended.
  8. Start the VTScada service.

When VTScada is running as a service, all operational access to your application is through other workstations where VTScada is installed and running as an interactive program, or through VTScada Thin Client connections. Ensure that your VTScada license permits the maximum number of simultaneous Thin Client connections that you expect. System messages that would otherwise have been shown on the interactive console are directed to a VIC connection. Error messages are directed to the Windows® event log.

You can use a VIC connection to perform tag configuration.

To perform development work, do any of:

  • Install VTScada on a second server and configure your server list. Use Get From Server to install the application on the second workstation. Configuration changes will be deployed from one to the other.
  • Connect Using the VTSX Program (or if available, Internet Explorer). This provides access to the Tag Browser, Application Configuration and (if licensed) the Idea Studio.
  • Connect Using the Anywhere Client, which provides access to both the Tag Browser and the Application Configuration dialog but not the Idea Studio.
  • ChangeSets, created on a non-networked workstation, can be copied to the server, then applied using the VIC. The identical application must be installed on the second workstation.
  • Stop the service and re-start as an interactive session. Ensure that you are logged into Windows using an account that has permissions that match those being used by the service, so that file changes can be saved. Perform the development work. Re-start VTScada as a service.

Plan for Troubleshooting

If you plan to allow programmers and developers to use an Internet connection to access diagnostic applications such as the Source Debugger or TraceViewer, then you must secure those applications and add them to one or more Internet Realm.

People sometimes ask how they can tell whether VTScada is running as a service. To answer that question, use the Windows Task Manager. (keyboard combination: Ctrl-Alt-Del). Assuming that VTScada is in fact running, then if it shows in the list of applications, it is not running as a service. If it shows under the list of background processes (or on the Services tab of the Task Manager) then it is running as a service.
If VTS doesn't show in any list, it is not running on this workstation. The Task Manager won't tell you what is running on remote servers. In this case, if you can see your application, you must be using a Thin Client, and from here you have no way to know whether the server is running in desktop or service mode.


Service Installation

Before installing VTScada to run as a service, it is important to understand Windows account permissions.

The Windows account used to issue service commands (e.g. starting and stopping the VTScada service) must have administrative privileges (and, if using the command line, the console must be run with administrator privileges).

The account under which VTScada runs when running as a service or interactively must have read / write access to the VTScada installation folder, sub-folders and to any other folders external to the installation folder that might be used for data storage.

If running as a service under a regular user account, then to access Workstation Status Driver values e.g. CPU, the account must be a member of the local "Performance Monitor Users" group.

Accounts and Permissions

You must provide the account credentials that VTScada will use when running as a service. You can use any user account that has permission to access the VTScada installation folders. You can use your regular user account or create one specifically to run VTScada under. (The second option is recommended.) On a domain system, your IT administrator can ensure that the correct permissions are set up for the user account.

Having the ability to sign in to the same user account that VTScada will run under allows you to configure aspects of the user account and also to run VTScada in interactive mode as the same user account it will run under when running as a service. But, you are advised not to run VTScada using an account that has administrator privileges.

Windows Security Integration can be used when VTScada is run as a service, but the account under which the service is run must allow the COM operations required for the AD queries.

Notes:

  • If the VTScada service is shut down, and VTScada restarted as an interactive program, then it will use the currently signed in account while in interactive mode. . If this differs from the account that VTScada uses when running as a service, you might not have access to logged data, alarm history and other files written using the service account, and therefore VTScada will be unable to perform required file operations during the interactive session.

  • Certain components (DCOM objects in particular) must grant the user attached to the VTScada Service permissions beyond those given to the administrator by default. For the OPC service, VTScada does this automatically.

Installation Process

There are two ways to install VTScada to run as a service:

  • Choose the Install VTScada Service option during the standard installation.

  • On a workstation where VTScada is installed, stop the program, then run the executable from the command line, using the /s switch.

If running the standard installation, you will select the account to use and enter the credentials in a dialog:

In the following examples, the square brackets are part of the command. Do not add a space before the brackets.

If installing from the command line, you will enter the account selection and credentials as part of the command switch.

  • Install the VTScada service with a fully-qualified user name and password:

vts.exe /s=install[username][password]

Domain accounts should be specified as "DOMAIN\account.name". If your password contains non-alphanumeric characters then you may need to quote the option. For example: /S="install[username][password]".

To remove the service registration use:

vts.exe /s=uninstall


Service Command Line Reference

The following command line options are recognized. (These must be run from a command prompt.)

USE OF THE LOCAL SYSTEM OR LOCAL SERVICE ACCOUNT IS STRONGLY DISCOURAGED.

vts.exe /s=install | Install VTScada as a service using the Windows® operating system account, "Local System". Reinstalls if previously installed. Permitted, but strongly discouraged.
vts.exe /s=install[NT AUTHORITY\LocalService] | Install VTScada as a service using the Windows account, "Local Service". Reinstalls if previously installed. Permitted, but strongly discouraged.
vts.exe /s=install[username][password] | Install VTScada as a service using an account of your choice. Reinstalls if previously installed.
vts.exe | Run VTScada as an application. Fails if the service is not stopped.
vts.exe /s=start | Run the VTScada service, installing it first if not present.
vts.exe /s=stop | Stops the service if it is running but leaves it installed.
vts.exe /s=uninstall | Uninstall the service. Will fail if the service is running.
vts.exe /s=disable | Disable the VTScada service, this leaves the service installed but prevents it from starting.
vts.exe /s=enable | Enable the VTScada service if it was previously disabled. This restores the ability to start the service.


Service Error Dialogs

Server-side dialogs are redirected to a VTScada Thin Client if one is available. By default, this is the longest-running connection because that connection is most likely in a control room.

You can set the preference for which VTScada Thin Client will receive the message by adding a configuration section to your Setup.INI file, found in the VTScada installation folder. Note that changes to that file do not take effect until you restart VTScada.

Client selection done by selecting the account name signed in at each VTScada Thin Client connection. Thus, the list is titled "Default-User-Sessions" and will contain the account names. All VIC connections are checked for each account listed in order. The messages will go to that client connection.

[Default-User-Sessions]
Joe
Bob
Mary

If you are running more than one application, you can have server messages go to the first client connection where a given application is running. For example, if one of the applications is named "Demo" and you would like server messages to go to whichever client connection is running that application (if available), then the list might be written as follows:

[Default-User-Sessions]
Demo
Joe
Bob
Mary

In the event that two clients match the given criteria, then the messages will go to the one that was running for the longest time.

Displayed when someone attempts to start an interactive VTScada session on a workstation where the VTScada service is running.

Displayed when someone attempts to start VTScada as a service on a workstation where it is already running.

Displayed if you attempt to stop the VTScada service using the command line if the console is not running with administrative privileges, or while signed in on an account that does not have sufficient permissions.


VTScada and VPNs

Virtual Private Networks (VPNs) are commonly used to connect the networks of remote sites together and to provide remote access for individual computers. VPNs have largely replaced RAS (Remote Access Server) for remote connections.

A VPN is established between either two network appliances (in the case of joining two otherwise remote networks together) or between a remote computer (such as an engineer's laptop) and a network appliance (VPN gateway).

In the case of two networks being joined together, this usually appears to VTScada as an additional subnet on the LAN. If there are two or more VTScada servers communicating across the VPN, they must have a route to each other. VTScada relies on name resolution to determine the set of IP addresses that may provide a connection to a remote VTScada server and will attempt to connect to each of those IP addresses that there is a route for.

Try to ensure that each VTScada server that must communicate using a VPN can successfully establish a connection to other remote VTScada servers. In other words, that not only can server A initiate and establish a connection with server B, but server B can also initiate and establish a connection with server A. This reduces the connection delay between peer servers and provides some redundancy in the case that one end cannot initiate a connection to the other.

We advise against configuring routing such that a connection attempt will be tried to a gateway that allows the connection to open, only to close it off quickly when the gateway discovers it has no route to the endpoint. Currently, VTScada cannot distinguish between this and a transient connection failure and so will continually retry the connection attempt in the hope that it will eventually work. VTScada will always try and maintain connections to its peers in order to keep data distributed and up-to-date.

In the case of an individual VTScada workstation requiring remote access using a VPN, the VPN may be established using HTTPS or other technology, such as IPSec. The VTScada workstation sees this as a separate network adapter with a route that allows connection to a VTScada server on the remote network.

VTScada will automatically detect the addition / change to the network adapter. Once again, it relies on name resolution to determine the IP addresses to which the remote server(s) can connect.

Often the IP address supplied to the workstation by the VPN gateway will be dynamically assigned from a pool of IP addresses (DHCP). If the IP address assigned to the workstation has been used for a different VTScada workstation recently then DNS records should be updated as soon as possible to allow the server to initiate a connection to the workstation for optimal connection maintenance.

It is strongly recommended that DNS be used for name resolution. DNS allows multiple IP addresses to be obtained for a given server name and will be updated soon after changes to the IP mappings are made, either by clients, a DHCP server or manually.

A local hosts file may be used, or IP addresses (rather than server names) may be specified in the application configuration. Hosts files are limited by only being able to identify one IP address per endpoint. Hosts files and application configured IP addresses carry a higher maintenance overhead should IP address assignments change and do not follow dynamic changes to IP address assignments.

Network Address Translation (NAT) routers are not compatible with VTScada. Do not use.
Each thick-client server must have a unique IP address. A NAT device will cause the same IP address to be assigned to more than one server. VTScada cannot operate in this environment.
As shown in the following illustration, a NAT device will cause Server B and Server C both appear to Server A as if they were on the same IP address.


VTScada and Virtual Machines

It is very common for sites to run VTScada on a virtual machine (VM). If doing so (and especially for Hosted Solution sites) please note the following:

Running more than one virtual machine on a physical server means that the two VMs, by necessity, share resources including CPU, RAM, Disk, Networking, etc. The typical data center applications that run on virtual servers tend to include web servers and databases, both of which are heavily disk-based. But, what works well for web pages does not work so well for a control system.

VTScada requires a machine that is designed for heavy CPU-usage because it is a computational-bound application. (That is, limited by the number of computations the machine can run, more than by the speed of storage access.) Servers that are typically chosen to run VMs are those that are designed for applications such as web servers and databases rather than the VTScada-type application.

Multiple VMs on a server also share the memory bandwidth as well as the total memory size. When multiple VMs are accessing memory, delays are introduced for all due to the finite capacity of the memory to deliver data to the CPU. Disk bandwidth is similarly impacted, but will likely be less of a problem because disk loading tends to be in bursts.

VTScada can use server cores, but most activity is handled by a single core. Although physical machines can have many cores, "server class" machines tend to have much lower clock speeds than "workstation class" machines. VTScada benefits most from higher clock speeds, where 4.0+ GHz is recommended and you should avoid servers with a clock speed of less than 3.0 GHz.

There is also a minor security concern with the vulnerability known as Spectre. "Minor" because there have not been any known attacks using it so far. It theoretically allows a program running in a process to access data in another process. This includes accessing data in a different VM running on the same server. So, even if your VM is kept well protected, a compromise on another VM running on the same server could allow VTScada information to be leaked. This is not a bug in VTScada but in both Intel and AMD processors. While nearly impossible to exploit, it may be a concern for the extra cautious.

Do not attempt to snapshot a VM while VTScada is running.
Doing so will likely result in copying files that are not in a consistent state at the instant when the snapshot is taken. Any attempt to use that backup would have a high probability of having some part of the application corrupted. Attempting to use that snapshot might cause the corrupted file(s) to be distributed to all other connected workstations running the application.
Even if the snapshot is consistent, it would be out of date and using an out of date copy for a machine is highly likely to cause extensive damage to a networked application.
For alternatives, see: Backups

In summary, VTScada works well on virtual machines, but you are advised to avoid installing many VMs running VTScada on a single server.


Virtual Servers

Many sites run VTScada on one or more virtual servers. The technology works well, but beware of the following scenario:

If VTScada is installed on a Virtual Server and then that server is cloned, then both VTScada instances will have the same Machine ID, which is stored in a registry value that VTScada creates. VTScada server redundancy and synchronization processes will not work in this situation. Reinstalling VTScada does not help. This scenario will also lead to duplicate VTScada Serial Numbers. It will also lead to a violation of the VTScada license, which requires one license per computer.

You must change the Machine ID registry key on one of the virtual servers. The key is stored in HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Trihedral. The server must be rebooted after making this change. You are advised to contact Trihedral Technical Support before proceeding.

VTScada must be activated on the new virtual server. License activation is unique to a single machine, virtual or otherwise.

(This is similar to the problem that is caused by installing VTScada on a replacement server using a backup created using a disk-imaging program.)

VTScada should work on redundant VM platforms where there is a shared disk image among redundant VM's, but may incur data corruption in the situation where a near-realtime backup VM image is spooled up when the running VM image incurs an out-of-service event. The risk relates to the hardware configuration.


Setup Recommendations Dialog

The Setup Recommendations dialog summarizes key performance and security best practices and provides hyperlinks for further reading. The dialog is a pop-up that appears when the VTScada Application Manager (VAM) starts. You must click through the slides to enable the close button.

When does the Setup Recommendation dialog appear?

  • The Setup Recommendations dialog will first appear after installation and will appear every time the VAM starts until you check "Don't show this again".
  • The appearance of the VAM is the trigger. If the VAM does not make an appearance due to the configuration of your application, the dialog will not appear.
  • When VTScada is updated, "Don't show this again" will reset to default and the dialog will start appearing each time the VAM starts until you check "Don't show this again" again.

Setup Recommendations will change over time. Changes to the dialog will appear with VTScada updates. When VTScada is updated and the dialog begins to appear again, it is a best practice to review the recommendations for changes before suppressing it again.

About the Hyper-linked Resources

The Security Guidelines Manual is separate from the rest of the Help documentation and can be found in the Documents sub-folder of your installation folder. (C:\VTScada\Documents\VTScada_Security_Guidelines_Manual.html). You do not need an internet connection for the hyperlink to work.

There is a little flexibility for the Optimization Guide. The hyperlink will direct you to the documentation page contained in your installation folder (C:\VTScada\VTSHelp...). This page is as up-to-date as your current version of VTScada. If you have opted out of downloading the local VTSHelp files, the hyperlink will redirect you to the online URL. This page is kept up-to-date with every new version of VTScada.

If you do not have an internet connection and you have opted out of installing the VTSHelp files, you may want to use a separate internet-connected device to check out the Optimization Guide here:

Optimize Your Configuration

Reopen the dialog from the VTScada Application Manager (VAM)

This is especially useful if you want to see the dialog without restarting the VAM or if you have checked "Don't show this again".

Click on the hamburger button on the top-left of the VAM and look for "Setup Recommendations".

From the VAM menu, you will find Setup Recommendations between License Management and Help.


Uninstall VTS

Viewing: Welcome > Installation & Activation > Uninstall VTS

Uninstall VTScada

Before uninstalling a licensed copy of VTScada, you must deactivate the license from the workstation.
You will not be able to do so after uninstalling.

Deactivation

Once activated, a license for VTScada 12.1 or later is associated with the computer it is activated on. To move your license to another computer, you must deactivate it on the first before activating it elsewhere but do not deactivate until the application is installed and running on the new system. You have 30 days following installation of VTScada before you must deactivate the license on the old computer and activate on the new. You are advised to use that time for testing the new system.

A license must be deactivated on one computer before it can be activated on another. To help avoid difficulties, the uninstall program will not proceed until you deactivate the copy of VTScada you are attempting to uninstall.

Start the deactivation process using the button provided in the License Management dialog. Deactivation can be done using the Internet, a URL, or by phone, using a process similar to activation. Deactivation via the Internet or by URL is allowed only a set number of times. Beyond that number, you must deactivate via phone.

You must complete the entire process as described in the Deactivation dialog and according to the method you have chosen, before you can activate the license on a new computer.

Unintall

Your VTScada installation includes a wizard that can assist you in uninstalling the entire VTScada suite, or selected VTScada components. Uninstalling VTScada is a simple, two-step process that removes all components of the VTScada software from your workstation. The uninstall process does not affect any VTScada applications you've created. These applications and their resources will remain untouched.

To completely uninstall VTScada from your system.

  1. Ensure that VTScada is not running.
  2. Navigate to the VTScada installation directory below C:\Program Files\Trihedral\.
  3. Locate the Uninstall.exe file and run it.
  4. Ensure that the Automatic radio button is selected.
  5. Click the Next button. The Perform Uninstall dialog opens.
  6. Click the Finish button. The Uninstall Wizard removes all VTScada components from your workstation.

Although the Uninstall Wizard removes all VTScada components from your workstation, it leaves any applications you have created and their data untouched. These applications can be imported into other installations of VTScada.


About VTScada and Time

VTScada records events using UTC (Coordinated Universal Time). All alarms, logged data, operational events, and everything else that has a time stamp, is recorded using UTC. This ensures that records are stored correctly, even if you have servers in multiple time zones. Time is stored using UTC.

VTScada displays time using your local time zone. This applies to reports, the Historical Data Viewer (HDV), and the clock at the top of each page. It applies whether you are at a workstation with VTScada installed, or are using a thin client connection to view a server in another time zone. Time is displayed using your time zone.

Accuracy of time depends on your computer being configured for the correct time and time zone. If you are in New York, but have configured your operating system to think that it is in London, England, then events will be recorded in UTC using an offset calculated for London, not New York. VTScada will also display times for London, not New York. It is important that you configure your servers to have the correct time and time zone, wherever they are located.

If you manually change the time or the time zone on your computer, you must restart VTScada. Failure to do so can result in inaccurate recording of timestamps.

A very limited number of VTScada's user interface tools can be configured to display time using either the time zone in effect at the server where an event is generated, or the local time. For example, Roster tags can be configured to use either the contact's stated time zone or the time zone of the current Alarm Notification Server. These tools are exceptions. For most of the user-interface, the rule stated above applies: time is displayed using the local time zone.

Viewing Trends and Reports after a Daylight Savings Time Shift

Both the HDV and the various reports display the data from a requested period of time using the start time you specify and an offset from that start time. (If a report configuration uses both a start time and an end time, the offset is calculated by subtracting the first from the second, before querying the history.) You will see all the records that exist from the start time through the length of the offset time. Attempting to view a full day's data (24 hours) on a trend at midnight after the shift to Daylight Savings time (a 23-hour day) can result in an hour-long flat line at the end of the trend.


Find Help

F1 help is linked to all VTScada dialogs and message boxes. To view help for any screen or dialog, press the "F1" function key on your keyboard, and a corresponding help topic will open to guide you. For example, if you need to know more about the VTScada Application Manager (VAM) and its tools, press your F1 function key while viewing the VAM and the help guide will open to that topic.

The Trihedral web site contains a wealth of information about VTScada including a often-updated how-to guide and a collection of training videos. You can also find the full VTScada documentation on-line.

https://www.vtscada.com

Classroom Training. Please see our web site for the current list of upcoming classes. https://www.vtscada.com/training-courses

Our technical support team is on-site and always available to answer your questions. We understand that if you're phoning, you need to talk to someone who can solve your problem now, not just fill in a support ticket. Trihedral takes pride in providing the best possible customer support.

Primary support line:

1.855.887.2232 (Toll-free in North America) or email:support@trihedral.com.

Closed Searching for help

Use the filter button to limit the range of the search. If no results are returned, check that you are searching on All Files, rather than a filtered subset. If there are still no results, try a synonym for the term. Searching for a term used by some other SCADA program will often return the closest equivalent concept used in VTScada.

Sometimes, fewer words in a search are better. If you enter more than one word into the search field, "AND" is assumed. (For example, Tag Browser is equivalent to Tag AND Browser, but not necessarily "Tag Browser".) If you want to specify "or", put that word into your search. For example, a search for CIP DRIVER will return more than 20 results while a search for CIP OR Driver will return more than 300 topics.

Menu links in a page are part of that page. If you search for something that's in a topic title, you will also get the pages that link to that title. This is sometimes useful for catching related information.

The search engine ignores certain commonly used words. For example, a, an, the, of, to, be, you, your, when, however, for, that, can (and more). If your search results are not successful, trim out some of the less important words.

"s" at the end of the word will have no effect on the number of results returned, but might sometimes affect the result ranking. "Driver" and "Drivers" will return the same topics.

Use the following tools to control the search:

Description | Technique | Example
Search for a phrase. | Wrap the string in quotes. | "Create a report"
Search for any of several things | OR | (pipe symbol) | "CIP driver" OR "DNP3 driver" "CIP driver" | "DNP3 driver"
Search for two or more specific strings. | AND + (plus symbol) & (ampersand) | "CIP driver" AND "DNP3 driver" "CIP driver" + "DNP3 driver"
Search for a match that does not contain a word. Note that your phrase must include one word to search for. You cannot search for NOT TAG to get ever topic that doesn't include the word "tag". | NOT ^ (caret symbol) | "driver tags"^CIP
Combinations | ( ) | widget & ("Analog Status" OR "Analog Input")
Closed Using this Help Guide:
  • To bookmark favorite topics in this guide, use your browser's bookmark or favorites button.
  • Click thumbnail images to expand them to full-sized images. Click again to shrink them back to the thumbnail.
  • You can expand topic headings that have an arrow such as " [image] How VTScada Works" and " [image] What's in This User's Guide" by clicking
  • Expanding text is printed only if first expanded. If all you see is the heading, that's all that will print.


Operate

In this section, you can learn about how to operate a VTScada application. For those who are interested and who have the necessary security privileges, links are provide to related sections where you can learn how to build or modify (develop) your applications.

Start and Stop
Options to manually or automatically start and stop VTScada.

Operational Controls
Tools and indicators when working with tags

Print...
Send whatever is on your screen to the default printer.

Alarm Display & Tasks
Using the Alarm Page

Alarm Display & Tasks
Using the Alarm Page

Alarm Analysis
Reports and related tools built into the Alarm Page

Operator Notes Page
Record operational notes to a secure digital notebook

Page Notes
Add "sticky notes" to pages as reminders or to inform other operators of a situation.

Historical Data Viewer (HDV)
Plot historical tag values as trend graphs

Reports Page
Run reports using built-in templates

Operator's Guide to Security
An overview of working within the VTScada security system


Start and Stop

Developers can configure both the VTScada program and a VTScada application to start automatically. Operators rarely do either task. If, as an operator, you are required to start the VTScada program and possibly your VTScada application, the following instructions will help you to do so.

The ability to stop an application is controlled by a security privilege that may not have been granted to you. If this is the case, any attempt to stop the application will be met with the Access Denied dialog. This will be true regardless of the method you choose, including an attempt to stop the VTScada program in general.

There is no security privilege that will block an application from starting. In many instances, it is critical that an application be able to re-start automatically, or permit the first available person to initiate the startup (for example, following a power failure).

If VTScada is running as a service, it cannot also run as an interactive application on the same workstation. Services are typically configured to start automatically.
You may connect to the application using a client instead of attempting to start an interactive session on this computer. See: Thin Clients: Mobile and Internet

Start the VTScada Program

On most workstations, there are (at least) two ways to start the VTScada program, the shortcut link and the start menu entry. Click either.

While VTScada should be installed using an account with administrator privileges, never run VTScada as an administrator. The files it creates during operation (including process history) would then be owned by the administrator group and not writable by a normal account. A similar problem may occur if switching the Windows user accounts used to start VTScada.

Stop the VTScada Program

Stopping the VTScada program also stops all running applications. Many VTScada applications are designed to run continuously. Do not stop VTScada unless you have been advised to do so by your manager.

Start a VTScada Application

To start a VTScada application from the VAM (VTScada Application Manager):

Click once on the quick button beside the application's name. (If the quick button is not a triangle, you may need to expand the triple-dot menu to select Start Application.)

The Start Application button.

  • Click the Start button.
  • Double-clicking on the application name will also start the application.

While an application is running, the VAM also remains open and running, although your VTScada developer may have configured it to be hidden from view.

Stop a VTScada Application

Many VTScada applications are designed to run 24 hours a day, 7 days a week. Do not stop a VTScada application unless you have expressly been advised to do so by your VTScada administrator or other authorized personnel.

The ability to stop an application is controlled by a security privilege (Stop Application) that may not have been granted to you. If this is the case, any attempt to stop the application will be met with the Access Denied dialog. This will be true regardless of the method you choose, including an attempt to stop the VTScada program in general.

Depending upon the way in which your VTScada application has been configured, you can stop your application in two ways:

  • From the VAM. The quick button will now be a square.
    (if it has not been configured to remain hidden)
  • From the application (if it has been configured to show the Windows® title bar)

Activating an Application

Activation is a step towards running. In an activated application, the version control system and the security manager run, but there is no user interface, no I/O, no logging and no alarms.

After an application has been activated, it will remain activated while VTScada continues to run. It is not re-activated when another event in the list occurs and there is no "deactivate" command.

An application is activated when any of the following occur:

  • The application starts (either auto-start, or in response to an operator clicking the run button).
  • Any layer (application) that was built upon this one is activated.
  • A developer opens the Application Configuration dialog.
  • A developer chooses to remove the application from the VAM.

The "Activating" dialog is displayed for a few moments during the process.

The Activating dialog

An application may be activated, but not be running. The attributes of an activated application are:

  • Security is enabled - only authorized users may Import File Changes or access the Application Configuration dialog.
  • In the case of remote (networked) applications, an activated application will send and receive deployed updates.

An application that is activated but not yet started:

  • Does not run the display manager. It is not visible.
  • There is no I/O activity for any of the tags.

The Loading Dialog

A dialog box shows the progress of a loading application while it starts.

The Loading dialog

In the unlikely event that an application fails to complete the loading process, try to make a note of the last message and the progress indicator before calling Technical Support.


Restart Required

Some configuration actions will not take effect until the application is restarted. After making such a configuration change, you will see a Restart Required symbol on the title bar and in the VAM.

You can continue to run your application until a restart is convenient, but no further configuration actions are permitted until the application restarts.

Actions that will trigger a Restart Required situation include:

  • Changes to properties that are designated as "Restart Required".
  • Using the Import File Changes tool in the VAM to import certain types of new code, such as updating a custom-coded VTScada report.


Automatic Start

The VTScada Program

When you configure both VTScada and your VTScada application to auto-start, an operator need only turn on a workstation to access the application. This feature can ensure faster re-start after a power failure, and can also help to prevent operators from running other programs (such as games) on their workstations.

The instructions vary according to your version of the Windows® operating system. In general, you must place a shortcut to the VTSLauncher.exe program in the Windows startup list. Refer to the documentation for your version of Windows.

Your VTScada Application

Often, the sole purpose of a workstation is to run a VTScada application. It therefore makes sense for VTScada and your application to start automatically after a power failure or other interruption.

If you use the HideWAM property in System.INI to hide the VTScada Application Manager (VAM), it is vital that your application start automatically because you will not have access to any of the controls in the VAM.

  1. Open the Application Configuration dialog for the application.
  2. Select the Information option from the menu.
  3. Click on the Automatically Start option so that it is selected.

    Click on Apply.


Shutdown on Low Power

VTScada is configured to perform an orderly shutdown when it is able to detect that the workstation is running on battery power (usually an uninterruptible power supply - UPS), and that battery is nearing the end of its charge.

You can control this feature using the following properties within the configuration file Setup.INI in the VTScada installation folder. These allow you to enable or disable the automatic shutdown feature, and when enabled, set a threshold for three different battery indicators, any of which will trigger an automatic shutdown.

Use these settings with care. Some VTScada users have found that in a location with both intermittent main power and faulty status reporting from the UPS, unexpected shutdowns have occurred.

Related information:

OrderlyShutdown - Enables or disables the feature.

ShutdownOnLowBattery - On or off. When on, and the battery status property indicates "low battery", a shutdown will occur.

LowBatteryPercent - Threshold value. When the remaining battery life, reported as a percentage value, crosses below this value, a shutdown will occur.

LowBatteryTime - Threshold value. When the remaining battery life, reported as a time remaining value, crosses below this value, a shutdown will occur.


Print...

You can print most of the pages in VTScada by clicking on the printer icon, found in the title bar.

In addition to the general-purpose print button, you can also print trend graphs, reports and operator notes.

To print any page:

There are two methods. The default system printer will be used in every case.

The following instructions apply to all pages.

  1. Press the keyboard combination, Ctrl + Prt Scr
    (Control+PrintScreen)
  2. Click OK in the Print Page confirmation dialog.

If the page has a title bar that includes the printer icon:

  1. Click the Printer Icon at the top of the page.

  2. Click OK in the Print Page confirmation dialog.

Result: A snapshot of the current page will be sent to the default Windows system printer.

To print a trend graph:

These instructions apply to the Historical Data Viewer page.

  1. Click the printer icon within the Historical Data Viewer page.

Print the Historical Data Viewer graph

  2. Click the OK in the Print Page confirmation dialog.

Result: The current view of the trend graph (plot or grid, including only the displayed data), is sent to the default Windows system printer.

To print operator notes:

These instructions apply to the Operator Notes page.

Export for printing.

  1. Use the search tools to limit the display to the notes that you want to print.
    All comments on the selected notes will be included in the export.
  2. Click the Export button.

    A Windows® dialog will open, prompting for the file name and folder to which to save the data.
  3. Accept the default file name and folder, or enter a new destination.
  4. Click the Save button.
    If the file already exists, you will be prompted to replace it, or you may return to the previous step and create a new file name.
  5. The file will be saved.
    Your default browser will be opened automatically, displaying the contents of the file.
  6. Print from your browser.

Print the current screen.

Comments will be printed only if they are expanded on the screen.

  1. Use the search tools to limit the display to the notes that you want to print.
    Only notes that fit on the screen will be printed using this method.
  2. Expand any comments that should be printed.
  3. Click the Print button at the top of the screen.
  4. Confirm that you want to print the currently displayed list of notes by clicking OK.

The notes will be sent to your default Windows™ system printer.

To print the alarm list:

While viewing the alarm page, click the printer icon. The full list of alarms will be included. Note that you may limit this using filters for the alarm list. The prompt dialog will ask you for a destination for the output.

To print a report:

To print a report, you must first generate a report. Any report format that you create can be printed.


Operational Controls

No two VTScada applications look quite the same. Each industry has its own requirements and different developers use their own style.

VTScada examples

Overview

These images show a small fraction of the tools available. The differences are mainly in appearance. VTScada itself is the same from one application to another.

If you are an operator, ask your VTScada developer if a custom Operator's Guide has been created for your application. A custom Operator's Guide explains the features of your VTScada application and how to use them.

The things that you can see on a screen fall into one of two categories:

  • Objects that provide context, reference information, or just look good.
    This includes labels, images of tanks or other equipment, background images, pipes, and all the rest.
  • Widgets.
    These are animated, and either show you the current value of whatever I/O tag is linked to the widget, or else they are controls that allow you to write to I/O tags. Widgets are the important parts.

Interact with VTScada

The various responses you can expect when you right-click or left-click on an object are as follows. Note that if your developer has placed two objects on top of each other, such as a tag-widget and a hotbox, the click will be recognized by both and you may end up changing pages and opening a pop-up HDV page.

Page or Object Mouse
Operation 		Result
Widgets showing input tags. Left-click

A windowed version of the Historical Data Viewer page opens and plots the selected equipment values on a graph.

Your VTScada developer may have configured your application to perform this behavior on digital input tags as well as on analog input tags.

Control objects for output tags. Left-click

When a command button or Legacy Set Value hotbox is clicked, it sends a value to the equipment with which it is associated. You should ask your VTScada developer for assistance if the operation of any command button or Legacy Set Value hotbox is unclear.

Navigation controls: hot-boxes and hot-buttons. Left-click

When a page change hotbox is clicked, the page associated with it will open.

Navigation controls: hot-boxes and hot-buttons. | Hover & Right-click | No action.
Tags for input or output Right-click

A shortcut menu with options pertaining to the selected object opens.

If you have the Tag Modify security privilege, you may adjust the scaling and other configuration properties of existing tags.

Widgets linked to tags for either input or output | Hover | Opens a tool-tip identifying the tag and equipment with which it is associated.
Buttons on the Alarm page, Historical Data Viewer page, or in the title bar or navigation bar | Hover | Opens a tool-tip identifying the tool or button and its action.

Tooltips

You can easily identify many of the features in your VTScada application by resting the mouse pointer over them. A tooltip will open and display information such as the name or purpose of a tool or button.

The same is true for tags (widgets):

A tool tip

Tooltips are also provided to assist you in identifying those tags and equipment that are associated with specific objects on your pages. In addition, VTScada developers can add tooltips anywhere at all, to provide instructions or context information.

Confirmation prompts are built into outputs such as buttons, sliders and text boxes. whether they are enabled is a decision left to the person who built the application. If your application developer chooses to require a confirmation prompt on operator controls, they also can provide information that will make the prompt descriptive. For example, "Are you sure you want to change the value to On?" as opposed to "Are you sure you want to issue the control action?".

Calendars

Several pages provide calendar controls if there is a choice of dates for the information you are viewing. (Three examples include the Reports page, HDV trend history and searching Operator Notes.) If you see a calendar control, click to open the calendar date selector:


Find and Open Pages Within an Application

In VTScada, "screens" and "pages" refer to the same concept: an on-screen display of information about your system.

Knowing how to find and open pages is a necessary skill in order to use any application. Even if your application was designed to fit on one page, VTScada itself provides a set of pages for alarm monitoring, creating reports, writing operator notes, and other tasks. Typically though, developers create many pages and design the navigation between those pages as seems best. You are unlikely to find two applications with the same, or even a similar, page layout.

There are usually several ways to find and open a page. Choices for the user will depend on the application design, what security privileges are granted, or both.

The Menu System. There are two versions of this...

1) The list (text) menu

Both the list version and the page version will always have exactly the same content, organized the same way. Use whichever you prefer.

If security privileges were created to protect pages within your application, those privileges also apply to menus. You might not see all pages if your security rights do not include the privilege required for a given page. If you are certain that a certain page exists but you do not see it in the menu then at least one of two things is true:

  1. That page is protected by a privilege that you don't have.
  2. That page was not added to the menu system. There may be other ways to navigate to it, such as via page buttons.

The list version of the menu. Your application will have different entries.

To open the list version of the page menu, select the menu button at the bottom-left corner of the screen. (Shown circled.) The menu will open upwards. Every entry with an arrow to the right will open a sub-folder of menu items if you click or hover.

Navigate using the list version of the page menu

  1. Click the list menu button at the bottom left corner of the VTScada application's screen.
  2. Click on Alarms, Reports and Diagnostics to open that folder.
  3. Click on the Alarms page entry.
    The Alarm page will open, and the menu will close.
  4. Reopen the menu.
  5. Click to open the Remote Sites folder.
  6. Open the Sites page.
  7. Now, try navigating to pages in the menu without clicking to open the folders. If you hover over an entry with an arrow, the folder will open. Try to move the pointer into the folder without it closing, then click to open a page.
  8. Returning to the list menu button, open the Sample Pages folder, then Dashboard A.

The page version of the menu. Your application will have different entries.

The Page Menu

To open the page version of the page menu, either click the four rectangles at the bottom-left corner of the screen

or click the VTScada logo at the top of the screen.

The Page Menu also counts as a page, in that you can navigate to it. The menu will fill the screen with previews of the pages. Where sub-menus appear as fly-out menus in the list version, here they look like folders.

Click a folder to open it.

The ability to show a live view depends on how many tiles there are and the size of the pages shown on those tiles relative to the screen. If the complexity requires excessive workstation resources, then a static "snapshot" view is shown instead. Snapshot views are indicated by a camera image:

Properties control the threshold between live and cached views.
PageSnapshotCacheThresholdCount, PageSnapshotCacheThresholdPct, and PageSnapshotsMaxInMemory.

Navigate using the page version of the page menu

  1. Click the Page Menu Tiles button at the bottom left corner of the screen. (The four rectangles.)
  2. Click on Alarms, Reports and Diagnostics to open that folder.
  3. Click on the Alarms page entry.
    The Alarm page will open, and the menu will close.
  4. Reopen the page menu by clicking the VTScada logo at the top left of the screen.
  5. Click to open the Remote Sites folder.
  6. Open the Sites page.

Navigate with Hotboxes and Page Buttons

Most pages will include links to other pages. These will be either a hotbox or a page button as shown. A hotbox. A page button.The hotbox will not be visible until you hover the pointer over it. Then, it will change color (usually yellow) to let you know that you've found it and can click.A page button is always visible, and therefore much easier to find. Just click to open the target page.

Pin useful pages.

You can create your own navigational shortcuts in the application. When any full-screen page is open, the navigation bar at the bottom of the screen will show it. Within that box, you can click the pin icon to save that page in the list.

You must have access to the task bar beneath a page, therefore pinning is (generally) for full-screen pages.

The ability to choose which pages to pin is all yours. The list is unique to your account; nobody can pin a page for you, and you cannot pin pages for anyone else. Pins set before security is enabled are lost after security is enabled.

Pinning a page.

Removing the pinned Overview page

Navigate to another page and the one you pinned will always be available. You can remove a pinned page from the navigation bar by clicking the X that replaces the green pin.

You can pin as many pages as you want, but it's best to limit the number so that they fit on the screen with full titles displayed.

  1. Navigate to the Alarms page.
  2. In the menu link at the bottom of the page, hover over the pin so that it turns green, then click.
  3. Navigate to the Historical Data Viewer (HDV) page.
  4. Note that the link to the Alarm page remains in the taskbar.
  5. Pin the HDV page.
  6. Use the pinned links to navigate between the two pages.
  7. Unpin the HDV page.

Navigate with Forward and Back Buttons

You must click and hold the Previous or Next button for two or three
seconds to get the list of recently-visited pages.

At the top-left of the screen are two buttons: Previous and Next. You can use the Previous button to step back through the pages you visited earlier. After stepping back through a few pages, you can use the Next button to step forward again.

Click and hold on either button to view a list of pages. You can select any page in the list to revisit, which is probably faster to do than clicking through the list one page at a time.

Navigate from the Title Bar with Keyboard Shortcuts

Key Combo | Description
Ctrl + T | Opens the Tag Browser.
Ctrl + D | Opens the Idea Studio.
Ctrl + P | Opens the Print dialog for current page. (No preview)
Ctrl + ~ | Opens the Application Configuration.

Right-Click to Open in a New Window

Many pages can be opened either full-screen, or as pop-ups, or in some cases, both. This might be useful if you want to view the Alarm page without leaving whatever page you are currently looking at.

The right-click technique works from the menu, (both list and page versions), from the alarm icon in the title bar, and with the list of pinned pages in the navigation bar. It does not work with hotboxes, page buttons, or the Previous and Next buttons.

For example, if you are currently viewing the Overview page, and you want to see the Alarm page as well, right-click on the alarm symbol at the top of the screen. The page opens in a new pop-up window.

The various pages of your application (that is, pages other than those built into VTScada) may or may not work the same way, depending on how they were configured.

Limits on Pop-Up Pages

Some applications are designed to limit the number of pop-up pages that will open. If this describes your application, then you might see a message similar to the following.

Eight is the default pop-up page limit.

Or, extra windows might be denied.


Widgets for Operation

Tags are the building blocks of any VTScada application. Tags are software components that represent equipment and equipment processes and states. Tags also are used to represent the port and the driver that communicate with the equipment, and even the state of computer upon which VTScada is running.

You interact with tags through widgets, drawn on pages. Some or all of the following control widgets may be used in your application:

A knob control. Click, hold, then drag the pointer around the edge to change the setting.

A slider control. Click, hold, then drag the pointer left & right or up & down to change.

A basic button. Click to do what the label says.

Various push-buttons. They work the same as a basic button.

Selector switches and toggle switches. Click on the label for the position you want to set.

Numeric or text entry fields. Click once, type, then press enter or tab to save your changes. Nothing will be set until you press enter or leave the field.

A few other, older types of control may also be available, or your application might include custom controls that don't exist anywhere else.

Widgets can be protected by security privileges. You might find yourself looking at an "Access Denied" message when you try to use some of the controls. Most likely, they will also be configured to required you to confirm a control action before anything is written to equipment. This is an optional feature, which may not be enabled on every control. If you are not sure how a control works, do not click to experiment, expecting to see a confirmation prompt that you can cancel before any damage is done.

Widgets for Monitoring

Input and Status tags gather incoming data from the equipment. For example, a gauge in a tank provides a level reading. This is passed to the I/O device, which passes the data through the computer's port to the Port tag in VTScada. The Port tag passes data onwards to the I/O Device Driver tag, which is able to understand the signals coming from the equipment. The device driver tag translates the information to a format that you can understand, and then passes it along to an Analog Input tag that represents the tank level. The analog input tag can display this data in the form of a numeral, a meter, an animated color bar, or some other widget

Widgets for status tags


Special Symbols for Tags

The operating state of a tag is displayed using the symbols described in this topic. These will let you know when a tag is showing manual values (coded test values instead of actual equipment values) or whether there has been an equipment failure.

Unlinked Widgets

Because developers can draw widgets first, then link those widgets to tags, it is possible to leave unlinked widgets in a page. These will show simulated values.

To avoid the risk of simulated values being mistaken for real process data, the unlinked widget symbol can be drawn on all unlinked widgets. If you see this symbol, know that the values being displayed are coming from a simulator, not from equipment.

Unlinked widget indicator

Note: It is possible to display this warning only as a blinking indicator in the title bar. Developers with configuration privileges can click that symbol to toggle between having an indicator on every unlinked widget or having only a single indicator in the title bar.

Toggle display of unlinked indicators

The title bar version of the unlinked widgets indicator will be visible only while someone is signed in.

Invalid Data

Whenever your application cannot access equipment values due to a communications error or an equipment failure, it reports invalid data. Invalid data is indicated on-screen using one or both of the following:

  • A display of asterisks (*) in place of a value
  • Black in an object's indicator area

Note: colors other than black may be used. Ask your VTScada developer about any special colors configured for your application.

Invalid data indicators

In the first row of images, Invalid Data is shown by the black square on the pump, the asterisks in the text fields and the black circles in the center of the station symbols.

After the equipment or communications problem is resolved and communications are re-established, the invalid data indicator is removed from the object's display. The second row of images displays the same objects in their normal operating state.

Note: It is normal to see invalid data indicators for a few moments while your application begins to run. This will last only until the application has time to communicate with hardware.

Questionable Data

When the value being reported by a piece of equipment is in doubt for any reason, it should be marked as questionable so that operators using the application are aware that the equipment has to be checked and its value confirmed against the data being reported. This is normally seen while a new application or equipment within the application is being commissioned. The Questionable Data indicator serves as a check to help keep track of what has been tested and what still needs to be.

Questionable data indicators

Developers can use a filter in the Tag Browser to find all the tags that have the questionable data indicator set. See: Show only tags marked as Questionable

The ability to mark data as questionable and to enter manual data are user privileges that may not have been assigned to you. Ask your VTScada developer which user privileges you've been assigned.

Manual Data

An exclamation mark indicates manual data. In normal circumstances, you should never see one of these. Manual data means that the tag is not showing a value from the PLC. Instead, it's showing some value that the developer put there, probably for testing

Manual data indicators

An event will be recorded whenever an authorized user changes a tag's manual via the tag's Properties dialog. Use the Alarm History to view the event logs. This action is controlled by the application property, RecordManualDataInEventLog. Refer to the property description for further details.

Developers can use a filter in the Tag Browser to find all the tags that have a manual value set. See: Show only tags with Manual Data


Tag Shortcut Menus

Shortcut menus allow you to interact with the objects in your application by changing their settings, accessing their properties, and performing specific tasks related to the selected object.

A shortcut menu opens when you right-click any graphic object related to the equipment in your system. Some menu options are standard for all objects, while others are limited to objects of a specific type.

The following is an example of the options you might see on a shortcut menu. In this case, the linked tag is an I/O & Calculations type.

The content of a shortcut menu depends the tag linked to the widget you've selected. Different tag types have different options.

Two common options are "Help" and "Properties". These and other options are described, with instructions, in the sections that follow.

You may or may not have access to all the features provided on the shortcut menu. The section that follows discusses disabled shortcut menu options.

Disabled Shortcut Menu Options

Shortcut menu options may be disabled (i.e. appear in gray) if any of the following circumstances exist:

  • You are not signed in to your user account
  • Your user account does not have the appropriate user privileges for the option(s)
  • The feature is not enabled in the linked tag.
    (For example, you cannot shelve an alarm that has not been configured.)

Check mark Shortcut Menu Symbol

A check mark symbol may appear beside certain options in the shortcut menu, such as Questionable Data.

The check mark indicates that the menu option has been activated.

Selecting the same option a second time deactivates it and the check mark is removed. Not all menu items can be switched off and on, therefore not all will have a check mark.

Help Option in tag shortcut menus

If a custom help file has not been configured for your application, then a topic from this guide opens and describe the properties pertaining to the type of tag selected.

The Help option in the shortcut menu may have been configured to provide you with custom help topics or instructions that apply directly to the object you've selected. If so, clicking the help option causes the custom help file to open on your screen to a topic applicable to the selected item.

If the Help option is not available, press F1 (or in some cases, Ctrl + F1) to access the help system.

Manual Data Option

Manual data is most often used for system testing. For example, you may want to check that alarms work as expected, but you do not want to push the live system into a dangerous state. You can set manual data on a tag instead to simulate the alarm state. Widgets on screen will indicate that manual data has been set by showing an exclamation mark (either as text or as a yellow icon).

Take care to remove manual data after testing.

The ability to enter manual data for a tag is a user privilege that may not have been granted to you by your VTScada developer.

Questionable Data Option

Questionable data is used to indicate that an operator has reason to believe that the data for a piece of equipment is not correct. It is also used when commissioning a system, as a means to keep track of which tags remain to be checked. (Those with the question mark). Selecting the Questionable Data option in the shortcut menu places a question mark in each graphic object representing the tag's data.

An example of the questionable data indicator.

Clicking the Questionable Data option from the shortcut menu places a question mark in the selected graphic object's display to indicate that the data being reported is in doubt.

This is a toggle option. Selecting it once turns Questionable Data on and selecting it a second time turns Questionable Data off. You will know that the questionable data option is on when a check mark appears beside it in the shortcut menu.

Shelve Alarm Option

If you possess the required security privilege, you can temporarily shelve alarms.

Logging Deadband Option

You must have tag modification privileges to use this option. It provides access to all logging features of the tag, not just the deadband. Authorized uses can disable logging, select an alternate Historian, and set a time-based logging interval in addition to adjusting the deadband.

A deadband value tells the system how much change is required in an analog value before a change in value is reported and logged. Because some analog values fluctuate very often, you may choose to adjust the deadband value to avoid logging system noise. Data is not reported unless it has changed by at least the deadband amount.

Properties Shortcut Menu Option

You must have tag modification privileges to use this option. The Properties option of the shortcut menu opens the tag properties folder, where you can view and modify the configuration of the selected tag.

Properties vary from one tag type to another as described in Tag Reference


Alarm Display & Tasks

The built-in Alarm Page is the usual tool for viewing and responding to alarms. You can also add a customized Alarm List to any application page, displaying only the alarms that are relevant to tags shown on that page.

If you have applied Global Tag & Area Filtering, you will see only alarms that pass the filter. A warning is provided, as shown. Alternatively, you can configure the list to ignore Global Tag and Area Filters.

An operator must be aware that an alarm exists before they are likely to look at the Alarm Page. VTScada provides the following tools for alarm notification:

Automatic page navigation

Disabled by default. You can choose to have VTScada automatically open a page where the tag related to an alarm is displayed if there is no operator activity for a configured number of seconds after the alarm occurs. Four properties in the alarms tab of the Edit Properties page of the Application Configuration dialog control whether and how automatic navigation will occur. See: Alarms Tab of the Edit Properties Page.

Display manager title bar

When an alarm with any priority level above Event is triggered, the alarm symbol in the Display Manager's title bar will flash red to notify operators. A slash through the alarm symbol indicates that sounds are muted.

Alarm page

When an alarm is triggered, the Current list and the Unacknowledged list on the alarm page display details about the alarm. The Active list also shows the same alarms, except for those configured as "Trip" alarms.

An alarm that is not yet acknowledged is always highlighted in the color associated with its priority in the alarm list. An alarm that was acknowledged is not highlighted, but its text appears in the color associated with its priority in the alarm list as long as it is also active.

Alarm sounds

When an alarm is triggered, an alarm siren will sound to alert operators. After the alarm is acknowledged, the alarm sounds cease.

Spoken alarms

You can configure VTScada to speak an alarm using the Microsoft SAPI speech engine. This can be either in addition to, or instead of, the siren. To configure speech, start by enabling spoken alarms at the workstation (Alarms Tab of the Edit Properties Page), then configure the appropriate Alarm Priority tag. (Alarm Priority Tags)

Station symbol

When an alarm associated with a specific station is triggered, the center of the station symbol on the Overview page will flash in red for all alarms with a priority higher than Event. Two examples of station symbols indicating alarm conditions follow:

After the alarm is acknowledged, the center of the station symbol will stop flashing but will continue to display red to indicate that the alarm is still active.

Station page

When an alarm associated with the I/O at a specific station is triggered, the widget for the I/O tag will flash in red for all alarm priorities above Event. Additionally, the alarm is highlighted in the station page's alarm list using the color associated with its priority. )

Widget indicators

Many widgets will indicate when the linked tag is in an alarm state. If the widgets use a Style Settings tag it will use the color configured in that Style Settings tag when the linked tag triggers an alarm.

Two widgets exist expressly for indicating alarms: The Alarm Priority Icon and the Alarm Priority Box. See: Alarm Priority Icon, Alarm Priority Box

The "Draw" widget does not link to a Style Settings tag but will turn red to signal an active alarm. This widget can also show that one or more of the built-in alarms of the linked tag is disabled. See: Draw Widget.


The Alarm Page

Every VTScada application has an Alarm Page, where you can view alarms, events, and Alarm Manager transactions. What operators can do with that page depends on the security privileges granted to their account.

In addition to the standard Alarm Page, many developers create a customized Alarm List on various pages. These lists can have some or all of the features of the one found on the Alarm Page and may be filtered to match the other contents of the page.

If you have applied Global Tag & Area Filtering, you will see only alarms that pass the filter. A warning is provided, as shown. Alternatively, you can configure the list to ignore Global Tag and Area Filters.

Key Terms:

Alarm:

A notification that an operating condition has exceeded a design limitation. An operator must take action to acknowledge the alarm and to fix the problem. The priority of the alarm indicates the urgency of action.

Event:

A record that something has occurred. No acknowledgment or action is required. An event is recorded for every time that you sign in, sign out, and send a control action to equipment using the SCADA system. Other events may have been created for your application.

Transaction:

Any entry in the alarm or event database. Includes configuration and state changes as well as alarms and events. A single alarm may have many transactions as it activates, is acknowledged, then returns to normal as correct operating conditions are restored.

Applications can be configured so that when an alarm occurs, a page showing the matching tag will open automatically. In effect, the Go To Page feature of the alarm list can be made to happen automatically after short delay.

Open the alarm page

Open the Alarm page by clicking the alarm icon at the top of the screen, or through the menu system. A right-click on any menu link will open the page as a secondary or pop-up window. Other navigation tools can be configured.

You can choose to view alarms from all databases, or from only one at a time.

Highlights from the VTScada Alarm page. Appearance may vary.

Alarm lists can be configured. Yours may not match this image.

The list can be filtered and sorted as needed. Alarms may be acknowledged using the buttons in the Alarm Actions section of the ribbon, but in most cases, it will be easier to use the button provided within the list for each alarm. A right-click on any alarm opens a context menu of controls. In particular, you may find the Plot and the Go To Page entries to be especially useful.

Alarm actions

The following actions are available to deal with alarms. Note that "Suppress" is not included here. Alarms are suppressed when a configured expression is TRUE and unsuppressed when that expression is FALSE.

Ack All |
Ack | Acknowledge the selected alarm. You must first select an alarm from the display before attempting to acknowledge it.
Shelve |
Note | Opens the Alarms notebook, allowing the operator to create a note that will be permanently attached to the selected alarm transaction.
Plot | Opens the Historical Data Viewer, showing the recent trend graph of the tag's value.
Go to page | If the tag causing the alarm is drawn on a page, that will be opened. If it is drawn on several pages, you will be given a choice. If not drawn on a page, an automatically-created one will be shown.

Change font sizes

Choose between five sizes of font for text used in the list and the column labels. Sizes range from small to extra large where each size is two points larger than the last.

Alarm Reports

The list is the report. Sort and filter as needed to display the alarm record that you want to include in your report. Then either print or copy the list to the Windows clipboard for use elsewhere.

Copy the list:

The right-click menu will not show the option, "Copy", but this tool is available. Use the keyboard combination, Ctrl+C to copy the entire contents of the displayed list, then paste that information into a spreadsheet.

All lists are limited to 1000 records, as configured using the property, AlarmPageHistoryRecordLimit.
If there are more records, a Load More button will be available. You can load successive groups of alarms up to the maximum of 100,000 (set by AlarmPageHistoryHardLimit).


List Options for Alarms

Eight lists are available to the Alarm Page and custom Alarm Lists.

Alarm list selection

If you resize your display so that there isn't enough room for all of the options, a set of scroll buttons will be added.

By default, shelved alarms are excluded from all lists except the one where they are the only type of alarm shown. Use the button shown here to include or exclude shelved alarms in your lists.

Database selection

All VTScada applications will have at least two alarm databases: System Alarm DB and System Events DB.

  • The System Events DB holds VTScada events including operator-actions such as signing in and operating a control. The only list where you can see these is the History list.
  • All alarms that you create, even those marked as "events" are stored in the System Alarm DB or other alarm databases that you might create.

When viewing history, you may wish to filter out events and view only alarms. Use the droplist as shown to do so.

If you have created your own alarm databases, an advanced configuration technique is to create named groups of databases, allowing you to use this tool to view a predefined selection rather than a choice between one or all. (Alarm Database Groups)

The lists:

Alarm history list

The History list provides more than a review of past alarms. It also provides a history of operational events including:

  • Security events - a record of operator logons and security management activities.
  • Control actions - who did what and when did they do that.
  • Alarm Notification System events - phone calls, emails and text messages sent, and all related events.
  • Report generation - for reports configured to run on schedule.
  • Alarms acknowledgment, shelving, muting, etc.
  • All changes to alarm configuration.
  • Page notes - creation, acknowledgment, editing and deletion, including the text of the notes and the name of the operator.

Other information may be included depending on the configuration of related application properties. Those properties and their effects are as follows:

  • RecordSuppressionStatus
    TRUE to record the suppression status of an alarm
  • RecordAlarmStatusWhileSuppressed
    TRUE to record the alarm status while an alarm is suppressed
  • RecordAlarmStatusWhileDisabled TRUE to record the alarm status while an alarm is disabled

Several tools allow you to filter which alarms and events are shown, but there are no tools to sort the History list. The order is always by time, with newer alarms added to the top of the list.

Filter the time range:

The span of time shown in the history will be limited to your selection of one of the following Range Limits: 1 day, 10 days, 30 days, 90 days. The purpose is minimize the time required to refresh the list.

View older items by using the calendar control (Date Selection in the following image) to select any date you wish. But, for whatever date you are viewing, no more than 90 days worth of records will be shown in the list.

All lists are limited to 1000 records, as configured using the property, AlarmPageHistoryRecordLimit.
If there are more records, a Load More button will be available. You can load successive groups of alarms up to the maximum of 100,000 (set by AlarmPageHistoryHardLimit).

Tools for the History display.

The pause button will activate automatically when you use the date selection calendar to view older alarm events.

Date selection tools for the history list

Versions of VTScada (VTS) prior to release 11.2, stored log information into separate files for set time spans (usually one month). Those versions included two buttons, Prev Log File and Next Log File to allow you to step through the log files. History is now stored using the Historian, and those buttons are now obsolete.

Active alarm list

Active alarms are those for which the condition that caused them to trigger still exists, whether the alarm has been acknowledged or not.

Only one instance for each alarm can be active at once, therefore entries cannot exceed the number of alarms that have been configured for the application.

Trip alarms are not included in the list of active alarms.

Unacknowledged alarm list

The unacknowledged alarm list displays all alarms that have not yet been acknowledged, whether the condition that caused the alarm to trigger still exists or not.

If the alarm remains unacknowledged, and the alarm trigger or condition has been resolved, but then occurs a second time, the time will be updated for that alarm's entry in the Unacknowledged list.

Current alarm list

Any alarm that qualifies as either Active, or Unacknowledged, will be included in the list of Current alarms.

Shelved alarm list

Shows all alarms that have been marked as shelved. Shelved alarms do not indicate when the associated equipment is in an alarm condition (although an event will still be added to the Alarm History). Operators should monitor this list to ensure that no alarm remains shelved longer than necessary.

Disabled alarm list

Shows all configured alarms in the application that are marked as disabled. Because disabled alarms will not indicate when the associated equipment is in an alarm condition, operators should monitor this list to ensure that no alarm remains disabled longer than is necessary.

If you have the required privileges, you can right-click on any alarm in this (or any other) list and use it's properties to change the Disabled status.

Configured alarm list

Simply, the list of all configured alarms in the application, including shelved and disabled alarms. This list will not tell you whether any particular alarm is active or unacknowledged.

Alarm List View and Fields

The columns that are included in any list will depend on:

  • Which list you are viewing.
  • The configuration of the Alarm Database to which the entries belong.
    Several predefined list formats are available and can be associated with Alarm Database tags or Alarm List widgets. They cannot be applied while viewing the Alarm Page.
  • Whether you have chosen to view the full set of possible columns.

You can change the alarm list background to your preference of black (night time) or white (day time). You may find that one or the other will cause less eyestrain.

If there are too many columns to fit on the screen, you can:

  • Increase the row height. This tool will combine several sets of two adjacent columns into one, stacking the information:

  • Ensure that the text size is set to the smallest of the three possible options. Click the toolbar button to cycle through the sizes.

  • Decrease the number of columns shown. The tooltip shows which columns will be hidden.

Alarm List Content

Notes:

  • The set of columns displayed in any list will vary according to the selected database and the selected list. See: Alarm Database properties Settings tab
  • Alarm Lists added to application pages may use customized column formats.
  • Advanced developers can create customized column formats. See: Customize Columns in Alarm Displays
Column | Content & Purpose
Time | The time and date when the alarm event occurred. Note: for shelved alarms, this is the date of the last significant alarm event, not the date when the alarm was shelved.
Priority | The priority of the alarm will be shown with the configured symbol. These will normally be one of Event, Critical, High, Warning, or Notice. These are the default priorities as configured for the Alarm Priority tags in your application. If you have modified the default Alarm Priority tags or have created your own Alarm Priority tags, the priority of alarms may differ.
State | The state is also shown using a symbol and may be any of: - acknowledged - active - shelve - disabled - configured
Event | History list only. Shows the transaction that occurred to add this to the list. Often matches the state.
Status | The status is also shown using a symbol and may be any of: Normal/Ack - non-active alarms that have been either have been acknowledged, or have never been active and therefore do not need to be acknowledged. Normal/UnAck - non-active alarms that have not been acknowledged. Alarm - active alarms, whether acknowledged or not. Disabled - configured alarms that are not enabled.
Ack | Contains the Acknowledge Alarm (Ack) button, if the alarm has not yet been acknowledged.
Area | The area configured for the Alarm tag (i.e. the text configured for the Alarm tag's Area property).
Name, Description | Properties of the tag that is in an alarm state.
Value | If viewing the History list, this is the value recorded when the alarm occurred, or when it returned to the Normal status. If viewing the Current list, this is the current value of the tag and will change as the tag changes.
Setpoint | The current setpoint of the alarm. The history list will show the setpoint that was in effect when the item was added to the list.
Units | The engineering units configured for the tag that is in an alarm state.
User | History list only. The username of the operator who acknowledged the alarm. Will be blank until the alarm is acknowledged.
Notes | A note icon will be displayed if there is a note attached to this alarm.
Workstation | Shown only in the History list. For alarms and system events, this is the workstation that was the primary server for the alarm Historian at the time of the alarm. For operator events, including those related to alarms, this is the workstation at which the operator was signed in. The machine ID will be shown if the workstation name cannot be determined.
Device | History list. Indicates where an action was done. For example, if an alarm acknowledgment arrived by email, this would display "Email". If the acknowledgment was done on a workstation, the workstation name or IP address would be shown.


Sort and Filter the Alarm List

The History list is always and only sorted by date, with the newest entries at the top of the list. All other lists can be sorted by any column, excepting State and Value. Click on the column header to sort the list by that attribute. Click a second time to reverse the sorting order.

Four filter controls are provided.

* Show Disabled and Show Suppressed apply only to the History list.
Suppressed and disabled alarms are historized based on the RecordAlarmStatusWhileDisabled and RecordAlarmStatusWhileSuppressed settings. Disabled and suppressed alarms do not appear in the history unless one of these settings is TRUE.
Shelved alarms can be made visible in any list but disabled and shelved alarms can never be shown in the Active, Unacked, or Current lists.

Filters are user-specific in the Alarm Page. The filter that you create will not apply to any other user's view of an alarm list.
Filters do not affect notification sounds.

Filter by selection

Use this to limit the list to alarms similar to one that you select. For example, all in the same area, or (History list only) all that were acknowledged by the same operator. You can filter for several properties (Area, User, Priority...) but you must add each filter, one at a time.

  1. Start by clicking to select one alarm in the list.
    (Choose an alarm with a property that you want to match in the filter.)

  2. Click the Filter by Selection button.
  3. Select one property from this list.
    * User is available only when viewing the History list.
  4. The current list will be filtered for alarms that have the selected property in common with the original selection.

Filters are shown on a yellow background. Click the x to remove.

Troubleshooting

  • The Filter by Selection button is not enabled.

One alarm must be selected before you can filter by selection. Click on a list entry that has at least one property that you want to look for with your filter.

Advanced filtering

If the Filter by Selection tool does not provide sufficient options, use this dialog to filter for exactly the alarms you need to see. This filter may be used with any of the display lists.

An alarm must match all the filters to display.

  • While it is possible to clear fields by editing, you are advised to use the X beside the field. This habit will ensure that you do not accidentally create a filter for a blank space, " ".
  • Wildcards are assumed only for the description field.
    For all other fields, you must add the * wildcard if needed as part of your filter.

Upon clicking "Apply" or "OK", the active filters bar of the Alarm List will appear, showing the filters in effect. You may remove filters using that bar, rather than re-opening the Advanced Filtering dialog.

Description

Filter using the text of the alarm's description field. For the description field only, the filter will include all alarms that include the text you provide, not just those that match the text exactly.

This filter can be made case sensitive.

Name

Filter using the name (or unique id) of the alarm tag. This will find only tags with an exact match for the name. Use leading or trailing wildcards to expand the filter to names that include the provided text.

Select the option, Include children, to filter for a parent tag name and populate the list with all alarms in all child tags of that parent.

Area

Use the drop-down list to select one area property for the field. You may type an area value if you would like to expand the filter using wildcards. For example: Zone* will filter for alarms in Zone 1, Zone 2 and Zone 3.

Priority

The priority option creates a filter matching alarm priority values. Use this to filter the list to show only Critical or High alarms. By selecting the "Or higher priority" option, you can filter for High and also include Critical alarms in the list.

User

Enter the account name of an operator, to filter for alarms and events attributed to that operator. It is not possible to filter for more than one operator at a time.

All operator actions including setting output values and shelving alarms, are attributed to the operator signed in at the workstation where the action occurred. Each alarm is attributed to the operator who acknowledges it. Unacknowledged alarms will not be included in this filter.

Event

Select one of the predefined event types from the list to filter for all alarms or events matching that type. Event types are described in Alarm Event Reference

Month

Provides a quick selection of any month in the current year. Use the following option, Date range, for complete control over the start and end dates of the filter.

Date range

Click the calendar icon for the start and end to select any date range desired. You cannot set an end date that is earlier than the start date. Attempting to do so will not result in an error. Rather, the dates will simply be switched so that the new earlier date becomes the start of the range, and the existing later date becomes the end of the range.


Acknowledge Alarms

The ability to acknowledge alarms is controlled by the Alarm Acknowledge security privilege.
VTScada can be configured to require a note when acknowledging alarms. If so, there may be a minimum length for each note.

You acknowledge alarms to silence the warnings and to record who dealt with which alarm and when.

The steps vary according to how you are working with VTScada. This topic provides instructions for each option.

Acknowledge an alarm within VTScada or a VTScada thin client:

  1. Open the alarm page.
    Use the alarm button, the menu, or any other navigational tool provided in your application.
  2. Ensure that you can see the alarm.
    The list may have a filter in effect that hides the alarm.
  3. Select the alarm that you want, then click the acknowledge button - either within the alarm row, or the button in the toolbar.

Assorted acknowledgment tools

Alternatively, you can click the Acknowledge All button to clear all the alarms shown in the filtered list, but this may be discouraged at your location - check with your supervisor.

Acknowledge All or Acknowledge Selected

The behavior of Acknowledge All depends on the value of the property AckAllAcksOnlyVisible. When set to 0 (the default) all alarms that match the current filter are acknowledged. When set to 1, only those that match the current filter and fit on the current display are acknowledged.

Variation for Site Pages:

The Site page for polling drivers, station tags, and other types will have alarm notifications. These will not look like the alarm page, but will show alarms and will include an Acknowledge button.

A site page alarm list

Acknowledge an alarm via email or text message

If your system is configured to send alarms by email or by text message, and if you are authorized to respond in kind, then you can acknowledge an alarm whose message contains an acknowledgment code. This code is unique to you, and to the exact instance of the alarm. Codes cannot be re-used or given to another operator to use.

The address you use must match one within the Roster. If you have configured your email or message system to forward to another account, that account must also be added to the Roster as an alias. The Roster Tags topic describes how to add an alias for your email account.

Use the Reply feature of your email program or SMS text message device to send the code back to VTScada. If this is successful in acknowledging the alarm, you will shortly receive a confirmation message unless your application has been otherwise configured. In the Alarm History, the words "by email" will be appended to your name to show that the alarm was acknowledged via email.

The alarm message will be similar to the following:

From: The VTScada System [mailto:The VTScada System]
Sent: December-14-11 10:43 AM
To:
Subject: The VTScada System: 1 alarm
12/14/2011, 10:42 AM. Default. Default Test Alarm.
Code: XXXX
To acknowledge the alarm, reply with ACK*XXXX, where XXXX is the alarm code in this email.

If configuring an auto-reply for your email account, as is sometimes done when going on vacation, be sure to exclude the VTScada system. Better practice is to remind your manager to disable your account in the roster(s), temporarily.

Rules for Acknowledgment Across a Change in Alarm Status

While an alarm is shelved, disabled, or suppressed, the triggering condition can normalize and then become active again. Alarm behavior upon unshelving / enabling / unsuppressing depends on your configuration of the system through application properties. Refer to the following rules.

Note 1: Those using the VTScada Alarm Notification System should note that these also apply to Notify / NotifyNormal.

Note 2: So far as these rules are concerned, Trip Alarms are considered to have normalized immediately after triggering.

1 If an active alarm is unacknowledged before being shelved, disabled, or suppressed, then it will still be unacknowledged when no longer shelved, disabled or suppressed, even if it normalized in the meantime.

→ | → | → | → |
Active & Unacked | Shelved / Disabled / Suppressed | Normalized or Not Normalized | Unshelved / Enabled / Unsuppressed | Still Unacked.

2) If an active alarm is acknowledged before being shelved, disabled or suppressed, and if the alarm condition remains active, then it will still be acknowledged when no longer shelved, disabled or suppressed.

→ | → | → | → |
Active & Acked | Shelved / Disabled / Suppressed | Remains active | Unshelved / Enabled / Unsuppressed | Still Acked.

3) Rule 2 can be reversed by setting the appropriate property, MakeActiveAlarmUnackedWhenUnshelved / MakeActiveAlarmUnackedWhenEnabled / MakeActiveAlarmUnackedWhenUnsuppressed

→ | → | → | → |
Active & Acked | Shelved / Disabled / Suppressed | Remains active | Unshelved / Enabled / Unsuppressed | Unacked.

4) If an active alarm is acknowledged before being shelved, disabled or suppressed, and if the alarm condition normalizes while shelved, disabled, or suppressed, then even if set to unacknowledged in some way while shelved, disabled, suppressed it will be acknowledged when no longer shelved, disabled or suppressed.

→ | → | → | → |
Active & Acked | Shelved / Disabled / Suppressed | Normalizes | Unshelved / Enabled / Unsuppressed | Still Acked.

5a) If an active alarm is acknowledged before being shelved and if the alarm condition normalizes and then becomes active again, then it will be unacknowledged when no longer shelved.

→ | → | → | → |
Acked / Active | Shelved | Active to Normal to Active | Unshelved | Unacked

5b) For disabling / suppressing alarms, this behavior depends on whether RecordAlarmStatusWhileDisabled / RecordAlarmStatusWhileSuppressed is set to 1. (There is no equivalent for alarm shelving. A shelved alarm is hidden from view but remains fully enabled /

RecordAlarmStatusWhileDisabled = 0 / RecordAlarmStatusWhileSuppressed = 0

→ | → | → | → |
Acked / Active | Disabled / Suppressed | Active to Normal to Active | Enabled / Unsuppressed | Acked

RecordAlarmStatusWhileDisabled = 1 / RecordAlarmStatusWhileSuppressed = 1

→ | → | → | → |
Acked / Active | Disabled / Suppressed | Active to Normal to Active | Enabled / Unsuppressed | Unacked

6) If an alarm is acknowledged and normalizes then there is no alarm. Shelving does not apply.
For a system that transitions from no alarm to what would otherwise be an active state while the alarm is disabled or suppressed, refer to the above rules for what should happen when enabled or unsuppressed.

Troubleshooting:

  • The alarm is not shown in the list.

A filter is in effect. The line behind the filtering tools will be orange if this is the case. Remove the filter.

  • The "Ack" button in the Actions list is disabled.

The alarm hasn't been selected. Or, you are authorized to view the alarm list but not to acknowledge alarms.

  • You acknowledged the alarm, but the sound restarts later.

This may be by design. VTScada managers can configure alarm indicators to re-activate after a period of time if the cause of the alarm has not been removed. You will need to acknowledge the alarm again.

  • There is no acknowledgment code in the email.

Roster tag entries must contain security account names to permit acknowledgment by email or SMS-text message.


Write Out to PLC when Alarm Status Changes

Write out to a PLC address during an alarm event. In a common scenario, a PLC is used to trigger a siren, klaxon, illuminated beacon or some other local event to alert operators. Once the alarm has been acknowledged, the PLC stops the alert.

Using an Alarm Status Tag and an I/O & Calculations Tag

A simple way to do this is to create a tag that will monitor for unacknowledged alarms and a second tag that will write out to the PLC when the conditions are met. (ie. alarms acknowledged.)

  1. Create an Alarm Status tag.

    1. Configure it with the necessary filters for priority, area and name.

    2. Set the Alarm List to "Unacked".

  2. Create an I/O & Calculation tag.

    1. Set the Data Type to "Digital"

    2. Check the "Calculation" check box.

    3. In the Calculation tab, set the Calculation field to "tag" mode and select the Alarm Status tag.

    4. Set the I/O Device and address appropriately to write to your PLC.

The Alarm Status tag's value will become TRUE when there are unacknowledged alarms that meet the set filter criteria, and FALSE when there are not.

Related information:

Alarm Status Tags

I/O and Calculations Tag I/O and Calculations Tag


Silence or Mute Alarms

The ability to silence or to mute an alarm is controlled by the Alarm Mute and Alarm Silence security privileges.

These operations apply only to the current operator and only on the current machine / device unless otherwise configured. See note at the end of this topic.

Alarm warning tones are designed to attract attention. They tend to be loud and unpleasant, and usually continue to sound until the alarm is acknowledged. (Both the sound and the duration can be configured.)

There may be situations where you either cannot or must not acknowledge an alarm immediately. You may wish to stop the alarm sound until then.

Alarm silence and mute controls

Silence applies to currently sounding alarms. Their audible warning will stop and will not re-start. New alarms coming in will be audible. To silence all current alarm sounds, click the indicated button.

Mute blocks all alarm notification from your computer's speaker. You must choose the duration of muting and you can unmute the alarms at any time, allowing sounds to resume. New alarms are also muted - the button applies to all current and future alarms equally.

While the mute option is in effect, the alarm indicator at the top of the VTScada screen will have a slash to indicate that audible warnings are disabled.

Indicator for alarm muting

To mute alarm sounds:

Mute dialog

Muting turns off all alarm sounds, including for any new alarms that come in while muting is in effect.

  1. Open the alarm page.
  2. Click the Mute button to block all alarm sounds.
  3. Select the duration of time for which muting will be in effect.

Notes for VTScada Developers:

Two application properties control whether silence and mute should affect all users or all workstations.

By default, silence and mute affect only the logged-on user on the current workstation. If your workstation or device changes its network connection from one IP address to another, that is considered a different device for the purpose of these properties.

ApplyMuteSilencePerUser | ApplyMuteSilencePerComputer | Result
1 | 1 | (default) Silence and mute affect only the signed-on user on the current computer / device.
0 | 1 | Changes to silence and mute will affect only the current workstation / device, but will remain in effect for all users until changed.
1 | 0 | Changes to silence and mute affect only the current user, but will follow a user who logs out from one computer / device, and in on another.
0 | 0 | Changes to silence and mute will affect all users on all workstations / devices.

For Developers: The application property, MaxMuteDuration can be used to prevent alarms from being muted for an excessive (or indefinite) length of time.

Muted Alarms Sound After Automatic Sign Out

This is by design. By default, alarm muting applies only to the current user and workstation, subject to the configuration described in the preceding table. If you mute an alarm, then leave your workstation, the alarm will sound when your account is signed out automatically.

The following tip may not be desirable in most situations, but you can prevent this behavior by muting alarms indefinitely (if allowed by MaxMuteDuration) for the Logged Off role. To do so, you must temporarily grant that role access to the Alarm Page and the Alarm Mute privilege. Sign out. Navigate to the Alarm Page. Mute indefinitely. Sign back in with your own account and ensure that you remove the temporary privileges from the Logged Off role.


Shelve Alarms

The ability to shelve an alarm is controlled by a security privilege that may not have been granted to you.
You may be required to create a note when shelving or unshelving alarms. If so, there may be a minimum length for each note.

Shelving is an operational action that can be used to deal with lower priority or nuisance alarms such as those that result from expected maintenance operations rather than those that signal a dangerous situation.

A shelved alarm remains enabled, and new alarms will be logged, but nearly all notifications and sounds will be disabled. The only remaining notification is that, if the tag has been drawn using a widget that changes color to indicate an alarm, then that color change will still occur.

Shelve dialog

View shelved alarms in any list

By default, shelved alarms are not included in lists other than the one designed to display them: Shelved Alarms. You can choose to view shelved alarms in any list by toggling the visibility control in the Filtering tools.

The act of shelving or unshelving an alarm will be shown as an alarm event in the History list.

Unshelving versus Acknowledging

If the alarm triggering condition normalizes while an alarm is shelved, you must still acknowledge the alarm after the shelving time period expires.

The act of manually unshelving a normalized alarm before the time period expires will automatically acknowledge that alarm. Developers can change this behavior by setting the property ManualUnshelveDoesNotAckNormalAlarm to 1.

Comparison: Shelve / Disable / Suppress Alarms

Feature | Used by | Use to...
Shelve | Authorized Operators Available through the user interface. | Hide and silence an alarm temporarily.
Disable | Developers / Engineers Must be configured in individual alarms. | Block specific alarms from occurring. For example, the alarm is not currently needed but might become relevant again.
Suppress | Automated Developers set a condition for suppressing one or more alarms using an expression or a tag. If set using a memory tag, authorized operators can suppress the alarms. If set using an expression, alarms can be suppressed automatically. | Block specific alarms from occurring while a condition is true. For example alarms might be suppressed while related equipment is not running.

Status indicator for shelved alarms

This view of an alarm history shows an alarm monitoring a tank's level. The lower line shows the alarm being activated. The upper line, with a time stamp several seconds later, shows the same alarm being shelved. All notifications related to that alarm will stop.

Alarm shelving is an operational task. No alarm can be configured as shelved.

The steps to shelve or unshelve an alarm are the same. If the alarm is not shelved, the menu or button will allow you to shelve it. If the alarm is shelved, the same menu or button will allow you to unshelve it.

A manually unshelved alarm will automatically move to the acknowledged state.
An automatically unshelved alarm does not. Except, that if the level normalizes while the alarm is shelved, then when the alarm is unshelved (either manually or automatically) it will no longer need to be acknowledged. Shelving (an operator action) + normalizing = an alarm that has been fully dealt with.
Since Trip alarms do not have an active / normal state, they are treated the same as an alarm that normalizes while shelved.

To shelve an alarm:

There are two methods:

  1. Open the Alarm Page, or any page that contains an alarm list.
  2. Right-click on a displayed alarm.
  3. Select Shelve from the menu that opens.

Or:

  1. Open the Alarm Page, or any page that contains an alarm list with a toolbar.
  2. Click on an alarm entry in the list, selecting it.
  3. Click the Shelve button in the toolbar.
    Note that you can shelve either the selected alarm (if you have selected one) or all shown in the list.

To view a list of all shelved alarms:

  1. Open the Alarm Page.
  2. Click the "Shelved" label in the set of List Options.

Shelved alarms will be included in this list regardless of whether they are also disabled.

For Developers: The application property, MaxShelveDuration can be used to prevent alarms from being shelved for an excessive (or indefinite) length of time.

Troubleshooting:

  • You are unable to use these functions.

These features are protected by security privileges. Check with your VTScada manager.


Suppress Alarms

Alarm suppression is used to prevent unnecessary alarm activations, annunciations, and notifications when the operational environment deems an alarm to be inapplicable. Alarm suppression is applied and removed automatically via a configured expression or tag reference. For example, if a "Low Flow" alarm is configured to detect a low flow rate, but the alarm is meaningless if the pump isn't running, then this alarm should be suppressed (suppression set to TRUE) when the "Pump Running" tag is FALSE."

The alarm will be suppressed when either the expression you write or the tag you select returns TRUE (1).

By comparison, alarm disabling must be done by an authorized person, directly in the configuration of each alarm. Also, the rule governing the suppression of one alarm can apply to many, whereas the act of disabling an alarm must be done one alarm at a time.

While the result of disabling or suppressing an alarm is the same (no alarm), these are different operations and therefore they are tracked independently. The Alarm Page and the Alarm List Widget provide separate views for disabled and suppressed alarms.

The condition that suppresses an alarm may be independent of whether anyone is signed in, therefore this feature is not protected by a privilege beyond the ability to create or modify tags.

The alarm suppression feature is available in Alarm tags and I/O & Calculation tags. For an I/O tag, there is a single alarm suppression expression that suppresses all the built-in alarms.
This feature does not apply to legacy Status tags.

Each time you toggle suppression on an alarm, an event is recorded. If you must repeat this operation frequently for hundreds of tags, a large number of events can be recorded. In this situation, consider setting the property RecordSuppressionStatus to 1.

Customers who used VTScada prior to the release of this feature might have configured parameter expressions in their I/O & Calculation tags to disable alarms. Those expressions are automatically transferred to alarm suppression as part of the upgrade process.

Comparison: Shelve / Disable / Suppress Alarms

Feature | Used by | Use to...
Shelve | Authorized Operators Available through the user interface. | Hide and silence an alarm temporarily.
Disable | Developers / Engineers Must be configured in individual alarms. | Block specific alarms from occurring. For example, the alarm is not currently needed but might become relevant again.
Suppress | Automated Developers set a condition for suppressing one or more alarms using an expression or a tag. If set using a memory tag, authorized operators can suppress the alarms. If set using an expression, alarms can be suppressed automatically. | Block specific alarms from occurring while a condition is true. For example alarms might be suppressed while related equipment is not running.

By default, no actions are recorded for an alarm while it is suppressed. You can alter this behavior using configuration properties such that, even though the alarm is suppressed, the occurrence of the activating or the normalizing state will be recorded. These records go directly to the Alarm History and are never part of the active alarm list.

If an alarm becomes unsuppressed while it is active, an event will be logged. Trip alarms do not have active/normal states. When a trip alarm becomes unsuppressed no event will be logged regardless of its recent activation history.

Related properties

MakeActiveAlarmUnackedWhenUnsuppressed - TRUE to mark an active alarm as unacknowledged when it becomes unsuppressed

RecordSuppressionStatus - TRUE to record the suppression status of an alarm

RecordAlarmStatusWhileSuppressed - TRUE to record the alarm status while an alarm is suppressed


Disable or Enable Alarms

The ability to disable or enable an alarm is controlled by a security privilege that might not have been granted to you. See your VTScada manager.
Disabling or enabling an alarm is a tag configuration change, not an operational change. It cannot be done with the tools in any alarm list.

There may be times when equipment must be taken offline. Rather than have alarms occur as a result, you may prefer to disable the associated alarms. The Alarm Page includes a list of disabled alarms, thus making it easy for you to find all the alarms that need to be re-enabled when the time comes. Procedures at your location may require that alarms be shelved rather than disabled. (Shelve Alarms)

To disable an alarm, use the tag's configuration panel. By design, the option of using an expression is available to alarm suppression but not for alarm disabling. This is in accordance with ISA 18.2: Disabling an alarm is considered a configuration action that should be done explicitly. Alarm suppression can be linked to an expression or tag. The effect is the same but the actions should be tracked independently.

Alarm tag - Actions tab.
Note that either an expression or another tag can be used to disable the alarm

Related properties

MakeActiveAlarmUnackedWhenEnabled
TRUE to mark an active alarm as unacknowledged when it becomes enabled

RecordAlarmStatusWhileDisabled
TRUE to record the alarm status while an alarm is disabled

Customers who used VTScada prior to the release of this feature might have configured parameter expressions in their I/O & Calculation tags to disable alarms. Those expressions are automatically transferred to alarm suppression as part of the upgrade process.

Comparison: Shelve / Disable / Suppress Alarms

Feature | Used by | Use to...
Shelve | Authorized Operators Available through the user interface. | Hide and silence an alarm temporarily.
Disable | Developers / Engineers Must be configured in individual alarms. | Block specific alarms from occurring. For example, the alarm is not currently needed but might become relevant again.
Suppress | Automated Developers set a condition for suppressing one or more alarms using an expression or a tag. If set using a memory tag, authorized operators can suppress the alarms. If set using an expression, alarms can be suppressed automatically. | Block specific alarms from occurring while a condition is true. For example alarms might be suppressed while related equipment is not running.


View the Related Tag

You can learn more about an alarm situation by viewing the linked tag as it was drawn on a page. In many cases, controls that you can use to deal with the alarm situation will also be available on the same page. Naturally, this depends on whether the linked tag was drawn on any page within the application.

Right-click menu for a selected alarm.

  1. For any alarm in the list, right-click to open a context menu.
  2. Click, "Go To Page" in the menu.

Alternatively, left-click on the alarm, then click the Go to Page button in the ribbon:

If the tag linked to that alarm was drawn on a single page, that page will open.

If the tag linked to that alarm was drawn on several pages, then a menu of choices will be displayed. A Site Details page option will be available if the tag can contain other tags.

Selection shown only when there is a choice of pages.

Troubleshooting:

  • A message tells you, "No pages that you have access to display the tag(s)".

Either there are no pages that display that tag, or your security privileges do not permit access those pages.

  • The Go To Page entry is not enabled.

Your developer has disabled this feature as a security measure. See: DisableGoToPage


Plot Trends from the Alarm Page

If the tag that triggered an alarm can be viewed in the Historical Data Viewer (HDV), then you can open the HDV for that tag directly from the alarm list.

To plot from the alarm list:

  1. Ensure that only one alarm entry is selected.
  2. Right-click on that entry in the alarm list.
    A context menu opens.
  3. Click, Plot.
    The HDV page opens as a pop-up window, showing the trend plot of whatever tag triggered the alarm.

Alternatively, left-click on the alarm, then click the Plot button in the toolbar:

Plot the selected alarm

Troubleshooting:

  • The plot entry is disabled.

The trigger associated with this alarm cannot be plotted in the HDV.
Your account does not have permission to view the Historical Data Viewer page.


Print or Export the Alarm List

Alarm lists are alarm reports. Use the filtering and sorting tools to limit the display to only those alarms you are interested in seeing, then use the Print tool to send the list to your default system printer.

To export, use either Ctrl-C or the "Copy to Clipboard" button to copy the list to the Windows clipboard for use elsewhere. If viewing the Alarm Page on the Anywhere Client (a thin client) then the "Copy to Clipboard" button is replaced by an "Export to CSV file" button.

The currently displayed list will be used in either case.

To print the current alarm list:

  1. If the Alarm Page is open as a full-screen page, click the printer icon at the upper right of the screen.

  2. Choose whether to send the list to the default printer, or to a printer file that can be copied to a printer at a later date.

If you chose Output to file, you will be prompted for a file name and location. Otherwise, the alarms will be sent to the default Windows system printer.

Troubleshooting:

  • Nothing is printed.

No alarms match the current list option, filtering options and selected time range.

The default Windows system printer for your computer may not have been the one you expected.


Dialing-in. The Alarm Notification System Menu

This information applies only to VTScada installations that include the optional Alarm Notification System. If your application has this feature, and you are one of the operators on the callout roster, then the following will help you to work with the Alarm Notification System menu.

The VTScada Alarm Notification System will begin each phone call by announcing itself and requesting your authorization code, which is the Alternate Identification Value that your manager defined for you in the security Accounts dialog (Configure Alternate Identification). The wording of the announcement is controlled by your VTScada Developer, but typically begins with the words "This is the VTScada system at <your company>."

You can enter your Alternate Identification by dialing the number on your phone. If your employer is using Twilio, you can also speak your Alternative Identification number out loud. What happens after you have entered your Alternate ID depends on how your developer has configured the system. You may begin with the Main Menu, or the developer may have configured the system to go directly to one of:

  • The list of unacknowledged alarms.
  • The list of active alarms.
  • The control menu.
  • The station status menu.

The following sections describe your options in each of these menus.

The Alarm Notification System Main Menu

From the main menu, you may press a number from 1 to 4 to access any of the other menus, or you may press star (*) to hang up.

The Alarm Notification System Unacknowledged Alarms Menu

The list of unacknowledged alarms spoken depends on two things: First, only alarms in the area you are permitted to view will be spoken. Second, if the Alarm Notification System initiated the call, then only the alarm(s) that caused that call to be made will be spoken. If you called the VTScada Alarm Notification System, then all unacknowledged alarms in areas that you are permitted to see will be spoken.

After the list is read, you can press 1 to repeat, 2 to acknowledge, or * to return to the main menu.

The Alarm Notification System Active Alarms Menu

The list of active alarms, in areas that you are permitted to view, will be read.

You can press 1 to repeat the list or * to return to the main menu.

The Alarm Notification System Control Menu

Start the control menu by entering the ID number of the station whose tags you want to control.

The alarm notification system will read the list of control tags in this area. Enter the number of the output tag that you want to control, followed by the # key. Entering just the # key at this point causes the list to repeat.

You can control the tag by pressing 1 to write a 1 or "ON" value, or you can press 0 to write a 0 or "OFF" value. Pressing the * key will take you back to the list.

The Alarm Notification System Station Status Menu

Start this menu by entering the ID number of the station whose tags you want to learn about. For the given station, the system will read the current values of the Pump Status tags followed by the Digital Status tags, followed by the Analog Status tags.

You can press 1 to repeat the information or * to return to the beginning.


Alarm Batch Operations

Many alarm tasks, such as adding a note, can be done only to a single alarm at a time.

Other alarm tasks, such as acknowledging or shelving alarms, can be done to a group of alarms. For these tasks, you will need to Sort and Filter the Alarm List.

Acknowledge a Group of Alarms

  1. Open the alarm page
  2. Filter the alarm list to show only the alarms that you wish to acknowledge.
  3. Use the Acknowledge All button in the Alarm Page toolbar to acknowledge all shown.

Shelve or Unshelve a Group of Alarms

  1. Open the alarm page
  2. Filter the alarm list to show only the alarms that you wish to shelve.
  3. Use the Shelve All Shown tool in the Alarm Page toolbar to shelve all shown.

Disable a Group of Alarms

Under the ISA 18.2 standard, the ability to disable alarms is a configuration option, done on a tag-by-tag basis by system developers, and is not available to operators.

Use Suppress Alarms instead.

Mute and Silence

Mute applies to all alarms and cannot be done on an alarm-by-alarm basis.

Silence applies to all currently sounding alarms.

Filters do not apply in either situation.


Alarm Analysis

Use these tools to learn more about a selected alarm in the list, or alarm statistics in general.

Alarm Reports

Opens a dialog with four alarm reports: Bad Actors, Alarm Flood, History, and Distribution of Priorities. Use these to spot trouble-prone hardware or possible improvements in the alarm configuration. See: Alarm Reports

Show Details

The dialog that will open contains four tabs: Details, Configuration, Statistics and Notes.

The Details and Configuration tabs will seem to duplicate eleven properties, but there is a significant difference between them: The Details tab shows information about the alarm event as recorded at the time it was occurred, whereas the Configuration tab shows information about the alarm as it is currently configured. An authorized user can change the alarm configuration at any time, but that will have no effect on the details of a particular alarm event as recorded.

Plot

Opens the Historical Data Viewer trend graph as a pop-up page, filtered to show only the tag whose value triggered the alarm. The Plot button will not be enabled if the alarm trigger uses an expression rather than a tag value. Restricted to user accounts that are permitted to view the HDV page.

Go To Page

Opens a page where the alarm, or the tag whose value triggered the alarm, can be seen. If that tag was drawn on more than one page, you will be given a choice of which page to view. Page access may be restricted based on your security privileges.

Copy to Clipboard

Performs the same function as pressing the keys, Ctrl-C. The contents of the currently displayed alarm list are copied to the Windows clipboard for use elsewhere. If viewing the Alarm Page on an Anywhere Client, the Copy to Clipboard button is replaced by an Export to CSV file button.

Properties

Opens the tag configuration dialog for the alarm. Restricted to user accounts that have tag modification privileges.

Show Configuration Events

Easily overlooked, this tool is part of the Filtering group and is enabled only when viewing the History list. The event types that fall under the category of "Configuration" are:

  • Commission
  • Decommission
  • Modify
  • Purge
  • Recommission
  • Reconcile

These are all the events that modify the Configured list, plus one (Reconcile) which happens when some portion of the alarm history needs repair. This tool is most useful when you want to see the history of an alarm's configuration, such as when it was first commissioned and when it was subsequently modified. Combine with other filters to display the configuration history for only one alarm.


Alarm Reports

Alarm reports help you to identify trouble spots, whether the cause of the trouble is in the physical system or in the configuration of your application. Most alarm report are presented as Alarm Lists, meaning that the usual filters and display options are available to help you focus on areas of interest in a report.

Alarm Lists are alarm reports. You can copy the filtered list to your Windows clipboard and then paste it into a document, a spreadsheet, or any other program.
In addition, there are several preconfigured filters, available via the toolbar button, "Alarm Reports". These are described in the following notes.

Toolbar detail.
On the Anywhere thin client, "Copy to Clipboard" is replaced by "Export to CSV file".

By default, each report shows a 30-day time period, but you may adjust this as needed. Reports show only Active and Trip alarm events unless you filter for other events.

Any filter that you select will remain in effect while you switch from one report to the next. This can be helpful for gathering more information about an event. For example, you might start by identifying a day on which an alarm flood occurred in the Alarm Flood report. Clicking on that bar in the graph filters the display to one day. You might then view the History report of alarms for that day to see which ones were part of the flood. You might then add name filters to view all the occurrences of one alarm at a time on that day.

As with any alarm list viewed on a VTScada workstation, you can use the keyboard combination, Ctrl+C to copy all information shown in the list, then paste that information into a spreadsheet.

Bad Actors Report

A bad actor is an alarm that is activated or tripped an excessive number of times within a time period. This may indicate a problem with equipment, with a process, or with the configuration of that alarm.

A common misconfiguration is to put an alarm on a normal process in order to create a report of the times when an expected event occurs. Do not do that. There are better ways to create reports.

The Bad Actors report shows all alarms that occurred within the time period, sorted by the number of times they were activated or tripped. This does not imply that all the alarms listed are bad actors. The purpose of the report is to help you find those that might be classified as such.

This report can be copied to the Windows clipboard by pressing Ctrl+C or using the Copy to Clipboard tool, then pasted to a spreadsheet. The columns Priority, Area, Name, Description, Count and Percent will be included.

All alarms are included. Only those with unusually high counts are "bad actors".

Alarm Flood Report

The Alarm Flood report shows a bar graph of the number of alarm occurrences within the selected time period. The information shown in this report is not restricted to alarm flood events but will help you to identify any that may have occurred.

The time covered by each bar in the graph varies depending on the length of the selected time period. Each bar may represent a day or may represent only a portion of a day.

Alarm floods are indicated by unusually tall bars.

As you move the pointer over the graph, it will appear as a cross-hair, with a vertical highlight matching the selected time slice. A tooltip window will follow the cross-hair, identifying the date range of the selected time slice and the number of alarms that were activated or tripped within it.

You can left-click on the graph to change the displayed range to a single day, within which each bar / time slice shows a half-hour interval. Right-click to return to the previous time range.

History Report

The History Report is identical to the History list from the Alarm Page, except that it is prefiltered to show only Active and Trip alarm events.

This report can be copied to the Windows clipboard by pressing Ctrl+C or using the Copy to Clipboard tool, then pasted to a spreadsheet. All columns will be included.

A history report

Select any alarm event in the list then use the tools from the Analysis portion of the toolbar to gather more information about it.

Distribution of Priorities

This report can be used by VTScada developers to help them design the application's alarm system to follow the ISA 18.2 standard.

The left-most graph shows the number of alarms activations and trip events within the selected time period, grouped by priority. This reflects the reality of current operations.

For those who are interested in ISA 18.2 compliance, the middle graph and the right-most graph should be used together. The standard recommends that only five percent of configured alarms be critical priority, and fifteen percent be high priority. The alarm configuration of your application is shown in the middle graph.

A sample configuration compared to the ISA 18.2 recommendation

The ISA 18.2 standard is available from the ANSI / ISA website at: https://webstore.ansi.org/standards/isa/ansiisa182016


Alarm Details Dialog

This dialog can be opened from the Alarm Page for any selected alarm. Use it to view all the available information about that alarm in one screen. This dialog provides more information than is available in the Alarm Page display, including configuration details for the alarm and statistics for how often it has occurred.

Alarm Details - Details display.

Details dialog / details tab

The details display shows fundamental information about the alarm including the configuration details that were in effect at the time the alarm occurred. Also included is the value of the trigger at the time that the alarm was activated, the database that the alarm is a part of, and related information as shown in the example.

Alarm Details - Configuration display

Details dialog / configuration tab

The configuration display shows the alarm's current configuration values. Note that these may have changed since the occurrence of the alarm being examined.

Alarm Details - Statistics display.

Details dialog / statistics tab

This tab shows the number of times that the alarm has been activated during each of four user-configurable time ranges. The average per day over each time range is also calculated and displayed.

Note that the maximum number of records that are counted when showing these stats is 1000. Also, when counting the records, VTScada filters for the alarm's current Area. If the alarm's Area has changed recently, the records with the old Area are not counted.

VTScada Application developers can change the number of days shown in each of the four windows.
See:AlarmStatRange0 - AlarmStatRange3

Alarm Details - Notes display

If any notes have been attached to this alarm, or if you wish to add notes or comments, use this tab of the Alarm Details page. See: Alarm Notes


Alarm Notes

There are two ways to add a note to any alarm. The easiest is to use the Add Note button:

  1. Select that alarm in a list, then click the Add Note button:

This method opens the Add Note dialog within its own window:

The Add Note dialog with a sample note:

You can also create new notes from the Alarm Details dialog as follows:

  1. Select the alarm in a list, then click the Show Details button.
  2. Open the Notes tab.
  3. Click Add Note.
    The Add Note dialog will open.

As with any other form of operator note, you may type in a new note or select a predefined note from the Quick Note list.

An alarm with a note.

Click the note icon in the alarm list to open the Alarm Details page, opened to the Notes tab. You may add new notes or comments to the alarm at any time.

For VTScada Developers: Every alarm database will have a child Notebook tag. Notes created for alarms in a particular database will be stored in the notebook matching that database.


Alarm Event Reference

Acknowledge

Recorded when an operator acknowledges an alarm.

Active

The triggering condition for the alarm is valid, and the alarm is not configured as a trip alarm.

Active Ack

An alarm is activated and acknowledged in the same transaction. This event type is included for compatibility with alarm standards, but will not occur within VTScada.

Commission

Recorded when an alarm is created. Also recorded when the tag that has the alarm is re-enabled after having been disabled.

Decommission

The tag containing the alarm was disabled or deleted.

Disable

The disable option was set in the alarm's configuration.

Enable

An alarm that had been disabled was re-enabled.

Event

Used only for VTScada events such as operator control actions.

Modify

A transaction in which the alarm was reconfigured.

Normal

The triggering condition for the alarm is no longer valid (and the alarm is not a trip alarm), but the alarm has not yet been acknowledged.

Normal Ack

An alarm is cleared and acknowledged in the same transaction. This event type is included for compatibility with alarm standards, but will not occur within VTScada.

Notify

A phone call, email or text message was sent by the VTScada Alarm Notification System.

Off Normal

An alarm that is activated without becoming unacknowledged. This event type is included for compatibility with alarm standards, but will not occur within VTScada.

Purge

Orphaned alarm events are purged automatically. These records are not deleted, but are marked as purged and hidden unless you choose to view them using the control in the alarm list toolbar.

Rearm

The alarm was acknowledged, but left in an active state longer than the rearm time. (Automatic rearming is an optional configuration property of alarms.

Recommission

Moving or renaming an alarm tag will always cause a Decommission / Recommission pair as the old name is decommissioned and the alarm is recommissioned under the new name.

Reconcile

(Formerly, "Rename") Housekeeping tasks whenever a rename, move, or recompile of an alarm tag occurs.

Shelve

Recorded when an operator shelves the alarm.

Suppress

Recorded when the configured event for alarm suppression occurs

Trip

The triggering condition has occurred for an alarm configured with the Trip flag.

Unshelve

Recorded when an operator deselects the shelve option for the alarm, or when the preset shelving time expires.

Unsuppress

Recorded when the configured condition for alarm suppression is not longer true.


Operator Notes Page

The Operator Notes page is a space dedicated to the electronic operator logs (notebooks). In spite of the page name, you have access to any notebook from this page. Notes are stored in a tamper-proof form and cannot be edited or deleted. You can however, add comments to notes to clarify the meaning, correct mistakes, or add additional information.

Notes can be added in the Operator Notes page, in the Alarm Page, in the HDV graph, and in the Notes tab of the HDV. You can also add widgets for note recording to any of your pages.
In all cases, notes are notes. The only variable is the choice of notebook.

Several notebooks are provided, but you can create any number that you need by adding new Notebook tags.

Operator Notes is the default notebook for the Operator Notes page. System Notes is the default for notes added in a trend window. Every alarm database has a matching notebook that will be used when an operator adds a note to an alarm record.

The Operator Notes page.

The time can be displayed either as an age (4 hours ago) or as a time and date (July 1, 2014, 14:01:04). An "update time" for a note shows when the most recent comment was added.

If a note seems to show two ages (4 hours ago * Added 2 hours ago) then it was created within an Historical Data Viewer graph. The first age shows the point on the graph where the note was placed, making it relevant to an event that occurred sometime in the past. The second age shows when the operator created the note.

Configure Quick Notes

A Quick Note is a named note stored within Notebook Tags that operators can add to their new notes. It might be a commonly used phrase, or it can be a template with blanks for the operators to fill in. Adding a Quick Note is similar to a copy & paste operation. The added note can be edited until they click the Add Note button to save it.

Quick Notes are created in a Notebook tag. Because there can be many Notebook tags matching many notebooks, you may have to duplicate Quick Notes if they should be available to more than one notebook.

Adding a Quick Note to the Notebook tag

As operators are typing their notes, they can click the Quick Note drop-down to select from a list of note titles. It is important for each title to be as descriptive as possible.

Selecting a Quick Note


Add Operator Notes

The ability to create notes is controlled by the Note Add security privilege.

Notes cannot be edited and they cannot be deleted. After being saved, notes become a permanent part of the application's history.
You can add comments to notes at any time, in order to clarify meaning, add detail or correct mistakes.

If the property, NoteAddRequiresAuthentication (NoteAddRequiresAuthentication) has been set in your application, then everyone will be required prove their identity when saving a note in spite of being currently signed in. This feature protects you from anyone who might create a note using your account while you are away from your workstation.

How you create a note depends on where you create a note. Your options are:

Add a note within the Operator Notes page

  1. Open the Operator Notes page.
  2. Select the correct notebook using the drop-down list at the top, left of the page.
    "Correct" depends on the procedures defined at your location.
  3. Click in the editing field, near the lower edge of the page.

  4. Type the text for the note.
    There is no limit to the size of a note. The text will wrap to fit the screen.
  5. Optionally, use the Insert a Quick Note button to select and copy a predefined phrase or template to the editing field.
    Text from quick notes can be edited until saved.
  6. Click the Post button to save your work.
  7. If prompted, enter your account name and password.
    You would only be prompted if security had been configured to require verification when creating notes.

Add a note within the HDV (trend graph)

  1. Ensure that at least one notebook is included in the legend.
    The System Notes notebook is included automatically when you open the HDV by left-clicking a tag. If you create your own selection of pens, you must remember to include a notebook.
  2. Click the Notes tool in the toolbar.
  3. Click on the graph, near the time for which the note is relevant.
    The Add Note dialog opens, confirming which notebook you are using.
  4. Enter your note, then click Add.

The note will appear like so:

Click the line to open a dialog where you can read the text or add comments.

Add a note to an alarm

There is no need to select a notebook. Notes automatically use the notebook belonging to the same Alarm Database as the alarm to which you are adding the note.

  1. Select an alarm in an alarm list. (Current, History, or any list)
  2. Click the Note tool in the toolbar, or right-click on the alarm line and select Add Note from the pop-up menu.

    The Add Note dialog opens, confirming which notebook you are using.
  3. Enter your note, then click Add.

Depending on the configured alarm list type, the note will appear as a notebook symbol to the right edge of the line.


Search for Notes

There are several ways to search for and view existing notes. The search is limited to the selected Notebook only.

Basic Search

Type any known word, phrase, or operator name into the search field, then press the Enter key on the keyboard. All notes and comments containing that text or created by that operator will be returned. Words from the search will be highlighted in the results.

Comments will be shown with an option to view the entire thread, which includes the original note and any other comments attached to it. This option is shown with the same highlight used to mark the search words.

The basic search will find matching text

Clear the Search Results

To return to the standard Operator Notes screen, which shows the most recent notes, click the X to the right of the search field.

Advanced Search

To search by date, operator name or other property, start by clicking the Advanced Search button:

The advanced search can find any note or comment

Each option that you specify in the Advanced Search dialog is treated as a requirement for the search. The result must have the text provided, and have been written in the specified date range and have been written by the specified user. Leave fields blank if you do not want to limit the search.

With this text:

Only notes that exactly match the text provided will be found. If you enter a series of words to search for, no notes will be found unless they contain exactly those words in exactly that order.

Spaces count. If searching for a phrase, and if the operator typed a double space between two words, your search must also have the double space in the same location.

You have the option of making the search case-sensitive. This can be useful if looking for only those notes that use the word at the beginning of a sentence.

In this month:

Provides a drop-down list of months within years. The list will extend to the date that the application first became operational. It is possible that some months will not contain notes, but they will still be included in the list.

In this date range:

Click the calendar icons to open date selectors. The date values are shown using the format YYYY-MM-DD.

The search option, "in this month:" will display the word [Custom] while you are searching a multi-month date range, unless you choose start and end dates within one month.

Choosing a start date

By this user:

Type the account name of the author of the notes you are looking for.

You can search for notes and comments by only one user at a time.


Export & Print Operator Notes

Creating a report of your notes is a matter of using the search to locate the notes you want, then either exporting or printing those. There are two options for printing Operator Notes: You may use the print button at the top of the VTScada screen to print the displayed portion of the screen, or you can export a range of notes to an HTML format for printing.

Export for printing.

  1. Use the search tools to limit the display to the notes that you want to print.
    All comments on the selected notes will be included in the export.
  2. Click the Export button.

    A Windows® dialog will open, prompting for the file name and folder to which to save the data.
  3. Accept the default file name and folder, or enter a new destination.
  4. Click the Save button.
    If the file already exists, you will be prompted to replace it, or you may return to the previous step and create a new file name.
  5. The file will be saved.
    Your default browser will be opened automatically, displaying the contents of the file.
  6. Print from your browser.

Print the current screen.

Comments will be printed only if they are expanded on the screen.

  1. Use the search tools to limit the display to the notes that you want to print.
    Only notes that fit on the screen will be printed using this method.
  2. Expand any comments that should be printed.
  3. Click the Print button at the top of the screen.
  4. Confirm that you want to print the currently displayed list of notes by clicking OK.

The notes will be sent to your default Windows™ system printer.

Troubleshooting:

  • Nothing shows up at the printer.

Check your Windows™ print control settings to ensure that the correct printer is set as default.

Review the screen to ensure that there are notes.


Configuration of Notes

You can control how notes are displayed and in what order. Click the gear icon at the top of the Operator Notes page to open the options dialog.

Note configuration options

Rather than limit the display to a given number of characters, the limit is for the number of pixels. The font size that you select, and the width of the characters within your note, will determine how many characters fit into that space.

The color selection tool

You also have control over the color used for the note. This will be used on the page for the title of the notebook, the name of the operator who created each note and comment, and for note markers in the Historical Data Viewer (HDV). Notebook color can also be controlled from the pen legend of the HDV.

Notes cannot be edited, but comments can be attached. The option to sort by most recently updated means that the date of the most recent comment on any note is used in place of the date of the original note itself. If a note does not have a comment, its original date is used.


Page Notes

Overview

Use Page Notes to add reminders on any VTScada page. (The ability to create and edit page notes is controlled by the security privilege, Page Note Edit.)

A note being created, then displayed on a page.

Page Notes are unique in that they can be added to any page, including the VTScada system pages such as Alarms and Reports. Nothing else in VTScada is so flexible in its location. Optionally, a note can be configured so that it is displayed on every page, throughout the application.

Also, unlike the text recorded in Operator Notes, Page Notes can be edited and deleted. (A permanent record is kept in the Event history, of who added, edited or deleted every note, and of the content of every note during its existence.)

If you hover the mouse over a note, you will see a tooltip telling you when the note was created and who wrote it.

Require acknowledgment of Page Notes

If you need a record that an operator has read a page note, you can "arm" it by clicking the check mark in the Edit Note dialog. When a note is armed, the next time that anyone clicks it, VTScada shows the following dialog:

Acknowledging an armed Page Note

Hide Page Notes

Notes and their background color cannot be made transparent and are always in the foreground of a page. This means that they will always hide whatever else was on the page, behind the note. A button at the top of the screen will hide or display all the notes on a page.

Hiding a page note is a temporary action

The act of switching to a different page, then coming back to the current one will cause all hidden page notes to display. VTScada assumes that the note exists to be read.

Disable Page Notes on a given workstation

Add the property, DisablePageNotes, setting it to 1 for specific workstations. Refer to Workstation-Specific Properties Workstation-Specific Properties

Appearance

The appearance of Page Notes can be adjusted in several ways: You can change the color of the text, the color of the background, the choice of text font, the size of the note and the style of the note border. These are all accessed by the properties button in the note editor.

Scaling

Page Notes scale with pages that have scaling enabled in Page Properties. The only exception is for notes with a scope of "All Pages in Application".

Page Notes with a scope of "This Page" or "All Pages of this Page Type" will change in size and position relative to a page as the page scales. Page Notes that can be seen globally, as they have a scope of "All Pages in the Application" do not scale and remain fixed, relative to the top left corner of the application window.

If you must use a global page note, do so strategically. Keep the note small so that it is not obstructive in applications and workstations that are scaled down. Position the note near the top left-hand corner of the application window to keep it within the field of visibility for all users.


Create a Page Note

The ability to create and edit page notes is controlled by the security privilege, Page Note Edit.

The following steps will guide you through the process of creating a page note.

  1. Click on the Add Page Note button:

The Edit Note dialog will open as shown:

  2. Click on the words "Sample note text" to activate the editing window.
  3. Click a second time to position the cursor on the sample text.

  4. Use the backspace or delete key to remove the sample text.
  5. Type your own note.
    Use the Enter key to write multi-line notes if needed.
  6. Drag the note into position on the screen.

Do this by clicking on, and then dragging the dialog box’s title area. You can also drag the edges of the dialog box to change the note’s width or height.

Page Notes must be fully inside a page. Also, you cannot save an empty note.
Try saving an empty note or a note that extends past the window edge in order to see the warning message.

  7. [Optional] Require operator acknowledgment of the note by clicking the green "Arm" check mark:
    A larger green check mark will appear on the note background area to indicate that it has been armed.
  8. Save the note by clicking on the Save button:

Troubleshooting:

  • VTScada will not save an empty note. Attempting to do so will result in the display of a warning, and the original text that was in the Edit Note dialog being re-inserted into the note.
  • In a networked application, when a note is saved, that page will be updated on all workstations. If someone on a different workstation saves a note to the same page that you are in the process of editing a note for, you will lose your edits as all notes are updated.


Hide a Page Note

The ability to hide page notes is controlled by the security privilege, Page Note Hide.

With one click of a button, you can hide all the notes on a page. This may be very useful when notes cover system controls or other display items. The Hide button is not visible when there are no page notes.

  1. Click on the Hide Page Note button.
  2. Click a second time to reveal the notes.

  3. Click again to hide the notes.
  4. Navigate to another page, then return to the page where your note is displayed.
    Your note should no longer be hidden.

VTScada assumes that page notes exist for a reason - hiding them is meant to be a temporary action.

The Hide Page Note button will only be displayed if there are Page Notes on the current page. If there is no Hide / Show Notes button, there are no notes on this page.

Troubleshooting:

  • The Hide Note button is disabled.

a) There are no Page Notes on the current page.

b) You do not have the security privilege required to hide the note. Check with your supervisor.


Edit a Page Note

The ability to create and edit page notes is controlled by the security privilege, Page Note Edit.

Pages notes are edited the same way that they are created - with the Edit Note dialog.

To open this dialog for an existing note, double-click on the note you want to edit. With the Edit Note dialog open, you can:

  • Move the note to a new location by dragging the dialog box.
  • Re-size the width and height of the note by dragging one edge of the dialog box.
  • Change the text of the note by clicking on the existing text, then typing a new message. A record of your new text will be saved in the VTScada events history.
  • Change the appearance of the note. See: Adjusting the Appearance of a Page Note for instructions.

Save your changes by clicking on the Save button:

VTScada will not save an empty note. Attempting to do so will result in the display of a warning, and the original text that was in the Edit Note dialog being re-inserted into the note.

Troubleshooting:

  • You are unable to access the properties, or delete the note.

Your security privileges do not include this ability. Check with your supervisor.

  • You erased the note text and now cannot save it.

VTScada will not save an empty note. Attempting to do so will result in the display of a warning, and the original text that was in the Edit Note dialog being re-inserted into the note.

  • Your work vanished.

In a networked application, when a note is saved, that page will be updated on all workstations. If someone on a different workstation saves a note to the same page that you are in the process of editing a note for, you will lose your edits as all notes are updated.


Delete a Page Note

The ability to create and edit page notes is controlled by the security privilege, Page Note Edit.

Page notes are different from operator notes in that they can be deleted.

  1. Double-click on the note you wish to delete.

The Edit Note dialog opens, providing you with a delete button.

  2. Click once on the delete button to immediately and permanently delete the note from the system.

A record of this action, including the text of the note that was deleted, will be added to the VTScada events history.

Troubleshooting:

  • You are unable to access the properties, or delete the note.

Your security privileges do not include this ability. Check with your supervisor.


Page Note Scope and Appearance

When you create page notes, each new note will have the same colors and other properties as the last unless you choose otherwise. This is done using the Page Note Properties dialog.

The Page Note Properties dialog is opened from within the Edit Note dialog:

Note Style

Select one of two styles: Note or Beveled.

Note, with its curled corner, is often the default.

Background Color

The background color is adjusted with a horizontal slider. Move the Properties dialog away from the note to see the background color being applied as you move the slider.

There are 6 available colors. Moving the slider from left to right will set the color to one of: Purple, pink, red, yellow, green or blue.

Font

The appearance of the text in the note is controlled by a font tag. The default is LabelFont. Click on the tag browser button to select one of the other fonts that have been configured for your application.

Text Color

Clicking on the Text Color button will open the VTScada Select Color dialog. Use this to set any color you want for the lettering of the note.

Scaling

Page Notes scale with pages that have scaling enabled in Page Properties. The only exception is for notes with a scope of "All Pages in Application". Those notes do not scale in size and their position remains relative to the top left corner of the application window.

Scope

This Page

Default option when placing a note. The note appears only on the current page.

All Pages of this Page Type

If the page has parameters, choose this option of you want the note to appear on every instance of that page regardless of how it was opened and which parameters are shown in the current instance. Do not select if the note should appear only on the current instance of the page.

All Pages in Application

Sometimes refered to as a global page note. The note appears on all pages, without exception. These notes do not scale or shift relative to a page with scaling enabled.

Troubleshooting

  • Page Note does not scale or move with a page.

    There are two possible causes-- the scope of the note or the version of VTScada on which the note originated.
    Check the Scope: Double-click on the note to edit it. Check to see if the Scope is "All Pages in Application". This is a globally visible configuration. Scaling in this mode is not supported by VTScada. Consider changing the scope or select the note size and position strategically. (If other workstations scale way down, keep the note as small as reasonably possible. Position global notes near the top left side of the application to keep them on screen.)
    Easily Update Note Version: Notes that originated on a version of VTScada that did not support note scaling will not scale until they are re-saved. Double-click on the note to edit and save it immediately. This will update the note.


Historical Data Viewer (HDV)

HDV Overview

VTScada makes it easy to view a trend plot of a tag's values over time. You need only left-click on an object that represents an input tag (analog or digital) to open a trend graph. Click more widgets to add more pens Closed Any data source displayed on the graph. This includes notebooks as well as analog and digital tags. to the graph or use the Tag Selector button within the HDV toolbar.

All Notebooks that have the same Area as the tag you select on screen will be included.
You can control this by changing the properties IncludeAreaNotesWithTrendedTags, and IncludeGroupNotesWithTrendedTags.
If using the Tag Selector tool within the HDV, only notebooks that you add will be included.

You can also use the following options to open or view the HDV:

  • The Historical Data Viewer Page, included in the Alarms, Reports and Diagnostics folder of the VTScada menu.
  • Draw a button or hotbox that will open a pre-configured HDV as a pop-up dialog. (HDV Button Widget, HDV Hotbox Widget)
  • Draw a miniature HDV on any page, configured as required. (Draw HDV Widget

Clicking a widget to open the HDV

Keyboard Shortcuts for the HDV

Key Combo | Description
Arrow Keys (Left/Right) | Pan backwards and forwards in time.
Shift + Arrow Keys (Left/Right) | Pan backwards and forwards in time in larger increments.
Ctrl + Minus sign (-) | Zoom out (x-axis).
Ctrl + Plus sign (+) | Zoom in (x-axis).
Ctrl + 0 or Ctrl + * | Return to live mode.
Esc | Exit selection choice in 'Pan & Zoom'

Troubleshooting:

  • Values are rounded to the nearest 1.

The I/O tag is configured for 0 decimal points. Open the tag's properties dialog and select the Display tab. Increase the decimal points to the value you want.

  • Unable to see plotted values in the graph.

Check pen configuration to ensure that all are being plotted with a visible line.

Check that there are values for the selected pens. If all values are a flat line at the top or bottom of the range, they may not be easily visible. If the tags are not logged, it may be necessary to reduce the time scale to see live values being plotted.

If security groups and realm-area filtering are configured, you may not have the right to view the selected pens.

Developers can configure tags and widgets so that the HDV does not open in response to a click. This many have been done for selected tags and widgets in your application.

  • The Historical Data Viewer doesn't open.

The developer may have disabled the trends feature for this tag. Check with your supervisor.

The item you clicked upon is not an input tag.

The ability to see the HDV is controlled by a security privilege that you may not have.

The HDV is already open but moved off to the side of the screen.

  • Another window opened in addition to the HDV, perhaps blocking your view.

Every object in the location where you click, will respond - not just the top-most tag. - Ask your developer to adjust the screen layout or use the full Historical Data Viewer window rather than clicking on this tag.

Daylight Savings Time vs. the HDV

Dealing with Daylight Savings Time:
VTScada records all data using UTC timestamps. In UTC, time advances at the rate of one second per second (barring leap-seconds) and if you were to plot your data against UTC time, you would see an uninterrupted line, assuming that your system is up and running, logging data.
Complications arise in places where daylight savings time (DST) is used. When DST starts in the spring, clocks jump forward from 2:00:00am to 3:00:00am. As far as UTC is concerned, data continues to be logged at the same rate, but if viewed on a graph that shows the local time, there will be a gap or a straight line showing no data for that hour. This is not a problem with VTScada. The gap exists because no time passed when the clock jumped forward, and therefore there is no data for that hour. Nothing can be shown.

Also, that day is 23 hours long, not 24, which may affect your reports. Again, this is not a problem with VTScada. According to your local clock, the DST-transition day had only 23 hours, therefore a daily report can include only 23 hours worth of data.

In the autumn, when daylight savings time ends, you can expect the same in reverse. It will appear that an hour's worth of data is over-written during the transition as the local clocks repeat that hour. That day is 25 hours long.

Rest assured that VTScada is faithfully and steadily recording your data, regardless of what your local clocks are doing.

Pause and Resume

If the tag is being logged, the graph can be scrolled to show historical information. If there is no saved data, then the graph will show only new values as they are being collected. The HDV makes it clear whether the plot is of live (current) or of historical values. While you are viewing live data, the pause button (following image) will look like any other button. While you are viewing only historical data, the button will be an arrow on a yellow background. Ctrl + 0 or Ctrl + * will also resume live mode if the HDV is paused.

Controls to pause and resume live data display

The Pen Legend

The pen legend, across the lower edge of the window, provides a color-key to the plot lines, value statistics for the time span shown and controls to hide a plot line or change its display characteristics. The Value column tracks the cursor position across the graph, showing the matching values as you move the cursor across the chart.

Besides being opened by a click on a widget, the HDV page can usually be found in the menu. Your application may also have shortcut buttons that link to the HDV, loading a preset group of pens.
When opening the HDV directly from the menu, you will need to select a set of tags to plot after the page opens. See: Select Pens (Tags) to Plot.

The HDV's features include the ability to plot multiple tags, save named groups for easy selection later, adjust the color, size and style of the graph lines, add notes, superimpose lines to mark alarm levels, view a table of the values, export, and much more.

Certain tasks described in this chapter require that you first select a pen. You can do so either by clicking the pen name in the legend, or by clicking once on a value in its scale legend, to the right or left of the graph.

Graphed Lines versus Logged Values

The Historical Data Viewer's plot display cannot show more data than there are pixels on your computer screen. For example, your display might have 1024 pixels across its width, of which 1000 or so are devoted to the display of the graph. If you are viewing a week's history for a tag that is logged every 10 seconds, there are 60480 records in the log file for the week. Each pixel on the graph must therefore represent approximately 60 logged values.

The following techniques are used to deal with this:

Analog Pens: Peaks and Averages

  • If the Plot Averages option is selected for a pen (tag) then for each pixel on the graph, the average of the logged values represented by that time span will be shown. If the Plot Peaks option is selected, then the minimum and the maximum values for the time span will both be shown, resulting in a banded plot. You can choose to plot Peaks and Averages at the same time.
  • You can control the default scale range for analog pens. The scale can be set in the tag configuration, within the pen properties, or allowed to float, automatically adjusting to the currently displayed values.

Digital Pens: Percentages

  • In the legend, "Average" refers to the percentage of the displayed time for which the tag was in state 1 ("On"), expressed as a decimal value.
  • In the grid view, when viewing averages over a time span that is greater than the logging rate, a % active value will show you what percentage of the logged values within that time span had a value of 1.

Averaged digital values as percentage of their time in state 1.

To view the history of actual on and off cycles, select the Raw Data option from the menu.


HDV Element Reference

Overview of the Historical Data Viewer (HDV) features.

Elements of the Historical Data Viewer

  • The Tool Bar. In order from left to right this provides access to the following tools.
    • Retrieve named pen groups.
    • Select what is to be plotted.
    • Export the displayed data.
    • Display a different length of time.
    • Display a different day.
    • Zoom in on a particular duration of the time frame.
    • Zoom out from the time frame.
    • Zoom in on the plot amplitude.
    • Zoom out from the plot amplitude.
    • Move one or more plots vertically.
    • Reset the vertical axis.
    • Separate Graphs.
    • Display a marker line at the cursor.
    • Hide Data Value - removes data value labels that you have added to the display.
    • Data Window Options. (Display tag value only or value plus one of short name, full name, or description.)
    • Adjust the text size.
      This steps through 5 sizes, changing both the main display and the title bar.
    • Add a note (select a Notebook pen first).
    • Print the displayed data.

The Pen Legend.

The pen legend appears across the bottom of the Historical Data Viewer page. It acts both as a guide to the pens that are plotting data on the graph, and as a means of displaying additional relevant data for each. An example of the pen legend is displayed here:

Analog plots are indicated in the pen legend by the [image] symbol, digital plots are indicated in the pen legend by the [image] symbol, and notebooks are indicated in the pen legend by the [image] symbol.

A pen that is selected in the pen legend will be highlighted in blue. To select a pen, click it in the legend or click an entry in its scale to the right or left of the graph. To deselect all pens, click the selected pen again.

There are columns for both analog and digital values. Where they do not apply to one type or the other, the entry will simply be blank.

Operators can move the cursor across the graph to see a the value of each tag for any time displayed. Note that this may be an average of several logged values covered by one pixel on the displayed graph, rather than each logged value.

  • Click the gear icon to open that pen's properties dialog.
  • Click the eye icon to hide or reveal that pen in the graph.


Select Pens (Tags) to Plot

Terms: Because the HDV displays a graph of tag data, tags are referred to as pens Closed Any data source displayed on the graph. This includes notebooks as well as analog and digital tags. in the selection. A named set of tags is referred to as a group.

If the HDV is opened as a pop-up page, you can quickly add more pens to the plot by clicking widgets on the original page. This technique is not convenient when the tags you want to plot are drawn on several pages, or when you want to save pen selections as named groups for easy retrieval in future. For these situations, use the Tag Selector dialog to add pens to and remove pens from the display. It provides filters that allow you to find tags quickly and you can create filter-based queries that automatically select all tags matching the filter.

Saving Pen Groups

After selecting pens, it is a very good idea to save that group, using a name that describes the selection (Pen Groups - Save Tag Selections). A list of your saved groups is always available in the HDV, for quick selection.

Saved groups are treated more like historical data than part of the application design. This means that they are not included in ChangeSets of the application.

For those using Realm Filtering, saved pen groups are tied to realms. Pen groups that you create while signed in within one security group are available only to members of the same security group.

To select pens:

Click on the Tag Selector button [image] to open the selection dialog.

Tags shown in the Tag Selection list can be added to the Selected Tags list by either of two methods:

  • Double-click on a tag to add it to the list
  • Click once on the tag, then once on the Select Tag button near the bottom of the dialog.

Instead of selecting tags, you can create a filter and save it using the Add Query button. This will select all the tags that match the filter.

Example HDV Tag Selector

Below the title is the Tag Selection area, headed by the option to Filter Tags or Create a Query. The filtering process is the same for both options.

Use the various Filter By fields to limit the display of tags to only those having matching names, areas, types, etc. Having filtered the list, you can either select individual tags from that list, or you can save the filter as a query to take all matching tags. A query can be especially useful on systems where new tags are constantly being created.

HDVMaxDataSources sets the maximum numbers of pens that will display on the HDV. It is important to note that "pen" refers to all data sources displayed on the graph and includes notebooks.

Remove a Pen or Query from the Selection

Tags can be removed from the Tag Selection list either one at a time or all at once.

To remove a single pen or query from the graph:

  1. If the tag selector dialog is not open, click the Tag Selector button to open it.
  2. Select the tag to be removed from the Selected Tags list (see image).

  3. Remove it by either double-click on the tag, or clicking on the Remove button.
  4. Click, Save Group.

The selected pen will no longer will be displayed on the Historical Data Viewer page's graph.

To remove everything from the list of Selected Tags, click the Remove All button.

Removing a pen from the HDV display (as opposed to the Tag Selection List) does not affect a saved group.

Troubleshooting:

  • Pens are still plotted

Changes were not saved. Click the Save Group button before exiting the tag selector.


Filter the Selection

When the Tag Selector dialog initially opens, it displays a list of all the tags in the application that could potentially be plotted. This may easily include thousands of tags.

Use filters in the Tag Selector to find the tags you want more quickly. Instructions follow. While instructions are provided for each type of filter individually, you may use several at once.

Filter Tags by Name

You may filter the list of tags by the unique name with which they have been configured (i.e. the Name property configured in the tag properties folder for each tag).

  1. Click the Tag Selector button appearing in the Historical Data Viewer page's tool bar.

The Tag Selector dialog will open.

  2. Enter one or more characters in the Filter by Name field.

You may use a combination of characters and the asterisk wildcard character (*) to locate a specific tag by its configured name (e.g. "130*" will find all tags whose name begins with "130" or "*B*" will locate all tags whose name contains the letter "B").

  3. Press the Enter key on your keyboard to input the search characters.

The tags matching the name or characters you entered will be displayed in the Tag Selection list. You may now plot the located tag(s) adding them to the Selected Tags/Queries for Plotting list.

To reset the Filter by Name field (thereby removing name filtering from the list), ensure that no characters are entered in it and then press the Enter key on your keyboard.

Filter Tags by Area

You may filter the list of available tags by the area with which they have been configured (i.e. the Area property configured in the tag properties folder for each tag).

  1. Click the Tag Selector button appearing in the Historical Data Viewer page's tool bar.

The Tag Selector dialog will open.

  2. Select the area by which you wish to filter the available tags in the Filter by Area drop-down list.

The tags matching the area you selected will be displayed in the Tag Selection list. You may now plot the located tags by adding them to the Selected Tags/Queries for Plotting list.

To reset the Filter by Area drop-down list (thereby removing area filtering from the list), select All.

Filter Tags by Description

You may filter the list of available tags by the description with which they have been configured (i.e. the Description property configured in the tag properties folder for each tag).

  1. Click the Tag Selector button appearing in the Historical Data Viewer page's tool bar.

The Tag Selector dialog will open.

  2. Enter one or more characters in the Filter by Description field. You may use a combination of characters and the asterisk wildcard character (*) to locate a specific tag by its configured description (e.g. "Well*" will find all tags whose description begins with "Well" or "*3*" will locate all tags whose description contains the number "3").
  3. Press the Enter key on your keyboard to input the search characters.

The tags matching the name or characters you entered will be displayed in the Tag Selection list. You may now plot the located tags by adding them to the Selected Tags/Queries for Plotting list.

To reset the Filter by Description field (thereby removing description filtering from the list), ensure that no characters are entered in it, and then press the Enter key on your keyboard.

Filter Tags by Their Data Source Type

You may filter the list of available tags by the type of data that they have been configured to read or write (i.e. analog, digital, or notebook).

  1. Click the Tag Selector button appearing in the Historical Data Viewer page's tool bar.

The Tag Selector dialog will open.

  2. Expand the Filter by Data Source Type drop-down list in the Filter Tags / Create Query section of the Tag Selector dialog.
  3. Select one of the following:
    • All: Display all data types.
    • AnalogDataSource: Display only those tags that read or write analog (continuous or decimal) data (e.g. "123.54" or "62.0") (i.e. analog input and analog output tags).
    • DigitalDataSource: Display only those tags that read or write digital (discrete) data (e.g. "1" or "0") (i.e. digital input and digital output tags).
    • NotesDataSource: Display only notebook tags.

The tags matching the data source type will be displayed in the Tag Selection list. You may now plot the located tags by adding them to the Selected Tags / Queries for Plotting list.

To reset the Filter by Data Source field (thereby removing description filtering from the list), select the option "All" from the list.

Filter Tags by Tag Type

You may filter the list of available tags by the their type (analog input, digital status, etc.) The list of tag types available will be influenced by the selected Data Source filter. For example, if you are filtering for only analog data source type, only analog tag types will be available for selection in the tag type filter.

  1. Click the Tag Selector button appearing in the Historical Data Viewer page's tool bar.

The Tag Selector dialog will open.

  2. Expand the Filter by Tag Type drop-down list in the Filter Tags / Create Query section of the Tag Selector dialog.
  3. Select one of the tag types.

The tags matching the data source type will be displayed in the Tag Selection list. You may now plot the located tags by adding them to the Selected Tags/Queries for Plotting list.

To reset the Filter by Tag Type drop-down list (thereby removing tag type filtering from the list), select All.


Using a Query to Select Tags

A query is a request for all tags that match a given criteria. It is saved as a text representation of the filter created using the fields at the top of the Tag Selector dialog.

For example, the following filter settings...

… can be saved as a query that will plot all the tags that match the selection filter. Be careful that this is not an excessive number of tags. The Preview button can be used to find out how many tags match the query before you attempt to plot them.

Queries are flexible. If new tags are added to the system that match the filter, you do not need to update the selected tag list - the query will find them the next time the HDV is used.

The steps to create a query are as follows:

  1. Open the Tag Selector dialog from the Historical Data Viewer.
  2. Define the filtering criteria using the fields in the Filter Tags/Create Query section of the Tag Selector.
  3. [optional] Click the Remove All button.

You can combine multiple queries or select both queries and sets of tags to get a list that is the sum of both. Again, avoid plots that include an excessive number of tags.


Pen Groups - Save Tag Selections

If user realms are in use, then the pen group you save will be available only to members of your security group.

You can create named selection groups of tags to plot. These groups are available for all users in a drop-down menu at the upper-left corner of the Historical Data Viewer. The ability to work with pen groups is controlled by the security privileges Group Modify, Group Save and Group Delete.

Notes:

Saved groups are treated more like historical data than part of the application design. This means that they are not included in ChangeSets of the application.

For those using Realm Filtering, saved groups are tied to realms. Pen groups that you create while signed in within one security realm are available only to members of the same security realm.

When you click on a group name from the menu, a preselected set of tags will be plotted on the graph.

The same feature is used by the HDV Button Widget. (HDV Button Widget)

Save a pen group:

  1. Open the Tag Selector from the Historical Data Viewer
  2. [optional] Define filters to reduce the length of the tag selection list
  3. Select tags from the list or click Add Query to save the filter as a query.
  4. Click the Save Group button.

The Save Group dialog will open.

  1. Enter a name for the new pen group in the Save Group field.
  2. Press the Enter key on your keyboard to input the new name.
  3. Click OK.

Troubleshooting:

  • Unable to use a particular name

Group names may not be numeric and may not contain most punctuation characters. Select a new name.

  • Group contains unwanted tags or is missing desired tags.

Groups can be edited. Add or remove tags are required, then save the group, using the current name.

Modify pen groups

After you have created a pen group, you can modify the tags belonging to it at any time.

  1. Expand the pen group drop-down list in the Historical Data Viewer page's tool bar (i.e. the drop-down list to the far left in the tool bar).
  2. Select the name of the pen group you wish to modify.
  3. Click the Tag Selector button.

The Tag Selector dialog will open, and the text Currently Editing <Pen Group Name> will appear in its title bar (where <Pen Group Name> is the name you configured for the selected pen group).

  4. Use the Select Tag and Remove Tag/Query buttons in the Tag Selector dialog to modify the Selected Tags list until it contains only the tags you wish to belong to the selected pen group.
  5. Click the Save Group button.

The Save Group dialog opens and displays the name of this pen group.

  6. Click OK to modify the referenced pen group.
  7. Click the Plot button to close the Tag Selector dialog and plot all pens belonging to the group on the graph on the Historical Data Viewer page.

Troubleshooting:

  • Wrong group selected for editing.

The tag selector's title will state the name of the group being edited.
If changes have been made to the wrong group and you have Version Control as part of your VTScada license, you may reverse the change. Otherwise, edit the groups to restore the pen selection.

Delete a pen group

To delete an existing pen group, provided that your account has the required security privilege:

  1. Expand the pen group drop-down list in the Historical Data Viewer page's tool bar (i.e. the drop-down list to the far left in the tool bar).
  2. Select the name of the pen group you wish to delete.
  3. Click the Tag Selector button.

The Tag Selector dialog will open, and the text Currently Editing <Pen Group Name> will appear in its title bar (where <Pen Group Name> is the name you configured for the selected pen group).

  4. Click the Delete Group button.

The Delete Group? dialog will open and request confirmation that you wish to delete that pen group.

  5. Click the Yes button.

The tags belonging to the selected pen group will be removed from the Selected Tags/Queries for Plotting list in the Tag Selector dialog.

  6. Click the Close button.

The Tag Selector dialog will close, and the tags belonging to the deleted pen group will removed from the graph on the Historical Data Viewer page.

Transferring Pen Groups

The following describes an advanced procedure. It should be used only by experienced VTScada developers.

Pen groups are stored in files under the Data\NetworkValues folder structure. These are not under version control and are not included in ChangeSets.

The pen group files are named using the pattern HistoricalDataViewer-Group-Group+ followed by the name of the group and related information. There will also be a file named HistoricalDataViewer+HistoricalDataViewer-GroupList.NVX You can copy these to another workstation where the application is installed.

  1. On the source workstation, create a copy of the files that match the patterns noted, then take or send that copy to the destination workstation. (All remaining steps are done on the destination computer.)
  2. On the destination workstation, stop the application.
  3. Delete the file \Data\NetworkValues\NetworkValues.Cache.
  4. Paste files you copied from the source computer into the Data\NetworkValues folder of the destination computer.
  5. Restart the application.

If the destination workstation had pen groups that were not on the source workstation, they will be lost when you over-write the GroupList file. Use this procedure only when the application is newly installed from a ChangeSet.


Show All, or Best-Fit Scales

You can control the scales shown on a pen-by-pen basis. By default, a full scale will be shown when there is only one analog pen in the graph. When two or more are displayed together, the display will switch to a best-fit option.

When the HDV must try to display more than just one full scale, it will automatically move some to the right side of the graph.

Configurable scale display options

Control the scale displayed, by pen: (Analog pens only.)

  1. Open the Properties dialog by clicking the gear icon in the legend.
  2. In the Analog Properties dialog, expand the Options list.
  3. Select between All, None or Best Fit.


HDV Grid as a Reporting Tool

Values that make up the Historical Data Viewer (HDV) graph can be viewed in a table by clicking the Grid tab at the bottom of the page.

Selecting the Grid tab.

The grid is a powerful tool for viewing a report of process values. You may choose to view raw values as logged or you can select averages, minimums or maximums over a given amount of time per record (row). Note that the list of available Time Per Record options will not include a value larger than the selected time span of the grid. Also, values that are significantly smaller than the displayed range will not be available.

As an example, you might configure the grid to display maximum values recorded in each fifteen-minute time span for the past day. For a finely-detailed report, you might configure the grid to show average values for each one-minute time span (or less) over the past week. Any combination that you configure may then be exported to a file for use in a report. A significant advantage to using averages over small time spans is that the time stamps will match for each tag's value, which will not be the case when exporting raw data.

Toolbar entries not labeled here are described in HDV Element Reference.

There is one column for every tag that was plotted in the HDV. Columns can be re-sized by clicking and dragging on the edges of their titles. Whenever the window is re-sized, all the columns will also re-size automatically in an attempt to display as much of each tag name as possible. A horizontal scroll bar may be added if any portion of the columns does not fit within the window area.

To re-order the columns, change their order in the tag selector.

Raw Values Data Retrieval Mode

If viewing raw values for more than one tag, you might notice that some entries are gray and some are black. Values tend to be logged a few milliseconds apart and sorting of the rows is done by timestamp. For each row, there will be at least one entry in black, showing the value logged at that timestamp. Rather than leave other columns blank, their last logged value is carried forward, but shown in gray.

When exporting raw data, timestamps are truncated to the nearest second. If greater accuracy is required, use a standard report. Reports Page

Raw data example showing millisecond differences between logging events.

Average, Minimum or Maximum Data Retrieval Mode

For each tag, all logged values within the chosen Time per Record will be used for the selected calculation. The result will be evenly-spaced time intervals with a calculated value for every tag at each time interval.

Averaged Values and Digital Tags

When viewing averaged values, Digital tags will periodically display a message such as "99.8% Active". This is the percentage of the non-zero, logged values for the time period covered by that row.


Add a Note to the Graph

Notes added the graph, can provide context for the values displayed. For example, someone looking at a graph of a holding pond's level may wonder why it suddenly rose, three weeks earlier. If the operator on duty at the time had added a note about the thunderstorm that filled the pond, then the mystery would be solved.

Notes added to the graph are linked to whatever point in time you choose, and a marker is added to that graph at that point. Use this to link notes to events, for example explaining why a level suddenly rose. Within the Notes database, the actual time of creation is also stored in addition to the apparent time. On the Operator Notes page, both the time to which the note is linked, and the time of creation will be displayed.

You can also choose to open the Notes tab of the HDV, which is simply another view of the Operator Notes page with its full range of features.

Notes are saved in a notebook - a pen (notebook tag) that must be selected before the Post button can be used. If only one notebook pen is included in the legend, then it is not necessary to select it before adding a note.

Available Notebooks:

VTScada uses the following rules to add notebooks to the legend:

  • If you open the HDV for a selected tag (by clicking on a widget or using the Plot command from the Alarm page or Tag Browser) then the System Notes notebook is included automatically.
  • If there is a Notebook tag that has the same Area property as the selected tag, then that will open as well.
  • If the selected tag is also a member of a saved group (Pen Groups - Save Tag Selections) and if that group includes a notebook other than System Notes, that will open as well.
  • If you use the HDV tag selector to choose which tags to plot, you must also select one or more notebooks. None will be added automatically in this case.

Troubleshooting:

  • An error message tells you to select a Notebook pen.

Choose a notebook tag from the legend. This tag provides the mechanism to save and retrieve notes.

  • There is no notebook pen to select in the pen legend.

Use the Tag Selector button to find and add a Notebook tag to the list.


Add Value Labels to the Graph

Since the Historical Data Viewer's vertical scale shows only the minimum and maximum values, it can sometimes be difficult to read a value between these limits. Adding value labels to the graph removes this problem by showing the value(*) at the selected point in time.

(*) Note that this is the graphed value, not necessarily a logged value. Graphed values are the average of all data points under a selected pixel.

The content of the label is controlled by the adjacent tool, Data Window Options:

The label will include the tag value in all cases. You can choose to add any one of Short Name, Full Name, or Description.

To add a label:

  1. Select an analog pen by clicking on it in the legend area.
  2. Click on the graph, lining up the cursor with the moment in time at which you want to display the tag's value.

A label will be displayed, with a line marking the point in time.

To remove a label:

There are three ways to remove labels. Each is a one-step process.

  • Click on an existing label. It will be removed from the plot.
  • Click the Hide Data Value button. All labels will be removed from the plot.

  • Close the HDV window and re-open it. Labels are temporary markers, not permanent additions to the plot. All are removed when the page is closed.

Troubleshooting:

  • The label does not appear.

- An analog pen must be selected in the legend before a label can be added.

- Control buttons at the top of the HDV such as Zoom-Out or Shift-Y-Axis will interfere with this process. Ensure that none of these are selected.


Change the Displayed Time Span

When the Historical Data Viewer (HDV) opens and tags are selected, the display is of live data - that is, a constantly updating display of values as they are being collected.

You may wish to adjust the displayed time span to show a greater or shorter length of time. If the values are being logged, then you can also change the displayed time to review historical values. Most of the tools that you will need can be found in the toolbar at the top of the HDV page.

Change the displayed start date:

  1. Click the Set Start Date button.
  2. Use the single arrow buttons to move backwards and forwards through the months, the double arrows to move a year at a time, click the date to switch to a month selector.

  3. Click on the date for which you want to start viewing logged data.

The calendar closes, and the date you selected is displayed below the graph.

Change the span of time displayed (method 1):

  1. Click the duration drop-down list. (To the immediate left of the Select Start Date button.)

  2. Select a time duration from the list

Change the span of time displayed (method 2):

The Zoom in X-axis and the Zoom out X-axis buttons combine two steps in one. The first is exactly the same as using the time span selector - each change in time span made using these buttons is the same as selecting the next duration from the list. The second function is that they scroll the history display to center the time that you click within the time span window.

  1. Click either the Zoom in X-axis or Zoom out X-axis button to active the control.

  2. Click on the graph to change the displayed duration and re-center the graph.

Scroll to view earlier or later dates:

The scroll bar below the graph can be used to view earlier or later dates. Click on the left and right arrows, or drag the indicator.

Reset the graph to the current date:

If you are not viewing current / live values, then the indicator to the left of the calendar button will be highlighted. Click the button to return the graph to the current time and live updates.


Adjust the Plot

There are several ways that you can adjust scale and placement of pens in the HDV graph.

Change the vertical scale

(Does not apply to digital tags.)

You can control the default scale range for analog pens. The scale can be set in the tag configuration, within the pen properties, or allowed to float, automatically adjusting to the currently displayed values. See: Analog Pen Property Reference

For a given time span, an analog tag's value may not change significantly compared to the full scale range. By changing the displayed scale ("zoom-in" or "zoom-out"), you can increase the amount of information available.

For example, the following two images show the same information, but in the second, the displayed vertical scale has been adjusted to show values from 500 to 1000 instead of 0 to 1500.

For the following instructions, if a tag is selected in the legend, the action will apply only to its pen Closed Any data source displayed on the graph. This includes notebooks as well as analog and digital tags.. Otherwise, the action will apply to all the pens.

To change the vertical scale:

  1. Decide whether to scale one pen or all pens
  • If one pen, select that pen in the legend.
  • If all pens, select no pens in the legend. Click on any that are selected, to deselect them.
  2. Decide whether you want to view a smaller scale range (zoom in) or a greater scale range (zoom out).
  • If a smaller scale range, click the Zoom In Y-Axis button.
  • If a larger scale range, click the Zoom Out Y-Axis button.
  3. Click on the analog graph.
  4. Each click on the graph while the Zoom In or Zoom Out button is selected will take you one step further in or out.

Troubleshooting:

  • You have zoomed too far and lost the pen.

Click the Reset Y button.

Shift a pen up or down

(Does not apply to digital tags.)

When plotting several tags, you may want to shift the position of one or more of the pens to either separate the graphs for clarity, or to superimpose them for comparison.

To shift a pen position:

  1. Decide whether to shift one pen or all pens.
  • If one pen, select that pen in the legend.
  • If all pens, select no pens in the legend. Click on a selected pen to deselect it.
  2. Click on the Shift Y-Axis button.
  3. Click on the graph and, while holding the left mouse button down, drag the pen display up or down.

Remove or hide pens in the HDV

When several pens are plotted on the same graph, you may want to hide one or more temporarily so that you can better view the remaining pens. Alternatively, you may want to remove the pen altogether.

To hide a pen:

  1. Click the eye icon beside that pen's entry in the legend.

The pen will be removed from the graph and the legend entry will turn gray to indicate that the pen is hidden.

To reveal a hidden pen:

  1. Click the eye icon a second time.

To remove a pen:

  1. Click the X icon beside that pen's entry in the legend.

    The pen will be removed from the graph and from the legend. If you were viewing a named group of pens, then you are now viewing an unnamed group.

To return the pen to the plot, either select it again, or change the group list to re-select the named group you were previously viewing.

Separate the graphs

When more than one pen is being plotted, the overlapping lines may be difficult to see. Rather than shift a pen up or down, you can also separate the pens into their own graphs at the click of a button. Note that this applies to only analog plots.

To separate analog graphs:

  1. Click the Separate Graphs button.
  2. Click again to merge the pens into a single graph.

Note that separating a large number of graphs may result in a very small display area for each.

Reset the scale and position

(Does not apply to digital tags.)

If you have adjusted the graph's scale or vertical position, you may decide that you want to return to the default display. This can be done for either a single pen, or for all pens using the Reset Button.

This operation applies only to vertical adjustments. There is no default for the horizontal scale (displayed time span) of the graph. Also, changes that you have made to color, line style and other properties are not affected.

To reset the scale range:

  1. Decide whether to reset one pen or all pens
  • If one pen, select that pen in the legend.
  • If all pens, select no pens in the legend.
  2. Click on the Reset button.


Change Pen Styles

The Historical Data Viewer (HDV) chooses a unique color for each pen Closed Any data source displayed on the graph. This includes notebooks as well as analog and digital tags. used to plot a tag's values. Thin, solid lines are used, and each tag's plot will be adjusted so that the full range of scaled values fits within the window - with no regard to how that might overlap another tag's plot.

You may decide to emphasize one or more pens by selecting a color with greater contrast, setting a thicker line width or a different line style.

You can include more information in a plot by adding lines to show alarm set points - and thereby emphasize when the tag's values went into an alarm state. You can include peaks and averages, add value labels at key positions, scale the display, select extra information to include in the legend, and even change the graph's scale to be logarithmic.

A variety of pen weights and styles

In all cases, adjustments are made by opening the pen's Properties dialog, which gives access to the full set of pen configuration controls. The legend configuration for each pen is remembered and used each time the associated tag is plotted in any instance of the Historical Data Viewer, regardless of how that instance is opened.

To open the properties dialog, do either of the following:

  • Double-click the pen's entry in the legend.
  • Click the gear icon for that pen's entry in the legend.


Analog Pen Property Reference

The appearance of the pens that are used to display analog plots can be adjusted as follows:

  • Double-click the pen in the legend, or click the gear icon to open the properties dialog.

Analog Pen Properties Element | Description
Scale Range
Use System Default

Selected by default. Applies the value stored in application property, HDVAnalogPenAutoScaling.

The default of HDVAnalogPenAutoScaling will vary depending on whether this is a new application or a legacy application created before the release of VTScada version 11.2.22. In legacy applications, auto-scales were not available therefore the default behavior is that they are not used. In new applications, auto-scaling is the default.

This option must be deselected to use any of the following:

Track Tag Scales | Select this option to have the graph display the scale range defined in the tag.
Manual Scales | Select this option to set the scale range within this dialog using the Min and Max boxes.
Min & Max | The range of the displayed scale. If the Manual Scales option is selected, then you can use these fields to provide your own scale range for the tag. Otherwise, these fields are display-only, showing the scale range currently in effect.
Auto Scales | Causes the scale to change according to the displayed values of the tag. See also, Ratcheting.
Ratcheting

An option used in combination with Auto Scales. If selected, the maximum scale value will increase as required to display the maximum value of the tag, and will not decrease. The minimum scale value will decrease as required to display the minimum value of the tag and will not increase. See also, Reset Ratcheting Scales button.

If this option not selected, both values will increase or decrease periodically according to the minimum and maximum tag values within the displayed time on the graph.

Reset Ratcheting Scales Button | Available only when Auto Scales is selected and ratcheting enabled. Causes the scales to be recalculated for the current display on the graph.
Scale Style
Scale Display Choose whether to display a full scale (all scales), a best fit scale or no scale.
Scaling Type | Select one of the three possible graph types: Linear, Logarithmic, Square Root.
Pen Color & Style
Use Tag Display Parameters For analog I/O and Calculation tags. Enabled only when selected, color and style parameters are configured in the tag.
Deselect to override the tag's configuration with values set here.
Color | Opens the Select Color palette, which you can use to select a new color for the pen.
Pen Style | A spin-box that you can use to change the line style (solid, dashed, etc.). Affects the choice of width, in that you cannot select a wide line for any style other than solid.
Display as a step plot | Intended for I/O and Calculation tags configured in the Discrete data type. The line drawn from point to point will not be sloped. Changes in value will be practically vertical with horizontal plateaus, hence, 'steps'.
Width A spin-box that you can use to set the width of the pen.
Affects the choice of style, in that choosing a wider line forces the line style to be solid.
Show Pen | Hides this tag's pen when not checked.
Show Alarms | Add horizontal lines to the graph that show the current value of alarm set-points associated with this tag.
Plot Peaks When each pixel represents several logged values, the graph is normally an average of the values represented by each pixel.
If Plot Peaks is selected, then two lines will be drawn - one for the maximum of those values covered by a pixel and one for the minimum. See also, Plot Average
Plot Average | The normal graph through for a pen - each pixel shows the average of the logged values represented by a pixel since there are usually more logged values than displayed pixels over a time span. See also, Plot Peaks.


Digital Pen Property Reference

The appearance of the pens that are used to display digital plots can be adjusted as follows:

  • Double-click the entry, or click the gear icon to open the properties dialog.

Digital Pen Properties Element | Description
Min & Max | The range of the displayed scale. 0 and 1 for most digitals, but may be set 0 to 3 for two-bit digital inputs.
Show Scales | Select whether the minimum and maximum scale values are to display along the Y-axis of the graph.
Color | Opens the Select Color palette, which you can use to select a new color for the pen.
Style | A spin-box that you can use to change the line style (solid, dashed, etc.). Affects the choice of width, in that you cannot select a wide line for any style other than solid.
Width | A spin-box that you can use to set the width of the pen. Affects the choice of style, in that choosing a wider line forces the line style to be solid.
Show Pen | Hides this tag's pen when not checked.
Average | Affects the legend display. If checked, the average of all plotted values across the displayed time span will be calculated for the tag.


Notebook Pen Property Reference

The appearance of the markers, placed on the graph when you add a note, can be adjusted as follows:

  • Double-click the entry, or click the gear icon to open the properties dialog.

Digital Pen Properties Element | Description
Show Pen | Hides this tag's pen when not checked.
Show Marker Line | When checked, the note's placement on the graph is shown with both an arrow and a vertical line. Deselect to remove the vertical line.
Color | Opens the Select Color palette, which you can use to select a new color for the pen.
Style | A spin-box that you can use to change the line style (solid, dashed, etc.). Affects the choice of width, in that you cannot select a wide line for any style other than solid.
Width | A spin-box that you can use to set the width of the pen. Affects the choice of style, in that choosing a wider line forces the line style to be solid.


Export HDV Values

The export button will send values displayed in the graph or grid to a file type of your choice. What is exported depends on what you are viewing, as per the following note.

Graphed values are not necessarily the same as logged values.
If exporting from the plot, values will be averages of the data values covered by each screen pixel.
If exporting from the grid, values will be averages, minimums, maximums or raw data depending on your choice of data retrieval mode.

If generating a file using the VTScada Anywhere Client, it will be transferred to your browser automatically. Check your browser's download history. (Will vary by browser.)
Only text files can be generated by a thin client, not spreadsheet or database files.
Similarly, Excel templates cannot be used when reporting via a thin client.

This applies to report generation, HDV exports, note exports, ChangeSet creation, and tag exports.
You cannot view a generated file (such as a report) within the Anywhere Client. The client shows only the VTScada user interface.

Adjust the time span to change the range of dates included in the export. Only the values in the current HDV display are exported.

The values can be exported to any of the following formats.

  • Access Database.
  • Excel Spreadsheet.
  • CSV File (Comma separated values in a text file.)
  • ODBC Compliant Data Source.
    Details will depend on the destination.

If exporting more than one tag, you will have the choice of exporting each to separate worksheets / database tables / files, or to merge all together.

If merging several tags to a single file or worksheet, and if exporting raw values from the grid view, the result will be a sparse table. There will be a row for every logged timestamp, but not every tag will have been logged at that exact moment in time.

Troubleshooting:

  • Error "General warning. Unable to open registry key 'Temporary (volatile) Jet DSN ..."

VTScada is running in an account that does not have sufficient permissions for the ODBC process. Adjust permissions for this account or use an account with a greater permission level.


Reports Page

You can generate reports using a variety of reporting formats provided with VTScada. In most cases, you will use the Reports page (a standard part of every VTScada application), but your application may have been created to generate reports automatically, or there may be buttons that you can press to create a predefined report on demand. This chapter describes how to use the Reports page. If other options exist, they will have been customized for your application - see your supervisor or VTScada Developer for more information about them.

VTScada provides an extensive set of tools for reporting, of which the Reports page is only one.

Report Page Features

The VTScada Report Page

The preceding figure shows the VTScada Reports page. Sections within the page are numbered to help guide you through the report generation process (1. Report type, 2. Tag List…) No options exist in this screen to allow you to design new types of report, but you do have a great deal of flexibility in deciding what to include in any of the built-in reports.

In general, you will create reports by stepping through the numbered sections. See Steps to Run a Report for detailed instructions.

1) Selection of report type. (See following table.)

2) Tag List. Filters and other tools for choosing the tags that will be reported on.

3) Reporting Period. Choose one of the predefined periods or use the controls to set a specific start and end time.

Scheduled reports: Use Report tags to create these (Report Tags). The Reports Page will only create reports on demand.

4) Number of consecutive periods. After setting a report period, you can generate a series of reports, each for the same length of time, but for consecutive periods extending back in time. For example, seven consecutive one-day reports rather than one seven-day report.

5) Report Destination. Select from ten options for where the report will be sent or displayed after it has been generated. (See Report Formats and Destinations)

If generating a file using the VTScada Anywhere Client, it will be transferred to your browser automatically. Check your browser's download history. (Will vary by browser.)
Only text files can be generated by a thin client, not spreadsheet or database files.
Similarly, Excel templates cannot be used when reporting via a thin client.

This applies to report generation, HDV exports, note exports, ChangeSet creation, and tag exports.
You cannot view a generated file (such as a report) within the Anywhere Client. The client shows only the VTScada user interface.

6) Other Report Options. Refinements that may be applied to some of the report destination choices.

The first option is to send a report to Excel, if available. The second and third options apply if previous periods are being generated (step 4) and the output is going to either Excel or Access format. Using separate sheets or tables for each iteration keeps the consecutive periods independent. If the Rename option is selected, you will be prompted for names when the report runs.

When running VTScada as a Windows service, DO NOT select Excel as an output destination or option from a Report Tag. As noted in the MSDN forums, office applications assume they are being run under an interactive desktop. If Excel attempts to open a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog from a non-interactive service, the result is an invisible dialog that cannot be dismissed, stopping the thread.

Besides the technical problems, you must also consider licensing issues. Microsoft's licensing guidelines prevent Office applications from being used on a server to service client requests, unless those clients themselves have licensed copies of Office. Using server-side Automation to provide Office functionality to unlicensed workstations is not covered by Microsoft's End User License Agreement (EULA).

Built-In Report Types

Refer to the reference chapter: Report Types Described

Daily snapshot report | The value of selected tags at a particular time each day throughout the report period.
Daily total report The sum of the values accumulated daily by each member of a selected set of tags within the time period you specify.
Do not use with analogs that measure fluctuating values such as flow rates or levels. This report is to be used with values that are incrementing over a time period.
For example, where the RTU or PLC includes a counter that increments whenever an event occurs such as a pump start or rain-gauge tip. These counters are finite and will reset to zero when the maximum value is reached on the device. This report will recognize a reset event and calculate for it.
Driver communication error detail report | A summary of error activity for a specified time period. Further information about these values is included in the VTScada documentation. (See Communication Driver Log-Enabled Variables.)
Driver communication summary report | A summary of driver activity for a specified time period, including response times, data quality, etc. Further information about these values is included in the VTScada documentation. (See Communication Driver Log-Enabled Variables.)
Hourly snapshot report | A snapshot of the value of each tag in a selected set of loggers at each hour within a specified time period.
Hourly total report The sum of the values accumulated hourly by each of a selected set of tags within the time period you specify. Do not use with analogs that measure fluctuating values such as flow rates or levels.
This report is to be used with values that are incrementing over a time period. For example, where the RTU or PLC includes a counter that increments whenever an event occurs such as a pump start or rain-gauge tip. These counters are finite and will reset to zero when the maximum value is reached on the device. This report will recognize a reset event and calculate for it.
Standard report | Raw data, as recorded from the selected tags. Note that for every timestamp in the report, there will be an entry for each selected tag, even though only one was likely to have saved a value at a particular timestamp. All other tags show the last recorded value prior to the given timestamp.
Analog summary report Displays the average, minimum, maximum, and total values for a set of selected analog tags within a configured time period.
When using this report to summarize flow data, set the Application Property, AnalogSummaryReportTimeUnits to the time unit used to measure the flow. If flow is measured in units per second, the property must be set to 1. If flow is measured in units per minute, the property must be set to 60.
Derived flow report Displays the number of cycles for a driver, along with the inflow, outflow, and total flow for the station. For this report, the tag selection area will be filtered to include drivers.
The report must be run on a Polling Driver or Data Flow RTU, with at least one Pump Status tag. Tied to the Polling Driver, there must be an Analog Status with a description of "Well Volume" measured in gallons, that the well pumps in each cycle. This is usually the volume between the lead and stop float switches. This data must be entered in the manual data field of the Analog Status tag.
Detail report Shows the values recorded for each selected tag, within the given time period.
For Digital Status tags, if the Off Text / On Text parameters are configured, those values are shown rather than 0 and 1.
Email Excel Template

Available only to applications built on the The Oil & Gas Solutions Layer.

Overall Total The sum of the values accumulated by each of a selected set of tags within the time period you specify. Do not use with analogs that measure fluctuating values such as flow rates or levels.
This report is to be used with values that are incrementing over a time period. For example, where the RTU or PLC includes a counter that increments whenever an event occurs such as a pump start or rain-gauge tip. These counters are finite and will reset to zero when the maximum value is reached on the device. This report will recognize a reset event and calculate for it.
Pump activity report

Displays data for the pump status tags in your application, enabling you to determine overall pump activity. Data includes count of pump starts, average run time, and total run time. The filter is set to I/O tags with the Pump equipment type, but may also use Pump Status and Digital Status tags.

The pump activity and pump discrepancy reports will by default sort the tags being reported by Station Number and then by description alphabetically. To have the tags reported in the order provided to the report, set the property PumpReportSortPumps to 0.

Pump discrepancy report | Similar to the pump status report, but organized to allow you to analyze for inconsistencies. This report is designed to help you spot instances of pumps that should be identical in behavior, but are not. This report shows only the pumps that have a 20% or greater difference in running time or have more than 1 start count difference.
Rainfall report | Must be used with a DFS or Polling driver. Displays a per-tag summary of totals within the time period configured for the report, enabling you to determine the total rainfall for selected tags in a given period. The most common configuration is to use a Data Flow Pulse Input tag where each pulse recorded from the rainfall measuring equipment signifies a predefined depth measurement.


Steps to Run a Report

The report page is organized into numbered sections, indicating the steps required to configure and run a report. For each step, there are several decisions to make.

Steps will vary depending on whether you are running a scripted report or a studio report.

The generalized steps are as follows:

Analytics, analysis, analyze

1. Select the type of report to create.

Detail of the Report Type drop-down list

For the list of options, see: Report Types Described

2. Select the tags to include.

The types of tag available for selection will be limited by your choice of report type. You can use the Areas selector to further filter the list.

Use the arrow buttons to move tags from the list of those available to the list of those selected.

This task is much easier if the tag selection is saved, to be loaded the next time the report is run.

Detail: Selecting tags for a report

After selecting tags, you should save the set as a named group, to avoid repeating work the next time that you run the report. Saved groups are required when creating Report Tags. (Report Tags)

Save a Tag Group.

  1. Select the tags to be included by moving them from the Tags Available list to the Tags In Report list.
  2. Click the Save Group button.
    The Select Group Name dialog opens.
  3. Either type a descriptive name for the tag group in the Group name field, or select an existing group name to update with the new tag selection.
  4. Press tab or click out of the field to enable OK. Click OK.

Groups are saved to *.GRP files in your application's ReportGroups folder. They will be included in ChangeSets.

Load a Tag Group:

  1. Click the Load Group button on the Reports page.
    The Select Group Name dialog opens.
  2. Select the tag group you wish to load.
  3. Click on the down arrow in the Group Name area, or start typing the name of the group you want.
  4. Click OK.

The tags belonging to the tag group are placed in the Tags In Report list.

When you load a tag group, those tags replace any that were already in the "Tags In Report" list.

Sorting

Tags are sorted in alphabetic order, but you have the option to change the order as desired by deselecting the Sort Alphabetically option, then using the arrows to move selected tags up or down in the list.

Detail: Sorting the list of tags

3. Select the report's time span.

Detail: Setting the reporting period

An extensive list of preset time-periods is available. In almost all cases, you will be able to find one that matches what is required for the report. For a list, see: Preset Time Periods for Reports.

Presets set the start and end time, relative to when you change the choice of preset. If you run a report for the "Last 4 hours before trigger time", then wait an hour and run the report again, the start and end times will not change.

In the case that there isn't a preset for the time span required, you can generate your own using the Start Time and End Time controls provided.

a) Click the calendar button to open a date-selection calendar. (If you wish to report on a time span prior to today.)

Detail: The calendar tool

b) Use the up-down arrows in the time fields to set the hour and minutes, or type directly in the time fields.

Note that you cannot set an end prior to the start.

4. Choose whether to repeat the report for multiple iterations of that time span.

Detail: Setting the number of previous periods

Leaving this field blank is the same as specifying "1 time period". Any larger value will cause the report to repeat for consecutive time periods of the same length set in step 3, where each iteration is for an earlier (previous) span of time.

Options in step 6 allow you to control how these iterations are included in the report output.

5. Select the output format and destination.

The drop-down list provides the main list of Report Formats and Destinations. Both are controlled here, where the list includes combinations of each.

Legacy report formats include:

  • CSV file
  • Text file,
  • Excel-compatible spreadsheet (several options)
  • Access MDB file, or other ODBC database.

Destinations include screen, printer, email and file on disk. The choice of destination affects the choice of format and vice-versa.

Detail: Setting the report destination

If an email server has been defined, you can choose to send most formats by email. The settings dialog will prompt for a From address, a Subject and a To address. Email addresses may be in the basic form, Name@Company.Com" or you may use either of the following longer forms. Multiple addresses may be entered, separated by semi-colons or commas. Do not add spaces within the angle brackets.
"Full Name" <Name@company.com>
-or-
Full Name <Name@company.com>

When running VTScada as a Windows service, DO NOT select Excel as an output destination or option from a Report Tag. As noted in the MSDN forums, office applications assume they are being run under an interactive desktop. If Excel attempts to open a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog from a non-interactive service, the result is an invisible dialog that cannot be dismissed, stopping the thread.

Besides the technical problems, you must also consider licensing issues. Microsoft's licensing guidelines prevent Office applications from being used on a server to service client requests, unless those clients themselves have licensed copies of Office. Using server-side Automation to provide Office functionality to unlicensed workstations is not covered by Microsoft's End User License Agreement (EULA).

6. Optionally, fine-tune the output format.

Detail: Selection of report options

The first option applies if you have chosen to output the report to the screen. If not selected, a plain text file format is used.

The second and third options apply if previous periods are being generated (step 4) and the output is going to either Excel or Access format. Using separate sheets or tables for each iteration keeps the consecutive periods independent. If the Rename option is selected, you will be prompted for names when the report runs.

7. Click the Run button to generate the report.

A progress dialog will be shown while the report is being generated. In most cases, you will likely want to select the option, "Close this dialog when the report is complete" so that you do not need to close it after every report runs.

The report progress dialog

If the output uses a Microsoft Excel™ file, and you have an older version of that program using the XLS file format, you may be limited to 255 columns (tags) in your report. Modern versions of Excel, using the XLSX format will support up to 16383 columns.
VTScada will automatically detect the installed version and produce an output file using the format it supports, XLS or XLSX


Report Formats and Destinations

The list of available output types (meaning both formats and destinations) depends on whether you are running a legacy report or a studio report. For each, there may be additional options and decisions to make.

Note for VTScada developers: Before you can assign an email destination for a report, you must configure VTScada so that it can access an email server. See: Email Setup for Alarms and Reports.

If running a report from a thin client, or if you are using an Excel output format, refer to the notes at the end of this topic before running your report.

Text file

  • Formatting is plain but easily read.
  • Will be saved to a file on disk. You must provide the name and folder location for the file.
  • May also be sent to an email address, either included in the body of the email, or as an attachment.

Sample text report

CSV file

  • CSV = Comma Separated Values.
  • The first row contains titles, remaining rows are enclosed in quotation marks and separated by commas. The formatting is designed to be imported into a spreadsheet or other program rather than read directly.
  • Will be saved to a file on disk. You must provide the name and folder location for the file.
  • May also be sent to an email address, as an attached file.

Sample csv report

Formatted Excel™ spreadsheet file

  • A header row is included in addition to the title row.
  • Formatting consists of the header & title rows being displayed with a bold font.
  • The worksheet will be named automatically using a timestamp.
  • Will be saved to a file on disk. You must provide the name and folder location for the file.
  • May also be sent to an email address, as an attached file.

Sample Excel report

Plain Excel™ spreadsheet file

  • Title row uses the same font as the rest of the report.
  • The worksheet will be named automatically using a timestamp.
  • Will be saved to a file on disk. You must provide the name and folder location for the file.
  • May also be sent to an email address, as an attached file.

Access™ MDB database file

  • The table name within the database is created automatically using a timestamp.
  • Will be saved to a file on disk. You must provide the name and folder location for the file.
  • May also be sent to an email address, as an attached file.

Sample Access report

An ODBC database, as specified in your Windows™ configuration

  • You must provide a DSN - Data Source Name for your ODBC connection.
    This is configured in the Microsoft Windows™ ODBC Manager tool, outside of VTScada. Ask your local IT department for details.
  • Cannot be sent by email.
  • The storage location is determined by your ODBC-compatible program.
  • Formatting and appearance is similar to that of the Excel or Access output.

Report Destinations:

Screen display

If the report is being sent directly to your screen, it may be formatted as plain text or displayed using Excel (assuming that you have Excel installed and activated on the workstation).

For legacy reports only, you may also choose your own macro-enabled Excel Template to use for formatting. This opens the possibility of applying customized formatting and using macros within Excel to perform any calculation that might be useful.

A file on disk

This is the inevitable result of choosing any of CSV File, Formatted (or not) Excel XLS file, Access MDB file, or Text File. You will be prompted for the folder and file name to use for storing the file.

A printer

All report formats may be sent to a printer. By choosing the explicit, "Printer" output type option, you save a step in the process of generating a Text File output type, and then sending that to the printer.

The only way to avoid having the option of printing a report is to select the Screen Display destination, and not use the Excel option for viewing it.

An email address

Any output format that involves the creation of a file can also be sent via email. Before you can use this option, your system administrator must have configured an email server for VTScada to use. You can send the report as the body of the email, as an attachment, or both.

If the output uses a Microsoft Excel™ file, and you have an older version of that program using the XLS file format, you may be limited to 255 columns (tags) in your report. Modern versions of Excel, using the XLSX format will support up to 16383 columns.
VTScada will automatically detect the installed version and produce an output file using the format it supports, XLS or XLSX

If generating a file using the VTScada Anywhere Client, it will be transferred to your browser automatically. Check your browser's download history. (Will vary by browser.)
Only text files can be generated by a thin client, not spreadsheet or database files.
Similarly, Excel templates cannot be used when reporting via a thin client.

This applies to report generation, HDV exports, note exports, ChangeSet creation, and tag exports.
You cannot view a generated file (such as a report) within the Anywhere Client. The client shows only the VTScada user interface.

When running VTScada as a Windows service, DO NOT select Excel as an output destination or option from a Report Tag. As noted in the MSDN forums, office applications assume they are being run under an interactive desktop. If Excel attempts to open a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog from a non-interactive service, the result is an invisible dialog that cannot be dismissed, stopping the thread.

Besides the technical problems, you must also consider licensing issues. Microsoft's licensing guidelines prevent Office applications from being used on a server to service client requests, unless those clients themselves have licensed copies of Office. Using server-side Automation to provide Office functionality to unlicensed workstations is not covered by Microsoft's End User License Agreement (EULA).


Use an Excel Macro Template

You can choose to send report data to a customized Microsoft Excel™ template file. Excel template files can be used to apply formatting, and to generate summary calculations using a VBA macro.

To use this feature, you must:
1) Have Microsoft Excel installed on your PC.
2) Use the Screen Display report output option.
3) Provide the name of the template file that you wish to use.

The VTScada installation comes with three sample template files, each provided in ".xlt" and ".xltm" formats. These templates are stored in the Examples directory within the VTScada installation directory (e.g. C:\VTScada\Examples\).

If help is required, there are many resources available in bookstores and on-line for both Excel and VBA. Trihedral does not offer support for either Microsoft Excel or the VBA language.

When running VTScada as a Windows service, DO NOT select Excel as an output destination or option from a Report Tag. As noted in the MSDN forums, office applications assume they are being run under an interactive desktop. If Excel attempts to open a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog from a non-interactive service, the result is an invisible dialog that cannot be dismissed, stopping the thread.

Besides the technical problems, you must also consider licensing issues. Microsoft's licensing guidelines prevent Office applications from being used on a server to service client requests, unless those clients themselves have licensed copies of Office. Using server-side Automation to provide Office functionality to unlicensed workstations is not covered by Microsoft's End User License Agreement (EULA).

Within each of these template files is a macro named, "Complete". A macro is a VBA program you write or record to perform a series of commands. In the case of these template files, the Complete macro sets the visibility of the report to true or visible, and saves the report.

  • Example1 is an empty template for a macro. The subroutine is defined but contains no code. Use this if writing a completely new template.
  • Example2 expects data from the VTScada standard report. It will save the Excel file to a new Reports folder, summarize each column of data using four functions from the Excel statistics library, and apply rudimentary formatting.
  • Example3 is functionally the same as Example2, but designed for use where VTScada runs as a Windows service. The report file is created and saved, but Excel never becomes visible during the process. This option may avoid the problems caused by a model dialog from a non-interactive service but the earlier warning stands.

Create an Excel Template

You must be familiar with using Visual Basic for Applications (VBA) to create or modify a macro within Microsoft Excel. The menus to open and therefore the steps to use within Excel will vary depending on the version you are using. The following procedure is provided as a guideline rather than a set of steps to be followed.

  1. Navigate to the Examples directory within the VTScada installation directory (e.g. C:\VTScada\Examples\).
  2. Open the template file you wish to use as a guideline.

The extension will be .XLT or .XLTM, depending on which version of Excel you use.

Be careful that you do not create a new file based on this macro instead of opening the macro for editing. Right-click on the file name and be sure to select Open rather than the default option, New.

  3. If prompted to enable macros, do so.
  4. Press the Alt-F11 key combination to open the VBA development environment.
  5. Locate Module1 in the Project area.

  6. Click to open the code window to edit the macro named Complete().

  7. Modify the macro as you require.

A way to do this that requires only a cursory knowledge of VBA programming is to start with a report that is saved to an unformatted Excel file. Turn on the macro recorder and adjust the report as you like. When the report looks the way you want, stop the macro recorder and examine the code that was created to learn how each step of the formatting process is coded into VBA.

  8. Expand the File menu and click, Save.
  9. Close the VBA development environment window.
  10. In Excel, select Save As from the file menu.
  11. Navigate to your application directory (e.g. "C:\VTScada\MyApplication\).
  12. Enter a name for the template file in the File name field.
  13. Close the custom template file.

Example1:

Sub Complete()

'This is an example of an Excel Template macro that can be used with VTScada reports.
'At this point the report module has already dumped the report data onto the spreadsheet.
'Your macro must be called Complete.
'To uncomment line, remove the preceding’

'If the macro makes any changes to the spreadsheet, then the user will not be able to
'close the workbook until they answer the save query dialog.
'To prevent this, set the Saved property of the workbook to 1
'Excel.Application.Visible = TRUE
'Uncomment the above line if you want your spreadsheet to display on report completion
'Leave it commented if you want report execution to take place silently (suitable for automatic reports)

'ActiveWorkbook.SaveAs Filename:="Output.xls"
'The above line is an example on how to save your file with a hard-coded filename.
'Default saving location for Excel is My Documents.

'ActiveWorkbook.SaveAs Filename:="C:\" + Replace(Worksheets("Sheet1").Range("A1").Value + " generated at " + Time$ + " on " + Date$, ":", "-") + ".xls"
'The above line is an example on how to save the file on your C drive with the filename being
'the report name and range concatenated with the time at which it was generated.

End Sub

The macro, "Complete" in file, "Example1" contains code to display the spreadsheet when the report is complete. (As noted in the comments, the relevant line of code must be uncommented.) An example of how to save the report spreadsheet with a hard-coded file name is included. Additionally, an example is provided of how to save and name the report spreadsheet with the report name and range, concatenated with the time at which it was generated.

Example2:

Sub Complete()
'This is an example of an Excel Template macro that can be used with VTScada reports.
'At this point the report module has already dumped the report data onto the spreadsheet.
'Your macro must be called Complete.
'To uncomment line remove the preceeding '
'If the macro makes any changes to the spreadsheet, then the user will not be able to
'close the workbook until they answer the save query dialog.
'To prevent this, set the Saved property of the workbook to 1
'This sample Excel template file automatically determines the extents of the data sent to it
'& calculates the total, average, standard deviation, and variance at the end of the report.
'This will work for any number of columns in any number of sheets in a workbook file provided
' that the title is always 2 rows high and that the time & date each occupy a column each.

' View the spreadsheet when it opens
Excel.Application.Visible = TRUE

'Save file name is set to current time & date
If Dir("C:\Reports", vbDirectory) = "" Then
MkDir ("C:\Reports")
End If

If Val(Application.Version) < 12 Then
ActiveWorkbook.SaveAs Filename:="C:\Reports\" + "VTSCADA Report " & Replace(Time$ + Date$, ":", "-") + ".xls"
Else
ActiveWorkbook.SaveAs Filename:="C:\Reports\" + "VTSCADA Report " & Replace(Time$ + Date$, ":", "-") + ".xlsm", FileFormat:=52
' 52 = xlOpenXMLWorkbookMacroEnabled = xlsm (with macro's in 2007-2010)
End If

' Trap errors & ignore
On Error GoTo ErrorCheck
' Number of title rows
Trows = 2
' Number of timestamp columns
TCols = 3

' Cycle through all worksheets
For Each Sheet In ActiveWorkbook.Worksheets
' Go to the sheet
Sheets(Sheet.Name).Select
' Record the active cell on the sheet
ActiveCellPos = ActiveCell.Address
' Determine the area used on the worksheet using Range format
UsedArea = Sheet.UsedRange.Address(ReferenceStyle:=xlA1)
' Get the number of rows & columns filled in
C = Sheet.UsedRange.Columns.Count
R = Sheet.UsedRange.Rows.Count
' Set comments Under Date/Time
Cells(R + 1, TCols).Value = "Total"
Cells(R + 2, TCols).Value = "Average"
Cells(R + 3, TCols).Value = "Standard Deviation"
Cells(R + 4, TCols).Value = "Variance"
' Formulas for each column
For I = (TCols + 1) To C
' Formula for total
Cells(R + 1, I).Activate
ActiveCell.FormulaR1C1 = "=SUM(R[-" & R - Trows + 0 & "]C:R[-1]C)"
' Formula for average
Cells(R + 2, I).Activate
ActiveCell.FormulaR1C1 = "=AVERAGE(R[-" & R - Trows + 1 & "]C:R[-2]C)"
' Formula for Standard Deviation
Cells(R + 3, I).Activate
ActiveCell.FormulaR1C1 = "=STDEV(R[-" & R - Trows + 2 & "]C:R[-3]C)"
' Formula for variance
Cells(R + 4, I).Activate
ActiveCell.FormulaR1C1 = "=VAR(R[-" & R - Trows + 3 & "]C:R[-4]C)"
Next I

' Select the calculated data & set to bold
Rows(R + 1 & ":" & R + 4).Select
Selection.Font.Bold = TRUE
' Bold the title line & set color
Rows("1:" & Trows).Select
Selection.Interior.ColorIndex = 35
Selection.Font.Bold = TRUE
' Adjust column widths to fit data
Rows("2:" & R + 4).Select
Selection.Columns.AutoFit
' Set to freeze pane on first data cell
Cells(Trows + 1, 1).Select
ActiveWindow.FreezePanes = TRUE

Rows(Trows + 1 & ":" & R).Select
Selection.Rows.Group TRUE
ActiveSheet.Outline.ShowLevels RowLevels:=1
Next

' Exit here to prevent running error trap when complete
Exit Sub

' Do nothing error trap
ErrorCheck:
Resume Next

End Sub

The macro, "Complete" in the file, "Example2" calculates the total, average, standard deviation and variance of the report data.


Run-Time Configuration of Report Tags

The Report Tools Folder

The components of the Report Tools folder of the Widgets palette can be used to add flexibility to Report tags. Report tags are extremely useful in that they hold all the configuration required to generate a report. This saves operators time by avoiding the need to work through the steps of the Reports page.

However, it may be useful to provide certain configuration options for a report tag, such as allowing an operator to choose the output destination, or the time span covered in the report. This can be achieved, without granting tag configuration privileges to the operator, by using the elements in the Report Tools folder.

This library duplicates the widgets available by drawing any Report tag. The exception is the Report Iterations widget because Report tags cannot include iterations as part of their configuration. The Report Iterations widget is included for the sake of completeness as one of the report page tools, and might be used if you were creating a custom report page.

The Report Tools folder can found in the Widgets palette of the Idea Studio. All the components that make up the Reports page are available here. Note that, it is not expected that you would use these to duplicate the Reports page. The usefulness of these tools lies in the ability to provide selected configuration options for a given Report tag.

After dragging each tool from the palette to a page, link it to the Report tag instance that it should modify.

Related information:

Report Button Widget - Allow a report to be generated (or re-generated) at any time.

Reset Target Widget - Choose the output format and location of the report.

Report Iterations - Repeat the report for consecutive time frames.

Report Options Widget - Choice of Excel or Access options to enhance selected output formats.

Report Tag List Widget - Selection of tags to be included instead of the original named group.

Report Type Widget - Enable selection of the report type.

Reporting Period Widget - Modify the time period that will be covered by the report.

Reporting Period (Enhanced) Widget - Provides a greater range of options for controlling the report's time period.


Operator's Guide to Security

Applications are normally secured. Your VTScada developer or manager will have created a user name and password for you to use. Or, they may have configured VTScada to accept your Windows account name and password.

In either case, "Username" in these instructions refers to the name that your manager told you to use. There is no need to guess.

Several consecutive attempts to sign in using the wrong password will result in your account being locked for a period of time. The length of the time period and the number of attempts before this happens are both under the control of your VTScada developer.(*)

To sign in to your user account:

Click on the "Sign in" button on the Display Manager's title bar.

The Sign in dialog opens, prompting for a
Realm or a Username depending on the configuration of your site.

If security realms (formerly known as "security groups") are in use at your site, this will prompt for your realm.

If you have been given a realm (or group), type it in, then press the tab key or the enter key, or click the arrow.

If realms are enabled, but you know that you do not belong to one, you can click the arrow or press tab to advance to the next prompt.

Security realms can be configured such that, instead of being prompted for realm and account name separately, you must enter them together with a defined character in between: OpsRealm:Sam. If this is the case at your site your manager will tell you what realm and character to use in front of your account name.

If you do not see this prompt, your site does not use a separate security realm sign-in.
Continue with the next step.

You will always be prompted for a username. Type the name that your manager told you to use, then press the tab key, or the enter key, or click the arrow.

Logon dialog - basic

The Username prompt.
A back arrow will be included if you are signing in to a realm.

You will always be prompted for a password. Type it in, then press the tab key, or the enter key, or click the arrow.

If you make a mistake, you can return to the previous prompt by clicking the back arrow or by pressing shift + tab.

The Password prompt

If you have entered everything correctly, your account name now appears where the "Sign in" button was. (Click that to sign out.)

You are signed in and your privileges are in effect.

Alternate instructions: If signing in to the Application Configuration dialog

If you attempt to open the Application Configuration dialog while not signed in to the application, you will be asked for a username and password (and possibly realm) in one dialog rather than in three steps.

Standard sign-in versus Realm sign-in.

Troubleshooting:

The appearance of the "Sign in failed" message will depend on whether you were trying to sign in from the application or the VAM, but the meaning is the same.

The name or the password (or realm if used) could be wrong

If you cannot sign on:

  • Check whether Caps Lock is on. Passwords are case-sensitive.
  • After several failed attempts, VTScada will lock your account for a period of one minute. (Both the number of attempts, and the lock-out period are configurable.) While locked, even a correct sign-in attempt will generate exactly the same message.

(*) A program attempting to hack an account by brute force will trigger the lock-out sooner and for a longer time than an operator making several attempts to remember a password and pausing between each attempt. This trigger-point is also under the control of your VTScada developer. (Developers should refer to the Security Property List..)


Change Your Password

Your developer or security manager may have configured your account to require a new password on a regular basis. If so, VTScada will tell you when it is time for a new password and help you create one.

If your system uses Windows authentication, you cannot change your password through VTScada.

In addition, you may be able to change your password at any time you choose. If so, you can change it as follows:

  1. Sign in to the application using your username and current password.
  2. Click on the button that now displays your username.

If there is an option labeled "My Account" you can proceed.

Basic security options dialog

Security options, as seen by an operator with the Account View privilege

  3. Click the My Account option. The Account dialog opens.

You may view your account settings, but change only your password and Alternate ID with the Account Modify privilege

  4. Enter your new password in the Password field.
  5. Enter the same password in the Confirm Password field.
  6. Click OK.

If the password you have entered matches in both fields, the new password is saved to your user account.

If you make a mistake when you are entering the password in the Password and Confirm Password fields, VTScada will require that you try again.

When you are selecting a password for your application, it is a good idea to use a combination of numbers and letters. Long passwords are strong passwords. A sentence (with the spaces removed) will always be more secure than a single word. You should never disclose your password to others. If you think that someone is aware of your password, you should change it immediately.


Two Factor Authentication for Operators

If your system administrator has enabled two factor authentication with TOTP, the next time you sign in you will be asked to register a device.

You may register more than one device to your account but they must have unique names.

Before proceeding you will have to select a device and set up an authenticator Closed A tool or application that verifies the user.. The most common authenticators are applications that can be installed on a mobile device such as a smartphone or tablet. Examples include:

  • Microsoft Authenticator
  • Google Authenticator
  • Keeper
  • Authy

Select an authenticator and install it on your device. For the easiest setup, choose a smart device with a functioning camera.

Have your device ready with the authenticator app open.

Back in VTScada, give your device a nickname like "Phone" and click the arrow for the next step. Your system administrator will be able to see the device nickname associated with your user account.

A QR code will appear alongside a 32-digit code.

Follow the directions on your authenticator app to scan the QR code.

You will be asked to provide a TOTP passcode from your device. This guarantees that the registration was successful.

If you do not have a functioning camera on your authenticator device, you can enter the 32-digit code manually. However, you have a limited time to do so before the code expires.

Your authenticator is now registered to your account. Every time you sign in, you must provide your password and a passcode from your device.

What to do if you have lost your device

If your device has been lost or no longer works, tell your system administrator right away. They will unregister your device and you will be able to register a new device (or re-register your recovered device) the next time you sign in.

Security best practices for operators

The greatest security risks happen offline. Always be mindful of your actions and surroundings and stick to trusted devices and networks.

  • Password protect your smart phone, tablet or any other device or authenticator you opt to use for TOTP.
  • Be aware of phishing attempts. Do not open suspicious emails, click suspicious links or download suspicious files on either your device or your workstation. If someone you know sends you a link or a file, check in with them first to make sure it's legitimate.
  • Keep your passcodes and QR codes obscured from line-of-sight just like you would an ATM or debit keypad.
  • If you hear from your system administrator that the company has implemented two factor authentication with TOTP, register your device as soon as possible. Don't leave your account unregistered.


Sign Out From Your Application

If you are finishing a shift or must leave the computer for a period of time, you should sign out so that the next operator can sign in to their account, and so that your workstation is not left unattended with an active account. Your VTScada developer may have configured your application to sign you out automatically after a period of time if you have left your account idle.

To sign out from your application:

  1. Click on your account name at the upper right of the screen.

The Options menu opens, displaying at least a "Sign out" option. (There may be more options, depending upon your privileges.)

  2. Click on the Sign out option.
Log off button

Found in the upper right of the VTScada window

The security menu closes, and the button again displays the label "Sign in", waiting for you or another user to sign in.


User Accounts and Privileges

When your VTScada developer or security manager set up your user account, a number of privileges or permissions were assigned to you. User privileges are a set of rules that define which options and specific functions of an application are available to you. These privileges have been assigned according to your operational duties. Your VTScada developer can explain which privileges you have been assigned, and how they work.

If you have not been granted the full complement of user privileges, you may encounter features that are off-limits. Disabled features appear grayed-out, or cause an access denied message to appear when you attempt to access the feature.

Sample "Access denied" message.

Related information:

Security Related Dialogs - Other security messages.


Security Related Dialogs

There are variety of security-related messages that you may encounter while working with VTScada.

Reset Password

Several situations may force you to change your password: If passwords expire on a set time interval, if a security account manager has changed the minimum password requirements, or if the manager has set an option that requires you to change your password. (Expired passwords will always work one last time to give you the opportunity to use the Reset Password dialog.)

Provide your old password to confirm your identity (note that passwords are case-sensitive) and then enter a new one. You are required to type the new password twice to minimize the chance of a typo being saved in the new word.

Old Password is Incorrect Dialog

The reset password dialog requires the user to verify their identify by typing their current (old) password before entering a new one. If an incorrect word is entered for the old password, the following dialog will appear.

Old password is incorrect

Click on the Close button and type the correct old password to proceed.

Password Warning

Password will expire in x days

If the application has been configured to warn users that their password will expire in the near future, then every time they sign in during the configured warning period the warning dialog will appear, showing the number of days until they must set a new password.

Access Denied: Not Signed In

In the event that you are not signed in and you attempt to access a control process (for example, if you attempt to close your VTScada application by clicking the Windows close button at the top of the Display Manager), or try to control machinery, you will receive an access denied message similar to the following:

You are not logged on

Sign in to the application using your username and password, and then attempt the control process again.

Access Denied: No Privilege

If you are signed in to your application, and attempt to access a control process for which you are not authorized, you will receive an access denied message similar to the following:

Access denied - no control privileges

The dialog shows that you do not have the privilege appropriate to the action you've just attempted to complete. If you find that the action is necessary to your duties as an operator, please speak with your VTScada developer, or the person in charge of the security for your application so that they can add the appropriate privilege to your user account.

Access Denied: No Application Close Privilege

If you have not been granted the appropriate user privilege, and you attempt to close the application using the Windows close button, you will receive the following access denied message:

Access denied - no application close privilege

If you receive the above dialog, you will be unable to close the application using the Windows close button. You must use the VAM to stop the application.

Password Entries Do Not Match

When you are in the process of changing your password, and the password you entered in the New Password and Confirm Password fields does not match, then the dialog opens as shown:

Password entries do not match

Close the dialog and re-enter your new password in both fields again, ensuring that you spell the password correctly and enter the exact same password in each field.

Password Too Short

If you are creating a new password and do not use the number of characters required by the security manager, you will see this dialog. Click the Close button, then create a new password having at least the number of characters stated in the dialog.

Password too short

New Password Matches Old Password

VTScada will not allow you to create a new password that is the same as the previous password. When changing a password, you must change it to something new.

New password matches old

Password Must Contain...

Your security manager may have configured the application to require strong passwords . These are passwords that contain numbers or special characters so that they do not match dictionary words. Click the Close button, then create a password having at least the number of special characters listed in the dialog box message.

Password must contain...

Operation Not Permitted Message

In extremely rare cases, a message may appear that reads, "Operation Not Permitted, Account Not Modified".

When running a standard VTScada application, you will not see this message. It can happen only if custom code happened to call a security-related function using a malformed user name.

If you do see this message, please contact the developer of your customized application.

This message is not to be confused with the Access Denied message that appears whenever a user attempts to access a function for which they have not been granted privileges.

Write Denied

You must hold the appropriate Control Token in order to write to this tag. For reasons of safety, only one person at a time may hold any tag's control token.

Request the token by clicking the button provided by the application developer.


Develop

VTScada Application Manager (VAM)
Create and manage applications using the VAM.

Edit Properties
Use properties to control how your application looks and works. Configure email for alarms and reports. Work in other languages.

Tags and I/O
Communicate with hardware or remote data sources. Configure control locks or control tokens. Design custom tag types to match your hardware. Set up recipes and batch processing.

Display Building (Idea Studio)
Use the Idea Studio to create display screens with shapes, images, text, and widgets.

Alarms
Configure alarms, configure alarm behaviors, build customized alarm displays.

Log and Report
Configure data collection, explore alternate data sources, build reports with third-party tools.

Client / Server Configuration
Configure primary and backup services for redundancy and for load distribution.

Sites & Maps
Configure site lists and site maps.

Secure Your Application
Configure basic security (accounts, roles, rules) and advanced measures (OAuth 2.0, Windows Security Integration, filter access by user realm, security certificates...)

Thin Clients: Mobile and Internet
Safely install a VTScada Internet Server and connect using any of three thin client types.

The Oil & Gas Solutions Layer
Discover the tools in the Oil and Gas Solutions Layer


VTScada Application Manager (VAM)

Use the VTScada Application Manager (VAM) to create and manage applications. It will open whenever you start VTScada and also at the end of the installation process. As a security precaution, applications should be configured to hide the VAM from all but authorized users while the application runs. See: Hide the VAM

VAM features

Application Tools - Select an application to see the full list
Application Starting | While an application starts, a circular progress indicator is shown.
Restart Required | A circling arrow indicates that a restart is required before you can do further configuration of that application.
Remove | Will ask whether to save the folder (hide the application from the VAM) or remove it entirely including all files and data. Requires the Configuration security privilege
Application Configuration | This dialog provides extensive control over your application, including application properties that control how it looks and works. Requires the Configuration security privilege
Import File Changes | Used by programmers who add custom code to their applications. Requires the Edit Files security privilege
Start (or stop) Application | Use the arrow (or square) to start (or stop) the application. Note that developers can configure an application to start automatically. Stopping requires the Application Stop security privilege Running applications are indicated by a dot to the left and the fact that the start button has been replaced by the stop button.

If the Toggle Visibility feature has been enabled for an application, it's menu will have an additional tool:

Option to hide a running application.

This feature is rarely used outside sites that provide hosted solutions. See: Hide a Running Application

VTScada Tools - Open by clicking the triple-bar tool at the top of the VAM
VTScada logo images are protected. VTScada will not start if you remove or modify those files. Reinstall VTScada to restore the original images if you disregard this warning.
Add New Application | The Add button gives several options for creating an application. You can build applications from scratch, copy a multi-server application to this workstation, add an existing application to the VAM, or use a ChangeSet to create a copy of an application. Add New Applications
VTScada Thin Client/Server Setup | Requires a license that allows thin-client connections. Also used if allowing external ODBC connections for SQL queries of your application's data. Preparation for Mobile and Internet Access
List Manager | Create and manage lists of your applications. Lists in the Application Manager Use the arrow tabs on either side of the VAM to switch between lists.
Settings | Select a new theme for the VAM's appearance and choose whether it will carry into any application that does not have its own theme color. VAM Settings Select the default language for your application. Languages
License Management | Opens the License Management dialogue. Use this to review which features of VTScada are enabled by your license and to deactivate the license on the current workstation before moving it to a new one.
Setup Recommendations | Manually open the Setup Recommendations Dialog. This dialog appears automatically when the VAM starts unless it is suppressed. Suppression resets when VTScada is updated.
Help | Opens the VTScada help system.
About VTScada | Includes system metrics and contact information for Trihedral Engineering. See: About...
Exit VTScada | Stops VTScada and all running applications. If an application is running, you must confirm that you intend to stop it. Requires the application stop security privilege.

Keyboard shortcuts for the VAM

Key Combo | Description
Ctrl + D | Opens the VTScada Debugger Utility (Not the Source Debugger).
Ctrl + L | Opens the Working Copy Lock Closed Grants the lock-owner (module) permission to read/write configuration files. info dialog.


Lists in the Application Manager

If your site has several applications, you can create lists in the VTScada Application Manager (VAM) in order to better manage those applications. Sites with few applications might choose to move the VTScada utility applications to a separate list.

The default list is "All Applications", although this label does not appear until at least one other list exists. Every application will always be a member of the All Applications list.
You can suppress the visibility of any list including All Applications.

For example, the following figure shows a detail from a VAM that has three lists. (Note the three dots at the bottom of the figure.) Of those three, the list for Halifax County is shown. You can navigate between the lists using either the arrows on either side, or the dots at the bottom of the list. The filled dot in the center indicates that this is the second of three lists.

Sample list. Change lists using the tools shown.

After creating one or more new lists, if you stretch the VAM wider, it will display multiple lists:

View two lists at once

Create a new list, add an application to it

These two tasks always go together. There is no such thing as an empty list.

  1. Open the List Manager from the VAM's main menu.
  2. In the List Manager, select Add New List

Adding a new list in the List Manager

  3. In the Add New List dialog, type a name.

The Add New List dialog with a sample name.

  4. Select OK.
    The new list is visible and selected in the List Manager
  5. Use the boxes in the right panel to select which application will be included in this list.

Choosing which applications are in a list

You must select applications for your list before closing the List Manager. An empty list will not be saved.

  6. Select OK to save your work.

The list is created and populated with applications. It may not seem like anything has happened, but look again. The list navigation tools are now active, and you are viewing the default list, All Applications. Your application still counts as one of "All Applications". Click any of the list navigation tools to view the new list.

Adding an application to a list will activate (but not run) that application.

Manage the applications in a list

An application can belong to many lists. Every application will always be part of the "All Applications" list.

  1. Open the List Manager dialog.
  2. Select the list you want to manage.
    (Illustrated in the previous set of instructions)
  3. In the right panel, add or remove check marks beside application names.

Sort and organize your lists

To reorganize the lists themselves, use the up/down arrows below the list names area.

There are two ways to organize the applications within a list.

  • Working directly within the VAM, you can move applications by dragging.
  • Within the List Manager, select a list, then select the Sort Alphabetically option to let VTScada reorganize the entries in that list.

Rename a list

The "All Applications" list cannot be renamed.

You must open an edit dialog to rename a list. Do so by selecting your list in the List Manager, then select the Edit Selected List Name tool.

Type a new name into the dialog that opens.

Delete a list

If you remove all the applications from the list it is deleted automatically. There is no such thing as an empty list.

An easier method is to Select the Remove Lists tool below the panel of list names.

Removing a selected list.


VAM Settings

You can make the following adjustments to the VTScada Application Manager (VAM) using the Settings dialog, which you can open from the triple-bar menu in the VAM:

Settings is the fourth row in the main menu.

Options in the VAM's Settings dialog.

Set a color theme for the VAM and all applications that do not have their own theme:

  1. Open the settings dialog as shown in the previous figures.
  2. Use the Color Themes drop-down to choose a color.

Language

Sets the ActiveLanguage for the VAM display. Choices include English and French.

Before you can choose another language, you must create a file containing translations of phrases (titles, labels, etc.) for language. See: Languages

Show English phrase and ID when phrase look up fails.

The key word in this selection is "and". When there is no phrase in the currently selected language, the phrase from the default language (English) will always be shown. When selected, you will also see the matching phrase key, making it easier for you to find that key and create a translation. If not selected, only the phrase in the default language is shown.


Access the VAM from a Thin Client

For those running VTScada as a Windows® Service, it is possible to access the VTScada Application Manager (VAM) using either the VTScada Internet Client (VIC) or the VTScada Anywhere Client. Only one client at a time may access the VAM, or other script applications on that VAM, using this method. The mobile client cannot be used for this purpose.

To access applications from a Thin Client (including script applications) each must be secured and you must be able to sign in to an account that holds the Thin Client Access privilege.

Features are limited according to the type of thin client in use:

  • Mobile client: No access to the VAM
  • VTScada Anywhere client: Access the VAM as an application, but no ability to use Find Existing, Get from ChangeSet or Clone from ChangeSet.
  • VTScada Internet Client: Access the VAM as an application, but no ability to use Find Existing.

Prerequisites:

  1. You are running VTScada as a Windows service.
    This is mandatory. The following steps assume that you have already installed VTScada as a service and are switching to desktop mode temporarily. The required command line switches are documented in Service Command Line Reference
  2. Configure a VTScada Thin Client Server.

Steps:

  1. Stop VTScada as a service on the server.
    vts.exe /s=stop ... where VTS.exe is located in the folder C:\Program Files\Trihedral\VTScada\VTScada_YourVersionNumber
  2. Start VTScada as a desktop application on the server (vts.exe)
  3. Add the Application Manager script application to the VAM as an existing application.
    (Find Existing ) By definition, it will already be running.
  4. Open the Application Properties dialog for that script application.
  5. Select the Edit Security page.
  6. Enable security.
  7. Create a user account and grant it the VTScada Thin Client privilege.
  8. Create a new realm that includes this application.
    DO NOT add this application to an existing realm.
    DO NOT add other applications to this realm. (Configure a Realm)
  9. Stop VTScada as a desktop application on the server.
  10. Restart VTScada as a service. (vts.exe /s=start)
  11. Connect to the realm you created, using either the VTScada Internet Client (VIC) or the VTScada Anywhere Client.

As with any script application, to which you plan to make an Internet connection, do not configure the application to start automatically. Doing so is both unnecessary and undesirable.


Add New Applications

Create applications and add them to the VAM using the Add Application tool, found in the triple-bar menu at the top left of the VAM window as "Add New Application". Use this tool either to create a new application or load an existing one.

Starting the Add Application Wizard

The Add Application wizard will open automatically as part of the VTScada installation process.

The first decision after clicking Add New Application is whether to use the quick option, or the advanced option set.

Quick Add:

  • Creates a standard application, with all the default VTScada features.
  • You can name the application whatever you want.
  • Unless you know that you have an OEM layerAn OEM layer (Application Layers) is simply another standard VTScada application. Your new application will inherit (or gain access to) all the tags, pages, widgets, custom code such as drivers and reports, property settings and everything else from that application. This option is popular with System Integrators who create similar applications for many customers, as it allows them to create and reuse customized features for their industry. 1 to use, select this option.

Advanced:

  • Can also create a standard application, but with the option of choosing an OEM layer(*) and naming an alternate folder.
  • Create a script application. (For VTScada programmers only.)
  • Load or clone an application from ChangeSet.
  • Load an existing application into the VAM list.
  • Copy an application from another workstation.

You can remove an application from the VAM without also deleting it from the computer. Select the application name, then click the Remove tool. You will be prompted for whether you want to delete or retain the files.

Create New

(Advanced option #1 of the Add Application dialog)

After opening the Add Application Wizard, choosing Advanced, then Create new, you will arrive at the Create new page.

Create new - advanced option

  • A default name, "New Application" is provided, but you are advised to replace this with a more relevant name.
  • The path will include the VTScada installation folder and the name of the application, with spaces and other symbols removed. You may choose or create a different path, but it is seldom useful to do so.
  • The Type selects the OEM layer that the new application will be built upon. OEM layers are most often used to provide industry-specific features. See Structure and Rules for details.

The Next button will take you to a confirmation screen where you can review your choices before clicking Finish to create the application.

Find Existing

(Advanced option #2 of the Add Application dialog)

After opening the Add Application Wizard, choosing Advanced, then Find existing, you will arrive at the Find existing page.

Find existing

Use this if you have an application on your workstation that you wish to add to the list in the VTScada Application Manager (VAM).

For example, a developer or customer may have given you an application on CD or memory stick. After copying the folders to your computer, use these steps to see and run the application in VTScada. You must also use these steps to view and run utility programs that come with VTScada. (These utilities exist to help VTScada programmers optimize their code. Only a few are useful for ordinary application development work.)

  1. Browse to the path containing the application's folder.
    The Show Path option is useful for cases where the path name does not match the application name.
  2. Select the application to load.
  3. Click Next.
    A confirmation page opens, where you can review your choices before clicking Finish.

Troubleshooting:

  • The folder exists, and contains an application, but the Found Applications dialog will not display it.

The application is already listed in the VAM, and cannot be added a second time. If you are attempting to make a copy, create a ChangeSet of the existing application and then create a cloned application using that.

  • The type is a string of random letters and numbers instead of an application name.

The application is based on an OEM layer that is not available. Install the OEM layer application first, then the one you want to run. You may need to go back to whoever supplied your application to ask for the OEM layer application.

Get From ChangeSet

(Advanced option #3 of the Add Application dialog)

The preferred way to copy a stand-alone application from one computer to another is to package it into a ChangeSet Closed An application's development history, packaged into a single file for distribution. There are several types of ChangeSet file. file. (ChangeSets - An Application in One File ChangeSets for Distribution)
Applications that will run on multiple servers are best distributed using the Get From Workstation option.

After opening the Add Application Wizard, choosing Advanced, then Get from ChangeSet, you will arrive at the Get from ChangeSet page.

Get from ChangeSet

  1. Use the Browse button to locate the ChangeSet file.
  2. Optionally, change the path (folder), into which the application will be placed.
  3. Click Next.
    A confirmation page will open, where you may review your choices before clicking Finish.

The Name and Type cannot be changed in this screen. You may change the name later using the Application Configuration dialog. The type is the OEM layer that this application depends upon, and cannot be changed at any time.

The OEM layer (Type) must exist and be added to the VAM before this application can run.

Troubleshooting:

  • A "1" or other number is added after the name or path.

The application already exists on your computer. You may choose to create a copy (clone) if you wish. The "1" distinguishes the clone from the original.

  • If the "Type" field refers to an application that does not exist on this computer, you must add that application before this one will run. Ensure that whoever gave you the ChangeSet file also provides a ChangeSet of the underlying type. See: Reusable Application Layers
  • If the application in the ChangeSet file had a server list configured, and those servers cannot be accessed from your workstation, you must remove the server list before starting the application.
  • If security was enabled in the application, ensure that you have a valid account name and password before running the application.

Clone From ChangeSet

(Advanced option #4 of the Add Application dialog)

A cloned application, created using a ChangeSet (ChangeSets for Distribution), provides a safe way to experiment with a new development idea. The clone is a (1) copy of the original at the time that the ChangeSet file was made, and will include all of the existing communication drivers and I/O, but not logged data. Mail server credentials and roster account parameters are encrypted using the application GUID. Cloning an application changes the GUID so these fields will need to be re-entered after a clone operation.

The revision history (repository) will be included from a standard ChangeSet, but not from a snap shot ChangeSet.

By working in a cloned application, you can test, debug and experiment, all without risk of changing the original application.

After opening the Add Application Wizard, choosing Advanced, then Clone from ChangeSet, you will arrive at the Clone from ChangeSet page.

Clone from ChangeSet

  1. Use the Browse button to locate the ChangeSet file.
  2. Optionally, change the name and the path (folder), into which the application will be placed.
  3. Click Next.
    A confirmation page will open, where you may review your choices before clicking Finish.

The type is the OEM layer that this application depends upon, and cannot be changed at any time.

The OEM layer (Type) must exist and be added to the VAM before this application can run.

Troubleshooting:

  • If the "Type" field referred to an application that does not exist on this computer, you must add that application before this one will run. Ensure that whoever gave you the ChangeSet file also provides a ChangeSet of the underlying type. See: Reusable Application Layers
  • If the application in the ChangeSet file had a server list configured, and those servers cannot be accessed from your workstation, you must remove the server list before starting the application.
  • If security was enabled in the application, ensure that you have been given a valid account name and password from the original application before starting this instance.

Get From Workstation

(Advanced option #5 of the Add Application dialog)

If you have VTScada licenses for two or more computers, and at least one license includes server capabilities, then use this option to install the application on the other computers on your network. (Client / Server Configuration)

The Get from workstation option is preferred for distributing an application between computers that are connected on a network. By using this method, you ensure that the most up-to-date version of the application is installed, and that future updates are distributed automatically. (Assuming a properly configured server list.)

If the application is based on an OEM layer, and that OEM layer is present on the server, it will also be retrieved at the same time as the application.

If the application is secured, you must sign in with an account that has either the Configure or Manager privilege, and that is not a member of any security group.

  1. Begin by opening the Add Application Wizard,
    ... choose Advanced and click Next,
    ... choose Get from Workstation and click Next.
    You will arrive at the Get from Workstation page.

Machine names are preferred over IP Addresses.
Type the name if the list is not populated automatically.

  2. Enter the machine name or IP address of the workstation containing the application.
    On a network with a properly configured domain name server, all local machines that have VTScada installed should be available for selection in the drop-down list.
  3. Click Next.
    Applications available on the selected workstation are shown. An asterisk will mark ones that already exist on your workstation.

Typical list of applications.

  4. Select the application you want.
  5. Click Next.
    A confirmation page opens, where you may review your choices before clicking Finish.

If the application is secured, you must logon before the transfer will take place. Get From Workstation operations are exempt from TOTP. You will not need to perform a TOTP check even if there is a device registered to the account.

After clicking Finish, the application is copied to your workstation and added to your list of available applications in the VAM.

When adding a backup server, you can monitor VTScada's progress while copying data to the new server by using the Historian Status widget. When the status returns to "Ready", your data is synchronized.

Troubleshooting:

  • No servers are shown in the Choose Server dialog.

This may indicate that your network domain name server (DNS) is not properly configured.
In most cases, you can ignore this problem and type in the name of the computer where the VTScada configuration server is running.
It may be necessary to add the Setup.INI property, RPCConnectStrategy, and set it to a valid value.

  • The Find Servers dialog reports that the requested computer is unavailable. This may be preceded by a "Contacting Workstation..." message.

The specified workstation is not available, or VTScada is not running on that computer.

  • The application you expected to find is not listed.

Applications that exist on both computers are not shown. If it is not listed in your VAM, try the Find Existing option.


Structure and Rules

Viewing: Develop > VTScada Application Manager (VAM) > Add New Applications > Structure and Rules

Concepts:

Add New Applications

Tasks:

Tags and I/O

Display Building (Idea Studio)

Reference:

Naming Rules

Reusable Application Layers

Application Files and Folders

Structure and Rules

There are two basic types of VTScada application: Standard and Script.

Standard applications

This is the type of application people use every day to monitor and control their system. At a technical level, it's worth noting that all standard VTScada applications are built (layered) on other applications. At the lowest level is the VTScada Library, which provides the development environment, tag and widget definitions, and all the user-interface elements that make up an application.

You may see the term OEM Application from time to time. An OEM application is simply a standard application, but one that is meant to provide tools for one or more other applications, in much the same way that the VTScada Library provides the tools such at the Tag Browser and Idea Studio, and all the familiar pages & widgets to standard applications. This is useful in many situations and essential for anyone building a set of subordinate applications, all monitored by one master application. See: Reusable Application Layers

Script applications

These are written in a text editor using the VTScada scripting language. Script applications are not based upon the VTScada Library Layer and therefore do not have access to the Display Manager, Idea Studio, built-in pages such as Reports and the HDV, the Alarm Notification System or any of the other tools and features provided in the VTScada Layer.

Several script application utilities are included with every copy of the VTScada. These include debugging and monitoring tools such as the Source Debugger, the VTScada Internet Monitor, etc. Most are not visible in the VTScada Application Manager by default but can be added as existing applications.

Script applications are seldom used for SCADA purposes.

Local vs. multi-server applications

A further distinction is whether an application is "local" or "multi-server". In both cases, these are standard applications. The difference is in whether a server list has been defined for the application.

If local, the application runs on only a single workstation and has no server list. If multi-server, then there is a server list and the application will run simultaneously on multiple servers and workstations, sharing data and tasks between them and automatically continuing without interruption should a server fail.

The application itself is the same whether local or multi-server. The difference is in the presence or absence of a server list.


Naming Rules

The rules for what is a valid or invalid name will vary according to the type of thing you are naming.

Naming Rules for Applications

In general, applications are stored in a path that matches the name. The rules for application path names are more strict than for application names because the path must be a valid Windows folder name. Application names may include alphanumeric characters, and can include the punctuation key symbols (i.e. decimal (.), and comma (,)), and symbols created using the number keys (for example, the number hatch (#), and underscore characters (_)).

If the application path name is based on the application's name, VTScada automatically removes any invalid characters and spaces. If you attempt to name an application "." (period), then VTScada will append a "1" to the path name because "." already exists as the name of the current windows folder.

The characters in the following table may not be used in application path names. If you choose to enter a custom application path, you cannot use these invalid characters or spaces.

Invalid Character | Example
Colon | :
Less Than | <
Greater Than | >
Pipe | |
Backslash (other than as a divider between folder names) | \

Naming Rules for Pages

Valid characters that may be used in page file names consist of any combination of:

  • Alphanumeric characters (i.e. A through Z, and 0 through 9)
  • The underscore character ( _ )
  • The decimal character ( . )

Page names can include other symbols (e.g. dollar sign ($), number hatch (#), equals (=) characters), spaces, or strictly numeric characters, but not in page file names. Because these symbols are acceptable in page titles, and the page file name is automatically based on the page title, VTScada strips any invalid characters when generating the page file name.

Note that widget names cannot be the same as the short name of any tag.

Naming Rules for Accounts and Passwords

  • Account names cannot begin or end with spaces.
  • Do not use the following characters in VTScada account names:

" \ / [ ] : | < > + = ; , ? * @

  • The following characters are not allowed in Windows account names: (spaces are accepted but not advised)

" / \ [ ] : ; | = , + * ? < >

Use care with special characters in account names and passwords. While valuable from a security standpoint, some characters may cause problems with certain Alarm Notification devices.
* As an example, it has been reported that many symbols other than letters and numbers in a password will not work with the Twilio® interface. To be safe, use only alpha-numeric symbols in account passwords.

Naming Rules for Tags

  • Tag names must be no longer than 64 characters in length

This rule refers only to the tag's immediate name, not its full name, which may include a lengthy list of parent tags.

  • Full tag names must be no longer than 253 characters in length

This rule refers to the tag's full name, which may include many parent tags.

  • Tag names must not duplicate other named items (reserved words).
    • You cannot name a tag "TagBrowser" or "Test", since those names are used elsewhere in VTScada.
    • A tag may not be named "Value" or "Area" since those are the names of tag properties.
    • Tag names may not duplicate Type names - you cannot name a tag "Calculation" or "Analog Status".
    • Tag names may not duplicate any function names. Refer to Function Reference.
    • In general, it is safest to avoid using common words unless you add a prefix or suffix.
  • Valid tag name characters include:
    • Any combination of alphanumeric characters (i.e. A through Z, and 0 through 9)
    • Spaces, except at the beginning or end of the name.
      (Some installations choose to avoid spaces as they can cause confusion. For example, "A B" looks like "A B" but the second has two spaces and is therefore a different name.)
    • Period
      (Legal but discouraged.)
    • Symbols other than those listed below.
      (Underscore _ and dash - characters are used in place of spaces at installations where spaces are avoided.)
  • Invalid tag name characters include:
    • Backslash (\ which used to separate parent names)
    • Forward slash (/)
    • Colon (:)
    • Asterisk (*)
    • Question mark (?)
    • Double quotes (")
    • Less than (<)
    • Greater than (>)
    • Vertical bar (|)
    • Leading spaces
    • Trailing spaces
  • Tag names cannot be purely numeric.

"51" is not a valid tag name but "Station 51" is.
An interesting side effect of this rule is that you cannot name a tag "E1" or similar because this is a valid numeric expression: ("E1" == "0E1" == "zero exponent one").

In the event that you have entered an invalid tag name, VTScada will notify you with a warning dialog and will clear the Name field so that you can try again.


Application Files and Folders

Files within an application are divided between "user files" and "working files". This chapter discusses user files. The set of working files in the .sync folder must not be edited. Any attempt to do so will damage or destroy your application.

Most user files may be edited using a text editor, but be aware that edited files must be imported into an application's working set before those changes will go into effect. The Import/Export Files dialog is not available in runtime-only versions of VTScada. Also, access to the Import/Export Files dialog is controlled by the Security Manager. Only users with the Edit Files privilege may import an edited file.

As you work within VTScada, it will automatically update the user files to reflect changes to the working set.

The working set of files and the change history repository are stored within the .sync folder. Do not attempt to edit any file in that folder structure. Any attempt to do so will damage your application.

Folders:

Pages

Contains the source code for all of the application pages. You may edit these files and import your changes to modify an application.

PlatformInfo

Contains information about your VTScada installation, the application and the computer you are running the application on. These details may be viewed by opening the VTScada Application Manager (VAM), clicking on Properties, then on Information.
Do not attempt to edit files in the PlatformInfo folder. Damage to your application is likely to result.

Resources

Contains logo and button images used by VTScada.

Bitmaps

If you are adding your own custom images for display in an application page, you will create this folder and store the images here.

Tags

If the setting, ExportTagFilesToUser is set, this folder will contain an up-to-date copy of all the tag files. This copy cannot be imported, but serves as a reference and can be used in recovery should the .sync folder be damaged.

Data

Contains data output files generated by the application including log files, retained data files and network values. Copy this folder to make backups of your application's data.

Widgets

Contains user copies of the source code for all user-created widgets.

Files:

Accounts.Dynamic

Created only after security has been enabled. Contains encrypted account information. User edits to this file will be ignored.

Application.version

Stores information about the current revision of the application. User edits to this file will be ignored.

AppRoot.SRC

The main source file for an application. Lists top-level variables and modules in use by the application. Edits may be imported. This file was named "AppMod.SRC" in earlier versions of VTScada.

GroupName.SRC

The source code for any user-defined widgets (groups) in the application will be stored in these files, where the name of the widget is used instead of "GroupName". User edits to these files may be imported.

Lexicon.VLX

If you customize the speech lexicon within an application, your edits will be stored in Lexicon.VLX.

Servers.RPC

Contains the list of configuration servers. This text file is in XML format. User edits may be imported, but must be made using correctly formed XML.

Settings.Dynamic

Contains application properties (formerly, configuration variables) whose value may be changed without re-starting the application. This file follows the same structure as the obsolete Config.INI

Settings.Startup

Contains application properties (formerly, configuration variables) whose value can only be changed by re-starting the application. This file follows the same structure as the obsolete Config.INI


Reusable Application Layers

While VTScada's development tools are useful for a wide variety of industries, you are likely to want to create additional reusable objects. These might be device drivers, reports, tag types, widgets, or other software modules.

With the VTScada layering system, you can create these tools in one application then re-use them in many others. This feature is especially useful for system integrators who develop applications for several clients in a particular industry. It is also recommended for use with subordinate applications (Master & Subordinate Applications).

Perhaps the best reason to use an OEM layer is that this is the easiest way to distribute and then update custom tags, etc. for use in other applications.

OEM Closed Technically: "Original Equipment Manufacturer". In practice, any application can be an OEM layer. layers are used for any, and sometimes all of the following reasons:

  • You have a set of industry-specific tools that you want to re-use for a number of client applications.
  • You want to ensure consistency of certain things across applications.
  • You don't want to distribute your source code.
  • You want to ensure that other developers, using your application, cannot modify the structure of certain tags or other objects. Sometimes, this is to protect those objects, and sometimes the reason is demarcation of responsibilities.

A certain amount of care and planning is required for the design of your OEM layer to ensure that everything works smoothly. Certain items can or cannot be overridden at the local level, depending on how you configure things.

How it works:

Every standard application is built on top of the VTScada System Layer application. All the pages you see in a new application, all of the default tags including Alarm Priorities, Fonts, and Menu Items, all the built-in reports, the Idea Studio with all of its widgets, and much more are defined in the VTScada layer and inherited by your application. You can change some of those tools, such as choosing a different font for one of the Font tags. Other things, such as the Alarm page and Operator Notes page, can be used but not changed.

Perhaps in your application, you build a new tag type called The Gizmo for equipment unique to your industry. You also create a widget that represents all the I/O and alarms for The Gizmo. Further, you have created a report so that operators can view a daily summary of how The Gizmo performed yesterday.

You are using tools inherited from the VTScada layer to build new features in your application.

Two plants use The Gizmo brand hardware for their operations. Your application will be distributed to both plants to serve as the OEM layer for their applications. The applications at Plant A and Plant B also inherit all the features of the underlying VTScada layer, so they also have all the standard tags, widgets, reports, etc.

If the Gizmo manufacturing company adds a new feature, you will modify your application to incorporate that into your tag type, widget and report. You then send a Snapshot ChangeSet to both Plant A and Plant B, updating the OEM layer at each location. They can now install and use the latest Gizmo, without needing to do a thing to their applications. The changes were incorporated when they applied the ChangeSet to the OEM layer.

Any VTScada application can be used as the base layer ("type" or "OEM layer") for another. When creating every new VTScada application, a required step is to select its type. (The "Quick Add" option in the wizard simply sets the type to Standard Application, meaning the VTScada layer.) If, in the Add Application wizard, you select the Advanced option, and then New, you are given an opportunity to choose the layer that the new application will be built upon and inherit features from. It is possible to create a chain of many such layers, each inheriting the features of all the layers below it.

There is an exception to the rule: Script applications that you create cannot be used as OEM layers. Script applications are not built on top of other layers.

New application properties

Select an OEM layer for a new app using the advanced option

The primary benefits that you gain from the VTScada layering system are re-usability and extensibility:

Re-usability:

Inheritance from lower application layers to upper layers means that the custom tools that you create for an OEM layer can be used in other applications. You do not need to recreate those tools or features for every application.

Extensibility:

New functions can be added to existing objects such as tags and drivers without changing the structure of applications built on the OEM layer. For example, if you extend the feature set of a custom tag in an OEM layer, then applications built on that OEM layer will immediately have access to the new feature set in your custom tag. Note that certain changes may require a restart before taking effect.

Other benefits from the use of OEM layers include:

  • Provides a clear distinction of who is responsible to maintain what portion of an application.
  • Ensures consistency across applications.
  • Separates the fundamental tools (tags, widgets and other code modules) from the application using those tools. Where application-specific customizations are required, it may be possible to apply a local override to the OEM definition, depending on what you are changing and whether source code is provide with the OEM layer.

OEM layers should be used by:

  • A system integrator who deploys SCADA/HMI applications with similar general functionality such as water wells or gas plants.
  • A organization that uses a standard set of SCADA/HMI functionality across two or more facilities
  • An original equipment manufacturer that deploys a common user interface with their equipment, where the user interface needs minimal or no unique configuration for each equipment installation.
  • An organization that needs a clear line between the parts of an application that can be edited and the parts that are under more strict change-control.

Best Practices:

  • Whenever the application design calls for two or more of the same complex tag type, widget, or other object, consider creating its template in the OEM layer.
  • Choose the type of ChangeSet according to your intended purpose.
    • For distributed development, standard ChangeSets are best because updates are merged.
    • For customers, Snapshot ChangeSets are best because they cannot see your development history.
    • To protect your proprietary work and to prevent edits of the resulting application, choose not to include source code with your Snapshot ChangeSet. This works best when used as an OEM layer.

If you intend to send updates, it is important to use "Create from ChangeSet" and never "Clone from ChangeSet". A clone will have a different GUID, and you will never be able to distribute updates to it.

  • If distributing a Snapshot ChangeSet without source code, and if you want to leave the default Overview page intact for applications to edit, then delete the OEM layer's copy of Overview. The default VTScada version will take its place and be available to the dependent applications. After deleting your copy of Overview, you will need to edit the page menu to put the VTScada version back in.
  • Consider enabling security in your OEM layer.
  • Consider setting the flag, DoNotStart, in your OEM layer, just before creating the ChangeSet for distribution.
  • Clean the OEM layer application before distribution.
    You will inevitably create instances of tags, widgets and pages in the OEM layer when designing and testing new objects. Before distributing the OEM layer, delete everything that you do not want to be part of applications built on that layer. For example, a new VTScada application has a TCP/IP Port tag type, but it does not come with instances of TCP/IP Port tags.
  • In an installation with primary and backup servers, ensure that Application Configuration option, "Synchronize the configuration of OEM layers via derived applications" is selected in the top-level application (found in the "Other" tab of the Edit Properties page of the Application Configuration dialog) so that updates to the OEM layer will be distributed using the same server list.


Inheritance Across Layers

New applications inherit object definitions and application properties from the layers on which they are based. They normally do not inherit instances of objects other than tags. For example, if your OEM layer has a custom report template, your new, derived application will be able to generate reports with that template, but you will not have a local copy of the code. The code remains in the OEM layer. (Tags are treated differently; the derived application will always be given its own copy of every tag in the OEM layer application.)

The same rule is generally true for pages, image files, device drivers, wizards and any other custom code. The new application remains dependent upon its OEM layers to supply various objects rather than becoming a complete, self-contained unit.

For an example, look at the list of application properties in a dependent application: properties with values set in this application are shown in black and can be changed. Properties whose values were set in the OEM layer are visible, and affect the dependent application, but they are not defined locally. Those properties can be changed, but only by creating a local copy, which will override the value from the OEM layer.

Pages and Widgets have different rules for inheritance

Use Care: Pages and widgets are handled differently from reports and wizard modules. If the OEM layer includes the source code of the page or widget, then upon opening the page or widget in the Idea Studio of the derived application, the default behavior is that the source code will be copied to the derived application. This creates a local override, which means that no further changes in the OEM layer will be seen in the derived application for that object.

For pages, you can control this behavior using the application property, AutoOverrideOEMPages.

When set to 0 (FALSE), developers working in derived applications will see the following prompt upon opening the Idea Studio for any page that exists (and for which there is source code) in the OEM application.

If overriding the page (default behavior) the source code is copied to the derived application.

If making a copy, the source code is copied and also renamed. The original page remains visible and usable, but its source remains in the OEM layer and updates there will be shown in the derived application. The copy is yours edit as you like. You are strongly advised against making the copy's name match the original. Doing so will only lead to confusion as you try to keep track of which page is the original and which is the copy.

Do not include source code files with your OEM layer unless you intend to make those objects editable in applications built on your layer.

Propagation of Changes Through Layers

You will need to deploy changes in the OEM layer if the AutoDeploy option has been disabled.

If the OEM layer has been installed at a site other than where development is being done, then updates to that layer should be made using Snapshot ChangeSets. If the dependent application (henceforth, "application") is modified using new features from the OEM layer, then it is essential that at the client site, the OEM layer be updated before the dependent application.

A restart of the application will be required if changes have been made any of the *.Startup file files or to source code files, excluding tags and pages. Any change that requires a restart of the OEM layer, including all properties marked "Restart required", will also require a restart of the application dependent on that layer.

Updates from the OEM layer to the application will be blocked by overrides in the application.

Tag instance parameters

Every tag instance in the OEM layer will be visible in the application and can be used there.

No restart required for updates: Changes made to tag parameters in the OEM layer are reflected immediately in the application excepting those that have been overridden.

Application overrides: Any property except the name can be overridden in the application.

Tag structure (child tags of defined types).

Every user-defined type in the OEM layer can be used to create new tag instances in the application.

No restart required for updates. Changes to the structure in the OEM layer will be reflected immediately in the application.

Application overrides. Possible, but discouraged. It is better to define a new type using the OEM structure as a component.
To redefine an OEM type you must have the Manage Types security privilege and the application property, CanRedefineOEMType, must be set to 1. (Review the warnings related to that property before proceeding.) New child tags can then be added and the Redefine Type command can be run in the application.
Updates to the type that are made in the OEM layer will continue to be seen in the application with one exception: Adding a child tag to the type definition in the application, then adding a child tag with the same name to that type in the OEM layer will cause an error. The child tag must be removed or renamed in the application.

Properties list of custom tag types

No restart required for updates. Changes to the structure in the OEM layer will be reflected immediately in the application.

Application overrides. Not possible under any circumstance.

Menus (page navigation, palettes)

The navigational page menu and the contents of all three palettes are stored as instances of Menu Item tags. The same rule applies as for other tag instances.

Pages and Widgets

Every page and widget in the OEM layer is visible and interactive in the application. No restart is required for updates. (Restart may be required in older versions of VTScada.)

Refer to notes earlier in this topic for the effect of AutoOverrideOEMPages.

Application properties

Every property in the OEM layer is visible in and applies to the application.

No restart required for updates, unless the property is marked "restart required". Changes to the property in the OEM layer will be reflected immediately in the application.

Application overrides. A copy can be made of any property. The properties list will still show the OEM version of the property in gray, including its current value, but the application's copy of the property will take precedence.

Code modules including reports

Every report and other module defined in the OEM layer can be used in the application.

Restart required for updates. (May vary.) Most module changes in the OEM layer will require a restart, therefore the application will also require a restart.

Application overrides. Possible by writing code. You must copy the module file (or create a new one of the same name) and declare it in the application's AppRoot.SRC file.

If the dependent application contains its own copy of a source code file or an application property, then it will ignore any changes made to those items in the OEM layer.
If the OEM layer is distributed without source code as a Snapshot ChangeSet, then the dependent application cannot obtain a copy of any of the source code. It can still set its own values for application properties. Changes to the installed OEM layer at the production site can be made only by applying a ChangeSet obtained from the development workstation.


Create an OEM Layer

As you design your OEM layer, it may be helpful to remember that as inheritance works for the VTScada layer, so it will work for yours.

Consider a new, standard application:

  • It starts with a set of tags including fonts, alarm priorities, etc. Those are copied to your new application because instances exist in the VTScada layer. If you create tags in your OEM layer, they will be copied to every new application based on your layer.
  • The new standard application does not contain any I/O tags. But, you can create new ones. I/O tags are defined in the VTScada layer, but there aren't any instances.
  • No standard application that you ever create will have an Alarm page. At least, it will never have its own instance of an Alarm page. That's because in the VTScada layer, we include only the compiled code for the Alarm page, not the source code. The next time you upgrade to a new version of VTScada, you might see a completely reconfigured Alarms page.
  • Every standard application you create will have its own copy of the Overview page as soon as you open that page in the Idea Studio. The next time you upgrade to a new version of VTScada, we might replace that with a completely new page, but you will continue to use your local copy.

Step 1

The first step is to decide whether an OEM layer would be useful for you. If any of the following use-cases apply, then yes.

  • You are a system integrator who deploys SCADA/HMI applications with similar general functionality such as wells, or gas plants.
  • Your organization uses a standard set of SCADA/HMI functionality across two or more facilities.
  • You work for an original equipment manufacturer that deploys a common user interface with their equipment, where the user interface needs minimal or no unique configuration for each equipment installation.
  • You have developers who can modify parts of your application, but you want to ensure that certain core features are out of their hands.

Step 2

Next, decide what will go into that layer. If you are thinking of including user-interface elements, consider grouping those into a widget rather than distributing the page. If you supply widgets, then at the application level, developers can add your widget to their pages and can extra information around it. If you supply pages, then what you create is what they get.

Step 3

Prepare the OEM layer for distribution. Everything you created while designing that application will show up in the applications built on your layer. Delete every tag instance that you created unless it is supposed to exist in every new application. Disabling these is not sufficient. Delete your test pages. If you changed display settings to suit yourself during development, change those back to VTScada defaults.

The Overview page is a special case. If you opened the Idea Studio while building the OEM layer, then a local copy was made of the Overview page's source code. If you distribute a Snapshot ChangeSet file without source code, then applications built on your OEM layer will treat Overview like any other page that you distribute with your OEM layer, meaning that no application built using your OEM layer will be able to edit its Overview page. If this is not desirable...

Step 3a

Delete the Overview page. (Unless you have customized it to be something that you do want to distribute as part of your OEM layer.) A warning message will inform you that the Overview page from the VTScada layer is still available.

Customize the top level of your menu system, adding the (VTScada version) of the Overview page back.

Do not open the Overview page in the Idea Studio again until after Step 4. If you do, repeat this step.

When installing the Snapshot, it is important to use "Create from ChangeSet" and never "Clone from ChangeSet". A clone will have a different GUID, and you will never be able to distribute updates to it.

Step 4

Create a ChangeSet for distribution. If you do not intend to distribute your source code and do not want the people receiving the OEM layer to be able to edit it, then create a Snapshot ChangeSet, and choose not to include the source code files.

If you are sending the application to a colleague who is helping with development, then do send a standard ChangeSet.

Step 5

Create and distribute updates. Things change, and new ideas come along. Your OEM layer will evolve. Ensure that you clean up the development tags, pages, etc. as before, then create a new Snapshot. At the destination, use the Apply ChangeSet command in the Application Configuration dialog.

If you plan to use Snapshot ChangeSets without code for your OEM layer, you will need a separate workstation (or, perhaps a virtual workstation) where you can keep the source code for the layer. What you cannot do is have both the full version with code and the snapshot version without code in the same VTScada folder.


Distribute OEM Layer Updates

If you have modified your OEM layer, then the process to distribute that change depends on how the OEM layer was originally distributed. You may also need to restart the application, depending on the type of change made to the OEM layer.

Networked applications

If your application runs on multiple servers, and is based on an OEM layer, then that OEM layer must also be present on each server. It can be difficult to maintain separate server lists for both the primary application and its OEM layer application, especially if the OEM layer is used by more than one application. Fortunately, one server list can work for both the application and the OEM layer at any site, so long as the SyncOEMLayers property is set TRUE, as it is by default. To verify, open the Application Configuration dialog of your application (the top layer application, not the OEM layer) and look for the check beside "Synchronize the configuration of OEM layers via derived applications" in the OEM Layer section of the Other properties tab.

With SyncOEMLayers set to TRUE (1), updates in the OEM layer's configuration will be distributed automatically using the application's server list as soon as those changes are deployed in the OEM layer.

Certain layers supplied by Trihedral will not synchronize automatically under any circumstance. Instructions for deployment are provided with all updates to these layers.

In rare cases, it is possible that you might not want this OEM layer to synchronize automatically. For example, you want to apply ChangeSets individually on each server, perhaps to test changes as you roll them out. Another possibility is that the update will require a full restart, and you want to control when that happens on each server. For these cases, you should add the property DoNotSyncLayer to the OEM layer application. When set, DoNotSyncLayer takes priority over SyncOEMLayers.

DoNoSyncLayer requires a full restart of VTScada, not just the application.

Snapshot Distributions

Snapshot ChangeSets without source code are run-only applications. This is the most common way that OEM layers are distributed from system integrators to clients. (ChangeSets for Distribution) Updates to the OEM layer must made be at a workstation where the OEM layer's source code resides, then distributed to clients via a ChangeSet. If you are also distributing updates to an application and those updates depend on new features in the OEM layer, then it is essential that the OEM layer be distributed first, followed by the dependent application.

Remember that ChangeSet updates can be applied only to applications having the same globally unique identifier.

After an application has been created, its name is only a display property. You can take advantage of this fact to add a version number to the OEM layer's name, and update that number each time you are ready to distribute a new set of features. Some integrators do this to help keep track of which release is installed at a site.
The name property must be updated manually.

Troubleshooting:

  • Changes made to a page or widget in the OEM layer are not showing up in the dependent application.

The OEM layer was distributed with source code. The page or widget was opened in the Idea Studio of the dependent application, causing a local copy to be made.
Use the Idea Studio to delete the local copy in the dependent application.
If it is necessary to have local variations to a page, then the OEM page should be made into a widget that can be added to a local page.

  • The OEM layer has no link to the Idea Studio.

This is by design. The OEM layer was distributed to this workstation (or server in your network) as a Snapshot ChangeSet without code. Pages and widgets within the OEM layer can be edited only on a workstation where the full version, including source code, is kept.


Branch an Application

You might want to use an existing application as a template for a new application. There are several ways to do this including copying the folders or creating a clone from a full ChangeSet. For both these methods, note that the history files for an application that's been under development for a while might be large. This includes the process I/O history (included only if copying the folder) and the development history (included with both methods).

If you want to use portions of an existing application while also making a clean start, use the following procedure.

(Reference notes: Create a ChangeSet File)

  1. Make a Snapshot ChangeSet (with code).
  2. Use Add New Application >> Advanced >> Clone from ChangeSet to make the new application.

You now have an application that contains all the features of the original but has no development or process I/O history. The new application is independent from the original and changes made to one will not affect the other.

New developers should note that ChangeSets are frequently misused. Review the warnings in ChangeSets for Distribution.


Hide a Running Application

You can configure an application to run with no user interface on selected workstations. For example, on a primary server where there is little need for user interaction. When there is a need to see the application, any authorized user can click its Show button in the VAM.

For applications that you can hide, the controls to Hide or Show the application are available only to user accounts that have the Configure privilege.

To allow hiding of an application:

  1. Open the Application Configuration dialog.
  2. Select the Edit Properties page.
  3. Open the Other tab of the Edit Properties page.
  4. Select the option to Enable the Toggle Visibility icon.

The option to log the current user off automatically is selected by default, and is recommended for most situations. If not selected, then the current user will remain signed in until the automatic logoff time is reached. Until then, anyone may click the application's Show button in the VAM and operate the application as the signed in user.

To hide an application:

You must configure an application so that it can be hidden before it may be hidden.

There are two ways to hide a running application:

  1. From the VAM, click the Toggle Visibility icon, as shown:

    If you use this option, you are not prompted to confirm the action.
  2. Click the X at the upper right corner of the main VTScada screen (provided that window was configured to include a border and the Windows® controls.)

    If you use this option, you are prompted to confirm the action.
    If you have the Application Stop privilege, the dialog will ask whether you want to hide the application or close it.


Hide the VAM

In any standard application, you can open the Other tab of the Edit Properties page of the Application Properties dialog and select "Hide VAM from users without Application Manager View privilege" (Not supported when running as a service).

This will hide the VAM only when your application is running and then only if an authorized user is not signed in. It does not require you to edit configuration files. A full restart of VTScada is required for it to take effect, restarting an individual VTScada application is insufficient.

This property applies directly to the installation of VTScada and extends to each application within the scope of that installation.

If the application is set to run full-screen without a Windows™ title bar, then there is no way for operators to stop it without the VAM. If there is a title bar with an X in the upper corner, then stopping the application will also cause VTScada to stop. The VAM will not continue to run, hidden from view, when all applications have stopped.

The security privilege, View Application Manager (Application Manager View (-40)), allows selected users to see and use the VAM while it remains hidden to all others. These users may stop the application without also causing VTScada to exit. (Assuming that they have the Stop Application privilege.)

To hide the VAM using the Application Configuration dialog:

Preparation: Ensure that security is enabled in the application and at least one account has the "View Application Manager" privilege. You will require no less than the "Configure" privilege.

  1. Open the Application Dialog
  2. Select the Edit Properties page.
  3. Select the Other tab within the Edit Properties page.
  4. Scroll down and select the option, "Hide VAM from users without ...".
  5. Click Apply to save your changes.
  6. Re-start VTScada for the changes to take effect.

When VTScada is run as a service this setting is ignored and the option to select it in the application configuration will be disabled.

To hide the VAM using Setup.INI:

Preparation: Before making this configuration change, it is essential that you configure at least one application to start automatically because without access to the VAM, you would have no way of starting any application. (Automatic Start) As a safety measure, VTScada will ignore the HideWAM setting unless at least one application is configured to start automatically.

Ensure that security is enabled within the application, and that the privilege View Application Manager is granted to at least one account.

For VTScada programmers: HideWAM is an older name for HideVAM. In Setup.INI, HideWAM is still used, but if you are creating code that refers to this property, always use the newer property, HideVAM. HideWAM is checked only on startup.

  1. Ensure that the Auto-Start option is enabled in your application.
  2. Open the Setup.INI file, located directly within the VTScada installation directory, using the text editor of your choice.
  3. The property HideWAM should exist. If not, add it (or better: HideVAM) within the [System] section.
  4. Set the property equal to 1.
[SYSTEM]
HideVAM = 1
  5. Save and close the Setup.INI configuration file.
  6. Re-start VTScada.

The VAM is hidden automatically.

  7. [Optional] Grant the general privilege View Application Manager to other selected accounts or roles.

When VTScada is run as a Windows service, this setting is ignored.


Remove an Application

At any time, you can choose to remove an application from the VAM's list of those available to run. The choices you make while doing so will determine whether this removes only the application's name from the list or if it deletes the application entirely from your computer.

To remove an application:

  1. In the VAM, select the application that you want to remove.
    Additional tools will be displayed.
  2. Click on the Remove button (trash can image).

A prompt will ask you to confirm that you want to remove the application.

Remove Application prompt 1

  3. Click "Yes"

A prompt will ask whether to keep the application's directory and files.

Remove application - confirmation 2

  4. Click Yes to keep the directories and files or No to delete them.

The application will be removed from the VAM.

There is no further confirmation dialog after this - choosing No will remove the application and all of its files from your computer.

OEM layers that have dependent applications may not be removed, but you can hide them. The process is the same except for the displayed prompts.


Edit Properties

Properties control how VTScada looks and how it works. For example: if you would like to silence all alarm sounds while you’re building an application you can set AlarmSoundDisable to 1. If you prefer that each new tag not start with the same configuration as the last one, set RememberNewTagParameters to 0. And if (for example) you’re using typed Modbus addressing, you need to consider whether ModiconTypedAddr1Offset needs to be set to 0 or 1.

The list goes on for thousands of properties.

To adjust properties for your application, the first step is to open the Edit Properties tab of the Application Configuration dialog.

In the Application Properties dialog, only a few dozen properties are available in the Basic mode. Most can be found in the Advanced mode but not all. There are also...

  • Hidden properties.
    Most are hidden so that access can be better controlled. You can view these by opening a configuration file, but only an authorized user can import any changes.
  • System properties.
    Affecting the VTScada program itself rather than an application, these properties are stored in Setup.INI, found in the installation folder. Changes to that file do not take effect until VTScada itself is restarted.

Open the Application Configuration dialog

Toolbar button for the Application Configuration dialog

The Application Configuration tool

The Application Configuration dialog contains a large collection of tools in addition to the Edit Properties page.

After security is enabled, you will need the Configure privilege to open this dialog.

Open the Application Configuration Dialog from the VAM:

  1. In the VTScada Application Manager (VAM), select the application.
  2. Select Application Configuration.

Open the Application Configuration Dialog from within an application:

  1. While an application is running, select the Configure button.

Open the Application Configuration Dialog from within the Idea Studio:

  1. Open the Idea Studio.
  2. Expand the File menu.
  3. Select Application Configuration.

Keep a tidy development environment. If you leave the Application Properties dialog open while you (or others) work on other tasks, you can expect to see warnings that settings may have changed, even though the change may have been to a file that doesn't affect configuration properties. Also, while a tag properties dialog is open, certain other development tools will not open.
When moving from one development tool to another, unless you plan to return to the first immediately, it is better practice to close the first window before opening the second.

Unsaved Changes

If you make changes in the Application Configuration dialog, then navigate to a different page, or close the configuration window, you will see the following message.

Unsaved changes warning dialog

Warning for unsaved changes on the Edit Properties page.

Click Yes to discard the changes and continue navigating or No to retain the changes and continue working on the same page.


Edit Properties with the Basic Mode

The most changed configuration properties are available in the four tabs of the Basic mode of the Edit Properties page of the Application Configuration dialog. All of these can be changed without restarting the application.

The Display Tab of the Edit Properties page

The Display Tab:

Properties that control the appearance of application. See: Display Tab of the Edit Properties Page

The Alarms Tab:

More than alarm properties, this includes control of the Alarm Notification System and email configuration for both the notification system and reports. See: Alarms Tab of the Edit Properties Page

Historical Data Viewer Tab:

Control the appearance of the HDV when viewed as a page or pop-up. See: Historical Data Viewer Tab of Edit Properties

Other:

Control VTScada's automatic functions including change deployment and prompts for comments. Also controls overall visibility. See: Other Tab of the Edit Properties Page


Display Tab of the Edit Properties Page

Use the Display tab to set the general appearance and behavior of the windows within your application.

Click to expand

General options set the overall appearance of the application. Window behavior options include control over the what operators may do to modify the window size, which page is the default at startup, the default background color for new pages and whether page content should stretch to fit the page. (That last option is better controlled in the Idea Studio).

Default size and minimum allowed size can both be set, measured in pixels, and you have control over the content of both the title bar and the navigation bar. The display tab also provides controls over map features including minimum and maximum zoom levels, the allowed area within which maps are shown, and the ability to do a bulk download of map tiles, to be cached on the local server.

General

Property | Stored as | Description
Application Name | Name | Holds the displayed name of the application. Changes to this property do not affect the path to the application folder.
Icon on VAM | VAMIcon | Select any image to be used to represent the application in the VAM. Images larger than 38x20 pixels will be scaled to fit. In order for the icon to blend smoothly into the VAM, rather than appearing as a rectangle, any pixels in the image file that are not a part of the actual icon should be transparent.
Color Theme | AppTheme | Select the overall color theme for the application. This controls the title bar, navigation bar, dialogs, and the color used for the application in the VAM.

Application Window Behavior

Property | Stored as | Description
Full screen without borders DispMgrFullScreen When selected, options for the window size and title bar decorations are disabled. The application will fill whatever screen it is displayed within.
You should design the application to fit the smallest screen that it will be displayed on.
Resizable border DispMgrResizable

Operators may drag the window borders to the size they want to view. Scroll bars will be added if the application size exceeds the window.
Options to control the window size become available.
Title bar decorations may be configured.

The property, DispMgrResizable, is treated as 0 (false) when using multiple display windows with DispMgrHoriz, DispMgrVert

Fixed size window (a combination of the above two properties) Width and height may be set in the following section.
Minimum window size options are not relevant.
Constrain aspect ratio DispMgrAspectRatio This option is available only when the resizable border has been selected.
Any change to one dimension of the page is matched by a change to the other.
Disable min\max buttons | DispMgrMinMaxDisabled | Only available in combination with resizable border option.

Application Window Size (Values measured in pixels.)

Property | Stored as | Description
Width | DispMgrWidth | Sets the initial width of resizable windows. Sets only the width of constrained windows.
Height | DispMgrHeight | Sets the initial height of resizable windows. Sets only the height of constrained windows.
Minimum width | DispMgrMinWidth | Only for resizable windows, ensures that the width is no less than this value. Does not apply to constrained or full-screen windows.
Minimum height | DispMgrMinHeight | Only for resizable windows, ensures that the height is no less than this value. Does not apply to constrained or full-screen windows.

Page Behavior

Property | Stored as | Description
First page at startup Page

Choose which page will be shown upon application startup. You may return to the last page viewed, or use the drop-down list to select any page in the application.

If you choose a parameterized page, you should set the values that will be used for those parameters using the Set Page Parameters button. Failing to do so will result in the operator being prompted for parameter values when the application starts.

Background color | DefaultPageColor | Sets the default color for all pages that have not been configured with their own background color.
Stretch contents ScaleDisplayContent

When selected, the page display will be scaled to fill the available area of each window, excepting the editor window.

This option is useful in the case that the application is displayed full-screen on many computers, each having a different screen size.

Automated display scaling works reasonably well when enlarging the page. It cannot do as good a job when shrinking a display for a smaller screen. In particular, labels embedded within buttons or widgets are more likely to be truncated than scaled down.
Always design for the smallest screen that the application will be displayed upon. Further information is provided in Size Pages for Differing Screens

Maintain aspect ratio | MaintainAspectRatio | If set to 1 (true), then pages will maintain their aspect ratio when stretched.

Map

Property | Stored as | Description
Minimum zoom level | SlippyMapMinZoomLevel | The minimum (furthest out) zoom level allowed.
Maximum zoom level | SlippyMapMaxZoomLevel | The maximum (closest in) zoom level allowed.
Set area limiting | MapAreaLimiting | See: Limit the Map Area
Bulk download | Not a property | See: Bulk Downloads of Map Tiles

Title Bar Contents

Configuration may be set independently for the standard display (Normal page) and for pop-up pages. When selected, the default is to use all decorations for the normal page and no decorations for pop-up pages.

The title bar includes ten separate items, each of which may be displayed or suppressed. The title bar itself must be selected for display in order for any of the decorations to have meaning.

Time format & date format:

Use the selectors to choose how time and date should be displayed in the title bar. If the available options do not include the format you prefer, open the Advanced Mode and change the values for DispMgrDateFormat and DispMgrTimeFormat.

Task Bar Contents

As with the title bar, configuration may be controlled independently for a normal page and for pop-up pages. The default is to show all task bar tools on the normal page and none on a pop-up page. As of release 11.2.23, independent control is available for the tiled menu and the list menu.

Page buttons are added by operators, and are unique to each operator. Choosing "Show Page Buttons" does not cause any to appear if the operator has not added them using the pin button, but deselecting the option will cause an operator's page button shortcuts to vanish.


Alarms Tab of the Edit Properties Page

Use the alarms tab of the Edit Properties page to set general appearance and behavior of alarm displays and the VTScada Alarm Notification System.

Click to expand

Visual options set where and whether alarm indicators flash, whether pop-up notifications can be configured, and the time and date display format. You can disable alarm sounds or have the server speak a message instead of using the default tones. Automatic page navigation can be enabled so that a relevant page opens automatically when there is no user-activity for a period of time, and you can choose to require notes to accompany operation actions such as acknowledging or shelving an alarm.

This is also the place to configure the Alarm Notification system, setting which priority of alarms will be sent, delays, notification rules and whether digits should be spoken as operators press the keys on their phone.

If using a mail server for alarm notifications or reports, Twilio® or VoIP for alarm notifications, configure the connection parameters here.

Visual Indicators

Property | Stored as | Description
Flash alarm icon in title bar when there are unacknowledged alarms.

AlarmIndDisable

AlarmIndDisableOnVIC

When selected, the alarm icon in the title bar will flash rather than simply showing red.

If your internet connection is limited by bandwidth restrictions, we recommend that you do not enable this option for the VIC display.

Flash task bar red when there are unacknowledged alarms AlarmFlashTaskBar

AlarmFlashTaskBarOnVIC

When selected, the entire task bar will flash red while there are unacknowledged alarms that are visible to the logged-on user.

If your internet connection is limited by bandwidth restrictions, we recommend that you do not enable this option for the VIC display.

Flash title bar red when there are unacknowledged alarms

AlarmFlashTitleBar

AlarmFlashTitleBarOnVIC

When selected, the entire title bar will flash red while there are unacknowledged alarms that are visible to the logged-on user.

If your internet connection is limited by bandwidth restrictions, we recommend that you do not enable this option for the VIC display.

Flash unacknowledged alarms in alarm lists FlashUnackedAlarmsOnServer
FlashUnackedAlarmsOnVIC 		When selected, unacknowledged alarms in the alarm list will flash, to draw operator attention.
Separate options exist for the server and VIC Closed VTScada Internet Client. Allows you to connect to an application over the Internet with many of the features of a full VTScada workstation. displays.
If your internet connection is limited by bandwidth restrictions, we recommend that you do not enable this option for the VIC display.
Highlight unacknowledged alarms in alarm list HighlightUnackedAlarms
When selected, unacknowledged alarms will be shown with a highlight color in alarm lists.
Use priority color for alarm list text. AlarmListUsePriorityTextColor When selected, text for the alarm in the Alarm Page and Alarm List uses the priority color.
Otherwise, white text is used on a dark background, and black when the background is light.
Allow pop-up notification when alarm trips | AlarmPopupsEnable | Pop-up alarm notifications must be enabled on an alarm-by-alarm basis, but may not be enable at all unless this option has been selected.
Require confirmation when Acknowledge All is clicked | AckAllRequiresConfirmation | Operators must click through a confirmation dialog when attempting to acknowledge all the alarms shown in the list.
Time format in alarm list | AlarmDisplayTimeFormat | Choose how time will be shown.
Date format in alarm list | AlarmDisplayDateFormat | Choose how dates will be shown.

Sounds and Speech

Property | Stored as | Description
Disable all alarm sounds | AlarmSoundDisable | When selected, alarms will be silent.
Speak alarms instead of playing sounds | AlarmSpeechEnable | Enables spoken alarms on the server. Other configuration may be required. See: Spoken Alarms on the Server or Workstation
Configure speech lexicon | file: Lexicon.VLX | Opens the Configure Lexicon dialog, where you may adjust the pronunciation of words phonetically.

Alarm Behavior

Property | Stored as | Description
Automatically acknowledge alarms when they clear | AutoAckClearedAlarms | If set, all alarms in the application will be set as acknowledged automatically upon clearing (the trigger condition returning to normal)
Enable the Acknowledge All button | AckAllEnable | Deselect if operators must acknowledge alarms individually.
Require confirmation when Acknowledge All is clicked | AckAllRequiresConfirmation | Useful when Acknowledge All is permitted. Requires confirmation that the operator intended this action.
Log all suppress and unsuppress events | RecordSuppressionStatus | Alarm suppression is typically automated. Ensure these are selected to record an event for each action.

Automatic Page Navigation

Property | Stored as | Description
Enable automatic page navigation when an alarm triggers | AlarmAutoNavEnable | When selected, new alarms will cause the application to open a page where the alarm tag (or triggering tag) is displayed. If drawn on several pages, VTScada will decide the most suitable. If drawn on none, the alarm page will open.
Open the target page in a pop-up window. | AlarmAutoNavWindowed | Relevant only if the preceding option is also selected. Causes the automatically-opened page to be opened in a pop-up window if possible. Ignored if the page is configured to never open in a pop-up window. Subject to limits imposed by PopupPageLimit.
Time without user activity preceding an alarm, to enable automatic navigation. | AlarmAutoNavTimeout | Automatic navigation will occur only if there has been no user activity for the set number of seconds preceding the alarm.
Minimum time to display a page after switching to it. | AlarmAutoNavHold | Number of seconds to hold one automatically-opened page before another may open. Has no effect on operator navigation.

Alarm Notes Properties

Property | Stored as | Description
Require note when acknowledging alarm | NoteRequiredForAck | When set, operators must create a note when acknowledging an alarm. Notes will be added to the notebook associated with the alarm's database.
Minimum length of acknowledge note | NoteMinLengthForAck | Minimum length of acknowledge note. If a minimum length is not provided, the note dialog will open, but operators can click OK to close it without saving a note. (Empty notes will not be recorded.) This may be useful if notes are suggested, but not required. Set a minimum length to enforce note creation. This will be true of the following properties as well.
Require note when shelving alarm | NoteRequiredForShelve | When selected, operators must add a note when shelving an alarm.
Minimum length of shelving note | NoteMinLengthForShelve | Minimum length of shelve note.
Require note when unshelving alarm | NoteRequiredForUnshelve | When selected, operators must add a note when unshelving an alarm.
Minimum length of unshelving note | NoteMinLengthForUnshelve | Minimum length of unshelve note.

Alarm Notification. See also: Alarm Notification Options

The options in this section apply only to VTScada licenses that include the Alarm Notification System.

Property | Stored as | Description
Notification priority: Do not notify on alarms Notify on priority 1 alarms only Notify on priority 1 or 2 alarms | CallOutPriority | Use the options in this section to control which priority-level alarms will be sent to remote operators. The choice made here affects the following two options, since a delay before notifying does not apply to alarms that are sent. Note that when Notify on Priority 1 is set, Priority 2 alarms will also be read on a voice call, but only priority 1 alarms will cause a notification to be sent.
Delay to notify on priority 1 (critical) alarms | CallOutDelay1 | Controls the number of seconds that VTScada will wait for a priority 1 alarm to be acknowledged by a local operator before it is sent to a remote operator. Can be set independently within each Roster tag.
Delay to notify on priority 2 (high) alarms | CallOutDelay2 | Controls the number of seconds that VTScada will wait for a priority 2 alarm to be acknowledged by a local operator before it is sent to a remote operator. Can be set independently within each Roster tag.
Delay between calls | RosterDelay | Controls the default length of time that VTScada will wait between making calls. The call sequence is controlled by a roster, configured within the application. If the roster fails to send a notification to one contact, no delay is used before attempting the next (if any).Can be set independently within each Roster tag.
Initial section | IncomingCallSection | Alarms sent by phone are organized according to a menu. You may choose which page of the menu will be spoken first, allowing operators to immediately hear the most relevant information without needing to step through a menu.
Echo phone through speaker | EchoPhoneThroughSpeaker | If the server has a properly configured sound card and speaker, alarms that are dialed out can also be spoken at the server.
Answer Inbound Calls | AnswerAlarmCalls | Controls whether inbound calls are answered. If not selected, this prevents the Alarm Notification System audio discriminator from being registered with the Modem Manager. This would be useful in an application where the Alarm Notification System is not being used for incoming voice calls, but other drivers are registered for incoming data calls. 30 seconds of time can thereby be saved from each inbound call. Not to be confused with the Modem Manager property, AnswerCalls.
Dial when alarm triggers | DialOnActive | Controls whether active alarms should dialed out.
Dial when alarm clears | DialOnClear | Controls whether the alarm system will dial out when the alarm clears.
Cancel call when alarm is acknowledged | DialCancelOnAck | If one operator acknowledges the alarm while the notification system is calling another, this option will cancel the phone call.
Cancel call when alarm clears | DialCancelOnNormal | Controls whether unacknowledged alarms whose condition has become normal should be dialed out to operators
Speak digit on phone key press (VoIP or Voice Modem only) | DialDTMFFeedback | Controls whether all phone key presses are spoken back to the user.

Outgoing Alarm Emails

Email configuration is discussed in greater detail in the topic, Email Configuration for Alarms and Reports. The following properties are repeated there. OAuth2 configuration is discussed only in that topic.

These properties are stored in an encrypted format, and cannot be modified in the Settings.Dynamic file.

Customers using basic authentication (username and password) with either Microsoft or Google email accounts must start using OAuth 2.0 or switch to another email provider. For Google, the change-over date was May 30, 2022. For Microsoft accounts, the change-over is scheduled began in October 2022. Refer to Google & Microsoft vs Basic Authentication

Protocol | Only SMTP is allowed.
Email server name or IP | The name or IP address of your email server. This information should be available from your system administrator or your email provider. It will typically take the form: "mail.yourcompany.com" for an internal email server or, using Google’s Gmail as an example, "smtp.gmail.com".
Email server port number | The port number used by your email server. Always check with your provider to determine the port to use, but for most local email server programs, this will be 25. If using Transport Layer Security, the port will usually be 587.
Email transport layer security | Controls whether TLS is used for communications. This is required by most email servers.
Email from address | The text you fill in here will be used in the FROM: field of all emails sent by the system. Note that some email servers will check that this is a valid email address and will reject the message if it is not. If you are configuring for alarm acknowledgment by email, this field must include the email address configured in the Incoming Alarm Email Acknowledgments section. The field may also contain a common name as well as the address. For example: "VTScada System" <VTSSystem@YourCompany.com> Multiple addresses may be used, separated by semi-colons. In the case of alarm acknowledgment by email, the other addresses will be each receive a copy of the acknowledgment.
User name | The account name on your SMTP server, if it is using username / password authentication. Disabled if you are using OAuth2 authorization
Password | The password for the account if using username / password authentication. If using Microsoft or Google and not using OAuth 2.0 then you are advised to obtain an App Password as described in Google & Microsoft vs Basic Authentication Disabled if you are using OAuth2 authorization. Both the user name and the password are encrypted for storage.
Use OAuth 2.0 | Disables both User name and Passwords fields. Enables access to the OAuth 2.0 configuration dialogs in the VTScada security system. See: OAuth 2.0 Protocol
Grant | Select which OAuth 2.0 grant should be used if more than one has been configured.
Consent | Initiate the consent process for the selected grant in order to use that email service.
Revoke | Revoke consent for the selected grant, ending the ability to use the email account configured with that service.

Incoming Alarm Email Acknowledgments

These properties are stored in an encrypted format, and cannot be modified in the Settings.Dynamic file.

Note that the "ack" code in outgoing emails is controlled by the presence of a contact user name in the Roster, not by whether incoming email acknowledgments are enabled.

Customers using basic authentication (username and password) with either Microsoft or Google email accounts must start using OAuth 2.0 or switch to another email provider. For Google, the change-over date was May 30, 2022. For Microsoft accounts, the change-over is scheduled began in October 2022. Refer to Google & Microsoft vs Basic Authentication

Protocol | Only POP3 is allowed.
Email server name or IP | The name or IP address of your email server. This information should be available from your system administrator or your email provider. It will typically take the form: "pop.yourcompany.com" for an internal email server or (using Google’s Gmail as an example) "pop.gmail.com".
Email server port number | The port number used by your email server. Always check with your provider to determine the port to use, but for most local email server programs, this will be 110. If using Transport Layer Security, the port will usually be 995
Email transport layer security | Controls whether security is used for communications. This is required by some email servers, such as Google’s Gmail.
User name | Use if your POP3 email server requires username / password authentication. Disabled if you are using OAuth2 authorization.
Password | The password for your POP3 server account, if it is using username / password authentication. If using Microsoft or Google and not using OAuth 2.0 then you are advised to obtain an App Password as described in Google & Microsoft vs Basic Authentication Disabled if you are using OAuth2 authorization. Both the user name and the password are encrypted for storage.
Maximum message size in bytes | Reject any message larger than this size. Use this field to block emails with large attachments, which might otherwise delay legitimate alarm acknowledgments.
Use OAuth 2.0 | Disables both User name and Passwords fields. Enables access to the OAuth 2.0 configuration dialogs in the VTScada security system. See: OAuth 2.0 Protocol
Grant | Select which OAuth 2.0 grant should be used if more than one has been configured.
Consent | Initiate the consent process for the selected grant in order to use that email service.
Revoke | Revoke consent for the selected grant, ending the ability to use the email account configured with that service.

Twilio Account Settings

Refer to Using Twilio for Alarm Notifications for further information.

You must have a Twilio account before configuring these settings. Refer to https://www.twilio.com/try-twilio.

A Twilio account can be used in place of a modem for sending voice calls with the VTScada Alarm Notification System.

Enable Twilio | Select before proceeding with the following configuration options.
Workstation Should be set to the name of the workstation that connects to your Twilio account. Must be set if you have multiple callback domains or Twilio accounts or you have configured Voice Call Redundancy. When set to the name of a workstation, all other properties in this section are saved to their own file for Workstation-Specific Properties
Note that when using multiple alarm notification servers with Twilio, each server requires its own fixed IP address or FQDN on the public Internet.
Twilio account SID | Your Twilio account identifier
Twilio auth token | Your authentication token, provided by Twilio.
Domain for Twilio verification

The domain, at which Twilio can reach your VTScada server. In most cases, this will be a direct connection to your secured server and will take the form "trihedral.com" for a domain of "https://www.trihedral.com".

Some sites make use of a secured proxy device that forwards connections to the VTScada server (secured or unsecured). In this case, the domain should be specified in the form "https://ProxyServer.com:123".

Twilio requires an HTTPS POST verification exchange with your site (either directly to the server or via a proxy). Your server must be visible to the Twilio server without the use of a VPN.

Realm for Twilio verification

The corresponding realm that you created for your application.

Do not use a realm defined for Realm Filtering.

Prefix for phone numbers

Use for situations where some of your VOIP providers require E.164 format, and some do not. For example, if your application is configured to use an HT813 modem and also Twillio SIP trunking.

The typical value would be "+1".

VoIP Closed Voice over Internet Protocol Settings

Refer to Using VoIP for Alarm Notification for further information.

Workstation | Should be set to the name of the workstation that connects to your VoIP device or system. Must be set if your system has multiple VoIP devices or you have configured Voice Call Redundancy. When set to the name of a workstation, all other properties in this section are saved to their own file for Workstation-Specific Properties

Enable VoIP Calls

If this box is selected, your application will use your VOIP settings for voice-based alarm notification. It will not use Twilio or voice modems, even if those are configured.
Enable VoIP SMS

If this box is selected, your application will use your VOIP settings for SMS-based alarm notification.

This feature works only with providers who support SMS and have enabled the MESSAGE extension for SIP. It does not work with Grandstream devices.

SIP identity

The unique SIP Closed Session Initiation Protocol. Used in connection with Voice over Internet Protocol. uniform resource indicator URI Closed Uniform Resource Identifier. URIs Identify, whereas URLs Locate. In many cases, a URI looks a lot like a URL.) that identifies the application. The scheme for this URI is defined in RFC 3261.

If you have an internal VOIP PBX Closed Private Branch Exchange. A private telephone switchboard. or virtual PBX, your phone system administrator must assign this to you. It will typically take the form, sip:11235551234@sip.myorg.com:5060

The port specification (:5060)is optional unless you have changed the property, VOIPPort, in your Setup.INI file.

If you are using a VoIP-to-FXO Closed Foreign Exchange Office device, the identifier before the "@" sign may be configured arbitrarily. (For example: sip:bob@bob.mydomain.com). You would use this same URI to configure incoming calls from the VoIP-to-FXO device.

In all cases, the fully qualified domain name (FQDN) of the server that VTScada is running on must follow the "@" symbol.

SIP server

If you are using an internal VOIP PBX, ask your phone system administrator for this information.

If you are using a VoIP-to-FXO device you may be able to leave this blank. (SIP INVITE requests go directly to the device instead of via the server.)

SIP proxy

If you are using an internal VOIP PBX, ask your phone system administrator for this information.

If you are using a VoIP-to-FXO device you may be able to leave this blank (SIP INVITE requests go directly to the device instead of via the proxy)

SIP domain

If you are using an internal VOIP PBX, ask your phone system administrator for this information. Typically this is the domain part of your SIP URI. For example,, if the SIP URI is "sip:11235551234@sip.myorg.com:5062", the domain field is "sip.myorg.com".

If you are using a VoIP-to-FXO device this is the IP address of the device.

SIP login user ID

If you are using an internal VOIP PBX, ask your phone system administrator for this information.

If you are using a VoIP-to-FXO device this might be blank, depending on the device. Refer to the device documentation.

SIP password

If you are using an internal VOIP PBX, ask your phone system administrator for this information.

If you are using a VoIP-to-FXO device this might be blank, depending on the device.

Prefix for phone numbers

Use for situations where your VOIP providers require E.164 format, and some do not. For example, if your application is configured to use Twillio elastic SIP trunking, a "+1" is common.

An HT813 ATA would not use a prefix.

Use for two-stage dialing. (ex. Dial 9 to get an outside line, pause for connection, dial number). Use a comma (,) to create a 2 second pause. (ex. "9,9025551234").

Dial pause length | The length of a pause indicated by a comma in "Prefix for phone numbers" is 2 seconds by default. To change the length of the pause enter a new number (in seconds).
Use SIPS

Select this box to enable encrypted VOIP.

This option should ALWAYS be selected if you are using an external SIP trunking provider or other VOIP service provider.

If using an ATA adapter such as the Grandstream HT813 or an internal VOIP PBX, this option should be selected ONLY IF required by your configuration of that device.

Enable IP address rewrite | If you are having problems with audio on VOIP calls, particularly if your VTScada workstation is on two networks, deselecting this box may help to resolve the issue.


Historical Data Viewer Tab of Edit Properties

Use the Historical Data Viewer (HDV) tab of the Edit Properties dialog to control how the HDV looks.

Properties include a set that control which elements of the HDV are enabled, how those elements appear and whether notes require extra authentication. A set of color selection boxes are provided, controlling colors for all elements of the HDV display.

Click to expand

The property HDVMaxDataSources is not included in this list but may be of use. This property limits the number of pens that will be displayed on a plot. The default is 100. Use the Advanced Mode to change the value.

General

Property | Stored as | Description
Show plot time selection scrollbar | HDVDisplayTimeSelectionScrollBar | Enables a scrollbar that operators can use to view values that no longer show in the current Plot display. Does not apply to the Grid display.
Show plot time scales | HDVShowTimeScales | Enables the display of time values below the plot so that operators can know when events occurred. Does not apply to the Grid display.
Show plot legend | HDVLegendVisible | Enables the display of the list of pens that are included in the plot. The legend includes a link to configure each pen's display properties, a command to hide or reveal the pen, and a set of statistics which update as the cursor is moved across the displayed time.
Use simple legend | HDVSimpleLegend | Applies only if the plot legend has been enabled. All statistics other than value at cursor position are removed from the legend when this option is enabled.
Sort grid in ascending order | HDVGridViewSortOrder | If selected, the grid tab will have the most recent time at the top of the list. When not selected, the most recent time is at the bottom of the list.
Add Note requires extra authentication | NoteAddRequiresAuthentication | When selected, operators who are adding notes to the Operator Notes page or to the Notes tab of the HDV will be prompted to confirm their identity by providing their user name and password. The note will be attributed to the user name used for confirmation, which might not be the same as the logged-on operator. Applies to all instances of the Operator Notes interface.
Use automatic min/max scales when plotting analog values | HDVAnalogPenAutoScaling | Sets the behavior of auto scaling of analog pens in the Historical Data Viewer when the Analog Pen Property, "Use System Default" is selected.
Time format | HDVTimeFormat1 and HDVTimeFormat2 | Use the drop-down selection to choose the format used to display time stamps. The display adjusts automatically, choosing the time format property or date format property that is most appropriate for the time span included in the graph or grid. The "seconds" part may be hidden as the display adjusts automatically for a restricted size.
Date format | HDVDateFormat1 and HDVDateFormat2 | Use the drop-down selection to choose the format used to display dates. The display adjusts automatically, choosing the time format property or date format property that is most appropriate for the time span included in the graph or grid. The "years" part may be hidden as the display adjusts automatically for a restricted size.

Colors

Property | Stored as | Description
General Background | HDVLayoutBGColor | The general colors relate to the overall configuration of the page outside the plot, grid and legend. This general background color is also used for the Operator Notes page.
General Text | HDVLayoutTextColor | Sets the color used for text outside the plot area.
Plot Background | HDVPlotBGColor | Plot colors relate to all components within the plot area.
Plot Text | HDVPlotTextColor | Sets the color used for text within the plot area.
Plot Grid Lines | GridLineColor | Sets the color used for the grid lines of the plot area.
Plot Cursor Line | HDVTimeCursorColor |
Grid Background | HDVGridCellColor | Grid colors relate to all components within the grid list.
Grid Text | HDVGridTextColor |
Notes Background | HDVNotesBGColor | Notes colors relate to all components in the notes tab. These colors apply to both the Notes page of the HDV and the Operator Notes page.
Notes Text | HDVNotesTextColor |


Other Tab of the Edit Properties Page

Use the Other tab of the Application Configuration dialog to set fundamental behaviors for your application. Properties here control whether local changes are deployed automatically, whether the application starts automatically when VTScada starts, whether comments are required when applying changes and whether the running application is visible.

For applications that are (or are based on) OEM layers, you can control visibility in the VAM, the ability to run the application, and whether OEM applications should be synchronized along with the dependent application across your network.

You also have control over whether the VAM is visible to users without the required privilege, whether the splash screen should be shown at startup, and (referring back to applications that are hidden while running) whether a Toggle Visibility control is available.

Click to expand

Application

Settings that affect only the current workstation.

Automatically deploy local changes.

AutomaticDeploy - Stored in Setup.INI. If not selected, all changes made to this application will be local until you use the Deploy Changes option of the Application Configuration dialog.

Automatically start the application when VTScada starts.

AutoStart - It is often the case that the sole purpose of a workstation is to use VTScada to monitor and control equipment. Because the VTScada application is often the only program that will run on that computer, it makes sense to configure it to start automatically.

Disable comment dialog when applying changes.

RepositoryCommentDisable - The comments you type when applying a change may be the only record of why the change was made.
Although not advised, you may select this option to disable the comment dialog.

OEM Layer

Settings that should be used only for applications that serve as OEM layers.

Don't show this layer in the VAM.

HideFromVAM - Applications must be loaded into the VAM to be used as an OEM layer, but you may wish to hide them for various reasons.

Don't allow this layer to run.

DoNotStart - Applications that serve as OEM layers are seldom run. Check this option to prevent operators from starting yours.

Synchronize the configuration of OEM layers via derived applications.

SyncOEMLayers - It can be difficult to maintain a server list for both the primary application and its OEM layer application, especially if the OEM layer is used at more than one site. You should therefore set this property.
When set to 1 (true), the OEM layer will use the dependent application's server list when synchronizing configuration changes.

In general, SyncOEMLayers should be set. Use DoNotSyncLayer for the case where OEM layers should be updated individually rather than synchronized automatically.

DoNoSyncLayer requires a full restart of VTScada, not just the application.

VTScada Application Manager

These Setup.INI file properties apply to VTScada in general.
Changes do not take effect until VTScada is restarted.

Hide the VAM from users without the Application Manager View privilege.

HideVAM - Prevent tampering by hiding the VAM from all but authorized users.

HideVAM has no effect unless the application is configured to start automatically. DO NOT SET HideVAM unless at least one account has the View Application Manager privilege. (This property will affect unsecured applications, in which case nobody will be able to see the VAM because nobody has the required privilege.)
When HideVAM is set, the VAM will stop when all applications stop.

Don't show the splash screen at startup.

NoSplash - Speed VTScada startup by skipping the splash screen.

Enable the "Toggle Visibility" icon on the VTScada application list.

EnableShowHide - If enabled, authorized users can hide the application while it continues to run.

When hiding an application, log the current user off.

LogOffUponHide - EnableShowHide must be set. Forces a log-off when the application is hidden.

SNMP Agent

Configuration properties for the single SNMP Agent service running in an application.

SNMP password must be entered using this form in the basic mode. These are encrypted before storage and cannot be added or edited successfully using the advanced mode.

Server Port Tag

Sets the SNMPAgentIPListenerapplication property. This should be a valid IP Network Listener tag.

Inform Retry Limit

Sets the SNMPAgentInformRetryLimit application property. This specifies the number of retries on failure to send an SNMP Inform message.

Inform Retry Interval

Sets the SNMPAgentInformRetryInterval application property. This specifies the delay between retry attempts for SNMP inform messages.

SNMP Version

Sets the SNMPAgentSNMPVersion application property.

Remaining properties vary depending on the SNMP version.

(v2) Read Community String

Provide the community string that allows read-only access to your device.

(v2) Read/Write Community String

Provide the community string that allows read / write access to your device.

(v2) Trap Community String

Provide the community string used when an SNMP trap is sent by a device.

(v3) Minimum v3 Security Level

There are three levels:

No Security - Authentication and Privacy settings are disabled and not used for all user names.

Authentication Only - Authentication Passwords and Authentication Protocol settings are enabled.

Authentication and Encryption - As for Authentication Only, plus the Privacy Password and Privacy Protocol settings are enabled.

(v3) Usernames

There are three username fields. For each, there is a matching set of passwords and protocols for authentication and privacy, which are enabled according to the selected minimum security level.

Read Only Username - Username given read only permissions within the VTScada agent.

Read/Write Username - Username given read and write permissions within the VTScada agent.

Trap Username - SNMP Username used when sending traps from the VTScada SNMP Agent.

As noted, for each of the above there are options to configure the Authentication Password, Authentication Protocol, Privacy Password and Privacy Protocol.

(v3) Authentication Password

Authentication password associated with the matching username. This value is stored in an encrypted format and never visible as plain text. To enable this field, the security level must be set to at least Authentication Only.

After moving the cursor away from the edit field, the value must be fully cleared and re-typed if a change to the value is required.

(v3) Authentication Protocol

Sets the encryption used for the matching authentication password. Choose between MD5 and SHA-1 as required by your system. To enable this field, the security level must be set to at least Authentication Only.

(v3) Privacy Password

Privacy password associated with the matching username. This value is stored in an encrypted format and never visible as plain text. To enable this field, the security level must be set to Authentication and Encryption.

After moving the cursor away from the edit field, the value must be fully cleared and re-typed if a change to the value is required.

(v3) Privacy Protocol

Sets the encryption used for the matching authentication password. Choose between MD5 and SHA-1 as required by your system. To enable this field, the security level must be set to Authentication and Encryption.


Edit Properties with the Advanced Mode

While the Basic mode is useful, many more properties can be found by clicking the Advanced Mode button at the lower-right of the Edit Properties dialog. This changes the view to a list of all properties in effect for this application, including those configured in OEM layers. These give you extensive control over how your application looks and works.

These notes do not attempt to describe each of the over 1000 properties available. You are encouraged to refer to the property reference section of the VTScada documentation to explore the options.

To switch from Basic Mode to Advanced mode, look for the button at the lower right of the Edit Properties dialog.

Edit Properties dialog - Advanced Mode button

Advanced mode button

... Changes the display to...

The Edit Properties screen

Edit Properties - Advanced Mode

The Application Configuration dialog will add properties only to the .Dynamic file. Any property that belongs in .Startup must be added using a text editor and then the changes imported. (Import File Changes Tool)
Existing properties in either file can be changed using the Application Configuration dialog.

Gray font / Black font?

Properties displayed in a black font are defined in the current application and can be edited there. Properties displayed in a faint gray font are defined in a lower layer. These OEM properties affect your application but cannot be modified within it.

Local vs OEM application properties

Gray versus black font in the Properties list

To override a gray (OEM) property, select it, then use the Copy button to copy it to your application. After copying, you can change the local instance to the value you want. Changes made to that property in the underlying application will no longer affect your application.

Tools for the Advanced Mode

The following tools are available to help you work with the property list in the advanced mode:

  • "Hide OEM Properties" removes all but the local properties from view.
  • Filter the list by entering a portion of a property name and the * wildcard, then press enter or press the filter button. For example, enter Disp* to find most Display Manager properties.
  • Sort the list by clicking on any column header. Reverse the sort order by clicking a second time.

Property Attributes

Every property has seven attributes, which can be seen in the seven table headings. These are:

Property Name

Simply, the name of the property. Must be a single word.
Most properties are described in the Reference chapters of the VTScada documentation.

Section

Every property must belong to a section. These cannot be assigned randomly. VTScada will ignore any property definition that is located in the wrong section (with a few exceptions).
Most of the properties that you will want to work with are in the section, [System]. Any new properties you create should be added to that section.

Value

All properties are stored as text, including those written out as numbers.
Some properties are set to blank. In most cases, blank means "use the default", which might mean, "don't use this feature".

Workstation

You can define properties whose value applies only to the named workstation. These will be saved in files named for the workstation. AutomaticDeploy is an example of a workstation-specific property.

Restart

If a property has a check mark in this column, then any change to that property will require the application to be restarted before the change will take effect.

Properties that require a restart are stored in the file Settings.Startup. All other properties are stored in the file Settings.Dynamic. You cannot use the Edit Properties dialog to add new properties to the .Startup file; they must be added directly to that file using a text editor and changes imported before they can be edited within the dialog. (See: Import File Changes Tool)

When you click the Apply Changes button to save a property that requires a restart, no further development work can be done in the application until that restart occurs. Therefore, choose your timing of such changes carefully.

OEM

Any property with a check mark in the OEM column will also be gray. These are defined in an underlying application layer.
To override any of these properties, you must copy them to the current application.

Comment

An optional description of the property.

When working directly with the configuration files, this must be stored on the line below the property definition or it will be taken as part of the value. Comment lines begin with a semicolon.

Change (or add) a property value in the advanced mode:

The general steps are as follows:

  1. Open the Application Configuration dialog.
  2. Open the Edit Properties page in the Advanced Mode.
  3. Find the property...
    1. You can search using wild cards. Also, the list can be sorted by name, type, or value for browsing.
    2. If you find the property and it is black, you can edit it directly.
    3. If you find the property and it is gray, you must use Copy to copy it from the OEM layer to the current application.
    4. If the property is not listed, click the Insert button to add it.
  4. Change the property's value.
  5. Apply the changes.
    You may need to deploy the change if Automatically deploy local changes is not selected in the "Other" tab of the basic mode.

Copying a property
Click to expand image

Widgets to change a property value

If you need to change the value any property on a regular basis, it may be inconvenient to open the Application Properties menu. Instead, you can use an Edit Property Checkbox or an Edit Property Field to modify that property on any of your pages. This may be especially helpful when you need to allow an operator to change a property but do not want to grant Application Configuration rights to the operator's role or account.


Change a Property's Value

You can use the Edit Properties page of the Application Configuration dialog to change the value of a property that is set locally within an application. If the property's value is set in an OEM layer, you must copy that property to the current application layer to change it (Copy a Property). If the property has not been defined in this application or any underlying layer, you must add it (Add a Property).

The most commonly changed properties may be accessed through one of the three tabs of the basic mode, Display, Alarms, and Other, eliminating the need to use the following steps.

  1. Open the Edit Properties page of the Application Configuration dialog.
  2. Open the Advanced Mode.
  3. Find and select the property whose value you want to change. Only properties that are not flagged as OEM (and displayed in a pale gray color) may be edited.
  4. Click in the Value field.

An edit window will open within the field.

  5. Type a new value for the property and press Enter.
  6. Click on the Apply button.

If the property is one that requires an application restart before it goes into effect, you will see the following warning:

  7. Click on OK unless you would like to make other configuration changes before proceeding with this one.

The Comment dialog will open.

  8. Type a comment into the Comments dialog and click OK.

If you later use the VTScada version control system to review the changes made to your application, this comment will help you remember why the changes were made.

  9. If the property requires a re-start before it takes effect, you will see the following dialog. Choose whether to stop the application, restart now or restart later.

If you choose Not Now, the Restart Required symbol will be added to the application's title bar and further configuration changes will not be allowed. The buttons for the Idea Studio, Application Properties, Tag Browser and for Page Notes will be hidden.

Closed Troubleshooting:
  • The new value has no effect.

Check that the property name is spelled correctly and that a legal value has been assigned.

Check that the property has been declared in the correct section.

Ensure that comments are not included on the same line as the property declaration.

Ensure that the file changes have been imported.

If the property requires a re-start, shut down the application and re-start it.

Related Tasks:

Copy a Property - Make a local copy of an OEM property, with its own value.


Add a Property

A small number of properties are not included in the default Settings.Startup or Settings.Dynamic files. For example, if you are defining realm-area filtering, you will need to add a series of properties to designate the areas for each realm.

There are two methods for adding a property: To add a property to the Settings.Dynamic file, it is easiest to use the Insert button in the Application Configuration dialog.

If adding a property to the Settings.Startup file, or if you are adding a property to a hidden section, then you should use a text editor to work directly in the file.

The Application Configuration dialog will add properties only to the .Dynamic file. Any property that belongs in .Startup must be added using a text editor and then the changes imported. (Import File Changes Tool)
Existing properties in either file can be changed using the Application Configuration dialog.

Another reason that you might add a property is if you wish to override a configuration setting from the file Setup.INI. Most commonly, this will be done to re-define a VTScada label within an application.

Notes:

  • Property names may not include the following characters []<>=;
  • Properties must be added within the correct section, otherwise they will be ignored.

Steps to add a new property using the Application Configuration dialog:

  1. Open the Application Configuration dialog and select the Edit Properties page.
  2. Click on the Insert button

The Add Property dialog will open.

  3. Enter the Property Name.
  4. Select or Enter a section.

Properties will be ignored if they are added to the wrong section of the Settings file.

  5. Enter a value for the property
  6. [optional] Select a workstation if this property is to be in effect on only that one.
  7. Enter a comment, describing the new property.

Comments will be stored on the line below the property in the Settings.Dynamic file.

  8. Click OK

The dialog closes. Note that the new property will not be saved until you apply your changes.

  9. Click Apply.

The Comment dialog will appear.

  10. Type a comment into the Comments dialog and click OK.

This comment is for the VTScada version control system and should explain why the new property is being added, unlike the earlier comment that explains what the property does.

Steps to add a new property using a text editor:

  1. Start a text editor that does not add formatting to your document.
  2. Open or create the file that the property should be added to.
    1. Use Settings.Startup for properties that require a re-start.
    2. Use Settings.Dynamic for hidden security manager properties.
    3. Use WorkstationName.Startup or WorkstationName.Dynamic in the WorkstationSettings sub-folder for properties that apply only to a specific workstation.
  3. Locate the appropriate section name for the property.

Section names are enclosed in square brackets. Each property listed in the reference section of this chapter will identify the section it must belong to.

  4. Add the property using the format, PropertyName = Value
  5. Add a comment to the following line using the format, ; Comment describing property.

Comments must not be included on the same line as the property definition. Comments on the same line will be taken as values for the property.

  6. Save the file
  7. In the VAM, click Import File Changes, or (better) use the Import/Export Files page of the Application Configuration dialog to import the new or edited file.

The Import/Export Files method is preferred because it enables you to review all changes in the file before proceeding with the import.

Closed Troubleshooting:
  • The new value has no effect.

Check that the property name is spelled correctly and that a legal value has been assigned.

Check that the property has been declared in the correct section.

Ensure that comments are not included on the same line as the property declaration.

Ensure that the file changes have been imported.

If the property requires a re-start, shut down the application and re-start it.

Next Steps:

Change a Property's Value - Control the appearance or behavior of your application.


Copy a Property

This dialog shares many features with the one used to add a new property. There are two reasons to copy a property:

  • To create a local copy of an OEM property, which you may then change for the current application.
  • To set a workstation-specific value for a property.

In the Edit Properties dialog, you will notice that a few properties are shown using a bold font while most are displayed using a faint gray shade. Those shown in a faint gray color are properties whose value has been set in one of the application's underlying OEM layers. (If the Hide OEM Properties option is selected, only local properties are shown.)

A property set in the current application takes precedence over a property set in an OEM layer. The same property cannot be set twice in the application, within a section and having the same workstation name.

  1. Open the Application Configuration dialog.
  2. Ensure that the Hide OEM Properties box is not selected.
  3. Find and select the property whose value you want to change.

See: Sort and Filter the Application Property List for shortcuts.

  4. Click on the Copy button.

The Copy Property dialog will open.

The Copy Property dialog enables you to change all fields. Note that unknown property names are ignored. Properties attached to the wrong section are likewise ignored.

  5. Change the Value as required for your application.
  6. [optional] If the copied property is meant to be in effect for only a particular workstation, type the name of that workstation in the field provided.
  7. [optional] Alter the comment field to provide a reminder note to yourself, explaining the reason for the new value.
  8. Click OK.

The dialog closes. Note that the new property will not be saved until you apply your changes.

  9. Click Apply.

If the property is one that requires an application restart before it goes into effect, you will see the following warning:

  10. Click on OK unless you would like to make other configuration changes before proceeding with this one.

The Comment dialog will appear.

  11. Type a comment into the Comments dialog and click OK.

If you later use the VTScada controlled versioning system to review the changes made to your application, this comment will help you remember what changes were made and why.

Closed Troubleshooting:
  • The new value has no effect.

Check that the property name is spelled correctly and that a legal value has been assigned.

Check that the property has been declared in the correct section.

Ensure that comments are not included on the same line as the property declaration.

Ensure that the file changes have been imported.

If the property requires a re-start, shut down the application and re-start it.

Related information:

- Save time when looking for a property.

- Structure and location of the files affecting an application.

- Error dialog description.

Next Steps:

Copy a Property - Make a local copy of an OEM property, with its own value.

Change a Property's Value - Control the appearance or behavior of your application.

- Have a different appearance or behavior from one workstation to another.


Configuration Examples

It's easy to underestimate how much control VTScada gives you through configuration properties. A few examples might help to expand the horizon.

Alarm Properties

AlarmDatabaseGroups - If you have many Alarm Database tags, use this to create named groups that display alarms from multiple databases.

MinMuteDuration - Set the minimum time duration for alarm muting. (There is also a property for the maximum value.)

ApplyMuteSilencePerUser - Controls whether the Mute and Silence controls of the Alarm Page affect only the current user.

AlarmSpeechEnable - Speak alarms at the server instead of using the alarm tones.

AckAllAcksOnlyVisible - By default, the Acknowledge All tool in the Alarm Page and Alarm List will acknowledge all alarms that pass the filter currently in effect, including those on the next page of a scrolling display. When set to 1 (TRUE), only those alarms that are visible in the list will be acknowledged.

AlmPgStartList - Selects the default list of alarms to display when the Alarm page opens.

Security

MaxFailedLoginAttempts - How many attempts before the account is locked for X minutes.

MaxRateFailedLoginAttempts - How frequently attempts can be made before switching from the maximum attempt value used for operators to the maximum value used for automated cracking programs.

ReadOnlyStation - Use with care! When set to 1 tag write operations on the named workstation will be prevented.

NoteAddRequiresAuthentication - When set, a logon prompt will be displayed whenever an attempt is made to save a note, requiring the author to prove that they are authorized to created notes.

Tags & Trends

RememberNewTagParameters - Whether new instances default to the values from the last instance created or if every tag starts out blank.

DefaultAnalogDeadbandFractionOfFullScale - The default deadband when logging analog values.

ParmChangedColor - The green background when a tag parameter is changed.

ParmInfoDateFormat - How to display dates in the tag modification tooltip.

OpenSitesAsPopup - Applies to all sites whose opening behavior is not explicitly configured. Set 1 (TRUE) to open a site page as a pop-up.

DemoMode - When set, legacy tags including Analog and Digital Status that have their Area set to "Demo" will update to a random value every 60 seconds. See also, SimulateIO, which affects drivers.

HDVMaxDataSources - Sets the maximum number of pens that will display on the Historical Data Viewer page.

Application Behavior Properties

AutoActivate - Activate and start are not the same thing. For example, an OEM layer must activate before the dependent layer can run, but the OEM layer itself does not run.

AutoStart - Run this application every time VTScada starts. Required when you run VTScada as a Windows service.

DoNotStart - Maybe your OEM layer isn’t meant to run.

HideFromVAM - Maybe your OEM layer shouldn’t even be seen.

NoSoftDriverFailure - Controls whether drivers should switch to backup servers on failed communications.

Logging, and more...

OperatorLogTemplate - controls what information is included when VTScada logs operational events.

HistorianConnectionRetryDelay - the number of seconds to wait before retrying a connection.

TraceUserConfigActions - Log operational events.

DisableUSDialog - When set, disables the dialog that prompts for parameter values when opening an under-specified (US) parameterized page.

DisableGoToPage - Deactivates the Go To Page feature in both the Tag Browser and the Alarm Page. Recommended if you rely on restricted access to hotboxes to prevent unauthorized access to certain pages rather than using security privileges within those pages.


Configuration File Structure

You are advised to use the Edit Properties dialog in most cases, but there will be times when it is either helpful or necessary to edit properties directly within their text files. Examples include working with hidden files or adding properties that take effect only on restart, as you would if configuring Tag Area Filtering.

Configuration properties are stored within one of the following files according to whether they can be changed dynamically, whether they are workstation specific, or whether they affect VTScada as a whole rather than one application.

Settings.Dynamic

Located in your application folder. This holds the majority of the properties that affect an application without needing to restart the application. Unless you have information telling you otherwise, look to this file first for any given property.

Settings.Startup

Similar to Settings.Dynamic, except that changes to these properties take effect only when your restart your application. Existing properties in this file can be edited using the Edit Properties dialog but if you are adding a "restart required" property you must edit this file to add it here before it can be edited within the dialogs. Properties that require a restart are flagged as such in the documentation.

Workstation.Dynamic and Workstation.Startup

These store the same properties as Settings.Dynamic and Settings.Startup except that the values are overrides that apply only to the named computer. "Workstation" must be replaced by the name of the workstation where these properties will be in effect. Workstation-specific files are stored in a sub-folder of the application. For example, if a property that can change dynamically should have a different value on the machine, RemoteSrv1, you will need
C:\VTScada\BedfordDemo\WorkstationSettings\RemoteSrv1.dynamic

Setup.INI

Located in the top level of the VTScada folders, these affect VTScada in general. Changes can be made only by editing this file using a text editor. Changes do not take effect until VTScada (not just your application) restarts.

Changes made directly to any of an application's configuration files are ignored until an authorized user runs the Import File Changes command.

All configuration files share the same structure:

[SECTION_NAME]
PropertyName = Value
   ; Comments
PropertyName = Value
   ; Comments

<HIDDEN_SECTION_NAME>
PropertyName = Value
   ; Comments

Rules:

  • Section names are marked by square brackets.
  • Hidden sections are marked by angle brackets.
    Hidden sections can be edited within the file but never show in the Edit Properties dialog.
  • Every property must be stored in the appropriate section. Properties stored in the wrong section will be ignored.
  • Property assignments take the form, Name = Value.
    Text values are not enclosed in quotation marks. Quotation marks may be included as part of a label.
  • Comments are both on a separate line, and are marked by a leading semi-colon.
  • Attempting to add a comment after a value, and on the same line as the value, will break the property.

Properties that can be changed without a restart of the application must be stored in the .Dynamic file. Properties that are loaded only on application restart should be stored in the .Startup file. Moving a property from .Startup to .Dynamic does not result in it being able to change without restarting the application.

Hidden Property Sections

Some application properties can never be viewed or edited in the properties list. These are defined in one of the hidden sections within Settings.Dynamic or Settings.Startup. Security defaults (time-outs, group name delimiters, etc.) are examples. Alarm-Area Filtering (covered later in this course) is another.

Hidden sections are those whose section heading is enclosed in angle brackets. <SecurityManager-Admin> is one of these. As a developer, you should be aware of these sections because you may need to edit properties within them, although this tends to be rare.

Direct Editing of Settings.* (and other) Files

A user-copy of both the Settings.Dynamic and Settings.Startup files can be found in every application. For example, C:\VTScada\MyApp\Settings.Dynamic. As a general rule, use the VTScada dialogs to edit configuration properties. It is rarely necessary or convenient to work directly with the files. One exception to that is that changes can be made to the properties in a hidden section only by directly editing either the Settings.Dynamic or Settings.Startup files. Note that none of those changes will have any effect unless subsequently imported by someone whose account has the Edit Files privilege.

Before using the Import File Changes button in the VAM, you are advised to review those changes by using the Import/Export Files page of the Application Properties dialog.

Current (unchanged in code) values shown in yellow. New (not yet imported) values shown in green.

User files have the following attributes:

  • VTScada maintains them, writing updates whenever changes occur in the application. These updates are merged into the files rather than over-writing them.
  • VTScada ignores changes made to user files until an authorized user imports those changes.
  • You can force a write from VTScada to the user files at any time. You have the option of merging changes or of over-writing the user file with the current contents of the working file.

Other Configuration Files

While discussing files that you can edit directly, note that in addition to Settings.Dynamic and Settings.Startup, you may also edit the following:

  • AppRoot.SRC – contains constant definitions and module declarations for your application.
  • Page source files in the \Pages sub-folder - contains the source code defining every page in your application.
  • Image files in the Bitmaps sub-folder – contains your additions to the application's library of graphic images.
  • User-created widgets, pages and tags.
    Just be aware that if you edit the source code for a user-defined tag, it will then count against your license limit.
  • AlarmListFormats.XML Must be copied from the \VTScada\VTS folder to your application before editing. You can use this XML file to modify the columns in the provided alarm lists or to generate a completely customized list format. (Note that while the file will set initial column widths, on-screen changes to the widths are stored with the user-account and do not reload from the XML file.)

User-files that you should never attempt to edit include:

  • Accounts.Dynamic - plain text and intentionally indecipherable by humans. The encoded contents of this file are tied to the application it was generated within and cannot be transferred to other applications.
  • Servers.XML – stores the network server configuration in an XML format. Use the Application Configuration tools to edit this rather than attempting to do so directly.


Workstation-Specific Properties

Any property can be assigned a value that will apply only to the instance of VTScada running on a specific workstation. You might use this feature to set display properties or security features that will be in effect only for a given workstation. Workstation-specific properties are mandatory when configuring Tag Area Filtering or Alarm Area Filtering. And, in combination with expressions, these can also be helpful for certain driver configurations such as Modbus Plus PLC addressing, where the link path to a device can vary from server to server.

Workstation specific property example

Workstation-specific properties in the Application Configuration dialog, Other tab

You can create a workstation-specific version of any property, not just the four shown here. Workstation-specific properties are stored in a file named after the workstation where they will apply and having an extension of either .Startup or .Dynamic. These are located in the WorkstationSettings sub-folder of your application.

The Application Configuration dialog will add properties only to the .Dynamic file. Any property that belongs in .Startup must be added using a text editor and then the changes imported. (Import File Changes Tool)
Existing properties in either file can be changed using the Application Configuration dialog.

Not for Thin Clients

Workstation-specific settings are valid only for computers with VTScada installed. For thin client connections, the name of any remote machine making a client connection cannot be known. You cannot create a workstation-specific setting for any thin client connection.

You can, however, create workstation-specific settings for all Internet client connections to a specific VTScada Thin Client Server by designating the name of the computer hosting the VTScada Thin Client Server. This may be especially useful if you have one server for Internet connections from within your trusted network and another in a DMZ (demilitarized zone) for connections from the Internet in general and you wish to have separate rules for each.

On a related theme, if you want to set display properties that apply only to thin clients, consider one or more Realm Display Setup Tags

In this example, the setting for the variable, DispMgrFullScreen will apply only to the VTScada installation running on the workstation, ANDREWH. (DispMgrResizable must also be set to 0.)

Workstation-specific properties are stored in files named after the workstation to which they apply. For the example given, there will be a file named, "ANDREWH.Dynamic" in the sub-folder, "WorkstationSettings". (C:\VTScada\BedfordScada\WorkstationSettings\ANDREWH.Dynamic")

The structure of the Workstation files is identical to that of the Settings.Startup and Settings.Dynamic files. All of the same rules for section names, comments, etc. apply.

Workstation-specific properties for hidden sections

Properties stored in hidden sections cannot be created or modified using the Application Configuration dialogs. You must work directly in the Settings.Dynamic file for these.

As an example, perhaps you wish to set the propertyRemoteAuthMethodsDisallowed to "usernamepassword", but only for a VTScada Thin Client Server located in your organization's DMZ. The process is simpler if you already have at least one workstation-specific property defined for that machine. Therefore, the recommended process is as follows:

  1. Use the Application Properties page to insert a new property with a name that does not match any existing property. (Perhaps, "nada".)
  2. When defining this property, set the workstation to the name of the machine where you want create a workstation-specific hidden property.
  3. Upon saving the new property, the WorkstationSettings folder will be created and a workstation-specific version of the Settings.Dynamic file will be created within it.
    You could rename this to .Startup if the property you are setting loads only on application restart.
  4. Open this file with a text editor and add the appropriate hidden-section label and the properties with values for that workstation.
  5. Optionally, delete the property you created in step 1 of this process.
  6. Use the Import File Changes button in the VAM to import the updated version.


Email Configuration for Alarms and Reports

You will need access to an email server for the following two features of VTScada:

  • Sending alarm notifications by email (or SMS-text ready email). Requires a license that includes the VTScada Alarm Notification System.
  • Sending reports by email.

In both cases, configuration of the email server is done using the Alarms tab of the Basic mode of the Edit Properties page in the Application Configuration dialog. Outgoing emails use the SMTP protocol. Incoming use the POP3 protocol. You have a choice of authentication methods and can use OAuth 2.0 if required by your email provider.

Before configuring the connection to your email server you must gather information about that server. The following illustrations and figures provide guidance. If using OAuth 2.0, refer to the topic, OAuth 2.0 Protocol.

Outgoing Email Configuration

Used for both alarm notification and reports by email.

Outgoing Email. This section follows many other alarm configuration options.

These properties are stored in an encrypted format, and cannot be modified in the Settings.Dynamic file.

Customers using basic authentication (username and password) with either Microsoft or Google email accounts must start using OAuth 2.0 or switch to another email provider. For Google, the change-over date was May 30, 2022. For Microsoft accounts, the change-over is scheduled began in October 2022. Refer to Google & Microsoft vs Basic Authentication

Protocol | Only SMTP is allowed.
Email server name or IP | The name or IP address of your email server. This information should be available from your system administrator or your email provider. It will typically take the form: "mail.yourcompany.com" for an internal email server or, using Google’s Gmail as an example, "smtp.gmail.com".
Email server port number | The port number used by your email server. Always check with your provider to determine the port to use, but for most local email server programs, this will be 25. If using Transport Layer Security, the port will usually be 587.
Email transport layer security | Controls whether TLS is used for communications. This is required by most email servers.
Email from address | The text you fill in here will be used in the FROM: field of all emails sent by the system. Note that some email servers will check that this is a valid email address and will reject the message if it is not. If you are configuring for alarm acknowledgment by email, this field must include the email address configured in the Incoming Alarm Email Acknowledgments section. The field may also contain a common name as well as the address. For example: "VTScada System" <VTSSystem@YourCompany.com> Multiple addresses may be used, separated by semi-colons. In the case of alarm acknowledgment by email, the other addresses will be each receive a copy of the acknowledgment.
User name | The account name on your SMTP server, if it is using username / password authentication. Disabled if you are using OAuth2 authorization
Password | The password for the account if using username / password authentication. If using Microsoft or Google and not using OAuth 2.0 then you are advised to obtain an App Password as described in Google & Microsoft vs Basic Authentication Disabled if you are using OAuth2 authorization. Both the user name and the password are encrypted for storage.
Use OAuth 2.0 | Disables both User name and Passwords fields. Enables access to the OAuth 2.0 configuration dialogs in the VTScada security system. See: OAuth 2.0 Protocol
Grant | Select which OAuth 2.0 grant should be used if more than one has been configured.
Consent | Initiate the consent process for the selected grant in order to use that email service.
Revoke | Revoke consent for the selected grant, ending the ability to use the email account configured with that service.

Incoming Email Configuration

Used only for acknowledging alarms that were sent by email.

Incoming email configuration. Follows Outgoing Alarm Email Configuration in the configuration properties dialog.

These properties are stored in an encrypted format, and cannot be modified in the Settings.Dynamic file.

Note that the "ack" code in outgoing emails is controlled by the presence of a contact user name in the Roster, not by whether incoming email acknowledgments are enabled.

Customers using basic authentication (username and password) with either Microsoft or Google email accounts must start using OAuth 2.0 or switch to another email provider. For Google, the change-over date was May 30, 2022. For Microsoft accounts, the change-over is scheduled began in October 2022. Refer to Google & Microsoft vs Basic Authentication

Protocol | Only POP3 is allowed.
Email server name or IP | The name or IP address of your email server. This information should be available from your system administrator or your email provider. It will typically take the form: "pop.yourcompany.com" for an internal email server or (using Google’s Gmail as an example) "pop.gmail.com".
Email server port number | The port number used by your email server. Always check with your provider to determine the port to use, but for most local email server programs, this will be 110. If using Transport Layer Security, the port will usually be 995
Email transport layer security | Controls whether security is used for communications. This is required by some email servers, such as Google’s Gmail.
User name | Use if your POP3 email server requires username / password authentication. Disabled if you are using OAuth2 authorization.
Password | The password for your POP3 server account, if it is using username / password authentication. If using Microsoft or Google and not using OAuth 2.0 then you are advised to obtain an App Password as described in Google & Microsoft vs Basic Authentication Disabled if you are using OAuth2 authorization. Both the user name and the password are encrypted for storage.
Maximum message size in bytes | Reject any message larger than this size. Use this field to block emails with large attachments, which might otherwise delay legitimate alarm acknowledgments.
Use OAuth 2.0 | Disables both User name and Passwords fields. Enables access to the OAuth 2.0 configuration dialogs in the VTScada security system. See: OAuth 2.0 Protocol
Grant | Select which OAuth 2.0 grant should be used if more than one has been configured.
Consent | Initiate the consent process for the selected grant in order to use that email service.
Revoke | Revoke consent for the selected grant, ending the ability to use the email account configured with that service.


System Properties - Setup.ini

There is another properties file to know about: Setup.INI. This contains properties that apply to VTScada as a whole, rather than to any individual applicationAs usual, exceptions apply. The section, [LAYER] contains properties that relate to applications. If defined only in Setup.INI, then these properties will apply to all applications, but any can be added to the [SYSTEM] section of an application's Settings.Dynamic file to override that property in a specific application. 1. Some of these are intended for the use of system integrators, to allow them to customize the overall appearance of VTScada. Others affect VTScada operations such as the use of XML features or the response to pending UPS battery failure.

Since the release of version 12, changes you make to Setup.ini will not be over-written by subsequent updates of VTScada.

Comments (if provided) must be on a following line, and must begin with a semi-colon.

Refer to the side menu for the listing of properties in this section.

Settings within Setup.INI will be read only when VTScada starts. The following sections are included:

[APPS]

A listing of the applications in the VAM. It's best left for VTScada to manage, especially if you have custom lists.

[OEM]

Properties that you can use to customize VTScada. These include the following:

NoSplash

When set to 1 (true) the initial splash screen animation will not run when VTScada starts.

HideWAM

When set to 1, the VAM will not display. Use with caution! This can be helpful when an application has been set to auto-start and you want to ensure that no-one at the customer's site has access to the VAM. Before using, make certain that one application has been set to auto-start and that it contains a security account that possesses the privilege, Application Manager View.

"HideWAM" is a carry-over from the days when it was the "Web Application Manager" not the "VTScada Application Manager". It still exists for backward-compatibility, but you are advised to use "HideVAM" for custom code that will change the setting.

[System]

System-wide properties including the following examples apply to your UPS:

OrderlyShutdown         = 1
  ; Enable / Disable orderly shutdown
ShutdownOnLowBattery    = 0
  ; Shutdown VTScada when windows reports battery as "low"
LowBatteryPercent       = 10
  ; Shutdown VTScada when battery % is less than this amount
LowBatteryTime          = 15
  ; Shutdown VTScada when battery time (minutes) is less than this

[Layer]

Properties that can be copied to an application, but will otherwise affect all applications. Most relate to synchronization timing or behavior of the version control repository. Notable properties in this section include:

AutomaticDeploy = 1
  ; All changes are automatically deployed when this flag is non-zero
RepositoryCommentMinLen  = 0
  ; Minimum number of characters required for repository comments
RepositoryCommentDisable = 0
  ; TRUE to disable prompting for repository comments

[Remote]

Properties that relate to the VTScada Internet Connection, including the folder path to the monitor log file.

[Themes]

Theme definition codes. Modify the existing themes or create your own. Each theme definition used the following format:

Theme = ThemeName, Hue Offset, Saturation, Brightness, Contrast

For example:

  Theme =   Grey, 0,0,1.1,1
  Theme =   Navy,-15,2,0.7,1

To create a new theme, you will need a paint program that can represent hue as a wheel, where 0 is blue. The hue value for the theme is the offset clockwise or counter-clockwise around the hue wheel.

[Trace]

Properties related to data collection for debugging.

[SQL_*]

Data type definitions for supported SQL programs

[TextFileExtensions]

[FileExtensionClasses]

FileExtensionClasses and TextFileExtentions work together to help define which files within an application folder can be added to the file manifest and what type of file each is, based on the extension.

[CriticalConfigurationFiles]

Files that may not be removed from the manifest.

[Clients-AdditionalAllowedOrigins]

Relevant to those using the VTScada Anywhere Client or the Excel Add-in. See: Domain Aliases (CORS)

Add any domain names or IPs that are used in connection URLs and that are not already included in the server list for the VTScada Thin Client. Set each domain name to 1.

[Clients-AdditionalAllowedOrigins]
myservice.com = 1

[Clients-AdditionalAllowedHosts]

Specify a white list of hosts for which VTScada will accept HTTP requests. If populated with any host name(s), VTScada will accept requests only for the names in the list. If not populated, VTScada will accept requests for any host name.

For example, your server might be known as "A, A.domain.com, or B.domain.com", but you might want to allow connections only to "A.domain.com"

The list should be populated as shown in the previous example for the [Clients-AdditionalAllowedOrigins] list.
HostName = 1.

[Mapping-FontsToFontFiles]

Maps fonts used in VTScada to file files.

[Mapping-TimezonesIANAToWindows]

Maps timezone names used in VTScada to Windows timezone names.

[HTTP-Unauthenticated]

Resources accessible via HTTP without authentication

[StandardServerLists]

Server lists to choose from when adding a new service in the Edit Server Lists panel.

[SlippyMapRemoteTileSourceX]

Where X is a number that must increase incrementally from 1 for each defined tile source. Defines the location and other required information for tiles to be used in a slippy map.


Languages

VTScada ships with English phrases for all parts of the program and with French, Simplified Chinese and Traditional Chinese for (most) phrases that are visible to operators. Translations are not provided for phrases used by development tools including the Tag Browser, Application Configuration dialogs and Idea Studio.

Use the Languages panel of the Application Configuration dialog to create new translations for your application, or to modify phrases used in any installed language. All phrases (labels) used throughout VTScada may be translated here, including those for the development tools.

Your account must have the Application Configuration privilege to be able to modify phrases. For long phrases, a compressed font will be used automatically so that you can see more characters. Hover over a phrase to see a tool-tip containing the full text in your default system font. Phrases and descriptions can not contain line breaks.

Changes are not saved until you click the Apply button.

Select your language for the VTScada Application Manager (VAM)

Your selection here affects only the labels in the VAM. Application names remain unchanged. Remember that Trihedral provides translations only for operator-interface phrases. Many of the tasks performed with the VAM are for developers and therefore no translation is provided.

  1. Expand the menu, located at the top, left of the VAM.
  2. Open the Settings dialog
  3. Select your preferred language.

Enable a language other than English for your application

  1. Open the Application Configuration dialog.
  2. Select the Languages panel.
  3. Select all languages that you want to make available in your application.

Set a default and enable up to 4 languages.

Detail from Edit Properties, showing FR - Français added to the allowed languages.

Switch between languages

When more than one language is available, operators can switch between one language and another using a selector as shown. Their choice will be remembered for future sessions. The user interface will switch immediately. Note that any untranslated phrases will be shown in the default language, along with the matching phrase key.

After signing in, switch between languages by
selecting your name, then your preferred language.

How it works:

All text used in VTScada and in your application is stored in language databases (csv files). This includes the entire VTScada user interface, text that you place on any page or widget, and tag properties such as area, description, and engineering units. All text.

For most users, this is invisible. With the possible exception of a few characters such as degree symbols that need to be updated to UTF-8, you should not notice any difference from earlier versions of VTScada. Continue to work as you always have.

Those who write expressions that generate text will need to be aware of, and use, phrase-handling functions. Refer to Multilingual Expressions.

If you want to display your application in a language other than US English, use the information that follows in this topic.
When making any change to text that you have written (in any language) always use the phrase editor rather than editing the text directly.

Language CSV files

VTScada ships with three language files: en.csv, fr.csv and cn.csv, all stored in the \Languages folder. Do not edit these files because they will be over-written by later updates to VTScada.

When you change a phrase, or when you add a new CSV file for another language, your work is saved to the \Languages sub-folder of your application. This file is part of your application and will not be damaged by VTScada updates.

Choosing how to edit language CSV files

DO NOT USE EXCEL TO EDIT LANGUAGE .csv FILES.

By default, when Excel opens a file, it will alter the structure of the file for its purposes. This will destroy the file so far as VTScada is concerned.
If you choose to disregard this warning, you can mitigate the effects by ensuring that all cells in your worksheet are formatted as text and then importing the .CSV file.

Your editor must use the UTF-8 character set.
Failure to heed this warning will result in VTScada showing non-printable characters.

Use only a text editor that can be configured for the Unicode UTF-8 character set. In recent versions of Windows, this includes Notepad but that was not the case in earlier versions. Check before editing.

Add languages

Your application is uni-lingual until you add a new language .csv file. None of the multilingual features will be visible before this step.

To add a new language:

  1. Create a folder named Languages within your application's folder, if one does not already exist.
  2. Using a text editor that can be configured to use Unicode UTF-8, create a new file within the Languages folder of your application.
  3. Name the file XX.CSV, where XX are two or more letters identifying the language you want to add.

Examples: FR.CSV or en-GB.CSV

  4. Within the file, add a line that will fully identify the language and the variant. For example en-us for US English, en-gb for English, United Kingdom, or fr-ca for Canadian French.
  5. Add a second line, which is the language name as it appears in that language. You may need to configure Windows to set an alternate keyboard configuration.

Example for a French Canadian language file, FR.CSV:

#LanguageID,fr-ca
#LanguageName,Français
  6. Save the file.
  7. Use the Import File Changes button in the VTScada Application Manager (VAM) to add the file to your application.
  8. Open the Application configuration dialog to the Display tab of the Edit Properties page (Basic mode).
    Your new language should be available.

Detail from Edit Properties, showing FR - Français added to the allowed languages.

  9. Select the new language in the list of those available.

Translated phrases for the new language may be added at your convenience. In general, you should ensure that the new language was added successfully before adding phrases to it.

Add and Edit Phrases using the Languages Panel of Application Configuration.

  1. Open the Application Configuration dialog.
  2. Select the Languages panel.

Detail from the Languages panel, showing only the controls

Search and Filter

View

Opens the language View dialog. Use this to select the columns to be displayed in the editing panel.

The Key column is useful if you have created your own phrases and need to know how to refer to them in your label expressions. Use the "View" button to display this column.
The Key column is essential if you are searching for VTScada labels and properties such as "DialerLocation" by name. Use the arrows within the dialog to change the order in which columns are shown.

The languages View dialog.
The Key column is not displayed by default, but is often helpful.

Filter

Enter a word or phrase to search for and limit the display to only those occurrences of the matching value. Leading and trailing wildcards are added automatically if neither is specified. Press <Enter> or the filter button after typing a value into this field.

New phrases are not shown in a filter until after you select the Apply button. Do not create the same phrase twice, thinking that it somehow failed to save.

Hide OEM Phrases

When selected, the display is limited to only those phrases defined in the current application. Phrases from underlying layers (including VTScada) are hidden.

Hide Completed Phrases

Relevant only when at least two languages are selected. Completed phrases are those for which a translation is available in all selected languages.

If you select the Hide Completed Phrases option while viewing only one language, then the grid will be empty.

Edit Phrases

There are two ways to edit a phrase:

  • Click twice on the phrase in the list, then begin editing.
    This is the most straight-forward method, but does not provide a way to edit the description attached to the phrase.
  • Click once on the phrase, then click the Edit button to open the Phrase Editor dialog. All languages that you have selected for viewing will be shown.

The Phrase Definition Editor. Click where indicated to open an editing field.

Descriptions are used to guide translators, providing context for words that might have several definitions.

Insert Phrases

Also opens the Phrase Editor dialog. All fields will be empty until you create your phrase. Phrases that contain commas will automatically be saved within quotation marks. Phrases that contain quotation marks will have those symbols "escaped" by doubling the quotation mark.

Each new phrase is assigned an automatically-generated key. You will need this value if using the \GetPhrase function to display your text in a label elsewhere in VTScada. Note the copy icon, available for each selected phrase.

Phrases cannot be deleted. There is no mechanism to search out every place in code where a phrase might be used, thus making it likely that a deleted phrase would break some part of the user interface.

The Key column is useful if you have created your own phrases and need to know how to refer to them in your label expressions. Use the "View" button to display this column.
The Key column is essential if you are searching for VTScada labels and properties such as "DialerLocation" by name. Use the arrows within the dialog to change the order in which columns are shown.

Copy / Paste Columns

Use these to translate multiple phrases with Google Translate®. To use:

  1. Select the Hide Completed Phrases option.
  2. Click the copy button in the column for which you have entries to be translated.
    Phrases will be copied until the first blank is reached or until a preset maximum buffer size is reached. If the first row in this column is blank, nothing will be copied.
  3. Open an Internet browser to a translation tool such as translate.google.com
  4. Paste the copied text into the translation window.
  5. Edit the translation as needed.
  6. Select and copy the translated text.
  7. In the VTScada languages list, paste the translations into the appropriate column.

Export / Sync

Use the Export command to send phrases to either a comma-separated value file or an Excel file for editing outside VTScada. Entries in the file are sorted alphabetically by key.

Use this file when contracting the services of a translator to generate phrases in a new language. Use the Sync command to import the edited file, synchronizing it with the phrases in your application.

Use caution if editing a CSV file in Excel. The default save option is likely to change the formatting in a way that is not compatible with VTScada.

Choose the target format and what information to include when exporting

The exported file will contain a version identification code. Do not delete this information. You cannot synchronize your application with a file that does not contain a valid version identifier.

The exported file will always include the key for each phrase. Take care not to edit the key. When synchronizing the file back into your application, phrases are matched to keys. A new phrase is created if no matching key exists.

Within the CSV file, wrap phrases in double quotes if they include a comma, a literal quotation mark, or use double quotation marks to signify a single quotation mark. For example, "Show a ""+"" rather than label" will be displayed as Show a "+" rather than label. (Do not wrap phrases in quotation marks when using the phrase editor.)

Phrases are never deleted when synchronizing. Entries that have no key value are ignored.

When adding new entries to the CSV file, start after the first three rows.

Note:

The first three lines in the exported file are reserved for use by VTScada. Do not edit these except to add columns for new languages.

The second column is reserved for use by VTScada. In general, do not edit, and leave blank for new entries. This holds a category number for each phrase, which is used only when translating the core VTScada user-interface phrases. Category numbers are used to set the priority of work when translating phrases by identifying where in the user-interface the phrase is used. Category values are assigned as follows, where operator-facing phrases are the highest priority category.

1: Operator

2: Demo pages

3: Configuration

4: Activation

5: System

6: Trace

7: Debug

% Codes

Numeric % codes such as %0 and %1 are non-defined replaceable parameters. These are used where VTScada will substitute information into a generic phrase. For example, "Alarms muted until %0 %1". This message is displayed when an operator mutes alarms for a defined length of time. When displayed, the time when muting ends will be shown instead of %0 and the date when muting ends will be shown instead of %1.

Text % codes such as %N, %A, and others are defined replaceable parameters. Refer to: Alarm Message Templates.


Phrase Editor

When more than one language is available for an application, this dialog will open automatically each time that VTScada detects that you type a new word or phrase in any field that will become part of the user interface. (Tag names and area properties are used in code, and therefore never translated.) You can disable the automatic opening feature of the editor, instead relying on the editor button, shown circled in the following image.

Opening the Phrase Editor for the Description field of a tag.

The language at the top of the list is the default for your application, as set in the Display tab of the Edit Properties dialog. Other languages are available as configured in the Edit Properties dialog.

Click as indicated to edit descriptions and phrases. Descriptions are encouraged as they are useful to guide translators, or to help other developers select which definition of a given phrase or word applies. (See following image.)

It is often the case that one word or phrase can have several definitions (a homograph). For these, click the plus sign (circled in following image) to add new columns as needed for each definition. Each column matches a unique phrase with a unique key. For the default language (top row), every entry must be the same. Editing one will result in all changing to match. VTScada will automatically find all matching phrases in your default language. The selected column indicates which translation is used in a given instance.

Example shows a second column added for a homograph.


Tags and I/O

Tags are the software representation of the parts of a physical system. A tag might represent the status of a pump, the level of a tank, a control switch to open a valve, etc. Tags also represent the connections to your hardware, both physical (TCP/IP or Serial) and software (the choice of driver). Further, tags are used to hold certain configuration settings including fonts, default colors for widgets, alarm priority characteristics and more.

In short, tags represent "things". Any things.

Points? A tag is a point and a point is a tag. VTScada uses the word "tag" more often (that's what the T in VTScada is for, after all) but "point" was used first, and you'll still see it from time to time.

The Tag Browser is the main tool for creating, modifying and deleting tags. It is also possible to export tags to a spreadsheet or database, then import changes back to the application. This is less user-friendly and is not advised for creating new tag hierarchies, but can save time when creating or updating many similar tags in existing hierarchies.

The Tag Browser allows you to organize your tags into a hierarchy so that it is easy to see which tags relate to which components in the system. Besides making it easier to find a given tag, this system makes it easy to expand the application by copying entire structures. A hierarchy also determines how some kinds of tags link to each other. Many tags work best when linked in such hierarchical structures. For example, I/O tags below the driver and dedicated alarm tags below the triggering tag.

While any tag could serve as the starting point to a hierarchy, the best choice is a Context tag, a container tag which provides a shared context to a group of related tags. (Design Your Own Tags, Context Tags) Context tags do not have any function except to organize a group. For example, a Context tag may represent a location that hosts several devices, each with their own tags. In very large systems, however, the parent tag might be an Alarm Database. (Alarm Database Tags)

Design Your Own Tags Context TagsAlarm Database Tags.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.


Tag Licensing

Your VTScada license restricts the number of tags that may run at the same time on one computer. Click the About... button on the VAM to view what is enabled by your license.

The tag limit applies only to legacy and I/O and Calculations tags that have a read or write address or any tag that has been modified at the code level. The count includes tags in all running applications.

Tags that count towards your license:

I/O and Calculations, when configured with an I/O address to read or write. |
Analog Input | Analog Output
Analog Control | Analog Status
Digital Input | Digital Output
Digital Control | Digital Status
Data Flow Pulse Input | Pump Status
Selector Switch | String I/O
Tags that you create or modify by writing code in .SRC files. |

All others do not count.


Optimize Your Configuration

Reading and storing a large amount of I/O process data can require significant computer resources, especially when you have multiple redundant servers. The following describes several ways that you can reduce bandwidth and network traffic on your system.

SSD drives:

Faster disk writes mean that data is less likely to be queued up, waiting to be written to the hard drive. A large queue can slow the rest of the system.

Do initial data storage on the current server, using a separate drive if possible.

Rely on backup servers for remote storage of data. By initially saving data on the designated current server, your data is not at risk of network bottlenecks or interruptions.

For systems that support a second local drive, the benefits of storing data on a device other than the one used by the operating system include:

  • Ease of upgrading to larger storage if required.
  • Improved speed because the drive can be used in parallel rather than competing with the operating system for access to the same drive.
  • Protection of your data in the event that the operating system becomes corrupted, requiring a re-installation or reformatting of the OS drive.

Poll rate:

Do not set your scan rates to poll more frequently than required. For example, if you need data only every five minutes, it would be a mistake to leave all scan intervals (or poll rates for those using the Polling driver) at the default value of 1 second. Reading data, saving to the Historian, and synchronizing those values across servers and workstations more often than necessary can cause a significant amount of network traffic for no useful purpose.

Deadbands on reading and logging

Set within I/O tags (and legacy Analog Status tags). If values are changing by tiny amounts very quickly, good deadbands will filter the data so not every change is read or is logged to disk. Every time a value is logged, it must also be copied to all of the redundant historians. But use care not to set the deadband so large as to miss important data. Defaults are set for you on both the read and the logging deadband, but you must always check whether those values are appropriate.

Strategic use of non-optimized tag parameter expressions

Non-optimized tag parameter expressions evaluate a parameter value whenever there is a change to any value used by the expressions. They are intended for situations where configuration values must be obtained from equipment that is reachable only after the application starts.

Tag parameter expressions become non-optimized by deselecting "Optimize to only evaluate at tag initialization" in the Tag Parameter Expression dialog. You should only deselect this option if there is a clear need to do so.

You are strongly discouraged from using non-optimized tag parameter expressions where changes occur frequently or if the tag has children. Every time the non-optimized parameter expression changes, the tag will restart and so will all of its descendants. This is resource intensive.

Misuse and over use of non-optimized tag expression can have undesirable side-effects.

Anti-virus configuration:

Most anti-virus programs want to read each file that is accessed before allowing another program to write to it. If VTScada is logging hundreds of data points per second, and the anti-virus software is trying to scan each individual file before it will allow the write, then they are unlikely to keep up, making it appear that VTScada is slow or even causing an out-of-memory error if the queue size becomes too large.

Trihedral recommends setting an exclusion so that the Data directory in the application folder is not scanned, either on demand or on full system scans. The full system scan is more of an issue because it will prevent file access while a file is being scanned, stopping writes temporarily.

Turn off folder indexing:

Trihedral also recommends that you use the Windows advanced options of the application's Data folder to turn off indexing, thereby speeding up writes. The steps follow, although this may require administrator privileges at some sites.

  1. Using the Windows file manager (not VTScada!), navigate to the application's Data folder.
  2. Right-click on the folder and select Properties.
  3. On the General tab, select Advanced.
  4. Deselect the option, "Allow files in this folder to have contents indexed...".


Deadbands for Reading and Logging

All analog I/O tags (including both the I/O tag in the Analog or Discrete mode and the Analog Status tag) have built-in deadbands that help improve performance. Without these, your system might read or log excessive amounts of system noise in addition to the values you care about. But while deadbands are designed to protect your system, they can be harmful if set too high or too low.

You are advised to note the deadband value on the I/O tab and the Logging tab of every tag you create. Adjust as required.

Symptoms of a poorly chosen deadband:

Mismatch indicator is always set.

Most common with devices that have a large unscaled (raw data) range. Values to be written are always converted to the raw form but then rounded to integers for the device. This conversion / rounding process will often introduce a small difference that will be caught as a mismatch. Setting a deadband larger than the mismatch will cure the problem.

For example, we are aware of devices with an unscaled range of 0 to 16383. Suppose that a register on such a device is assigned a scaled range of 0 to 60. When a value of 1 is entered, it will be converted to the raw value of 1*16383/60 = 273.05. But if the device stores only whole values within its range, this is converted to 273, thus introducing a mismatch condition. (273.05 written / 273 read as feedback.) The same math can result in a raw value that is meant to represent a scaled "1" being converted to something like "0.99817" as it is converted from unscaled to scaled.

A read deadband of 0.1 will cure these problems.

Sluggish screen updates / missing values.

The I/O read deadband may be too high and therefore missing changes in value.

Flickering screen updates.

The I/O read deadband may be too low and therefore recording system noise rather than useful data.

Missing data in the history.

The logging deadband is too high and therefore not recording all changes.

Data folders are filling the drive.

The logging deadband is missing or too low, filling the history with changes that are mostly system noise.

The read deadband can be adjusted in the I/O tab of your tag:

The default value is based on several factors including, but not limited to:

  • The application property, DefaultDriverDeadbandFractionOfFullScale
  • The display range if configured, or the scaled range otherwise.

The logging deadband can be adjusted in the Logging tab of your tag:

The default value is based on the application property, DefaultAnalogDeadbandFractionOfFullScale multiplied by the tag's display range if configured, or by the scaled range otherwise.


The Tag Browser

Use the Tag Browser for most tag-related tasks. (See: Add a New Tag or Child Tag) You can open this tool from within the Idea Studio or directly from the title bar of your application (click the icon or type Ctrl + T). The icon to the left of the Tag Browser on the title bar opens the Idea Studio (or you can type Ctrl + D). Users must have the Tag Parameter View security privilege to be able to do this. Only those with the Tag Modify security privilege can make changes.

Opening the browser from the title bar:

From the Idea Studio

Add the Tags tool to the Quick Access Toolbar of the Idea Studio. Then you won't need to reopen the Home ribbon each time you want it.

Every VTScada application starts with a set of Font Style tags, Alarm Priority tags, Notebook tags and others. Also, palette items including widgets, shapes and images are organized using Menu Item tags. These are what you see when you first launch the tag browser. Rest assured that they do not count against your licensed limit. Only I/O tags with addresses and tags that you code from scratch are counted towards the license limit.

Default tag list in the Tag Browser

Parts of the Tag Browser:

The numbers at the top of the tag browser tell you many things.

Tag Browser address bar

Tag Browser title bar

Showing x ...

The number of tags displayed in the main window (tag list). This is a function of the selected parent (left window) and any filters you may be using.

... of x Running Tags:

Total count of running tags in this application (not a total from all running applications). Includes every widget, image, shape, page menu, etc.

Using x ...

Of the tags that count towards your licensed limit, this is how many you've created so far, not counting disabled tags. This count is a total from all running applications on your workstation.

... of x Licensed Tags:

Your license limit.

Filter Controls

In even the smallest application, the tag list will become long enough to require scrolling. For this reason, it is important to know how to filter the list so that you can find the tags you are interested in. The filters are shown in the next image. You may use any or all of these filters in combination.

If no tags match the filter parameters, or if you have used the address bar or tree window to browse to a tag that has no child tags, then the main browser window will read, "There are no tags that match the current selection."

Tag Browser filters

Available filters

When a filter is in use, the filter area is given a yellow-ish background.

There are also advanced forms of tag filtering that require configuration before they can be used. See: Filtering Tags, Alarms and Realms.

Several filters can be applied together. In this case, tags must pass all the filters. ("And", not "Or".) When applying multiple filters, each must be of a different type. You cannot filter for areas "North or South", but you can filter for any area ending with th: "*th". Filters are applied to parameter values as shown in the Tag Browser. In the case where parameters are set by expression, the filter looks only at the result of the expression, not the code of that expression.

Each applied filter is shown in the filter bar, and can be removed individually by clicking the small "x" beside the filter name. To clear all filters, click the large "X" beside the filter symbol.

Click the filter symbol to open the filtering dialog. Click again to close the dialog.

Filter by location in the tag structure

When a parent tag is selected, the list shows only the child tags of that parent. If the option, Show Children is selected, all children and grandchildren are included. Otherwise, only the immediate children of the selected parent are shown.

Search & Filter by name

You do not need to expand the filter selection dialog to filter by name. Simply type the name (or portion of the name) into the search field and press [enter] or [tab]. This will create a "Name contains" filter. The presence of the word "contains" in this filter tells you that wild cards are applied automatically. If you would prefer to search only for names that begin or end with a word, add a wildcard to one side or the other. Examples follow:

The search field is not case sensitive. Entering "A*" is the same as entering "a*".

    A* Return all tag names that contain an "A" as their first character (e.g. "AnalogFont" or "AlarmPriority0").

    *A Return all tag names that contain an "A" as their last character (e.g. "WellA" or "Soda").

    *A* Return all tag names that contain one or more instances of the letter "A" (e.g. "AnalogFont" or "LabelFont").

    A This is equivalent to *A*.

Any parameter contains...

The "Any parameter contains" filter is similar to the name filter but more powerful. All properties of all tags are examined for a match to the filter. Use this if you know a portion of a tag's description or are looking for all tags with a particular engineering unit or scale factor. You can filter on both the tag name and the "any parameter contains..." option.

Address Contains

Provide any portion of an I/O address (read, write or history). For example, if using bitwise addresses for a Modbus compatible device, you might enter /1 to filter for addresses that include only bit 1.

Use a wildcard to limit which portion of an address is examined. For example, 401* for addresses that begin with those numbers or *401 for addresses that end with those numbers.

In this Area

The area property of your tags isn't shown in the Tag Browser, but you can still use it for a filter. Select one area at a time to view tags that were configured with the matching area property.

Of this Type

Select one type at a time to view only the tags of that type. This filter also affects the New Tag selection by pre-selecting the same type from the list.

With this Equipment Type

I/O and Calculation tags can be assigned an equipment type. Select one type at a time to view tags that were configured with the matching property.

Show only tags marked as Questionable

Limit the display to only those tags with the Questionable Data flag set.

Questionable data is an indicator that authorized operators can set on any I/O tag whose values are in doubt. It is never set automatically.

Show only tags with Manual Data

Limit the display to only those tags with a Manual Data value set.

Manual data is typically used when testing a system. These should rarely be left in place in a working application.

Show Children

Includes all children and grandchildren from the selected parent. Does not include tags in the Menus group unless you navigate to that group.

Show Disabled

Includes inactive tags. These are tags whose start condition evaluates to false and tags that have been explicitly disabled. (Disabling a tag sets the start condition explicitly to FALSE.)

List Sorting

You can sort the display by any of the column headings, Name, Description, Type, Address or Value. Just click on the column header to sort in ascending order, or click again to sort in descending order. The first column is unlabeled and is used to show Icons That Describe Tags, which may provide extra information about tags. You can also sort by these.

Tree View Window

The window on the left side ("tree view window") shows:

  • Tags of any type that have a child tag.
    Menus and Alarm Databases are examples.
  • Context tags, which typically have child tags.

You can close or open the tree view window by double clicking on the vertical bar that separates it from the main tag window.

Tag List Window

The main area of the browser. Any given tag may or may not be visible in the list, depending on:

  • The filter control in effect.
  • The selected parent tag.
  • Whether the "Show Children" filtering option is selected.
  • Whether the tag is disabled, and whether the "Show disabled" filtering option is selected.
  • Whether realm-area filtering is in effect.

Tags under the Menus entry

Your application's page menus are organized using Menu Item tags, as are palettes in the Idea Studio. Because the order of these tags is reflected in the organization of menu and palettes, extra control buttons are added to the Tag Browser when you are working within the Menus group.

When creating new tags, your choices will be limited according to the parent of that tag. Within the menus group, you can create only tags relevant to menus or palettes, such as pages, menu items, folders, and dividers.

Command Buttons

All the commands that apply to a tag can be accessed by right-clicking on that tag to open its context menu. In addition, a set of copy & paste commands can be found at the top of the tag browser and the most commonly used commands are available in buttons at the bottom of the browser.

Tag Browser Commands

Tag Browser controls

Tag tools (right-click menu)

Properties

Open the tag's properties dialog.

Draw

Opens the Idea Studio and a filtered palette within the studio, making it easy for you to draw (and automatically link) the selected tag.

Plot

Opens the Historical Data Viewer to show a trend graph of the selected tag.

View Alarms

Opens the Alarm page, filtered to show alarms from the tag.

Operate

If the tag can perform an operation (such as writing a new value to hardware), and if the current user has the required privileges, use this to trigger the tag's action. For I/O tags with a valid Write address, this enables the user to send control actions to hardware while continuing to work in the Tag Browser.

Cut, Copy, Paste as Child

Use "Cut" to move the tag, retaining its history and links to widgets. Use Copy to create a new tag elsewhere, having the same configuration. Use Paste as Child in both cases to complete the operation.

New Child

Create a new tag below the one selected.

Delete

Remove this tag. History is not destroyed, but queries rely on existing tags, therefore there will be no way to retrieve the tag's data after it is deleted.

Enabled

When not selected (no check mark) the tag does not start and does not run.

Set Start condition

Create an expression to control whether the tag should start and run.

Create New Type, Redefine Type

Applies only to Context tags with a type name. Create and update your own types that fully define equipment.

Go to Page, Go to Page (Popup)

If the tag is drawn on a page, open that page. If drawn on more than one page, you will be given a choice of which to open.

Shortcut to modify tag properties:

The Tag Browser is not the only path to edit a tag's properties. In a running application, if you can see the widget that's linked to the tag you want to edit, you can right-click on that widget to open a context menu. (Assuming that you have the Tag Modify privilege and that this feature is enabled in the widget. )

The menu will vary by tag type, but the Properties option will always be there. Other options in this menu open specific pages of the full properties dialog.

The fastest way to open a tag's properties dialog.

This right-click menu can be disabled by editing the properties of the widget in the Idea Studio.

Options in the properties dialog of every widget
that can be linked to a tag.

Tag Browser Keyboard Shortcuts

Key Combo | Description
Esc | Close the tag browser
Tab | Change focus (Tree View > Grid List > Import > Discover > New > Properties > Draw > Close > Search > Show Children > Show Disabled > Tree View)
Shift + Tab | Change focus in the opposite order.
Arrow Left/Right | Closes/Opens tag trees.
↵Enter | Navigate inside to display children.
Ctrl + N | Create a new tag as if you had clicked the "New" button.
Ctrl + Shift + N | In the grid list, create a new child tag under the selected tag.
Ctrl + Shift + V | In the grid list, pastes a copied tag as a child of the selected tag.
Delete | Deletes a single selected tag in the grid list.
Alt + Enter | Opens the properties dialog for the selected tag.
Alt + Up | Navigate up one level in the tag hierarchy
Alt + Left or Alt + Right | Navigate back and forward through the tag browser's navigation history.

Keypress search is available. In grid view and in the select type panel, you can jump to a specific name by starting to type it in. This feature is more intuitive to use if Show Children is disabled.

Tips:

  • During a development session, each new tag of the same type will start out identical to the last of that type, save only the name. This can save time when making several similar tags since you won't have to set the same values over and over. But, if the majority of the fields in each new tag differ from the last, this feature may not be so useful. You can disable it by setting the application property, RememberNewTagParameters to 0.
  • Even with RememberNewTagParameters set, it's often easier to create new tags by copying and pasting existing tags, then changing a few properties to suit the new one.
  • You can export the tag database for editing in a spreadsheet and then import the modified database back into VTScada. This can save time when creating a lot of tags. It's especially helpful when you need to change one property in a long list of tags since the spreadsheet will allow you to do a search and replace on that property.


Icons That Describe Tags

Many of the tags shown in the browser will have symbols drawn in front of them. These tell you something about how the tags were created. You can hover over each symbol in the browser to see a tool-tip definition.

Configuration Field Colors, seen within each tag, also provide useful information

Symbol Meaning
Has child tags. This is a parent tag.
Any tag instance that you have created directly. Not one of the default tags, and not generated automatically like the child tags of a MultiSmart Station.
An automatically-generated tag, within which you have overridden one or more of the default parameter values.

The blue dot can have either of the following meanings:

1) In an automatically-generated tag structure, these are ad hoc tags. They are only available in the particular instance of the parent tag being provided. The other tags are static children that will always be there.

2) In a tag structure generated by the OPC UA address assist tool, this indicates a node of subtype "Property".

Disabled. The start condition evaluates to FALSE, or you have explicitly disabled the tag.
Visible only when the Show Disabled option is selected.


Configuration Field Colors

Tag fields in the configuration panel will change color to provide more information about the type of change that has occurred in them.

Icons That Describe Tags also provide useful information.

Field Color | Meaning
White | Unchanged during current editing session. No over-ride or parameter expression.
Green | The parameter value has been changed from its previous (or default) value in the current editing session. A special case is if the parameter's original value came from code built into the tag type's definition. In that case the color orange will be used...
Orange | A parameter value that was originally defined through parameter expression code has been overridden to use either a specific value or a new expression.
Pale Yellow | Non-inherited value. Similar to an override, but used in the Area field of a child tag if you have provided a new value rather than allowing the tag to use the Area inherited from its parent tag.
Blue | The value is calculated from a parameter expression.
Red | The field's current value is outside the allowed range of values for this field.


Add a New Tag

Viewing: Develop > Tags and I/O > The Tag Browser > Add a New Tag

Concepts:

Tags and I/O

Tasks:

Optimize Your Configuration

Reference:

Tag Reference

Add a New Tag or Child Tag

Adding a new tag by right-clicking

New tags are placed below the currently selected level of the tag tree. While you can always move a tag, it's easier to create it in the right place from the beginning.

There are two ways to create a tag in the Tag Browser: The first is to click the large button at the bottom of the window, labeled "New". The second is to add a new tag by right-clicking on the target level and selecting "New Child" from the menu that opens.

"Child tag" simply means "below the selected level". The point is that it has a parent in the Tag Browser. This gives benefits of organization, clarity in naming, ease of application scaling, and security management.

The Select Type dialog will open every(*) time you add a new tag. The last four types that you created will be listed at the top, making it easy to create another of these types. Below those, tags are grouped according to their use. Tags that have extra features are marked. You can hover the pointer over a symbol to learn more:

Selecting a type

(*) If you had set the Tag Browser's type filter to a specific tag type, then the selection part is done. When you add a new tag, the properties dialog will open for a new instance of the type that matches the filter. If the filter is set to a group, then the Select type dialog opens to that group.

If you know the name of the tag you're looking for, click the tag group to which it belongs or All Tag Types and try typing the tag name out. This keypress search feature is also available in the Tag Browser grid view and the Source Debugger.

After you select a type, its properties dialog (example follows) will open. Every tag's properties dialog has an ID tab, similar to the following image, which will include Name, Area and Description at a minimum.

ID tab of the I/O tag's properties dialog. (Sometimes called a configuration folder.)

There are rules for tag names (Best Practices for Tags). In general, keep the names shorter than 64 characters. Spaces are allowed except at the beginning or end of the name, where they will be trimmed away. Do not use reserved words. ("Test" is a reserved word in this program. So are "Value" and "Area". VTScada will let you know when you bump into others.) Some punctuation characters are allowed (dash and underscore among others), but use sparingly. And, include letters, not just numbers. For example, "Station 51" is fine but "51" won't be accepted. You can find a full list of the rules in the VTScada documentation.

See: Best Practices for Tags.

You're allowed to change the names of your tags, but if you have expressions or anything else that links to the old name, you will need to tell those to use the new name instead. See: Move and Rename Tags.

Fields turn green when you change the information within them. This helps you keep track of what you have changed and what you haven't touched. The green lasts only until you click OK. If you re-open the folder later, all fields will be white again until you start making new changes.

If you create a second tag of the same type, it will be pre-configured with the same values as the last except for the name, and those fields will be marked green so that you know which ones are not default values. This can save time, but be careful not to leave values that should have changed for the new tag. (There's a property to control that behavior: RememberNewTagParameters.

Fields can also turn other colors, depending on how they're configured. See: Configuration Field Colors.
Hover over a field to see a tool tip that tells you more about that field.

To add a new tag to your application:

  1. Open the Tag Browser, using either the button at the top of the page, or from within the Idea Studio.
  2. Check the Address bar at the top of the Tag Browser.
    Ensure that you are adding your tag where you want it to be within the hierarchy. New tags will be added to the selected parent tag.
  3. Check whether a filter is in effect.

A filter in the tag browser won’t stop you from adding a new tag, but it may limit the type you can create or interfere with your ability to see that tag in the list after it has been added. A type filter will limit the list available in the Select Type dialog. This may be helpful or it may be a hindrance.

  4. Click New.

You will be prompted to select the type of tag that you want to create.

  5. Open the appropriate group and select the type.

A new tag properties folder will open.

  6. Configure the tag’s properties.

Notes for every type of tag are provided in the reference section of this documentation.

  7. Click OK.

The new tag will be referenced by its Name and Description in the Tag Browser’s tag list. A tag's full name includes the name of all it's parent tags, separated by backslashes. This can sometimes become too long to display in a field, in which case VTScada will abbreviate the displayed name. Hover the pointer over the field to see the full name, displayed within a tool tip.

If the Auto Deploy option is selected for the application, then this operation is complete. Otherwise, this will be considered to be a local edit until you deploy your changes.

Keyboard Shortcuts for Tag Properties

Key Combo | Description
Ctrl + Z | Undo last action in a numeric or string field. Click on the field that you want the undo to apply to. May be used up until the state of the field the last time changes were applied.
Ctrl + Y | Redo last action in a numeric or string field. Click on the field that you want the redo to apply to. May be used up until the most recent new change.
Ctrl + Tab or Ctrl + PgDn | Switches to the next tab.
Shift + Ctrl + Tab or Ctrl + PgUp | Switches to the previous tab.


Relative Paths - Tag Relationships

In this topic, the examples refer to a driver that is linked to a port. The information holds true for I/O tags linked to drivers, loggers and alarms linked to I/O, etc.

The default auto-linking behavior changed in VTScada 12.2.
Just prior to version 12.2, tags with auto-linking configurations in their tag selector fields (ex. [*Drive], [*Port]...) would only automatically link to direct ancestors.
Older applications can be configured to auto-link with direct ancestors, uncle tags or else sibling tags by enabling the property EnableSiblingTagAutoLinking however this may cause unexpected behavior. Tags that were linked to other tags using an auto-linking configuration may automatically link to another tag unexpectedly and break your application.
Applications created after the release of version 12.2 have EnableSiblingTagAutoLinking enabled by default.

VTScada developers will often build tags in a hierarchy. For example:

Station 1 is a Context. PLC_Port is a TCP/IP Port. PLC1 is a driver...

This method of linking the tags together has several advantages:

  • Tags for a station (or equipment, or anything) are grouped in one place, making them easy to find.
  • Adding new stations is a matter of copying only the one top-level tag. Child tags are copied automatically.
    (Tools are available to automate much of the work when duplicating stations or equipment.)
  • Tags that need to link to another tag (linking to Driver tags, Port tags, Alarm Database tags, Publishers, Historians, Style Settings and so on...) will automatically link to relevant ancestors and siblings. Direct ancestors will prevail over siblings. For example, the driver in the example hierarchy will find the port without you needing to select it during configuration.
  • Keeping flatter hierarchies and avoiding deeply nested hierarchies will results in more succinct full tag names that make it easier to use tag selectors, troubleshoot and generate easy-to-read reports.

#1 There are many ways that a hierarchy can be built and there is no single method that can be considered "best" in every instance. After reading this topic, take time to consider your system and decide on a tag hierarchy that will work for you.

#2 If you change your mind after changing how tags link together, you can easily restore the original configuration by doing a right-click on the parameter then selecting "Reset to Default". This option is enabled only for properties that have a default.

Links between tags

As an example, when a driver is linked to a parent Port tag, the configuration field for the port would look like so:

[*Port] is expression code. Building it up piece by piece it means:

[ ]       "Look for a tag..."
[* ]      "Look for a tag of type..."
[*Port]   "Look for a tag of type port"

This will find the first relative tag of the correct type. If a tag is found, its description field is shown following the [*...] code.

This type of link between tags is useful if you copy tags for a new site. Instead of having to reconfigure the driver copy to use a different port, it will simply attach to the closest ancestor that is a port. If there is no port ancestor it can auto link to a sibling port. On the other hand, it can become difficult to manage tags if there are too many levels.

Links between tags by default

This overly simplified hierarchy only serves one purpose: demonstrating default links between tags.

In the provided example, there is only one context tag to mark the top of the hierarchy. All 'Driver #' tags are Modbus Compatible Device tags and all 'IO#' tags are I/O & Calculations tags. The IO# tags will link to the Driver tags like so:

IO1 → Driver 1

IO2 → Driver 2

IO3 → Driver 1

IO1 will link to Driver 1 because Driver 1 is IO1's ancestor. Even though Driver 2 is a sibling of IO1, the ancestor (parent, grandparent etc) will prevail. IO2 will link to Driver 2 because it is the closest ancestor. IO3 will link to Driver 1, a sibling, because it has no ancestor tag that is a Driver.

No matter how the tags link by default, you can always manually override the selection using the tag selector or select a specific relative pathway. The button between the X button and the Tag Browser button gives you a choice of how to specify the link. Each is useful in its own right.

Choice of tag relationships

Ancestor relative path [*Port]

The default for child tags. The driver must be a child of the port before you can use this. That's where the "ancestor" part of the name comes in. The driver will find the closest parent, which might be several generations back.

Open relative path [Sim Host]

The default for siblings. This is "open" in the sense that it does not point to a specific tag and "relative" in the sense that the position of the tags in the hierarchy matters. Imagine if you create Station 2 by copying all of Station 1. If you were using open relative path, you would still need to change the IP address in the port, but the copy of the driver would be looking for the nearest port named "PLC1_Port", not the specific one within Station 1.

>> Note that if the name changes, the link breaks.

Fixed depth relative path [..\PLC1_Port]

Like the previous, but not open. This option says to find a tag with the matching name, the matching number of generations away. Each generation back is specified by a dot-dot-backslash ..\

Absolute path [<Station 1\PLC1_Port>]

Use that tag and none other. The full tag name must be provided, right from the top of the hierarchy. This is tied to the selected tag's unique ID, so the port tag's name can change but the link will be kept to exactly the same tag.

It may be interesting to note that when working in the Tag Browser, the default for new tags will be Ancestor or Open Relative. When drawing tags in the Idea Studio, the default relationship between the widget and the tag is Absolute. You can rename or move a tag with confidence that it will remain linked to the same widget.

If there are two of the same tag type at the same level (such as two sibling Driver tags), the auto-linking tag will not link, and the tag selector field will show an error:

Examples of Tag Hierarchies

Following are a few examples of how tags might be organized...

1. Flat.

All tags at the same level. This method is outdated but you may see it in very old applications.

Flat tag structure.

If your application needs more than 10 tags then don't do this. (Also, write better names and descriptions than those shown in this example.) If your application needs less than 10 tags, a context tag is still a best practice.

Prior to the introduction of Context tags, this was the only way to organize tags. Knowing how to use filters in the Tag Browser was an essential skill in order to find any given tag.

2. Simple

One PLC, very few I/O.

Communication, Driver and IO are siblings under a context tag.

A simple hierarchy

Create a context tag as the parent. The driver, the port and the I/O are all siblings. This will save a great deal of configuration time while creating the I/O as they will link to their siblings automatically.

It's also easy to copy this structure if you add a second or third PLC with a similar set of I/O.

3. Simple sites

Each new PLC is grouped under a context tag and complex devices (such as a pump) are grouped under nested context tags. This design is easy to scale up and parse down. Tags that link to other tags will auto-link with ancestor tags or else a sibling of the correct type. So, for example, the I/O tags nested under the Pump 1 Context tag will find the driver nested under Site 1, a Speedset will link to a Driver as an ancestor.

Simple site hierarchy

Do not assume that "site" can only mean "location". A "site" could just as easily mean a pump, a generator, a lift station, or anything.

4. More complex sites

Hierarchies in the tag browser are flexible, scalable and can grow with the system needs to become quite complex. There is a large catalog of tags that serve a wide array of purposes

A moderately complex hierarchy

As projects become larger, complexity increases. Use care and plan ahead. Create as many levels in your tag hierarchy as you need, but do not let this get out of control. Having too many levels can be as hard to manage as having too few.

Ancestor pathways are not contained by context tags. In the following example, Driver 2 prevails because it is an ancestor of IO1. Despite residing together under the same Context tag, Driver 1 is merely a sibling of IO1. If Driver 2 did not exist, Driver 1 would have auto linked to IO1.


Constant, Expression or Tag

When configuring a tag, you will often find three ways to set a property value: Constant, Expression or Tag. For example, when configuring an Alarm tag, you will have the option of setting a delay on the alarm. Depending on your choice of constant, expression or tag, the configuration parameter will look like one of the following examples:

Tag configuration - Constant

Tag configuration - expression

Configuration option - tag

Another option is available for all other tag parameter fields: By right-clicking you can create a tag parameter expression. Tag parameter expressions are typically used for automated tag configuration.

The ability to right-click on a parameter to add an expression does not apply to parameters that provide the options Constant - Expression - Tag. For those, use the tools provided instead of the right-click menu.

The following is provided as a guide to help you choose the option best suited to your application.

Constant

Constant should be used for any parameter that is unlikely to change. You can always come back to the properties dialog to update the value, but otherwise ‘constant’ means ‘unchanging’. Select this option for all values that should remain as you configured them.

Expression

Expressions are snippets of the VTScada programming language that you can write to create values that change with changing conditions. For example, you could create an expression that sets this parameter to the average of 3 or more other tag values. Another expression might change an alarm setpoint depending on current conditions.

Select this option when you want the parameter’s value to be based on a formula, usually referencing other tag’s values. The result will be the similar to (but slightly more efficient than) a Tag Parameter Expression with the optimization option deselected.

The button [image] opens the expression editor. The button [image] clears the current expression. The word ": Invalid" means either that no expression has been provided, or that the result of a calculation is meaningless, such as dividing by zero.

This type of expression cannot use functions that are marked as "Script-only".

Tag

Many parameters can take their value directly from another tag. That other tag might be an operator control for setting a value, such as an alarm set point or delay. The selected tag need not be one for which you have provided an operator input - any tag with a value can be used to set the parameter’s value.

Select this option when you want to have a parameter’s value match another tag’s value.

The tag browser button will open the Tag Browser, from which you can select or create a tag whose value will be used. The "X" button clears the selected tag.

The link button is used with parent-child tag structures to control how the selected tag fits into the overall structure.


Move and Rename Tags

Full tag names describe the tag's place in the hierarchy. Thus, moving a tag and renaming a tag are essentially the same operation.

There can be side-effects when moving a tag. Details vary with the situation. Use care in the following cases: an I/O tag configured to use the nearest parent driver, a tag with a parameter expression that refers to another tag, a tag that is part of a user-defined type.

A tag's unique ID stays the same in nearly all cases when renaming(*), therefore logging, alarms, reports, widgets, etc. will not be affected. But, anything that is based on the user-friendly name, including any expressions you may have created, are likely to break. See the examples and cautions at the end of this topic. (* The exception is a cut-and-paste operation. Cut is equivalent to delete. The following paste creates a completely new tag.)

Note that you can select multiple tags in the Tag Browser's main window by holding down the Ctrl key while selecting. Use this to copy, move, or delete several tags at once.

To rename a tag:

  1. Select the tag in the Tag Browser
  2. Click Properties, or right-click on the tag and select Properties from the context menu.
  3. Change the text in the name field.
  4. Click OK.

Rename a tag from "Pump1\Op Status" to "Pump1\Running".

To move a tag:

  1. Select the tag to be moved, in the Tag Browser
  2. Right-click on the tag and select Cut, or click the Cut button.

... or ...

  3. Right-click on a tag elsewhere in the hierarchy, under which you want to place the original tag.
  4. Select Paste as Child
    You will be reminded that references may need to be updated - see following notes on the effects of changing the name.

  5. Click Yes to acknowledge the message and complete the move, or No to cancel the move.

Move a tag from Pump1\Op Status" to "Pump2\Op Status".

Effects of changing the name:

  • Expressions that referred to the tag may need to be updated.

Expressions are created by users, not by VTScada, and use the tag's name rather than the unique ID. Changing the name of the tag will usually mean that the expression will need to be changed to use the new name. An exception to this is if both the referencing tag and the referenced tag are moved together. In this case, the reference is likely to survive, but it is wise to check.

  • The link between tags may be affected depending on whether that link is Ancestor Relative Path, Open Relative Path, Fixed Depth Relative Path or Absolute Path. See: Relative Paths - Tag Relationships
  • Potential for confusion

If operators are used to seeing the tag with one name, changing its name to something else is likely to cause confusion.

Examples and Cautions

Logged history, tags drawn on a page, reports, built-in alarms and network values are all associated with the tag's unique ID, not the name.

Example 1:

You have an Analog Status tag named AAA, which has logged history and which is drawn on a page. You delete that tag. You then create a new Analog Status tag and name it AAA.

The new tag has a new unique ID and therefore nothing that was associated with the old tag's unique ID will be associated with the new tag's ID. This may surprise anyone who used older versions of VTS where tags were identified only by their name.

Example 2:

You have created a new type of tag, DrainValve. DrainValve was created using two tags: a parent Context tag (Valve1 in this example), and a child Analog Status tag named Flow. (See: Design Your Own Tags)

Sample tag structure with user-defined types.

You move Flow from Valve1 into Pump 1 by doing a cut and paste operation.

When asked whether you want to redefine type ValveType, you decide upon "No".

Warning when moving a tag from a user-defined type.

If you choose "No" you cause the operation to be a cut (delete) and paste (create new tag) rather than a move. WaterPipe gets an Analog Status tag named Flow that is identical to the original, but which is a new tag with a new unique ID. Logged history, etc from the original Flow is now unrecoverable.

When synchronizing version changes, a move trumps a modify.

Example:

You have installed the application on two, unconnected computers. On one computer, you move a tag to a new location in the tag tree. On the other computer you leave the tag where it is, but change its properties.

You then connect the two computers (or take a ChangeSet from one to the other), thus allowing the version control system to synchronize the application on both machines.

In the final synchronized version, the tag will have been moved. The property changes will not be included in the running version.


Copy an Existing Tag

Viewing: Develop > Tags and I/O > The Tag Browser > Copy an Existing Tag

Copy a Tag

VTScada applications often have many similar tags. For example, ten pumps or twenty wells, all with similar I/O. For this reason, the Tag Browser includes a Copy button that can help you to create large numbers of similar tags quickly. (*)

Note that you can select multiple tags in the Tag Browser's main window by holding down the Ctrl key while selecting. Use this to copy, move, or delete several tags at once.

The steps to create a new tag based on a copy of an existing one are as follows:

  1. Open the Tag Browser.
  2. Use the Tag Browser’s searching and filtering capabilities to locate the tag whose properties you want to copy.
  3. Right-click on the tag and select "Copy" from the context menu, or select the tag and click the Copy button at the top of the Tag Browser.
  4. In the tag browser, locate the destination parent tag and right-click on it to open a menu.
    Every new tag must have a parent. This may be any other tag, or it may be the root level (\).
  5. Select "Paste as Child".

If the parent already has a child with the same name, you will be prompted to create a new name for the copy. Do so now.

  6. Open the new tag's configuration folder to adjust properties as required.

The copy will have a new unique ID and therefore no access to any information logged from the original.

If the Auto Deploy option is selected for the application, then this operation is complete. Otherwise, this will be considered to be a local edit until you deploy your changes.

(*) If copying groups of tags that relate to a single object such as a well, generator, or pump, it's better to create a custom tag type for that device than to copy groups of individual tags. See Design Your Own Tags.


Driver Discovery

Configure the Driver Discovery dialog according to the device and location you want to search. Details may vary according to driver type. After configuring, press the Start button to begin the discovery process. A progress dialog will be displayed while the process is underway.

This example shows driver discovery for the Delta Driver, which uses only the general settings.
Driver-specific settings for other driver types are described later in this topic.

Driver Type

Select the type of driver you wish to search for. Supported drivers include:

  • BACnet Driver
  • Delta Driver
    (Applies only to Delta AH, AS and DVP PLCs )

Created Port Type

Used after discovery is complete and VTScada is about to create the port tags. Each driver will have their default choice (BACnet: UDP, Delta: TCP) but you can override that using this property.

Broadcast Machine

Should be set to the expected I/O Server

Adapter/Subnet

Select the internet adapter and corresponding IP Subnet to send the broadcast on.

Broadcast Address (Optional)

If not specified, VTScada will use the default broadcast address of the chosen subnet. (e.g 192.168.22.255) The broadcast address will also be the address from which the tool captures packets.

Port

Automatically set to the driver default.

Time Limit

The time to allow a discovery action to take place.

Maximum Number of Responses

Limit the number of responses that will be accepted.

No Valid Tags Found

If no driver information can be found on the specified Adapter/Subnet and port within the time limit allowed, the process will be aborted and an alert message displayed. Review the configuration to ensure the selected Broadcast Machine has communication with the remote devices.

Driver-Specific Configuration: BACnet

Minimum Device ID / Maximum Device ID (BACnet specific)

Allowable device IDs to respond to the Who-Is request. Typically left at the default range but can be set if only interested in locating a subset of BACnet devices.

Foreign BBMDs (BACnet specific)

Set the IP addresses of the BBMDs that will forward the Who-Is request to their foreign networks.

Hop Count (BACnet specific)

The number of times to forward the Who-Is request on the BACnet network. Typically done in a nested router situation.


Import Tags from PLCs

This feature is available for the following drivers:
* BACnet devices
* Bristol devices
* Delta
* MQTT Sparkplug B devices
* OPC Classic Client devices
* OPC UA Client devices
* Rockwell CIP devices

Examples in this topic show tags being imported from a Rockwell device.
More devices will be added as it becomes possible to do so.

The import button is located on the bottom toolbar of the Tag Browser. It is enabled only when a supported driver is selected.

Valid device selected for a tag import.

Information available from the PLC does not always map cleanly to tags, therefore the tag importer must make assumptions. Always review the list carefully.
This is particularly true with OPC UA where the import tool will place certain properties of tags inside a parent I/O tag where possible instead of bringing them in as separate I/O tags. If the latter functionality is desired, the user will have to create their own independent I/O tag for this purpose.

Preparation:

You cannot import tags unless:

  • Your application is not pending a restart.
  • Your account has the Tag Modify privilege.
  • You have selected a valid driver tag in the main window of the Tag Browser.
    Do not attempt to work from the left, tag-tree window.
  • No other actions are in progress.
  • The selected driver tag belongs to the current application, not a subordinate application.
  • The Import Tags dialog is not already running.
  • The selected driver is ready to start the Import process.

Tags are typically imported as type, I/O and Calculation. Parent Context tags are created as needed. If a tag already exists in your application, defined parameters from the import will override those in the existing tag.

Tag names that are invalid, excepting those that are blank or too long, will be modified to become valid, then imported. The modification will typically take the form of an additional underscore, or underscore + digit.

Steps to Import:

  1. Select a valid tag.
  2. Select the Import button.
    If problems are encountered, you may see one or more of the error dialogs described later in this topic.
  3. Use the Importing Tags dialog to filter for and deselect any that do you not want to import.
    This dialog is a variation on the Tag Browser, and works in much the same way, but note the additional filtering options.

The Importing Tags dialog is a simplified view of the Tag Browser. The main Tag Browser remains open in the background.

To select or deselect all tags shown in the list you can select or deselect the check box in the list's label bar, to the left of "Name". Selecting or deselecting a parent tag will select or deselect all of its children as well.

You may view and deselect tag parameters before importing tags. Click on a tag to enable the parameter button. The parameter button will remain disabled for tags that don't have any parameters to display, including auto-generated Context tags. You can use the parameter button or double-click on a tag to open the parameters dialog.

If the tag is checked in the Import Tag Selector, all parameters will be selected by default. If a tag is unchecked in the Import Tag Selector, all its parameters will also be unchecked.

Tags selected for import, that only have partially selected parameters will display a semi-circular icon in the Tag Import Selector table, see the included legend for guidance.

Closing and reopening the Import Tags dialog will reset all parameter selections.
Use care not to lose track of the Importing Tags dialog by minimizing it or moving it behind another window.

  4. Click OK to finish the import.

The Importing Tags dialog is displayed while the operation runs.

Conflicts

Note the Conflicts Only option in the filter. A fully filled yellow circle is displayed when all or no parameters are being imported. A partially filled yellow circle is displayed when only some parameters are selected for import. Local properties will be overridden by matching tag that you choose to import.

Tag name conflicts before importing

You will be warned. Example showing errors from the deprecated CIP driver.

Import Tag Errors dialog

Displayed if any of the following problems are encountered after attempting an import.

Tag names that are invalid for any reason other than those following, will be modified to become valid, then imported. The modification will typically take the form of an additional underscore, or underscore + digit.

  • The full tag name exceeds 253 characters.
  • The given tag type does not exist.
  • The tag's name is blank
  • An ancestor cannot be imported for any of these reasons.

A contrived example to illustrate tags that can not be imported.

Related information:

Write a Custom TagImport API


Operate from the Tag Browser

If a tag can write to hardware (that is, it has an write address) and if the currently signed-in operator has the correct privileges to do so, then they can write a new value directly from the Tag Browser.

In addition to the custom privilege protecting the tag, the user must have at least one of the following privileges: Tag Modify, Tag Add/Copy or Tag Delete. Without at least one of these, they do not have access to the Tag Browser.

This feature does not give users any new or additional access to operate hardware. They must be able to open the tag browser, see the tag (no realm-filtering restrictions) and possess the custom privilege protecting that tag.

Changing an analog I/O tag's value

Note that in the case of a Selector Switch output, the user will be presented with the Horizontal Buttons widget rather than an Numeric Output widget.

Operate tags other than I/O tags

The following types do not have write addresses, but can be operated from the Tag Browser:

Counter Tag

Operating this tag will reset the counter. Enabled only when a valid source is defined.

MultiWrite Tag

Will trigger the multi-write to occur. Enabled only when there is at least one output.

Report Tag

Will run the report configured within the tag.

Totalizer Tag

Will reset the current total. Enabled only when a valid source is defined.


Delete a Tag

Tags can be deleted using the tag browser.

If you delete a parent tag, you will also delete all of its child tags.

If you delete a tag, everything that referred to that tag's unique ID value will become inaccessible. Widgets will display the unlinked indicator, and is no way to retrieve logged data.

  1. Open the Tag Browser.
  2. Use the Tag Browser’s searching and filtering capabilities to locate and select the tag you wish to delete.
  3. Right-click on the tag and select the Delete option from the context menu.
    Alternatively, you can select the tag, then click the trash can icon at the top, right of the browser.

A confirmation dialog will open and request confirmation that you wish to delete the selected tag. If you delete a parent tag, you will also delete all of its child tags.
If the tag is used in any pages, you will be warned and given an opportunity to open the Go To Page dialog. Use this to review how the tag is used in any page that you have security rights to open.

  4. Click OK.

If the Auto Deploy option is selected for the application, then this operation is complete. Otherwise, this will be considered to be a local edit until you deploy your changes.

If you create a new tag with the same name as the one deleted, it will have a new unique ID value and therefore no connection to anything that referred to the deleted tag.

If you later change your mind after deleting a tag, you can use the Version Log (provided that your VTScada license includes this option) to revert the change.

Disabling a tag has the same apparent effect on the application as deleting it (the tag stops, related widgets are hidden, the tag count drops). The difference is that you may re-enable the tag at any time. Previously logged data can again be retrieved. See: Disable Tags.

Note that you can select multiple tags in the Tag Browser's main window by holding down the Ctrl key while selecting. Use this to copy, move, or delete several tags at once.


Disable Tags

You can disable any tag listed in the tag browser. The tag will stop running, and will be removed from view unless Show Disabled is selected. Disabled I/O tags are not counted against your license.

To disable a tag, right-click on it and click to remove the check mark from the line, "Enabled".

Enable or disable a tag

You might choose to disable a tag if you do not intend to use it for a period of time, but you do expect to use it again, or you will need access to it's logged data and therefore do not want to delete it.

You can view disabled tags by selecting the Show Disabled option in the Tag Browser.

Show disabled tags

Tags can be disabled automatically by use of a Start Tag Expression in the Name field. This is often used when building tag structures automatically. For example, you might create a lift station or well that can have one to four pumps. The tags for Pump 2, Pump 3 and Pump 4 would be configured so that they will be disabled in stations where they are not required. See: Design Your Own Tags.


Go To Page

Use the Go To Page command, found in every tag's right-click context menu in the Tag Browser, to navigate to any page that contains a widget linked (directly or indirectly) to this tag. With this feature, you can quickly view a tag as drawn in the context of the application.

If the Idea Studio is open when you use this feature within the Tag Browser, then that page will open in the Idea Studio.

Note that for containers including Station tags, Context tags, and Polling Drivers, the Site Details page is always included as a destination, even if there are no other tags within this container.

Notes:

The Go To Page feature can be disabled by setting the application property, DisableGoToPage to TRUE.

VTScada programmers can create a module that will intercept this call, for tasks such as opening a specific page in all cases or to prevent navigation for specified tags. See Hook for "Go To Page" calls.

There are three situations where it is helpful to set Exclude from Site List on your Context tags:

- When requesting a Go To Page on any Context tag (or other container type) from the Tag Browser or Alarm Page, the Sites page will be included in the list of possible pages and might be the default.
- The above is also true for child tags of the Context tag.
- Context tags (and new types created from them) are always included in the list of a Sites List Display Options. This may not be appropriate if the Context represents equipment rather than a site.

To prevent these actions, do the following:
1. Select the Add Site Properties button in the Settings tab of the Context tag.
(See: Change the Parameter List if you have already turned the Context into a new type.)
2. Delete all site properties except for SiteListDisplay.
3. In the Display tab, select the option Exclude from the site list
(If any child tags should be included in a site list then select Display as a Folder instead.)

To go to a page:

  1. Right-click on the tag in the Tag Browser.
  2. Click, Go To Page.

If only one page has a widget linked to the tag, that page will open immediately. If there is a choice of pages, then a dialog will ask you to choose which page to view.

Entries in the Go To Page dialog respond to a left versus right click in the same way that entries in the menu do. That is, if the page has no restrictions on how it can be opened, a left-click will open it in the main application window and a right-click will open it as a pop-up.

If there are no pages containing widgets linked to this tag, or if all such pages are protected by security privileges that your account does not have, then you will see the following message:


Plot Trends From the Tag Browser

If a tag can be viewed as a trend plot in the Historical Data Viewer (HDV), then you can open the HDV for that tag directly from the Tag Browser list. All selected tags will be included in the plot. See: Historical Data Viewer (HDV)

To plot from the Tag Browser:

  1. Select one or more tags.
  2. Right-click on one of the selected tags in the list.
    A context menu opens.
  3. Click, Plot.
    The HDV page opens as a pop-up window, showing the trend plot of the selected tags.

Troubleshooting:

  • The plot entry is disabled.

The selected tag cannot be plotted in the HDV.
Your account does not have permission to view the Historical Data Viewer page.


Tag Change History

Every change to a tag's configuration is recorded in the VTScada version control system. Hover the pointer over a field to determine when the last change was made and by whom. You can easily spot fields that have been changed during the current editing session, as the background color of changed fields will turn green. The background highlight lasts only for as long as you are editing the configuration folder - each time you open a tag's configuration folder the fields will not be green, waiting for fresh changes.

(Certain actions may cause the field to turn yellow or blue, where each color has a meaning. See: Configuration Field Colors)

Before editing.

After editing.

If security is not enabled, no user name will show in the history. Otherwise, the name of the user signed in at the time the change was made, will be used.

Viewing the change history

Operational changes such as opening and closing valves are stored in the Alarm History, not the version history. See: Alarm history list

Changes that result from importing a tag file are attributed to the user who imports that tag file. See: Edit Tags Outside of VTScada

The format of the displayed tooltip is controlled by a set of application properties. See: Tag Properties, starting with "ParmInfo".


Tag Identification

Navigate to the Tag Identification dialog by clicking the ellipsis button beside the Name field found in the ID tab of any tag property accessed from the tag browser.

Information Available

Tag Created

Displays the date and time that the tag was created.

Name

Displays the name of the tag as seen in the tag browser. Styled as a breadcrumb trail, this name is determined by the parent/child relationship of the tag relative to other tags in its hierarchy. This field is not editable. The last portion of this name can be edited by changing the name of the tag in the ID tab and the rest of the name will be altered if the tag is moved. See Move and Rename Tags for more details.

Copy this name by highlighting and typing Ctrl+C or by clicking the double page button ( [image]) next to the Name field. This will add the text straight to your clipboard.

Unique ID

This identifier is immutable. It is completely uneditable and unaffected by changes made to the tag (location or otherwise). VTScada uses this identifier to keep tabs on this tag and its history in a secure and stable manner that affords the user more flexibility in their application. The name of a tag may change, its location may change, the language used may change but expressions and hierarchies will not be disrupted because it is this immutable and unique ID that VTScada goes by. You may have stumbled upon unique IDs when using expressions or glancing at the code.

This field is useful for debugging and troubleshooting. Copy this ID by highlighting and typing Ctrl+C or by clicking the double page button ( [image]) next to the Unique ID field. This will add the text straight to your clipboard.


Add New Menu Items

Menu item tags work differently than I/O and other configuration tags. They can be added only to the Menus section of the Tag Browser, and they are configured using a specialized properties dialog rather than a set of configuration panels.

To add new menu items, you can work in the Tag Browser, or you can right-click on the Page Menu page. Menu items include the palettes of widgets and images in the Idea Studio, so you can also right-click on a palette to edit those menu items.

Depending on where you click, you will be presented with a different dialog, appropriate to that level of the Menus tree.

In the Tag Browser:

  • Click at the top level, Menus, and the dialog will prompt you to create a new folder(1). Specific widget or page menu links are not allowed at this level.
  • Click at the Menus\Drawing Tools\Images level and the dialog will give you options for a folder, an image or a menu item reference. Similarly for shapes and widgets.
  • Click on the Menus\Page Menu level, and the dialog will give you options for creating a folder, divider, page item or menu item reference.

On the Page Menu, or in an Idea Studio palette:

  • Right-click on a folder and you will have the option of creating a new child item within that folder.
  • Right-click on a page, widget or image button and you will have an option of creating a new menu item at the same level in the menu structure.

(1) If you add a new folder immediately below Menus, it will be ignored. Only the top three folders, Widgets Images and Shapes will be shown. Add new folders and menu items within one of those.

You can rearrange the standard menu and palettes, organizing them however you please. But, if cutting a standard folder, note that it will appear to have been removed as seen in a menu or palette, but will remain in the Tag Browser. This ensures that if a later VTScada upgrade adds new menu items, the standard folder structure will remain available.

Versions of the New Menu Item Properties dialog:

General Selection

(Content varies according to where in the Menus tree the new item is being added.)

A new menu item being added at the Page Menu level.

Because the content of this dialog will vary according where in the Menus tree you are adding the tag, please refer to the following descriptions for specifics.

New Folder

Folders exist to help organize the various menu items. They can be added at any level of the Menus structure. (See cautionary note(1), above.)

New Folder

Title: The title is the display name for the folder. You may click New Thumbnail to select any image on your VTScada images collection. The default image measures 244 x 183 pixels, therefore an alternate image will display best if it is near to those dimensions.

Folder Contents are filtered according to where in the menu tree the folder is added. The example shows "Pages", therefore this folder is being added below the Menus\Page Menu branch.

The following options exist only when a folder is being added to the Page Menu branch. They are not available in folders added to any of the palettes.

Hide Recent Pages: Recently visited pages are displayed in a list across the top of the tiled menu, making it easy for operators to reopen commonly accessed pages. By hiding the list, you make more room available on screen for the pages shown within the folder.

Hide Labels: The label is the name of the page, ordinarily shown below each page image in the folder view.

Hide Folder Path: The folder path is the navigation bar, beginning with the home icon.

Select this option when it is necessary to make the maximum possible space available to the folder contents.

Shape / New Code

Similar to creating a new group, but potentially more powerful when used by developers who can work with VTScada script code.

New shape / new code

Title: The title may be either text or an expression.

Code: To add code, open the expression editor using the editor button.

The simplest method of adding code is to draw something in the Idea Studio, then copy the image(s) and paste directly into the expression editor. Edit as required to achieve your design. References to tags may be added as required.

Shapes are based on VTScada script code. When editing a shape, refer to the function reference in this manual for details.

Menu Item Reference

Used to create a reference to an existing menu item tag. This is used to include the same widgets, images, etc. in multiple folders. If the reference is to a parameterized page, there is no option to specify values for the parameters. The values used for the original will also be used by the reference.

Reference menu item

The advantage of a reference over a copy is that if the original item is deleted through the Idea Studio, (but, not if through the Tag Browser), then all reference instances will also be removed, automatically.

Page Menu Item

A page must already exist before it can be added using this dialog. Use the Select Page button to open a dialog, from which you can choose the page to be added to the menu. See also: Add Navigation.

Page menu item

Title versus Label: The title is the name of the page. You may wish to assign a label other than the title, to add clarity for the operators. If creating a series of links to the same parameterized page, each using a different set of tags or values, it is strongly recommended that you assign a meaningful name to each menu item and parameter set.

Select Page: Opens a list of all pages in the application, from which you may select the page to be linked to this menu item.

Set Parameters: The Set Parameters button will be enabled only if the selected page has parameters. If so, it is strongly recommended that you assign tags or values for the parameters in the menu link so that operators are not confronted with a dialog prompting for values.

Divider

Divider menu item

When the title is left as [divider], this menu item adds a horizontal line across the list menu. Has no effect in the tile menu.

Use dividers to help operators navigate a large list menu by grouping similar pages between dividers.

You may substitute any word or phrase for the title. If doing so, it is recommended that you do so in a way that makes it clear that this is a divider, not a page. Leading and trailing punctuation characters are commonly used for this purpose.

Widget

Widgets are used to represent tag values using some type of animation, or to provide operator-interface controls. An extensive collection of widgets is provided with VTScada, and you can create your own.

Used to organize items in the Widgets palette.

The widget must exist before it can be added to a new menu item tag. Use the Select Widget button to locate and select it.

A default title is provided, but it is strongly recommended that you provide your own. Click the Specify Label button to enable typing in the Title field.

Image

Used to simultaneously import new images into your application folder and add them to the Images group of the Menus tree.

Used to organize items in the Images palette.

In general, you should navigate to the appropriate folder of the Images sub-tree before adding a new menu item. Because well over a thousand images are provided with VTScada, it is important to keep the menu organized by type so that you can find any particular image that you need.


Build the Communications Chain

Before creating I/O tags, you must configure the connection between VTScada on your computer and the hardware at the remote site. This is the role of the tags in the communications chain.

There are three links in the chain:

  • The port (serial, TCP or UDP)
  • The driver (communication protocol for your device)
  • The I/O (addresses on the PLC or RTU)

Some applications also have one or more of the following optional links:

  • Polling driver - Groups I/O at a station and controls the timing of communication. Often used with radio communications.
  • Driver Multiplexer - Allows I/O to switch between alternate routes of communication as needed.

Ports (See: Port Tags)

Port tags describe the path for communication between VTScada and the physical hardware. If the hardware is connected to your server via a serial port, you will need a Serial Port tag, specifying the COM Port to use, the baud rate, parity, stop-bits, etc.

If the connection is made over an Ethernet network, you will need a TCP/IP or UDP/IP port, configured to use the correct IP address or DNS name, and port number.

General steps to create a Port tag:

  1. Open the Tag Browser.

  2. In the Tag Browser, click "New". You could also right-click on the backslash in the tree view window and select "New" from the context menu that opens.

new child tag

  3. In the Select Type dialog, open the Ports group, then choose the appropriate type of port for your application: Serial, TCP/IP or UDP.
  4. In the Tag Properties dialog, provide an appropriate name, area and description for the new tag.
  5. Open the Connection tab and define the parameters to match your hardware.

Drivers (See: Communication Driver Tags)

Drivers connect to Ports and define the protocol used to communicate with your hardware. Which one you choose will depend on the specifications of that hardware. More than 35 drivers come with each copy of VTScada and many more are available on request. Each brand of PLC or RTU generally requires its own communication driver. (Some also allow an alternate protocol. For example, many have a Modbus Compatibility mode.)

In addition to the driver, you might add a Polling driver to control communication frequency. You can add a driver multiplexer to define an alternate line of communication in the event of device failure.

To create a Driver tag:

  1. Open the Tag Browser.

  2. [Optional step] Navigate through the tag tree if you want to create the driver as a child of an existing Port tag.
  3. Click the button, New.
  4. In the Select Type dialog, open the Drivers group and choose the appropriate type of driver for your application.
  5. In the Tag Properties dialog, provide an appropriate name, area and description for the new tag.
  6. In the remaining tabs, provide the configuration details that are appropriate for your device.

By creating the driver as a child of a Port tag, the linkage between the two will be automatically configured to have the child automatically connect to the parent tag. If you chose not to create the driver as a child of a Port tag, it will automatically connect to the nearest available relative. You must select a Port tag before this driver will be able to communicate with hardware.

Since VTScada 12.2, tags will connect to uncle (shared grandparent) or sibling (shared parent) communication tags (ports, drivers, etc.) if they cannot find an appropriate parent Port tag.

Input / Output Tags (See: Input Tags, Output Tags)

I/O tags receive values from or send values to specified addresses on the PLC or RTU. They depend on the configured driver tag to provide the connection details and the protocol for the device. The I/O and Calculations tag can be used for analogs and digitals, inputs and outputs, and (naturally) calculations. Single-purpose legacy tags are still available for each of those tasks, but only for the sake of backward-compatibility.

Addresses must be provided by the person who configured the hardware. For some drivers, an Address Select or Address Assist dialog makes address configuration a matter of selection from a list. For all drivers, the VTScada documentation includes guidelines for their address format.

Security... Output tags are secured by assigning a custom privilege to the tag, then granting that privilege only to authorized users.
It's more efficient to plan for security at the beginning of a project, protecting each output tag as you create it, than to return later to update a large number of tags.

(See: Data Suffixes for Tag I/O Addressing)

To create an I/O tag:

  1. Open the Tag Browser.

  2. Right-click on the driver tag in the tree view window and select "New Child" from the context menu that opens.
  3. In the Select Type dialog, choose an I/O and Calculation tag.
  4. In the Tag Properties dialog, provide an appropriate name, area and description for the new tag.
  5. Select the correct mode for the I/O you intend to read or write.
    (Within reason, you can change your mind about the mode later.)
  6. In the remaining tabs, provide the configuration details that are appropriate for the type of I/O being configured.

By creating the I/O tag as a child of a driver, that part of the configuration will be filled in for you. If you chose not to create the I/O tag as a child or sibling of a driver tag, you must select (or create) a driver tag before this tag will be able to communicate with address specified in the hardware.

Address Coalescing

Contiguous I/O addresses (in the same “Block”) are read all at once, so long as all I/O have the same polling rate. For greater efficiency, try to keep your I/O addresses together and do not assign varying polling rates unless necessary.

Optional Links in the Communication Chain

Polling Driver Tags

Polling driver tags are designed for use in telemetry applications where communication links may be costly, either in terms of time or money. Polling drivers should be linked between a communications driver tag and the I/O tags. Their function is to control the order and the frequency of data transfer between the I/O tags and the remote equipment via the communication driver tag.

Driver Multiplexer

Driver multiplexer (DriverMUX) tags allow you to set up redundant or alternate lines of communication between I/O tags and equipment. Possible uses for this tag include establishing a fail-over communications route if one system is lost, and load sharing between two lines of communication.

Setting up fail-over protocols for Polling Driver tags is accomplished with shared RPC services. Indeed, shared RPC services are enabled by default in Oil & Gas applications. If you are interested in learning about this advanced topic, check out RPC Manager Service


Communication Chain Examples

All connections take one of the following forms. Terms used in this illustration are defined in the following table.

Native Serial | Driver supports native serial communication as defined in protocol standard documents on PC serial ports using VTScada Serial Port tags.
Modem | Driver supports native serial communication as defined in protocol standard document(s) over modems defined in the operating system.
Native TCP/IP | Driver supports native TCP/IP communication to devices as defined in the protocol standard documents.
TCP/IP Tunnel | Driver supports tunneling of serial protocol via Ethernet connected TCP/IP to serial converters using VTScada TCP/IP Port tags.
Native UDP/IP | Driver supports native UDP/IP communication to devices as defined in the protocol standard.
UDP/IP Tunneled | Driver supports tunneling of serial protocol via Ethernet connected UCP/IP to serial converters using VTScada UDP/IP Port tags.
Other Connection | Driver supports device or protocol-specific interface or methodology not covered by these definitions. (For example, ODBC.)
Virtual PLC | Driver supports VTScada acting as a memory-mapped PLC or RTU that other devices can read from or write to.

Common Arrangements

A few common arrangements follow. Many more are possible. Note that the driver tags in each example need not be all the same type.

Scenario 1:

VTScada I/O server with wired IP connection to field device transceiver with static I/P.

Scenario shown based on the use of a typical polling protocol such as Modbus, DF1 or ENIP/CIP

Scenario 2:

VTScada I/O server with wireless IP connection to field device transceiver with wireless static IP.

  1. Scenario shown based on use of typical polling protocol such as Modbus, DF1 or ENIP/CIP.
  2. The polling group may be excluded except in one of the following scenarios:
  • Where all data from each field device is to be read at the same time, such as in a single block read (e.g. to minimize communication costs). In this case, the poll rate in the polling driver overrides the scan rate of the associated I/O tags.
  • Where the field devices are to be polled in sequence, in which case the polling group ID must be the same for all devices.
  • Where different protocols (driver tags) are used to communicate with different field devices.

Scenario 3:

VTScada I/O server with serial connection to field devices.

  1. Scenario shown based on the use of a typical polling protocol such as Modbus, DF1 or ENIP/CIP.
  2. If configuring the system for redundant I/O servers, use a serial to Ethernet converter to place each field device on an Ethernet connection
  3. If using COM port redirection software, continue to use Serial Port tags. Otherwise, use TCP/IP tags.

Scenario 4:

VTScada I/O server with wireless connection between base station transceiver and field devices.

  1. Scenario shown based on the use of a typical polling protocol such as Modbus, DF1 or ENIP/CIP.
  2. Polling group may be excluded except in one of the following scenarios:
  • Where all data from each field device is to be read at the same time, such as in a single block read (e.g. to minimize communication costs). In this case, the poll rate in the polling driver overrides the scan rate of the associated I/O tags.
  • Where the field devices are to be polled in sequence, in which case the polling group ID must be the same for all devices.
  • Where different protocols (driver tags) are used to communicate with different field devices.
  3. If configuring the system for redundant I/O servers, use a serial to Ethernet converter to place each field device on an Ethernet connection

Scenario 5:

VTScada I/O server with dial-up modem connection to field devices.

  1. Scenario shown based on the use of a typical polling protocol such as Modbus, DF1 or ENIP/CIP.
  2. Polling group may be excluded except in one of the following scenarios:
  • Where all data from each field device is to be read at the same time, such as in a single block read (e.g. to minimize communication costs). In this case, the poll rate in the polling driver overrides the scan rate of the associated I/O tags.
  • Where the field devices are to be polled in sequence, in which case the polling group ID must be the same for all devices.
  • Where different protocols (driver tags) are used to communicate with different field devices.
  3. If configuring the system for redundant I/O servers, each server must have access to a modem.
  4. Multi-modem (pooled) configurations supported.


Driver Server Lists

You can assign a server list to drivers using the ID tab of the tag's configuration panel. One server list can be shared by many drivers.

A list of excluded drivers is included at the end of this topic.
Custom drivers (those not included with VTScada) may not have a Server List parameter. Most of these will recognize a DriverServerListName parameter that is defined in a parent Context tag or Context-based type. See notes later in this topic.

There is no need to create a server list at a small site where there is only one server, or where all drivers use the default server list.

Choosing a custom server list within a driver's configuration panel.

Any existing server list can be selected or you can define the name for a new server list. One server list can be used for as many drivers as needed, assuming that the servers in that list are able to connect to the specified hardware for each driver. Different types of drivers can use the same list.

If you create a name for a new server list within the driver, it will be flagged as shown in the following figure. The driver will use the system's default server list until you define the servers for the new list. (Servers for Specific Services)

A newly-created Server List.

Alternative: Assign a Server List in a parent tag

If a parent Context tag (or Context-based type) contains a setting named "DriverServerListName", whose value is set to a valid name, all driver tags that are descendents of that Context will use that list unless otherwise configured. This method is recommended for use with custom drivers that do not have a Server List parameter.

All drivers below this Context will use the Fair County server
list if they do not have their own Server List.

Notes:

  • If you have defined a DrivernameSharedRPC or DrivernamePortSharedRPC property, it will have priority over the server list.
  • If your driver has a valid Server List parameter, and there is a parent Context with a valid DriverServerListName parameter, the driver's local Server List will have priority.
  • If there are parent and grand-parent Context tags, each with a DriverServerListName parameter, the closest parent to the driver has priority.
  • Notes for Context tags apply equally to user-defined types that you create from Context tags.
  • A server list name cannot contain a backslash character.

Server Lists versus SharedRPC

Traditionally, every driver in VTScada has its own service. This continues to be true. In older versions, you needed to create a server list for each driver's service. The feature described in this topic lets you create one server list that can be shared by many drivers of many types. Each driver keeps its own service, meaning that the failure of one does not affect any other driver sharing the server list.

The xSharedRPC property for a driver puts all drivers of the same type on the same service. While valuable in certain circumstances, this will cause all drivers sharing that service to fail over when one fails.

Excluded Drivers:

DataFlow driver (Always registers as "DataFlow" service)

PollDriver (Always registers as "PollDriver" service. See following notes.)

TransactionTag (Does not have RPCService)

WorkStationStatusDriver (Only uses the machine itself, no need for sever list)

SNMP Driver (Currently uses SNMP groups to set the RPC Service name)

Polling Drivers

There is a "PollDriver" service that is used for housekeeping tasks but primarily, the Poll Driver inherits the RPC service of its communication driver. To make sure that Poll Drivers work properly, all communication drivers that are attached to Poll Drivers in the same Polling Group must use the same server list.

Driver Multiplexer Tags

These work a bit differently. If you set up a tree of DriverMUX tags and subordinates, the root tag of that master / subordinate tree(*) controls the server list for all subordinate drivers. The server list capability for a subordinate driver will be disabled if a server list is defined in the master Driver Multiplexer.

If a DriverMUX has no subordinate driver, there is nothing for its server list to control. It can still be set, but you will be warned that the multiplexer is not controlling anything.

(*) Referring to the structure defined within the multiplexer, not a parent-child structure in the Tag Browser.

If creating tag-based server lists and using a legacy application created prior to version 10.2, refer to notes in FriendlyTagServiceNames


Memory Tags

If an I/O and Calculation tag does not have a configured address (read, write or history) then it does not count against your tag license. This configuration can be valuable as a "memory tag", which holds a value that is provided by an operator via a widget. The data type can be Analog, Discrete, Digital, or String.

Because memory tags do not write to an address in hardware, it is possible to set their value to Invalid. This can be controlled with the option, "Allow value to be cleared", which is visible in the I/O tab only when no address has been configured. This option also affects certain widgets such as the Droplist Widget, which will show "No Data" (value: Invalid) only if the memory tag can have its value cleared.

2-bit Digital, and all Calculation options of the I/O tag do not count as Memory Tags.

Operators can set the value of a memory tag using any of the standard control widgets. It is also possible to set the values of multiple memory tags in a single operation by using Multi-Write Tags

Memory tag values will persist across application restarts. You can configure a default (initial) value for a memory tag using the input field "Default Memory Value" on the I/O tab, but only if "Allow value to be cleared" is not selected.

Only I/O tags that have an address (read or write) count against your tag license. Memory tags have no address and therefore do not count.

See: I/O and Calculations Tag


Control Locks

Create Control Locks to prevent use and operation of selected equipment via the VTScada screens. Among other uses, locks are typically applied when technicians are physically working on dangerous equipment to prevent remote activation of that equipment.

If you are looking for a way to lock controls for some users but not others, you should apply a security privilege, not a control lock.

Feature | Effect | Use... | Reference
Security Privileges | Control who is allowed to write to an output. | Use in all applications | Restrict Access to Output Tags
Control Locks | Prevent use and operation of selected equipment via the VTScada screens. If the tag is protected by a privilege, users must also have that security privilege. | Only where there is a need to lock controls for all users, regardless of privilege. | Control Locks
Control Tokens | Ensure that only the current token owner can write to an output tag. Users must also have the required security privilege and the tag must not be locked. Only one user at a time can hold a Control Token. | Only where there is a need to restrict control to one operator at a time. | Control Tokens

VTScada Control Locks do not override physical switches or alternate controls for the PLC. They apply only to the VTScada user interface.

Control Locks are applied to tags. A locked tag cannot be operated by anyone (regardless of their security privilege) until the lock is removed. Locking a parent tag will automatically lock all of its child tags, making them inoperable as well. This allows you to prevent operation of an entire subsystem with a single lock.

Control Locks use features of the VTScada Alarm Manager. When working with Control Locks, you may note similarities, including the fact that active locks are shown in a customized view of an Alarm List widget.

Enable the Control Lock System

To use the Control Lock system in your application, the ControlLocksEnabled property must be set to 1. Disabling this property will not remove existing locks but will render all locks useless. (They will not prevent tag operation.)

Detail from the Edit Properties tab of the Application Configuration dialog.
(Refer to Edit Properties.)

Lock Management via Widget

Locks are added, removed, viewed, and managed using widgets that you draw. Do not look to the Tag Browser or tag properties for locks. Lock-related widgets can be found in the palette folder, Tools\Control Locks.

Add Locks

To create a lock on a tag (either a specific I/O tag or a parent of many I/O tags) draw an Add Lock Button Widget on a page of your choice and link it to an output tag or a parent of several output tags. To create a lock, users must have the security privilege, Lock Add / Remove. (Refer to Control Lock Security for further notes about security and locks.)

View / Remove Locks

To view and manage locks in your application, draw the Locks List Widget on a page of your choice. (The Locks List widget is in fact the Alarm List widget, configured to display Locks rather than alarms. The Alarm Page does not have this configuration option.)

To provide confirmation to operators that a tag is locked, draw either a Lock Level Icon or Lock Level Box on any page where that tag is shown, linking the icon or box to the tag for which you want confirmation. These widgets serve both to indicate when the tag is locked and the lock level applied.

The locks can be removed by clicking the Remove button in the Lock List widget.

Lock Levels

By default, all locks will prevent control of the tags they apply to. However, there are situations where you might want to use locks to inform the user of a situation but not prevent control. This behavior can be configured by setting a Lock Level and configuring the matching ControlLockLevelXPreventControl property (where X=1,2,3,…) to 0.

To inform the operator than a lock has been set (whether that lock prevents control or not), draw a Lock Level Icon Widget or Lock Level Box Widget on a page with the tag. If the Lock Level does not prevent control, no warnings are displayed; the icon or box widgets are the only indications that an information-only lock has been set. If the Lock Level prevents control, a warning message is displayed:

Like Alarm Priorities, the lower the number of a Lock Level, the higher its priority. Three lock levels are defined in every application and you can add more if required by adding new ControlLockLevelXPreventControl properties to your application, setting X to 4, 5, 6, etc. .

It is possible for any output tag to have more than one lock applied (for example, one on the tag itself, one on the parent equipment type, one on the parent station type, etc). In this situation, the enabled lock with the lowest Lock Level (highest priority) is the one that takes precedence and is shown by the tag's Lock Level Icon or Lock Level Box widget.

The highest priority (lowest number) lock takes precedence and dictates how the tag is locked. For example, a tag with a Level 1 lock that does not prevent control and a Level 2 lock that does prevent control will still be operable.

You can disable Control Locks on any tag structure by adding ControlLocksEnabled as a property of the parent Context tag (or user-defined tag) and setting that to 0. Locks will then not apply to any child tag within the hierarchy.
The opposite is not true: you cannot selectively enable Control Locks on tag hierarchies without enabling them for the application as a whole.

Related Properties:

ControlLockAutoUnlockUponLogout

ControlLockCanOnlyRemoveOwnLock

ControlLockLevelIconXOffset

ControlLockLevelIconYOffset

ControlLockLevelXColor

ControlLockLevelXLabel

ControlLockLevelXPreventControl

ControlLockNoteMinLength

ControlLockNoteRequiredForAdd

ControlLockNoteRequiredForRemove

ControlLockOwnerMode

ControlLocksEnabled


Control Lock Security

Privileges

Two privileges relate to the use of Control Locks:

Lock Add/Remove

This privilege allows users to add locks without restriction, and to remove locks subject to any restrictions imposed by the application property, ControlLockCanOnlyRemoveOwnLock. (See following notes for Lock Ownership Mode.)

Lock Administrator

This privilege allows users to remove any lock. It does not give users the ability to add locks. The intent of this privilege is to allow a supervisor to remove locks when the person who would ordinarily do so is not available.

Lock Ownership Mode

You have the option of enabling the Ownership feature of Control Locks by setting ControlLockCanOnlyRemoveOwnLock to 1. Doing so restricts which locks users with the Lock Add/Remove privilege can remove, such that they can only remove locks that they ‘own’. This does not affect users with the Lock Administrator privilege, who are always able to remove any lock.

Ownership can be defined in several ways and is set using the ControlLockOwnerMode property.

Anyone with the Lock Administrator privilege can always remove any lock.

0. Session ID ownership (ControlLockOwnerMode=0)

Users only own locks that they create during a given session. Each time a user signs on, a new session ID is generated. Therefore, signing in and setting a lock, signing off, and then signing in again would result in the same user being in a different session and not be able to remove the locks they set in the first session. This extends to both thin and thick clients. Even if the same user is signed in on several clients, locks added on one will not be removable on other clients.

1. Account ID ownership (ControlLockOwnerMode=1)

This is the most straightforward ownership mode. As the name suggests, ownership is defined by the account ID that added the lock. If the same user is signed into several machines they would be able to remove locks set on other machines / clients.

2. Machine ID ownership (ControlLockOwnerMode=2)

In this mode, ownership is defined by the machine ID. This is useful way to segregate removal permissions based on physical workstations. When ownership is set to this mode, AutoUnlockUponLogout does not apply.

3. Custom Hook ownership (ControlLockOwnerMode=3)

Applies only to those who are developing their own code that involves Control Locks. When ownership is set to this mode, AutoUnlockUponLogout does not apply.

Ownership is defined by a custom hook provided by the customer within their code: ControlLockIsOwnerHook.SRC.

AutoUnlockUponLogout

You can activate an automated lock release mechanism by setting ControlLockAutoUnlockUponLogout to 1. If lock ownership is any of: disabled, set to Session Id, or set to account ID, then signing out will release all locks set during the session.

Auto lock release is disabled for MachineID ownership or custom hook ownership.


Control Tokens

The Control Token system ensures that only one person (owner) at a time has control over a tag or set of tags. It is complimentary to the Control Locks system. A lock denies control and a token grants exclusive control (providing that the tag is not otherwise locked).

Upon enabling the Control Token system, all users must request a Control Token for every output.
DO NOT ENABLE THIS FEATURE WITHOUT PROVIDING USERS WITH A WAY TO REQUEST A TOKEN.

It is essential that Request Token Button Widgets exist or that appropriately configured Control Token Box widgets be drawn on any page that contains an output widget.

If a token is applied to a tag, only that token’s owner has control over the tag. A control token restricts user actions. It does not restrict automated actions. Any tag can have only one token. (This is in contrast to Control Locks where multiple locks can be placed on a tag for different reasons.)

The Control Token system can be enabled globally by setting the application property ControlTokensEnabled to 1. (Edit Properties) Alternatively, it can be enabled for a specific tag tree (or part thereof) by adding the property to a Context tag (or tag type derived from a Context tag) to enable Control Tokens in child tags of that parent. (You can also disable Control Tokens for a section of a tag tree by adding the property to a parent tag and setting the value to 0.) VTScada will check for ControlTokensEnabled starting with the current tag and working up through the scope of the tag tree to the application in general.

Placing a token on a tag grants the token owner control over that tag and all of the children that do not already have another control token. Adding a token to a parent tag does not override any existing token on a child tag.

Tokens are requested, viewed, and managed using widgets that you draw. Do not look to the Tag Browser or tag properties for Control Tokens. Token-related widgets can be found in the palette folder, Tools\Control Tokens.

Feature | Effect | Use... | Reference
Security Privileges | Control who is allowed to write to an output. | Use in all applications | Restrict Access to Output Tags
Control Locks | Prevent use and operation of selected equipment via the VTScada screens. If the tag is protected by a privilege, users must also have that security privilege. | Only where there is a need to lock controls for all users, regardless of privilege. | Control Locks
Control Tokens | Ensure that only the current token owner can write to an output tag. Users must also have the required security privilege and the tag must not be locked. Only one user at a time can hold a Control Token. | Only where there is a need to restrict control to one operator at a time. | Control Tokens

VTScada Control Tokens do not override physical switches or alternate controls for the PLC. They apply only to the VTScada user interface.

You can disable the Control Token feature on a site by site basis through an application.
Do so by adding the property ControlTokensEnabled to the parent Context tag(*) of the site and set the value to 0. Tags within that structure can then be operated without first obtaining a Control Token.

(* or Context-based custom type if the parent tag is no longer a Context)

Requesting Control Token Ownership

Authorized users(*) can request a Control Token for that tag either explicitly using a Request Token Button Widget, or implicitly by opening a page that contains an appropriately configured Control Token Box widget.

(* An "authorized user" is anyone with the Token Request / Release privilege, as well as any privilege required to use a given output tag.)

These requests are made using widgets, and can be made for a single output tag or for all the tags under a common parent. If no-one else has a control token on the tag, the default behavior is for the request to be granted immediately.

It may happen that one or more people want to request control over a tag when someone else already has a control token for that tag. What happens in this case depends on your configuration: by default, later requests must wait until the current token owner releases control. You can configure the system such that incoming requests with a higher priority level will automatically take control from the current token owner.

To keep track of who has control and who is requesting control, two separate lists are maintained: the Token list (who has ownership) and the Token Requests list (who is requesting ownership).

The Token Administrator privilege can be granted to selected users so that they can release any existing tokens and can grant or deny any existing token requests. The Token Administrator privilege by itself does not grant the user the ability to request a Control Token.

Releasing Tokens

At any time, you can choose to release tokens that you hold. Do so with a Release Token Button widget that matches the token you wish to release. (Like the Control Token Request button widget, the release button is linked to a tag and affects only the token applied to that tag. A more convenient option might be to use a Token List, where all tokens are shown and you will have the option to release any that you hold.

By default, token owners can release only the tokens that they own. You can change this behavior by setting the application property, ControlTokenCanOnlyRemoveOwnToken, to 0. (This does not affect Token Administrators, who can release anyone's tokens.)

Ownership can be defined in several ways and is set using the ControlTokenOwnerMode property.

As described in the notes for that property, ownership may be linked to any of the user's sign-in session, the user's account in general, the user's current workstation, or to a custom programming hook that you provide.

Global Tokens

Formally known as Root Tag Tokens, a Global Token will grant control over every output in the tag tree. The Request Token Button, Release Token Button and Control Token Box widgets all have a Global Token check box within their properties configuration.

A Global Token does not force the release of other control tokens. If a Global Token has been requested and is available it will be granted immediately-- but control of any output already being controlled by someone with a control token will stay in their control until they release their token. Once the control token for a specific device has been released, the user holding the Global Token will assume control.

The Global Token works by declaring a fictitious 'Root Tag' in the ControlTokenManager. The syntax to use this would look similar to:

\ControlTokenManager.RequestToken(\ControlTokenManager.RootTagID, Level)

The Root Tag name and area can be changed by adding ControlTokenRootTagName and ControlTokenRootTagArea properties.

Token Lifetime

Control Tokens will continue to exist after the holder signs out. You can alter this behavior such that the act of signing out will always release all tokens held by a user, automatically. Do so by setting the property ControlTokenAutoReleaseUponLogout to 1. This also denies all token requests made in that session.

The lifespan of Control Tokens (and Control Token Requests) can be controlled by the properties, ControlTokenMaxAge and ControlTokenRequestMaxAge, neither of which are set by default, meaning that there is no automatic expiry.

Stale Tokens & Requests

These are tokens or requests left behind when a user shuts down the application without releasing (by any means) the tokens or requests that they hold. This can occur with a workstation crash or a user simply shutting down their computer without signing out.

The owner of every token and request will send a "heartbeat" signal to the token server. If a pulse does not arrive for a set amount of time, VTScada will assume that the token or request is stale. The server will release stale tokens and requests when it checks its dictionary of timestamps every ControlTokenMonitorTime seconds or when the list of tokens and requests changes. This behavior is controlled by the following properties:

  • ControlTokenEnableOwnerMonitor
    Defaults to 1 (TRUE) to enable release of stale tokens.
  • ControlTokenMonitorTime
    Defaulting to one hour (3600 seconds), this is the frequency at which the control token manager checks its list of token and request owners to ensure that it is current and release / deny stale tokens / requests
  • ControlTokenStaleTokenTime
    If there are no requests for the token, it will be determined to be stale after not receiving a heartbeat for one day (86400 seconds) (It has been a day since we heard from the owner.)
    The interval also applies to all requests.
  • ControlTokenPendingRequestStaleTime
    If there are requests for the token, it will be determined to be stale after not receiving a heartbeat for one minute (60 seconds) (It has been a minute since we heard from the owner.)
    This interval does not apply to any requests.
  • ControlTokenOwnerHeartbeat
    Defaulting to 30 seconds, this is the frequency at which a token owner confirms with the server that it is still active.

Token Actions

As noted, if a user requests a token and no-one else has a token on that tag, the request will be granted immediately.

If a user requests a token and someone else currently has a token for that tag or its parent, then a Token Request will be appended to the Token Request list. This pending request can then be either Granted or Denied, either by the current token holder or by a Token Administrator. If the request is Granted, then the current token holder loses control over the tag and a new token with a new owner is placed. If the token request is Denied, the token request will be removed from the Token Request list. A user cannot have multiple identical token requests.

Releasing a token initiates an auto-granting mechanism where the next person in the list of Token Requests will be granted control (and a new token). They will be removed from the list of Token Requests so that when they release their token, the next request can be granted.

If you hold a token and another user requests control over that tag, you will be presented with the Token Requests dialog:

Your choices are:

  • Grant the request. (You will lose control of the tag.)
  • Deny the request. (The request will be removed from the Token Request List.)
  • Close the dialog without taking action. (The request will remain on the Token Request list and will be granted when you release the Control Token.

Token Levels vs. Token Actions

Like Control Locks, tokens have levels. The default and highest level for token requests is 1. As with alarm priorities, increasing level numbers indicate lower priorities. All levels grant control over the tag. (There is no equivalent to ControlLockLevelXPreventControl.) Levels are used in combination with application properties to control the behavior when someone else requests a token that you hold.

The relevant properties that control what will happen when someone requests a token that you hold are as follows. Taken together, the default values mean: "never release someone else's token and add all requests to the token request list". Levels do not apply.

Levels will apply to the actions of requesting / granting / denying / releasing tokens if you choose to set any of the following properties to values other than the default. The rules vary according to the combination of values you set for these properties but the overall effect is to allow automated actions and decide whether any action can proceed based on a comparison of the priority of the request.

Three token levels are provided and more can be added (and simultaneously given an indicator color and label) by inserting ControlTokenLevelXColor properties, where X can be 4, 5, etc. Do not skip values. A label may also be defined (ControlTokenLevelXLabel) but this is optional and should be defined only if you want something other than (for example), "Level 4", which will be used by default.

ControlTokenAutoStealOption

Defaults to 0. Controls whether to grant an automatic token request for a token on a tag that is currently being controlled by another owner.

ControlTokenAutoRequestOption

Defaults to 1. Controls whether automated requests for tokens will be added to the request list.

ControlTokenManualStealOption

Defaults to 0. Controls whether to grant a manual token request for a token on a tag that is currently being controlled by another owner.

ControlTokenManualRequestOption

Defaults to 1. Controls whether manual requests for tokens will be added to the request list.

For example, suppose that a user has a control token with a low priority level (3) and another user creates a request with a higher priority level (1). By default, the level is irrelevant and the second user must wait until the first token is released. But you could configure the system such that the act of creating a higher priority request will automatically release the first token and grant a new token to the person making that high priority request. Other combinations are possible.

Possible values for each of these properties:

0 | Never
1 | Always
2 | If request level priority > token level priority (lower number / higher priority takes precedence)
3 | If request level priority >= token level priority
4 | If request level priority < token level priority
5 | If request level priority <= token level priority
6 | If request level priority == token level priority
7 | If request level priority != token level priority

Related Widgets

Request Token Button Widget

Release Token Button

Control Token Box

Tokens List

Token Requests List

Tokens and Token Requests List

Token Level Box

Token Level Icon


Other Modes of Communication

I/O device drivers are only one of the options available for linking your VTScada application to external sources of data. You may also write your own code, calling on OPC, COM (Component Object Model), DDE (Direct Data Exchange), ODBC (Open Data Base Connectivity), Protobuf, or DLL (Dynamic Link Libraries).

Tools and techniques for using each of these technologies can be found in the topics within this chapter.

For most tags, only the value is available directly. Driver tags contain seven variables in addition to the value. (Communication Driver Log-Enabled Variables) Other variables and properties can be monitored by creating an expression in an I/O and Calculations tag to mirror that variable, then publishing the calculation tag. For an example, refer to: Monitor the Alarm Status

This chapter is for advanced users. Some of the topics described here require you to write custom code in either VTScada or C++.

The vast majority of VTScada users will find the solutions they need in the library of Communication Driver Tags Communication Driver Tags. Drivers exist for most of the technologies described in this chapter, relieving you of the need to write code.


OPC Configuration

VTScada supports both OPC UA and OPC Classic.

The OPC UA Client driver interfaces to an OPC UA server running on either the local or another computer.

OPC UA is an alternative communication protocol to OPC CLASSIC, which uses DCOM for communication between a client and a server.

As DCOM is not involved in OPC UA, fewer steps are required to configure a connection to a server, successfully. DCOM for OPC CLASSIC has a reputation for being difficult to configure, so much so that a number of commercial "OPC-tunnellers" exist that act as proxies between the client and server in an effort to simply the configuration.

An OPC UA server may be running on a remote computer or be embedded in a smart device. It can run on a variety of operating systems (e.g. Windows, Linux etc). The number of OPC UA products available is still limited, while there are many OPC CLASSIC servers still available and already deployed. Here also, a tunneller can be used to connect OPC UA clients to an OPC CLASSIC server.

If both client and server are using OPC UA, the only additional configuration necessary is to ensure that firewalls allow the correct ports to be opened. The port(s) in use are defined by the OPC UA server.

For most tags, only the value is available directly. Driver tags contain seven variables in addition to the value. (Communication Driver Log-Enabled Variables) Other variables and properties can be monitored by creating an expression in an I/O and Calculations tag to mirror that variable, then publishing the calculation tag. For an example, refer to: Monitor the Alarm Status


OPC UA Support & Security

The VTScada OPC UA Client driver supports the OPC Foundation’s specification #1.04. The features and capabilities of OPC UA are described by the specification in a number of "profiles". An endpoint (client or server) states which profiles it supports to indicate the features and capabilities it has.

Profiles

The VTScada OPC UA Client driver is designed to support the profile described by the URI http://opcfoundation.org/UA-Profile/Client/Minimum UA Client Profile. However, your device may vary. There are 4 profiles of OPC UA, as follows:

Standard UA Server Profile
(May be supported by VTScada. Requires verification)

Software servers installed on computers.

  • Kepware (Tested successfully)
  • Matrikon (Tested successfully)
  • Schneider EcoStruxure (Tested successfully)
  • Autosol Communication Manage (ACM) (Specialty version, tested successfully)
  • Triangle Microworks (Tested successfully)
  • Mission Controls OPC cloud server (Tested successfully)

Embedded UA Server Profile
(May be supported by VTScada. Requires verification)

Embedded in PLC components.

This is a less capable profile than Standard, notably without the Datachange Facet, which allows the server to use deadbanding. This is a key function to limiting the amount of data returned from field devices and therefore some manufacturers include the Datachange Facet to their version of the Embedded profile.

  • ABB AC800M PLC has an OPC UA module and states embedded (Not tested).

Micro Embedded Device Server Profile
(May be supported by VTScada. Requires verification)

Embedded in PLC components. Less capable than Embedded.

  • Schneider M580 PLC (Tested successfully)
  • Codesys PLC (Tested successfully)
  • Mitsubishi Melsec PLCs FX OPC card (Not tested)
  • Siemens S7 1500 PLC (Specialty version. Tested successfully)
  • Prosoft (Tested and unsuccessful. There are issues with security certificate incompatibility)
  • Emerson RX3i (Tested successfully. Do not confuse with the GE RX3i)
  • Red Lion DA10D (Specialty version. Tested successfully)

Nano Embedded Device Server Profile (Not supported by VTScada)

Embedded in PLC components. Less capable than Micro Embedded. Excludes security and subscription services

If you have a VTScada application running with OPC UA you can check the profile of the device by opening the driver properties folder, selecting the Diagnostics tab and clicking the Details button.

OPC UA Protocol Support

OPC UA has a layered protocol architecture. The most relevant parts are the protocol encoding and the transport protocol.

OPC UA Encoding Protocols

OPC UA has 3 protocol encoding variants:

  • OPC UA Binary. This is the encoding supported by the VTScada OPC UA Client and is the most commonly supported and most compact one.
  • OPC UA XML. Currently unsupported by VTScada.
  • OPC UA JSON. Currently unsupported by VTScada.

OPC UA Transport Protocols

Communication with a server can be achieved using one of four transport protocols:

  • OPC UA TCP. This is the transport protocol supported by the VTScada OPC UA Client.
  • SOAP/HTTP. This was not widely supported by the industry and deprecated since specification level 1.03.
  • OPC UA HTTPS. Currently unsupported by VTScada.
  • WebSockets. Currently unsupported by VTScada.

OPC UA Security

There are 2 layers of security. One layer secures the communication between server and client and the other authenticates the user to the server.

The "None" security policy permits communication without encryption or message signing (no confidentiality or integrity). This should only be selected for testing or when the connection is otherwise protected by external means, such as a VPN between the VTScada system and the OPC UA server.
Where encryption or cryptographic signing of communication is desired (recommended), a trusted certificate is required at both the OPC UA server and the VTScada OPC UA Client driver to verify identity.

Transport Protocol Security.

This ensures privacy and integrity of the communications between server and client. It is achieved through a Public Key Infrastructure (PKI) using X.509 certificates in a similar manner to HTTPS.

The difference is that for HTTPS, a client (such as a web browser) receives an X.509 certificate from the server to which it is trying to connect and decides whether this is trustworthy. If it is, communication between server and client is encrypted and proceeds without user intervention. If the certificate is not deemed trustworthy, the user is warned and communication is halted. So long as trusted certificates are issued appropriately, this works well.

In OPC UA both client and server exchange X.509 certificates (they each have their own) and communication only proceeds if each end trusts the other. Trust is established if the certificate is derived from one that is already trusted (like HTTPS) or an administrator explicitly tells the server or client that the certificate from the other end is to be trusted.

Enforcing certificate trust ensures that the OPC UA Client will only connect to the server you specify, and that the server will only accept connections from "trusted" clients.

The VTScada OPC UA Client supports the following transport security policies:

  • http://opcfoundation.org/UA/SecurityPolicy#None
  • http://opcfoundation.org/UA/SecurityPolicy#Aes256_Sha256_RsaPss
  • http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256
  • http://opcfoundation.org/UA/SecurityPolicy#Aes128_Sha256_RsaOaep

Additionally, the following deprecated policies are also supported, although these should be avoided as they use the SHA-1 hashing algorithm, which was broken in 2017. Support for these is provided for compatibility with older servers that do not support newer algorithms.

  • http://opcfoundation.org/UA/SecurityPolicy#Basic256
  • http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15

Session Security

While transport level security protects the communication, session security authenticates a user, authorizes the user to be able to perform some actions, and denies the ability to perform others.

There are 3 types of session security, all of which are supported by VTScada.

  • Anonymous.
    An anonymous user need provide no credentials. The capabilities the server grants the user will likely be limited to monitoring non-sensitive data.
  • Username / Password.
    This is the traditional method of authentication, with a username and password being supplied that grants the user whatever rights are configured by the server. This is appropriate for all uses, from process monitoring and control to interactive applications generating reports or the like. It is portable across client machines, therefore (as long as the transport security permits), you can use a username and password from any client computer.
  • X.509 Certificate.
    The user is issued with an X.509 certificate. To be authenticated to the server, the client sends the certificate and is authenticated only if the server trusts the certificate. This is distinct from transport layer security in that the encryption keys associated with the certificate are only used to prove ownership of the certificate, not perform encryption. This restricts user access to computers that have the user certificate installed on them or, (if the client software permits it) can be read from an attached device such as a smart card reader.

Default Security Settings

The default setting of the VTScada OPC UA Client enforces transport-level security and requires that appropriate X.509 certificates are supplied.

It is possible to use an unsecured communication mode, where certificates are not required, no authentication of server identity is performed and communication is not encrypted or digitally signed. Use options within the Diagnostics tab of the OPC UA Client configuration dialog to do so. This is a temporary setting only and (by intent) will revert to requiring certificates and secure communication when the driver is reloaded. (For example, on application restart.) The VTScada OPC UA Client will select the most secure mode supported by the server for transport layer security.

X.509 Certificates

For all secured communication, the OPC UA server and OPC UA Client require appropriate X.509 (v3) certificates.

VTScada has the capability to generate self-signed certificates for use by the OPC UA Client in the absence of another certificate generation mechanism. This provides an easy way to generate certificates when no Certificate Authority (CA) generated certificates are required.

Certificate Trust

A certificate must be "trusted" to be used. The trust can be achieved in 2 ways:

  • Implicit trust via the certificate issuer.
  • Explicit trust via manual user action.

If the certificate is issued by a trusted CA (i.e. the issuing CA has a root certificate in the appropriate "Trusted Publishers" store), then the certificate is implicitly trusted.

If the certificate is not issued by a trusted publisher, or is self-signed, then a manual user action is required to trust the certificate. Users undertaking such actions should verify, by inspecting the certificate thumbprint, that the certificate is the expected one as issued by the remote party, whether server or client.

Client Certificates

The OPC UA Client must be provided with at least one X.509 certificate. This is used for identification and authentication of the OPC UA Client to the OPC UA server, for transport layer security.

The server must trust this certificate. The server implementation determines how trust is established, but generally the server will allow an administrative user to instruct the server to trust it.

For self-signed OPC UA Client certificates, the administrative user normally has to trust the certificate itself. For CA signed certificates, the administrative user normally has to trust a root certificate, from which the transport certificate is derived.

Depending on the user authentication mode, a second X.509 certificate may be required that is used in place of the traditional username/password authentication. Again, an OPC UA server supporting this user authentication method will be able to authorize access using that certificate.

A client certificate may also be used to supply an "application URI" for the OPC UA Client when creating a session on the server. If your OPC UA server requires a specific application URI to be provided, you must incorporate this into the client’s X.509 certificate as a URL entry in the certificate Subject Alternative Name extension.

Server Certificates

An OPC UA server provides the OPC UA Client with a certificate to prove its authenticity. For the OPC UA Client to trust the server and establish a session with the server, the server’s certificate must be trusted by the OPC UA Client.

This is achieved using the driver’s configuration folder. Conversely, a server certificate can have its trust by the OPC UA Client removed should the need arise.

Server certificates MUST contain the host name as provided in the Endpoint URL specified in the driver’s configuration folder. This may be part of the Distinguished Name of the certificate or be in the Subject Alternative Names extension as a DNS record.

Certificate expiry and renewal

All certificates have an expiry date, and when they expire, certificates are no longer usable and communications with the OPC UA server will fail.

The OPC UA Client will create ad-hoc alarms for each certificate in use, beginning 30 days before their expiry. The alarms will be set to normal when the certificates have been replaced.

VTScada has no mechanism to renew certificates automatically. Self-signed certificates can be renewed by creating another and selecting it in the appropriate grid. Externally-provided certificates must be imported and then selected in the appropriate grid. It is up to you to ensure that all certificates in the VTScada system are renewed as required, including (for example) those for the primary and backup I/O server. New certificates will be used on the next connection attempt. You must also take action at the OPC UA server to trust new client and user certificates.

Server certificates require particular care when renewing (on the server) as when they are first sent to the VTScada OPC UA Client they will be untrusted and will require manual action to trust the new certificate. A secondary I/O server will only receive the server certificate when a connection is made to the server, so either a fail-over and manual trust will be required. Alternatively, the server certificate (if the server sends the same certificate to all clients) can be copied to the appropriate place on the secondary I/O server and trusted before a connection is made.

VTScada Server Fail-over

Every VTScada server will (must) have its own certificate. On the backup VTScada servers, the hostname in the Subject field will be similar to CN=backup.example.com. Configure the certificates on both the primary and backup VTScada servers to use the same use the same "Friendly Name" for their certificates. This will allow two different client certificates to be used on the primary and backup machines. This name should be the same on all client machines (VTScada backup servers) because it is not in the certificate. The Friendly Name is then used in the OPC UA Client driver configuration so that the single name can identify the required certificate on each machine.

Note that the certificate Friendly Names can be created when generating the first certificate on a client machine. Others are created using the Windows certificate manager utility.

You will also have to trust the backup client certificate on the OPC UA server and trust the server certificate on the VTScada client / backup server.


OPC Classic Configuration

OPC Closed Open Platform Communications. A communication interface based on DCOM and Web Services technology. Classic is an older communication interface based on DCOM Closed Distributed Component Object Model and web services Closed An application programming interface (API) that can be accessed using HTML. technology, which enables automation and control applications running on your PC to communicate with control equipment. In short, the OPC specification defines a set of interfaces for easy-to-use objects, and includes the functions and properties to enable the manipulation of these objects.

The basic transport layer for OPC is DCOM (Distributed Component Object Model). Because it is distributed, a human-machine interface (HMI) or supervisory control and data acquisition (SCADA) software package like VTScada can process and collect data from OPC Servers that are running on different computers on a network.

Configuration of OPC to use DCOM is not easy and changes made by Microsoft in 2023 add extra complexity. Trihedral recommends the use of an OPC tunneller instead.
For support of the tunneller software of your choice, please refer to the supplier.

The OPC server can produce error -1073479672 (0xC0040008) when referencing a tag that does not exist or is not available over OPC.

VTScada provides both an OPC Classic Client driver and an OPC Server as tag types. Access to the server tag depends on whether your VTScada license key includes this optional feature. Please see your Trihedral account representative for details.

OPC Classic Client

The OPC Classic Client driver enables VTScada to act as a client to an OPC server, enabling the exchange of data between a VTScada application and the server. The advantage to using OPC is that it enables VTScada to communicate with new control devices without requiring a custom-written driver. The OPC server takes care of communications with the control device, and enables VTScada to access its data via an OPC automation DLL.

If you install third-party OPC software in some cases the VTScada OPC Classic Client or Server may stop functioning correctly. Sometimes this can be solved by re-installing the OPC Core Components. Contact technical support for assistance.

OPC Classic Server

The OPC Server (OPC Driver) enables VTScada to act as a server to an OPC Classic Client. This enables other programs (including another VTScada application with an OPC Classic Client driver) to exchange data with VTScada.

An OPC Server enables clients to retrieve information about objects. There are 3 basic levels of objects:

  • OPC Server
  • Group
  • Items

The OPC Server object maintains information about the server, and acts as a container for OPC group objects. It handles data requests from clients.

The OPC Group object is a collection container for OPC Items. The OPC Group maintains information about itself and provides the mechanism both for containing and logically organizing OPC items.

The OPC items represent connections to data sources within the OPC Server. In the case where VTScada is providing the server, these items are tags. Each item provides the client with data and properties. Data presented to the client by each item is specified to contain one value, one time stamp and a set of quality flags. The data will be either numeric or text.

The OPC server object enables clients to browse within the server namespace to find what items are available to add to groups. The namespace is organized as a hierarchy and contains not only tag value identifiers, but property value identifiers that may be associated with a tag.

For Master & Subordinate configurations:
You cannot publish data from a subordinate application to an OPC client through a master application. You must have an OPC Server tag on the same application as the IO tag publishing the data.
You may have OPC Server tags on both the subordinate and the master applications; these will appear as siblings to an OPC client.

Related information:

Trace Viewer Application - You can monitor OPC communications using the Trace Viewer. Note that communications will be slowed while tracing is enabled.


Securing an OPC Classic Server

Security for OPC servers is provided by the Microsoft Windows™ DCOM security tools. For a comprehensive discussion of how to secure an OPC server, refer to the OPC Foundation's website: http://www.opcfoundation.org

Additionally, the Software Toolbox® (not affiliated with Trihedral Engineering Ltd.) provides very good reference information and tutorials for DCOM security configuration. These materials can be found at:

https://www.softwaretoolbox.com/dcom/html/dcom_for_windows_7-_8-_-_server_2008.html

In general terms, the following steps are required to secure the server:

  1. Run the program, DCOMCNFG.exe on the workstation to which users will be connecting.
  2. Find the entry "Trihedral VTScada OPC Server" as shown in the following image:

  3. Right-click on the Trihedral VTScada OPC Server entry and select Properties. The following dialog should open (shown with the Security tab selected):

Use this to select the groups and users who will have permissions for each of the three categories.

It is very important to deny Launch and Activation privileges to all users. If a client application attempts to launch VTScada, it will do so from its own directory, not the application folder. This will not work.

Notes for Windows Workgroups

If your computers are networked in a workgroup, additional security settings may be required.

The default installation forces remote users to authenticate as Guest. This means that DCOM clients cannot connect to a server unless the Guest account is enabled and has enough rights to launch the server.

Adjust these settings from the Control Panel:

  1. Open the Control Panel.
  2. Click to open Administrative Tools.
  3. Open the Local Security Policy dialog.
  4. Click, "Local Policies".
  5. Click, "Security Options".
  6. Click, "Network access: Sharing and Security model for local accounts".
    Change this setting to the following:
    "Classic - users authenticate as themselves".


Compatibility with OPC Tunneller Software

Certain third-party OPC tunneller software may attempt to launch a non-interactive VTS.exe as the OPC server instead of connecting to the already-running VTS.exe. Do the following to avoid problems:

  • Configure the VTScada OPC Server (in DCOMCNFG) to disallow "Launch for all users" and to run VTScada as the interactive user.
  • After installing the third-party OPC tunneller software, install the latest OPC Core Components from OPCFoundation.org.
  • Run all configuration tools for the tunneller software as Administrator.
  • Ensure that all necessary services related to the tunneller software and OPCEnum are running.
  • Ensure that the server's firewall explicitly allows access to the port that the tunneller software uses.


Configure VTScada as an OPC Classic Client

This topic refers to an older technology. Where possible, consider the OPC UA Client Driver instead.

To configure VTScada as an OPC Classic Client, you will need:

  • A program that provides an OPC server to which you wish to connect
  • The OPC server's program identifier.
  • If the OPC server is not on the same computer, then you will need the name of the workstation where the server is located.

To configure an OPC Classic Client driver where another VTScada application is the server:

Given a VTScada application (App1) that provides an OPC Server whose server namespace is BedfordSim and that includes an Analog Input tag named Tank1Level, whose values you wish to read in another application.

(All steps should done in the second application)

  1. Using the tag browser, add an OPC Classic Client Driver tag to App2
  2. Provide a name for the OPC Classic Client driver tag.
  3. The Server Prog ID will be "Trihedral.VTSOPC.DA"

Note: this name is case-sensitive.

  4. Provide the name of the workstation that App1 is running on.
  5. Click OK to finish configuring the client driver.
  6. Add a new Analog Status or Analog Input tag.
  7. Set the I/O device field of this tag to use the OPC Classic Client driver you added in step 1.
  8. Set the address using the following template: OPC_Server_Name\tags\all\AI_tag_name.

For this example, the address would be: BedfordSim\tags\all\Tank1Level.

  9. Draw the tag.


Configure VTScada as an OPC Classic Server

You are likely to experience problems if the VTScada server and the OPC Classic Client are not running as the same Windows account. This may be the case if the client is being run as a service, or VTScada is being run under another account (again, as a service). The most common symptom is that the client will attempt to launch a second instance of VTScada rather than connect to the first.

Preparation

Windows Server 2016 was used to determine these steps. They may not be applicable to other operating systems.
Tests used VTScada as a server and a client. Other OPC Servers and clients may differ.

Preparation is required before you configure VTScada to work as an OPC Server. Before proceeding, ensure that you can run Windows PowerShell with elevated permissions and that you have access to a Windows account that is a member of the local machine's Administrative Group.

  1. A VTScada license key that includes the OPC Server option.
    Contact your VTScada account representative.

  2. OPC Core Components installed.
    These are installed automatically by VTScada if your license includes the OPC option.
    May fail to install due to a lack of .Net 2.0. on your server. If so, uninstall any older version of the OPC Core Components and repeat the VTScada installation.

  3. The OPCEnum service must be set to start automatically, and must be running.
    If not, execute the following commands in a Windows PowerShell prompt that has elevated permissions:
$s = Get-Service OPCEnum
$s | Set-Service -StartupType Automatic
$s | Start-Service
  4. Firewall rules for OPCEnum.
    Set the profile as required using an elevated PowerShell prompt.
New-NetFirewallRule -DisplayName "OPC Server Enumerator 1.10" -Action Allow
 -Profile <Choose one of Domain, Private, Public or Any as required>
 -Protocol TCP -Direction Inbound -Program C:\Windows\SysWOW64\OpcEnum.exe
  5. A Firewall rule for VTScada should be enabled for the required connection profile.
    VTScada creates a rule for the Domain and Private profiles. This should be sufficient. Otherwise, create an exception for VTS.exe for all ports on the required profile(s). Steps may vary depending on whether you are using Windows Defender or a third-party firewall.
  6. Restart the computer.

VTScada running in desktop mode

The following steps were determined while using an account that was a member of the local machine's "Administrative Users" group.

  1. Open the DCOM settings for Trihedral VTS OPC Server,
    Select Launch and Activation Permissions,
    Select "Customize,
    Click "Edit",
    Remove "Remote Launch" for the INTERACTIVE user.
  2. Continuing in the DCOM settings for Trihedral VTS OPC Server,
    Select Access Permissions,
    Select "Customize,
    Click "Edit",
    Add the INTERACTIVE user,
    Enable local and remote access for the account.
  3. Continuing in the DCOM settings for Trihedral VTS OPC Server,
    Select the Identity tab,
    Select "The interactive user".
  4. Restart the computer.

VTScada running as a Windows service

The following steps were determined while using an account that was a member of the local machine's "Administrative Users" group. VTScada was set to run as a service under that account.

  1. Open the DCOM settings for Trihedral VTS OPC Server,
    Select Launch and Activation Permissions,
    Select "Customize,
    Click "Edit",
    Remove "Remote Launch" for the INTERACTIVE user.
  2. Continuing in the DCOM settings for Trihedral VTS OPC Server,
    Select Access Permissions,
    Select "Customize,
    Click "Edit",
    Add the INTERACTIVE user
    Enable local and remote access for the account.
  3. Continuing in the DCOM settings for Trihedral VTS OPC Server,
    Select the Identity tab,
    Select "This user"
    Ensure that the credentials for the service account are correctly entered. (Password)
  4. Restart the computer.

Steps within VTScada:

  1. From the tag browser, add an OPC Classic Server tag
  2. Give it a namespace.
    The name of the application is recommended

Within VTScada, no further action is required in order for the client to read the values of tags in the current VTScada application, but you may wish to secure your application. This is done outside VTScada using Windows® operating system user and group configuration tools.

Additional Notes:

  • Values are updated on change.
    The client attached to the VTScada OPC server need not (and should not) use polling. The fastest update rate supported by the server is 20ms.
  • Adding an OPC Server tag to a networked application enables the OPC server on every workstation running the application.
    Clients must specify which workstation they are connecting to.
  • If your application uses an OEM layer, having its own custom tag types, you will need to add code to those tag definitions in order for the OPC Classic Client to see them.
  • If your goal is to share live data between separate VTScada applications, using an OPC Server and Client combination will provide the most efficient means of transferring that data.
  • In large systems, clients can take a long time to subscribe to all of the tags that the OPC Classic Server is publishing. During periods of heavy interaction between the OPC Classic Server and a client, the setting OPCServerRequestRateThreshold can be utilized to temporarily suppress outgoing publishes.

Related information:

GetOPCServerRequestRate

OPCServerRequestRateThreshold

OPCServerRequestRefreshPeriod


OPC Classic Addressing for VTScada

The name of OPC server program id is "Trihedral.VTSOPC.DA". All clients connecting to a VTScada OPC server will need to connect to this Prog ID.

Each VTScada application must have its own namespace. This is defined in the OPC Server Setup tag. The naming hierarchy can be visualized with the help of the following diagram:

To access a tag's value, use the syntax:

NameSpace_name\tags\all\TagName


Properties of OPC Classic Item Tags

The OPC Item tags, which represent VTScada tags, may reveal the following standard properties. Items that do not have a property name are not available to the VTScada OPC Classic Client.

Property ID | Description | Property name
1 | Data Type | N/A
2 | Item Value | N/A
3 | Item Quality | N/A
4 | Item Timestamp | N/A
5 | Item access rights (e.g. R/W) | N/A
6 | Server scan rate (ms) | N/A
100 | EU Units | EUUnits
101 | Description | ItemDescription
102 | High EU | HighEU
103 | Low EU | LowEU
104 | High Instrument Range | HighInstrumentRange
105 | Low Instrument Range | LowInstrumentRange
106 | Contact Close Label | ContactCloseLabel
107 | Contact Open Label | ContactOpenLabel
108 | Item Timezone | ItemTimezone

The following custom OPC properties have been added to the VTScada tag OPC Items as needed:

ID | Description | Property Name
5000 | Area | Area
5001 | Device Tag | DeviceTag
5002 | Address | Address
5003 | Raw (unscaled) Value | RawValue
5004 | Low Alarm Limit | LowAlarmLimit
5005 | High Alarm Limit | HighAlarmLimit

To access a particular OPC Property value, use the following syntax:

AppOneOPCServer\tags\all\TagName\PropertyName

To access a tag's value, use the syntax:

AppOneOPCServer\tags\all\TagName

Not every tag has all of the properties that are listed in the above tables. The following will help you find whether a property is available for the tag you are interested in.

Property | Available in...
ItemDescription | All tags
EUUnits | All tags with a Units variable
HighEU, LowEU, HighInstrumentRange, LowInstrumentRange | All scalable tags (AnalogStatus, AnalogInput, AnalogControl, AnalogOutput)
ContactCloseLabel, ContactOpenLabel | DigitalStatus
DeviceTag, Address | All I/O tags
RawValue | AnalogStatus and AnalogInput
LowAlarmLimit, HighAlarmLimit | AnalogStatus


Tags that support OPC

All tag instances of the following VTScada types will show up as OPC items if you have configured an OPC Server tag. The writable tags make it possible for an OPC Classic Client to use an output tag to write to a PLC value.

Read:

  • Calculation
  • Function
  • Network Status
  • Pump
  • Counter Tag
  • Totalizer Tag

Read and write:

  • Analog Input
  • Analog Output
  • Analog Status
  • Analog Control
  • Digital Input
  • Digital Status
  • SelectorSwitch

Write:

  • Digital Output
  • Digital Control


Item Value/Quality/Timestamp

An OPC Item representing a tag has three values that are updated whenever the tag value changes:

  • Value
  • Quality
  • Timestamp

The timestamp is usually the time that the tag value changed, except in the case of input tags that retrieve timestamps along with values from I/O devices. In the latter case, it is the timestamp that corresponds to the current tag value.

VTScada OPC Server items support the following qualities:

Quality value | Name | Description
0x00 | Bad | The tag’s value is Invalid or the tag’s Quality value indicates Bad quality.
0x04 | Config Error | The tag was deleted or the server application was stopped.
0x40 | Uncertain | The tag is marked as Questionable.
0xC0 | Good | Good quality
0xD8 | Good (Local Override) | The tag has Manual Data specified.


Register or Unregister a VTScada OPC Server

When VTScada is installed, the VTScada OPC Server DCOM component is automatically registered with the operating system. This is required for a client to connect to the VTScada OPC Server (for any VTScada application).

If (after unregistering), you wish to register a VTScada OPC Server, run the following command:

vts/RegOPCServer

If you wish to unregister VTScada as an OPC server, run the following command at a command prompt (Note that this must be run from an administrator-privileged command prompt):

vts/UnRegOPCServer

This is a VTScada-wide setting that will apply to all applications.


OPC Classic Troubleshooting

There have been reports of the OPC core components being damaged during the installation of third-party OPC server. The usual symptom is slow connectivity.

The following two suggestions may help to alleviate the problem.

  • If slow connectivity is experienced while running the 64-bit installation of VTScada, try reinstalling with the 32-bit option selected. In testing, this was found to substantially reduce connection time.
  • Fast response times should be available with the 64-bit version of VTScada. The problem may be caused by OPC-related registry settings and components. To restore the settings:
  1. Stop VTScada
  2. From an Administrator command prompt, run the following files to remove the current installations of the OPC Core components:

OPC_Core_Components_Redistributable 3.00.101.0 (x64).msi
OPC_Core_Components_Redistributable 3.00.101.0 (x86).msi

  3. From the same command prompt, use the same MSIs to reinstall the OPC Core components.
  4. Restart VTScada and test your application.

The OPC server can produce error -1073479672 (0xC0040008) when referencing a tag that does not exist or is not available over OPC.

In large systems, clients may struggle to successfully subscribe to all tags being published

To streamline outgoing publishes in times of heavy interaction, use the setting OPCServerRequestRateThreshold to temporarily suppress outgoing publishes. The OPC Server request rate can be discovered using the API GetOPCServerRequestRate. When the value of OPCServerRequestRateThreshold is exceeded by GetOPCServerRequestRate, VTScada will hold onto the most recent Publish call from every tag and update the client after the request rate has normalized (becomes less than the threshold). The interval used to calculate GetOPCServerRequestRate is set by OPCServerRequestRefreshPeriod. The default is 5 seconds. This is the minimum period of time allowable for an accurate reading but frequent enough to return to normal publishing quickly after high engine activity subsides.

Note that GetOPCServerRequestRate applies across all running applications and OPCServerRequestRateThreshold is controlled at the application level. I.e. If one application has a heavy load all applications can respond independently according to the needs of the application.


Modem Configuration and Use

You can use modems for I/O communication between VTScada and a remote telemetry unit. They are also used for voice and pager calls by the Alarm Notification System.

Verify That Your Modem has Voice Support

If using a modem for the Alarm Notification System, you must choose one that has voice support. Manufacturer’s claims aside, you can verify this as follows:

  1. Open the Windows® operating system control panel.
  2. Open Phone and Modem options.
  3. Select your modem.
  4. Click on Properties
  5. Select the Diagnostics tab
  6. Click on Query Modem

The response will include a line that begins with: AT+F class = ?

  • If this line includes a ,8 at the end, then you have voice modem support.

(e.g. AT+F class = ? 0,1,8)

  • If not, then your modem does not have the required voice support.

All modems are under the control of the Modem Manager, a VTScada service that enables management of modems distributed across a number of different workstations as a common pool. The Modem Manager Server and clients cooperate to provide modem pool management and to set up data paths between modem users and the allocated modems. The modem pool is managed using a time priority queue.

Outgoing calls are queued and are then executed at the requested time. You can receive calls on any modems, even on those on backup servers or clients. Call queue information is distributed to all copies of Modem Manager on a networked system so that queue integrity is maintained, even after switching to a backup server. If a call has not yet been established and server fail-over has occurred, the backup server that handles the Modem Manager's preserved queue will complete the call.

You must configure one Modem tag for each modem in the system. For use with the Alarm Notification System, leave the tag's area field blank. If using a data modem for I/O, you can force data calls to use that modem by configuring the area property to match that of its serial port and adding the application property, UseSerialAreaInModemCall, set to TRUE (1).

All modem access uses TAPI - the Microsoft telephony management layer that enables programs to share and pass calls. TAPI enables the sharing of telephony resources between multiple applications. It interfaces to a modem driver so that you do not need to configure VTScada for the specifics of the modem.

Both a modem audio driver and a TAPI Service Provider (TSP) are provided by Trihedral. These have been designed to avoid several of the problems associated with the older Unimodem V driver, including its limitation in detecting and switching between voice vs. data calls.

The Unimodem V Driver is still available, but will not display in the list of drivers unless you set the application property, UseUnimodem to 1.

if your system includes more than one modem, and those modems are attached to servers located in regions with different area codes, then use the canonical address format Closed American Gas Association for each phone number and configure the server's location within the Windows™ Phone and Modem Settings dialog.

Some internal modems appear to enforce a "serial port" baud rate of 115200, even though they don't use a real serial port, they just appear to be a COM port from a Windows software point of view. Because raw 16-bit linear audio at 8000Hz requires 160000 baud, the decoder on the modem is starved for data, and data accumulates in the ModemTSP queue. For this reason, you should avoid using the 16-bit linear format. Both μ-law and A-law are available on most modems and give excellent audio quality. With a data rate of ~80000 baud, they are well under 115200 baud.


Install a Voice Modem

If your VTScada application is running, stop the application and shut down the VTScada Application Manager before beginning this procedure.

Step 1: Install the voice modem

Your modem will come with specific instructions to guide you through proper modem installation. This will include proper installation of the modem within the computer chassis, as well as proper installation of the modem drivers. Obey the manufacturer’s instructions exactly as written. If you have Internet connectivity, it is recommended that you download and install the most updated device drivers.

Step 2: Verify that modem driver was installed correctly

Verify your modem driver installation to ensure that the voice feature of the modem will work correctly.

Verify the voice feature as follows:

  1. Open the Control Panel of your Windows® operating system.
  2. Open, Phone and Modem Options.
  3. If this is the first time that you have configured a modem in this computer, a prompt will ask for location information. If so, complete this information and select OK to continue. The Phone and Modem dialog box will open to the Dialing Rules tab. Caution: Neglecting to complete the location information will cause your modem to function improperly.
  4. Select the Modems tab.
  5. Choose the modem you have just installed and click on Properties.
    The properties dialog box for your modem will open.
  6. Select the Diagnostics tab and click on the Query Modem button.
    When your modem responds, you will see a set of modem commands and responses as shown in the following images. A modem that is correctly configured for voice will include a comma followed by the number eight (i.e. ,8) within the responses from either the AT+FCLASS=? command or the AT#CLS=? command.

If your modem query fails, then your modem driver has not been installed properly. Uninstall the modem and reinstall as per the manufacturer’s instructions.
If neither of the responses include a ‘,8’, then the modem will not support the Alarm Notification System. Purchase a modem that provides voice support.

Correct: The Response includes ‘,8’

  7. Close Phone and Modem Options.

Step 3: Install the VTScada modem driver and service provider, if not already installed.

In most cases, the wave bus enumerator, voice modem wave device and modem TSP (Telephony Service Provider) are installed automatically and silently. If not, a "Found new Hardware" message may appear the next time that VTScada starts.

If this dialog appears, do the following:

  1. Select, Install Automatically, when prompted.
  2. Click, Next.
  3. Select, Not This Time when prompted to connect to Windows Update.
  4. Click, Next.

As part of this installation, you will see a pop-up titled, Software Installation.

  5. Click, Continue Anyway to allow installation.

Caution: Do not click Stop Installation, or the VTScada modem drivers will not install.

Step 4: Verify correct installation of the VTScada voice modem TSP

Verify your VTScada voice modem TSP installation to ensure the voice feature of the modem will work correctly with the VTScada Alarm Notification System:

  1. Access your Windows Control Panel.
  2. Select Phone and Modem Options. The Phone and Modem dialog box will open to the Dialing Rules tab.
  3. Select the Advanced tab.
  4. Verify that the Trihedral® Voice Modem Service Provider is listed as shown here. Note: If not, your VTScada modem drivers have not been installed correctly. Contact Trihedral Technical Support (1-800-463-2783) for assistance.

  5. Select, Trihedral Voice Modem Service Provider
  6. Click on the Configure button.

A Trihedral Modems Configuration pop-up will show the modems associated with the Service Provider.

  7. Ensure your new modem is listed.

If not, your VTScada modem drivers have not been installed correctly. Contact Trihedral Technical Support (1-800-463-2783) for assistance.

  8. Close Phone and Modem Options.
  9. Restart VTScada


Installing the Trihedral TSP and Modem Audio Driver

Viewing: Develop > Tags and I/O > Other Modes of Communication > Modem Configuration and Use > Installing the Trihedral TSP and Modem Audio Driver

Installing / Uninstalling the Trihedral TSP and Modem Audio Driver

The Trihedral drivers are installed on your system when VTScada is installed. The TSP driver installs silently on all versions of the Windows® operating system, but you may need to confirm that you want to install the modem audio driver.

If dialogs similar to the following are shown, you should select "Install".

To verify that the modem audio driver was installed, you may view the Windows Device Manager dialog. Each modem has one audio driver installed, shown as a "Voice Modem Wave Device". The following image shows how this would appear where three modems have been installed:

To Uninstall:

  1. Locate the VTScada files in Program Files (or Program Files (x86) if running 32 bit).
  2. Under this folder, locate ModemUpdate.
  3. From an elevated command prompt, run Modem update in this location with the option -u (ModemUpdate -u . )

Alternatively, the Modem TSP driver can be uninstalled using Device Manager to uninstall the drivers, and the Advanced tab of the phone and modem control panel to uninstall the Modem TSP.


Configure Modem Logging

The Trihedral® Voice Modem Service Provider can log modem traffic in one of two ways:

  • Standard logging, which is designed to mimic the Unimodem log file format
  • Advanced Logging, which provides control over where the file is stored, and what information is logged. The files created by this option are stored in .csv format, meaning that you can open them with Microsoft Excel.

To enable modem logging:

  1. From the control panel of the Windows® operating system, open Phone and Modem options.
  2. Open the Advanced tab.
  3. Select the Trihedral Voice Modem Service Provider

  4. Click, "Configure".
  5. Select your modem.

  6. Click on its Configure button.

The Modem Properties dialog will open.

  7. Open the Logging tab.
  8. Select the "Enable" box for either standard or advanced logging. See the following notes to help you decide which.

If selecting Advanced Logging, take care to select only the options that are necessary. The Audio Control, in particular, will result in the creation of very large log files. Instructions follow. In most cases, standard logging will prove sufficient.

Do not select options in the Developer Logging tab. These are intended for use only for short time periods and only when working with Trihedral Technical Support to resolve modem problems. While the Developer Logging options are enabled, overall performance of communications through the modem is impaired.

For Advanced Logging:

  1. Choose the folder path for storage of the logs by clicking the "Browse" button.
    The folder selection dialog opens. The path chosen here is displayed in the Log Path field.
  2. Make the Log Path accessible to the "NETWORK SERVICE" user, which is a virtual user account used by the operating system to run the Trihedral Voice Modem Service. This is done using the tools provided by Microsoft Windows as follows:
    1. Navigate to the selected folder using Windows Explorer and right-click on the folder, selecting Properties from the droplist that opens.
    2. In Properties, click the Security tab.
    3. In the Security tab, click Edit.
      The Permissions dialog opens.
    4. Click, Add...
      The user selection dialog opens. This dialog has a single data entry field.
    5. Type "NETWORK SERVICE" (all caps, include the space but not the quotes) into the data entry field, then click OK.
      The User Selection dialog closes. The Permissions dialog remains open.
    6. Ensure that "NETWORK SERVICE" is selected in the box in the top half of the Permissions dialog.
      At the bottom of the Permissions dialog is a list of permissions including Full control, Modify, etc.
    7. Ensure that there are no selected check boxes in the Deny column and that the check boxes in the Allow column are selected for at least the following permissions:
      • List folder contents
      • Read
      • Write
    8. Click OK on the Permissions dialog and the Properties dialog.


Removing a Modem

Viewing: Develop > Tags and I/O > Other Modes of Communication > Modem Configuration and Use > Removing a Modem

Remove a Voice Modem

There are various reasons why you may need to replace a modem. When replacement is necessary, it is critical that the correct modem and driver removal is followed before installing a new modem.

Use this procedure precisely to ensure proper modem and driver removal.

Step 1: Remove the manufacturer's modem driver

  1. Access the control panel of the Windows® operating system.
  2. Open Phone & Modem Options.
  3. Open the Modems tab.
  4. Select the Modem to remove.
  5. Click on the Remove button.

The modem is removed from the list.

  6. Close Phone & Modem Options.

Step 2: Remove the physical modem from the computer.

  1. Shut off your computer and physically remove the modem from the computer.
  2. Restart your computer.

Step 3: Verify that the voice modem driver entries in the registry have been removed.

Manually changing the Windows Registry may cause your Windows Operating System to become unstable. If you are not familiar with accessing and working within the Windows registry, contact Trihedral® Technical Support (1-800-463-2783) for assistance.

  1. Create a system restore point

Refer to your Windows Help system for guidance on creating and using system restore points.

  2. Open your registry editor.
  3. Navigate to the registry folder shown here. (Refer also to following image.)
Computer
      HKEY_LOCAL_MACHINE
      SYSTEM
      CurrentControlSet
      Control
      Class
            {4D36E96D-E325-11CE-BFC1-08002BE10318}

Any sub-folders of this that are numbered 1000 or higher, refer to the VTScada modem TSP. As such, ONLY delete folders numbered 1000 or higher. All keys within these folders are deleted when the folders are removed.

Caution: If there are any existing folders with labels less than 1000, contact Trihedral Technical Support (1-800-463-2783) for assistance.

The removal of the modem and its associated drivers is complete. You may install a new modem safely.


Modem Manager Operation

The Modem Manager runs as a server on one system and as a client on others. The server and client Modem Managers cooperate to provide the modem pool management and to set up data paths between modem users and the allocated modem.

Incoming and outgoing calls are referred to as "tasks". When an outgoing call (or task) is requested by a workstation on the network, the Modem Manager will determine if a modem is free, select an unused modem, and dial the call. If the Modem Manager determines that all modems are in use, the call is queued until a modem becomes free.

The queue operates on a time priority basis. If an outgoing call is attempted and fails, the call is not sent to the tail of the queue, but slips into the queue according to configured parameters. For example, if a call is tried and fails, and was configured to redial in one minute, then the call is added to the queue as needed.

The modem selected by the Modem Manager to perform the outgoing call may be on a different workstation from the task requesting the call. The Modem Manager sets up transparent data paths between the modem and the requester. In the event that the Modem Manager fails to complete the connection, it can retry the attempt using alternative modems (if available).

When an incoming call is received, the Modem Manager passes the initial data to tasks that have previously registered an interest in incoming calls. If a task accepts the offered call, then the Modem Manager will set up transparent data paths between the modem and the recipient. If no one accepts the call, then the Modem Manager will return the call to the operating system to allow other applications the opportunity to take the call.

if your system includes more than one modem, and those modems are attached to servers located in regions with different area codes, then use the canonical address format Closed American Gas Association for each phone number and configure the server's location within the Windows™ Phone and Modem Settings dialog.

Factors to Consider for the Configuration of Incoming Calls

Incoming calls are handled by a discriminator, which will control where to send the call. In most applications, the only audio discriminator is the Alarm Notification System, which appears to the Modem Manager as a driver.

If you wish to create your own audio discriminator, or if you need to manage incoming data calls from any device, write a custom driver using the Modem Manager programming interface.

Consider the following factors for the configuration of incoming calls that are handled by the Modem Manager.

  • Answer incoming calls?
  • Set up modems (on a per modem basis) to answer on a specific number of rings.
  • Decide how many modems to keep free to accept incoming calls.
  • Specify noise filtering conditions to ensure that good connections are detected correctly.
  • Register the driver (provide a module).
  • Decide whether to hand-off unaccepted calls.
  • Specify to the Modem Manager where to route the data.

Factors to Consider for the Configuration of Outgoing Calls

Restrictions of call retries are handled using the CallLength, CycleDelay, and CallInterval1 through CallInterval10 application properties.

Local telecommunications authorities may have regulations regarding the frequency at which call attempts are made to a particular number. Use CallLength, CycleDelay, and CallInterval1 through CallInterval10 parameters to define a redial cycle. CycleLength defines the number of steps in the cycle (with a maximum of 10), CallInterval1 through to CallInterval10 define the delay (in seconds) at each step transition, and CycleDelay defines the final delay (in seconds) before the cycle restarts.

The DialResetTime application property enables you to configure the minimum amount of time in seconds between a hang-up and the next use of the modem. The default value is 10 seconds. During this time, TAPI sends initialization strings to reset the modem. If not granted a long-enough time interval, the modem will not reset properly.

Allocating Modems in a Central Managed Pool for Outgoing Calls

There are situations that require a caller to use only modems with a specific property when making a call, even though those modems are part of the central managed pool. For example, where virtual modems have been set up with special initialization strings, such as for cellular connection.

Use the Area parameter of Modem tags for this purpose. If a Modem tag has an Area defined, then it is selected for an outgoing call only if the call originator has specified the same area name. Additionally, when allocating local modems on a particular system, the allocator will take account of any Area name associated with the Modem tag, and use it to map the physical modem. The actual capabilities of a modem (Data, Voice, Fax, etc.) are handled by matching the physical media mode of the modem.

Selecting Which Modem to use in a Network Application

If you have a networked application with modems available on more than one server, the standard VTScada behavior prior to version 10 was to use only the modem on the primary modem server, so long as it is available. If the modem on the primary server is not available, another modem is selected for use based on which was least recently used. There is a potential drawback to this system in that the modems on backup servers are not used (and therefore not verified to function) until they are needed.

This modem selection behavior is controlled by the application property, MMCycleTime. When not set to any value, modems are selected as just described.

When MMCycleTime is set to zero (0), then for each call, VTScada will select the least recently used of all modems. This ensures that modems are used equally.

You may retain the original behavior, but if so, you should ensure that other modems are used and thereby tested on a regular basis by setting MMCycleTime to a numeric value greater than 0. For example, if MMCycleTime is set to 86400 (the default value, which is the number of seconds in a day) then any modem that has not been used for that length of time is selected for the next alarm. If more than one modem has not been used in a day, then the least recently used is selected. This system enables you continue using the modem on the primary server while it is available, but once a day (depending on the need to send alarm notifications) modems on backup servers are used.


Designate Modem Manager Server(s)

As with many of VTScada's services, it is possible to designate a workstation other than the primary configuration server to manage the Modem Manager Service.

In a multi-server application, the Modem Manager is configured to run on one workstation that was designated as its server. This can be any workstation that is licensed to operate as a server. It is prudent to spread services out, to distribute the load across workstations for larger applications.

You should have at least two servers: one as the primary Modem Manager server and the other as a backup server in the case that the primary Modem Manager server fails. Using a network device that shares the same modem between two servers may have unintended side effects.

Related Tasks:

Servers for Specific Services


MultiSpeak Support

The MultiSpeak® communication protocol defines a web services-based standard for exchange of data between SCADA and various services required by electric utilities, such as outage management.

VTScada uses a subset of the MultiSpeak specification to support selected methods required by the Milsoft™ DisSPatch® outage management system and has received a MultiSpeak 4.1.6 Interoperability certificate from Milsoft for DisSPatch. It does not support all devices using the MultiSpeak protocol.

For a little bit of background, MultiSpeak is a service (not a driver, it does not have a tag). It uses SOAP services (Simple Object Access Protocol) over HTTP as a means of communicating between systems so it must use the HTTP available in VTScada. To this end, you must be prepared to configure your application for thin client access.

From there, it is your IO tags that you will be modifying to publish data to the outage management system with some MultiSpeak properties adjustable from your application configuration.

Configure your application and enable MultiSpeak:

You must complete each of the following actions to complete your MultiSpeak configuration:

Check that your license supports Remote Data Access

In the VAM, open the menu and select License Management to see which whether "Remote Data Access" is enabled by your license key.

Secure your application and grant thin client access

Secure Your Application and ensure that at least one account has the Thin Client Access privilege. You will be expected to provide this username and password to the outage management system (ie. Milsoft)

Configure a Realm and a Thin Client server

Configure a VTScada Thin Client Server and Configure a Realm. If you wish to communication over a secure connection you must install an SSL certificate for your server. This is optional but strongly recommended.

Once your thin client/server setup is complete, test it out. Click "test" next to the Anywhere URL in the Realms tab. A web browser should pop up and display a VTScada login screen. This is a quick and easy way to rule out a connection issue if there is troubleshooting to be done later.

Configure MultiSpeak properties in VTScada

  • Add the names of your Internet Realms to the application property MultiSpeakRealmNames.

  • Add the URL to which you intend to connect, to the application property MultiSpeakSubscriptionURL.

  • You may wish to limit the number of points sent at a time with MultiSpeakMaxMessagePoints

  • Check MultiSpeak Interface Properties

Provide directions to your I/O and Calculations tags

You must select the Publish option in each I/O and Calculations tag that will communicate with the outage management system.

For most tags, only the value is available directly. Driver tags contain seven variables in addition to the value. (Communication Driver Log-Enabled Variables) Other variables and properties can be monitored by creating an expression in an I/O and Calculations tag to mirror that variable, then publishing the calculation tag. For an example, refer to: Monitor the Alarm Status

MultiSpeakLegacyIOPublish can be enabled in applications that use legacy tags without the publish option, however, with this property enabled, all I/O tags in your application will publish. You will not be able to pick and choose.

Assuming that all of the above have been configured correctly and that there is a working connection between your VTScada server and the DisSPatch device, communication should now be enabled.

If notifications sent by VTScada have their responses successfully received from Milsoft but no outages / normalization events are reported, make sure that the Company name set in Milsoft matches the MultiSpeakMHCompanyAttribute if set or the default value "Trihedral Engineering Ltd." otherwise .

Troubleshooting:

General MultiSpeak troubleshooting tools

All MultiSpeak messages can be captured in the VTScada Trace Viewer Application using the SOAP message Tracing data source.

VTScada can also maintain a diagnostics trace log for use by support staff. This has two components:

  • An in-memory buffer of recent events that will be captured by a memory dump
  • A log file of recent events that will never overflow (it regularly cuts out older records).
    This is located at <Application Folder>\Data\TraceFiles\MultiSpeak.log

There are three settings that control the operation of the trace log:

  • MultiSpeakTraceFileSize - How large the log file can get before older records are removed.
  • MultiSpeakTraceLevel - How much detail to log.
  • MultiSpeakTraceMemorySize - How many recent events to store in memory

This is lightweight and is designed to be left running so diagnostics can always be retrieved after a point of interest. Within the MultiSpeak service, various events are raised with a log level. If that level is at or below the MultiSpeakTraceLevel setting, the event is added to the file and the memory buffer.

In a multi-server environment, only the server sends out notifications. For support purposes, make sure the traces and logs are taken on the server and that the endpoint on the Multispeak client points mainly to the VTScada main server (and, if possible, the backup server)

Specific MultiSpeak Scenarios

In the case where your application runs on multiple workstations, VTScada will ensure that only the primary server maintains the notification queue. In spite of this there may be instances where the following can occur:

  • A notification may be received multiple times by the Outage Management System.
  • Some notifications may be lost.

If this is unacceptable, the configuration must specify MultiSpeakMaxMessagePoints to be exactly 1 (so that the queue length is 1) and MultiSpeakNotificationDelay to be as short as possible. This configuration will guarantee that every change in an I/O will immediately be sent to the outage management system.

If notifications sent by VTScada have their responses successfully received from Milsoft but no outages/normalization events are reported, make sure that the Company name set in Milsoft matches MultiSpeakMHCompanyAttribute if set or the default value "Trihedral Engineering Ltd.

Related Properties

MultiSpeakLegacyIOPublish - Set TRUE to enable MultiSpeak publishing for Legacy I/O tags

MultiSpeakMaxMessagePoints - Maximum number of ScadaPoints (tag values) to include in one message.

MultiSpeakMaxPointIDLength - Maximum number of characters for a MultiSpeak PointID.

MultiSpeakMessageRetries - Number of times a MultiSpeak notification should try again after timing out.

MultiSpeakMessageTimeout - Time for MultiSpeak notification messages to wait for a response.

MultiSpeakMHCompanyAttribute - Outgoing MultiSpeakMsgHeader Company attribute value.

MultiSpeakNotificationDelay - Time in seconds to wait before sending a notification message.

MultiSpeakPingURLProbingPeriod - Sets the frequency of checks to verify that a MultiSpeak endpoint remains available during long periods of inactivity.

MultiSpeakRealmNames - List of realm names that can accept incoming MultiSpeak messages.

MultiSpeakSubscriptionMethods - CSV list of methods for MultiSpeak notification messages.

MultiSpeakSubscriptionPassword - Password to use for MultiSpeak notification messages.

MultiSpeakSubscriptionURL - Destination for MultiSpeak notification messages.

MultiSpeakSubscriptionUsername - Username to use for MultiSpeak notification messages.

MultiSpeakTraceFileSize - Maximum size of the file trace for the MultiSpeak service in MB.

MultiSpeakTraceLevel - Diagnostic trace level for the MultiSpeak service.

MultiSpeakTraceMemorySize - Maximum size of the in-memory trace for the MultiSpeak service.


MultiSpeak Data Structures

VTScada supports the following MultiSpeak data structures:

  • scadaPoint
  • scadaStatus
  • scadaAnalog
  • PointID

scadaPoint

<scadaPoint objectID="a89ksdf8">
  <objectName>Temperature</objectName>
  <description>Current temperature</description>
  <scadaPointType>analog</scadaPointType>
</scadaPoint>

objectID

This will get the PointID which is the tag UniqueID or generated hash.

objectName

VTScada tag name

description

VTScada description (translated to default language)

scadaPointType

Analog or status, based on the tag's membership in the Analogs or Digitals group respectively

scadaStatus

<scadaStatus objectID="a89ksdf8" verb="Change">
  <objectName>Breaker 23A</objectName>
  <quality>Measured</quality>
  <status>Open</status>
  <timeStamp>2021-02-04T21:15:00.000Z</timeStamp>
</scadaStatus>

objectID

PointID (uniqueID or hash)

verb

Always "Change"

objectName

VTScada tag name

quality

Unknown if the tag value is Invalid

Calculated if the tag belongs to the Analytics group (a calculation tag)

Measured if the tag represents an I/O value

status

Unknown if Invalid

Closed if 1

Open if 0

timeStamp

Time of the last value change in UTC

scadaAnalog

<scadaAnalog objectID="f2aa6dyf8" verb="Change">
  <objectName>Voltage</objectName>
  <value units="VAC">208</value>
  <quality>Measured</quality>
  <timeStamp>2021-04-06T15:13:01.025</timeStamp>
</scadaAnalog>

objectID

This will get the PointID which is the tag UniqueID or generated hash.

verb

Always "Change"

objectName

VTScada tag name

value

current VTScada tag value

units

units of the tag translated to the default language

quality

Unknown (if invalid),

Calculated (if tag belongs to the Analytics group),

Measured (otherwise)

timeStamp

UTC timestamp VTScada read the current value

PointID

The PointID is the unique identifier for tags that is common between VTScada and other MultiSpeak Endpoints. It is returned in scadaPoint, scadaAnalog, and scadaStatus structures, and is used to request a particular tag value using the GetSCADAAnalogBySCADAPointID and GetSCADAStatusBySCADAPointID methods.

The PointID in VTScada is the tag's UniqueID, although in the specific case of the GetSCADA methods, VTScada will also respond to requests by the tag name.

Some systems place a character limit on the PointID, and while VTScada does not have that requirement, the MultiSpeakMaxPointIDLength setting can be configured to accommodate such systems. If this is set and the UniqueID is longer than the limit, a hash is generated to use as a 10-character PointID instead (although the UniqueID will still be used if it's short enough). Milsoft's DisSPatch OMS has a maximum of 38 characters, therefore VTScada should be configured accordingly.


MultiSpeak Notification Methods

Notification methods are a report by exception scheme where VTScada sends Analog and Status value changes to another MultiSpeak endpoint using the SCADAAnalogChangedNotification and SCADAStatusChangedNotification methods. These send arrays of scadaAnalog and scadaStatus points respectively, based on the VTScada tag type (specifically membership in the Analogs or Digitals groups).

The MultiSpeak specification outlines subscription registration using the RegisterForService method. VTScada does not support this method, and instead requires this configuration to be performed using application properties (see MultiSpeakSubscriptionMethods, MultiSpeakSubscriptionPassword, MultiSpeakSubscriptionURL). The parameters of the RegisterForService method map directly to the VTScada properties.

Tags are configured to be notified by selecting the Publish check box in the I/O tag. Legacy tags can also publish based on the MultiSpeakLegacyIOPublish property value.

The operation of the notification scheme works as follows:

  1. Whenever a tag that is configured to publish gets a new value, it is added to an internal list inside VTScada. Separate lists are maintained for Analog or Status (digital) points.
  2. After the list reaches MultiSpeakMaxMessagePoints in length or MultiSpeakNotificationDelay seconds have passed, the message will be built and sent (and the list cleared). A tag will not be in the list more than once. Newer changes will replace older ones.
  3. After the message is sent, VTScada will wait for confirmation that the notification was received (HTTP code of 2xx without error objects inside). Success or failure will be logged, the latter with any error message from the server.
  4. If VTScada fails to receive a notification response or the connection times out (based on the value of MultiSpeakMessageTimeout), it will retry with a PingURL command up to MultiSpeakMessageRetries times. If one of these PingURL requests succeeds before MultiSpeakMessageRetries, the notification is tried only once more.


MultiSpeak API

This section is provided as a technical reference. Most users will not need to work with the methods described here.

Of the MultiSpeak service methods specified in interface 9 (Outage Analysis-SCADA), VTScada supports only the ones needed to interoperate with Milsoft’s DisSPatch™ Outage Management System.

Milsoft has developed its MultiSpeak web service using the MultiSpeak 4.1.6 standard. The web service model defined by the standard uses the Soap 1.1 protocol as the message format and HTTP as the transport protocol.

The DisSPatch system is able to invoke the following methods on a connected VTScada application:

  • PingURL
  • GetAllSCADAPoints
  • GetMethods
  • GetSCADAAnalogByScadaPointID
  • GetSCADAStatusByScadaPointID

VTScada may invoke the following methods on a connected DisSPatch system:

  • GetMethods
  • PingURL
  • SCADAAnalogChangedNotification
  • SCADAStatusChangedNotification


GetAllSCADAPoints

The GetAllSCADAPoints method provides a way for an OAS Closed Outage Analysis System to request the complete list of SCADA points from a SCADA system. The SCADA system is expected to respond back with all the SCADA points that exist within its system. The list of SCADA points can then be used to map points to the appropriate phases on device elements in the OAS circuit model.

If all the points fit in a single message, then ObjectsRemaining will be set to 0 and LastSent is the last point listed in the message.

A sample GetAllScadaPoints request coming out of an OAS:

POST http://MultiSRV/MultiSpeakRealm1/ HTTP/1.1
Connection:Keep-Alive
Content-Type:text/xml; charset=utf-8
Accept:text/*
Authorization:Basic YTph
User-Agent:SOAPWinHTTPClient
SOAPAction:"http://www.multispeak.org/Version_4.1_Release/GetAllSCADAPoints"
Content-Length:882
Host:MultiSRV

<?xml version="1.0" encoding="UTF-8"?>
 <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
                xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Header>
      <snp:MultiSpeakMsgHeader xmlns:snp="http://www.multispeak.org/Version_4.1_Release"
          UserID="" Pwd="" MajorVersion="4" MinorVersion="1" BuildString="Release" Build="6"
          AppName="Company Software Name" AppVersion="Company Software Version"
          Company="Company Name" />
    </soap:Header>
    <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
       <GetAllSCADAPoints xmlns="http://www.multispeak.org/Version_4.1_Release" />
    </soap:Body>
 </soap:Envelope>

A sample GetAllScadaPoints response coming from VTScada. Each point (tag) is uniquely identified by an objectID. It carries its VTScada tag name as well as the type (Analog or Status). Note that VTScada would return in a GetAllScadaPoints response only the IO tags that have their “Publish” flag set.

If VTScada has more tags to send than “MultiSpeakMaxMessagePoints” then multiple messages can be sent. VTScada sends a response with the header containing an attribute called “lastSent” set to the last pointID contained in the message. It also sets another attribute called ObjectsRemaining to the number of tags remaining. This signals to the OAS that there are more tags to come. The OAS can send more requests and set the element lastReceived to the lastSent, repeating as required.

HTTP/1.1 200 OK
Date: Mon, 25 Jan 2021 20:30:00 GMT
Server: VTScada 12.0.26
Content-Type: text/xml; charset="utf-8"
Content-Length: 3361
Cache-Control: no-cache, no-store

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
                  xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
                  xmlns:s="http://www.w3.org/2001/XMLSchema"
                  xmlns:s1="cpsm_V4.1_Release"
                  xmlns:s2="gml_V4.1_Release"
                  xmlns:s3="http://www.w3.org/1999/xlink"
                  xmlns:si="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
                  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
                  xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
                  xmlns:tns="http://www.multispeak.org/Version_4.1_Release"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <soapenv:Header>
    <tns:MultiSpeakMsgHeader MajorVersion="4" MinorVersion="1" Build="6" BuildString="Release"
             AppName="VTScada" AppVersion="12.0026" Company="Trihedral Engineering Ltd."
             MessageID="c7fa2e8a-edb3-40b6-b125-d22f7a9fcb64"
             TimeStamp="2021-01-25T20:30:00.216Z" Context="Production" />
  </soapenv:Header>
  <soapenv:Body>
    <tns:GetAllSCADAPointsResponse>
    <tns:GetAllSCADAPointsResult>

<tns:scadaPoint objectID="i8ho{7gz&amp;p">
   <tns:objectName>CalcMom</tns:objectName> <tns:description>CalcMom</tns:description>
   <tns:scadaPointType>analog</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="i8ho{7gz&amp;p\#}s}143_r;">
  <tns:objectName>CalcMom\Calc1</tns:objectName>
  <tns:description>Calc1</tns:description>
  <tns:scadaPointType>analog</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="i8ho{7gz&amp;p\#}s}143_r;\ke6tuvsd2r">
  <tns:objectName>CalcMom\Calc1\Calc2</tns:objectName>
  <tns:description>Calc2</tns:description>
  <tns:scadaPointType>analog</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="quywa8lOb5">
  <tns:objectName>CalcMom\Calc1\Calc2\Calc3</tns:objectName>
  <tns:description>Calc3</tns:description>
  <tns:scadaPointType>analog</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="cjZaH10iYp">
  <tns:objectName>CalcMom\Calc1\Calc2\Calc3\CalcChildWithaLongName_ABCDEFGHIJKLMNOPQRSTUVWXYZ</tns:objectName>
  <tns:description>CalcChildWithaLongName_ABCDEFGHIJKLMNOPQRSTUVWXYZ</tns:description>
  <tns:scadaPointType>analog</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="!~7jii98ja">
  <tns:objectName>StatusMom</tns:objectName>
  <tns:description>StatusMom</tns:description>
  <tns:scadaPointType>status</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="!~7jii98ja\fw^x)hm%bh">
  <tns:objectName>StatusMom\Status1</tns:objectName>
  <tns:description>Status1</tns:description>
  <tns:scadaPointType>status</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="!~7jii98ja\fw^x)hm%bh\)6{k0p-132">
  <tns:objectName>StatusMom\Status1\Status2</tns:objectName>
  <tns:description>Status2</tns:description>
  <tns:scadaPointType>status</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="Gtqn4wN8M9">
  <tns:objectName>StatusMom\Status1\Status2\Status3</tns:objectName>
  <tns:description>Status3</tns:description>
  <tns:scadaPointType>status</tns:scadaPointType>
</tns:scadaPoint>

<tns:scadaPoint objectID="pPylU8plF9">
  <tns:objectName>StatusMom\Status1\Status2\Status3\Status4</tns:objectName>
  <tns:description>Status4</tns:description>
  <tns:scadaPointType>status</tns:scadaPointType>
</tns:scadaPoint>

</tns:GetAllSCADAPointsResult>
</tns:GetAllSCADAPointsResponse>
</soapenv:Body>
</soapenv:Envelope>

Sample response with the lastSent set. (Note that the property MultiSpeakMaxMessagePoints is set to 3 for testing):

<?xml version="1.0" encoding="UTF-8"?>
 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
                   xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
                   xmlns:s="http://www.w3.org/2001/XMLSchema"
                   xmlns:s1="cpsm_V4.1_Release"
                   xmlns:s2="gml_V4.1_Release"
                   xmlns:s3="http://www.w3.org/1999/xlink"
                   xmlns:si="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                   xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
                   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
                   xmlns:tns="http://www.multispeak.org/Version_4.1_Release"
                   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <soapenv:Header>
    <tns:MultiSpeakMsgHeader MajorVersion="4" MinorVersion="1" Build="6"
                   BuildString="Release" AppName="VTScada" AppVersion="12.0026"
                   Company="Trihedral Engineering Ltd." MessageID="bfc3ebb9-4f50-4735-8748-aa22b5b2d04a"
                   TimeStamp="2021-01-25T20:51:14.955Z" Context="Production"
                   LastSent="pPylU8plF9" ObjectsRemaining="0" />
  </soapenv:Header>
  <soapenv:Body>
    <tns:GetAllSCADAPointsResponse>
    <tns:GetAllSCADAPointsResult>
    <tns:scadaPoint objectID="i8ho{7gz&amp;p">
      <tns:objectName>CalcMom</tns:objectName>
      <tns:description>CalcMom</tns:description>
      <tns:scadaPointType>analog</tns:scadaPointType>
    </tns:scadaPoint>

    <tns:scadaPoint objectID="i8ho{7gz&amp;p\#}s}143_r;">
      <tns:objectName>CalcMom\Calc1</tns:objectName>
      <tns:description>Calc1</tns:description>
      <tns:scadaPointType>analog</tns:scadaPointType>
    </tns:scadaPoint>

    <tns:scadaPoint objectID="i8ho{7gz&amp;p\#}s}143_r;\ke6tuvsd2r">
      <tns:objectName>CalcMom\Calc1\Calc2</tns:objectName>
      <tns:description>Calc2</tns:description>
      <tns:scadaPointType>analog</tns:scadaPointType>
    </tns:scadaPoint>
    </tns:GetAllSCADAPointsResult>
    </tns:GetAllSCADAPointsResponse>
  </soapenv:Body>
</soapenv:Envelope>


GetMethods

The GetMethods method provides a way for an OAS to request a list of MultiSpeak methods supported by a VTScada. VTScada will respond with a GetMethodsResponse containing a GetMethodsResult listing all the methods.

A sample GetMethods request coming from an OAS:

POST http://MultiSRV/MultiSpeakRealm1/ HTTP/1.1
Connection:Keep-Alive
Content-Type:text/xml; charset=utf-8
Accept:text/*
Authorization:Basic YTph
User-Agent:SOAPWinHTTPClient
SOAPAction:"http://www.multispeak.org/Version_4.1_Release/GetMethods"
Content-Length:882
Host:MultiSRV

An example of a corresponding GetMethods returned from VTScada:

HTTP/1.1 200 OK
Date: Mon, 25 Jan 2021 20:21:56 GMT
Server: VTScada 12.0.26
Content-Type: text/xml; charset="utf-8"
Content-Length: 1398
Cache-Control: no-cache, no-store

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:s1="cpsm_V4.1_Release" xmlns:s2="gml_V4.1_Release" xmlns:s3="http://www.w3.org/1999/xlink" xmlns:si="http://www.w3.org/2001/XMLSchema-instance" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:tns="http://www.multispeak.org/Version_4.1_Release" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
<soapenv:Header>
<tns:MultiSpeakMsgHeader MajorVersion="4" MinorVersion="1" Build="6" BuildString="Release" AppName="VTScada" AppVersion="12.0026" Company="Trihedral Engineering Ltd." MessageID="d8246baf-48c7-4f4b-8a0f-c667f1f25d71" TimeStamp="2021-01-25T20:21:56.846Z" Context="Production" />
    </soapenv:Header>
    <soapenv:Body>
       <tns:GetMethodsResponse>
           <tns:GetMethodsResult>
              <tns:string>PingURL</tns:string>
              <tns:string>GetMethods</tns:string>
              <tns:string>GetAllSCADAPoints</tns:string>
              <tns:string>GetSCADAAnalogBySCADAPointID</tns:string>
              <tns:string>GetSCADAStatusBySCADAPointID</tns:string>
           </tns:GetMethodsResult>
       </tns:GetMethodsResponse>
    </soapenv:Body>
</soapenv:Envelope>


PingURL

The PingURL method provides a way for an OAS Closed Outage Analysis System to test that it can communicate with VTScada’s MultiSpeak web service. VTScada will respond with a PingURLResponse. An empty response with an empty <PingURlResult>, i.e. with no error content, means success.

VTScada also sends PingURL requests to an OAS in order to verify that it is alive. For example, if a notification is sent by VTScada, but no response is recieved before a preset time, VTScada will send a number of PingURL requests to verify whether the OAS is online before giving up.

When the MultiSpeak service starts, and assuming that a subscription is valid(*), it will send successive PingURLs, separated by MultiSpeakMessageTimeout pauses, until one succeeds. The service will then immediately send a GetMethods request. If the GetMethods request fails, the cycle PingURL / GetMethods will restart until GetMethods succeeds. If a notification fails, the PingURL / GetMethods cycle restarts until a GetMethods request succeeds.

A sample PingURL request coming from an OAS:

POST http://MultiSRV/MultiSpeakRealm1/ HTTP/1.1
Connection:Keep-Alive
Content-Type:text/xml; charset=utf-8
Accept:text/*
Authorization:Basic YTph
User-Agent:SOAPWinHTTPClient
SOAPAction:"http://www.multispeak.org/Version_4.1_Release/PingURL"
Content-Length:879
Host:MultiSRV

An example of a corresponding PingURLResponse returned from VTScada:

HTTP/1.1 200 OK
Date: Mon, 25 Jan 2021 20:10:24 GMT
Server: VTScada 12.0.26
Content-Type: text/xml; charset="utf-8"
Content-Length: 1152
Cache-Control: no-cache, no-store


GetSCADAAnalogByScadaPointID

The GetSCADAAnalogByScadaPointID method is used by an OAS Closed Outage Analysis System to request SCADA analog data on demand for a specific SCADA point. The analog data is used as view-only data by Milsoft.

Sample GetSCADAAnalogByScadaPointID request from an OAS:

POST http://MultiSRV/multispeaktestrealm/ HTTP/1.1
Connection:Keep-Alive
Content-Type:text/xml; charset=utf-8
Accept:text/*
Authorization:Basic YTph
User-Agent:SOAPWinHTTPClient
SOAPAction:"http://www.multispeak.org/Version_4.1_Release/GetSCADAAnalogBySCADAPointID"
Content-Length:1006
Host:MultiSRV

Sample GetSCADAAnalogByScadaPointID response from VTScada. If successful (pointID corresponds to a tag that is accessible by the user according to the filtering rules being applied ) then the response contains the tag name, value, timestamp, quality, and units. If it fails then the response contains an error such as “tag not found” or “incorrect tag type”. The latter happens if we pass in an objectID that corresponds to a status and not an analog.

HTTP/1.1 200 OK
Date: Mon, 25 Jan 2021 21:03:06 GMT
Server: VTScada 12.0.26
Content-Type: text/xml; charset="utf-8"
Content-Length: 1536
Cache-Control: no-cache, no-store

 <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
                  xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
                  xmlns:s="http://www.w3.org/2001/XMLSchema"
                  xmlns:s1="cpsm_V4.1_Release"
                  xmlns:s2="gml_V4.1_Release"
                  xmlns:s3="http://www.w3.org/1999/xlink"
                  xmlns:si="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
                  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
                  xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
                  xmlns:tns="http://www.multispeak.org/Version_4.1_Release"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

  <soapenv:Header>
    <tns:MultiSpeakMsgHeader MajorVersion="4" MinorVersion="1" Build="6" BuildString="Release"
                             AppName="VTScada" AppVersion="12.0026" Company="Trihedral Engineering Ltd."
                             MessageID="27371d7b-8dd7-423f-beeb-57cc535625e5"
                             TimeStamp="2021-01-25T21:03:06.217Z" Context="Production" />
    </soapenv:Header>
    <soapenv:Body>
      <tns:GetSCADAAnalogBySCADAPointIDResponse>
        <tns:GetSCADAAnalogBySCADAPointIDResult objectID="cjZaH10iYp" verb="Change">
          <tns:objectName>CalcMom\Calc1\Calc2\Calc3\CalcChildWithaLongName_ABCDEFGHIJKLMNOPQRSTUVWXYZ</tns:objectName>
          <tns:value units="Calc4/Units">10</tns:value>
          <tns:quality>Calculated</tns:quality>
          <tns:timeStamp>2021-01-25T21:03:06.001Z</tns:timeStamp>
        </tns:GetSCADAAnalogBySCADAPointIDResult>
      </tns:GetSCADAAnalogBySCADAPointIDResponse>
    </soapenv:Body>
</soapenv:Envelope>

Sample response with an error:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
                  xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
                  xmlns:s="http://www.w3.org/2001/XMLSchema"
                  xmlns:s1="cpsm_V4.1_Release"
                  xmlns:s2="gml_V4.1_Release"
                  xmlns:s3="http://www.w3.org/1999/xlink"
                  xmlns:si="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
                  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
                  xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
                  xmlns:tns="http://www.multispeak.org/Version_4.1_Release"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <soapenv:Header>
    <tns:MultiSpeakMsgHeader MajorVersion="4" MinorVersion="1" Build="6"
                             BuildString="Release" AppName="VTScada" AppVersion="12.0026"
                             Company="Trihedral Engineering Ltd."
                             MessageID="ee292939-4760-447b-a421-e430725be877"
                             TimeStamp="2021-01-25T21:10:10.530Z" Context="Production" />
  </soapenv:Header>
  <soapenv:Body>
    <tns:GetSCADAAnalogBySCADAPointIDResponse>
    <tns:GetSCADAAnalogBySCADAPointIDResult objectID="cjZaH10iY" errorString="Tag not found" />
    </tns:GetSCADAAnalogBySCADAPointIDResponse>
  </soapenv:Body>
</soapenv:Envelope>


GetSCADAStatusByScadaPointID

Similar to GetSCADAAnalogBySCADAPointID but for Digitals. This method is used by an OAS Closed Outage Analysis System to request SCADA digital data on demand for a specific SCADA point. The digital data is used as view-only data by Milsoft.

Sample GetSCADAStatusByScadaPointID request from an OAS:

POST http://MultiSRV/MultiSpeakRealm1/ HTTP/1.1
Connection:Keep-Alive
Content-Type:text/xml; charset=utf-8
Accept:text/*
Authorization:Basic YTph
User-Agent:SOAPWinHTTPClient
SOAPAction:"http://www.multispeak.org/Version_4.1_Release/GetSCADAStatusBySCADAPointID"
Content-Length:1006
Host:MultiSRV

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Header>
    <snp:MultiSpeakMsgHeader xmlns:snp="http://www.multispeak.org/Version_4.1_Release"
                             UserID="" Pwd="" MajorVersion="4" MinorVersion="1"
                             BuildString="Release" Build="6" AppName="Company Software Name"
                             AppVersion="Company Software Version" Company="Company Name" />
  </soap:Header>
  <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <GetSCADAStatusBySCADAPointID xmlns="http://www.multispeak.org/Version_4.1_Release">
      <scadaPointID>pPylU8plF9</scadaPointID>
    </GetSCADAStatusBySCADAPointID>
  </soap:Body>
</soap:Envelope>

Sample GetSCADAStatusByScadaPointID response from VTScada:

HTTP/1.1 200 OK
Date: Mon, 25 Jan 2021 21:14:23 GMT
Server: VTScada 12.0.26
Content-Type: text/xml; charset="utf-8"
Content-Length: 1484
Cache-Control: no-cache, no-store

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
                  xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
                  xmlns:s="http://www.w3.org/2001/XMLSchema"
                  xmlns:s1="cpsm_V4.1_Release"
                  xmlns:s2="gml_V4.1_Release"
                  xmlns:s3="http://www.w3.org/1999/xlink"
                  xmlns:si="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
                  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
                  xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
                  xmlns:tns="http://www.multispeak.org/Version_4.1_Release"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <soapenv:Header>
    <tns:MultiSpeakMsgHeader MajorVersion="4" MinorVersion="1" Build="6" BuildString="Release"
                             AppName="VTScada" AppVersion="12.0026" Company="Trihedral Engineering Ltd."
                             MessageID="09c2a051-4744-4664-b129-a02db0e4f87f"
                             TimeStamp="2021-01-25T21:14:23.894Z" Context="Production" />
  </soapenv:Header>
  <soapenv:Body>
    <tns:GetSCADAStatusBySCADAPointIDResponse>
      <tns:GetSCADAStatusBySCADAPointIDResult objectID="pPylU8plF9" verb="Change">
        <tns:objectName>StatusMom\Status1\Status2\Status3\Status4</tns:objectName>
        <tns:quality>Measured</tns:quality>
        <tns:status>Open</tns:status>
        <tns:timeStamp>2021-01-25T20:07:50.016Z</tns:timeStamp>
      </tns:GetSCADAStatusBySCADAPointIDResult>
   </tns:GetSCADAStatusBySCADAPointIDResponse>
  </soapenv:Body>
</soapenv:Envelope>


SCADAAnalogChangedNotification

The SCADAAnalogChangedNotification method provides a way for VTScada to send to an OAS Closed Outage Analysis System such as Milsoft DisSPatch, notifications of changes in VTScada’s analog tag values. This method can be used to send one or more scadaAnalog data objects for any tags that have data updates.

A sample SCADAAnalogChangedNotification request sent by VTScada. It carries the updates from 5 analog tags.

POST / HTTP/1.1\r\n
SOAPAction: http://www.multispeak.org/Version_4.1_Release/SCADAAnalogChangedNotification
User-Agent: VTScada/12.0.26
Accept-Encoding:gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 2691
Connection: keep-alive
Host: MultiSRV:8083

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
                  xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
                  xmlns:s="http://www.w3.org/2001/XMLSchema"
                  xmlns:s1="cpsm_V4.1_Release"
                  xmlns:s2="gml_V4.1_Release"
                  xmlns:s3="http://www.w3.org/1999/xlink"
                  xmlns:si="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
                  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
                  xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
                  xmlns:tns="http://www.multispeak.org/Version_4.1_Release"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <soapenv:Header>
    <tns:MultiSpeakMsgHeader MajorVersion="4" MinorVersion="1" Build="6"
                             BuildString="Release" AppName="VTScada" AppVersion="12.0026"
                             Company="Trihedral Engineering Ltd."
                             MessageID="b00b93f3-1f87-449f-b10a-f6f3501a2c8c"
                             TimeStamp="2021-01-25T21:42:48.503Z" Context="Production" />
  </soapenv:Header>
  <soapenv:Body>
    <tns:SCADAAnalogChangedNotification>
      <tns:scadaAnalogs soapenc:arrayType="tns:scadaAnalog[5]">
        <tns:scadaAnalog objectID="quywa8lOb5" verb="Change">
          <tns:objectName>CalcMom\Calc1\Calc2\Calc3</tns:objectName>
          <tns:value units="Calc3/Units">8.6602540381562</tns:value>
          <tns:quality>Calculated</tns:quality>
          <tns:timeStamp>2021-01-25T21:42:48.501Z</tns:timeStamp>
        </tns:scadaAnalog>

        <tns:scadaAnalog objectID="cjZaH10iYp" verb="Change">
          <tns:objectName>CalcMom\Calc1\Calc2\Calc3\CalcChildWithaLongName_ABCDEFGHIJKLMNOPQRSTUVWXYZ</tns:objectName>
          <tns:value units="Calc4/Units">5.0000000010801</tns:value>
          <tns:quality>Calculated</tns:quality>
          <tns:timeStamp>2021-01-25T21:42:48.501Z</tns:timeStamp>
        </tns:scadaAnalog>

        <tns:scadaAnalog objectID="i8ho{7gz&amp;p\#}s}143_r;\ke6tuvsd2r" verb="Change">
          <tns:objectName>CalcMom\Calc1\Calc2</tns:objectName>
          <tns:value units="Calc2/Units">9.6592582629714</tns:value>
          <tns:quality>Calculated</tns:quality>
          <tns:timeStamp>2021-01-25T21:42:48.501Z</tns:timeStamp>
        </tns:scadaAnalog>

        <tns:scadaAnalog objectID="i8ho{7gz&amp;p" verb="Change">
          <tns:objectName>CalcMom</tns:objectName>
          <tns:value units="MomUnits">-9.9785892323911</tns:value>
          <tns:quality>Calculated</tns:quality>
          <tns:timeStamp>2021-01-25T21:42:48.501Z</tns:timeStamp>
        </tns:scadaAnalog>

        <tns:scadaAnalog objectID="i8ho{7gz&amp;p\#}s}143_r;" verb="Change">
          <tns:objectName>CalcMom\Calc1</tns:objectName>
          <tns:value units="Calc1/Units">9.9144486137585</tns:value>
          <tns:quality>Calculated</tns:quality>
          <tns:timeStamp>2021-01-25T21:42:48.501Z</tns:timeStamp>
        </tns:scadaAnalog>
      </tns:scadaAnalogs>
    </tns:SCADAAnalogChangedNotification>
  </soapenv:Body>
</soapenv:Envelope>

A sample SCADAAnalogChangedNotification response coming back from an OAS to VTScada. An empty SCADAAnalogChangedNotificationResult (one that has no errorObject content) means notification received successfully.

<?xml version="1.0"" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/>
  <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <snp:SCADAAnalogChangedNotificationResponse xmlns:snp="http://www.multispeak.org/Version_4.1_Release">
       <snp:SCADAAnalogChangedNotificationResult/>
     </snp:SCADAAnalogChangedNotificationResponse>
  </soap:Body>
</soap:Envelope>

A sample ScadaAnalogChangedNotification response coming back from an OAS to VTScada with an error:

<?xml version=""1.0"" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/>"
  <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <snp:SCADAAnalogChangedNotificationResponse xmlns:snp="http://www.multispeak.org/Version_4.1_Release">
      <snp:SCADAAnalogChangedNotificationResult>
        <snp:errorObject errorString="User could not be authenticated." eventTime="2015-01-01T10:00:00Z"/>
      </snp:SCADAAnalogChangedNotificationResult>
    </snp:SCADAAnalogChangedNotificationResponse>
  </soap:Body>
</soap:Envelope>


SCADAStatusChangedNotification

This method is the same as SCADAAnalogChangedNotification, but for statuses (digitals). The SCADAStatusChangedNotification method provides a way for VTScada to send to an OAS Closed Outage Analysis System such as Milsoft DisSPatch™, notifications for changes in VTScada’s status (digital) tag values. This method can be used to send one or more scadaStatus data objects for any tags that have data updates.


Using ODBC

ODBC (Open Data Base Connectivity) is a standard interface to a wide variety of database packages. ODBC drivers are available for most common databases. With the ODBC interface, a VTScada application can be written to store and retrieve data from the database in a format independent of the particular database used. To switch databases, only the driver needs to be changed.

In order to perform ODBC operations, an ODBC driver for the DBMS that you wish to use must be installed on your system and properly configured. Consult your DBMS vendor documentation for details of how to do this.

The program, VTScadaODBCDriverInstall.EXE (distributed with VTS), will install an OBDC driver on your system. This driver is compatible with both 32 and 64 bit Windows versions. The VTScada OBDC driver will allow you to access VTScada tag and alarm history data using SQL queries. Queries may be written with VTScada modules (Function reference: ODBC), or (for those whose license includes the Remote Data option) from 3rd-party reporting tools.

Prior to VTScada version 12, the ODBC driver also enabled you to query tag data using SOAP services. With version 12 and later, the driver uses REST. Those who need to use SOAP can request a copy of the version 11.3 driver. Both may be installed on the same workstation.

To access an ODBC data source, a Data Source Name (DSN) is used. This can be configured using the Microsoft Windows ODBC Data Source Administrator (installed under Control Panel\Administrative tools) or (better) using a file DSN or "DSN-less" connection string.

32-bit ODBC data sources on a 64-bit Windows use the Microsoft Windows ODBC Data Source Administrator located in %systemroot%\SYSWOW64\odbcad32.exe. Consult the online Microsoft documentation for more details.

Related information:

SQL Queries


Protobuf Support

"Protobuf" refers to "protocol buffers". This is a Google® specification for messages that contain serialized, structured data. It is used by several 3rd party tools including Sparkplug B®

The format of the data is typically predetermined and shared prior to the data itself, and can form the basis of protocols. A Protobuf specification consists of one or more messages, which contain fields. There are various field types available (string, double, float, various signed/unsigned integer types). See the proto2 language guide for further details.

Message naming

Where a function takes a Protobuf message name, this is the full name, including the package name. For nested messages this also includes all parent messages. For example, in this Protobuf specification:

syntax = "proto2";
package com.trihedral.protobuf.example;
message Data {
  message SubData {
    required string name = 1;
  }
  required double  double_val  = 1;
  required SubData sub_message = 2;
}

The SubData message would be referred to as com.trihedral.protobuf.example.Data.SubData.

Groups

Decoding and encoding of Protobuf 2 (proto2) groups is not supported.

oneof

Protobuf has a concept, oneof, which defines a set of values where only one is present. If more than one of the values is set when encoding, then the value that is selected to be encoded is undefined.

Decoding of values from a oneof field requires drilling down into the individual field metric component.

Example: For Sparkplug B, the metric message has a oneof field called value consisting of various options such as int_value, boolean_value, string_value, etc. Thus for the following decode statement:

DecodedData = ProtobufDecode(Handle, Msg, EncodedData);

If the returned value is of integer format, then to extract the value, the proper call is DecodedData.int_value, not DecodedData.value. Similarly for encoding, the encoded value needs to be placed into the lower level element of int_value, not the higher level value.

Mapping of Protobuf types to VTScada types

Many data types have a straightforward equivalent. For example float / double in Protobuf is converted to or from a double (#VTypeDouble) and Protobuf byte/string are converted to/from VTScada strings (#VTypeString).

Protobuf repeated fields are converted to or from VTScada arrays, Protobuf maps are converted to or from VTScada dictionaries, and messages are converted to or from VTScada structures. When encoding, any value that can be cast to the target type will be converted.

Performance considerations

Repeatedly parsing a Protobuf specification is a computationally expensive task. If messages of a type are repeatedly encoded and decoded, reusing the handle value from ProtobufParse is recommended. An example of this would be a driver handling Protobuf encoded data.

VTScada's Protobuf API

ProtobufDecode - Decodes Protobuf serialized data.

ProtobufEncode - Creates a buffer for a given Protobuf file containing VTScada value data.

ProtobufInstantiate - Instantiates a message using default values.

ProtobufParse - Load a Protobuf specification from a file.


Using COM in VTS

COM refers to the Windows Component Object Model. This chapter will assist you in COM in VTScada to communicate with other devices. The following terms are used:

Automation Interface

A COM interface that uses late binding.

CLSID Class Identifier

A GUID that represents a COM class

COM Component Object Model

A software architecture that enables the components made by different software vendors to be combined into a variety of applications.

DDE

Direct Data Exchange.

GUID

A Globally Unique Identifier.

OLE

Object Linking and Embedding.

ProgID

Program Identifier. A human-readable form of a class identifier.

SRO

Scope Resolution Operator.

VTable Interface

A COM interface that uses early binding.

Related information:

Com - Functions related to COM


Introduction to COM

This document assumes a basic knowledge of what the Component Object Model (COM) is and how it functions. Introductory information available from Microsoft and others may be helpful if you require more background information on COM.

The Platform SDK documentation is provided with Visual C++, and is available for download from Microsoft. This provides a good starting point for those new to the Component Object Model.

A COM object is a piece of code that exists in an in-process DLL or out-of-process executable file on a computer. The COM object encapsulates a set of behaviors that can only be accessed via a set of formally declared "interfaces". An interface contains a list of member methods (along with their typed parameters), that can be called. All interface methods return a result code of type HRESULT. These interfaces can be classified into two types:

Virtual Table interfaces and Automation interfaces

These two interfaces are described as follows:

VTable Interfaces

VTable or "Virtual Table" interfaces are very closely related to the virtual function table that would be generated for indirectly calling C++ virtual functions. Automation interfaces are defined by Microsoft in their OC96 specification and, essentially, provide a limited set of strongly typed functions that can be called from C++ or other compatible languages. As those functions exist in a VTable interface, knowledge about the function names, calling conventions, and parameter types must be known when the compatible language is compiled. This is termed "early binding".

Automation Interfaces

The early-bound functions of an automation interface, however, provide a mechanism to access a much broader range of methods that the object supports. The calling convention and binding of names to physical functions is performed at run-time, and does not have to be known at compile time. The automation interface mechanism also provides dynamic discovery of parameter type information. Such discovery and subsequent usage of the discovered functions is termed "late binding". These interfaces have largely grown out of the need for scripting languages to use COM objects without requiring compile-time knowledge of the object's methods.

VTScada uses the late binding ability of automation interfaces to interact with a COM object.


Accessing COM Objects

COM defines standard ways to instantiate an object, regardless of the location of the server code that generates the object instance. An object may be instantiated in-process by a DLL server, out-of-process on the same computer by an EXE server, or on another computer that is also an EXE server. Regardless of the object's location and the method of construction, the syntactic constructs to manipulate the object are identical. VTScada script code that constructs such object instances and manipulates them has no knowledge of the object's location.

A COM object may be identified by a "CLSID" (class ID), comprising a 38-character string that consists of an opening curly brace, a 36-character GUID (Globally Unique Identifier), and a trailing closing curly brace.

Each application has its own Globally Unique Identifier (GUID), which is generated by VTScada when the application is created. It can be found in the Information page of the Application Configuration dialog.

Internally, the operating system uses the GUID to look-up instantiation information for the specified object in the system registry. This notation is hardly human-friendly however, and so another translation exists, allowing an object to be identified by a "ProgID" (Program ID). The ProgID is then internally translated into a CLSID by the operating system.

A ProgID is a text string typically identifying a server code for associated objects, along with the identity of the object itself (for example, "TrihedralWidgetServer.Widget2" where "TrihedralWidgetServer" is the server code, and "Widget2" is the object).

The look-up information for such translations and the ultimate identification of the location of the object's server is all contained in the system registry, as such information is normally programmatically stored there during the installation process for the object's server.

To create an instance of a COM object, you may use the COMClient statement. This statement takes a parameter representing the CLSID or ProgID of the object to be created (among other items), and assuming that this identifier does indeed map to a COM object, returns a value that may be assigned to a variable. This variable is an opaque handle, termed the "COM Client Interface" and is the only way to subsequently manipulate the object instance.

Manipulation of the object instance occurs via "properties" and "methods". You can think of properties as being the data that the object holds. The automation interface provides a "property get" ability, and a "property set" ability, to allow the properties contained within the object to be manipulated. The automation interface also provides the ability to call object methods.

The distinction between accessing a property and calling a method can sometimes be blurred. For example, it may be that the object implements a method that simply changes or returns the value of an internal property. Some properties may be parameterized; in other words, setting the property value requires more than one parameter to be passed. The syntactic structure of COM calls in VTScada however, conceals such confusions by providing a set of uniform object manipulation operations, where parameters passed to property manipulations are done in a manner identical to those in a method call.

When using a VTable interface (see Introduction to COM), the set of properties and methods, along with their parameter types, are normally expressed in source code form in a header file. However, automation interfaces had such metadata programmatically generated into a binary file called a "type library" when the object's server was built. The VTScada engine uses the type library's metadata to convert between VTScada values and the target object's expected value types, and to locate the correct property or method within the target object. The VTScada programmer can either use the object's formal documentation or one of the various commercially available "type library browsers" to examine the metadata stored in a type library, and hence, discover the methods and properties that the object supports.

Each property get, property set or method call is described in the type library. Each parameter will be described not only by its type, but will also carry a directional specification such as [in] [out] or [in, out]. The directional specification indicates whether the parameter is an input to the instance ([in]), an output from the instance ([out]) or is both ([in, out]). By specifying a non-constant VTScada variable as a parameter for [out] and [in, out] parameters, the VTScada variable value will be updated at the conclusion of the property or method invocation.


Syntactic Structure

The implementation of COM in VTScada is intended to mimic the natural object model used by VTScada. As mentioned in Accessing COM Objects, opaque handle held in a variable instance that has a ValueType of "COM Client Interface" references an instance of a COM object. VTScada itself does not act as a server for COM objects, rather, it acts merely as a client. In other words, VTScada provides no COM objects. It simply provides the ability to use COM objects.

All properties and methods of the COM object are accessed using the scope resolution operator [SRO] "\". This presents the VTScada programmer with both syntactic and semantic compatibility with existing VTScada objects.

For example, a VTScada module can be instantiated, creating an object instance. The object instance can be scoped into to examine or modify values within the object. An object instance may provide methods that can be invoked. Only the instantiation syntax differs between the same operations, performed on a COM object. This is a necessary departure to describe the parameters necessary to locate an object server and cause it to instantiate an object.

Consider the following code:

[
  MyVTSObject Module;
  VTSObj;
  COMObj;
]
Init [
  If 1 Main;
  [
    { Instantiate a VTScada object }
    VTSObj = MyVTSObject();
    { Instantiate a COM object }
    COMObj = COMClient("Trihedral.Widget");
  ]
]
Main [
]

Firstly, an instance of the VTScada module "MyVTSObject" is instantiated. The object value returned from the instantiation is stored in variable "VTSObj". Next, an instance of the COM object identified by the ProgID "Trihedral.Widget" is instantiated, and the COM Client Interface value is stored in variable called "COMObj".

Suppose that you wish to modify the contents of a value, held in the variable "MyValue" in the VTScada object created above. You could use code such as:

VTSObj\MyValue = 42;

Similarly, if the COM object instantiated in the above code had a property called "MyValue", you would use code such as:

COMObj\MyValue = 42;

This is termed a "property set" operation.

Reading the contents of a value in a VTScada object, or a property in a COM object is also similar:

VTSResult = VTSObj\MyValue;
COMResult = COMObj\MyValue;

For the COM object, this is termed a "property get" operation.

These operations can be combined:

VTSObj\MyValue2 += VTSObj\MyValue;
COMObj\MyValue2 += COMObj\MyValue;

Note that the normal expression operators [+= in this case] can be used just as easily with COM properties as with VTScada values.

An invocation of a method in a COM object is no different from invoking a method of a VTScada object:

VTSObj\MyValue2 = VTSObj\GetSomething(1, 2);
COMObj\MyValue2 = COMObj\GetSomething(1, 2);

In the first of the above two lines of code, a method contained in VTScada object instance is called with two numeric parameters. In the second, the same thing is happening with a COM object.

In the code above, the VTScada object was "launched". A VTScada object will remain running as long as its caller remains running. A COM object will remain running as long as there is a valid reference to it. VTScada objects can, however, be "called" from steady state. In this case, the VTScada object remains running until the state containing the call stops. Even if the VTScada object terminates, it will restart as long as the steady-state call remains running. A similar situation exists with COM objects. If a COM object is called from steady state, it will remain running as long as the steady-state statement remains running. A change of state will stop the COM object, even if there are other references held on it. In other words, the COM Client Interface value returned from the COMClient call is assigned elsewhere. Any variable value holding references to the COM object will be automatically invalidated when the COM object stops:

[
   MyVTSObject Module;
   VTSObj;
   COMObj;
   COMObjName;
]
Init [
   If 1 Main;
   [
      COMObjName = "Trihedral.Widget";
   ]
]
Main [
   { Instantiate a VTScada object }
   VTSObj = MyVTSObject();
   { Instantiate a COM object }
   COMObj = COMClient(COMObjName);
   If Trigger Done;
]
Done [
   { Both the VTScada object and the COM object are now stopped }
]

Like steady-state VTScada object calls, a steady state COM object call will re-trigger if its return value changes or any parameters to it change. In the case of a COM object, the return value would only change if some external event caused the COM object to be lost (e.g. communication failure, or if the parameter(s) to the COMClient statement caused the COM object to be destroyed). In the above code, changing the value of COMObjName would cause the existing COM object to be destroyed, the value of COMObj to be invalidated, and a new COM object to be constructed. After the new object has been constructed, the value of COMObj will change to hold the COM Client Interface value for the new object.

Whether the object is a VTScada object or a COM object, properties and methods may also be accessed in both steady-state statements and scripts, but note that a property get in a steady-state statement will only evaluate once, as, unlike VTScada values, there is no automatic trigger from a COM object that a property value has changed. Instead, COM objects use "events" to indicate changes, and these events may call VTScada subroutines.

Consider the following code:

[
   Changed Module;
   COMObj;
   Latest;
]
Init [
   If 1 Main;
   [
      { Instantiate a COM object }
          COMObj = COMClient("Trihedral.Widget", Invalid, Self(), Self(), Self());
   ]
]
Main [
   If Watch(Valid(Latest), Latest);
   [
      ...
   ]
]
<
Changed
(
   NewValue;
)
ChangedEvent [
   If watch(1);
   [
      Latest = NewValue;
      Return(0);
   ]
]
>

Note that the COMClient statement has grown four extra parameters. The first of these specifies the context in which it is permissible to instantiate the COM object. The second parameter specifies the scope in which event subroutines are to be found. All COM events have a name associated with them, defined by the COM object. If a subroutine module of the same name as the event exists in the scope specified in the third parameter to the COMClient statement, that subroutine will be called each time the corresponding event occurs. The subroutine is called on the same thread as the incoming event from the COM object, and so therefore may occur concurrently with other scripts running in the same scope.

The event subroutine is entered with whatever parameters were supplied by the COM object and the return value is passed back to the COM object as a result code (an HRESULT). Zero is a "success" return value. Each COM object defines what parameters are provided and what it expects the return value to be under different error conditions.

The event subroutine is run in the scope of the parent specified in the fourth parameter of the COMClient statement, therefore, any non-local variables referenced in the subroutine are resolved to values within that scope. In the above example, "Latest" is resolved to the value of "Latest" within the module that made the COMClient instantiation. The fifth parameter specifies the caller scope that is set up for the subroutine invocation. While this is normally meaningless for a subroutine, it can be used to pass "auxiliary" scope to the subroutine, adding flexibility.

The parent and caller parameters are optional, and if not specified, will default to Self(), Self(). The event subroutine search scope parameter is also optional, however, failure to specify a valid search scope, or subsequent invalidation of that parameter, prevents event subroutines from being called. By specifying a variable as the event subroutine search scope parameter, you can enable and disable event subroutine calls, or even move the search scope for them.

The code above, then, uses a COM event to re-trigger the single statement in state Main when the COM object raises a "Changed" event that changes the value of "Latest". This is the primary method by which COM objects cause event-driven processing in VTScada.


Sample Code

The following is a simple working example that reads and writes spreadsheet cells in Microsoft Excel™. Each of the main segments of code in this section can be joined to make a complete script application that will compile and run.

{=========================== System ============================}
{===============================================================}
[
  Graphics Module { Contains user graphics };
  WinTitle = "Excel COM Tester" { Window title };
  System { Provides access to system library functions};
  RunningOnVIC            { TRUE if this is a VIC session           };
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         System\DialogBGnd, 1);
]

<
{====================== System\Graphics ======================}
{ This module handles all of the graphics for the application }
{=============================================================}
Graphics
[
   ExcelObj { The COM interface to the Excel object };
   ProgID { The ProgID for the Excel object };
   RangeObj { The COM interface to a "range of cells" object};
   CellsRead { Result of reading back some cells from Excel };
   CellsWritten { Cell values to be written to Excel };
   Kill = 0 { Gets set non-zero to terminate things };
   Row { Loop counter variable };
   Col { Loop counter variable };
   ValuesText { Text of the values read from spreadsheet };
]
Main [
{***** Instantiate the Excel object...Nothing happens yet *****}
   ExcelObj = COMClient(ProgID);
   {* But when the Excel object does become valid, make it visible ***}
   If Edge(Valid(ExcelObj), 1);
   [
      ExcelObj\Visible = 1;
   ]
   {***** When the Create button is pressed, make the ProgID valid. This causes the COMClient statement, above, to retrigger and ExcelObj to become valid *****}
   If ZButton(10, 30, 90, 10, "Create", 1, System\DefFont);
   [
      ProgID = "Excel.Application";
   ]

Initially, "ExcelObj" will be Invalid. When the "Create" button is pressed, the ProgID is made valid, the COMClient statement re-triggers, and the Excel object is instantiated. On instantiation, the Excel application is run (if not already running), but remains invisible. "ExcelObj" becoming valid causes the second statement to execute, which makes the Excel application window visible. Invisibility is not a general trait of such COM objects, but rather the behavior of Excel. It is possible to leave the Excel application invisible and still use it. You can try this by removing the property set:

ExcelObj\Visible = 1;

The completed application will function identically, but Excel will remain invisible.

The next requirement is code to shut down the COM object. Changing state would be sufficient to release the reference held on Excel and cause it to shutdown, however, Excel will not shutdown automatically if you have modified data within it, so you must make additional method calls to cause this to happen.

{***** Shutdown code. Pressing the "Kill" button stops the object only. Hitting the toaster bar close stops the object and kills this application *****}
If ZButton(110, 30, 190, 10, "Kill", 2, System\DefFont);
[
   Kill = 1;
]
If WindowClose(Self());
[
   Kill = 2;
]
If Kill;
[
   { Close down the Excel workbook and quit Excel }
   ExcelObj\Workbooks(1)\Close(0);
   ExcelObj\Quit();
   { Excel will run until the hold is released}
   ProgID = Invalid;
   { Terminate this application if so instructed }
   IfElse(Kill == 2,
      Slay(ParentObject(Self()), 0);
   { else }
      Kill = 0;
   );
]

In the above code, the variable "Kill" is set to "1" if the "Kill" button is pressed, and is set to "2" if the application is closed. To force Excel to close with modified data, the following two method calls are made on the Excel object:

ExcelObj\Workbooks(1)\Close(0);
ExcelObj\Quit();

Note that this would not be necessary if no changes were made to the data that Excel was operating with, and...

ProgID = Invalid;

...would be sufficient to close Excel. Similarly, a change of state would cause the Excel COM object to shut down. However, the simple application given here has only one state, with the COMClient statement being steady-state, so invalidating the ProgID or terminating the application is the only way to release the object.

The statement above:

ExcelObj\Workbooks(1)\Close(0);

…illustrates the use of "nested" interfaces. "ExcelObj" contains one or more "WorkBook" objects that can be accessed via the WorkBooks() method. For example:

ExcelObj\Workbooks(1);

returns a COM Client Interface to the first workbook. Because the value returned is a COM Client Interface, it can be used to call methods on the object to which it is connected. This can be done either by storing the COM Client Interface in a variable for later use:

WorkBookObj = ExcelObj\Workbooks(1);
WorkBookObj\Close(0);

or by a direct call:

ExcelObj\Workbooks(1)\Close(0);

In the latter case the "Workbooks" COM Client Interface will only exist temporarily - for the duration of statement execution.

The Excel object just instantiated, though, has no "workbook" object. To create one is simply another method call, which is made in response to the user pressing he "Workbook Add" button:

{***** Other buttons...Add a workbook *****}
If ZButton(10, 90, 90, 70, "Workbook Add", Valid(ExcelObj) ? 3 : 0, System\DefFont);
[
   ExcelObj\Workbooks\Add();
]

Excel cells are represented by a "Range" object, which is an interface that can be obtained from the ExcelObj by a simple method call. This is made in response to the "Range Get" button:

{***** Get an object which represents a range of cells *****}
If ZButton(110, 90, 190, 70, "Range Get", Valid(ExcelObj) ? 4 : 0, System\DefFont);
[
   RangeObj = ExcelObj\Range("A1:C1");
]

Assigning values to a range of cells is done by setting the "Value" property of the Range object to the VTScada values that will occupy those cells. Note that you can pass VTScada arrays as well as scalar values to a COM method or property. This is done in response to the user pressing the "Put A1:A3" button:

{***** Set the values of a range of cells *****}
If ZButton(10, 120, 90, 100, "Put A1:A3", Valid(ExcelObj) ? 5 : 0, System\DefFont);
[
   CellsWritten = New(3, 1);
   CellsWritten[0][0] = 11;
   CellsWritten[1][0] = 12;
   CellsWritten[2][0] = 13;
   ExcelObj\Range("A1:A3")\Value = CellsWritten;
]

Similarly, reading back a range of cells is done through the same "Value" property. However, this time the property is used on the right-hand side of the expression, and so is an implicit "property get" rather than the implicit "property put" that resulted from using the property on the left-hand side, above:

{***** Get the values of a range of cells *****}
If ZButton(110, 120, 190, 100, "Get A1:A3", Valid(ExcelObj) ? 6 : 0, System\DefFont);
[
   CellsRead = ExcelObj\Range("A1:A3")\Value;
]

Excel requires that the data supplied to the "Value" property put is dimensioned exactly the same as the range of cells into which the data is being put. Hence, the array dimension used was 3 rows by 1 column. Exactly the same holds true for putting data into multiple columns of the same row. This example places 1 row of 3 columns into the workbook:

{***** Set the values of a range of cells *****}
If ZButton(10, 150, 90, 130, "Put B1:D1", Valid(ExcelObj) ? 7 : 0, System\DefFont);
[
   CellsWritten = New(1, 3);
   CellsWritten[0][0] = 21;
   CellsWritten[0][1] = 22;
   CellsWritten[0][2] = 23;
   ExcelObj\Range("B1:D1")\Value = CellsWritten;
]
{***** Get the values of a range of cells *****}
If ZButton(110, 150, 190, 130, "Get B1:D1", Valid(ExcelObj) ? 8 : 0, System\DefFont);
[
   CellsRead = ExcelObj\Range("B1:D1")\Value;
]

In both cases, the result of the property get is an array dimensioned exactly the same as the cell dimensions.

ZText(210, 117, Concat("Cells Read Dimensions: ," PickValid(ArraySize(CellsRead, 0), "Invalid"),
      " ", PickValid(ArraySize(CellsRead, 1), "Invalid")),
      0, System\DefFont);

Finally, the last code segment renders the values read from the cells into a text string and displays it:

If Watch(1, CellsRead);
[
   Row = 0;
   ValuesText = "Cells Read: ";
   WhileLoop(Row < ArraySize(CellsRead, 0),
      Col = 0;
      WhileLoop(Col < ArraySize(CellsRead, 1),
         ValuesText = Concat(ValuesText, CellsRead[Row][Col], " ");
         Col++;
      );
      Row++;
   );
]
ZText(210, 147, ValuesText, 0, System\DefFont);
]
{ End of System\Graphics }
>

Compiling and running the application will result in the following user interface display:


Using DDE

DDE (Dynamic Data Exchange) is a mechanism within Windows that enables data to be exchanged between two different programs, such as VTScada and Microsoft Excel. The program that supplies the data is called the server, while the program that accepts the data is referred to as the client. VTScada can act as either a client or a server.

DDE can also enable VTScada to accept data from another application, such as a chart, word processing document or spreadsheet. To do so, VTScada uses its DDE Client tag.

The application that supplies the data is called the server, while the program that accepts the data is called the client. VTScada can act as either a DDE client or a DDE server. The sections that follow provide instructions for configuring dynamic data exchange from an outside application to VTScada, and from VTScada to an outside application.

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.

Related information:

VTScada as a Local DDE Client

Use VTScada as a DDE Server

DDE - Functions related to DDE.


TCP/IP Networking

TCP/IP support is integrated into VTScada. To use this feature you will need to have a TCP/IP stack, which is supplied by many network vendors. All TCP/IP functions in VTScada are performed using socket streams that act like serial connections between two programs. VTScada can act as both a socket server and a socket client.

Following is an example of a Client and a Server that will create a connection and pass the string "Hello World" followed by a number representing the number of seconds since midnight.

Client:

[
   Graphics Module { Contains user graphics };
   Calculations Module { Contains user calculations };
   WinTitle = "Socket Test - Client Side" { Window title };
   RunningOnVIC            { TRUE if this is a VIC session              };
   SocketHandle;
   Client;
   Server;
   Data;
]
Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);
]
<
{===================== System\Graphics =======================}
{ This module handles all of the graphics for the application }
{=============================================================}
Graphics
Init [
   If 1 Screen1;
   [
      Client = ClientSocket(0, "Richard", 20000, 1024, 1024, 1);
   ]
]
Screen1 [
   If TimeOut(!Valid(Client), 2) Init;
   If TimeOut(ValueType(Client) <> 8,2) Error;
   If GetStreamLength(Client) > 0 || MatchKeys(2, "r");
   [
      SRead(Client, Concat("%", Concat(GetStreamLength(Client), "c")), Data);
   ]
   If TimeOut(1, 1);
   [
      SWrite(Client, "%s", Concat(" Hello World ", Time(Seconds(), 3)));
   ]
   If MatchKeys(1, " ");
   [
      SWrite(Client, "%s", Concat(" Hello World ", Seconds()));
   ]
   ZText(10, 150, Data, 15, 0);
   ZText(200, 100, Cond(Valid(Client),"Connected", "Not Connected"), 10, 0);
   ZText(200, 110, Concat("ErrorCode : ", Client), 10, 0);
   ZText(200, 120, Concat("Type : ", ValueType(Client)), 10, 0);
   If WindowClose(Self());
   [
      CloseStream(Client);
      Slay(Self(), 1);
   ]
]
Error [
   ZText(100, 130, Concat("ErrorCode : ", Client), 10, 0);
]
{ End of System\Graphics }
>

Server:

[
   Graphics Module { Contains user graphics };
   Calculations Module { Contains user calculations };
   WinTitle = "Socket Test - Server Side" { Window title };
   RunningOnVIC            { TRUE if this is a VIC session              };
   SocketHandle;
   Client;
   Server;
   Data;
   Attribs0;
   Attribs1;
]
Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);
]
<
{===================== System\Graphics =======================}
{ This module handles all of the graphics for the application }
{=============================================================}
Graphics
Init [
   If 1 Wait ;
   [
      SocketHandle = SocketServerStart(0, 20000, 1024, 1024, 1);
   ]
]
Wait [
   If SocketWait(SocketHandle) Main;
   [
      Server = ServerSocket(SocketHandle);
   ]
]
Main [
   If GetStreamLength(Server) > 0 || MatchKeys(2, "r");
   [
      SRead(Server, Concat("%", Concat(GetStreamLength(Server), "c")), Data);
      SWrite(Server, "%s", Data);
   ]
   If WindowClose(Self);
   [
      CloseStream(Server);
      SocketServerEnd(SocketHandle);
      Slay(Self(), 1);
   ]
   ZText(0, 50, Data, 15, 0);
   ZText(0, 100, Cond(Valid(Server), "Connected", "Not Connected"), 10, 0);
]
{ End of System\Graphics }
>

Related Functions:

BlockWrite

ClientSocket

ServerSocket

SocketServerStart

SocketServerEnd

SocketWait

SRead

SWrite


SNMP Agent Configuration

The SNMP agent is not enabled by default. You must enable and configure the agent before using. All of the application properties listed at the end of this topic should be reviewed.

When configured, you will be able to serve tag values over SNMP. An SNMP client will be able to connect to the server to read from or write to tags configured for SNMP access. The following features are available:

  • Access to VTScada tag values via SNMP GetRequest commands.
  • Ability to set VTScada tag values via SNMP SetRequest commands.
  • Ability to send Trap/InformRequest notification to the NMS Closed Network Management System when tag values change.
  • Paired with an SNMPGetBulkDistributor Tag, ability to poll GetBulk requests.
  • Support multiple simultaneous client connections.
  • The address (OID Closed Object IDentifier. A part of the SNMP driver addressing system.) assigned to a tag is retained and existing address bindings do not change when regenerating or updating the MIB Closed Management Information Base. A hierarchy of the information available to an SNMP device, organized by numbered Object Identifiers (OIDs)..
  • You can export the SNMP Agent configuration as a MIB file, allowing VTScada settings to be imported into a 3rd party system.
  • The enterprise Private Enterprise Number (PEN) may be customized.
  • The community names are configurable.

Look for SNMP configuration in the Other Tab of the Edit Properties Page. There, the SNMP version must be set to v3 for all options to be displayed.

Do not allow write access over an unsecured network. Community strings are plain-text passwords.

VTScada supports only ASCII-encoded MIB files.

To enable the SNMP agent:

  1. Open the Edit Properties page within the Application Configuration dialog.
  2. Select the Advanced Mode option.
  3. Locate the property SNMPAgentEnable.
    This will be an OEM property, unless previously configured in your application. If so, you must copy the property to your application before you can change the value.
  4. Set the value of the local copy of SNMPAgentEnable to 1.
  5. Save and apply changes.

The SNMP Agent requires IP Network Listener Tags to provide access to the system. That tag provides features such as IP filtering and connection audit logs. The IP Network Listener tag must be configured with the name specified in the application property, SNMPAgentIPListener .

  1. Locate the property, SNMPAgentIPListener.
  2. Make note of the value of that property.
  3. Ensure that you have an IP Network Listener tag located at the top level of the tag hierarchy, and having a name that is identical to the value shown in the property, SNMPAgentIPListener.

Related information:

Service enabling properties:

SNMPAgentEnable

SNMPAgentReadCommunity

SNMPAgentWriteCommunity

SNMPAgentWriteEnable

SNMPAgentIPListener

Advanced communication properties:

SNMPAgentMaxTCPSize

SNMPAgentMaxUDPSize

SNMPAgentSessionTimeout

Trap configuration properties:

SNMPAgentTrapCommunity

SNMPAgentTrapHost

SNMPAgentTrapPort

SNMPAgentTagNotifyMode

Properties used only to inform traps:

SNMPAgentInformRetryInterval

SNMPAgentInformRetryLimit


MIB Objects

The VTScada SNMP Agent implements MIB-II, which is a basic object available on most SNMP agent devices. (See: RFC 1907 - Management Information Base for SNMPv2)

This provides certain basic objects such as the device identification and message processor success and error counts. VTScada fully implements MIB-II as per compliance requirements.

Custom objects implemented by the VTScada SNMP Agent are located under the VTScada OID (1.3.6.1.4.1.42905.1). The top level nodes of the product are as follows:

appTraps(0) | definitions for custom trap types (not accessible)
appInfo(1) | application server information such as application name and memory usage
appNotifyInfo(2) | Notification subsystem information variables
appTags(3) | Contains all the tags configured for use with the SNMP Agent


Agent Tag Setup

By default there will be no tags available in the agent MIB, only basic service variables. Tag setup requires a manual action to initiate. In particular, the property, SNMPAgentEnable must be set to 1 before proceeding.

  1. Open the Idea Studio.
  2. Within the Widgets palette, open the Tools folder.
  3. Open the SNMP Agent Tools folder
  4. Add the 'SNMP Agent' button to your page.

The SNMP Agent button has only one configurable property: the name to display on the button.

  5. Close the Idea Studio.

Running the SNMP Agent:

  1. Click the SNMP button.
    The SNMP Agent Setup dialog will open.

There are two options: Generate New and Update Existing.

  1. Generate New will reset prior OID address assignments
  2. Update Existing will retain prior OID address assignments
    (Either way the SNMP Agent will be updated to the current VTScada tag configuration)

Select the desired option and then choose a location in which to save the exported MIB file.

Only OPC-enabled tags can be made available via the SNMP Agent. The update process automatically includes all OPC-enabled tags running in the application.

  • OID addresses are assigned to tags and are retained until explicitly reset.
  • Every available tag will have the following fields: { Name, Value, Quality, Timestamp, Type }
  • SNMP data type and access level for Value are determined via the OPCGetTagAttributes() API.
  • A subset of the values from OPCGetTagProperties() populate the optional fields: { Description, Area, Units, Device, Address }
  • SNMP Get commands use the OPCReadTagValue() API to access the Value, Quality, and Timestamp.
  • SNMP Set commands use the OPCWriteTagValue() API to set the Value.

See the OPC setup guide for OPC API function implementation.

subsequent tag configuration changes will not be included until the next time MIB Setup is executed.


Agent Tag Fields

The following set of fields are potentially available for every OPC-enabled tag. A subset can be defined using SNMPAgentTagExposedProperties.

  • Name - The full VTScada tag name
  • Value - Value if the tag if Quality is good
  • Quality - quality of the tag Value, as follows:
    • Bad (0)
    • Configuration Error (4)
    • Uncertain (64)
    • Engineering units exceed low limit (85)
    • Engineering units exceed high limit (86)
    • Good (192)
    • Good with manual override (216)
  • Timestamp - UTC timestamp associated with the tag
  • Type - Name of the tag type
  • Description - Description of the tag
  • Area - Area of the tag
  • Units - Engineering units associated with the tag value
  • Device - Name of the associated I/O device tag
  • Address - I/O device address associated with this tag

Except for Value, all fields are read-only.

Quality values 85 and 86 will occur only for VTScada tags that map to 32-bit integers, such as the Counter tag.


Trihedral MIB Definition

The exported VTScada SNMP Agent MIB is defined under the Trihedral enterprise. Most management software will require the Trihedral MIB definition to process the VTScada MIB.

The Trihedral enterprise MIB definition:

TRIHEDRAL-MIB DEFINITIONS ::= BEGIN

IMPORTS
         MODULE-IDENTITY, enterprises FROM SNMPv2-SMI;

trihedral MODULE-IDENTITY
    LAST-UPDATED "201312020000Z"
    ORGANIZATION "www.trihedral.com"
    CONTACT-INFO ""
    DESCRIPTION  "Trihedral Engineering Ltd."
    REVISION     "201312020000Z"
    DESCRIPTION  "First draft"
    ::= { enterprises 42905 }

END

A copy of this definition is present in the installation directory under Mibs\TRIHEDRAL-MIB.txt


Agent Tag Change Notification Traps

The SNMP Agent provides a custom trap type for sending tag change notifications to the management server. IO tags will automatically publish via SNMP when Destination tags are specified. Custom code is required to send a change notification, but this can be done from a simple child tag that watches the parent value, or from an application service module. This provides maximum flexibility as to when and how the notifications are sent.

\SNMPAgent\NotifyTagChange

Description: | Sends a notifyTagChange trap to the configured trap destination.
Returns: | Boolean error indication.
Usage: | Subroutine
Format: | SNMPAgent\NotifyTagChange(TagName[, NeedAck, Fields])
Parameters: |
TagName
Required. Name of the tag to send the notification for
NeedAck
Optional. Any Boolean expression. Set TRUE if acknowledge is required or FALSE to send unacknowledged trap. Defaults to FALSE.
Fields
Optional. An array of field names to send in trap/inform PDU. Defaults to (Timestamp, Value, Quality). See available field names under Agent Tag Fields.
Comments:

This sends a notifyTagChange trap to the configured trap destination. By default the SNMP Agent notification subsystem will only send notification from the current server.
The option SNMPAgentTagNotifyMode can adjust this behavior as needed. The name of the RPC service for notifications is "SNMP Agent Notifications", which can be configured like any other VTScada RPC service.

If the SNMP Agent Notifications service server changes then a notifyServerChange trap will be sent from the new server. The management system can choose to poll for the current tag values whenever this occurs, as notifications may have been missed during the transition period.

The following custom appNotifyInfo MIB objects also provide some useful information.

  • notifyServer(1) - 1 if this is the current notification server
  • notifyFailCount(2) - count of notifications that did not receive an acknowledge (after retries).
  • lastNotifyFailUTC(3) - UTC timestamp of the last notifyFailCount

A management system relying on notifyTagChange notifications to keep values updated should keep an eye on the fail statistics, polling for current tag values whenever synchronization has been lost as indicated by an increase in the fail count.


Custom MIB Setup

The option exists to configure the SNMP Agent MIB to produce an OEM MIB rather than the standard VTSCADA MIB. The primary setting to enable this is:

SNMPAgentOEMSetup

This is a string of the form "enterprise(PEN).product(number)". (For example: "acme(696).rocketApp(1)").

The enterprise and PEN must match what is defined in the enterprise MIB file. After this setting is specified you must include the following to generate a functional MIB file:

SNMPAgentOEMEnterpriseMIBModule

Enterprise MIB module name for exported MIB file (e.g. "ACME-MIB"). Must match the enterprise MIB file module declaration.

SNMPAgentOEMProductMIBModule

Product MIB module name for exported MIB file (e.g. "ROCKET-APP-MIB")

The MIB subsystem will create a custom MIB based on these settings. Note that the enterprise MIB file will have to be supplied to the end user in order for the custom product MIB to be of use. However, the VTScada SNMP Agent does not need the actual enterprise MIB module to function.

The header of the generated MIB file will contain the following fields. Definitions for these are optional.

SNMPAgentOEMOrganization

(string) Organization for exported MIB file

SNMPAgentOEMContactInfo

(string) Contact Information for exported MIB file

SNMPAgentOEMDescription

(string) Product description for exported MIB file

In order for the custom parameters to be SMIv2 compliant, the following rules must be observed,

  1. MIB Module names:
  • Must begin with UPPER case letter, followed by zero or more letters, digits, and hyphens
  • Hyphen cannot be last, and there cannot be two consecutive hyphens
  2. SNMPAgentOEMProduct setting names:
  • Must begin with LOWER case letter, followed by zero or more letters and digits
  • Have no hyphens


VTScada Agent MIB Representation and Manipulation

Prior to version 12.1, the internal MIB configuration of tags was persisted in an XML file. This proved to require heavy processing for large MIBs.

It is now persisted within a valid JSON file containing an array of JSON objects, where each tag is represented by a single JSON string (or object). The JSON file is processed one line (object) at a time and is not loaded in its entirety. JSON formatting tools may be used to verify the validity of the data in the file.

The file may be modified as explained in the following notes, so long as the format of the file respects three rules:

  • The first line is always (and only) an opening square bracket: [

  • The last line is always (and only) a closing square bracket: ]

  • Between the first and last lines, each JSON object representing a tag must be on a single line.
    The file is processed line by line, assuming that a JSON object occupies a single line.

Backward compatibility support:

If an XML configuration file exists when an application is launched, that file is read, an internal configuration is generated, and then immediately written to a JSON configuration file. Following this, the XML file is deleted. If the XML file causes any error reports at loading, no internal configuration is generated, no JSON file is generated, and the XML file is not deleted.

Problems in the XML file must be fixed and the application restarted (or the agent disabled then enabled). Note that extremely large XML files may cause a freeze or crash. These must be deleted and a new JSON file created by triggering the generation of a new MIB.

Manipulation of the MIB:

MIB files are generated and persisted as a JSON file for all OPC-enabled tags. For each tag, the properties to be exposed via SNMP are set via the application configuration property, SNMPAgentTagExposedProperties.

It is possible to manipulate the MIB manually by editing the JSON file and the generated MIB file in parallel (Both must be edited simultaneously so that the change in the MIB file is reflected in the internal MIB.)

For example assume you have three I/O tags (IO1, IO2, IO3). Assume also that you set "SNMPAgentTagExposedProperties" to the CSV template: "name,value,timestamp". This means that you want to expose only name, value, and timestamp via the SNMPAgent. After pressing the button, Generate New MIB you will get the following:

[
{"id":"io1","TagName":"IO1","SubId":1,"DataType":"DisplayString","Access":"read-only","TagFields":[{"field":"name","id":"io1Name"},{"field":"value","id":"io1Value"},{"field":"timestamp","id":"io1Timestamp"}]},
{"id":"io2","TagName":"IO2","SubId":2,"DataType":"DisplayString","Access":"read-only","TagFields":[{"field":"name","id":"io2Name"},{"field":"value","id":"io2Value"},{"field":"timestamp","id":"io2Timestamp"}]},
{"id":"io3","TagName":"IO3","SubId":3,"DataType":"DisplayString","Access":"read-only","TagFields":[{"field":"name","id":"io3Name"},{"field":"value","id":"io3Value"},{"field":"timestamp","id":"io3Timestamp"}]}
]

The main part of the MIB related to the tags will look like the following:

-- Application tags
appTags OBJECT IDENTIFIER ::= { vtscada 3 }
io1 OBJECT IDENTIFIER ::= { appTags 1 }
io1Name OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"Name of the tag for discovery"
::= { io1 1 }
io1Value OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"Value of the tag if quality is good"
::= { io1 2 }
io1Timestamp OBJECT-TYPE
SYNTAX Unsigned32
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"UTC timestamp associated with the tag value (POSIX time)"
::= { io1 4 }
io2 OBJECT IDENTIFIER ::= { appTags 2 }
io2Name OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"Name of the tag for discovery"
::= { io2 1 }
io2Value OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"Value of the tag if quality is good"
::= { io2 2 }
io2Timestamp OBJECT-TYPE
SYNTAX Unsigned32
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"UTC timestamp associated with the tag value (POSIX time)"
::= { io2 4 }
io3 OBJECT IDENTIFIER ::= { appTags 3 }
io3Name OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"Name of the tag for discovery"
::= { io3 1 }
io3Value OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"Value of the tag if quality is good"
::= { io3 2 }
io3Timestamp OBJECT-TYPE
SYNTAX Unsigned32
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"UTC timestamp associated with the tag value (POSIX time)"
::= { io3 4 }
END

Suppose that you decide not to expose the timestamp for IO1. Then you can make the following edit:

  1. In the MIB file remove the following OBJECT-TYPE definition:

io1Timestamp OBJECT-TYPE
SYNTAX Unsigned32
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"UTC timestamp associated with the tag value (POSIX time)"
::= { io1 4 }

  2. In the file, SNMPAgentConfig.JSON, remove the timestamp member for IO1
    Do so by removing: {"field":"timestamp","id":"io1Timestamp"}. The JSON file would look like the following:

[
{"id":"io1","TagName":"IO1","SubId":1,"DataType":"DisplayString","Access":"read-only","TagFields":[{"field":"name","id":"io1Name"},{"field":"value","id":"io1Value"}]},
{"id":"io2","TagName":"IO2","SubId":2,"DataType":"DisplayString","Access":"read-only","TagFields":[{"field":"name","id":"io2Name"},{"field":"value","id":"io2Value"},{"field":"timestamp","id":"io2Timestamp"}]},
{"id":"io3","TagName":"IO3","SubId":3,"DataType":"DisplayString","Access":"read-only","TagFields":[{"field":"name","id":"io3Name"},{"field":"value","id":"io3Value"},{"field":"timestamp","id":"io3Timestamp"}]}
]

Note that step 2 is mandatory in order for IO1's timestamp to be removed from the internal MIB.

  3. Import file changes for the app.
    The internal MIB would look like this in the Source Debugger, notice how there is no more entry for the IO1 timestamp. So now a read for the object a OID 1.3.6.1.4.1.42905.1.3.1.4.0 will fail.

Cautions:

  • If the XML contains an error, it must be fixed or no MIB will exist in the app.

  • If an application configuration is changed (for example I/O tags added or removed) and a Generate New MIB is triggered, there is no guarantee that the I/Os will preserve the same OIDs.


Support for Analog Tag Values

Standard SNMP does not define a floating point data type. To provide this values over SNMP, without truncating to integers, the floating point numbers are encoded as strings by default.

For example, 1234.567 is returned as a DisplayString with value "1234.567".

Tags with integer values are encouraged to report their type as integer rather than a floating point to avoid such issues.


Support for Data Time Stamps

The timestamps (type: timeticks) provided by SNMP are based on sysUpTime (see MIB-II), which is relative to the device restart rather than any useful epoch. Further, sysUpTime will roll over eventually.

To provide for tag values, and other useful timestamps, the SNMP Agent encodes timestamps in type Unsigned32 as the number of seconds since midnight of January 1, 1970 (where "midnight" is 00:00). By convention all timestamps will be in UTC.


Using DLLs

DLLs are dynamic link libraries. They are the primary means for accessing C code functions from VTScada. With the DLL statement, you can access existing DLLs or access your own DLL used to create some specialty function. To create a DLL you will need a programming language compiler for a language such as C.

Related Functions:

DLL

LoadDLL


Data Diode Support

VTScada can replicate the historian across Data Diode.

Your Data Diode configuration may resemble the above diagram. The publishing tags and widgets belong in a secured network. The data is transmitted out, to a client tag on the receiving application. There is no means to transmit data into the secured network, effectively isolating it.

A Data Diode configuration requires two VTScada applications, one app on the secured network (publishing side), and one on an external network (client side).

Tag Setup

The app on the secure network must have:

  • A Data Diode Publisher tag with a configured TCP/IP Address and Port Number.

  • At least one Historian tag linked to the Publisher tag.

  • I/O tags linked to the Historian tag(s), generating the data to be transmitted.

The app on the external network must have:

  • A Data Diode Client tag with a configured TCP/IP Port Number.

  • At least one Historian tag linked to the Client tag.

  • I/O tags matching the publishing application configuration.

The Historian tag(s) and any tags being published to the historian tags must be present in both applications and have identical Unique IDs.
Without identical counterparts, incoming data will not display friendly names and you will not be able to plot it to a Historical Data Viewer.
The easiest way to do this is to create the publishing application, copy it and reconfigure the copy to use as the client application.

To use a copy of an application on the client machine, you will need to:

1. Insert a customized workstation-specific setting in the application configuration menu, as described in the Data Diode Publisher tag and Data Diode Client tag sections. This setting links the Historian tag(s) to the Publisher tag on each machine in the Data Diode Publisher tag’s server list.

2. Set the start condition of the Data Diode Publisher tag to make it only enabled on its potential servers. e.g. the start condition can be WKStaInfo(0) == DDPServerMachineName1 || WKStaInfo(0) == DDPServerMachineName2 || .. || WKStaInfo(0) == DDPServerMachineNameN.

3. Repeat the above steps for the Data Diode Client tag.

Any number of Historian tags can connect to the same Data Diode Publisher tag and Data Diode Client tag.

Server Setup

  • The publishing app must be the primary server for the Data Diode Publisher tag and the client app must be the primary server for the Data Diode Client tag.

  • The server list of the Data Diode Publisher tag must be a subset of the server list of the Historian tags. (ie. it cannot include machines that are not in the Historian tag's server list.)

  • There can only be one client server; the server list of the Data Diode Client tag can only contain one machine. If you want to switch to a new machine you must reconfigure the server list to only have the new machine in it and then update the IP address and port number in the Data Diode.

  • You may have a multi-publishing server setup. If the primary publishing server went down, the secondary publishing server would continue to send form where the primary server left off.

To optimize performance it is a best practice to set up the publishing app in such a way that the Data Diode Publisher tag has a dedicated primary server and the historian has a separate dedicated server. Writing to the Historian is a resource-heavy process and having it on a dedicated machine will improve the efficiency of the whole system.
This configuration is not essential but would benefit large-scale systems that produce a lot of history data. This would mean there are at least two servers on the publishing side, apart from any redundancy you may also have.

Security Considerations for your Data Diode Configuration

It is your responsibility to ensure the security of the connections between VTScada and the Data Diode Device.

We strongly recommend your IT department set firewall rules for the port used by the Data Diode Client tag to ensure it only accepts connections from the Data Diode device.

Operation and Monitoring

There is no way for the operator of the client application to communicate back up stream to the publishing application. The appeal of Data Diode is that there is no means of entry. Operators of the publishing application can start transmissions from where they left off, start from a specific date and time, reset the publisher and start from the earliest Historian entry, and stop transmission.

The status of the Historian tags can be monitored, from both ends, through the Historian Status widget. It is recommended that the Client Application use a Sync Indicator widget paired with a Comm Indicator widget to monitor the status of incoming transmissions.

If the server fails on the client app, there is no way for the publishing app to detect it. It will continue transmitting data until the publishing application stops or an operator intervenes. Once the server issues on the client side are resolved, you can back-track by using the Start from Date/Time button to start retransmitting from the date of the last successful transmission.

Start from Date/Time (UTC) will retransmit the data that was transmitted by the Data Diode Publisher from that date/time. It does not retransmit data from that date/time in the Historian.
For example-- If operations were halted on September 10th and resumed on September 20th, then when Data Diode Publisher begins transmitting on September 20th it will start at the first Historian entry after the last one it sent (on September 10th), catch all the way up to the present and continue to transmit new data as it becomes available. If on September 30th you retransmit data from September 20th using Start from Date/Time, the transmission will include all Historian entries from September 10th because those were transmitted by the Publisher on September 20th.

To learn more about Data Diode widgets, see Data Diode Widgets

Normal Sync

On the publishing side, data goes from the I/O tags → Historian → Data Diode Publisher. When data is written to the historian tag, the new records are queued into chunks of data for transmission and tracked from historian to publishing. VTScada keeps track of the last known record published to the Data Diode. As long as a transmission is in progress, new data will flow down this path to the Data Diode Publisher to be published to the Data Diode Client.

The Data Diode Client communicates with the Client Application. On this side, data goes from the Data Diode Client → Historian. The Data Diode Client tag listens at the port and sends data to the Historian for further processing. Tags that share unique IDs in both applications will display friendly names and may be plotted on a Historical Data Viewer. The transmitted data is written to the local storage.

If some records are not what we expected to receive (for example, if they arrive out of order or there are missing chunks) the user would be alerted by the Sync Status Indicator Widget.

The historian will keep a limited amount of transmitted data in memory in case the disordered or missing files are a temporary problem to reduce instances of false alarms.

Bulk Sync

The transmission of data can be manually stopped (with a Data Diode Publisher Stop button) or unintentionally halted in the event of a failover of the publisher server. New data accumulates. When the transmission starts again, it will pick up at the last known transmission and undergo a Bulk Sync process to transmit all outstanding data. From there, data will continue to transmit live.

Bulk Sync can be triggered by using the start button if data has accumulated since sync last stopped and is also triggered if the Start from Date/Time button is used in the publishing application. Start from Date/Time prompts the user to select a date and time (UTC) and will transmit all data from that point to present and then continue to transmit live data.

A Bulk Sync sends a much higher volume of data than typical live publishing. To mitigate any potential fallout should the Bulk Sync be disrupted, a separate Bulk Sync file is saved every hour during the potentially lengthy process. This is intended to minimize the time it would take to restore lost data.

Publish all Available Historical Data

To start publishing from the earliest Historian entry, you can go to the settings tab of the Data Diode Publisher tag properties dialog and click "Reset Published State". You will be prompted to make sure this is your desired action.

Start from Date/Time depends on historical information that will be erased if the published state is reset in the publisher tag property settings. If you select reset published state you cannot skip ahead to the end by trying to start from a more recent date. You will have to let the bulk sync process complete.

Note that Historian tags on the publishing application can be configured to delete data after a specified amount of time has elapsed. In this case, the earliest historian entry will only be as old as the specified time.

Also note that the Historian tags on the client application cannot be configured to delete data after a specified amount of time. The tag will still take a value but the setting will not affect information recieved and stored from Data Diode. The Historian tag on the client application only saves what it receives from the Data Diode Client tag to the local datastore. It cannot create or delete data.

How Does Data Diode Check for Missing Data?

A packet of information is sent from the publishing application to the client application at regular intervals and at the end of a bulk sync. This transmission provides the client application with enough information to check the state of the received transmissions. If the information from the publisher doesn't align with the information received from the client, the Sync Status Indicator widget will show an error, the timestamp (UTC) of the error and the last known in-sync transmission. New information is sent, received and compared at regular intervals until the check is passed and the Sync Status Indicator widget will return to normal, displaying "In Sync"

Related information:

Data Diode Client Tag

Data Diode Publisher Tag

TCP/IP Port Tags

Historian Tags

Data Diode Start Button Widget

Data Diode Start From Date/Time Button

Data Diode Stop Button Widget

Data Diode Publisher Statistics Dialog

Sync Status Indicator Widget

Comm Indicator Widget

Data Diode Client Statistics Dialog

History Stats Value Widget


Design Your Own Tags

"Alarm", "I/O and Calculation", "Counter" are examples of tag types supplied with VTScada. You can easily create your own types to join this list, such as "LiftStation", "Generator" etc. Each one of your new types may contain as many child tags as required to describe the matching equipment.

To create a new type of tag, start with a Context tag. Any Context tag with a legal word in the Type field can be turned into a new type template. All child tags of that Context will be included in the new template. The Type property value becomes the name of the new type. Within your application (and any applications that use this one as an OEM layer), the new type will be available alongside the standard tag types.

The following images illustrate the process.

Step 1: Create a Context with a Type property.
Add all the relevant child tags.

Name the type something that you can guarantee will be unique to your application. One way to do this is use compound words like AceCustomPump.
An error message will be displayed if the type name cannot be used.

Step 2: Create New Type

Step 3: Your custom type is now available when adding new tags.

New copies of your custom type can be created as easily as any standard VTScada tag type. If the type definition includes child tags, as is normally the case, then those will be created at the same time. Note that you can build on this by creating your own widgets that display all the child tags in one object.

Plan ahead and do less work later.

Before following the steps just described, take time to build the tag so that as much work as possible is done once and never needs to be repeated. For example, configuration fields in the child tags can and should use parameter expressions (that you create) so that they will be configured automatically using information from the parent tag.
When adding new instances of your custom tag type, developers should only need to configure the parent type. All child tags should be configured automatically using parameter expressions. The expression can be complex, or it can be as simple as copying a value from the parent tag to the child. The goal is to keep all of the configuration in one place / tag.

If some child tags will not be needed in every instance of the type, then use Start Tag expressions. These are similar to parameter expressions, but are stored in the tag's name field and control whether the tag will be enabled or disabled. For example, in a lift station that can have up to three pumps, all three will exist in the type definition, but two will be controlled by Start Tag expressions and be enabled only according to the number of pumps configured in the parent station.

If there's a chance that you will want to use the new type in other applications, build the type in an OEM layer below your application rather than directly in the application. It's much easier to distribute feature updates via OEM layers than to export tag types. (Reusable Application Layers)

Custom configuration

Some (not all!) configuration properties that relate to tags can be inherited from a parent tag instead of using global settings from the Application Configuration dialog. For example, you can have Roster and Alarm tags with their own delays and call-out priority settings. Alarm message templates can be designed that differ from one part of the application to another. Drivers can have differing configuration if (for example) you have some Modbus devices whose addressing begins at 0 and others whose addressing begins at 1. (ModiconTypedAddr1Offset)

Improve the design

You can modify the design of the new type by making changes to one instance, then issuing an "Redefine Type" command on it in the Tag Browser. For example, you might add a Context tag having two child tags: an Analog Input, and a Logger storing the Input's data. Later you decide to add an Alarm to the structure. By running a Redefine Type command, all new and existing instances of that type in the current application will include those child tags.

Never redefine a working instance of your custom type. Always create a temporary copy to modify, then run redefine on that. This avoids the danger of having local overrides become part of the type definition, changing all existing and new instances.

Context (Site) Tags and Alarm Notification

Context tags (or custom types derived from a Context tag) may define custom alarm message templates, for use by all alarms occurring within the structure. This is done by adding the desired template name(s) to the Context's list of properties. To create a custom property value that will be dynamic and unique for each instance, use tokens. A token will be replaced by the meaning it represents. All non-token characters will be passed along as a string. (To pass a percent sign as part of a string you must type %%)

A custom template with a value of:

Check: %D%T - %A - %M

will output a message like:

"Check: [Date][Time] - [Area] - [Alarm description]"

You cannot pass an expression in the value field of a Context tag's custom property. To do this, you must create a custom tag type. See Alarm Notification Templates for more detailed instructions.


Add Properties to Context Tags

In nearly all cases, the Context tag that will form the basis of your new type definition will hold a set of properties relevant to that new type. These can serve many purposes, as follows:

Site Properties

Properties after clicking Add Site Properties

All Context tags and user-defined types based on Context tags will be included in Site Lists, whether you add these properties or not. But, you must add Latitude and Longitude properties before the tag can be drawn on a map and other site properties before you can set configuration options such as excluding the tag from a Site List or setting a custom details page or map icon.

Connector Properties

If you want to represent a pipe, power line, or other conduit between two sites use the Add Connector Properties button.

Properties after clicking Add Connector Properties

Connectors link to sites that you create with latitude and longitude properties, and are drawn on a map as a straight line with arrows. Use Connectors when the connection between two sites is monitored by I/O. You would not use a Connector when all that's needed is a line between two points.

Custom Properties

You can add any properties that you want to a Context tag for use in your custom type. There is no limit, although a long list may become difficult to use. These properties may hold all the information required to fully describe the site or object. Child tags can use tag parameter expressions to inherit any of these properties for use in their own configuration. As stated earlier, it should rarely be necessary to configure any child tag of a custom type. All typical configuration should be done only in the parent tag of the structure. This may mean duplicating properties from the children in the parent.

Adding a property to a Context tag

The option to specify that the value is translatable text is important. If selected, whatever you type will be stored in the languages file as a new phrase, and the matching phrase key will be stored in the parameter. Do not select for any value that must be used as-is, such as an I/O address.

After the context is turned into a type, the panel shown in the following figure will change. The overall appearance will resemble the ID tab, but with an entry for every property. (A scroll bar is provided if needed.) The Property Name will vanish, replaced by the Comment, which becomes the title for the field. Values can be edited in exactly the same way that Description and Help ID properties can be edited on the ID tab. Those who learn the VTScada programming language can redesign the properties dialog as they like, noting that after doing so the tag will be counted against the number permitted by your license.

Assorted custom properties


Automated Tag Configuration

Any parameter(*) of a tag can be configured using an expression rather than a static value. This is an extremely powerful feature that you can use to create tags that configure themselves based on where they are placed in the application. Also use it for tags that rely on data from the remote device for their configuration.

(*) The name parameter works differently. An expression here can be used to enable or disable the tag, but cannot change the name.

dynamic, dynamic, dynamic, dynamic

If you have created a tag as a child of another tag, then you have seen this feature in action. The Area field of every new tag will copy the parent tag's area unless you apply an override to set a new value. If you move or copy a tag to a new parent, its area field will change to match the new parent. The expressions described here are most effective when used in parent-child tag structures, where they can use information stored in an ancestor.

When using expressions for parameters, it is up to you to ensure that the result is valid and that it makes sense for the parameter. For example, an I/O address of either INVALID or "Hello World" is unlikely to produce a desired result.

Before writing your first parameter expressions, review the notes in the chapter, Expressions. In particular, take note of the advice in the topic, Keep the Else's under control !

Identify Parameters with Expressions:

  • Parameter fields that contain expressions can be identified by their blue shading.
  • If you override an expression with a new value, the field will have a yellow shading.

"FmoocKh", in this application, is the key for a parameterized phrase:
"Primary pump in the %0 region".
"EU43y4gag" will not exist as a key in your application.

The context menu that appears when you right-click on a tag's configuration field will vary according to what the field is and how it was created.

Create, Edit, Remove, or Override an Expression

For all of the these actions, right-click on the parameter in the tag's configuration dialog. Your choices will vary depending on whether you add the expression to the name parameter (start conditions only), area parameter (which can inherit from its parent), and whether the tag is part of a user-defined type (where changes are considered overrides).

(1) "Reset to Default", seen in all the following examples, is not about expressions but rather for resetting a parameter to its default value if there was one. For example: in a driver tag, the port configuration defaults to [*Port] (ancestor relative path) but you might have changed it to absolute path. "Reset to Default" gives you an easy way to change it back.

(2) The ability to right-click on a parameter to add an expression does not apply to parameters that provide the options Constant - Expression - Tag. For those, use the tools provided instead of the right-click menu.

Name field.

Add or remove start conditions

Other fields, no existing code to override.

Add or remove parameter expressions.

Other fields, with code to override (child tags of a user-defined type)
Inherit from parent (Area parameter only)
Add or remove override

Optimized Expressions

When using an expression to configure a parameter value, you can choose whether the value should be evaluated only when the tag starts (and re-starts), or whenever there is a change to any value used by the expression. Non-optimized tag expressions are intended for situations where configuration values must be obtained from equipment, which is reachable only after the application starts.

Do not deselect the optimization option unless there is a clear need to do so. Misuse of non-optimized tag expressions can have undesirable side-effects. In particular, note that configuring a tag so that its properties change dynamically may have an impact on logged values or cause unintended alarms.
Every time that the non-optimized parameter expression changes, the tag will restart, as will all of its descendants, just as if you changed it in the Tag Browser. Be certain that variables within the expression will not change frequently.

A parameter expression that refers to tags outside the current hierarchy must use a non-optimized expression. There is no way to predict which hierarchy of tags will start first, therefore you must allow the expression to re-evaluate if a tag that it refers to in a different hierarchy starts later than the current tag.

When optimization is selected:

  • The parameter value will be evaluated only when the tag is created, when the application re-starts, or when you explicitly change any property of this tag or a parent using the Tag Browser.
    The expression will not be re-evaluated during normal operations.
  • Your selection of functions is limited to those that can be evaluated in script mode.

When optimization is not selected:

  • Expressions can use information obtained from hardware after tags have initialized and I/O operations begin.
    This is the primary purpose of non-optimized parameter expressions.
  • The expression will be re-evaluated whenever any of the parameters used in the expression change.
    Be careful to consider all the possible effects of this fact.
  • When a parameter changes, this tag and all of its child tags will restart, slowing the application temporarily and increasing the load on the CPU.
  • Each non-optimized tag expression requires extra RAM, roughly equivalent to half that required for a typical tag.
  • Your selection of functions is limited to those that can be evaluated in both script and steady-state.

Identifying properties

Do not add quotation marks to property names. Quotation marks should be used only to indicate literal text.

To read the a tag property other than it's value, follow the square brackets around the name with a backslash and then the name of the property.

[SomeTagName]\ShortName

To access the value of a property in a parent tag, preface the name of the property with two dots and a backslash (..\). VTScada will search upwards through the Parent-Child tree to find the first instance of a matching property name. You can specify the number of levels up at which to start by repeating the ..\ code.

Your expressions can use relative tag addresses, VTScada application properties and other system variables. Refer to topics in the scripting chapters beginning with Use Tag Values in Expressions.

Referring to text properties such as Description, Area or Engineering Units? You should use \ParmPhrase(), \GetPhrase() or \GetParmPhrase() rather than Concat(). See: Multilingual Expressions.

Start Tag Expressions

An expression in the name field of a tag will not change the tag's name. Rather, this expression will control whether the tag starts or not. Examples of this can be seen in the various Station Tags, which may be configured with a varying number of pumps for each station. This is done by tying the number of pumps in the overall station tag configuration to an expression in the name field of each pump. If the number is 1, only the first pump tag will start and the station tag will have one pump. If the number if 2, then two pump tags will start.

The expression used for a start condition must evaluate to TRUE (usually defined as 1) or FALSE (defined as zero).

For example, the MultiSmart, and MPE station tags include an option to set the number of pumps in the station.

The number of pumps in the station tag can vary.

The tag structure varies according to the number you choose:

On the left, one pump. On the right, three pumps configured.

Changing the selector doesn't change the number of pump tags created. It changes the number started. Select the Show Disabled option in the Tag Browser to reveal the difference.

The Multismart always has the same number of pumps. The choice is how many to start/enable.

Tags cannot be manually disabled from the right-click menu if they have a start condition. The "Enable" option will be grayed out.

To use this feature, add a Start Tag Expression to the name parameter of a tag.

The method is the same as adding a Tag Parameter Expression.

In the Tag Parameter Expression editor, whatever expression you create must ultimately return a Boolean result, meaning either zero or numeric non-zero (usually, one). If the expression works out to true at start-up then the tag starts. If false, it doesn't.

Start tag expressions are always optimized. They run only when the application starts or when a parent tag is redefined, which causes all child tags to restart. Ensure that the conditional within your start tag expression can be evaluated in both of those situations.

Overrides

Having made use of an expression to control a tag's configuration, you can choose to override that value in a given child tag. For example, a child tag which would otherwise inherit the area value "North County" might be assigned the area "South Street". When a value that would otherwise be based on a calculation is changed, this is called an "override". Assigning a value to a field that has no expression does not override anything and is simply called "assigning a value". The difference can be seen in the color that the field will turn: orange for overrides, and green for simple assignments.

A tag that has an override is marked with a [image] in the Tag Browser.

Overrides are both common and useful. Do not assume that the symbol means that you must take action to "clean up" the override in some way.


From Context to Type

After you have:

  • Added child tags below your Context tag to monitor and control all of the I/O processes, alarms, logging of a device. (See: Add a New Tag or Child Tag)
  • Created properties in the Context tag to fully describe the device. (See: Add Properties to Context Tags)
  • Created parameter expressions within the child tags so that configuration is done automatically, using information stored in one place - the Context tag. (See: Automated Tag Configuration)

Then it's time to turn the Context tag into a new type. This is not mandatory. You could copy the Context tag and it's full structure of child tags for every new instance of the device. But, turning the Context into a type makes many other tasks easier.

You will need the Manage Tag Types security privilege to perform the tasks described here.

The steps to create a tag type are as follows.

  1. Ensure that your Context tag has a value in the Type field.
  • The Type value will become the name of the new tag type.
  • This value must be a single word and must be valid for use as tag type name. It must not match any existing tag type. If this condition is not met, an error message will be displayed.
  • Type values can have a maximum of 31 characters.
  2. Right-click on the Context tag in the Tag Browser to open its context menu.
  3. Select the option, Create New Type.

A dialog will open to confirm that you wish to proceed with this action. This same dialog provides an opportunity to control which of the built-in widgets will be associated with the new type. Some of these are not optional, and cannot be deselected. You may choose to create custom widgets at a later date for your new tag type.

  5. Click, OK.

The new tag type is added to your application, and the selected context tag is converted to be an instance of this type.

Troubleshooting:

  • An error dialog reports that the type name is not valid.

There must be a type name, which is a single word.

  • An error dialog reports that the name exists, but you have not used that word elsewhere.

Name conflicts with other parts of VTScada can happen. The names, "Pump" and "Calculation" for example are both taken.


Modify a Custom Type

It is inevitable that you will want to modify a custom tag type that you have created. You might decide to change the parameters in the parent. Or, you might decide to add, edit or remove child tags. Or, perhaps you just want to change a few things about one instance. Each type of change has its own procedure.

If security is enabled, the privilege, "Manage Types", must be granted before you will be able to proceed. This privilege is not granted to any role by default.

Override a property of a single child tag instance.

If one instance of a custom type needs to have slightly different properties from all the rest, you will override that instance. For example, perhaps it's a characteristic of the primary pump that it is prone to overheat when running faster than 1000rpm, but the secondary pump doesn't have this problem. You might modify the speed I/O tag in the primary pump like so:

The orange color means that you are overriding default values.

All parameters in all child tags of a user-defined type are set automatically using whatever value was in that field when the type was created. You're allowed to override those values whenever and wherever you need. The orange color serves only as a reminder: "this value is an override, not a default".

In the Tag Browser, you'll get a similar warning:

The star on the orange dot indicates that this tag contains at least one parameter override.

If you were to add a new child tag in Pump 1, it would show with a green plus symbol:

"This child tag was added explicitly by a user"

If you delete a tag, then it's disabled within that one instance.

In all cases, these overrides affect only Pump 1. Nothing has yet changed Pump 2 or any other new CustomPump that you create. For that, you can...

Redefine a Type Definition

You can right-click on the parent tag of the structure, Pump 1, and from the menu choose Redefine Type. Instantly, all of the overrides within Pump 1 will be made part of the CustomPump definition. Pump 2 (and all subsequent pumps) will gain a warning alarm on the speed and a new demo tag.

There's a risk that the instance contains overrides that are meant only for that one object, not for all. Take extreme care when using this command.

When you decide to modify a user defined type definition, the recommended procedure is to:

  1. Create a temporary instance of that type. Call it Template or something equally obvious.
  2. Override the child tags as required. Add new tags, modify parameters, even delete (or better, disable) obsolete tags.
  3. Run Redefine Type on that temporary instance.
  4. Delete the temporary instance.

All the current pumps and all news ones will use the redefined type definition with one very important exception:

All existing tags keep their overrides.

Therefore, in the case of a conflict between a parameter that you change in the type definition and a parameter that you overrode in one particular pump, you always keep the local override.

Deleted tags:

If the instance you redefined had a deleted tag (disabled within that one instance) then following the redefine operation, that tag will be removed from the structure definition and deleted from all instances.

But if you disable a child tag and then redefine the type, that child is disabled within all other instances.

While it may look the same, VTScada remembers whether you deleted or disabled a child tag.

Change the Parameter List

After turning a Context tag into a new type, the Settings tab becomes the Other Parameters tab. The ability to add and edit parameters has vanished. You can still work with the parameter list, but now you must use the Manage Types page in the Application Configuration dialog.

Manage Types

All of the user-defined types in the current application will be listed. You have two options:

  • Export and synchronize just the tags within the type. Use this to modify the child tags outside VTScada.
  • Edit the parameter list of the type definition.

Our focus here is the second of those two options. It's usually the easier method.

Select a type, then click the Edit button to open the Edit Properties page. Here you can work with the parameters of the type, just as you could in the original Context. In fact, this is slightly more powerful: you can use this page to delete the HelpKey parameter if you are not using it.

Edit type paramters window

Detail from editing a type's properties

Work directly in the list to change properties. Use the Add button to create new properties. Note that you can provide only a name and label when doing so. There is no way to set a default value here for your parameter.

The Translate option refers to the value and means "This property is text". Do not use for I/O addresses, even if those addresses include letters.

Besides providing a way to edit the parameters, this is useful as a reminder for the names that you gave each parameter. After the Context has been turned into a type, only the label will show, making it difficult to build an expression that uses the parameter if you forgot the name.


Conflicts When Redefining Types

It is possible to create a conflict between child tag names when redefining a type. For example, suppose that you created a type named LiftPump, then modify it as follows:

  • Two instances of LiftPump are created: LP1 and LP2.
  • In LP1, you create a special-purpose tag to measure flow. This is an Analog Input named FlowRate.
  • In LP2, you do the same, but create it as an Analog Status tag, also named FlowRate.
  • Realizing that every lift pump will need to measure the flow rate, you then decide to use the Redefine Type command on LP1. This will add FlowRate to the type definition.
  • When VTScada attempts to update LP2's definition to add the Analog Input, it will find that there is already an Analog Status of the same name, and therefore there is a conflict to resolve.

The problem in the preceding scenario is the work flow. When modifying the structure of a user-defined type by adding or removing child tags, you should always work in a temporary instance (template) rather than within a working instance. But from a real-life perspective, there is nothing unreasonable about the development process that led to this naming conflict. Other, more complicated scenarios involving OEM layers or Unique ID values can be imagined.

Whatever the combination of steps that led to a naming conflict in the type definition, the important thing is to resolve the conflict quickly and in a way that will not interfere with future development work. You have the following choices:

  • Remove the child tag (or its name) from all instances of the type except the one that will be used for the Redefine Type operation.
    The instance that is to be redefined may exist in the OEM layer, rather than the current application.
    If widgets were linked to the tags being removed, they will need to be linked to the new child tag after the Redefine Type operation.
    If there is logged data that must be retained for those child tags, it may be possible to move or rename them rather than deleting them. This may not be an option for some communication tags.
  • Create or redefine the type without the child tag.
    The tag will then need to be added, individually, to each instance of the type on an as-needed basis. Extra care will be required so that an instance is not forgotten.
    If later redefining the type definition for another purpose, the tag with the conflicting name must not be present in the instance being used for the Redefine Type operation.


Manage Types Outside VTScada

If you have created a new type of tag, you can export the type definition to a spreadsheet or database file. After modifying the tag structure in the exported file, you can import those changes to update the type definition within the application. This provides an alternative to working within the VTScada tools. (Modify a Custom Type)

Your account must have the security privilege, Manage Tag Types, before you can work with this dialog.

Type definitions may be built-up across OEM layers. Only what was added, changed or overridden in the current layer will be exported. For OEM types, the descendents list will count only the child tags defined in the local application, not in the OEM application.

Detail from the Manage Types page of the Application Configuration dialog

Options:

Show OEM Types | Enabled only if the application property, CanRedefineOEMType has been set to TRUE. Use extreme caution.
Remove | Allowed only for user-defined types, and only if there are no instances of that type in the tag browser.
Edit | Applies if the original parent was a Context tag before the type was created. You can use this to add, remove and edit the properties of that tag, using a dialog similar to the Settings tab of a Context tag's configuration panel.
Sync | Requires an existing spreadsheet or database, created using the Export button. Synchronize will import any changes that were made in that file, modifying the type definition within the application. What it does next depends on your choice of Import Clean Up Options. If Update is selected, a fresh copy of the structure will be sent to the external file, including an updated version number. If Delete is selected, the external file will be removed.
Export | Sends the structure of the selected tag to a file of the selected type, Access, Excel or other ODBC.

If there is no check mark in the Removable column of any of the tags (preceding image), then there is at least one instance of each in the application. (Standard VTScada types cannot be removed, regardless of whether there are any instances.) Note that the Remove button and the Edit button can only be enabled while the application is running.

The check mark in the Editable column indicates that this type was based on a context tag. You can click the Edit button at the lower left of the display to work with that tag's parameters. All instances will update to have the new or changed parameters when you finish. See Edit Type Properties.

If you intend to work with the tags in a spreadsheet or database, start by clicking the Export button.

An operating system dialog will open, to prompt you for a file name. The suggested name for the export file will match the type name, but this is not required. The VTS_Reserved worksheet or table in the file contains the name of the type that will be modified when the file is re-imported.

Each type must be exported to, or imported from its own file. You cannot put two type definitions into one file.

All the child tags of the current type are exported, no matter how many generations deep in the structure. But, if any of those child tags are themselves user-defined types, then their structure will not be included because there can be only one type definition per export. The exception to this rule is that tags with values that have been overridden will always be exported.

Each entry will be named according to its place in the tag structure. In this example, SpecialPurposeTag has the following structure (shown with an instance named "MyStation1").

In the export file, child tags are named relative to the parent. So, in this example, the TCP/IP Port worksheet will have the following entry for the TCP/IP Port child named IO_Port. Because this is the first child in the structure, its name does not include the top-level parent.

The Modbus Compatible Device tag is a child of the TCP/IP port. It's worksheet name will reflect its place in the structure:

Note the doubled backslashes. A single backslash indicates the division between parent and child tag names, but the spreadsheet program forces us to use the doubled backslash. See also: Relative Tag References & Parameter Expressions.

And, so on for the two Analog Input types that are children of the Modbus Compatible Device in this structure.

Note the use of relative tag paths (*Driver) for the each I/O tag's driver field.

You can add new child tags of any type to the structure by creating entries in the appropriate worksheet or table. You can also remove or modify any child tag's definition in the structure.

Warning: Column A must be left blank for new tags. Do not change or remove this field for existing tags.

Upon re-importing the file by using the Synchronize button, the file, the structure within the application will be modified with your changes.

Version control applies to exporting and importing type definition files. The exported file contains a key that identifies the application's current version number at the time of the export. VTScada is able to compare the contents of the file being imported to the definition of the type as it existed at that revision. Only differences between the file's current contents and the type definition as it existed at the time of the export will be merged.


Copy Types to Other Applications

Having created a custom tag type, you may want to use it in another application. By far the best way to do this is through the use of application layers, where one application is built on another, thereby inheriting all of the custom features of the first (OEM) layer. See: Reusable Application Layers.

This topic was written before VTScada included support for multiple languages. The phrases used by your tags (descriptions, engineering units, ...) must be managed separately from the steps described here.

If you use the steps described in this topic, you may have difficulty managing updates to tag definitions over the long term.

You are strongly advised to use OEM layers instead, whenever possible. When type definitions are stored in an OEM layer, updates are a simple matter of distributing a ChangeSet of the OEM layer.

There may be cases where you need to share a custom tag type between applications that for some reason cannot share a custom OEM layer. A common scenario is a Systems Integrator creating a type for a specific project, then deciding to add that type to an OEM layer so that it can be reused in many projects. This process may also be necessary if you create master applications.

The process provided here will copy the definition template for the type, but no instances of the tag. The example images within the steps show the custom tag, HoldingTank, being copied from the Completed Tutorial application to a new application.

To copy a custom tag type definition from application A to application B:

  1. Find the source file that defines the tag.
    This will be a .SRC file with the same name as the tag, stored in the application's main folder.
  2. Copy that file to the main folder of application B.

Steps 3 through 6 apply only if the custom type includes child tags. If not, proceed to step 7.

  3. Ensure that application B's folder structure includes a folder named "ChildTags".
    If not, create that folder now. Note that "ChildTags" is one word.
  4. Open the ChildTags folder of application A.
  5. Find the sub-folder that has the same name as the tag type.
  6. Copy that entire sub-folder to the ChildTags folder of application B.
  7. Return to the main folder of application A.
  8. Using a text editor that does not add formatting, open the file AppRoot.SRC.
    (UTF-8 character encoding is strongly recommended.)
  9. Scroll to the section labeled [ (POINTS).
  10. Copy the line that declares the tag type.
  11. Open the AppRoot.SRC file of application B.
  12. Paste the line into the [ (POINTS) section of that file.
  13. Save your changes.
  14. In the VAM, click the Import File Changes button for application B, then click OK to import the files and recompile. (The number of files to be imported will vary.)

You should now have the tags, but not the phrases associated with those tags (description, engineering units, ...). Unfortunately, there is no tool that will gather the relevant phrase keys for you. If dealing with a small number of tags, the simplest way to proceed is to edit the properties of every child tag within the destination application, changing text ysuch as "EU43y4gag" into the correct phrase. It will help to have the original application available for reference.

Be sure to use "Redefine Tag Type" to share the corrected phrases with the type definition.

If there are many child tags, you might export that type definition to Excel. It should be relatively easy to sort by description, etc. in order to identify and gather the keys. Then, copy the matching phrase definitions from the source application's "en.csv" file to the matching language file in the new application. Use the Import File Changes tool when ready.

Custom tags may include other custom tags, some of which may have been defined in an OEM layer. If so, this procedure must be followed for all.


Delete Custom Tag Types

Only type definitions that you have created can be deleted. You cannot edit or delete a standard VTScada type.

If you delete a child tag from a custom type structure, it will be flagged as disabled until you run Redefine Type on the parent. It cannot be fully deleted so long as it exists as part of the type structure.

Prerequisites:

  • There must be no instances of that type in the application.
  • If the application is secured, you must possess the Edit Properties privilege and the Manage Types privilege.
  • You must be working in the application where that tag was created - you cannot edit the definition of a type in an OEM layer from within an application based on that OEM layer.

To delete a type definition:

  1. Ensure that there are no instances of that type in the application.
  2. Open the Application Configuration dialog.
  3. Open the Manage Types page.
  4. Select the type in the list.

If there is no check mark in the Removable column, the type is in use somewhere in the application (either as an instance or as a child of another type) or else this is a standard VTScada type, which cannot be removed.

  5. Click the Remove button.

There is no confirmation dialog - the type definition will be removed from the application.

Removing a user-defined type.


Edit Tags Outside of VTScada

Some developers find that it is efficient to create or edit tags in a tabular format, such as a spreadsheet, especially when there are a large number of similar changes to make. VTScada makes it easy for you to export your tag database to Microsoft Excel™, Microsoft Access™, or to Microsoft SQL Server™, SQLServerExpress™, MySQL™ (using the MySQL 8.0 or later Unicode driver), or MariaDB™ (using the ODBC 3.1 or later driver) via ODBC. After editing in your preferred program, you can synchronize the changes made in that file or database with the running application.

If your goal is to copy a custom tag type definition from one application to another, the best option is to use an OEM layer (Reusable Application Layers).

Certain specialized applications may contain parameter data that exceeds the 8k cell limit of Excel. An export will proceed, but those parameters will not be included. VTScada will not allow the spreadsheet to be synchronized back into the application.

Tags are both exported and imported using the same page of the Application Properties dialog, "Export/Sync Tags".

Notes:

  • If selecting the Excel format, the Microsoft Excel program must be installed on the computer. Microsoft COM objects, provided only with a copy of Excel, must be present to create a spreadsheet that is fully compatible with Excel. (After the export file is created, you can work with it in any Excel-compatible spreadsheet program.)
  • Excel must be activated. If installed but not activated, this procedure will not work.
  • Tags that are created automatically as children of a complex type (those within a MultiSmart or MPE station, or your own user-defined types) will be exported without configuration data that would be generated automatically when the complex type is created. Override values will be exported, and you may apply or remove override values in the exported file.
  • Tags with override values are marked with a * before the name (example: *Station 1\\Pump 1\\Set Speed)
  • Blank tag names: An entry with a blank tag name or only a * is one that duplicates another tag name. This can happen if a tag is disabled and you then create another with the same name, disregarding the warning message, or sometimes following a series of override and delete operations in a user-defined tag type.
    The enabled tag takes precedence during export / synchronize operations. The row with the blank tag name should be examined to see if it is worth retrieving by adding a new name, but otherwise deleted.
  • If copying a row in order to create a new tag, you must exclude the data in column A, and the name of your new tag must not begin with a *.
  • A * in front of the tag name signifies that the tag contains an override. This is handled by VTScada automatically. Never add or remove the *.
  • If you change a text property in an existing tag, the result is to change the phrase in the current language database. The phrase key remains the same as do all translations using that key.
  • You cannot use the procedure described in this topic to modify the structure of a complex type by adding or removing child tags. A separate tool exists for that purpose - See: Manage Types Using a Spreadsheet or Database.
  • If you have custom tags with a large number of parameters, you should be aware of the following limits: If exporting to Access, the maximum number of tag parameters is 256. If exporting to Excel, the maximum number of parameters is 65,536. None of the tags built into VTScada approach these limits.
  • If you use Microsoft OneDrive®, you may experience problems if OneDrive insists on synchronizing a newly exported file with one that was exported earlier. Problems are especially likely if you open the local file before it is synchronized to the cloud. OneDrive will assume that the older version in the cloud is the correct one. Outcomes may vary.
  • Tag parameters that are longer than 8192 characters exceed Excel's limits. A placeholder will be substituted so that the operation can proceed without causing an error. Upon import, that placeholder will be matched with the existing tag and the old parameter used without change. Do not edit the placeholder.
    If the tag is deleted, moved, or if a new tag is created by copying one with the placeholder, the import operation will fail. In this case, you must delete the placeholder. The text of the placeholder follows: <Parameter_value_unable_to_be_exported_to_Excel>
  • You can export a subtree of tags. If you specify a tag in the Export Root Tag field, the export will be limited to just that tag and its children. You do not need to select the root tag when importing. You cannot select a different root tag to import a subset of changes.
    You cannot import a subtree if the root tag has been deleted. The only way to resolve this circumstance would be to revert to an older version of the application from before the root tag was deleted, import the subtree and then go from there.

If there are any concerns about an import, then, as with any configuration change, it can be reverted using the Version Log.

The export file will contain information that identifies both the application and its current version. This will be used by the VTScada version control system when synchronizing the modified database. Look for the table or worksheet, VTS_Reserved. The synchronization process gives you the following option for what will happen to the spreadsheet or table after you import it back to the application.

  • You may direct VTScada to update the file by performing a fresh export, thereby ensuring that you can continue editing the file and synchronizing those changes. Choose this option when you are making a series of consecutive edits and synchronizations.
  • You may direct VTScada to delete the file, thereby ensuring that you must perform a fresh export before the next editing session. Choose this option when you expect to work in the Tag Browser before going back to the external database.

In general, it is best to work on an exported file that matches the current tag database. Importing an older file that does not include recent changes, may lead to errors.

Only if you have a large number of tags.

Tags can be imported (synchronized) without re-starting your application. Note that if there are a large number of tags to import or export, the operation may take a few minutes. The operation will be faster if the application is not running. When you request either operation, a dialog will remind you of this:

When exported to an external data file, each tag type will be stored in its own table or worksheet. Within a tag type table, each instance of a tag will be stored on a separate row, with a field for each attribute of the tag. (See following example) If a tag is part of a parent-child tag structure, the full name of the tag within the structure will be shown.

Relative tag references and parameter expressions will be adjusted to avoid conflicts with Excel conventions. Backslashes and other expression operators will be preceded by an extra backslash. Commonly-seen formats include the following:

..\\*TagType | Reference to a parent tag of the named type
\= | Optimized tag parameter expression follows (snapshot expression)
\% | Non-optimized tag parameter expression follows (refreshing expression)

If adding expressions to tags in an exported Excel file, you cannot use relative references such as [TagName]. All existing expressions are exported using the full syntax, "Scope(Self, "TagName")\\Value". You must do the same.

Exported tags as seen in an Excel workbook

When adding new tags, you must leave the field in column A blank.
Do not change the value in column A for any existing tag, unless your goal is to delete the tag.
Do not begin new tag names with a *. This symbol is used to indicate existing tags that have an override.


Export, Synchronize

Export sends the tag database to either of Microsoft Access™ or Microsoft Excel™.

In addition to these, you can use the ODBC option to send the data to any of Microsoft SQL Server™, SQLServerExpress™, MySQL™ (using the MySQL 8.0 or later Unicode driver) , MariaDB™ (using the ODBC 3.1 or later driver). Before using any of these, ensure that you have created a database for use by VTScada and used the 64-bit ODBC Manager tool to create a DSN. The account you choose for the connection must have rights to create tables, add and edit data.

Synchronize (Import) brings the edited tags back into the application, merging changes rather than over-writing.

The structure of user-defined tag types is not exported. Refer to Manage Types Outside VTScada instead.

Subordinate Application tags are excluded from tag exports.

Tags can be exported but not synchronized using the VTScada Anywhere Client.

If generating a file using the VTScada Anywhere Client, it will be transferred to your browser automatically. Check your browser's download history. (Will vary by browser.)
Only text files can be generated by a thin client, not spreadsheet or database files.
Similarly, Excel templates cannot be used when reporting via a thin client.

This applies to report generation, HDV exports, note exports, ChangeSet creation, and tag exports.
You cannot view a generated file (such as a report) within the Anywhere Client. The client shows only the VTScada user interface.

To export your tag database:

The steps to either import or export tags begin with the same page in the Application Configuration dialog:

  1. Open the Application Configuration dialog and select the Export/Sync Tags page.

The Export/Sync Tags menu lets you modify/add/delete tags outside VTScada. Export all tags or select a specific tag tree.

  2. To export your entire tag database, leave "Export Root Tag" set to the default "All Tags".
  3. Select the output type.

If ODBC is to be chosen, you must have already defined a Data Source Name (DSN) for your SQL Server database using the Microsoft ODBC Data Source Administrator.

  3. Choose whether to open the file after exporting. (Recommended)
  4. Choose whether to hide empty sheets if exporting to Microsoft Excel.
    All tag types are exported to a matching sheet, but those that contain no tags are hidden from view, making it easier for you to find the tags that do exist. To reveal a hidden sheet, use the tools provided according to your version of Excel.
  5. Choose whether to exclude tags that came from an OEM layer and were not modified in your application (for example, most Menu Item tags) and all children of user-defined types, whose values have not been overridden. This option can greatly reduce the time required for the export.
  6. Click the Export button.

If exporting to Access or Excel, you will be prompted for a file name and path.

If exporting to an ODBC data source, you will be prompted for the DSN.

  4. Provide the destination for the exported tags and click OK.

To export a subtree of tags

Exporting tags from a large application may be a slow process that may take many minutes. If you only need to modify a subset of the exported tags, you may specify the root tag in question using the tag selector of the "Export Root Tag" field.

  • Specifying a tag will export just that tag and its children.

  • You can modify/delete those tags or add tags within that subtree and import the database.

  • Note that the Export Root Tag field has no effect when importing.

  • The option to export just a subtree of tags is only available when the application is running.

  • You don't need to do anything special to import the subtree, VTScada will keep track of where it came from.

Troubleshooting:

  • The file could not be created.

Ensure that your Windows account has access to the folder you choose. You may need to select another folder.

  • The exported file does not contain the child tags of my custom tag structure.

It won't. You can edit those using the Manage Types dialog.

  • A warning message tells me that Microsoft Excel (or Access) is not installed.

Excel or Access must be present. To create a file that is fully compatible with those programs, the related Microsoft objects must be present on this computer.

To synchronize your tag database:

You can choose to follow-up the synchronization operation by deleting the external file or replacing it with a fresh export of the application's tag database.

Tags are matched based on their GUID (Column A in a worksheet). If the file being synchronized does not contain any GUID matching one in the tag database, VTScada assumes that your intent is to delete that tag. If two rows have the same GUID value, an error message will be shown and the synchronization operation will stop.
For all tags, any parameter value set or changed in the external spreadsheet or database will replace the current or default value in the VTScada database.

You are advised to ignore the AuditName column in each worksheet.
(In this context, "ignore" means both "pay no attention to" and "do nothing with".)

If creating new tags, ensure that none of the names include a *.
The * before a name is a flag to VTScada, indicating that this is an existing tag with an override. If the name of your new tag begins with a *, VTScada will not add it when synchronizing.

  1. Open the Application Configuration dialog and select the Export/Sync Tags page.

  2. The Export Root Tag field is irrelevant to synchronization. Leave it set to default.
  3. Choose the format matching the file to be imported / synchronized.

If ODBC, you must have already defined a Data Source Name (DSN) for your database using the Microsoft ODBC Data Source Administrator.

  3. Select the clean-up option.

As a guideline, use the update option when making a series of modifications. Use the delete option when there will be significant changes to the internal tag database before the next round of external edits.

  4. Click the Sync button.

If importing from Access or Excel, you will be prompted for a file name and path.

If importing from an ODBC data source, you will be prompted for the DSN.

  5. Choose the source file or DSN and click OK.

A message will inform you of how many tags were imported.

If you attempt to import tags that were exported from a different application, you will see an error message warning you that the GUIDs do not match. The tags will not be imported.

Troubleshooting:

  • The error message reports that the GUID of the file does not match that of the application.

The file was created in a different application. Synchronizing it with the current application may have undesirable side-effects, but it can be done by first removing the GUID from the VTS_Reserved table or worksheet of the file.

  • Conflicts were reported with one or more tags.

For one or more rows in the external file, column A - the unique identifier - is duplicated in the file. For new tags, column A must be blank.

  • Tags were deleted from the application when the file was synchronized.

The information in column A - the unique identifier - was removed or changed for one or more rows. Repair using the VTScada version control system. Do not remove rows in the external file (or their unique identifiers) unless you intend to have them removed from the application.

  • I've deleted a tag and now I cannot import its subtree.

You cannot import a tag subtree if the root tag has been deleted. There is no recovery besides reverting the deletion from the Version Log, at which point you will be able to import the subtree.


Import Legacy Tag Databases

Prior to the release of VTS 10, tags were stored in a database file named Points.MDB. For most applications, this was a Microsoft Access database. (Microsoft SQL Server was used by a very small number of applications.) These Points databases did not include any information to identify the application, or its version.

You can import the tags from an older application's Points.MDB file. The steps are the same as those provided in the previous topic but, be aware of two potential problems:

  • The file, Points.MDB stores tag instances, but not type definitions. If the source file used type definitions from an OEM layer, then the destination application must also have access to that layer's code to use the tags.
  • Conflicts between tag names in the older database and the current application may not be resolved the way you would prefer. Because the older database has no version control information, VTScada is not able to automatically determine how to resolve a conflict between two tags of the same name.

After importing an older tag database, you must compile the current application (using the Import File Changes button) before you be able to see all of the imported tags.


Import to Other Applications

After exporting tags from an application, if you then attempt to import those tags to a different application you will see an error message reporting "Failure to import tag database".

This is meant to protect your application in the case that the imported database may include type definitions that are not present in the destination, or possibly a name conflict between the current and imported set of tags.

If you are satisfied that these two problems will not occur, and you are sure that you want to import the database, then you may proceed by removing the identifying information from the external tags database. This is stored in a table (or worksheet) named "VTS_Reserved". After the GUID entry in this table is removed or set to "00000000-0000-0000-0000-000000000000" the tags may be merged into any VTScada application just as the tags from an older VTScada version may be imported.

You should remove all Menu Item and other default tags from the spreadsheet or database before proceeding.

The tag database does not include phrases matching phrase keys used for descriptions and other text parameters in your tags. In the destination application, you will have to provide new text for all these parameters.


Filtering Tags, Alarms and Realms

You can restrict certain information to authorized users or authorized workstations by using a filtering protocol defined in configuration files. These features are complementary to the VTScada security system, rather than duplicating it.

You can apply several types of filtering to tags:

Global Tag & Area Filtering

The filtering dialog is visible only in a secured application, and then only to those who have been granted the associated privilege. Allows operators to create custom filters as needed, restricting their view of tags and alarms to only those they need to see right now. Global Tag & Area filtering is not linked to any workstation.

Realm Filtering:

Limit the display of tags belonging to one or more specified areas or tag hierarchies to operators who belong to a given security realm. Operators will not see alarms outside their assigned realm. Note that they will still see all tags drawn on any page they are permitted to view, but will not be able to see or edit properties of tags outside their realm and will not be able to issue control actions using those tags.

Unlike tag area filtering and alarm area filtering, realm filtering is not linked to any workstation.

Tag Area Filtering:

Tag area filtering is an older feature and works only with areas that are a single word. Do not use spaces and wildcards in this type of filter.

Prevent tags belonging to one or more specified areas from loading on a given workstation when your application runs. This type of filtering is generally used in applications where memory is limited, and certain workstations do not require access to all of your application's tags (e.g. in a large plant where a certain plant section is beyond the responsibility of operators in other sections).

Alarm Area Filtering:

Display only the alarm tags belonging to one or more specified areas on a given workstation. This type of filtering is generally used in applications where certain users should not see certain types of alarms on their workstation (e.g. in a large plant where alarms belonging to equipment in a certain plant section is beyond the responsibility of operators in other sections).

Using Multiple Filter Types

In general, more filters equates to a slower application. Consider your goal and options carefully before defining more than one kind of filter. If using multiple filter types, they are applied in the following order:

  1. Tag area filtering
  2. Realm filtering (tag and area)
  3. Global filtering (tag and area)
  4. Alarm area filtering
  5. Local filters applied by dialog boxes or pages.


Global Tag & Area Filtering

Operators who have been granted the Global Tag & Area Filtering privilege can use a tool, provided in the title bar, to restrict their view of tags and alarms to only those they need to see right now. This can be valuable in a larger application where operators need to focus on one area of the system at a time, which may change from day to day.

The filter tool is visible only to operators with the
Global Tag and Area Filtering Privilege

When a filter is in effect,
the tool will be shown in gold with a check mark

These filters affect which tags and alarms the user can see and hear in any tag or alarm list. Every user is warned of this fact when first opening the filter dialog. Improper use can mean that alarms are missed.
Notifications sent by the VTScada Alarm Notification System are not affected by this filter.

While a name-based filter is in effect, all entries from the System Events database are hidden. This includes operator actions, security events, etc.
To see system events in alarm lists, ensure that all tags are selected in the Global Tag & Area Filters dialog.

When filtering on area, Alarm Databases (and therefore their alarms) are excluded if their area does not match the filter.

You can enable/disable the coloring, and even make the filter flash when in effect using application properties. See: UserFilterIconColorize, UserFilterIconFlash.

Global Tag and Area Filtering does not affect your ability to see pages, the widgets that you can see on a user-created page, or alarm notifications via Rosters.

This tool does limit the tags and alarms you see when viewing any of:

  • Site lists
  • Alarm page, alarm lists, and the title bar alarm icon
  • Tag Browser
  • Tag List widget
  • Tag selection in the HDV (dialog must be reopened after changing the filter)
  • Tag selection in the Reports page

Filters have all the following characteristics:

  • User-defined.
  • Dynamic and flexible. If you have access to the filtering tool, you can change the filtering rules at any time.
  • Persistent. The last filter you set will remain in effect across page changes, networked workstations, and application restarts.
  • Global. Your filter affects all tag and alarm lists.
  • Filters cannot be sent in ChangeSets.

Global Tag and Area Filtering is designed for use by operators who need to focus on smaller parts of the application for a limited period of time. Do not attempt to do development work while a filter is in effect.

Create and Apply Filters

Select the Global Tag & Area Filters button to open the filtering dialog.

The filter tool is located on the title bar of every page that has a title bar.

Selecting this tool, as shown in the previous figure, will open the Global Tag & Area Filters dialog. You must have the Global Tag & Area Filter Privilege to see the icon and to open this dialog. Note that Global Tag and Area filtering can be disabled for all by setting UserFilterMode to 0.

You will see a warning the first time you open this tool in any new application. The tag list shows only container tags such as Contexts, Stations, Polling Drivers, and user-defined types. Existing restrictions are shown in this dialog.

The Global Tag & Area Filters dialog with no filters applied
(all are selected for viewing)

You can control which parts of this dialog are shown by changing the value of the application property, UserFilterMode. Advanced users can write code to set or check filters. See: Custom Global Filters for Tags and Areas

At least one tag or one area must be selected in order to apply a filter. The dialog will not allow you to create a filter that excludes all tags and all areas.

Global Tag & Area Filtering Examples:

Example 1: Selecting tags for a report.

The first of the following two images shows the tag selection for a report with no filter in effect. The second shows the same list filtered for the Northern Zone tags. Note that this zone includes tags with three area properties: North, Northeast, Northwest.

Before filtering for the Northern Zone

The same list after filtering out Eastern Zone and Southern Zone tags

Example 2: Alarm Lists

Filtering for alarms in either the East or the Northwest areas. Note that the System area is included in the filter. If it were not, the System Alarm DB would be excluded and no alarms would be shown.

Filtering for alarms in either the East or the Northwest areas.


Realm Filtering

Customers who are familiar with legacy versions of VTS/VTScada may be looking for "Realm Area Filtering".
Filtering has been extended to allow filters that specify tag hierarchies instead of, or in addition to, area properties and is now referred to as "Realm Filtering".

A new section name notation, [-REALMFILTER] has been defined. Legacy applications may continue to use the older notation, [-REALMAREAS], but that keyword will not appear elsewhere in these notes.

Realm filtering is based on a combination of security realms (as defined using the Accounts dialog) and either a set of selected tags (usually upper-level tags in a hierarchy), a set of area properties, or both. It will affect your application in the following ways:

  • Members of a security realm can see and acknowledge only the alarms from tag hierarchies or areas matching their designated realm filtering list.
  • When working with reports, members of a security realm can select tags only from tag hierarchies or areas matching their designated realm filtering list.
  • When working with the Historical Data Viewer, members of a security realm can select tags only from tag hierarchies or areas matching their designated realm filtering list.
  • Operators with the History Page Access privilege will not be able to trend tags that are outside their realm.
  • The tag browser is affected, such that users in a given security realm will see only the tags that match their designated realm filtering list.
  • For VIC connections, you must create a realm with the same name as each security-realm. (See: Internet Realm) Users can sign in to only the realm that matches their security realm.
  • Users who are not part of a realm may only sign in to the realm designated by the RootNamespace propertyThe value of RootNamespace must not match any defined security realm. 1.
  • Security managers who are members of a realm can see only those accounts and roles that are also members of the same realm.

Ensure that you maintain one super-user account, which is an account having the manager privilege and which is not a member of any realm. Failing to do so will make it impossible for you to manage accounts outside your realm.

  • Realm filtering does not change what is visible on a page. All tags are visible on all pages to all users unless that page is protected by a security privilege.
  • While an operators may be able to see a control widget linked to a tag outside their realm, they cannot write to hardware using that tag.
  • Similar to the last point, operators with the Tag Modify privilege will not be able view or edit the properties of tags that are outside their realm
  • Tags that are automatically linked to other ancestor/sibling tags via a * reference, e.g. [*Driver], will still be linked to the ancestor/sibling tag even if the ancestor/sibling tag is outside the user's realm.
  • Alarm notification rosters must be configured with each contact user name including the full realm qualifier.
  • ODBC queries cannot see tags outside the matching realm list.

Why Should I Use Realm Filtering?

Realm filtering is most often used for larger applications where there users should be restricted to access tags or alarms from one part of the application but not another. Use Realm tag filtering to specify:

  • What alarms should be visible to a user, based on their security realm.
  • What tag hierarchies or areas should be shown in the tag browser, reports screen and historical data viewer when a user who is part of a defined security realm is signed in to the application.
  • What tag areas should be shown in the tag browser (if any) when no user is signed in to the application.

While realm filtering can prevent users from seeing and therefore acknowledging alarms in tags or areas they are not authorized for and can also prevent them from selecting those tags in reports and trends, it does not affect any page displays other than the alarm list. It does restrict access to controls on pages.

Filtering is only one part of security. You should also use application-specific security privileges to Protect Pages and Output Tags. Some benefits of realm filtering can also be achieved by using Master & Subordinate Applications.

How Does Realm Filtering Differ From Tag Area Filtering and Alarm Area Filtering?

Realm filtering affects lists of tags and alarms configured for tags in specific hierarchies or having specific area properties, hiding them from users according to their security-realm. It is not limited to any one workstation. The user may sign in to any workstation and they will still only have access to the alarms permitted by the filter.

Tag area filtering prevents tags that have been configured with specific areas from loading on a given workstation.

Alarm area filtering hides alarms associated with specific area properties from loading on a given workstation.

Where is Realm Filtering Configured?

  • Security Realms are configured for each user in the Accounts dialog.
  • Filters are configured in your application's Settings.Dynamic file using the Edit Properties page of the Application Configuration dialog.

How do I Configure Realm Filtering?

The following elements are involved in realm tag filtering:

  • Security realms must be configured and accounts assigned to realms.
    See Security Realms and follow the steps there to enable realm sign-ins and add users to realms before proceeding with the remaining steps.
  • Define one or more [RealmName-REALMFILTER] Sections. While these are stored in Settings.Dynamic, you are advised to use the advanced mode of the Application Properties dialog.
    • Name = properties in the above section.
    • Area = properties in the above section.
  • (Optional) Define a [RealmFilter] section containing names or areas whose alarms should be visible when no user is signed in.
  • (Optional) Define a [*-REALMFILTER] section containing the names and areas that should be visible with a super-user is signed in.

How should I format my filters?

For both Name and Area filters, an exact text match can be used. Additionally, the question mark (?) and asterisk (*) wildcard characters are permitted. Filters are not case-sensitive.

From an efficiency standpoint, the best name filters formats are:

  • An exact tag name with no wildcards.

    For example A\B\C\D for just one tag.
  • An exact tag name followed by "\*".

    For example, A\B\C\D\* for A\B\C\D and all of its children.

In the case where you want to see the parents of A\B\C\D, but not all of their children, the pattern set would be:

A\ , A\B\ , A\B\C\ , A\B\C\D\*

Other patterns are possible, but may be much slower.

If working with Master & Subordinate Applications and attempting to filter for tags in a subordinate application, you must use the name of the subordinate tag as seen in the master, rather than wildcards. The only exception is to use a single leading wildcard, which will filter for tags in both the master and subordinate application. Note the use of backslashes in all the following examples.

Good examples:

MasterFolder\SubordinateAppName\MySites\*
*MySites\*

Bad examples:

Master*Folder?\SubordinateAppName\MySites\*
MySites\*

Security Realms and the VTScada Thin Client Server

Security realms also affect user's access to an application through the VTScada Thin Clients. On the VTScada Thin Client Server, add one realm for each security realm. Each realm must be given the same name as the security realm, and must include a reference to this application.

An operator can then connect to the application using a URL that includes the name of the Realm he is connecting to. For example, members of the Western realm would use the address: http://www.yourdomain/Western.

You must also define the RootNamespace property to designate an Internet realm for users who do not belong to any security realm.

[RealmName-REALMFILTER] Section

The Settings.Dynamic [RealmName-REALMFILTER] section holds the list of tag areas or tag names (and their alarms) that should be visible when a user in a given security-realm is signed in.

To specify the visible tags:

  1. Open your Application Configuration dialog.
  2. Select the Edit Properties page.
  3. Select the Advanced Mode.
  4. Select Add.
  5. Complete the dialog as shown.
    (Area filter shown on the left, tag filter shown on the right.)
  6. Select OK
  7. Repeat for as many tag names as you require.
    You may use the asterisk (*) wildcard character as any part of the Value, but for best results you are advised to restrict wildcards to the beginning or end of the tag names.

For each subsequent Name or Area property in the same section, you will be warned that the property already exists. Proceed anyway.

[REALMFILTER] Section

The [REALMFILTER] section of Settings.Dynamic is used only if you want to define the alarm areas that should be visible when no user is signed in. This is typically used if there is an Alarm List drawn on the default page because the Alarms page will not be accessible when no user is signed in. (See also, RealmAreasExcludeInvalid which controls whether tags that do not have any area defined will be included or excluded from view.)

To create a REALMFILTER section:

  1. Open your Application Configuration dialog.
  2. Select the Edit Properties page.
  3. Select the Advanced Mode.
  4. Select Add.
  5. Complete the dialog as shown on the left to filter on tag Area properties.
    Complete the dialog as shown on the right to filter on named tags. Note the \* in the value, which includes child tags of Station 2.
  6. Select OK
  7. Repeat for as many areas and tags as you require.
    For each subsequent area, you will be warned that the property already exists. Proceed anyway.

[*-REALMFILTER] Section

This optional section is used to restrict the tag areas that should be visible when a super user is signed in. (A super user is one who does not belong to any realm.) If you do not provide a [*-REALMFILTER] section, the super user can see all areas. If you do provide the section, then they can see only the areas specified in that section.

There cannot be a section that explicitly defines a filter for the RootNamespace. This means there cannot be a [<RootNamespace>-RealmFilter] section.
For example, there cannot be a [ALPHA-RealmFilter] section, where "ALPHA" is the RootNamespace. The intent is that only a [*-RealmFilter] section be defined for super users to use.

To specify the tag areas that should be visible when a super user is signed in:

  1. Open your Application Configuration dialog.
  2. Select the Edit Properties page.
  3. Select the Advanced Mode.
  4. Select Add.
  5. Complete the dialog as shown on the left to filter on tag Area properties.
    Complete the dialog as shown on the right to filter on named tags.
  6. Select OK
  7. Repeat for as many areas or tag hierarchies as you require.
    You may use the asterisk (*) wildcard character as any part of the Value.
    For each subsequent property, you will be warned that the property already exists. Proceed anyway.

While realm filtering can prevent users from acknowledging alarms in areas they are not authorized for and can also prevent them from drawing tags having those areas, it does not affect any page displays other than the alarm list, and does not restrict access to controls.

If you wish to restrict user access to pages or to control tags, use application-specific security privileges. Some benefits of realm filtering can also be achieved by using Master Applications.

Restricting realm access to areas does not mean that the operators cannot see the tags belonging to areas outside of their realm's defined set of areas. It does mean that they cannot see or acknowledge alarms resulting from those tags. It also restricts their ability to select tags for use in reports and the Historical Data Viewer.

A related property is RealmAreasExcludeInvalid. This variable controls whether tags that do not have any area defined will be included or excluded from view.

If RealmAreasExcludeInvalid is set to 1, then no user will be able to view tags that do not have an associated area.


[REALMFILTER] Section

Properties in the [REALMFILTER] section define the tag areas that are accessible when no user is signed in to your application. (You may wish to protect your system by preventing view access for users who are not signed in.)

Define these areas as shown:

[REALMFILTER]
Area = Station005
Area = Station006

In this example, if a user attempted to access the VTScada application on a workstation without signing in to the application, they would see only tags whose area are configured as "Station005" and "Station006".

[REALMFILTER]
Name = East Stations\*

In this example, if a user attempted to access the VTScada application on a workstation without signing in to the application, they would see only tags that are children of East Stations.

If you do not want users who are not signed in to view any tag data, set the Area variable equal to nothing, as shown:

[REALMFILTER]
Area =

The question mark (?) and asterisk (*) wildcard characters are permitted. Area declarations are not case-sensitive, nor is the [REALMFILTER] section heading.

[REALMAREAS] is now deprecated. It will continue to work as always, but you are advised to use [REALMFILTER] for all new applications.


[*-REALMFILTER] Section

Use the [*-REALMFILTER] section to indicate the areas that are accessible when a super user is signed in to your application (a super user is one who is not restricted by any group and who has access to all application data).

In addition to configuring the [*-REALMFILTER] section, be sure to set up security groups to restrict users to certain tag areas based on the group to which they've signed in. See: Security Realms.

[*-REALMFILTER]
Area = *

In this example, the asterisk (*) wildcard character in the section heading (i.e. [*-REALMFILTER]) indicates all realms, and the asterisk wildcard character following "Area" indicates all areas. The result of the above example is that super users will see everything.

[*-REALMFILTER]
Name = *

In this example, the asterisk (*) wildcard character in the section heading (i.e. [*-REALMFILTER]) indicates all realms, and the asterisk wildcard character following "Name" indicates all tags. The result of the above example is that super users will see everything.

The question mark (?) and asterisk (*) wildcard characters are permitted. Area and name declarations are not case-sensitive, nor is the [REALMFILTER] section heading.

[*-REALMAREAS] is now deprecated. It will continue to work as always, but you are advised to use [*-REALMFILTER] for all new applications.


[RealmName-REALMFILTER] Section

To use these examples, supply an existing realm name from your application in place of "RealmName".

The [RealmName-REALMFILTER] section is used to indicate the tag areas and names that are accessible when a group user is signed in to your application. To use the [RealmName-REALMFILTER] section properly, use the syntax shown. You may create area-based filters, name-based filters or both. Name-based filters should end with a \* and apply to all tags below the specified parent.

[RealmName-REALMFILTER]
Area = East
Area = West
Name = Station 1\*
Name = Station 2\SubStation 1\*
...

The question mark (?) and asterisk (*) wildcard characters are permitted. Declarations are not case-sensitive, nor is the [REALMFILTER] section heading.

In the example above, RealmName in the section heading ([RealmName-REALMFILTER]) must be replaced by the name of a security realm, and the Area = and Name = declarations beneath the section heading assign the tag areas and hierarchies permitted when a user is signed in to that realm. For example:

[NorthEast-REALMFILTER]
Area = Tank
Area = Pump

Using the example above, a user signed in to the "NorthEast" realm is permitted to view all tags whose area is either "Tank" or "Pump".

In addition to configuring the [<Area>-REALMFILTER] section, set up Security Realms to restrict users to certain tag areas based on the realm to which they are signed in.

[RealmName-REALMAREAS] is now deprecated. It will continue to work as always, but you are advised to use [RealmName-REALMFILTER] for all new applications.


Tag Area Filtering

Tag area filtering will prevent tags that have been configured with a specified area from loading on a given workstation when the application runs.

Tag Area Filtering is an older feature and can use only areas that are a single word. You cannot use spaces and wildcards in this type of filter.
Consider using a master application with subordinate tags instead. See: Master & Subordinate Applications

Why Use Tag Area Filtering?

Use tag area filtering to reduce the demand for memory on a given computer. It is particularly useful on older PCs with limited memory, or on PCs where tag licensing is restricted.

How Does Tag Area Filtering Differ From Alarm Area Filtering and Realm Filtering?

Tag area filtering prevents tags configured with specific areas from loading on a given workstation. Alarm area filtering hides alarms that have been configured with specific areas on the Alarm page on a given workstation. Realm filtering restricts the display of alarms based on the tag name or area and the security-realm membership of the operator.

Tag area filtering does not affect the data presented on the Alarm page. Users can view alarm data corresponding to the unloaded tags in the History and Configured lists, and the filtered areas are visible in the Area Filtering drop-down list. If you wish to hide these areas from view on the Alarm page, you must use alarm area filtering. See: Alarm Area Filtering.

Where is Tag Area Filtering Configured?

Tag area filtering is stored in Workstation.Startup files, where "Workstation" is the name of the computer on which the properties will apply. Note that workstation files are stored within the folder, "WorkstationSettings", not at the top level of your application. See: Workstation-Specific Properties Workstation-Specific Properties

The Application Configuration dialog will add properties only to the .Dynamic file. Any property that belongs in .Startup must be added using a text editor and then the changes imported. (Import File Changes Tool)
Existing properties in either file can be changed using the Application Configuration dialog.

How is Tag Area Filtering Configured?

The following elements are involved in tag area filtering:

  • A Workstation.Startup file named for the PC to which it should apply (e.g. MyPC.Startup),
  • Add the AreaFilter property, set to 1.
  • Add the AreaExclude property, set to 1 or 0 to define default behavior for areas not explicitly listed.
  • Add the [Areas] section and subsequent area declarations to define which areas to include and which to exclude.

The properties in each section will be Area names, with values set to 1 or 0 to include or exclude them. Areas not listed will be included or excluded according to the value of the property AreaExclude.

You cannot add declarations for areas that contain a space. You cannot use wildcards in area names.

AreaFilter Property

The AreaFilter property enables (or disables) tag area filtering. you must create a copy of the AreaFilter property for the workstation, and set its value to 1 to enable tag area filtering at that station.

AreaExclude Property

The AreaExclude property defines how to handle areas not explicitly referenced in your Workstation.Startup file.

  • If set to 1, then any area not explicitly included, is excluded.
  • If set to 0, then areas not explicitly excluded are loaded at startup.

If using AreaExclude, be careful that system areas are included in the list of tag areas to load, otherwise you may find that ports, drivers, fonts, etc. are not loaded, thereby preventing the application from running properly on the workstation.

[AREAS] Section

The [AREAS] section is the heading under which you may specify which tag areas to include or exclude from loading at start up. You will need to add each area as a property.

  • To load tags configured with a specific area when the application runs, set the name of the property to the area, and the value to 1.
  • To prevent tags configured with a specific area from loading when the application runs, set the name of the property to the area, and the value to 0.
  • Tags in areas not specifically listed are loaded or not depending on the AreaExclude setting.

Wildcard characters and spaces are not permitted in area names when applying tag area filtering.

After you have completed the configuration, import file changes and restart your application. (Workstation.Startup files are only read when the application initially runs.)

Detail from the Advanced view of the Edit Properties dialog


Tag Area Filtering Example

In this example, a large plant has two main areas (AreaA and AreaB). Each area employs a group of skilled personnel that operate and monitor only the equipment processes in their own area. Because each area has thousands of tags, memory is limited on the plant workstations therefore, the plant management has requested that the workstations in each area load and display only those tags that correspond to the equipment in that area. The one exception is the plant manager who, because he must oversee the entire plant, wishes to view all tags for the application on the main server in his office. I

Given workstations:

  • MainControlStation
  • StationA
  • StationB

You must stop and restart the application on the workstations before these properties will go into effect, even thought the Restart column will not show a check mark.

MainControlStation Configuration

Because the workstation named MainControlStation must load all tags for the application so that the plant manager has full access, it requires no special configuration at this time.

StationA Configuration

The following configuration is required for the workstation named StationA. Note the values for Workstation and Section in each of the following properties.

(Properties will be visible in the Application Configuration dialog after being created using a text editor and the changes imported. .Startup files cannot be created from the Application Configuration dialog.)

Areas that load on StationA

The AreaFilter property in the section, System, is set to 1 so that tag filtering is enabled this workstation.

The AreaExclude property is set to 1 so that any areas not specified will not load.

The two properties in section, "Areas", have names matching the areas that will load (System and AreaA), and values of 1 to enable loading.

StationB Configuration

The workstation named StationB requires the following configuration. Note that these properties are added using the Application Configuration dialog, just as the properties for StationA were. You can save time by copying existing properties, changing values of the fields as required. What matters most is the value in the Workstation field.

Areas that load on StationA or StationB

The result of the above configuration is that the workstation named StationB will only load tags whose Area property was configured as "AreaB" and the "System" area tags .


Alarm Area Filtering

Alarm area filtering will show alarms that have been configured with one or more specified areas on a given workstation, and hide those associated with areas that are not included.

Why Use Alarm Area Filtering?

Alarm area filtering is typically used in applications where some users do not need to be aware of some alarms (e.g. in a large plant where alarms belonging to equipment in a certain plant section is beyond the responsibility of the operators in other sections).

As an alternative to Alarm Area Filtering, you might consider using Master & Subordinate Applications.

How Does Alarm Area Filtering Differ From Tag Area Filtering and Realm Filtering?

Alarm area filtering hides alarms associated with specific areas from a given workstation. The alarm tags is still visible to developers who have access to the Tag Browser and other application development tools.

Where is Alarm Area Filtering Configured?

Alarm area filtering is best achieved using workstation-specific application properties.

How do I Configure Alarm Area Filtering?

The following elements are involved in alarm area filtering:

  • A workstation.startup file named for the PC to which it should apply (e.g. MyPC.startup), and
  • The <Alarm_Manager> section and subsequent area declarations.

Workstation.Startup File

Create a workstation.startup file for each PC for which you wish to apply tag area filtering. To create a workstation.startup file:

  1. Create a text file that is named for the PC to which its settings should apply, and which has the .STARTUP extension (e.g. MyPC.startup).
  2. Save this text file to the WorkstationSettings folder of your application and use either the File Manifest or Import File Edits to make it part of the application's working set of files. (You may need to create the WorkstationSettings folder.)

A PC will only obey the workstation.startup file that carries its name.

After you have created your workstation.startup file, configure it for alarm area filtering as follows:

<Alarm_Manager> Section

The <Alarm_Manager> section is the Workstation.Startup section heading under which you may specify the alarm areas visible to the workstation.

Note the use of angle brackets rather than the more common square brackets for this section. These are required.

The following instructions will guide you through the process of successfully configuring the <Alarm_Manager> section.

  1. Create or open a WorkstationName.startup file, where WorkstationName is the name of the computer where filtering will apply.
  2. Save this file into the WorkstationSettings folder of your application.
    (Create that folder if it does not exist.)
  3. Within the file, add a section named <Alarm_Manager>.
  4. In this section, enter AlarmArea followed by an equals sign, followed by the name of the alarm area to display (as in the following example).

Alarm area filtering allows the asterisk wildcard character. For example, to view all alarms whose area ends with "1" you could enter *1 for the AlarmArea property. To view all alarms whose area begins with "a" you could enter a* for the AlarmArea property.

<Alarm_Manager>
; The alarm areas to show
AlarmArea = North
AlarmArea = South

After you have completed the configuration of your Workstation.Startup file(s), save the files, import file changes at the VAM, and then restart your application.


Alarm Area Filtering Example

In this example, a large plant has two main areas (AreaA and AreaB), each of which has a set of skilled personnel that operates and monitors only the equipment processes in that area. Because the plant operators are specialized only in their own area and need only respond to the alarms in their area, the plant management has requested that the workstations in each area display only those alarms that are relevant.

Given workstations:

  • WorkstationAreaA
  • WorkstationAreaB

WorkstationAreaA Configuration

The workstation named WorkstationAreaA requires the following configuration:

  1. A text file named, WorkstationAreaA.startup is present in the WorkstationSettings sub-folder of the application.
  2. The <Alarm_Manager> section is added to the WorkstationAreaA.startup file.
  3. The AlarmArea property is set to AreaA so that only alarms configured with an Area property of AreaA are visible on this workstation.

The completed WorkstationAreaA.Startup file should appear as follows:

<Alarm_Manager>
; The alarm areas to show
AlarmArea = AreaA

The result of the above configuration is that the workstation named WorkstationAreaA will only display alarms whose Area property was configured as "AreaA".

WorkstationAreaB Configuration

The workstation named WorkstationAreaB requires the following configuration:

  1. A text file named, WorkstationAreaB.Startup is present in the WorkstationSettings sub-folder of the application.
  2. The <Alarm_Manager> section is added to the WorkstationAreaA.Startup file.
  3. The AlarmArea property is set to AreaB so that only alarms configured with an Area property of AreaB are visible on this workstation.

The completed WorkstationAreaB.Startup file should appear as follows:

<Alarm_Manager>
; The alarm areas to show
AlarmArea = AreaB

The result of the above configuration is that the workstation named WorkstationAreaB will only display alarms whose Area property is configured as "AreaB".

Alarm area filtering does not prevent tags from loading, therefore the alarm tags associated with the hidden alarm areas will continue to appear in the Tag Browser (for those users who have the security privileges to access the Tag Browser).


Display Building (Idea Studio)

Just getting started with VTScada? If you pressed F1 in response to the message on the initial Overview page, then here's what to do next:
You can clear the welcome message from the Overview page by pressing Ctrl + A (select all) then Delete. Then you will have a blank page, on which to begin development.
Steps in the development process follow, under the topic, "Organize your work".

Best practices for HMI design (Human Machine Interface)

Before creating the user interface for a SCADA system, it is worth learning the principles of HMI design. Several excellent resources can be found online and in textbooks. We encourage you to study the ISA 101.01 standard, which is available for purchase from the ISA online store. General information may be available through a web search.

A full discussion of HMI design is well outside the scope of these notes. Instead, our purpose is to show you the tools available within VTScada, leaving it to you to design the best HMI for your operation.

Display scale issues

Please read, Size Pages for Differing Screens

Organize your work

You can build the user interface before, during or after creating tags. Most developers create tags first, then draw them. When building the user interface, the typical order of steps is to:

  1. Create and configure new pages. (See: Pages)
  2. Configure navigation to those pages. (See: Add Navigation)
  3. Draw widgets on the pages and link those widgets to tags. (See: Widgets for Tags)
  4. Enhance the display with images and decorations such as borders and frames. (See: Images, Decorations)

Idea Studio Components

The Idea Studio is where you create the user interface. It opens in its own window, so that you can edit pages while viewing them live in the operator display. There is no "save" button. Your changes are applied as you make them. (If your application runs on multiple workstations, you might choose to switch off auto-deployment while editing. Configuration Deployment)

Open the Idea Studio by clicking the button shown circled.

You can make the Idea Studio open automatically when a user with configuration privileges signs in, by setting the application property AutoOpenIdeaStudio to true (1).

Quick Access Toolbar

Often overlooked, this contains tools that you will want to use frequently. Note the many tools for customization.

Customization options of the Quick Access toolbar

Standard tools in the Quick Access toolbar include:

  • Deploy Local Changes - Enabled only when automatic deployment is switched off.
  • Show Operator View - Close the Idea Studio and open the current page in the main window. Strongly recommended rather than simply minimizing the Idea Studio to view the page.
  • Undo / Redo - Back up from design errors.
  • Customization Menu - As shown in the image. Hide tools, change the location of the toolbar, minimize the main ribbon.

You can add any often-used tool to the Quick Access toolbar. To do so, right-click on any tool in any ribbon and select, Add to Quick Access Toolbar.

Adding the Tag Browser tool to the quick access toolbar

To remove a tool, right-click on its icon in the Quick Access toolbar and select "Remove from Quick Access Toolbar".

The ribbons

This is where you will find most (not all) of the tools in the Idea Studio. Ribbons are shown on an "as needed" basis, according to what is selected on screen. When more than one ribbon might apply (perhaps you have selected both text and an image), you will find tabs across the top of the Idea Studio that can be used to switch from one ribbon to another. In all cases, the Home ribbon will be available.

Reference: Ribbons

The file menu

Labeled with the word File, or with only an icon, depending on the version of the Windows® operating system that is installed on your computer.

Opening the file menu

Tools in this menu allow you to:

  • Create new or existing pages and widgets. (Open a Page or User-Defined Widget to Edit)
  • Close the open page or widget.
  • Clone the current page or widget, creating an identical copy.
  • Import a page or widget by selecting its source code file.
  • Delete a page or widget.
  • Open the Application Configuration dialog
  • Open this Help file.

Note that most File Menu tools can also be found by left-clicking the plus sign or right-clicking a page label in the Idea Studio navigation bar:

Shortcut to file management tools for a page.

Splitter bars

These bars divide the palette (on the left) and the panels (on the right) from the drawing area of the Idea Studio.

Double-click either bar to open and close or drag left and right as needed. Both bars will always be visible but may be mistaken for the edge of the window.

The Idea Studio, elements and home ribbon.
Icons replace labels in this compressed view.

The palettes

Covering the left side of the Idea Studio, the three palettes are where you will find all widgets, images and shapes to add to your pages. Palettes are organized into folders and for the widgets palette at least, you will find the same items in several folders for ease of searching.

The palette is a window that can be closed, opened and resized. Use the scale slider at the bottom of the palette to resize the contents but note that labels are not shown when the icons are much smaller than the default size.

Palette detail, widget palette open

Palettes include:

  • Tabs for switching between the three palettes.
  • A Recent Items list, with a separate list for each palette.
  • A navigation bar to help you keep track of which folder you are viewing within a palette.
  • The tools and folders that make up each palette.
  • Widgets for Tags
  • Images
  • Shapes, Pipes, Lines

Palette entries are built using Menu Item tags, which means that you can reorganize them to suit your needs. Do so either within the "Menus" section of the Tag Browser, or by right-clicking directly within a palette, then using the pop-up menu (recommended).

Remember that you can search for tags by name, or by all information. That fact applies to Menu Item tags as well. But, you must be working in the Tag Browser to do so.

Many developers like to create a folder of frequently used widgets or images to save time from searching.

Panels

There are three tabs within the panels window. The panels window will open automatically to the Multi-Image Widgets tab or the Layers tab when relevant to what you are doing within the Idea Studio. The Tag Links panel must be opened as needed. Many developers choose to leave the panels window open but reduced in size from the default while they work on a page or widget.

Navigation buttons and zoom controls

Across the bottom of the Idea Studio, all the currently open pages and widgets will be listed. You can click any page or widget's tab to open it for editing. You can click the (+) sign to the right of the tabs either to open a currently closed page or widget or to create a new one. You can also right-click a tab to open a menu of file-commands for that page or widget.

Display controls are provided in the bottom bar of the Idea Studio. You can change the display scale to 'zoom-in', the better to see detail in your work. You can also change the display scale of the palettes to see which tool you are choosing or to see more tools at a smaller scale. The three sets of coordinates in this toolbar show the top-left corner location of selected objects, the overall size of the selection and size of the page.

To pan, use the scroll bars across the bottom and the right side of the Idea Studio.

Detail from the Idea Studio navigation bar

Keyboard shortcuts for Idea Studio

There are a lot of keyboard shortcuts for Idea Studio and more to come. Many of these shortcuts are industry standards and should feel intuitive.

Key Combo | Description
Ctrl + N | Creates a new standard page.
Ctrl + O | Opens an existing page or widget
Ctrl + T | Open the Tag Browser.
Ctrl+ L | Link the selected widget to a tag. Enable Show Children when the tag browser opens.
Ctrl + Plus sign (+) | Zoom in.
Ctrl + Minus sign (-) | Zoom out.
Ctrl + Scroll Wheel | Zoom in and out.
Shift + Scroll Wheel | Move left and right instead of up and down.

Ctrl + TAB

or

Ctrl + PageDown

With multiple pages/popups/widgets open, switch to the next tab.
Shift + Ctrl + TAB
or
Ctrl + PageUp 		With multiple pages/popups/widgets open, switch to the last tab.
Ctrl + Z | Undo the last action. May be used more than once.
Ctrl + Y | Redo last action. May be used more than once.
Ctrl + A | Select all the graphics.
Ctrl + Click | Select all graphics under cursor.
↵Enter | Open the properties of the selected widget, image or shape.
Arrow Keys | Move selections.
Shift + Arrow Keys | Move selections 10x faster.
Shift + Drag | Move selection orthogonally.
Del | Deletes selected graphics.
Ctrl + C | Copies the selected graphics.
Ctrl + X | Cuts the selected graphics.
Ctrl + V | Paste the graphics from the clipboard at the cursor location.
Alt + Arrow Keys | Re-size selection.
Alt + Shift + Arrow Keys | Re-size selection while maintaining aspect ratio.
Esc | While resizing/nudging/drawing a pipe et cetera, hit escape to cancel process.
Ctrl + [ | Bring the selected object forward.
Ctrl + ] | Send the selected object back.
Shift + Ctrl + [ | Bring the selected object to the front.
Shift + Ctrl + ] | Send the selected object to the back.
F2 | Align left.
Shift + F2 | Align right.
F3 | Align top.
Shift + F3 | Align bottom.
F4 | Align center.
Shift + F4 | Align middle.
F5 | Match height.
Shift + F5 | Match width.
Ctrl + B | Changes selected text to bold.*
Ctrl + I | Changes the selected text to italic.*
Ctrl + U | Underlines the selected text.*
Backspace or DEL | When drawing a line or pipe, remove last vertex in path.

*Text as in using the Text tool, not widget labels. Widget labels use font tags through their property dialog.


Pages

A page is the canvas on which you draw your application. There are two types: the full screen page used to provide an overview of part or all of a system, and the pop-up page used to provide detail or control for some small part. There are no restrictions on the number of pages you may create.

Every VTScada application starts with a set of built-in pages. Most of these (the "system pages") cannot be edited. For example, the Alarm page, Reports page and Historical Data Viewer all exist to be used, but not changed.

You can edit or delete only a few of the built-in pages. Of note is the Overview page, which is a starter page to help you begin building your application. Three sample pages are also included, from which you may freely copy elements for use in your own user interface. Pages that you can create and change are referred to as "application pages".

The Page Menu page is a special case. You can (and will) edit the contents, but you cannot delete it, making it more of a system page.

Display scale issues

Please read, Size Pages for Differing Screens

Add pages

There are several ways to create a page. The result will be the same, whichever method you choose. You can also import existing pages from another application but be aware that you may also need to import images or widgets that exist only in the other application, and that linked tags will not be imported with the page.

When creating a page, you will be asked for a title, and (with some methods) whether you want a standard page or a pop-up. Both can be changed later using the page properties ribbon.

  • The Idea Studio must be open before you can create a page.
  • If security is enabled, your account must have configuration privileges and the Page Add privilege.

When creating either a page or a widget, you will always be prompted for a title. A default value is provided, but you are advised to create a meaningful title for the page. It can be changed later, if required.

Prompting for a title - this dialog will be seen for every page and widget creation method.

Press Ctrl + N:

  1. In the Idea Studio, press the key combination Ctrl + N on the keyboard.
  2. Provide a title for the page in the dialog that opens.
  3. Click OK to save the title and close the dialog.

File Menu >> New

  1. In the Idea Studio window, click the "File" menu to open it.
  2. Click on or hover over the option, "New" expanding the option list.
  3. Click either Page or Pop-up Page, depending on the type you wish to create.
  4. Provide a title for the page in the dialog that opens then click OK.
  5. Choose whether to include the page in the menu.
    You can edit the menu later if you change your mind.
  6. Click OK to save the title and close the dialog.

New Tab Dialog (+)

  1. In the Idea Studio, click the plus sign at the bottom of the editing window.
    The New Tab dialog opens.
  2. Choose create a new standard or pop-up page.
  3. Provide a title for the page in the dialog that opens.
  4. Click OK to save the title and close the dialog.

Import an existing page

  1. In the Idea Studio, click the File menu to open it
  2. Click Import.
  3. Click Page.
  4. Use the Browse button to find and select the .SRC file of the page you want to import.
  5. Provide a title for the page in the dialog that opens.
  6. Click OK to save the title and close the dialog.

Clone an existing page

An application may require several very similar pages or widgets. Rather than create each from start to finish, it can be easier to copy or clone an existing instance and make a small number of changes.

  1. Open the page or widget in the Idea Studio and ensure that it is the selected item.
  2. Open the file menu.
  3. Click the command, Clone.
  4. Type a name for the new instance, then click OK.
    The new instance will be created and opened for editing.

Alternate steps:

  1. Open the page or widget in the Idea Studio.
  2. Right-click on its tab at the bottom of the Idea Studio.
  3. Click the command, Clone.
  4. Type a name for the new instance, then click OK.
    The new instance will be created and opened for editing.

Creating a new page in Idea Studio will generate a Page tag viewable in the Tag Browser. To see your Page tags in the Tag Browser, navigate to Menus > Page Menu.
VTScada bases page order off of the order you see in the Tag Browser, so extra control buttons will appear when navigating in the Menus group to allow you to change the order.


Open a Page or User-Defined Widget to Edit

When you open the Idea Studio, the current page in the application will be the one that the Idea Studio displays first.

If the page is already open for editing, it will be accessible using the tabs across the bottom of the Idea Studio screen.

If the page is not open in the Idea Studio:

  1. In Idea Studio, click File
  2. Click Open
    Alternate methods: Press the keyboard combination, Ctrl-O or click the plus button in the list of open pages.
  3. Select the page or widget that you want to edit.

Symbols used in the "Open" dialog:

  • This is a dialog-box page.
  • This is a full-screen page.
  • This a tag widget.
  • This is a standard widget.

The "Open" dialog can display pages and widgets in a list format instead of the default preview format. This can be useful if you want to see the name of the file that each item is stored with.

All, Page, or Widget?

Note the filter. (Shown as "All" in the previous image.) When working in the Idea Studio,, you can filter to show only pages or only widgets. VTScada will remember your choice the next time you use the Open dialog.

Override or Copy?

If your application is based on an OEM layer, and if you have access to edit the source code of that application, then you may see the prompt, Override or Copy OEM Page?

The default is that a local instance of the page file will be created, overriding the OEM version. No further changes from the OEM layer will be visible. This is especially relevant for the Overview page, which usually should remain the VTScada default and be editable. (That is, not overridden by your custom OEM layer application.)

If you choose to copy the page, a new version of that page with a new name will be created in your application. The OEM version will not be overridden. You are strongly advised against making the copy's name match the original. Doing so will only lead to confusion as you try to keep track of which page is the original and which is the copy.

If you select Cancel, the Idea Studio will open without doing either action. You may proceed with creating and editing pages solely within your application.


Limit Pop-up Pages

If your application uses pop-up pages for controls or other features, you can limit the number that may be open at any one time. By default, VTScada will allow eight pop-up pages to be opened at once before displaying a warning. More pages may be opened, but the operator must chose to do so by acknowledging the warning.

Trend windows (HDV graphs) that were opened by clicking a tag do not count toward the pop-up page limit.

A related option is that you might want to close all pop-up pages when the operator changes the page in the main display. This is sometimes done on the basis that the pop-up pages are often controls related to the current display. When the main display changes, the control pages should close.

Use the following application properties to limit or control pop-up page behavior.

PopupPageLimit

Sets the maximum number of pop-up pages that may be open at any one time.

If the operator attempts to open more pages than set by this limit, then the action will depend on the next property:

PopupLimitAction

Use this property to set one of the five possible actions:

0 or not set | No action. The limit will be ignored.
1 | Warn. Display a warning, but allow the operator to open the pop-up page.
2 | Prevent. Display an error dialog, and prevent the opening of the pop-up.
3 | Close Oldest. Whichever pop-up was open the longest during the current session will be closed so that this one can open and remain within the limit.
4 | Close Newest. Close the second most recently opened pop-up page what that the current page can be opened without exceeding the limit.

PopupCloseOnPageClose

Close the pop-up page automatically if the page from which it was opened closes. (There must be a hotbox or hot-button on that page.)

This action can be overridden on a page-by-page basis by adding the variable, PopupCloseOnPageClose, to the page. If this variable exists and is set to 0 (FALSE), then the page will remain open while others close.

Variables can be added only by editing the page's source code. Remember that it is necessary to import file changes after editing a source code file.


Add Navigation

As you create pages in your application, it is necessary to give operators a way to move from one page to another. There are several ways to do this. As you create each page you will be prompted for whether to add that page to the menu. If you choose yes, it will always be added at the top level. You can (and should) organize those menu item links into folders, which you can create from either the Tag Browser or the Page Menu page.

You can also provide in-page navigation using buttons and hotboxes.

Refer to Find and Open Pages Within an Application for an Operator-level overview of the navigational controls. This topic describes how to create those controls.

In-Page Navigation: Page Hotboxes and Page Buttons.

Buttons and hotboxes are used for in-page navigational links. For pages that relate directly to the current display, these tools are considered time-savers for operators as they eliminate the need to search through a menu.

Both tools can be found in the Standard Library folder of the Widgets palette.

  1. Open the Idea Studio
  2. Open the page in which you want to add a hotbox or button.

    If the page is not already open, or available for selection from the tabs at the bottom of the Idea Studio, click File, then Open.

  3. Open the Widgets palette
  4. Find, then click to expand the Standard Library folder.
  5. Drag a Page Hotbox or a Page Button onto the Idea Studio screen.
  6. Adjust the size and location of the hotbox or button.
  7. With the hotbox or button selected, click the Properties button in the toolbar.

  8. Select the page to opened in response to a click.
  9. Adjust the appearance as desired, using the options in the hotbox.
  10. If the page has parameters, select the tags or set the values to use for this instance of the page.
  11. Click OK to close the properties dialog and save your work.

Define and organize the menu

Entries (items) in the navigational menu system are stored as Menu Item tags. The contents and order of both the list menu and the tiled menu match the organization of Menu Item tags in the Tag Browser.

Folders within the tiled menu are shown as fly-out sub-menus in the list version.

The menu structure is best edited using the right-click context menu while viewing the Tile Menu, but you can also edit the menu within the Tag Browser. Note that only the tag browser allows you to change the order of entries within a folder.

Reorder the list:

This task can be done only in the Tag Browser. To reorder the items in the menu, select one, then click the Move Up or Move Down buttons. You cannot drag Menu Items. This tool cannot not move pages into sub-folders.

Add a page to the menu using the Page Menu Page:

Pages must exist before you can add to the menu. The act of adding a new menu item does not create a page to match, nor is there a way to create the page while creating the menu item.
When creating a new page you will be prompted to add it to the menu.

  1. Navigate to the Page Menu Page by clicking the VTScada logo at the top left of the screen.
  2. Navigate to the folder level where you want to add the page and right-click:
    1. To add the page at the current menu level, right-click on a page, on a blank square (if any) or on the narrow divider bar between folders.
    2. To add the page to a sub-folder, right-click on that folder.

Lettered arrows match options above.

  3. In the pop-up menu that opens, select New (page at current level) or New Child (page under selected folder).
    The New Menu Item Properties dialog opens.
  4. Select Page.
    The Select Page dialog opens.
  5. Click to choose the page to add.
    The New Menu Item Properties dialog opens.
  6. Reconfigure the menu item if required.
    You might choose to change the title, or if this is a parameterized page, add parameters.
  7. Click OK to finish.

The steps to add a folder, divider or menu item reference are much the same, differing only in the dialog boxes and options along the way.

New Menu Item Properties dialog

Displayed when adding a new entry of any type to the Page Menu.
Options may vary depending on whether you add the item to the Page Menu or a palette.

Select Page dialog

Includes all pages to which you have security privileges
Note the choice to display pages as a list or as thumbnail images (shown).

Use the File box to filter the selection, noting that this looks for the title / label of the page rather than the file name. In most cases, these will be similar but that is not guaranteed. Wild cards can be useful.

Depending on where you are defining navigation, the drop-down list may be enabled. For example, when choosing a Custom Details Page for a Context tag (or type derived from a Context tag) the drop down list will offer the option, Site Pages, filtering for only those pages that are appropriate for the tag be included.

All text entry fields in VTScada wait until you finish typing and press enter or tab before responding to what you type. This is by design to help avoid accidental changes.

New Menu Item Properties dialog

The configuration panel for a Menu Item tag - see: Menu Item Tags

Alternate steps: Using the Tag Browser

  1. Open the Tag Browser
  2. Navigate to the Page Menu section.
  3. Optionally, continue navigating to a folder within the Page Menu section.
  4. Click New in the Tag Browser, or right-click on Page Menu and select New Child from the menu that opens.
    The New Menu Item Properties dialog opens.
  5. Click to select the page option.
    The Select Page dialog opens.
  6. Select the page to add and click OK.
    The New Menu Item Properties dialog now shows configuration options for a page.
  7. Optionally, change the label, add parameter if this is a parameterized page, or select a different page.
  8. Click OK.

Related Property: DisablePageSnapShotting

Add a folder to the menu

Folders help you organize your Page Menu into fly-out or cascading menus, gathering pages into logical groups. When using the tiled menu, you can monitor the pages within the folder on one screen.

Folders can be added at the top level of the Page Menu, and can be added below other folders. They cannot be added below pages.

To add a folder, use the same steps as for adding a Page Menu entry. Configuration differs only as follows:

Select Folder rather than Page from the New Menu Item Properties dialog.

Title

Type a name for the folder

New Thumbnail

Select any image on your VTScada images collection. The default image measures 244 x 183 pixels, therefore an alternate image will display best if it is near to those dimensions.

Folder Contents

Filtered according to where in the menu tree the folder is added. The example shows "Pages", therefore this folder is being added below the Menus\Page Menu branch.

The following options exist only when a folder is being added to the Page Menu branch. They are not available in folders added to any of the palettes.

Hide Recent Pages:

Recently visited pages are displayed in a list across the top of the tiled menu, making it easy for operators to reopen commonly accessed pages. By hiding the list, you make more room available on screen for the pages shown within the folder.

Hide Labels:

The label is the name of the page, ordinarily shown below each page image in the folder view.

Hide Folder Path:

The folder path is the navigation bar, beginning with the home icon.

Add a divider to the menu

Dividers are visible only in the list version of the menu. They draw attention to menu items and help to separate one set of items from another. No configuration options are enabled.

Add a Menu Item Reference

A menu item reference is a copy of another menu item. This might be used when you want to link to a parameterized page using a new set of parameters.

The easiest way to add a new menu item reference is to copy and paste an existing item, then edit the properties to change the label (title) and parameters.


Delete a Page

You cannot delete System pages such as the Alarm page and the Reports page. You can remove OEM layer pages from your menu, but cannot fully delete them because they will continue to exist in the OEM layer. This includes the VTScada Overview page and sample pages.

Pages that you created may be removed using either of the following procedures.

Method 1:

  1. In the Idea Studio, open the page for editing.
  2. Open the File menu.
  3. Click the Delete entry.

Method 2:

  1. In the Idea Studio, open the page for editing.
  2. Right-click on the page tab.
  3. Click the Delete entry.


Page Property Reference

Use the Page Properties ribbon to control the appearance and behavior of each page you control.

Page management commands such as New, Open, Import and Delete are found in the File menu, rather than the ribbon.

Color

Opens the Select Color dialog, from which you can choose any color you like for the page background. Some developers will set a color theme for certain groups of pages as a visual guide for operators. While helpful in some cases, it does little good for operators who are color blind.

In general, if setting a background color always choose a neutral shade, to avoid eye strain and not distract operators. If designing to high performance HMI standards, choose a shade half-way between the "ON" color of equipment (usually white) and the "OFF" color (usually dark gray). Doing so allows both colors to stand out against the background.

Image

Use any image on your computer for the background of the page, using the Image Selector.

If a background image has been applied, you can use this same tool to remove the image.

You can force an image to fill the page using either of two options: Tile will cause the image to repeat in an array until the entire page has been filled. Stretch will re-size the image until it fills the screen. If stretching the image, you can choose whether the aspect ratio is to be maintained.

The Colorize option opens the Select Color dialogue, with which you can add a color to the image.

The Adjust menu contains six further controls to adjust opacity, brightness, etc.

Opacity | Adjust the visibility of the background by reducing its opacity, making it semi-transparent.
Brightness | Adjust the brightness of the colors in the background.
Contrast | Adjust the contrast between bright and dark shades in the background.
Mirror | Flip the image left-to-right.
Tile Scaling

Applies only if the Tiled option has been selected. Adjusts the size of each tile.

You may select one of the pre-set scale options, or click "Custom" to open the Tile Scaling dialog.

Margins

If a page has a background image that is not tiles, you can adjust the margins around that image to control its location.

The top margin defaults to 41 pixels, allowing space for the VTScada title bar. While you can adjust all four sides, you will generally find it to be most effective to adjust only two edges, setting a margin for either the top or the bottom, either the left or the right.

As indicated by the check box, the values do not apply to pop-up windows unless you direct them to do so.

Title

Pages are (apparently) identified by their title. But two or more pages can have the same title. What will always be unique is the file name, which is easily discovered by hovering the pointer over the page's tab at the bottom of the Idea Studio.

If you are familiar with VTScada's expression language, you can create one to display a title that can vary. This is seldom used outside of parameterized pages, but there can be very useful.

The same dialog is also used when renaming a page or widget

Size

Size settings apply (mostly) to pop-up pages. Using horizontal and vertical coordinates measured in pixels, you can set initial, minimum and maximum sizes and the location on the screen, measured from the top left corner of the screen to the top left corner of the page.

Size settings have no effect on standard pages other than to set defaults for the first time it opens, but they can be extremely useful in limiting the apparent page area in the Idea Studio. By setting a page size that matches resolution of your monitor (or the smallest monitor that the application will be displayed upon) the Design Studio's working space will help you stay within this area.

The default minimum Width by Height for an Anywhere Client is 1366 x 768. If you set smaller values, some standard VTScada dialogs may become unusable.

Pop-up Behavior

Choose between No Restrictions, Always Pop-up and Never Pop-up.

A page marked as "No Restrictions" will open as a standard page when the operator left-clicks to open it but will open as a pop-up window if the operator right-clicks to open it. Note that you can use application properties to limit how many pop-up pages may be open at a time and what will happen when an operator attempts to open one past that limit.

Opening a pop-up from a pop-up will always result in a new window, never with the new replacing the old in the same window. The subsequent pages must be marked as "No Restrictions" in order to stay within the same window.

Unless otherwise configured, a standard page includes a title bar, for which it reserves the top 41 pixels. A pop-up page does not. Switching from one mode to the other as you build a page will seem to add or remove 41 blank pixels as the title bar is removed or added at the top of the screen.

See: Limit Pop-up Pages.

Thumbnail

Optionally select or remove the thumbnail image, used for reference when working with the page. The thumbnail image is not shown as part of the page, like a background.

Bar Items

Choose to include or exclude standard items in the title bar and task bar of the page. Note that standard pages and windowed pages (pop-ups) are configured separately. By default, windowed pages do not have a title bar or task bar but you can add these and then go on to select which elements are shown.

Advanced developers can use the PageWinOpt variable for additional control such as disabling the Windows minimize / maximize buttons.

Title bar components

Title bar with all decorations shown:

Title Bar Item | Description
Windows title bar | The Optional Windows Title Bar may or may not be configured for your application. If it is present, it displays the title of your application in the left corner, and includes a minimize, maximize, and close button in the right corner.
Previous page | Click to open the previously viewed page. If no page has been viewed previously (this is the first time you are running the application) then the tiled page menu will open. Hold for a list of previously visited pages. Note: a page that you can navigate to with the Next button will not be included in the list of previous pages.
Next page | Click to step forward after using the previous page button. If you navigated several steps back in the list of previously visited pages, then click and hold this button for a list of "next" pages.
VTScada Logo | Click to open the tiled page-menu. Developers can set the page to be opened using the property, TitleLogoTarget.
Page title | The name of the page you are viewing.
Unlinked widgets | Click to toggle individual flagging of unlinked widgets. While individual flagging is off, this button will blink orange as a warning.
Page editor | Click to open the editor window, where all development work is done.
Application properties | Opens the application properties window, with its many configuration and administrative tools.
Add page notes | Click to add a reminder note, resembling a 'yellow sticky' to the page.
Hide page notes | Click to temporarily hide (not delete) all page notes. This button is visible only when there are page notes to hide.
Tag & Area filter | Visible only to operators with the Tag & Area Filtering security privilege. Used to filter tag lists, especially when viewing the alarm page.
Print | Click to print the current VTScada page using the default Windows printer.
Alarms | The Alarm button informs you of an alarm condition by flashing red. You can open the Alarm page by clicking this button.
Time/Date | The Time/Date displays the current system time and date.
Sign in button | Click to sign in to your account. After you have signed on, this button displays your account name, but is still a button. Click again to sign out or to access the security dialogs if your account is authorized to do so.

The task bar is used for navigating through the pages of your application.

Navigation Bar Components

Task bar with all decorations shown:

Navigation Bar Tool | Description
Menu list | When clicked, this opens a customizable menu of the pages for your VTScada application. Selecting an item from the menu opens that page.
Menu tiles | Opens a tiled menu of pages. Tiles in the upper portion are recently visited pages. Tiles in the lower portion match the contents of the menu list, with sub-menus shown in folders. A navigation bar between the two portions keeps track of which folder is open in the lower part of the display.
Pinned pages | These buttons provide single-click access to different pages in the application. They are under your control and different users can have a different list of buttons. Use the pin icon in the displayed page to pin it to the bar and the "x" icon remove a pinned page. You can change the order of the buttons by dragging left and right.
Current page | The name of the current page is highlighted.
Closed Remove the Windows Title Bar Controls

It is possible to remove the standard Windows title bar controls from a page, but this can only be done by editing the page's source code and then using the Import File Changes button in the VTScada Application Manager.

This is an advanced procedure, intended only for those who are comfortable using the VTScada scripting language.

If removing the Windows close control button from a page's title bar, you must ensure that you add a Page Close Button widget to the page. Failing to do so will mean that operators have no method for closing the page.

To remove the Windows control tools:

  1. Open the source code for the page using any text editor. (Use the button in the Home ribbon of the Idea Studio to do this.)
  2. Close the Idea Studio before proceeding. This will avoid the possibility of a conflict between the page being edited in the Idea Studio and the same page being edited within a text editor.
  3. In the editor, add a PageWinOpt variable declaration immediately below the Title = ... line, as shown:
[
  Title = "Pump Control";
    { Bit number 98765432109876543210 }
  PageWinOpt = 0b00001010000100011010;
  4. Save the file.
  5. Open the VTScada Application Manager and click the Import File Changes button for your application.

Further information about the bit-wise window options can be found in the parameters for theWindow Window function in the VTScada Function Reference.

Scale Page

Default applies the application property ScaleDisplayContent to the contents of this screen. Otherwise, you can choose to always or never scale the page.

If scaling the page, you can also choose whether to force the aspect ratio to be maintained. Default applies the application property, DispMgrAspectRatio.

If scaled, the larger of the page contents or the defined page size will be scaled to fit the operator's screen. The Idea Studio is not affected by this property.

Automated display scaling works reasonably well when enlarging the page. It cannot do as good a job when shrinking a display for a smaller screen. In particular, labels embedded within buttons or widgets are more likely to be truncated than scaled down.
Always design for the smallest screen that the application will be displayed upon. Further information is provided in Size Pages for Differing Screens

Manage Parameters, Parameter Values

By parameterizing a page, you can re-use the same page for similar sets of tags. For example, one control page can be used for a series of stations, if each station has the same hardware. See: Parameterized Pages

The Values button is enabled only when the page has parameters. When editing a page, widgets and other items that are linked to parameters may not be displayed unless a tag has been chosen for, or a value has been assigned to the parameter. Click this button to open the Manage Parameters dialog, where you may assign values to be used during the current editing session.

The Manage Parameters dialog will always be displayed when opening a parameterized page for editing, or when the navigational link to the page does not have values assigned to the page's parameters.

Page Security

Use this to apply an existing custom privilege to the page, thereby denying access to everyone who does not have that security privilege. (Note that security cannot be applied to widgets.)

If custom privileges have not yet been created, or if security has not been activated, this menu provides access to the security accounts and privilege dialogs, for developers who are authorized to access those dialogs.


Size Pages for Differing Screens

A common challenge is to develop pages that can be used on many screens where those screens may vary greatly in size, aspect ratio and resolution.

Helpful tools and techniques exist but there are limitations to what is physically possible. If you design a page to show a lot of information on a high-resolution, wall-sized monitor, then it cannot be displayed well on a low-resolution monitor or on a cell phone.

Terms:

It is important to have a clear understanding of the problem before attempting a solution.

Screen Size: A measure of how big the screen is. Screens are measured across the diagonal and the number may or may not include glass covered by the frame holding the screen. The horizontal and vertical dimensions of the screen will be less than the screen size.

Aspect Ratio: The relation of the longer side of the screen to the shorter side. Commonly expressed in the form, Long:Short. The most used aspect ratio for computer monitors at time of writing is 16:9.

Resolution: Strictly speaking, resolution refers to the number of pixels per unit area of the screen, expressed in the form "width x height". But on most computers, you can choose from a variety of different resolutions. The number of pixels in your screen doesn't change, but the way the image is displayed can make it look like it has. If your monitor can display 1920x1080 pixels but you configure it as 800x600, then your graphics system will use several pixels as if they were one. Note that the aspect ratio of a 1920x1080 resolution is 16:9, If the screen resolution is 800x600 then the aspect ratio is 4:3. Therefore, if you switch from a resolution with one aspect ratio to another with a different ratio, your video system will typically deal with the difference by leaving empty bars along the top or the sides. You may have experienced this while watching a movie at home in "widescreen mode". Alternatively, most displays will allow you to force one aspect ratio to fit another by stretching the image in one direction or the other, filling the screen but distorting the image.

Pixel: A term with two definitions. Screen pixels are the thousands of points of light that make up the screen. The maximum resolution of your screen matches the number of pixels in each direction. Image pixels refer to the uniquely painted rectangles that make up a raster (bitmap) image or text. If you scale up (zoom in on) an image, more screen pixels are used to display each image pixel and you see the rectangles. Both definitions are relevant to this discussion because image quality is very much affected by how image pixels map to screen pixels.

Pixel Density: The number of pixels per square inch. When comparing screens of similar size, the more the better in terms of image quality. If a small screen and a large screen both have the same resolution then the smaller screen must pack those pixels into a smaller area, hence a greater pixel density. A small screen with the same resolution as a large screen shows the same image, but it might be hard for a human eye to see the smaller details, thus making it seem that the image quality is less.

Device Width: (Related terms: "CSS Resolution", "CSS Width".) Attempting to squeeze a page that was designed for a 27" monitor onto a 4" phone seldom works out very well. Text becomes too small to read and detail within images too small to see. Two techniques are used to deal with this:

  1. Web designers create responsive web pages that change in layout when viewed on a small screen, hiding some components and requiring a user to scroll to see others that were previously visible on one screen. Responsive design is not possible in VTScada where pages are treated as single images, but you could provide alternate pages to your users for use on mobile devices.
  2. Cell phones and tablets are designed to use "CSS pixels per inch", which differ from the physical pixels per inch, automatically scaling everything to use more physical pixels per image pixel. This fact is especially relevant to developers who are creating screens for the VTScada Anywhere Client. Refer to https://mydevice.io/devices/ for a chart of values for common cell phones and tablets.

Examples:

When configuring your VTScada pages, the most important dimension is resolution, and to a lesser extent, screen size. At the time of writing, it is possible to purchase a 43-inch monitor with a resolution of 3840x2160 from a popular brand. Suppose that you are using one of these while creating your VTScada pages. A 43" monitor at 16:9 aspect ratio has a width of 37 inches.

Your client is using 24" screens. (21" wide, assuming the same aspect ratio.) If their monitors display the same resolution, then they will see your pages as you created them, but shapes and text will be just slightly more than half the size that you see. If the resolution remains the same as the screen shrinks, then the only difference from one screen to another is how big things will appear. The increased pixel density may result in some apparent improvement in the display.

Let's keep the screens the same but change the resolution. Your client is now viewing your page on a 43" monitor, but they have a model with a maximum resolution of 1920x1080. The graphics in your page were created to fill a width of 3840 pixels but your client can see only half that number of pixels at a time. Scroll bars appear (taking up more pixels) and the client must scroll left and right to see all the pixels you drew. Alternatively, they can ask their computer to scale the display so that it will fit, but this will degrade the image. If you try to view an image that was 100 pixels wide using only 50 pixels, then information must be lost.

Image scaling using a Paint program. Image 1 shows a VTScada dialog box, full sized. In image 2, the dialog was scaled to fit within a smaller number of pixels. In image 3, that scaled image is viewed at the same size as the original, simulating the effect of scaling to a smaller resolution on an equivalently sized monitor. The loss of detail is readily apparent.

Image scaling within VTScada. Image 1 shows a typical detail, full-sized. In image 2, the page was configured with the Scaled to Fit option and the page size reduced to approximately half the width and half the height in terms of pixels. This is equivalent to viewing the page on a monitor with a lower resolution. Image degradation is apparent in the text and all the widgets.

Note that different parts of a VTScada page will be handled differently: Title bars, the task bar, and things like the Tag Browser are handled differently than the objects within a page. Text in edit fields, droplists, and non-legacy buttons is not scaled. Due to the way that VTScada layers graphics, a slightly different result might be obtained by grouping all the objects in the page before scaling. This would not improve the result; it would simply change how scaling is applied to the content within the page. The point is that your results may vary.

Design for a Variety of Displays:

For desktop monitors, the best course of action is to find out the minimum screen resolution that your operators or customers will use to view your pages and then design for that by configuring your screen to match. This ensures that nothing will be clipped, and images will not be degraded by being scaled to use a smaller number of pixels. If viewed on a screen with a larger resolution, your pages will either take up less of the screen or will be scaled up. Scaling up may result in some blurriness as information that was displayed on one pixel is stretched across two or three but will not degrade the images.

Although significantly more work, you might consider creating alternate pages for use by screens with smaller resolutions. There is no way to automate the selection of a page by having VTScada sense the resolution of operator's screen so you will need to provide appropriate navigational links and instruct your operators on which to use.

That advice is also relevant when designing pages for use by the Anywhere Client but complicated by the fact that VTScada will resize your page to the device's CSS resolution, not its physical resolution. VTScada gives you some control over this, as it will resize for the greater of the device's CSS width (device width) or the VTScada minimum page size. Within VTScada, specify that minimum size as the minimum application window width and height using DispMgrMinWidth and DispMgrMinHeight or use a Realm Display Setup tag. The smaller that minimum size is (within reason), the less zooming will need to be done by Anywhere Client users.

Browser scaling with the VTScada Anywhere Client.

The Anywhere Client displays your pages within a web browser on the device of your choice. All web browsers offer the ability to scale the display, either by using a pinch-zoom or by honoring the key combinations Ctrl + and Ctrl -. If the page doesn't initially fit the display, then before attempting any solutions using VTScada, try scaling the display within your browser.

"Stretch contents of a page to fit available area".

This is an option in the Display tab of the Application Configuration dialog's Edit Properties page. After selection, you can configure each of your pages to either stretch or not stretch. You might choose to have full-screen pages stretch, but not pop-up pages, which are usually created to be smaller in size. The limitation of this tool is clearly illustrated in the example shown earlier in this document. Page stretching may help for a small range of screen resolutions but should not be used if the variation is large.

See: ScaleDisplayContent

Use Display Manager properties to control how pages are shown.

None of the following solve the problems of trying to display a page using half the number of pixels with which it was created. But they do offer you some control over how your pages are displayed. Note that properties can be configured to be workstation-specific, allowing you to change display characteristics to match a target workstation. In the case of thin clients, the workstation would be the VTScada Thin Client Server, and the workstation-specific properties would apply to all Internet connections.

  • DispMgrAspectRatio - Constrain the aspect ratio of a page window when users are changing the window size
  • DispMgrBMPMarginBottom - Sets the width of the bottom margin for a background image in a page.
  • DispMgrBMPMarginLeft - Sets the width of the left margin for a background image in a page.
  • DispMgrBMPMarginRight - Sets the width of the right margin for a background image in a page.
  • DispMgrBMPMarginsWin - Sets the width of all margins equally for a background image in a page.
  • DispMgrBMPMarginTop - Sets the width of the top margin for a background image in a page.
  • DispMgrFullScreen - Applies to the application in general, not pop-up pages. If set to 1 (true), the application displays in full screen mode. No Windows title bar is present (default).
  • DispMgrHeight - Applies to the application in general, not pop-up pages. Sets the height of the Display Manager. If set to Invalid (default) VTScada will fit the page to your screen based on the characteristics of your workstation. See also, DispMgrWidth.
  • DispMgrHoriz - Allows you to tile multiple pages on the screen, horizontally. DispMgrVert must also be configured.
  • DispMgrMinHeight - If the application window is resizable, sets the minimum height in pixels to which users can stretch the window.
  • DispMgrMinWidth - If the application window is resizable, sets the minimum width in pixels to which users can stretch the window.
  • DispMgrPageStyle - Provides control over title bar and task bar contents of the application window.
  • DispMgrResizable - Allows users to resize the application window, assuming that DispMgrFullScreen is not set True (1).
  • DispMgrTitleBorder - Sets the number of pixels used by the window title border.
  • DispMgrVert - Allows you to tile multiple pages on the screen, vertically. DispMgrHoriz must also be configured.
  • DispMgrWidth - See DispMgrHeight.
  • DispMgrWPageStyle - Provides control over title bar and task bar contents of pop-up windows.
  • DispMgrX and DispMgrY - Sets the upper left coordinate where the application window will open if not in full screen mode.
  • ScaleDisplayContent - If enabled, page contents will scale to fit the available area. When enabled globally for the application, can be enabled or disabled for each page.
  • StretchBackground - Applies to background images within a page.

See: Display Manager Properties

Realm Display Setup tags.

These affect VTScada Internet Clients (VIC) and VTScada Anywhere Clients, but not Mobile Internet Clients (MIC) or VTScada workstations. Realm Display Setup tags allow realm-by-realm configuration of the window size, minimum window size, and level of user control to change window size and scale. They can also control what items are displayed in a page's title bar and task bar and select the default startup page to be shown when a client connects. Realm Display Setup tags do not change page scaling.

Use Realm Display Setup tags with care. More than once, a user called technical support after experimenting with this tag, forgetting that it was created, and then being stymied when a VIC or Anywhere Client window was locked to an unexpected size.

See: Realm Display Setup Tags


Configure for Multiple Monitors

Configuration for a multiple-monitor display, or multi-page display on a single monitor, depends partly on your hardware and partly on VTScada configuration options.

If you wish to implement a multiple-monitor display in legacy mode (i.e. with DispMgrExtendedDesktop set to 0, or invalid), you will probably want to use a graphics card the supports the stretching of a single display across multiple monitors. Terms used may include "video wall", "stretched desktop", "spanned desktop". If your graphics hardware is limited to a single display, your application may end up with multiple display manager windows on a single monitor.

Typical Configuration:

For a modern multiple monitor configuration, using conventional graphics cards, in the Application Configuration dialog of VTScada, set the property, DispMgrExtendedDesktop to 1.

Doing so will cause VTScada to base the size of individual monitor displays on the total dimensions of the Windows desktop for multi-monitor support.

Note the following:

  • All monitors must be set to the same display resolution (e.g. 1920x1200).
  • The layout defined byDispMgrHoriz andDispMgrVert must match the layout defined using the Windows display settings. See also: DispMgrExtendedDesktop.
  • Both DispMgrHoriz and DispMgrVert must be configured.
    There is no effect if you configure only one.
  • The top-left monitor must be set in Windows as the primary monitor.
  • Normally, correct configuration would involve not setting DispMgrWidth and DispMgrHeight, and would require DispMgrTitleBorder = 0. If you insist on setting DispMgrTitleBorder to 1, DispMgrWidth and DispMgrHeight must be set to the actual resolution of the monitor, minus the Windows title bar height.
  • This configuration covers the Windows task bar.
  • Use a Realm Display Setup tag for multiple-monitor configurations using the VIC. Multiple-monitor support is not available for the Anywhere Client.

Define Startup Pages

Each monitor can have its own startup page. Define these using a set of application properties named according to the pattern "DispMgrStartupPageX = PageName" where "X" is the index number of the monitor (Starting from 1) and PageName is the name of a page as defined in code. (Instructions to find this name follow.)

See: Add a Property

Find a page name:

The visible name of a page is a display property and it is possible to use the same name for more than one page. To keep track of pages at the code level, VTScada ensures that each is defined with a unique name. You could discover these using the Source Debugger but it is simpler to refer to each page's Menuitem entry in the Tag Browser: Look for the Contents column as shown:

(A whimsical name is used here for the sake of the example and to emphasize that the defined page name might not always match its file name.)

Automated display scaling works reasonably well when enlarging the page. It cannot do as good a job when shrinking a display for a smaller screen. In particular, labels embedded within buttons or widgets are more likely to be truncated than scaled down.
Always design for the smallest screen that the application will be displayed upon. Further information is provided in Size Pages for Differing Screens

Related information:

DispMgrHoriz

DispMgrVert

DispMgrHeight

DispMgrWidth

DispMgrExtendedDesktop

DispMgrTitleBorder

DispMgrStartupPageX


Page Shuffling

You can configure your application to show a series of pages in order, automatically. (In other words, a slide show.) To do so, you must configure a set of related application properties; there is no user-interface tool for this feature. Examples are provided with the property descriptions.

Begin by creating the list of pages to be included in the automated display. (PageShuffleList, PageShuffleEnable) Set the display time for each page (PageShuffleDelay) (either one time for all, or a distinct time for each) and a duration for which shuffling will be disabled when an operator action such as a key-press or mouse movement is detected (PageShufflePauseDuration). You can also set a list of realms for which shuffling is enabled (PageShuffleRealms). All selected realms will display the same set of pages for the same duration - there are no realm-specific configuration options.


Parameterized Pages

A parameterized page is one that can be reused for similar equipment installations. For example, your application may have multiple lift stations, each housing the same (or similar) equipment. The design of each page shows the equipment and differs only in which set of tags is being shown in a particular station.

Rather than create a separate page for each station, create one. But, link the widgets to parameters in the page rather than tags in the application. Navigational links to the page control which set of tags is used for the parameters when the page is opened via a particular link.

Pages can have a maximum of 100 parameters. If your page requires more than 10, you are encouraged to re-think your design. Perhaps Tag Widgets would be a better solution?

In the following example, a single control page was created, but it can be used for both pump 1 and pump 2 because the widgets are linked to parameters and a different set of tags is used for the parameters in each case. The page title uses a parameter within an expression so that operators will know which pump is being controlled.

A single page, opened twice, showing tags from two separate pumps.

Parameters are typically linked to tags, but this is not a requirement. Parameters can be defined to hold numbers or text as well as tags. In all cases, the navigational link to the page must be configured to supply the value or tag to be used by each parameter.

Add parameters to a page using the Manage Parameters button in the ribbon, as shown. This button opens the Edit Parameters dialog, where you can view, edit or add parameters.

Manage parameters, button and dialog from the Page Properties ribbon

Clicking Add opens the following dialog, where you can configure the new parameter.

Adding a tag parameter to a page.
The type is a user-defined tag in this example

The example shows a new parameter being configured. Recommended practice is to ensure that the parameter name is unique, avoiding any conflict with tags or other named objects. The description field should guide developers or operators when selecting the tag or value for the parameter. If the parameter is of type tag, you would typically select which types can be used, thereby guiding later selection of tags to types that are appropriate. Use the Ctrl key to select more than type. Type selection is optional; if none are chosen then tags of all types will be available for use with the parameter.

The same dialog is used when editing existing parameters.

Parameterized pages and plain widgets use parameters in the same way and share configuration dialogs.

Only text parameters can be marked as non-translatable. (Other types are never translated.) Select this for text that should never be translated, such as I/O addresses.

Removing Parameters:

By design, there are no tools in the user interface to delete parameters. The easiest way to remove one is to use the Version Control Version Control system to find the change where the parameter was added to the page and reverse that. Otherwise, if you are certain that a parameter is not needed and that it cannot be edited to use for a new purpose, then experienced developers can remove parameters by editing the page's source code, then importing the changed file.


Link Parameters to Objects in a Page

Nearly every property of nearly every object that can be drawn on a page can use a page parameter as its data source.

Parameters can also be used for scaling, movement and opacity.

Or for example, text. Given a page that contains a line of text and also a text parameter...

A parameter of type, Text.

You can open the Edit dialog for the text and choose an alternate source for the words that are to be displayed.

Expanding the data source, then choosing the option, Parameters

When the data source is set to Parameter, a drop-down selection of the parameters in this page will be available.

Selecting the specific parameter for the text.

The text will now display whatever is provided for that parameter when the page is opened.

Tag Parameters

If the parameter is a tag, then you have the option of selecting parameters, variables, or child tags with their parameters and variables.

This parameter is a user-defined type with child tags.
Text in the page uses a property (HighScaleValue) from one of those child tags.

Parameter Values within the Idea Studio

If you happened to try the steps described in the previous example, your text would now look like the following in the Idea Studio:

Text with a blank parameter.

While working in the Idea Studio, the parameter has no value. You are advised to provide parameter values that are just for use within the Idea Studio so that you can see objects as operators will. To do so, click the Values button in the Page Properties ribbon:

The values you set in the resulting dialog do not become defaults. They are for use only within the Idea Studio. But there, they are very helpful in making the page look realistic and ensuring that text doesn't disappear.


Setting Values for Parameters

The value for each parameter in a page comes from the link to that page. This can be the Menu Item tag or it can be a page hotbox or page button widget.

Setting a parameter value in a page Menu Item and in a page button widget

If you create a link to the page but don't provide values for the parameters then your operators will be prompted every time they open that page.

"Underspecified" is programmer-ish for "value not provided"

As a general rule you should provide values for all the parameters in a page in every navigational link that you give to operators. (Parameterized Pages)

At the same time that you edit the navigation links to add parameter values, it is a good idea to change the label or title of the link so that operators will know what to expect when they open the page.

Advanced VTScada developers can use DecodeParms DecodeParms to query the parameter values of existing MenuItem tags.


Expressions in Page Titles

If you use parameterized pages, you should make sure that operators know which tags they are working with when they open that page. You could do this by using parameterized text at the top of the page. You can also do this by adding an expression to the page title that will use a parameter or a value from the linked tag.

The page title can be edited using a tool in the page properties ribbon:

Editing the page title

If your page has a text parameter and you want to use that in the title expression, just type the name of that parameter. For example:

Using a text parameter for the page title.

If your page has a tag parameter and you want to use the name or description or some other property of that tag, then do so by adding a backslash after the parameter and the name of the tag property that you want to use. If the tag in question is a parent, you can use any property of any child tag within the structure.

Using the short name of whatever tag is specified for the parameter pPumpChoice


Widgets versus Parameterized Pages

Widgets and pages share a number of features:

  • Both are created using the same tools of the Idea Studio.
  • Both can display tag values and other contextual information.

They also have important differences:

  • You can navigate to pages, but not to widgets.
    Widgets can only be seen when drawn on a page.
  • Widgets can be linked to tags and can make use of linked tag properties.
    You can't link a tag to a page the same way that you can link a tag to a widget. You could write expressions in your pages to achieve a similar result, but this is more difficult.

When creating custom widgets, parameterized pages, and also custom tag types, your goal should always be to reduce repetitive work. If you have only two stations, then just create the tags for the two stations. Create a page for each station, copying objects from the first to the second where convenient.

But if you will have 20 or more stations, and each station can have two or ten pumping systems or other equipment, then create a custom tag for all the I/O in the equipment and create a tag for a station.

Move as much configuration work as possible to the top. For tags, this means creating parameters in your Context tag for everything that needs to be configured in the child tags. Then use expressions in the child tags to pull information from the parent context, performing math or string concatenation where useful.

All the configuration for all these child tags is done within the parent, tag.

For widgets, it means creating a custom widget that can be linked to one of your user-defined tags and that represents some or all of the I/O within that tag.

The widget shows five I/O, but links to only one tag.

For pages, it means creating a parameterized page that displays one or more of your custom widgets, passing the appropriate tag for the widget(s) through parameters when the page is opened.

This page has one parameter for the station, not 18 for the I/O shown.


Ribbons

(Reference topic)

Many of the object creation, formatting and alignment tools, available to the Idea Studio, are stored in ribbons across the top of the page. Several ribbons exist, but only the Home ribbon will be visible at all times. Other ribbons contain properties or formatting tools and will be visible only you have selected objects of a given type.

Home Ribbon

Clipboard tools:

Cut Copy and Paste are standard tools for duplicating objects.

Manage Tools:

Both Tags and Page Menu open the Tag Browser. The difference lies only in the branch of the tag tree initially selected: Menu Items or other.

Insert:

Contains the three elements most commonly used when building a user interface: Text, Line and Pipe.

Actions:

Select contains a menu of object selection tools, including the ability to select all objects of any given type.
Zoom contains a series of preset display scales, and a link to a slider where you can adjust the display scale by any percentage.

Arrange:

Tools for changing the display order and alignment of selected objects. Also include in this section are tools for matching properties across all elements in a selection set, and to group objects together.

View:

Open or close the Palettes window.

Open or close the Panels window.

Enable or disable the unlinked indicator display, so that you can track which widgets are not yet linked to any tag.
Open the source code file for the current page. Changes made to any page must be imported via the VAM (VTScada Application Manager) before they will be used by the application.

Page Properties Ribbon

Background:

Add color or an image to the page background

Display:

Tools to adjust all visual aspects of the page besides the background.

Parameters:

Create a parameterized page (or widget), then adjust the values used for the parameters.

Advanced:

Prevent unauthorized access to a page by adding a custom privilege. This tool also provides access to the Security system, where you can create custom privileges and grant those privileges to accounts. If editing a page, you can use Tag Types and Drawn Context to modify the types that are or can be linked to the widget.

Widget Properties Ribbon

Used when editing a user-defined widget.

Background:

Set a background color for the Idea Studio and the palette. Not included when the widget is drawn on a page. Background images are not available for widgets.

Display:

Change the name of the widget. Select an image that will represent the widget in the palette.

Parameters:

Add and control parameters, if any are associated with the widget.

Advanced:

Edit the list of tag types that can be linked to this widget. Select a particular tag to use for the instance shown in the editor.

Widget Tools Ribbon

Used when editing a widget instance, drawn on a page. If the widget contains images the Image Tools ribbon will also be available.

Clipboard tools:

Cut Copy and Paste are standard tools for duplicating objects.

Insert:

Contains the three elements most commonly used when building a user interface: Text, Line and Pipe.

Configuration:

Open the Properties dialog for the selected widget, or link it to a tag. Edit applies only to widgets of your own creation, opening the configuration page for that widget.

Display:

Adjust the opacity of the widget, or open the Properties dialog to one of the menu items, Scaling, Movement or Coordinates.

Arrange:

Tools for changing the display order and alignment of selected objects. Also include in this section are tools for matching properties across all elements in a selection set, and to group objects together.

Image Tools Ribbon

Clipboard tools:

Cut Copy and Paste are standard tools for duplicating objects.

Insert:

Contains the three elements most commonly used when building a user interface: Text, Line and Pipe.

Adjust:

Mirror and Anti-alias are toggle buttons that can be switched on or off. Other tools provide a range of control over all aspects of the image's color, and brightness.

Display:

Adjust the opacity of the widget, or open the Properties dialog to one of the menu items, Scaling, Movement or Coordinates.

Arrange:

Tools for changing the display order and alignment of selected objects. Also include in this section are tools for matching properties across all elements in a selection set, and to group objects together.

Shape Tools Ribbon

Clipboard tools:

Cut Copy and Paste are standard tools for duplicating objects.

Insert:

Contains the three elements most commonly used when building a user interface: Text, Line and Pipe.

Style:

Adjust the display properties the shape's fill or outline.

Display:

Adjust the opacity of the widget, or open the Properties dialog to one of the menu items, Scaling, Movement or Coordinates.

Arrange:

Tools for changing the display order and alignment of selected objects. Also include in this section are tools for matching properties across all elements in a selection set, and to group objects together.

Text Tools Ribbon

Clipboard tools:

Cut Copy and Paste are standard tools for duplicating objects.

Insert:

Contains the three elements most commonly used when building a user interface: Text, Line and Pipe.

Color:

Adjust the color and opacity of the text's foreground or background.

Font:

Select the font characteristics that should be used for the selected text.

Paragraph:

Adjust the vertical and horizontal alignment of the text within its bounding area.

Saved Fonts:

Choose an existing font (as stored in a Font tag) or save the current configuration as a new, or updated existing Font tag.

Edit Text:

Opens the edit text dialog for the selected line of text.

Display:

Adjust the opacity of the widget, or open the Properties dialog to one of the menu items, Scaling, Movement or Coordinates.

Arrange:

Tools for changing the display order and alignment of selected objects. Also include in this section are tools for matching properties across all elements in a selection set, and to group objects together.


Panels

Panel tabs as icons and...
expanded to show tab names.

The Panels area of the Idea Studio is initially closed, but will open automatically when you select a multi-image widget (such as an indicator light) or when you select two or more objects. You can open and close the panels using any of the following:

  • The panels tool in the Home ribbon.
  • Double-click the splitter bar between the panels and the drawing area.
    (A vertical white bar, about 4 pixels wide, easily mistaken for the right border of the Idea Studio when the panel is closed.)
  • Drag the splitter bar.
  • Select a multi-image widget.
  • Select two or more objects in the drawing area.

Tag Links Panel

Simplify the task of selecting widgets and keeping track of which widget is linked to which tag.

Search and replace tag-links on a page by name.

Multi Image Widgets Panel

When editing images within a selected widget, choose which parts to change and which to leave be.

Layers Panel

Simplify the task of selecting (or not) overlapping objects.


Tag Links Panel

The Tag Links panel helps you keep track of which widget is linked to which tag (or remains unlinked). It can be helpful when selecting widgets on a crowded page because each item you select in the list is simultaneously selected on the page.

Detail from the tag links panel showing a widget linked to one tag

The list is sorted alphabetically by linked tag name, re-sorting as each link is made or changed. Unlinked widgets are always at the top of the list.

Limit the list to those selected, or show all in the current drawing area.

Edit the links by clicking on a link to see a tag browser button at the right, and a data source selection at the left. On the page, the matching object will be marked with a bold selection window, becoming the anchor object in the selection set.

Tools for linking are identical to those in the selected widget's properties dialog.

Search and replace tag links

Given a set of selected widgets, you can replace several tag links in one step by using the Search and Replace button of the Tag Links panel.

For example, you may have drawn a set of widgets related to Pump 1 on a page. You also have a similar set of tags for Pump 2 and for Pump 3, each of which must be drawn on its own page.

The preview of the search and replace operation is updated as you change each field. The links are not changed until you click the Replace button.

Preliminary Steps:

  • You have created I/O tags for Pump 1, Pump 2 and possibly others.
  • You have created a page for Pump 1 and linked those widgets to the tags for Pump 1.
  • You have cloned the Pump 1 page, to create a page for Pump 2.
    All the copied widgets are still linked to Pump 1.

Open the Search and Replace dialog

Steps to search and replace:

  1. Open the Tag Links panel.
  2. Click the Search and Replace button.
    The Search and Replace dialog opens.

You can also use wildcards.

  3. Type "Pump 1" in the field, Search for this string.
    All links that have "Pump 1" anywhere in the link are selected. The preview operates immediately, replacing "Pump 1" with an empty string in every link. The status will change to "Bad tag reference." Nothing will happen to the widgets until you click Replace at the bottom right of the dialog.
  4. Type "Pump 2" in the second field, then press tab or enter.
    The links will be updated to use Pump 2 in every case that previously used Pump 1.
  5. Click, Replace.

Note that you have the option of deselecting any links that matched the search but should not be changed.


Multi Image Widgets Panel

Opens automatically when any widget composed of multiple images is selected, including any that have just been drawn. The panel can also be opened or closed using a tool in the Home ribbon.

The automatic-open feature can be disabled using a check box at the bottom of the panel.

When widgets containing component images are selected for editing, both the Widget ribbon and the Image ribbon are enabled. You can change the image used by the widget, and change all of the formatting characteristics of that image.

If the widget has multiple images, as is the case with the toggle switch, indicator lights, selectors and others, then you can choose which of the component images should be affected by certain formatting changes.

Changes from the Adjust section of the formatting ribbon will apply to the selected component images. Changes from the Display section apply to the overall widget. For example, note that the Display section has a Rotation command, which will be applied to the full widget, while the Adjust section has an Image Rotation command, which will apply only to the selected component images.

All selected images will be added to the list, with their component images separated by relevant action or state.

A typical view of the panel
with one selected widget.

This feature gives you a fine level of control over image editing within widgets, and is also useful for making global updates to widgets. For example, you might need to change a large number of pump widgets from the old model to a new version. You can also use this feature to update a set of Image Change widgets to use a new color scheme for each state. (The states of an Image Change cannot be linked to a Style Settings tag, therefore the color selection for each state must be set directly.)

Use the Multi-Image Widget palette:

Rotating both images in a widget.

Editing only one image of a multi-image widget

Your choice.

The auto-open behavior of the Multi-Image Widgets panel is under your control. You will find the option to disable it at the bottom of that panel.


Layers Panel

While you cannot create separate layers within the Idea Studio, the Layers panel gives you most of the same features.

All selected objects are listed in this panel. The highlighted row in the panel list matches the current anchor object within the selection set.

With the Layers Panel, you can:

  • Left-click once on any item in the list to make that the anchor object.
  • Move objects up and down the list to move them forward or back in the display order.

    Use the arrows at the bottom of the panel or click and drag the row.
  • Right-click on any object to open a menu as shown. With this, you can:
    • Open the object's properties dialog.
    • Make that object the only one selected.
    • Remove the object from the selection set.
    • Copy or cut the object matching the selected row.
    • Delete the object matching the selected row.

Use the tools at the bottom of the panel to

  • Change the display order of a selected item in the set (up and down arrows)
  • Deselect the option of automatically opening the panel when more than one object is selected.
  • Use the slider to change the size of graphics in the list.


Shapes, Pipes, Lines

Shapes are geometric objects. Like images, they are used to provide visual context for a page. Shapes include rectangles, ellipses, stars and more. All shapes have an outline and most have a fill, both of which can be configured independently as to style, width, and color. You can set either the outline or the fill to "none", removing that part of the shape from the display.

Shapes have no "Link" option to tie them to a tag. They are essentially static, although any property (movement, scaling, etc.) can be animated by specifying a tag value or an expression to provide its value.
The Style Settings tag has no effect on shapes and should not be linked to any property.

To add a shape to a page:

  1. Open the Idea Studio and open the page, to which you want to add a shape.
  2. Open the Shapes palette.
  3. Drag a shape from the palette to your page.
  4. Adjust the size, location and other properties of the shape as required.

A format ribbon is available for each widget type.
Advanced configuration details can be accessed by opening the Properties dialog of the widget.

Troubleshooting:

  • The image is too big / too small.

All images have an initial size, which may be wrong for your application. After the image is placed, zoom in or out on the canvas until you can see the edges easily, then select the image and drag the corner grips to resize it.

Every shape can be scaled, stretched, rotated, colored, and more after being dragged to a page. All shapes have an outline, and all except for arcs have a fill. The appearance is controlled by tools in the formatting ribbon, or by each shape's properties dialog.

A variety of shapes, with a variety of outlines and fills.

Shapes have no "Link" option to tie them to a tag. They are essentially static, although any property (movement, scaling, etc.) can be animated by linking it to a tag value or to an expression.

The Style Settings tag has no effect on shapes and should not be linked to any property.

After drawing the shape on a page, you can adjust its appearance using either the ribbon tools or the shape's properties dialog. The properties dialog for a rectangle, with the Advanced options opened is shown in the following example. All shapes will have a similar properties dialog.

Advanced properties for fill.

Fill - Color, Pattern, Background

Only color will be available unless you expand the advanced options. Click to open the Select Color dialog.

Click the pattern option to view a selection of shapes that can be used for the fill: brick, zigzags, etc.

Each shape is drawn using lines of the current color selection, against a background color of your choice.

Outline - Color, Style, Width

Only color will be available unless you expand the advanced options. Click to open the Select Color dialog.

The style option can be used to select the pen style, (solid or dashed), that will be used.

The default width is one pixel, but may be increased to a maximum of 30.


Pipes

Pipes can be drawn in any color, and have any width from one to thirty pixels. Each new pipe uses the color of the last pipe you drew in the current session.

As you draw a pipe, each segment will snap to an angle that is some multiple of fifteen degrees. To release this feature and draw at any angle, hold down the Ctrl key on the keyboard as you move the mouse. Pipes respond to alignment lines with other objects. Hold down the Ctrl key to release alignment snap.

Pipes do not have rounded corners, but after drawing a pipe you can add images from the extensive collection of pipe fittings, available in the Images palette.

To draw a pipe:

  1. Open the Home ribbon in the Idea Studio, and click the Pipe tool.
    The tool can also be found in several other ribbons.
  2. Click once on the page, where the pipe is to begin.
  3. Move the mouse and click again to mark the end, or the next corner.
  4. Continue, adding as many segments as required.
    To remove points while drawing, press either the backspace key or the delete key, as many times as needed to remove vertices in the reverse order that you added them.
  5. To stop, right-click after placing the final endpoint of the pipe.

Change a pipe's color and width:

Having drawn a pipe, you can adjust both the color and the width using the Outline button in the formatting toolbar. Note that pipes do not have a fill property. Selecting the option, No Outline from the menu is the same as choosing "invisible" instead of a color.

Relocate a pipe:

A selected pipe has two types of handle: a white square at each endpoint and a blue dot in the middle of each segment.

  • Drag an endpoint handle to relocate that corner or end.
  • Drag a middle dot to add a new corner.
  • Click and drag between handles to move an entire segment. Any connecting segments will stretch with the segment that was moved.
  • To move the entire pipe, select it then tap the arrow keys to nudge the object one pixel at a time.


Lines

Lines can be drawn in any color, and have any width from one to thirty pixels. By default, each new pipe will be black, and have a width of one pixel. Lines differ from pipes in that they do not have a gradient shading.

As you draw a line, each segment will snap to a multiple of fifteen degrees. To release the snap feature and draw at any angle, hold down the Ctrl key on the keyboard as you move the mouse.

Multiple segments that lie along a straight line will be merged into a single segment.

To draw a line:

  1. Open the Home ribbon in the Idea Studio, and click the Line button.
  2. Click once on the page, where the line is to begin.
  3. Move the mouse and click again to mark the end, or the next corner.
  4. Continue, adding as many segments as required.
    To remove points while drawing, press either the backspace key or the delete key, as many times as needed to remove vertices in the reverse order that you added them.
  5. To stop, right-click after placing the final endpoint of the line.

Change a line's color and width:

Having drawn a line, you can adjust both the color and the width using the Outline button in the formatting toolbar. Note that lines do not have a fill property. Selecting the option, No Outline from the menu is the same as making it invisible.

Relocate a line:

A selected line has two types of handle: a white square at each endpoint and a blue dot in the middle of each segment.

  • Drag an endpoint handle to move that corner or end. If you straighten a path by dragging a corner into line between connecting corners, the handle will be removed.
  • Drag a middle dot to add a new corner.
  • Click and drag between handles to move an entire segment. Any connecting segments will stretch with the segment that was moved.
  • To move the entire line, select it then tap the arrow keys to nudge the object one pixel at a time.


Images

Images provide visual context for a page. They may be maps, photographs or drawings of equipment, flow charts or anything else. A selection of photo-realistic background images of water, metal, stone, and more are available, as are lighting overlays. Note that these can be scaled or tiled to fill an area.

Images have no "Link" option to tie them to a tag. They are essentially static, although any property (movement, scaling, etc.) can be animated by linking it to a tag value or to an expression.
The Style Settings tag has no effect on images and should not be linked to any property.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Add an image to a page: (Method 1)

  1. Open the Idea Studio and open the page where the image should be added.
  2. Open the Images palette.
  3. Click on a group to view the images within it.

If required, click the home button at the top of the folder list to return to the top level and select a different folder.

  4. Drag an image from the palette to your page.
  5. Adjust the size, location and other properties of the image as required.

Most tools are available through the image format ribbon.
Advanced configuration details are available by opening the Properties dialog of the image.

Add an image to a page: (Method 2)

  1. Open the page in the Idea Studio.
  2. Open Windows Explorer and find an image on your computer.
  3. Drag the image from Windows Explorer to the page in the Idea Studio.
    The Imported Images folder of the Images palette will be revealed, and the image will be imported to your project and added to that folder.
  4. Click OK in the New Menu Item dialog to accept the defaults. (Or, edit as needed before clicking OK.)
  5. Adjust the size, location and other properties of the image as required.

Troubleshooting:

  • The image is too big / too small.

All images have an initial size, which may be wrong for your application. After the image is placed, zoom in or out on the canvas until you can see the edges easily, then select the image and drag the corner grips to resize it.

Select Image Dialog

The Select Image dialog is used when changing an existing image.

Folders can be opened with a click. A click on an image will select it, completing the Select Image operation. New folders can be created, and new images imported using the buttons at the bottom of the Select Image dialog.


Import Images

Even though several thousand images are included with every copy of VTScada, it is likely that you will want to use your own images from time to time.

• You can create new folders for your imported images (described following). Doing so will help you keep those images organized.
• No image may measure more than 10,000 pixels on either side.
You should keep your images as small as possible in terms of overall pixels. Most VTScada images are less than 200 pixels wide or tall. Larger images will slow the response time of your pages.

Folders can be created using the same dialog box that opens when importing an image, as described in the following steps.

Palettes and the items within them such as images and folders, are organized and stored in Menu Item Tags. The following steps will therefore refer to menu items. The same result can be obtained by starting with the Tag Browser where menu items can also be created, edited, and shuffled using Menu Item entries in the Tag Browser.

Note that you can select multiple tags in the Tag Browser's main window by holding down the Ctrl key while selecting. Use this to copy, move, or delete several tags at once.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

To import an image, Method 1:

  1. Open the Images palette of the Idea Studio.
  2. Open a folder for the image to be imported.
  3. Click the Import Image button.

    The New Menu Item Properties dialog will open.
    It is at this point that you could choose to create a new folder before repeating the steps to import images to that folder.
  4. Click, Image in the New Menu Item Properties dialog.
    The Import Image dialog will open.
  5. Browse for and select the image to be imported.
    The New Menu Item Properties dialog will display a preview of the image, and its properties.
  6. Click OK.
    The image will be added to the open folder.

To import images or a folder of images, Method 2:

  1. Open the Images palette of the Idea Studio.
  2. Within the palette, open a folder for the image or images to be imported.
  3. Open Windows Explorer and find the image or images that you want to import.
    Note that you may select multiple images, or a folder of images.
    If you select a folder, VTScada will attempt to create a matching folder within the palette before importing the images.
  4. Drag the image from Explorer to the palette.
    The New Menu Item Properties dialog will open. In most cases, there is no need to change any parameters within this dialog.
  5. Click OK.
    The image will be imported and added to the current folder at the bottom of the list.

Method 2 works equally well if you drag the image to the editing canvas rather than to a palette folder. The difference is that the image will be saved to the folder, "Imported Images" instead of a folder of your choice.

Remember that you can edit the Images palette as you see fit.

Troubleshooting:

  • The image is not visible after being imported.

It may be necessary to scroll through the images of the current folder to find the one you imported.

  • The image is in the wrong folder.

Use the Tag Browser to reorganize the palette.

Note that you can select multiple tags in the Tag Browser's main window by holding down the Ctrl key while selecting. Use this to copy, move, or delete several tags at once.


Decorations

Decorations are images that you add to a page to enhance other objects. Examples include lighting overlays, tiles & textures, folders, frames and tooltips. Some are widgets (plain widgets, which may have parameters) and some are images.

The following example illustrates how decorations such as tiles and lighting overlays can enhance your application


Border

Borders are most often used to provide a visual indication to operators that a set of controls have some common purpose. Borders can appear raised or sunken relative to the rest of the page, and can be transparent or shaded.

You can find the Border image in the decorations folder of the Images palette.

The properties dialog for a border:

Colors

By using the default option of System Colors, you can make your borders look similar dialog boxes used by your operating system.

The fill is the background color of the border's area. The highlight and shadow are used to make the border appear raised or sunken by simulating light shining on one edge or the other.

If you choose your own fill color, it is recommended that you use a darker shade of the same color for the shadow and a lighter shade of that color for the highlight.

Attributes and Width

Selection option for the visual effect that will be applied to the border. The difference is in the choice of the order of the shadow and highlight lines around the fill area.

Widget Folders:

Decorations


Grid

The grid shape creates a rectangular area of any color, visually divided into smaller rectangles by lines.

The background and the lines can be given any color you prefer, or either can be made transparent. Lines may be solid or dashed.

You can find the Grid image in the decorations folder of the Images palette.

The properties dialog for the grid:

Columns and rows

Control over how many cells will be included in the grid. Cells are always uniform in size.

Colors and Line Style

Click to open the Select Color dialog for each part of the grid. Six line styles are available, including invisible.

Widget Folders:

Decorations


Folders

The Folders widget creates a user-interface object with multiple tabs where each tab has a separate display of system monitoring and control objects. The tabs are used to select which frame to display.

Three styles of folder are provided in the palette, but these are all variations on the same widget.

(See Style, later in this topic.)

A folder may have from one to fifteen tabs. You have extensive control over the appearance of the folder and the tabs within it.

The content for each tab's frame must come from an existing object in your application. These may be pages, tag widgets, or plain widgets. You do not draw objects on a folder as you would on a page.

There are two parts to a folder's configuration: The first defines the overall style of the folder. The second controls the content and the appearance of the individual tabs.

If your pages include tabbed folders, then the Unique Key property of the folder must be set in order for tabs to function when viewed using a Mobile Internet Client.

As a general rule, define the tab setup first, then adjust the style to your preferences.

Define a Folder's Overall Style

The Style tab of the folder configuration:

Style

The folder may use any of the following three styles. Each folder style can be further refined with a selection of tab styles, which may differ between the selected and the unselected tabs.

Tab Label Margin

Sets the number of pixels above the tab labels. A large margin value may increase the height of the tabs, but will not increase the width - if necessary, the label will be truncated to provide the required margin within a given tab width. The overall folder width, divided by the number of configured tabs, controls the width available for each tab.

Selected Tab's Frame Setup

The shape of the tabs themselves and the area below the selected tab are controlled by the Frame Setup selection. If either Frame Tabs or Frame Buttons are selected for the overall style, then you may further refine the shape by selecting one of the six built-in frame designs. See Frame for details. The System Tabs style does not allow for further refinement of the frame.

Selected Tab's Label Color

Opens the Select Color dialog, from which you can choose the color, in which the selected tab's text will be displayed. To emphasize that a tab is selected, it is best to choose a color with high contrast from the tab's color.

Unselected Tab's Frame Setup

Provides the same set of options as for the Selected Tab's Frame Setup. Use care with this selection: by choosing a raised frame for the selected tab and a flat or sunken frame for the unselected tabs, you can provide a clear visual message to the operator to help them see which tab is selected. Choosing a frame for the unselected tab that is a completely different style from that of the selected tab may cause confusion.

Unselected Tab's Label Color

Sets the color of the text to use for the labels on the unselected tabs. This should have a low level of contrast against the tab's background color to indicate that the tabs are not selected, yet still have enough contrast to read easily.

Font Style

Select a Font tag to define the appearance of the tab labels.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Unique key for saving selected tab

Variables such as dialog positions and sizes are normally retained per-user and per-module. What this means for the folder is that the "Last viewed tab" would be saved, but shared across all folders.

By providing a unique key to this parameter, each folder drawn in an application can save its own last viewed tab. If used, the key may be any phrase such as, "Main Station Display" or "Treatment Plant Panel".

If the folder is used in a parameterized page, it will be necessary to have a different key for each version of the page that you open. Therefore, this property may be linked to a page parameter or expression.

Tab #

Sets the starting / current tab number, with "1" as the default.

You may use an expression to change the current tab dynamically as required.

Define a Folder's Tabs

The number of tabs, the label for each, and the content of each tab's frame are defined with the Tab Setup.

The table in the center of this panel displays a summary of each tab's configuration and can be used to re-order their appearance in the folder. Use the controls above or below the table to modify the tabs.

Number of Tabs

May be any value from one to fifteen. This changes only the number of tabs displayed, not the number that exist. If you configure four tabs, then drop the number to three, you will have hidden the fourth tab, not deleted it.

Move Selected

Tabs may be re-ordered. They are displayed left-to-right across the folder in the order that they appear from top to bottom in the table.

Tab Layout

Provides control over how the contents of the tab fit into the folder size.

  • The margin, measured in pixels, will ensure a set amount of blank space around the contents. If the area of the folder plus the margin is smaller than the selected content, then the content will be scaled down to fit.
  • If Stretch to Fit is selected, the folder content will be expanded to fit the available size.
  • The Maintain Aspect Ratio option controls whether the content may be deformed when being stretched or shrunk.
  • Finally, the Horizontal Alignment and Vertical Alignment options control how content that is smaller than the folder will be placed within the available space.

Tab Contents

For the selected tab, you may provide the text for the label and the contents of the tab's frame.

Any one of three types of object may be used for the tab's contents: Tag Widget, Plain Widget or Page. The specification of the contents depends on the content type. See following examples.

Steps to use a Tag Widget:

  1. Select Tag Widget as the Widget Type.
    The Context field (reading "No tag selected") will be enabled. You can configure this to use a tag, a parameter or a linked tag property. The linked tag property option is used only when the folder is being drawn within a user-defined widget.
  2. Select a tag, parameter, or linked tag property.
    The Select Widgets button will be enabled. For example, if you select an Analog Status tag for the content, you can then choose from any of the Analog Status widgets.
  3. Click the Select Widget button to choose from the available representations of this tag.
    The Set Parameters button will be enabled.
  4. Click, Set Parameters to configure the widget's appearance.

Steps to use a Plain Widget:

  1. Select "Widget" as the Widget Type.
    The Context field (reading "No tag selected") will be enabled. You can configure this to use a tag, a parameter or a linked tag property.
  2. Click the Select Widget button.
    A palette will open. You may use any folder.
  3. Select the Widget that you want to show on the tab.
    If this widget uses parameters, you will be prompted to provide set those parameters for this instance.
    You may later use the Set Parameters button to change those selections.

Steps to use a Page:

  1. Select Page as the Widget Type.
    The Context field will be set to "Pages" and disabled.
  2. Click the Select Page button to open a menu of all the pages in this application.
    Any page may be used, but in general, it is best to use a page that was designed to fit the area of this folder.
  3. Select the Page that you want to show on the tab.
    If this page uses parameters, you will be prompted to set those parameters for this instance of the page.
    You may later use the Set Parameters button to change those selections.
    Note that, the page's background image will not carry through to display in the tabbed folder.

Widget Folders:

Decorations


Frame

A frame is similar to a border, except that it provides a much greater range of formatting options. Frames are used in the construction of Folders.

Three frames.

The properties dialog for the frame shape:

Frame Styles

Set the overall appearance of the frame by selecting from one of the nine built-in options, or choose your own frame image. Images for the built-in frames can be found in sub-folders of C:\VTScada\VTS\Resources\Frames.

Each folder has nine images, setting the appearance of each corner, each side and the fill. Use these as examples if building your own frames, but add the new folder to your application's Bitmaps folder. Do not add or change files in the VTScada folders.

Frame Image Directory

Custom frames can be created by following the pattern found in any of the Frame sub-folders of the VTScada installation. For example, C:\VTScada\VTS\Resources\Frames\Frame1

Each of these sub-folders contains nine images that together make up the frame. To make a custom frame:

  1. Copy one of the existing frame folders to your application's Bitmaps folder
    C:\VTScada\MyApplication\Bitmaps\MyFrameFolder).
  2. Edit the images there to suit.
  3. Select Custom Frame from the Frame Styles drop-down.
    The "Browse" button will be enabled.
  4. Browse to and select your custom frame folder (not the images within the folder).
  5. In the VAM, select Import File Changes for your application.

Use Theme Color

When selected, the Color Options will be adjusted for you such that your frame will take the appearance of whatever color theme is in effect for the application.

Colorize

Enabled only when the option, Use Theme Color is deselected. Colors may be set explicitly using the Select Color dialog, or they can be linked to tag value, page parameters, linked tag property or expression.

Opacity slider

Controls the overall visibility of the frame. An Opacity of one is fully visible and a value of zero is fully transparent.

Widget Folders:

Decorations


Lighting Overlays / Tiles & Textures

These are images, used and configured the same as pump, motor and valve images.

Lighting overlays are often used to enhance other objects. (Examples can be seen in many of the gauge widgets, and in the Dashboard A sample page.) Tiles and textures are often used as a background fill. (All of the Dashboard sample pages make use of a textured background.)


Rounded Rectangle

A rounded rectangle is one with a user-specified radius for the corners. Each corner can have its own radius value.

The fill and the border can be independently configured.

The Properties Dialog for the Rounded Rectangle:

Fill

Color

Use the Select Color dialog to choose the color of the rectangle's interior. Set the color to transparent (0% opaque) to remove the fill.

Pattern and Pattern Color

Select any of the 25 predefined Fill Patterns supplied with VTScada.
For each of the sample patterns, the black lines or dots represent the portion of the pattern that will be affected by a choice of pattern color. The space between the lines or dots of the pattern will be filled with the base color chosen for the fill.

Outline

Color

Use the Select Color dialog to choose the color of the outline border. Set the color to transparent (0% opaque) to remove the fill.

Line Width

Measured in pixels, use this control to set the width of the outline boundary. Changes to the line width do not alter the size of the rectangle because additional pixels are added inside the outline, overlapping the fill.

Line Style

Select any of the five Line Types supplied with VTScada.

Corner Radius Settings

If the basic mode is selected, one data entry field is used for all four corners. Select the advanced mode to set independent values. Note that basic mode will be selected by default if the rectangle is square.

Each radius is measured in pixels. Use a value of zero for a right-angle.

Values less than zero or greater than 999 cannot be entered directly, but will be accepted from expressions or tag values. Setting a radius value less than zero or greater than the dimensions of the rectangle can produce interesting (and potentially useful) shapes.

Widget Folders:

Decorations


Tool Tip Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Tool Tip widget is used for adding extra information to a screen that should not be displayed unless requested. The widget is drawn as a rectangular area. When an operator moves the pointer over the area, the information that you configure will be displayed.

The properties dialog for the Tool Tip widget. Note that you may use any of the following for both title and content:

  • Static Text
  • Parameters
  • Linked Tag Property
  • Expression

Title

Text to display in bold above the body of the tool tip.

Titles are limited to 99 characters.

Tool Tip Contents

Usually, the greater part of the information to display.

Both the title and the contents are optional. You may choose to display only the title in bold, or only the contents.

Widget Folders:

Decorations

Tools\Standard Library


Site Legend

Not linked to any tag

* Does not use the Style Settings tag.

The Site Legend describes the colors used in Site Icon indicators. While not quite a widget, it is more than just an image. You can draw a Site Legend on any page. Operators can use a button in the Sites page to toggle display of the legend on or off.

The dots show the meaning of colors in the center of the icon. Two dots together in the legend indicate that the icon will alternate between those colors. The rings show the meaning of colors in the outer ring of the icon. Several of these colors apply only to Polling drivers and DataFlow Stations.

By default, the legend is drawn with black text on a white background but both can be changed. The legend can be scaled as needed.

Widget Folders:

Basic Components\Specialty\Mapping\

Analytics\Diagnostics\

Tools\Site Tools Library\

Decorations


Text

Text is an essential part of any display. Titles, instructions, and labels are all required to help operators use the display screens that you build.

While you may use the ribbon to format each label that you write, you are advised to make use of styles instead. By creating a small set of styles and applying them to the text that you create, you avoid the need to constantly return to the formatting commands, and you ensure that each type of label, title or instruction block will have the same appearance, exclusive of color, background, alignment and opacity.

Add single-line text:

  1. Open the Idea Studio and open the page to which you want to add text.
  2. Ensure that the Home ribbon is selected.
  3. Click the Text button in the ribbon.
  4. Click on the page, near where you plan to put the text.
    A selection box will mark the location on the page and the Edit Text dialog will open.
  5. Type a single line of text, then click OK.
    Note that you may also select a page parameter or, if working within a tag widget, link this text to a property of the linked tag.
    The dialog can be re-sized as needed. Lines will wrap as required to fit the display space.

While it is possible to press <Enter> while typing, multiple lines in the Edit Text dialog will be merged together into a single line on the screen. Spaces will not be added to replace the line breaks.

Add multi-line text:

  1. Open the Idea Studio and open the page to which you want to add text.
  2. Open the widgets palette.
  3. Click to open the Tools folder within the Widgets palette.
  4. Click to open the Standard Library, within the Tools folder.
  5. Drag the Multi-Line Text widget onto the page.
  6. Open the widget's properties dialog.
  7. Type the multi-line text in the field provided.
  8. Adjust the display properties as required.

The text will wrap within the bounding box as required to fit, and it will use the line breaks that you type.

Troubleshooting:

  • Line breaks in the Edit Text dialog were ignored.
  • Words that were on two lines in the Edit Text dialog have been merged into a single word.

This is by design. If multiple lines of text are required, use the Multi-Line Text widget.

  • When stretching the bounding box on the page, the text appears to deform.

This is only a preview while re-sizing the bounding box. The text is controlled by its font and style definition and will not be scaled or stretched with its bounding box.


Data Entry Forms

You can create forms in your VTScada application either on a page or as a pop-up. Forms allow you to fill in multiple data fields and submit all the information at once, apply time offsets to individual fields, and optionally select a date and time other than "now" to apply to the submitted values. Values can be written in the past in a way that can be viewed, for example, on a Historical Data Viewer.

A quick sample of a form built using the Data Entry Form widgets.

A form is made by enabling the "Include in Form" property setting in at least one compatible widget and by having a submit button on the same page or pop-up.

The form-related widgets are pictured here with a DrawHDV widget to show an example of recorded data.

The widgets with form capabilities include:

You will find a Forms section in the properties dialog of each of these widgets.

  • Enabling "Include in Form" indicates that this widget is part of the form.

  • The submit button acts upon all widgets with "Include in Form" enabled that are on the same page or pop-up as the submit button.

  • Each of these widgets has a time offset. For values that are recorded at a past time, individual offsets can be applied to shift the window closer to the present time. For example, in a form where values are recorded at 11:00 AM according to the DateTimeSelector, an offset of +15 minutes will result in the value being recorded for 11:15 AM.

  • You cannot record values in the future. Offsets that exceed the current selected time will not apply.

There are four widgets that are exclusively for forms:

Clear Button Widget

Date Time Selector

Form Reset Button Widget

A Submit button is the only required form widget; You are not required to have a Clear button, Reset Button or a Date Time Selector. The Submit button triggers the submission of new data filled out in the form fields.

A Clear button clears all the data filled in the form-enabled data entry widgets. You may also achieve this by enabling "Clear form values on submission" in the submit button properties.

A Reset button returns the values displayed in the form-enabled data entry widgets to the original values. The original value can either be a current value (the most recent stored tag value) or a historic value (an earlier stored value). If you have previously recorded (submitted) a value of "40" at 5:15 PM and you type "30" in the field to be recorded at 5:15 PM but instead of clicking "submit" you click "reset" the value in the field will display "40".

The Date Time Selector sets a date and time at which to record the submitted values. Clicking on the widget will open a dialog that allows the operator to adjust the date, time or quickly move to the current time.

If Time Offset and Time Unit options are specified, they're added up. For example, if a Numeric Entry has a Time Offset of 1 hour and the Date Time Selector is set to 11:00 AM, the value logged at 12:00 PM will be logged as:

Date Time Selector's timestamp + (Time Offset × Time Unit)

Time offsets only apply if a Date Time Selector is present and not preset to "Now".

Using Time offsets will amend values in the Historical Data Viewer but there will still be a record that a change was made by a form recorded as an event.

the record indicates the real time that the form was submitted and the time that was indicated on the Date Time Selector widget when the Form was submitted. The event log also includes the workstation and user who was logged in when the form was submitted.
If a Date Time Selector is not present, the event description will simply say "Form submitted".

If you add new data to one of the form entry fields, the field will turn green until the data is submitted. If you enter a new value into a field and click submit but the value stays green that means, for some reason, the value has not successfully submitted. If you run into this problem, check your time selector and offsets to ensure you aren't trying to submit a value at a future date or time.

Related information:

Checkbox Switch Widget

Clear Button Widget

Date Time Selector

Form Reset Button Widget

Droplist Widget

Numeric Entry Widget

String Entry Widget

Submit Button Widget

Hook for Form Timestamps


Widgets for Tags

To display the value of a tag to an operator, or to allow operator control over a tag, you will use a widget. Widgets take many forms including color indicators, gauges, buttons, bars, switches, animations, text, meters, and more. In all cases where a widget is meant to represent or control a tag, there will be an option to link it to that tag.

There are widgets for tasks other than displaying or controlling tags, and these do not have a link option. Examples include Border, Grid and Folder. And if you are willing to spend time writing expression code, there are ways to display a tag's value other than using a widget. This chapter is concerned only with widgets for tags.

For a list of widgets included with VTScada, see the reference chapter: Widget Reference. Every widget topic includes instructions to help you find that widget in the palette. You can also create your own widgets. See: Create Widgets.

Palette entries are Menu Item Tags Create a folder for your most frequently used widgets and copy their menu entries there.

Because developers can draw widgets first, then link those widgets to tags, it is possible to leave unlinked widgets in a page. These will show simulated values.

To avoid the risk of simulated values being mistaken for real process data, the unlinked widget symbol can be drawn on all unlinked widgets. If you see this symbol, know that the values being displayed are coming from a simulator, not from equipment.

Unlinked widget indicator

Note: It is possible to display this warning only as a blinking indicator in the title bar. Developers with configuration privileges can click that symbol to toggle between having an indicator on every unlinked widget or having only a single indicator in the title bar.

Toggle display of unlinked indicators

Within the palette, widgets are grouped into folders according to their general appearance, purpose, and type of tag to which they can be linked. Many widgets can be found in several folders.

Many of the newer widgets can be linked to Style Settings Tags. This provides a single point of configuration where colors can be assigned to tag states (running, stopped, alarm, LCD component, etc.).

To add a widget to a page:

  1. Open the Idea Studio and open the page where the widget will be drawn.
  2. Open the Widgets palette.
  3. Click on the folders to view and find the widget you want.

Navigate through the folders to see what is available or use the search bar to look up the widget you want by name or category. Folders are organized by widget type, and by tag type. Use the navigation bar at the top of the folder list to return to a higher-level folder, including the "Home" folder.

  4. Drag a widget from the palette to your page.
    Alternatively, click once on a widget to attach it to the cursor, then drop it on the page.
  5. Adjust the size, location and other properties of the widget as required.

A format ribbon is available for each widget type.
Advanced configuration details can be accessed by opening the Properties dialog of the widget.

  6. Link the widget to a tag as follows:
    1. Select the widget.
    2. Type Ctrl + L or click the Link button, either in the widget format toolbar or in the right-click context menu.
    3. From the tag browser that appears, choose the tag this widget will represent and click Select.
    4. If the tag does not already exist, create it.

There are four ways to link a widget to a tag:

  • Selecting the widget in the Idea Studio, then click the Link button in the Widget Properties ribbon
  • Selecting the widget in the Idea Studio, then type Ctrl + L
  • Open the Properties dialog for the widget, then click the Tag Browser button found there.
  • Use the Tag Links panel.

Widgets can also be linked to parameters, as is often done when using a parameterized page.

Draw from the Tag Browser

It is often easier to find a widget by drawing the tag from the Tag Browser. The Idea Studio will open (if not already open) and a filtered palette dialog will be provided, containing only those widgets that can be used with the type of tag you are drawing.

Preparation:

  • Ensure that the page you want to draw the tag on is displayed.
  1. Open the Tag Browser (Ctrl + T) and select a tag.
  2. Click the Draw button, or right-click on the tag and select Draw from the menu.

    If the Idea Studio is not open, it will immediately open to the same page that you are viewing in the main window.

A dialog will open, showing the possible widgets that can be used to represent this type of tag.

  3. Navigate to the folder containing the widget you want to use, if it is not already open.
  4. Drag the widget you want to the page.

    Alternatively, click once on the widget you want to draw - an instance will attach itself to the cursor. Click on the page where you want to place the widget.

The Tag Browser remains open, allowing you to draw the tag again using another widget, or to draw other tags. Close it when you have finished

Troubleshooting:

  • The widget is too big / too small.

All widgets have an initial size, which may be wrong for your application. After the widget is placed, zoom in or out on the canvas until you can see the edges easily, then select the widget and drag the corner grips to resize it.

  • The widget is cycling through values / colors all by itself.

Widgets display simulated values until they are linked to a tag.

  • Unable to find a particular widget.
    See Searching for Widgets

Look in the Widget Reference for the one that you want. Each description includes a list of folders where the widget can be found.


Searching for Widgets

Finding widgets by navigating through folders

In the left-hand window of Idea Studio there are three separate palettes for widgets, images and shapes. The widget palette will appear open by default.

There are hundreds of widgets available in VTScada and they have all been sorted into folders grouped intuitively by widget type and tag type. Click once to access a folder. Click on a widget once to 'pick it up' to drag it to the page. It is worth taking some time to explore these folders to become familiar with the many available options.

As widgets are selected they will appear in the Recent Items section beneath the tabs for ease of re-selection. Widgets that already appear on your page can also be copied and pasted.

As you navigate through folders and sub-folders the path you have taken will appear in the breadcrumb. You may navigate back to a previous location by clicking any segment of the breadcrumb:

Folders are sorted by relevance but may be sorted alphabetically by checking "Alphabetical Sort". The size of the folders may be changed using the slider at the bottom of the palette.

You may create your own folders to reorganize your palette as it suits you and to store custom widgets.

Using the search function

Using the search bar can quickly narrow down your search. Enter keywords into the search bar to display all folders and widgets that may be relevant. The results are based on widget or folder label, widget module names, and the name attributed to widget thumbnails.

Results are sorted by relevance but may also be sorted alphabetically.

Searches will include matches from the current folder you are in and all sub-folders. If you are not seeing the results you expect, check your breadcrumbs to see what folder is being searched:

This search function supports wildcards where ? may be substituted for any one character and * may be substituted for a string of characters. For custom widgets with common naming schemes this is a handy feature.

• "Custom?" will match with CustomA, CustomB, CustomC...
• "Custom*" will match with CustomAA, CustomWidgetA, CustomWidgetB...

To include the characters * or ? explicitly (and ignore the wildcard function) use a backslash(\) in front of the character.

Troubleshooting:

  • While resizing folders or widgets, the labels disappeared

    Make the folders or widgets a little bigger and the labels will return.

  • The search results are not what you expect; there are fewer results than expected.
    Searches are performed starting at the sub-folder open in the palette and all the sub-folders therein but excluding everything that came before it. If you are in a sub-folder, click on the home icon in the breadcrumb and try again.


Select a Data Source

Most widgets must be linked to a data source that provides the value shown by the widget. The data source is usually a linked tag, but this is not the only option. You can also select a page parameter if you are using a parameterized page, or a linked tag property if you are using a custom widget.

The Tag Links Panel can be helpful if you have many widgets on a page, as it provides a list view showing the tag to which each widget is linked. Every item selected in the page is also selected in the list and vice-versa.

Information in this topic is relevant to every property of everything that can be drawn, including color, scaling, movement, opacity, and others. Properties can also be linked to expressions.

For Scaling, Movement and Opacity properties, if you are using numeric values, the scale ranges from 0 to 1. If using a tag, expression or property, the scale can be adjusted and in the case of a tag, should match the Scaled Process Data Max value of that tag.

Tag:

How: Use the Tag Browser to select any tag whose value can be represented by this widget.

Why: This method creates a one-to-one relationship between a tag and an animation on a page. For uncomplicated applications, this is the easiest way to draw tags.

Parameters:

How: The tag selection area is replaced by a parameter selection. From this control you can select any page parameter (or descendants of that page parameter) whose type has a value that can be represented by this widget.

Why: The same page can now be used for more than one tag. For example, if your application has several identical pumps, tanks, stations, or other equipment. In each button or hotbox that is used to open the page, you can use a different set of tags for the parameters.

Drawn Tag Property:

How: Enabled only when the widget is one that you have created. Select any of the properties of the tag instance being drawn. The selected property must have a data type that can be represented by the widget.

Why: Similar to using a parameters, this provides a way for the same object can be re-used for different tags. This technique is most often used when you have complex drawing objects, showing all the tags that are part of a complex tag type you have defined.


Choices for Operator Interaction

Tag widgets can provide the following features for operators: a trend window in response to a left-click, a pop-up menu in response to a right-click, a tooltip in response to the pointer hovering over the widget. Availability varies by widget, linked tag type, and your configuration choices.

Trends.

For widgets linked to numeric types, a left-click on the widget will cause the Historical Data Viewer (trend) window to open for the associated tag. If the click lands on several overlapping widgets, all the associated tags will be plotted in the HDV. You can disable this feature for all analog tags by setting AITrendEnable to false (0) and for all digital tags by setting DITrendEnable to false.

Context menu

In all cases, a right-click on the widget will cause a context menu to open. The contents of this menu will vary by tag type - the image shown here is a sample. The attached tag in this case is an I/O & Calculations Tag.

In all cases, there will be a Help option at the top, opening the relevant page in this reference for the associated type. A Properties option will be found at the bottom of the menu, allowing authorized users to re- configure the attached tag.

Tooltip

Hovering the pointer over any tag’s widget will cause a tool tip to display. This enables the operator to see the tag’s name and description. You can disable this feature globally by setting the application property ShowTip to false.

Confirmation Dialog (Only in selected output widgets)

If selected, the operator must confirm the action before a control signal is sent to the PLC. An example of the confirmation dialog follows:

(Text will vary according to your configuration.)

Disable Control (Only in selected output widgets)

When selected, operators will not be able to use this widget to write a value via the linked tag. It is possible to create an expression that will check the identity or privilege set of the current operator before enabling this option. See the examples at the end of Examples of Expressions.

Widgets configured with Disable Control selected are "grayed-out" if displaying a label. Widgets that display an image become semi-transparent according to the property, DisabledControlWidgetOpacity.

This option affects only the widget being configured. If a second control widget is linked to the same tag and neither the tag or that second widget are protected, the operator will be able to write to hardware.

Operator Interaction Controls

These tools are configured on an individual basis using each widget's properties dialog. There is no global setting for all. Options will vary by widget as appropriate. For example, there is no need of a confirmation dialog in a widget that does not provide operator control. Note also that selected widgets that provide output control have more options to configure these interaction controls than the basic check box.

Used by most input widgets

Used by some control widgets

Used by selected control widgets

These options are stored as parameters to the widget. This means that you can right-click to edit the widget's Menu Item tag in the Widgets palette to set defaults for these parameters. Note that any given widget may have more than one entry in the palette. A change to one Menu Item will not affect any other.

Right-click the palette entry to open the properties dialog.


Create Widgets

Anything that you have drawn can be grouped into a new custom widget. There are three kinds, any one of which may be best depending on your purpose.

Detail from the Idea Studio, home ribbon

This can be as simple as a grouping used to make alignment easier on a page, or as complex as the components of the MultiSmart and MPE Site pages.

A single widget, with many components.

There are three classes of custom widget, listed in order of increasing features and capabilities:

Group

  • Best choice for moving and aligning a set of elements while working in the Idea Studio.
  • Worst choice for creating a library of shapes.
  • You cannot assign the name.
  • Cannot be added to a palette.
  • Cannot be linked to a tag, even if the elements within the group are tag-linked widgets.
  • If ungrouped, the file remains in your Widgets folder, but cannot be used (no user-assigned name).

Plain Widget (Simply labeled "Widget" in the dialogs)

  • Elements may include one or more existing widgets in addition to shapes or images.
  • Must be given a name.
  • Automatically added to the palette.
  • Tag links, if any, are done through parameters rather than directly to the widget.
  • Does not become a native widget for any tag.

Tag Widget

  • At least one existing widget must be included in the selection set.
  • All of the included widgets must be linked to tags before grouping.
  • Must be given a name.
  • Automatically added to the palette.
  • Becomes a native widget for a tag type, which is typically the common parent of all in the selection. (Other types can be added to the list.)

When creating either a plain widget or a tag widget, you will see the New Widget dialog. Instructions for using this dialog are provided in the subtopics, "Plain Widgets" and "Tag Widgets".

Widget names cannot match the short name of any tag.

The New Widget dialog

New widgets are added to the top level of the Widgets palette and also to the list of most recently used widgets. Each time that you create a new widget, you should take a moment to reorganize the palette, moving the menu item into a folder of your choice. By keeping the palette organized, you will save time later when looking for a widget that you want to use.

Any individual widget can be broken apart into its components by selecting the instance, then clicking "ungroup" in either the formatting toolbar or the right-click menu. If your intent is to change the appearance of a widget, you should edit the widget definition rather than following a process of ungroup - edit - regroup.

Also, while you can nest groups into widgets into other widgets, you are advised not to. It's simply easier to manage groups and widgets that are not nested than those that are.

Widget definitions can be opened for editing the same way that a page is opened. Use the Open command in the Idea Studio's file menu to open the widget by name or select any instance in a page and click Edit, either in the toolbar or the right-click menu. Your changes will affect all instances of the widget or group throughout the application.

A Tag Icon Marker

You can choose whether to add a Tag Icon Marker to your widget. The icon (yellow blob) will not be visible to operators unless you take steps to make use of it, which usually means adding a parameter named "Questionable" to your context tag.

You have the option of giving every new widget, both plain and tag, its own parameters for operator interaction. In most cases, you probably won't want those. If your widget includes a control widget, a click on one is a click on both. If you include the Trend, Navigation, and Tooltip controls, and if you want to operate a control within the widget without having the Trend window for your widget opening, you are advised to open the new widget's properties dialog and select Disable Trend. In many cases it is easier not to include the operator interaction tools.

Operator interaction parameters. It's your choice whether to include these.

A widget can be given a background color, but this will be displayed only in the Idea Studio and in the palette. When drawn on a page, the widget's background color will not be included.

Application security privileges cannot be selected within widgets. To protect output controls, apply the security privileges to output tags or to pages.

Widget Rotation

Most VTScada widgets can not rotate, but, it is possible that for a user-defined widget, the ability to rotate might be useful. This is especially true of widgets that are made of shapes and images rather than built from existing VTScada widgets.

You must edit your widget's source code to add a property that will enable rotation. If you have the Edit Files security privilege, you can do so as follows:

  1. Create the widget using the Idea Studio.
  2. Hover the pointer over the widget's tab at the bottom of the Idea Studio to display its identifying tool tip.
  3. Make note of the name and location of the file holding the widget.
  4. Open that file using a text editor.
    Tip: you can do this using the Source Code tool in the Home ribbon of the Idea Studio.
  5. Close the Idea Studio.
    This is to ensure that you do not continue editing the file with the Idea Studio while also editing the widget's file directly. Do not skip this step.
  6. Add the following line within the variables declaration section of the widget. (The first section of code enclosed in square brackets.)
  7. CanRotate = TRUE;
  8. Save the file and close your text editor.
  9. Import the file changes.
    (Import File Changes Page)


Keep a Tidy Palette

Every new widget that you create will be added to the top level of the palette. You don't have to create very many before this becomes disorganized.

Try to develop a habit of maintaining a tidy palette. You should create folders for your custom widgets, moving new Menu Item tags to those folders. These can be at the top level of the palette, or within existing folders.

If you find that you use the same dozen or so VTScada widgets for most of your work, you can save time by creating a folder named Favorites, to which you can copy your most frequently-used palette menu items.

You can change the order of folders in the palette by working with their Menu Item entries in the Tag Browser.

Note that you can select multiple tags in the Tag Browser's main window by holding down the Ctrl key while selecting. Use this to copy, move, or delete several tags at once.


Plain Widgets

In the Idea Studio, these are referred to as simply "widgets"In earlier versions of VTScada / VTS, plain widgets were referred to as "library widgets". 1 as opposed to "tag widgets" or "groups". Examples of VTScada plain widgets include Clock, Border, and Edit Property Checkbox. A plain widget differs from a group as follows:

  • You can provide a name of your choice for the widget.
  • It can be added to a palette.
  • It has parameters, and you can add more.

Plain widgets differ from tag widgets in that they are not designed to be linked to tags. But, it is possible to achieve a similar effect through the use of the plain widget's parameters. In this, a plain widget is like a parameterized page. Note that one parameter will be created automatically for every linked tag selected when creating the widget.

In general, if your intention is to create a widget that you can link a specific tag, or a set of tags with a common parent, you should create a tag widget rather than a plain widget. Use plain widgets for extending the list of shapes in your application or for widgets that must be linked to two or more unrelated tags.

Create a Plain Widget

Prerequisites:

  • If all objects in the selection set are tag-linked widgets, you are strongly advised to add a bounding box or other shape. The widget you are creating will not be visible in the palette otherwise.
  • All widgets in the selection set must be linked to tags before they can be included in the new plain widget.

  1. Select the objects that are to be included in the widget.
  2. Expand the Group option in the toolbar and click "New Widget".
    The New Widget dialog opens:

  3. Select the option "New Widget".
  4. Replace the default name with something that describes the widget.
  5. Click OK.

There will be two results:

  • The widget will be added to the Widgets palette, at the top level.
    Use the menu editor if you wish to move it to a different folder.
  • Any tag links to widgets within the original selection set will be replaced by parameters.
    When drawing new instances of this widget, you will need to open its properties dialog and specify the tags to use for each parameter in each new instance.

Troubleshooting:

  • An error message says that widgets must be linked to tags before proceeding.
    All widgets in the selection must be linked to tags. This includes widgets from the Equipment folder of the Widgets palette. Examine the properties of each component in the selection set to determine whether it is a widget and whether it has been linked to tag.
  • In the Widgets palette, the tag-linked widgets of this new object are invisible.
  • The new object has a label in the palette, but is invisible.
    The last two are the same problem, but this is how plain widgets work. Within the palette, there is no tag selection for the parameters used by those tag-linked widget, and therefore they are not visible.

Draw a Plain Widget

A plain widget is drawn just like any other widget: Drag it from the palette to the page.

The one complication is that, if the plain widget includes tag-linked widgets, then there will be a parameter for each. After dragging to a page, you must open the widget's properties dialog and select the tag to use for each parameter.

As a guide, each parameter will show the name of the original tag that it replaced within the widget. The tag selection will not be filtered for matching types unless you select appropriate types through the Manage Parameters dialog.

The Manage Parameters dialog is available in the Idea Studio ribbon, when the widget has been opened for editing.

Managing parameters of a plain widget

Troubleshooting:

  • Parts of the widget are invisible.

Either, tags have not been selected for the parameters used by those tag-linked widgets, or the wrong type of tag was chosen.


Tag Widgets

Most widgets in the Idea Studio palette are tag widgets. VTScada makes it easy for you to create your own, extending the options available to create a user interface that is customized for your industry or application.

Tag widgets have the following features:

  • Tag widgets are designed to be linked to a single instance of one or more types of tag. They are native representations of tag values, available when you click "Draw" on a tag selected in the Tag Browser.
  • The tag to which a tag widget is linked may be a parent tag. When properly configured, all of the child tags will be assigned to components of the widget automatically. This enables you to draw an entire station or complex equipment with a single widget.
  • Tag widgets may be given parameters, but this is uncommon.

Example:

Tank Level with bar and floating text

This example of a user-created tag widget, Tank Level, is designed to represent analog values as a tank filling with fluid. The numeric display rises with the fluid level. Tank Level has become a native widget for use by any analog tag within the application.

The easiest way to create a new widget is to draw the components then group the pieces. Further editing can be done if required. All existing widgets that will go into the new widget must be linked to tags before being grouped.

Want to create your own version of the Tank Level? Here's how. Feel free to vary these instructions as appropriate for your application.

  1. Draw an Analog I/O tag (or Analog Status) as a Color Fill widget.
  2. Place a tank cut-out image above it and scale both so the Color Fill exactly matches the cut-out.
  3. Draw the same tag as a Numeric Value widget, placed to align with the bottom of the tank.
    !! Do not move this widget up or down after deciding on its placement !!
  4. Check the Color Fill widget's coordinates to obtain its height in pixels.
    (Use for Y in the following expression)
  5. Open the Numeric Value's properties and configure the Vertical Movement property as shown, where "Your tank height" is the number from the last step and the tag is the same one used to draw this widget. Do not move the widget up or down after completing this step!
  6. Group the Color Fill, the tank and the Numeric Value as a new Tag Widget, changing the name, but otherwise accepting all defaults.


Create a Tag Widget for One Tag

These instructions are for creating a widget that will represent only one tag at a time. But, just as a meter can be used for many types of tag, your custom tag widget can be configured so that you may link it to any one of many types of tag.

To create a tag widget that can be linked to one tag:

  1. Choose a tag and draw it using one or more widgets.
    Alternatively, draw one or more widgets and link them all to the same tag.
  2. Add context such as images, pipes, text and shapes.
  3. Select the components that will make up the widget.
  4. In the ribbon, click Group.
    You could also right-click on one of the selected objects and click Group from the menu that opens.
  5. Select New Widget as the type of group.
    The New Widget dialog opens.
  6. Provide a name for the new widget, replacing the default word, "Widget".
  7. Ensure that the option, New Tag Widget, is selected.
  8. Select the tag that was linked to the component widgets.
  9. Click OK.

Results:

  • The original objects are removed and replaced by an instance of the new widget. The yellow diamond in the upper left corner is a Tag Icon Marker, which may be used to indicate questionable or manual data. It can be removed from the widget if you do not want to make use of this feature.
  • The new widget has been added to the Widgets palette. You are advised to edit the menu to store your widgets in a sub-folder rather than adding them all at the top level of the palette.
  • As you drag instances of this widget onto pages, you can now link them to any instance of the same type of tag that was used when creating the widget. You can edit the parameters of the widget to expand the types it can be linked to.
  • If you draw an instance of the tag from the Tag Browser, you will find that the new widget is now a native option for that type.

Example: Create TankLevel

Tank Level

This tag widget, TankLevel, is designed to represent analog values as a tank filling with water. The numeric display rises with the water level. TankLevel will become a native widget for use by any Analog tag.

  1. Create at least one Analog Input or Analog Status tag.
  2. Open the Idea Studio.
  3. Select the Widgets palette and open the Basic Components >> Bars folder.
  4. Drag a Color Fill widget onto the page.
    Adjust properties as you like. In this example the fill color was set to blue.
  5. Link the Color Fill to your Analog Status or Analog Input tag.
  6. Select the Images palette and open the Tanks folder.
  7. Drag a tank with a cut-away to the page (Tank26 was used in the figure.)
    Place it over the Color Fill.
  8. Adjust the image or the widget so that the Color Fill matches the cutaway of the tank.
  9. Make note of the size of the Color Fill:

  1. In the Widgets palette, browse to the Text folder.
  2. Drag the widget Numeric Value onto the page.
  3. Position the Numeric Value to the side of the tank, even with the bottom edge.
  4. Link the Numeric Value to your Analog Status or Analog Input tag.
  5. Open the properties dialog of the Numeric Value and select the Vertical Movement option.
  6. Select the same Analog Input or Analog Status tag that you used for the rectangle scaling.
  7. Set the maximum pixels to be the same as the height of the Color Fill (or a little less).
  8. Ensure that the movement direction is Up and that the Use Tag Scaling option is selected.

  1. Click OK to close the dialog.
  2. Select all three objects that you have drawn.
  3. Click, Group in the toolbar, or right-click and select Group from the pop-up menu.
  4. Select the option, New Widget.
  5. In the New Widget dialog, provide the name Tank Level.
  6. Ensure that the Tag Widget option is selected.

  1. Click OK to finish.
  2. Right-click on the new widget and click Edit in the menu that opens.
  3. Open the Widget Properties tab in the ribbons.
  4. Click Tag Types in the ribbon.
    The Edit Parameters dialog opens. Whichever tag type you used above is shown in the list of associated tag types.
  5. Add other analog type to the list of associated tag types.
  6. Click OK in the Edit Properties dialog to save your work.
  7. Close the widget editing page.

Tank Level will now be listed in the Widgets palette. You can drag it onto any page and link it to any of the types you selected in the Edit Parameters dialog.

Troubleshooting:

  • On attempting to group the objects, an error message complains that some are not linked to a tag.

All tag widgets within the selection set must linked to tags before they can be grouped. This does not interfere with your ability to use the widget for other tags later.


Create a Widget for a Tag Structure

Equipment often has several tags which are drawn together. If those tags are associated as child tags with a common parent, then you can group the various related widgets and link the collection to the parent context.

In the following (simplified) example, there is a valve with four I/O tags. The parent context tag has been turned into a new type named ValveType and a second instance has been created. All other tags including ports and drivers have been removed from the image.

The four child tags are normally shown and used as a group:

Having drawn those four tags once with labels and scales, you shouldn't need to draw them again for other valves. Rather, turn these into a new widget that can be reused and linked new instances of ValveType.

To create a multi-tag widget:

Prerequisites: The situation just described, with a parent-child tag hierarchy that has been drawn once.

  1. In the Idea Studio, select all the widgets, labels, and everything else that was used to represent the tag structure.
  2. In the ribbon, click Group >> New Widget.
    You could right-click on any of the selected objects and use these commands from the context menu.
  3. In the New Widget dialog, ensure that the option, New Tag Widget is selected.
  4. Provide a meaningful name for the new widget.
  5. In the Select Tag area, ensure that the parent valve is selected.
    This is necessary so that the new widget can be drawn for other tags of the same type.
    Use care: sometimes the default selection is one level too high or low in the hierarchy.
  1. Click OK.

The separate objects will immediately be grouped into a new tag widget, available for drawing new ValveType tags. You should open the new widget's properties to disable the operator interaction features. See: Choices for Operator Interaction

Example: Draw Valve2 using the new widget.

The new widget (ValveControl in the previous example) is part of the Widgets palette.

  1. Drag the widget from the palette to a page.
  2. Link the widget to Valve2.
    The four widgets within ValveControl will link automatically to the four tags of Valve2.
  3. [Optional, but recommended.] Open the widget's properties to disable trends, navigation and tooltip.

Troubleshooting:

  • The wrong tag was chosen while creating the widget.

You can change the list of tags associated with this new widget. Use the Drawn Types tool in the Widget Properties ribbon while editing your widget.

  • An extra object was included / an object was missed.

You can edit the widget, adding and removing widgets, images and shapes.

  • The label is the same for every widget drawn. This would be more useful if the label could say which particular valve was being drawn.

You can link labels (and anything else) to properties and parameters of the tag being drawn. Instructions are provided in a sub-topic.


Edit a Tag Widget

After creating a custom widget you will likely want to change it.

At the code level, a widget is very similar to a page. Both can be edited within the Idea Studio using exactly the same tools. In fact, it can be difficult to tell whether you are editing a page or a widget. The easiest way to check is to note the icon used in the tabs at the bottom of the Idea Studio.

There's an icon for each type of page and widget

That and the toolbar ribbon...

Don't ignore the ribbon title

There are two ways to open a widget for editing in the Idea Studio:

  • Use the Open command, then select the widget.
    The Open command is available from the File menu, the plus button, and the keyboard combination Ctrl-O.
  • Right-click on a custom widget within a page then choose Edit from the pop-up menu.

Right-click menu for a custom widget, within a page, within the Idea Studio.

When editing one of your custom widgets, everything you do goes into effect immediately, changing all instances of that widget on all pages.

Reference Point

The reference for every widget is the upper left corner. This is 0,0 in the Idea Studio's coordinate system. Do not move the pieces of a widget away from this corner unless you want every instance of that widget to jump to a new location.

Equally important: Never scale the pieces of a widget while editing unless you want every instance to scale. Results can be unexpected.

Tag Icon Marker

Most VTScada widgets contain a tag icon marker. (Tag Icon Marker) This is the yellow symbol that blinks a question mark when the linked tag's Questionable flag is set, and an exclamation mark when the linked tag is using manual data. If a widget has not yet been linked to a tag, the indicator will show a star (asterisk).

The Tag Icon Marker in a VTScada widget (Color Fill)

A Tag Icon Marker can be added to user-created tag widgets automatically. For it to function, the tag to which the widget will link, must have at least one of the properties, "Questionable" or "ManualValue".

In the case of user-created tag widgets for tags that do not have either of those properties, there is no benefit to adding the Tag Icon Marker.

Tools in the Widget Properties Ribbon

Tools in the Widget Properties ribbon

Many of the sections are shared with the Page Properties ribbon, with options that do not apply to widgets disabled. As shown, you can adjust the background color (this doesn't affect the drawn widget, but can be useful if your widget will normally be placed on a dark background) or change the title if the original name isn't suitable.

Of particular note are the tools Tag Types and Drawn Context.

Tag Types

A new tag widget can be linked only to tags like the one to which the original was linked. It is standard practice to expand this list to include similar types. For example, if the original was linked to an Analog Status tag, you may also wish to be able to link new instances of the widget to Analog Input, Calculation, and other tag with numeric values.

To link your widget to other tag types:

  1. Within the Idea Studio, open the widget for editing.

    Use the Open command in the file menu, press Control-O, or right-click on a drawn instance of a widget and select Edit from the pop-up context menu.
  2. Select the Widget Properties ribbon.
  3. Click the Tag Types button in the Widget Properties ribbon.

    The Edit Parameters dialog opens.
  4. Use the arrows to fill the column on the right with all the tags that you might want to link to your widget.

Troubleshooting:

  • The Widget Properties ribbon is not visible.

The Widget Properties ribbon is visible only when editing a widget. Use the Open command to open a widget for editing.

Drawn Context

The Drawn Context is used only within the Idea Studio. It does not create a permanent link to any tag so far as the definition of the widget is concerned. It does allow you to select one tag to be used to provide values for display within the Idea Studio. This is extremely helpful as it provides context for everything you see as you edit the widget.

Linked Tag Properties

The objects you selected when creating a tag widget were linked to tags. After grouping, the link changes from a specific tag to a type of parameter called a "linked tag property". This is a very powerful concept that gets it's own chapter. (Linked Tag Properties)


Linked Tag Properties

Widgets are linked to tags. Properties of those tags can therefore be accessed and displayed in the widget.

In the majority of cases, the only property that is used is the tag's value, but you can link any property of any tag to any display property of anything within any tag widget that you create.

For example, you could:

  • Set the color of an object based on Area - Objects in the East area will be green and objects in the West area will be purple.
  • Tie the opacity of an object to a child tag's Start Tag expression. If the tag doesn't start, the object doesn't show. (Setting a widget's opacity to zero is roughly equivalent to disabling that widget. The code for the widget just doesn't run.)
  • Change the scale of an object based on an analog tag's scaled max property.
  • Create a label to match the name, area, and description of the linked tag.

If you examine the properties of any child widget, you'll discover that the data source selector has a new symbol, as circled in the following image:

Note the symbol used for the data source. Tag names shown here are generic examples.

Suppose that you decide to add a new VTScada widget to your custom tag widget. Perhaps it's a Numeric Value so that an Analog Status is displayed as a number as well as a moving indicator. You can do this simply by dragging a Numeric Value to the widget, just as if you were drawing one on a page. But, you absolutely must not link that new widget to any tag.

Instead:

  1. Open its properties dialog and click the arrow for the data source selection:

The data source selection arrow.

  2. Choose the option, Linked Tag Property

Selecting the Linked Tag Property data source. Other options, not shown here, may be available.

  3. Expand the Linked Tag Property selection and navigate through the child tags to select the one you want. In this example the "Linked Tag" is a custom type and the Analog Status is a child of a child of that type.

Selecting a child tag of the linked type.

The result is that the widget can be used for the Level of any instance of the custom tag structure.

One common example is to display the tag name or description as a label within the widget. You might also choose to display the area value, create a calculation that uses the tag's minimum and maximum scaled values, or add the engineering units to the display.

Example: Configure a text label to display the description field of the linked tag.

Prerequisites: This procedure applies only to tag widgets. The tag widget must be open for editing in the Idea Studio. Text has been added to the widget as a label.

  1. Open the properties dialog of the text label.

  2. Click the button as indicated. This provides access to a selection of data sources for the text to display.

  3. Choose the option, Linked Tag Property.

The text input field will be replaced with a drop-down list of tag properties. The list of possible properties comes from the list of types that the widget can be linked to.

  4. Expand the list to find and select Description.

Each instance of the widget will now show the description field of the tag to which it is linked. Note that this works, even though you did not use an expression with \GetPhrase().

You might want the property to be only part of the label, or to create an expression that uses the property. After following the procedure described in the example, you can change the data source to Expression. You will find that the expression for the linked tag property is "Root\Property_Name". Use this in an expression as required.

Take care: this information is for widgets linked to tags, not for parameter expressions in general. Here, "Root" refers to the current Drawn Tag Context. Use only when working with properties of a tag widget.

For example, to display the current tag's area value as part of the label "Tank in area: X", the process is:

  1. Create a parameterized phrase. (Multilingual Expressions, on page 1)

The expression is "Description", which returns the
phrase key for the text shown in the Description parameter.

  2. Use that phrase key in your expression and hand in the root tag's Area property for the parameter.
\GetParmPhrase("1Mtq2g5", \Root\Area)

Opacity Versus Linked Tag Properties

You were able to hide the Numeric Value widget based on whether the Flow had started because it is a child of a parent tag that is still there and running. Also, you were working with an I/O tag, which has a Started property.

Trying to do the same thing with the overall widget for your CustomPump (as an example) would be more complicated. First, user-defined types do not have a Started property or variable. Instead, you would need to refer to the Tag_Start_Condition property. But if the tag doesn't start, then that's neither 0 or 1 - the tag effectively doesn't exist at all. What you're likely to get instead is an unlinked widget, not an invisible one.


Build a Station Widget

Customers using the Station and Site Tags that come with VTScada have access to a number of complex widgets design to show aspects of the station. For example, the Well Details Widget:

These widgets are designed to work with Station tags and cannot be used for your custom tags, even though there may be similarities. Fortunately, you can create your own versions as Tag Widgets. Specific details for how to do so will vary according to your tag structures, but the general steps are:

  1. Create a tag structure for the well, or similar equipment (see: Design Your Own Tags).
    This must include all the I/O tags that you want to represent in the widget, and it must be created as a named type, not left as a Context tag.
  2. Plan the overall layout of the widget.
    You might use the Well Details as a starting point. The background is a selection of imported images.
  3. Draw the I/O tags within the planned layout.
    In the Well Details widget, Equipment / Status Color Indicator widgets are used for the two wells.
    The Numeric Value Widget is used for various read-outs and a greatly simplified Historian Status Widget is used for the last 24 hours of the well level. The well level is a Top Bar Widget with a partially transparent color.
    The moving text uses an expression for its vertical motion parameter as described in the article Tag Widgets.
  4. Group the background and all the relevant widgets into a new Tag Widget.
  5. Use for the rest of your wells.


Step Buttons

Meaning, "a button that will increase (or decrease) a value by 1". VTScada does not include a step button widget, but you can easily create your own. In addition to the widget, you'll need two Multi-Write Tags that you will create as children of the output tag for which you want to add step buttons. Multi-write tags do not count against your license.

Preparation:

An I/O tag that writes an analog value, and for which you want to add step buttons.

This example uses the High Level Setpoint tag, found in the Training Simulator.

Part 1. Create two MultiWrite tags:

  1. Add a MultiWrite tag as a child of your I/O tag.
    In this example, it is named Step Up.
  2. In the Write List tab of the MultiWrite, select the parent tag.

The purpose of the next two steps is to make this tag generic, so that it can be copied to any output tag where it will work without additional configuration.

  3. Select the path button (circled with a dotted line in previous image).
  4. Select the option, Ancestor Relative Path.

    The path should now read [..\*Numeric], followed by the description of the tag you are using as the parent.
  5. Click once in the Value column.
  6. Select the option, Expression.
  7. Open the expression editor.

  8. Enter [..\*Numeric] + 1 then select OK to save your work.

  9. Apply your changes and close the tag configuration dialog.
  10. Copy Step Up
  11. Paste it as a child of the High Setpoint, I/O tag, changing the name to Step Down
  12. Edit the properties of Step Down to change the expression to subtract 1 instead of adding.
    [..\*Numeric] - 1

Step Up and Step Down can now be copied as children of any output tag for which want to add Step Buttons. The link to the new parent will be automatic thanks to the use of Ancestor Relative Path.

The next set of steps will create the basic output control plus two step buttons and save them as a widget for re-use.

Part 2: Create a Widget:

  1. Draw the output tag as a Numeric Entry widget.
  2. Adjust the appearance of that widget as you see fit but do not select a font for the label and do not provide a title.
  3. Draw Step Up as a MultiWrite Button, placing it beside the Numeric Entry.
  4. Change the label of the button to +
  5. Draw Step Down as a MultiWrite Button, placing it below the button for Step Up.
  6. Change the label of the button to -

  7. Adjust the appearance as you see fit.
  8. Group as a Tag Widget.
    In this example, the widget is named Step Controls.
  9. Ensure that the default tag selection is the original output tag.
    If not, then ensure that both step controls are linked to MultiWrite buttons that are children of that tag and that no widget is configured to use a font or any other identifiable tag.
  10. Select OK to finish.
  11. Open the properties of the new widget.
  12. Select the Disable Trend option.

Suggested Enhancement: Add text to the widget as a label. Use Linked Tag Properties so that the text shows the ShortName of the output tag.


Delete a Widget

VTScada widgets cannot be deleted, but you can delete the ones that you created.

Both plain widgets and tag widgets are added to the palette menu automatically. You may have edited the menu to control which folder the widget is stored within.

It is up to you to remove all instances of the widget from the palette before deleting it. You may choose to clean up the palette menu later, at which time the widget's entry will use a cryptic unique id rather than the former name.

To remove a group:

  1. Select the group.
  2. Right-click to open the context menu.
  3. Click, Ungroup.

To delete a plain widget or a tag widget:

  1. Open the Idea Studio.
  2. Open the widget for editing
    Right-click on an instance and select Edit from the menu, or use the File menu to open the widget.
  3. In the Widget Properties toolbar, click Delete Widget.


Select and Arrange

It is usually the case that you will want to adjust things after you draw them on a page. They might need to be aligned with other objects, nudged a bit up or down, or have their display order changed so that they do not "hide" behind other objects. In all cases, you must select objects before using the format tools.

To treat a selection of several objects as one you may choose to create a temporary group using the objects.

The Multi Image Widgets panel may be configured to open automatically whenever a multi-image widget is selected. This may be inconvenient at times. You can disable this behavior within the Multi Image Widgets panel.

Click on an object.

A left-click selects the object. A right-click selects the object and opens the related context menu.

Any other objects that were already selected will be deselected. You can use this to cycle through objects that overlap.

Ctrl-Click and Shift-Click.

Both are the same. Hold the Ctrl key or the Shift key down while clicking on objects. Adds or removes objects to/from a selection set. Other objects that were already selected remain part of the selection set.

Use the Layer panel to choose the anchor Closed One object within a selection set, indicated by a bold border. Tools to align and to match properties will use this as the reference object. object within a selection set.

Click on an empty spot and drag the cursor over one or more objects.

Sometimes, referred to as a sweep select. A right-to-left selection gathers only objects completely inside the window.

Right-to-left is a window selection

A left-to-right selection gathers every object it touches.

Left-to-right is a crossing selection

The Shift or Ctrl keys work with a window in the same way that they work with individual clicks. Objects will toggle between selected and deselected without any effect on the selection set outside the window area.

Press Ctrl-A on the keyboard

All objects on the page will be selected.

Use Select All in the home ribbon

This is the same as pressing Ctrl-A on the keyboard.

Filtered Selection

Use "Select of this type" in the home ribbon

Selects all objects of the chosen type.

Use Invert Selection from the home ribbon.

In a crowded page, you may find that it's easier to select the objects that you don't want. If so, you can select those and use Invert Selection to swap them for the objects that you did want to select.

Groups

A group is a collection of objects, joined together for the purpose of selection and editing.

Groups are named automatically and are not added to any of the palettes. You can copy and paste groups, but there is no list of groups to select from.

Use groups as an extension of the selection tools. Groups are very helpful to use when editing your pages. They allow a set of objects to be treated as a single item. In a crowded page, it is much easier to click on one part of a group to select the whole than to try to select each and every component.

Alignment of individual objects

Alignment of grouped objects

To create a group:

  1. Select the objects that are to be included in the group.
  2. Expand the Group option in the toolbar and click "Group".

You could also right-click on any member object, and click "Group" from the menu that opens.

Formatting commands apply to a group as a whole, but are more limited for the group than for the component objects. For example, a group cannot be rotated, even if the component parts could be.

In essence, a group is a page drawn on another page. If you click the Edit command for a selected group, it opens as a page, where the individual components may be modified, and new parts added. For advanced developers, each group is stored in a .SRC file, using exactly the same format as found in a page or widget's source code file.

A group may be ungrouped as easily as it was first assembled. An "Ungroup" command can be found in both the toolbar and the right-click context menu for each group.


Snap Lines

The Snap Lines tool in the Format toolbar is used for two purposes:

  • You can enable or disable alignment snap with a click.
  • You can set the colors of the alignment lines and the default spacing using the Advanced mode.

Access the snap line control dialog

When Snap Lines have been disabled, all automatic alignment features will be disabled, including proximity snaps to existing objects. Alignment guides will not appear.

The advanced mode opens the Snap Line Options dialog:

Snap line options

Snap line options

Alignment refers to the dashed line that indicates edge or center alignment.

Dynamic Space arrows appear when you are adding objects to an array and the new object is nearly at the same spacing of existing objects.

The Fixed Space is a user-controlled, default distance for adding new objects relative to existing objects.

Dynamic (equal) spacing arrows take the size of the entire object into account, including space left for labels, even though you may not be using those. This might lead to unexpected results. In the following image, the "stars" in the first view are actually very short spacing arrows. In the second image, the center object is selected, revealing the full size of its bounding box.


Display Order

The toolbar commands, Bring Forward and Send Back, can be used to change which object appears to be in front of other objects. Referring to the image, similar options exist for Send Backward as those shown for Bring Forward.

The most recently drawn object will always appear to be on top of other objects. This remains true as it or other objects are moved about the page.

When changing display order, you can choose to send objects all the way forward or back, or you can move them one step at a time, relative to other objects on the screen.

If there are several objects in the selection set, they will retain their display order relative to each other, and will be brought forward or sent back as a group relative to other objects on the screen.


Align

This topic covers both alignment while dragging and alignment of objects within a selection set.
The procedures apply to Widgets, Images, Text, and Shapes.

To disable alignment snap temporarily, hold the Ctrl key down while dragging. Use the Snap Lines tool to enable or disable alignment snaps.

Align while dragging

  1. While you drag an object across a page, alignment lines will automatically appear, matching an edge or center of the object you are dragging to the edge or center of existing objects.
  2. When aligned with two existing objects, or more that are equally spaced, red distance alignments will indicate when the object being dragged is at an equal spacing with respect to the existing objects.
  3. Click when the alignment line indicates that the object you are dragging is properly aligned with an existing object.

Notes:

  • Automatic alignment works both horizontally and vertically.
  • Alignment snaps work for the top, bottom and center of any object.
  • When a group of objects is being moved, alignment snaps refer to the overall bounding box of all selected objects, not for individual objects within the group.

Troubleshooting:

  • There are too many objects - alignment lines appear everywhere.

Zoom in until fewer objects are visible.

  • Alignment lines are not appearing as expected on existing objects.

It is likely that the existing objects have been grouped. Alignment lines treat the group as a whole, rather than finding the individual elements within the group.

Align Selected Objects

Tools are provided to align a set of selected objects along a common edge or center. You can also space the selected objects equally, either horizontally or vertically.

  1. Select two or more objects.

One object in the selection will have a bold bounding rectangle. It is the anchor / reference point, to which the other objects will be aligned.

  2. To select a different object as the anchor, hold down the Ctrl key and click it once to deselect, then again to re-select.
    The most recently selected object will be the anchor.
  3. Click Align to open the menu of alignment options.
  4. Click on the desired alignment option.

Troubleshooting:

  • Unwanted objects are selected.

Use the Layers panel to manage your selections.

  • Alignment did not happen as expected.

It is likely that the selection includes objects that have been grouped. Alignment actions treat the group as a whole, rather than finding the individual elements within the group.


Nudge to Move and Re-Size

You will often want to move an object by only one or two pixels. Or, you may want the object to be a few pixels larger. Movement across such small distances can be difficult to control using only the mouse, even if you first re-size the display using the zoom feature of the Idea Studio. The solution is to use the arrow keys to nudge selected objects. An arrow key alone will nudge by 1 pixel. Hold the Shift key to nudge by 10 pixels.

Note that you can also adjust the size and location of an object one pixel at a time using the Coordinates panel of the Properties dialog.

To move an object by nudging:

  1. Select one or more objects.
  2. Tap the arrow keys on the keyboard.
    The select object(s) will move by one pixel for each arrow key tap, in the direction indicated by the arrow key that you use.
  3. Finish the action by pressing the Enter key, or by left-clicking anywhere on the Idea Studio canvas.

To resize an object by nudging:

  1. Select one or more objects.
  2. Hold the Alt key down while tapping the arrow keys on the keyboard.
    Hold both Alt and Shift to lock the aspect ratio while the object is being re-sized.
    The select object(s) will be re-sized(1) by one pixel for each arrow key tap, in the direction indicated by the arrow key that you use.
  3. Finish the action by pressing the Enter key, or by left-clicking anywhere on the Idea Studio canvas.

(1)The base point of every object is its upper-left corner. It will be re-sized relative to that point. Therefore, it is always the right edge or the lower edge that will move in response to each nudge.
Re-sizing a pipe or line by nudging means changing its width.

Ctrl-Z can be used at any time in the Idea Studio to undo.


Coordinates

Any object can be sized or positioned using its coordinates. Dragging, stretching, or nudging an object on the page will change the values shown in the coordinates dialog. The values refer to the object's bounding box, which is always rectangular, regardless of the shape of the object.

Width and Height are measured relative to the top, left corner of the object's bounding box. Changing width and height will also change the values for the right and bottom coordinates. If you change the coordinates for any of the edges, the width and height will not remain the same unless the difference between opposite sides remains the same.

Coordinates property

If your goal is to move an object without resizing or it, you might prefer to use Nudge to Move and Re-Size


Formatting Tools

The Format ribbon of the Idea Studio is visible only when one or more objects are selected. A different format ribbon exists for each type of object, but the tools shown in the following image are common to most(1) ribbons.

(1)Notes:

  • Rotation cannot be used on all objects.
  • Align, Match and Group can be used only when two or more objects are selected.
  • With the exception of Scaling, Movement and Coordinates, changes apply to all selected objects that a tool may be used with.
  • The tools Scaling, Movement and Coordinates will open the selected object's Properties dialog. If more than one object is selected, only the anchor object within the selection set will be affected.

Before looking at the details for using each of these tools, take a moment to review the techniques and shortcuts available for selecting objects (See: Select and Arrange). When working with several objects, you might save time by creating a temporary group before using a format command.

When two or more objects are selected, several Format ribbons will be available, one for each object type in the selection set. Format changes will be applied to all selected objects that can be affected by the change, regardless of the format ribbon used.

In a selection set, the most recently added object is always the anchor object as indicated by a bold border.
Use shift-click or ctrl-click to remove and add objects to the set, thereby changing the anchor object.
The anchor object remains in place for alignment and sizing operations.


Opacity

The opacity of all VTScada objects can be adjusted, making them partially, or fully transparent.

The easiest way to adjust opacity is to select one or more objects, then click the Opacity button in the formatting toolbar. You can use any of the pre-set values for convenience or click on Custom to open the slider dialog. A value of 100% is fully opaque, and a value of 0% is fully transparent, and therefore invisible.

Advanced developers can use the data source button (left of the slider) to tie the opacity value of any object to a tag value or expression, thereby making the object fade or vanish in response to changing conditions. (See: Select a Data Source)

Note that only the numeric value is scaled between 0 and 1, as shown in the previous image. All other options scale between 0 and the default Max Scaled Value of tag, which is 100.


Rotation

  • Does not apply to lines or pipes.
  • Shapes, images, and text can be rotated.
  • Most widgets cannot be rotated.
  • If editing a widget that includes images, use the tools in the Images ribbon rather than the Widgets ribbon.

Rotation is always done around the geometric center of an object's bounding box, and always proceeds clockwise in units of degrees.

If you have selected more than one object, each will be turned independently about its own center. Objects that had already been rotated will be reset to zero before the new angle is applied.

All rotation is relative to an object's zero-position, rather than cumulative. The Reset option will always bring an object back to its original orientation.

Advanced developers can use the data source button (left of the slider) to tie the rotation value to a tag value or expression, thereby making the object turn in response to changing conditions. See: Select a Data Source

Widgets and rotation

Widgets themselves cannot be rotated, but if the widget uses one or more images (e.g. the equipment widgets and the indicator light widgets), then those images within the widget can be rotated to have the same effect. If this option is available for the selected widget, both the widgets ribbon and the images ribbon will be available. The Multi-Image Widgets panel will open automatically if the selected widget contains more than one image (and if you have not configured the Multi-Image Widgets panel to not open automatically).


Scale

Scaling can be applied to any object, using its properties dialog. Note that, stretching an object by dragging its corners has no effect on the scale values. Rather, scale is applied to the object as placed (or stretched) on the page.

The result of scaling operations will vary depending on the type of object being scaled. For example, when scaling a pipe (must first be made part of a group or widget) the length of the segments will scale, but the width will remain a set property of the pipe. When scaling an image, the pattern will scale or not depending on the image configuration.
Pages can be configured so that their contents will scale automatically as the page is resized. Refer to the link in the list of related topics.

Scaling can animated by being linked to a tag value or a VTScada programming expression. The result is similar to functionality built into the widgets, Top Bar, Bottom Bar, Right Bar and Left Bar. Scaling can be applied independently to any of an object's sides. See: Select a Data Source

Scaling can be applied to only one object at a time. If more than one object was selected, only the anchor object (shown with a darker highlight) will be affected. To scale a set of objects, group them first.

When the properties dialog is first opened to the scaling options, all will be set to "None". Select the Advanced option for every edge that will have scaling applied.

A scale factor of "1" is "100%".


Movement

Movement can be applied to any object, using its properties dialog. Note that, repositioning an object by dragging it on the page has no effect on the movement values. Rather, movement is applied to the object as placed on the page.

Movement can be animated by linking it to a tag value or a VTScada programming expression. The result is that the object will travel across the screen in response to changing conditions. For example, a numeric display of a holding tank level that moves up and down the tank, staying even with the fluid level. See: Select a Data Source

Movement can be applied to only one object at a time. If more than one object was selected, only the anchor object (shown with a darker highlight) will be affected.

When the properties dialog is first opened to the movement options, all will be set to "None". Select the Advanced option to view the controls.

The default option is to select a tag, whose value will be monitored across its scaled range. The "Use Tag Scaling" check box should normally be selected. The object will move from its original position, either left or right as selected using the drop down, in response to an increasing value of the tag being monitored. When the monitored tag is at its lowest scaled value, this object will be in its original position on the page. When the monitored tag reaches its maximum scaled value, this object will move by the number of pixels you specify.


Outline Properties

For any object that has a line or outline, you can modify the appearance using the properties dialog.

You must open the advanced properties option to see this view

The properties dialog will often open in the "Simple" format. Use the selection at the top of the dialog to access the Advanced format so that you can view and change all the available properties of the line or outline.

The standard method of setting the property values is to use the selectors to the right of each property. The color button opens the Select Color dialog, and the width and line style selectors open drop-down menus of options.

You can link property values to tags or expressions, thereby animating any property as it responds to changing conditions in the application. See: Select a Data Source


Fill Properties

For any enclosed object, you can modify the appearance of the fill using the properties dialog.

The properties dialog will often open in the "Simple" format. Use the selection at the top of the dialog to access the Advanced format so that you can view and change all the available properties of the line or outline.

The standard method of setting the property values is to use the selectors to the right of each property. The color button and background color button both open the Select Color dialog. The pattern selector opens a drop-down menus of options.

You can link property values to tags or expressions, thereby animating any property as it responds to changing conditions in the application. See: Select a Data Source


Match Properties

If you have images, shapes and widgets that are uneven in size, transparency, scaling, etc. you can use the Match Properties tools to apply properties from one to others in a selection set.

While Widgets, Images, Text, and Shapes may all be included in a selection set, not all of their properties can be matched.
For example, images cannot match a text font. Widgets cannot rotate.

To match properties:

  1. Select two or more objects.

One object in the selection will have a bold bounding rectangle. It is the anchor / reference object, whose properties will be applied to the other objects.

  2. To select a different object as the anchor, hold down the Ctrl key and click it once to deselect, then again to re-select.
    The most recently selected object will be the anchor.
  3. Click Match to open the menu of property options.
  4. Click on the desired property to match.

Troubleshooting:

  • Unwanted objects are selected.

Use the Layers panel to manage your selection sets.

  • I chose to match color, but the blue pump remained blue.

The pump might be blue because it uses a blue image rather than a gray image with a blue color applied. Use the Image Selection option of Match Properties to change the image used by this object.

  • Not all of the objects rotated.

Widgets cannot rotate.

  • The wrong object's properties were used.

Undo. Verify that the bold rectangle is around correct anchor object and match properties again.


Color Selector

The color selector is used in all cases where the color of a page, a widget or a shape can be changed (excepting pipes).

The Select Color dialog

In a few instances, such as when changing the background color of a page, a miniature color selector will be displayed. The miniature version is effective for quickly selecting a color when the full range of options is not required. Use the More Colors button in the miniature selector to open the full color selector.

This topic focuses on the options in the full version of the color selector.

For your convenience, the last several colors used are provided at the top left of the selector, allowing you to quickly match a new object to the color of an existing one.

A range of basic colors and matching shades is provided to help save you time when developing your applications. The second from the left is Active Orange, used with the Image Change widget (see following notes).

The Pick Color tool works within any VTScada window, even though the eyedropper image appears only within the Idea Studio. In other VTScada windows, clicking the standard pointer on any object will pick up that object's color for the selector.

Numeric color values may be provided using either Hue-Luminosity-Saturation or Red-Green-Blue values. You may also set an opacity value if you would like the object being colored to be partially or completely transparent.

The color sample area and sliders are designed to be intuitive to use.

Note: Color values are stored in code using hexadecimal aRGB Closed A colour value, defined as four, two-digit hexadecimal values. Alpha - Red - Green - Blue. An Alpha value of FF is assumed if only the RGB values are provided. values, having the form "<AARRGGBB>" for alpha, red, green, blue, where "alpha" refers to opacity.

Active Orange

Active Orange is not supported with .PNG format files. When creating an image to use in an Image Change widget, or selecting one to be covered by an Image Change with no image of its own, use the .BMP format.
If tiling an Image Change over a background image that contains areas of Active Orange, the Color Replace property of that background image must be set to Active Orange. That property cannot be set when an image is used as a page background.

The shade known as Active Orange, or Orange 241 has been designated to work with the Image Change Widget.

An image change, drawn without a selected image, is a rectangular region that will change color as the linked tag's value changes. The region will be visible only where it is above something drawn using Active Orange (see note, above). In practice, this is less effective on monitors with millions of colors than it was in the days of a 256 color palette. Blending at the edges of a color region tends to leave fragments of an orange-ish boundary, as shown in the following examples.

Active orange is defined as color 241 in the VTScada palette, or the RGB value, R=255, G=160, and B=0, with full opacity. ("<FFFFA000>"). In the Select Color dialog, it is the second color in the row of Basic Colors.

The following example shows a static image that includes an area of Active Orange. An Image Change widget, linked to a digital status tag, is drawn above the region. As the linked tag changes in value between state 0 and state 1, only the region of the Image Change above the Active Orange swatch will be visible and change color.

The dashed lines in the second image mark the boundary of the Image Change. It does not matter that covers a larger area than the orange triangles as only the portion on top of the Active Orange color will be visible.

Transparent Black

In imported images that do not support transparency, areas that are pure black in color (RGB value, #000000) will be rendered as fully transparent in VTScada.

Transparent black is not supported with .PNG files or any other format that supports transparency. Save your image file using the .BMP format if you wish to use this feature.

Any parts of an image that are drawn using this color will be transparent when placed on a page or used as an icon.

To see an example of this at work, try opening any of the equipment graphics provided by VTScada using a graphic software program such as Paint. You will notice that all equipment objects actually have black backgrounds, however, when these images are placed on a VTScada application page, the backgrounds appear to be transparent. An example follows:

An image, with areas drawn using pure black:

The same image drawn on a white VTScada page:

To create your own custom graphics that include transparent areas, use the transparent black color wherever you want background objects on the page to show through.


Adjust Image Dialog

Can be opened using the Adjust button within the properties dialog of any image or widget containing images. Many of the tools within this dialog are also available in the formatting ribbons.

The Adjust Image dialog has two modes. Note that the advanced mode will open by default in some cases, such as when editing an image within an Image Change widget.

The advanced mode includes the button, Reset to Defaults, which may be used to repair poor choices in configuration.

Basic mode

Advanced mode

If linking a widget property to a tag value as part of an expression, you should use the [<TagName>] notation, specifying an absolute path reference to the tag. See: Use Tag Values in Expressions

Colorize

Many images in the library are provided in a gray-scale format. You can use this to add vibrant (or other) color. Indicator lights, found within various widgets, make use of this technique to allow a plain gray disk to appear as a glowing red or green lamp.

With the Colorize sub-menu, you can select one of the pre-set colors to quickly add a tint, or you can open the Select Color dialog to gain access to the full range of options for applying tint, hue, saturation, opacity, and other features.

Mirror Image

Flips the image from left to right. There is no vertical mirror option.

Antialias

Causes images that have jagged edges to appear to have smoother lines by feathering the edge. Note that the feathering may increase the size of the image by extending the boundaries.

Rotation Angle

Rotation is always done around the geometric center of an object's bounding box, and always proceeds clockwise in units of degrees.

Opacity

A sliding scale from fully transparent (zero) to fully opaque (1).

Brightness

A value of 1 (one) uses the image's original brightness. Possible values range from zero (black) to four (white).

Contrast

A value of 1 (one) uses the image's original contrast. Possible values range from zero (a uniform gray with no contrast) to four (very nearly washed-out).

Hue

Useful only if the image is not gray. Values range from -180 to 180 and may be thought of as degrees around the circle of a color wheel, where zero is the starting point. By shifting the hue, you change the base color.

Saturation

Describes the intensity of the hue. In this dialog, saturation can range from zero to two, with one representing the originally defined saturation.

Add Tint

Where hue describes the color of the object, a tint can be thought of as a colored light shining on that object. This slider controls the intensity (saturation) of that light.

Tint Hue

Controls the color (hue) of light shone on the object. Can range from -180 to 180, representing values around the color wheel.


Image Properties Dialog

Provides an alternative method of formatting an image. The tools found here can also be found in the Format Images ribbon.

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Tile Image and Scale Factor

Creates a repeating pattern of the image within the defined image area. The scale factor changes the size of each copy relative to the original.

Color Replace

Use the Color Replace option if the image includes a color indicator patch, or if you have selected the No Image option. (Color indicators within images are areas of Active Orange.


Image Formatting

Any image that you have added to a page can be modified to suit your purpose. Beyond the usual display and alignment tools, all of the following can be used to adjust images. In all cases, the original image appearance can be restored by clicking the Reset tool. Formatting options change how an instance of the image is displayed. They do not change the image file.

Images have no "Link" option to tie them to a tag. They are essentially static, although any property (movement, scaling, etc.) can be animated by linking that property to a tag value or to an expression.
The Style Settings tag has no effect on images and should not be linked to any property.
For information about accessing image properties and linking them to tag values, see: Adjust Image Dialog

Image formatting options

Color Replace

(Properties dialog only) Relevant only if the image includes a color indicator patch, or if within an Image Change widget, you have selected the No Image option. Color indicators within images are areas of Active Orange.

Change Image

Opens the Select Image palette, from which you can select a new image to replace the one being used. Other formatting commands that had been applied to the original image will remain in effect for the new one.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Brightness

Similar to contrast, rotate and other controls.

Adjust the brightness of the image using one of the pre-set values or click Custom to open a slider. Brightness can be adjusted up or down. A value of 1 (one) uses the image's original brightness. Possible values range from zero (black) to four (white).

Contrast

Increase or decrease the difference between bright and dark shades within the image. At higher contrast, bright shades become brighter and dark shades become darker, making certain details easier to distinguish up to a point. At very low contrast, all shades approach a uniform intensity within each hue. Values range between zero and four, with one being the image's original contrast.

Both the brightness and the contrast dialogs include a data source button (left of the slider), which advanced developers can use to tie the property to a tag value or expression, thereby making the object change in response to operating conditions.

Colorize

Many images in the library are provided as in a plain, gray-scale format. You can use this to add vibrant (or other) color. Indicator lights, found within various widgets, make use of this technique to allow a plain gray disk to appear as a glowing red or green lamp.

With the Colorize sub-menu, you can select one of the preset colors to quickly add a tint, or you can open the Select Color dialog to gain access to the full range of options for applying tint, hue, saturation, opacity, and other features.

When creating your own gray images, use color #888888 for best results. Gradients based around this shade will also work well.

Mirror

Flips the image from left to right. There is no vertical mirror option.

Anti-alias

Causes images that have jagged edges to appear to have smoother lines.

Image Properties Dialog

You can also modify an image using its properties dialog. This has links to all of the tools found in the ribbon, plus one: The Tile and Scale Factor option.

Image Properties dialog

Tiled images

While any image can be tiled, this option is intended for use with backgrounds such as water, wood, stone and metal. When the Tile option is selected, the details show at their original size, and the image is cropped or repeatedly tiled to fill the area you have specified.

If the Tile option is not selected, the image is scaled to fit the specified area.

Scaling images with the tile option on versus off


Text Formatting

The control you have over the appearance of text in your application depends on how the text was created.

  • Single-line text, created using the Text command in the ribbon has the most options for formatting, and is described in this topic.
  • Multi-line text, created from the Widgets palette offers a selection of font, color and border, as described in the Multi-Line Widget topic.
  • Labels built into VTScada widgets are controlled by the built-in Font tags. Use care if modifying those tags as there can be an adverse effect on the VTScada widget labels.

Single Line Text

The Format Ribbon applies to single line (standard) text only. That is, words created using the Text command of the Home ribbon. Use the following ribbon tools to adjust the appearance of selected text.

Color
(Highlight and Text) 		The two options control the highlight (background) and the text color. By default, the background is fully transparent.
Color options are not stored with named styles.
Font

Choose any system font installed on your computer and set display characteristics including size (measured in points), bold, italic, or underline.

Selected text responds to the keyboard shortcuts Ctrl-I (italic), Ctrl-B (bold), and Ctrl-U (underline).

Choices made here can be stored in a named style for use with other text. See: Font Tags.

Alignment Configuration of both horizontal and vertical alignment, relative to the bounding box containing the text.
If the text does not fit within the bounding box provided, the end of the line will be clipped.
Saved Fonts

Fonts are saved in Font Tags. Alignment and color configuration are not included in the properties that can be saved.

If you make changes in the Fonts section of the ribbon, you can choose to apply those changes to one of the existing fonts, or to create a new Font tag.

Built-in labels on VTScada widgets make use of the standard Font tags. Changes to the format of those may cause various labels to become difficult to read.

Opening the Manage Fonts dialog results in the Tag Browser opening, filtered to the Font type.

The ribbon options are also available in the form of a properties dialog box.

A selection of options within the Text Properties dialog

For ease of use, the ribbon is recommended. Advanced users, who are familiar with the VTScada scripting language, can use the tools in the properties dialog to tie display characteristics to expressions or tag values.


Advanced Formatting: Options for Properties

Many property dialogs offer a range of options for supplying the value to any given property. Use these to make a property change dynamically in response to changing conditions in the application.

Four options to supply a value for a property

Four of the many ways to supply a value to a property

The default symbol indicates the kind of value that the property can hold, whether that is a link to a tag, a number, a color, etc.

As shown in the following image, you can click on the arrow to be presented with a range of options for how to supply a property value in a way other than direct (and static) configuration in the properties dialog.

Typical options to supply a value to a parameter
Options may vary by value type. The first is always the default.

Options

Tag Value

Select a tag whose value type matches that needed by the property.

Numeric Value

Provide a constant value to be used by the property.

Parameter

Pages and user-defined widgets (both standard and tag widgets) can have parameters. If this object is within one of those, you can select a parameter from the page or widget to pass its value to this object parameter.

Linked Tag Property

Applies if the object is within a user-defined Tag Widget. The value for the parameter can be supplied by a property of the correct value type within the linked tag.

Expression or Text Expression

Write a steady-state expression to supply the value to the parameter.

Value Ranges

Most parameters will have a range of accepted values. For example, color is typically provided as text in the form "<AARRGGBB>" (Alpha - Red - Green - Blue, supplied as hexadecimal values). Color parameters will also accept a numeric value from 0 to 255 corresponding to the VTScada color palette.

If the parameter is a selection such as Alignment (left, right, center), On/Off, True/False, etc. the range of possible numeric values is restricted to those matching the selection, starting at 0. The order is typically shown in the default values:

Numeric values in a selection set


Import / Export Widgets and Pages

As of VTScada version 12.0, widgets and pages must be exported from one application in order to be imported to another. This process ensures that phrases matching all text and labels in that widget will be included.

Resources used by the widget such as images and custom Style Settings tags, will need to be imported separately. Tags and tag definitions are never included with widgets.

The import tool will handle only those widgets or pages that are contained within a single source code file. If you have developed a widget that spans multiple files, you must add it to your application manually. Refer to procedures described in the Scripting chapters of the documentation. Note also that if you are attempting to do a manual import of a modern widget into a legacy application that does not have LocalScopeSyntax set to 1, then before you do the import you must edit any function calls that use the "." separator to use the "\" separator instead.

To export a widget or page:

  1. Open the Idea Studio.
    (You do not need to open the widget.)
  2. Select File Menu >> Export
  3. A dialog will open, showing a selection of all the pages and widgets in your application, for which you have source code.
  4. Select the widget (or page) to export.
  5. Browse to the location on the hard drive where you want to save the file.
  6. Provide a name for the file you are creating with the export.
    (In most cases, you should make this match the name of the widget being exported, for the sake of easier identification.)
  7. Select OK to finish.

Pages that contain custom widgets

If exporting a page that contains custom widgets, you will be reminded that those must also be exported.

At the destination, import the widgets and groups before importing the page. Note that the list shows the file name of the widget, not the title.

If the page contains unnamed groups you must ungroup those before the export.

Use either the Filtered Selection tool in the toolbar or the Layers Panel to find and select all groups, then right-click on each in turn to open a menu that will contain an "ungroup" option.

Named widgets do need to be ungrouped before export, so long as you export those as well to send with the exported page.

To import a widget:

  1. Open the Idea Studio >> File Menu >> Import
  2. Select Widget.
  3. Browse to select the widget's .SRC file.

Tags are not included with the widgets or pages. It's up to you to ensure that you have matching tags within your application that can be linked to the widget's parameters.

The exported version of a page or widget contains a language information header in XML format. You are advised to avoid making changes to this part of the exported file.


Alarms

Alarms warn when the monitored system is not functioning properly.

The VTScada alarm system does much more than just notify operators when a pump has stopped running, or a well level is low. The system also stores a record of every operational and security event that occurs in the system. To differentiate between the two, the word alarm refers to situations that require an operator's action to prevent damage to life or property. The word event refers to a record of something that did not require an operator's attention.

VTScada has an optional Alarm Notification System that can be configured to contact designated remote operators by voice, pager, SMS text, or email if alarms are left unacknowledged for a defined period of time.

Important Alarm Terms

Active / Active Alarm

The trigger for the alarm has reached or is past the setpoint. For digitals, the tag's value is in the state that triggers the alarm.

Normal / Normalize

After triggering an alarm, the tag's value returns to a normal operating condition. The alarm remains "Current" and must still be acknowledged.

Inactive

There is no such thing as an "Inactive" alarm. The opposite of "Active" is "Normal".
That said, alarms can be shelved by operators or disabled by developers.

Current

Any alarm that is either Active or Unacknowledged.
(But not Shelved or Disabled.)

Trip / Trip Alarm

Seldom used and applies only to alarms triggered by a digital tag's state. Removes consideration of Active or Normalized. A Trip alarm is not included in the list of Active alarms, but it is Current and must be Acknowledged. (Remember, there is no such thing as an "inactive" alarm.)

Shelved

Used by busy operators to hide (temporarily) unacknowledged alarms that are less urgent while dealing with more important tasks.

Disabled

Used by developers to "switch off" an alarm trigger (and any current alarms from that trigger) rather than delete it entirely.

Suppressed

Alarm suppression is applied and removed automatically via a configured expression or tag reference. For example, if a "Low Flow" alarm is configured to detect a low flow rate, but the alarm is meaningless if the pump isn't running, then this alarm should be suppressed when the "Pump Running" tag is FALSE."

Alarm Databases(Alarm Database Tags) and Tag Hierarchies

Depending on the size and complexity of your application, there can be benefits from creating extra Alarm Databases. Do so if any of the following apply but avoid creating extra databases if they are not needed.

  • Security across realms.
    Realm filtering can be applied so that an operator can be restricted to see only the alarms from a single alarm database (or set of databases). All other databases could be hidden from this operator.
    Note that it is not a requirement that you create multiple alarm databases to use realm filtering.
  • Management of alarms.
    If operators in different roles or locations are required to look after a certain subset of alarms, those alarms could be kept in a separate database so that no filtering is required in the alarm list beyond the selection of which database's alarms to show.
  • Efficiency.
    It can be slow to filter alarm history if there are millions of alarm records in a database. If the alarms are distributed between multiple databases then each will be smaller, thus making it faster to filter alarm history.
  • Management of large, widely distributed systems.
    If two or more plants are part of the same application, and those plants are separated by a slow network link, then you can improve local performance by setting up an Historian-AlarmDatabase pair for each plant, where each plant will be use local server(s) for its primary server.
    (We do not recommend creating additional Historians except in large or widely-distributed systems.)


Create Alarms

All alarms are configured within tags. For some, it is part of the tag's configuration, for example, the I/O and Calculations tag, as well as several legacy types. For most other tag types, or to create an expression that considers several factors to trigger an alarm, you must create an Alarm tag.

Analog Status tags - alarms tab

High alarm within an
I/O tag in analog mode

Alarm tag - Trigger tab

Built-in alarm configuration is always the easiest to configure and in most cases all that you would need. The separate Alarm tag provides the most control over all aspects of alarm configuration.

There are three main parts to alarm configuration:

Alarm Identification

The tag's name, area and description are all important when configuring alarms. Names because that uniquely identifies the source of the alarm. Area because that is often used to sort and filter alarm lists. Also, Rosters for the VTScada Alarm Notification system are keyed to area. And description, because (when available) this is how alarms are reported to operators.

Alarm Trigger

An alarm on an analog tag is triggered by defining a high or low setpoint. When the value reaches or passes the setpoint, the alarm triggers and is said to be in an active state. An alarm on a digital tag is triggered by a given state, activating when the equipment enters that state, whether On or Off, Running or Stopped.

The setpoint can be predefined in the alarm, but it is always possible to configure operator or automatic control over the setpoint.

You might need to avoid nuisance alarms. Use either or both of:

  • Deadband - allows you to specify a range, within which the alarm will remain active if the triggering value retreats from the setpoint.
    The purpose of this feature is to prevent system noise from repeatedly triggering alarms or cluttering the record with repeating events. For example, a high alarm with a setpoint of 80 and a deadband of 2 will trigger when the value reaches 80, and remain in the active state so long as the value is above 78. Without the deadband, if the value hovered above and below 80, then each time it crossed the setpoint a new "active" or "normalized" record would be recorded.
  • Delay - allows you to ignore a brief spike in value.
    If you set an "on" delay, measured in seconds, the value must remain at or beyond the setpoint for that length of time before an alarm is triggered.
    An "off" delay is the reverse, used to prevent the alarm from returning to the normal state if the trigger briefly drops below the high setpoint or rises above the low setpoint.
    For alarms built into other tags, the only available delay is "On". Create a separate Alarm tag if you need an "Off" delay.

Alarm Priority and Action

For alarms built into tags, setting the priority is the step that creates the alarm. While the priority is set to "None", the alarm does not exist.

This tag has a High Alarm. It does not have a High High alarm.

Some developers, working under the idea of "just in case we need it later" have set alarm priorities but also selected the "disabled" option in the advanced mode. It is far easier on system resources to simply leave the priority as None until the alarm is needed.

Stand-alone Alarm tags do not have a "None" priority. They exist when you create them.

There are five priorities defined by five Alarm Priority Tags, which are included in every VTScada application. These control how the alarm looks and sounds (the "actions"). Using the advanced mode of a built-in alarm, or the Actions tab of an Alarm tag, you can override the some of the default actions from the priority and can add others such as enabling pop-ups or rearming.

Alarm tag - Actions tab

Features here include:

  • The ability to disable an alarm.
  • The ability to set a rule that will suppress the alarm.
  • A rearm time. When enabled, the alarm will return to the unacknowledged state after a given length of time if the triggering condition remains active.
  • Trip – For digital triggers only.
  • The name of a .WAV file may be provided in the sound field if you would like a customized alarm sound such as phasers firing or a warning of a warp core breach. (The file should be located in the application folder.)

Level alarms versus trip alarms:

"Level" alarms

Alarms that become active when a setpoint value is reached, and return to a non-active state if the value being monitored is no longer past the designated setpoint.

For example, if the alarm’s high level setpoint is 100 inches, the alarm will activate when the tank reaches that level. If the level then drops below 100 (plus optional deadband), the alarm will return to a normal state. (Although, it must still be acknowledged).

"Trip" alarms

Trip alarms do not have an active or inactive state. Something occurs to trip the alarm and that is all the information that matters.

If you shelve a trip alarm, then the act of unshelving it is taken to be equivalent to acknowledging it, whether you manually unshelve the trip alarm, or allow the shelving time to expire.

Typically, if an alarm is unsuppressed while in an active state, an event would be logged. However, because trip alarms do not have an active/normal state, unsuppressed trip alarms will not log an event.

They are usually added to digital tags, especially those that read fault status from the PLC. Trip alarms do sound and must be acknowledged. They are alarms.

The term "active" can be confusing. The thing to remember is that it refers to the cause of the alarm, not to the alarm itself, even though you are likely to hear people use the term "active alarm". By that, they mean an alarm whose cause has not returned to a normal operating condition.

There may be situations where the state of the system is not relevant after the alarm starts. All that you care about is that something rang the alarm. This is when you would configure the alarm as a trip alarm. A trip alarm is just as much an alarm as any other, but it will never be included in the list of "active alarms". A classic example is a burglar alarm where the alarm is triggered when the door opens. Nobody cares whether the burglar had the good manners to close the door after entering. The burglar alarm is not in the "active" list but it is still very "current" and there are lots of flashing lights and sirens.

Trip alarms are triggered only by digital I/O (or the equivalent). But there is no requirement that every alarm triggered by a digital value must be configured as a trip alarm.


Configure Alarms Within Tags

The following steps describe the general process to configure a built-in alarm within a tag. The available options are similar to those found in an Alarm tag but filtered as appropriate for digital or analog modes. Refer to the images that follow the steps.

The Alarms tab of an I/O tag configured as an Analog or Discrete type has both a basic and an advanced mode. Refer to I/O and Calculations tag: Alarms tab (Basic analog type) for relevant details.

  1. Open the "Alarms" tab of the tag.
  2. Choose which alarm to configure.
  3. Select a priority for the alarm.

Initially, all built-in alarms are set to "None" as a priority. The None option exists so that the tag will not be included in a list of disabled tags.

  4. Configure a set-point.

For a digital tag this is a selection of state 0 or state 1.
For an Analog Status, this is any number.

  5. Configure advanced options as necessary for your system.
    Refer to the description of the I/O and Calculations tag or the Alarm Tag for a complete reference of alarm options.

Alarm within an I/O tag in digital mode

Analog Status tags - alarms tab

High alarm within an I/O tag in analog mode


Alarm System Configuration

This chapter describes configuration of the overall VTScada alarm system. Refer to Create Alarms for information about creating and configuring specific alarms.

Alarm Databases

Alarms belong to Alarm Database tags. These tags specify which historian will store information from each alarm. By default, all alarms that you create belong to the System Alarm DB tag. See: Alarm Database Tags.

For the majority of applications, there is no need to create extra alarm databases, but locations that maintain large distributed systems might choose to do so. For those that do, it is possible to create display groups so that alarms from several, but not all, databases can be viewed at the same time.

Database groups are defined as an application property, AlarmDatabaseGroups. Multiple groups can be defined within the single property, each with a list of databases. Separate the groups with semi-colons and database names within each group by commas.

[System]
  AlarmDatabaseGroups       = Northeast Group:NorEast,NorWest;Southwest Group:SouWest,SouEast

See: Alarm Database Groups

Application Properties for Alarms

Over 70 properties exist to control the alarm system. These affect everything from default color choices to timings and VTScada actions in response to alarm events.

In the Alarms tab of the Edit Properties page of the VTScada Application Configuration dialog, you can find the most commonly adjusted properties. Many more are available in the Advanced view of the Edit Properties page. Refer to: Alarm Properties and Alarm Notification System Properties.

A small selection of the available properties

Automatic Alarm Acknowledgment

Automatic alarm acknowledgment does not apply to Trip alarms.

You can configure groups of alarms to be acknowledged automatically when the alarm clears. This may be useful in hosted systems for alarms that are not going to be acknowledged and in situations where operators use a separate HMI for daily tasks, rarely interacting with VTScada.

Do not use automatic alarm acknowledgment in any situation where operators are expected to acknowledge alarms.

To configure automatic acknowledgment for set of tags, add the setting AutoAckClearedAlarms to a parent Context Tags and set its value to 1 (TRUE). All subsequent alarms generated by tags below this Context will automatically be marked as acknowledged (Normal Ack) when the triggering value returns to a normal state.

To configure automatic acknowledgment for all tags in an application, add the System property, AutoAckClearedAlarms, to that application using the Advanced mode of the Edit Properties page of the Application Configuration dialog. Set the value to 1 (TRUE). All subsequent alarms generated in this application will automatically be marked as acknowledged (Normal Ack) when the triggering value returns to a normal state.

Custom Alarm Lists and Indicators

The greater part of the VTScada Alarm Page is an Alarm List widget. You can draw and configure Alarm List widgets of your own on any page you choose, creating customized lists that relate to a specific set or group of tags. You can also disable large sections of the tools within your custom Alarm List, then provide a small set of external tool widgets to allow basic tasks. See: Alarm Lists and Related Tools

To draw operator attention to a tag that is in an alarm state, especially if that tag is represented by a widget that does not have built-in alarm indications, you can add an Alarm Priority Box or Alarm Priority Icon to your pages.

Filter for Muting Alarm Sounds

VTScada programmers can write filters that control which alarms will sound and which are muted. This and many similar tasks are possible by adding Alarm Manager Hooks to your application code. See: Custom Alarm Hook API

It is risky to code customized solutions for VTScada without understanding how the language works. Small mistakes can result in code that will consume all of your computer's resources. You have been warned.


Customize Alarm Management

These notes usually refer to the "Alarm List" rather than the "Alarm Page". This is to emphasize the difference between the two. The Alarm Page is (mostly) just another page, but one that happens to contain a fully configured Alarm List. You can draw your own Alarm Lists on any page, configuring them as you like.

The first step is to add an Alarm List to a page. Look in the Widgets palette under Tools >> Alarm Tools. The initial size of the widget is 901 by 501 pixels. Developers often modify Alarm Lists to hide many of the features and fit it to a smaller area.

The Alarm List widget can be linked to a tag. This is equivalent to filtering for a specific tag and its children and may be useful for pages operators should have access only to the alarms within certain tag hierarchies. (And note that just because it can be linked to a tag, does not mean that it must be linked to a tag.)

The column format of alarm lists is controlled by the Alarm List widget, or by the selection in the Alarm Database properties Settings tab. Advanced developers can Customize Columns in Alarm Displays, by editing XML files.

Further details and steps are provided in the reference chapter of this documentation beginning with Alarm Lists and Related Tools.


Alarm Indicator Widgets

The Alarm Priority Icon (Alarm Priority Icon) and Alarm Priority Box (Alarm Priority Box) provide visible indications when the linked tag is in an active or unacknowledged alarm state, and when it is either shelved or disabled.

The icon will not be visible for alarms that are unacknowledged but no longer active unless the property AlarmPriorityIndicatorShowNormalUnacked is set to 1. The icon will always be displayed when the alarm is shelved or disabled.

Trip alarms are never in an active state; therefore this widget cannot be used to show those.

You can link this widget to a parent tag rather than a specific status or alarm tag. When linked to a parent, it will become activated when any child tag in the hierarchy is in an active alarm state. The icon will display the highest priority of the set of active alarms.

If the alarm (or set of alarms in child tags) includes a shelved alarm, then the widget will be activated and display an S. If the linked tag (or child tags) includes a disabled alarm, the widget will display an X.

If linked to a parent tag, and within the set of child tags there are unacknowledged alarms, active (but acknowledged) alarms, shelved alarms and disabled alarms, then the order of precedence for the display is as follows:

  1. Unacknowledged (icon blinks with the highest priority alarm of the set)
  2. Active (icon shows the highest priority alarm of the set)
  3. Disabled (icon shows an X)
  4. Shelved (icon shows an S)

Place the Alarm Priority Icon on a page, near to whatever image or shape represents the equipment that will trigger the alarm. The Alarm Priority Box can be used the same way, except that it adds a box for you to place around the equipment that is in an alarm state. The box is visible only when the icon is visible.


Configuring Spoken Alarms

Viewing: Develop > Alarms > Alarm System Configuration > Configuring Spoken Alarms

Spoken Alarms on the Server or Workstation

You can configure VTScada to speak an alarm at the workstation or server. Alarms can be spoken either in addition to the standard tone, or instead of the tone. This feature is available on VTScada Thin Clients as well as workstations running VTScada.

You can control what details are spoken by changing the template property. (Alarm Message Templates) You also have control over how words are pronounced by adjusting the lexicon. ( Speech Lexicon Configuration).

If an alarm is acknowledged while it is being spoken, the voice will stop immediately .

Requirements:

To hear a spoken alarm, all of the following must be in place:

  • Microsoft SAPI engine installed on the computer. (Installed by default with Windows®)
  • The workstation has speakers and audio ability.

Refer to your system configuration. Ensure that the speakers are turned on and that the volume is set to an audible level, both on the speakers and in the computer.

  • Application Properties related to the alarm text-to-speech system are set.

At a minimum, set the application property AlarmSpeechEnable to 1.

The list of properties was scrolled to this entry. This is not the first property in the page.

  • The Alarm Priority tags is configured to enable alarm speech.

As shown in the following image, the Enable Alarm Speech option is selected and the Alarm Annunciation Cycles set to a value greater than 0 in the Alarm Priority tag used by your alarm.

Option available only if AlarmSpeechEnable is 1, as per previous step.

  • The alarm is not configured to use a sound (.wav) file.

If the Alarm tag has a .wav file configured, only that sound will be played.

If the Alarm Priority tag has a .wav file configured, then if the number of sound cycles is set greater than 0, the .wav file will play before the spoken alarm.

If Sound Cycles is set to either 0, or Unlimited (-1), then only the spoken alarm will sound.

If Sound Cycles is set to 1, the tone will play once before the alarm is spoken.

Additional Configuration Options

The following options are available to you to control how, when and where alarms are spoken.

  • An alarm is spoken or not based on the configuration of its Alarm Priority tag.

The Enable Alarm Speech is selected and Alarm Annunciation Cycles set greater than zero.

  • Alarm tones or .WAV files may be played zero or more times before an alarm is spoken.

.WAV files may be configured in the Alarm Priority tag, but not in the Alarm.
Alarms with a configured .WAV file will not be spoken.

  • Spoken alarms may be configured to play one or more times.
  • Spoken alarms may be deactivated globally with the configuration setting, AlarmSpeechEnable.
  • If using the SAPI speech engine, you can select which voice (supported by the speech engine) to use.
  • You can select whether alarms should be spoken on all workstations, or on only the alarm server.

Configuration Settings

The following is an overview of the configuration settings that control the spoken alarms.

  • AlarmSpeechEnable

Set to 1 to enable spoken alarms. Alarm speech is disabled by default.

Use workstation-specific copies of this property to enable speech on some stations and disable it on others.

  • AlarmSpeechTemplate

Provides a template for spoken alarms to use. May be a combination of words and replaceable parameters.

  • AlarmSpeechVoice

If using the Microsoft speech engine, there are several voices that you could use. You can select which voice to use with this variable. In general, it is best to set this variable to a dash (-) to indicate "configured Windows voice".

  • AlarmSpeechQuality

Determines the format quality used for speech using the Microsoft speech engine. The number used for this variable will match an entry in a numbered list of formats. When set to -1, the quality native to the voice engine will be used. The default value of 6 balances audio quality against network transfer overhead.

  • AlarmSpeechInit

May be used to provide an initialization string to the speech engine to control the voice. Please refer to the SAPI documentation for the details of this initialization string.

  • SpeechEngine

May be used to select an alternate speech engine.

  • UseOldSpeechEngine

Obsolete. Maintained only for backward compatibility. If enabled, spoken alarms will not have access to the pronunciation configuration options.


Configure Speech Lexicon

Viewing: Develop > Alarms > Alarm System Configuration > Configure Speech Lexicon

Speech Lexicon Configuration

Use the Speech Lexicon dialog to adjust how words are pronounced when spoken by voice engine. If using a third party speech engine that provides its own lexicon configuration, disable the VTScada Speech Lexicon by changing the value of the property, EnableLexiconDialog to 0.

The Speech Lexicon is opened from the Alarms tab of the Edit Properties window:

The list of properties was scrolled to this entry. This is not the first property in the page.

The Speech Lexicon dialog

The lexicon settings are used with alarms spoken at the workstation, and with the Alarm Notification System. Although the speech engine will pronounce many words plainly and without a flaw, you should review abbreviations, place names, operator names, and alarm messages, adjusting as required so that they are pronounced clearly by the speech engine. Also, some users may prefer a localized pronunciation for certain words.

Set Speech Pronunciation

  1. Open the Configure Speech Lexicon dialog.
  2. Click Add. The Add Lexicon Word dialog opens as shown.

  3. Enter the word, phrase, or place name in the Key field.
  4. Click Speak button to the right of the Word field.
    The speech engine speaks the word, name, or phrase in the Key field.
  5. Identify which syllables you want to change.
  6. In the Phonetic Spelling field, enter the word or phrase using a Phonetic Spelling Reference, rather than a dictionary-correct spelling.

  7. Click the Speak button to the right of the phonetic spelling field.
    The speech engine speaks the word, name, or phrase as you have spelled it.
  8. Repeat as required to adjust the pronunciation until it sounds as you would like.
  9. Click OK. The word, name, or phrase is added to the Special Words list of the Dialer Pronunciation dialog.
  10. Click Add to add another word, name, or phrase, to the "Current Lexicon Contents" list. Click OK to close the dialog.

Certain two-letter combinations are pronounced as individual letters rather than their combined sound (example: HI). Others may have default words assigned (example: "AK" may be pronounced "Alaska" on some systems). Use an underscore with a two-letter combination to force pronunciation of both.

You can add, test, and configure as many unusual words, phrases, names, roots, abbreviations, places, and operator names as you require.


Phonetic Spelling Reference

Use the following phonemes in the VTScada Lexicon Dialog to control the sound of spoken words.

Note that, mixed case words are broken into shorter syllables (lower case letters) and individually pronounced letters (upper case letters). Thus, "VTScada" is pronounced "Vee Tee Scada".

Phoneme | Example | Phoneme | Example
- | syllable boundary (hyphen) | h | h as in help
! | sentence terminator (exclamation mark) | ih | i as in fill
& | word boundary | iy | ee as in feel
, | sentence terminator (comma) | jh | j as in joy
. | sentence terminator (period) | k | c as in cut
? | sentence terminator (question mark) | l | l as in lid
_ | silence (underscore) | m | m as in mat
1 | primary stress | n | n as in no
2 | secondary stress | ng | ng as in sing
aa | a as in father | ow | o as in go
ae | a as in cat | oy | o as in toy
ah | u as in cut | p | p as in put
ao | o as in dog | r | r as in red
aw | ou as in foul | s | s as in sit
ax | a as in ago | sh | sh as in she
ay | i as in bite | t | t as in talk
b | b as in big | th | th as in thin
ch | ch as in chin | uh | oo as in book
d | d as in dig | uw | oo as in too
dh | th as in then | v | v as in vat
eh | e as in pet | w | w as in with
er | ur as in fur | y | y as in yard
ey | a as in ate | z | z as in zap
f | f as in fork | zh | s as in pleasure
g | g as in gut |  |


Orphaned Alarms

It is rare but possible for an alarm to become "orphaned" during application development. For example, the following (completely contrived*) set of steps might lead to an orphaned alarm:

  1. Create an alarm and allow it to activate.
  2. Export the tag database to Excel.
  3. Remove the activated alarm tag.
  4. Set the property, AlarmDatabasePurgeDelay to a high value to delay VTScada's automatic clean-up process.
  5. Restart the application.
  6. Import the spreadsheet containing the modified tag list.
  7. From the Alarm Page, open the details dialog for the alarm.

Use this dialog to remove the alarm from the lists. In most cases, it is advisable to remove orphaned alarms from all lists. Confirmation is required. (No record can ever be removed from the history list, but if a tag was deleted, the record will show only its unique ID. This is done to avoid confusion with any new tag that you might create using the same name as the deleted tag.)

(*) These steps are not recommended practice, and there is no guarantee that they will succeed in creating this situation, which is undesirable in any event. The steps are provided only to give a sense of how an orphaned alarm might come to be.

Related information:

AlarmDatabasePurgeDelay


Alarm Notification System - Alerts by Phone, Email or Text

Viewing: Develop > Alarms > Alarm Notification System - Alerts by Phone, Email or Text

Concepts:

Roster Selection Hierarchy

Tasks:

Email Setup for Alarms and Reports

Reference:

Roster Tags

Modem Tags

SMS Appliance Tags

Alarm Notification System - Alerts by Phone, Email or Text

The Alarm Notification System will send alarm notifications to off-site operators by any of phone, email, pager message or SMS-text. Operators will see or hear the details of active alarms and (optionally) may acknowledge those alarms using the same format with which the alarm was sent.

This feature is an optional part of your VTScada license. Contact a representative of Trihedral Engineering Limited for further details. It is not available to VTScada Light installations.

Customers using the modem dialer feature of the Alarm Notification System must ensure that they apply Windows updates on a regular basis.
Updates to VTScada will often include modem drivers that have been patched to work with the latest Microsoft updates for your version of the Windows operating system. They may not work if you have not applied those updates to your system.

If using a voice modem, the workstation name configured in the modem tag must have fewer than 15 characters.

If running multiple applications (for example, hosted systems) then you cannot share modems, SMS devices, or Twilio accounts between applications. You must have independent modems or Twilio accounts for each application.

Only alarms with priority Critical (1) or High (2) are sent, and those only after they have gone unacknowledged for a configured length of time.

If a new alarm should occur while operators are being notified of existing alarms, or if the first person in the active roster has already been informed of an existing alarm when the new alarm occurs, the Alarm Notification System will start through the roster again with the first person on the contact list.

Having an operator sign in remotely through the Alarm Notification System does not affect the status of any operator who is signed in at the site.

The Alarms Tab of the Edit Properties Page contains several settings that control alarm notification behavior. See: Alarm Notification Options These should be reviewed before proceeding.

Hardware and Software Requirements:

VTScada cannot send notifications unless you provide the means to do so, therefore you must configure at least one of the following.

  • For spoken alarms, the Alarm Notification System uses either a modem, the Twilio service, or a VoIP service to make outgoing calls.
  • For email notifications, create an account on your email server then configure VTScada with the credentials to send and receive email through that account.
  • For SMS-text notifications, you will need an SMS appliance or Twilio.
    Many customers find it easier to send an SMS-ready email than to configure an SMS appliance.
  • For pager notifications, the system can use only a modem.

For the SMS text option: While VTScada will always attempt to send the text message, there is no guarantee that your the cellular provider will deliver all messages. Use the SMS option with caution.

VTScada Tag Requirements:

You will need to configure some or all of the following tags in your VTScada system:

Modem Tags - A Modem tag, if using a voice modem.

SMS Appliance Tags - A SMS Appliance tag, if sending and receiving text messages.

Roster Tags - One or more Roster tags, to control who is contacted, and how the notification is sent.

Trigger Tag - Trigger tags to automatically activate Rosters on schedule. Manual switching is done with a Make Active widget.

Other Configuration:

In addition to hardware and tag configuration, you may want to use the following:

Using Twilio for Alarm Notifications - Configure VTScada to send notifications using your Twilio account.

Alarm Area Filtering - Alarm Area Filtering or ...

Realm Filtering - Realm Filtering, to control which alarms an operator may view.

Speech Lexicon Configuration - Voice Lexicon configuration to control how words are pronounced.

Make Active Widget - Draw the Rosters as Make Active buttons, to enable manual switching from one roster to another. Automatic switching is done with a Trigger tag.

Alarm Notification Options - Configure which alarm priorities trigger a notification and the delay before sending. Also, which menu or sub-menu to read first in Alarm Notification System calls.

Alarm Message Templates - Template configuration to control what is sent in the alarm message.

Allow Acknowledgment by Email or SMS Text - Configuration requirements to allow acknowledgment.

Accounts and Roles - Configure security accounts to control who may acknowledge alarms, and to associate a user name with each alarm acknowledgment.

Alarm Notification System Properties - Related settings and properties.

Phone number formatting matters. You must use a format that is acceptable for whichever service provider or device you have opted to use. You are generally safe using the E.164 standard of canonical phone numbers Closed Microsoft Azure Active Directory app registration, an OAuth 2.0 provider., however, you are advised to check your device manual or check with your service provider to confirm their formatting rules.

Related information:

Alarm Data Logging - Alarm System Event Logging

Roster Selection Hierarchy - Rules governing which roster to use for an alarm.

Activate a Roster - Covers manual and automatic activation.

The Alarm Page - Operator instructions for using the alarm page and alarms sent from the Alarm Notification System.


Google & Microsoft vs Basic Authentication

Many VTScada customers rely on either Google or Microsoft’s email servers to send alarm notifications to operators. In 2022 both providers changed how third-party applications such as VTScada can access their systems. Authentication by username and password over POP3 and SMTP are no longer allowed and instead, access via OAuth 2.0 is required.

  • This change affects only customers using Google or Microsoft email servers.
    If your site maintains its own email server or if you are using a different provider, this change does not affect you.

  • Trihedral recommends OAuth 2.0, as it is required by both Google and Microsoft.
    Changing from basic authentication to this new system takes time and effort, but in today’s security environment it is simply not safe to continue using basic authentication.

  • You can try using an App Password.
    These are vendor-generated passwords that can be used only with a specific app or device. After generating the App Password, use that as the password when configuring outgoing and incoming email accounts in VTScada. While the instructions state that it need be used only once, you are advised to leave the App Password configured.
    Instructions to generate an App Password for Google are available at Google Support.
    Instructions to generate an App Password for Microsoft are available at Microsoft Support.

    Vendors note that this option is less secure than OAuth 2.0, therefore use at your own risk.

  • There may be other Internet-based email providers who do continue to provide basic authentication over POP3 and SMTP.
    While Trihedral cannot recommend these, we acknowledge that they are an option, especially for smaller sites that might find it challenging to implement an OAuth 2.0 solution.

Google is actively phasing out support for Basic Authentication. Your experience using Basic Authentication with Google products is subject to change. To learn more about the proposed time line, you must monitor news and updates from Google such as Google Workspace Updates

It has been reported that applications using a Google App Password for authentication have suddenly stopped sending notifications. While phasing out support for Basic Authentication, occasional Google Workspace updates may cause your application to be logged out. If this happens, you will have to log back in or generate a new App Password.

To implement OAuth 2.0

Before configuring VTScada to send and receive email using your OAuth 2.0 credentials you will need the following:

  1. Obtain an account with either Google or Microsoft Azure that allows OAuth 2.0 configuration, to be used by your VTScada server.
    Refer to the Google or the Microsoft documentation for specifics of how to create such an account. Both companies provide a variety of options, and we cannot provide guidance beyond noting the importance of ensuring that the account must allow for OAuth 2.0 configuration.

  2. Protect access to your VTScada server with an X.509 certificate. (Or as it is more commonly known, a TLS/SSL Certificate.) This is an absolute requirement for OAuth 2.0.
    Reference notes and instructions for installing a certificate are provided in the VTScada documentation: (Internet Security (TLS, X.509, SSL))

With those in place, you can proceed with OAuth 2.0 configuration for your VTScada email notifications. Reference notes, instructions and examples are provided in the VTScada documentation: (OAuth 2.0 Protocol)


Alarm Message Templates

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Control the content of alarm messages by defining templates using the Languages panel of the Application Configuration dialog. You can also add templates as properties of Context tags for use by alarms within a site or other user-defined tag structure.

You can define a separate template for each of:

Template name | Used for...
Section 1: Alarm message templates
AlarmDialerTemplate | Telephone alarm descriptions. The initial greeting is not set by a template. You can set the spoken name in the greeting using the Alarms tab of the Edit Properties dialog.
AlarmEmailTemplate | Emailed alarm descriptions. Does not apply to SMS-ready emails.
AlarmPagerTemplate | Paged alarm descriptions.
AlarmSMSTemplate | Descriptions of alarms when sent by SMS message including SMS-ready email.
AlarmSpeechTemplate | Locally spoken alarm descriptions Select "Speak alarms..." in the Alarms tab of the Edit Properties dialog, then configure one or more AlarmPriority tags to speak the alarm instead of playing a tone.
Section 2: Alarm status templates. If DialOnClear is enabled, the status will be appended to the message. Does not apply to locally spoken alarms.
AlarmDialerStatusTemplate | Alarm status appended to telephone messages.
AlarmEmailStatusTemplate | Alarm status appended to emailed alarms.
AlarmPagerStatusTemplate | Alarm status appended to paged alarms.
AlarmSMSStatusTemplate | Alarm status appended to SMS alarms, including SMS-ready emails.
Section 3: Additional email and SMS templates
AlarmEmailAckTemplate | Message confirming alarm acknowledgment by email.
AlarmEmailAckSubjectTemplate | Subject line for alarm acknowledgment by email.
AlarmEmailAckCollisionTemplate | Emailed message to operators, informing them that the code they used acknowledged more than one alarm.
AlarmSMSAckTemplate | Message confirming alarm acknowledgment by text.
AlarmSMSAckCollisionTemplate | Text message to operators, informing them that the code they used acknowledged more than one alarm.

In addition to these, you may set the subject line for alarm emails using the property, AlarmEmailSubjectTemplate.

The control string can be a combination of words and the following replaceable parameters. Note that the pause can add clarity to the message by separating words that might otherwise run together when spoken.

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Examples:

AlarmSpeechTemplate = %P alarm. %T, %M

Speaks (for example): "Critical alarm. 10:35 pm, Well level high"

AlarmSpeechTemplate = VTScada %P alarm in %A %W %M has reached %V at %T.

"VTScada critical alarm in zone one <pause> Holding tank level has reached eighty at eleven forty nine a. m.".

Context (Site) Tags and Alarm Notification

Context tags (or custom types derived from a Context tag) may define custom alarm message templates, for use by all alarms occurring within the structure. This is done by adding the desired template name(s) to the Context's list of properties. To create a custom property value that will be dynamic and unique for each instance, use tokens. A token will be replaced by the meaning it represents. All non-token characters will be passed along as a string. (To pass a percent sign as part of a string you must type %%)

A custom template with a value of:

Check: %D%T - %A - %M

will output a message like:

"Check: [Date][Time] - [Area] - [Alarm description]"

You cannot pass an expression in the value field of a Context tag's custom property. To do this, you must create a custom tag type. See Alarm Notification Templates for more detailed instructions.

Related information:

AlarmDialerStatusTemplate

AlarmDialerTemplate

AlarmEmailAckSubjectTemplate

AlarmEmailAckTemplate

AlarmEmailStatusTemplate

AlarmEmailSubjectTemplate

AlarmEmailTemplate

AlarmPagerStatusTemplate

AlarmPagerTemplate

AlarmSMSAckTemplate

AlarmSMSStatusTemplate

AlarmSMSTemplate

AlarmTemplateDateFmt - Controls the date format spoken.

AlarmTemplateTimeFmt - Controls the time format spoken.

AlarmEmailSubjectTemplate - Sets the subject line for alarm emails.


Email Setup for Alarms and Reports

Viewing: Develop > Alarms > Alarm Notification System - Alerts by Phone, Email or Text > Email Setup for Alarms and Reports

Concepts:

Alarm Notification System - Alerts by Phone, Email or Text

Roster Selection Hierarchy

Reference:

Roster Tags

Modem Tags

SMS Appliance Tags

Email Setup for Alarms and Reports

If your VTScada license includes the Alarm Notification System option, you can send alarm notifications to operators by email, and (optionally) you can allow them to acknowledge those alarms by replying to the email.

For all VTScada installations, you can configure reports so that they will be delivered by email.

VTScada does not have a built-in email server. For both alarms and reports by email, you will need access to an email server and you will need to provide connection parameters for it, including the account and password to use. All account credentials are stored in an encrypted format.

Customers using basic authentication (username and password) with either Microsoft or Google email accounts must start using OAuth 2.0 or switch to another email provider. For Google, the change-over date was May 30, 2022. For Microsoft accounts, the change-over is scheduled began in October 2022. Refer to Google & Microsoft vs Basic Authentication

Do not use a personal or business account for testing inbound email configuration. VTScada will always delete all messages from the inbox after reading them. This is necessary to avoid having the inbox fill with old messages.

For the same reason, do not attempt to use the same email account for two applications.

Large Numbers of Emails / Rapid Emails

Avoid sending large numbers of emails through Internet providers that are generally in the business of supporting home or small business use. The definition of "large" will depend on your provider, but is generally available in their documentation. (Link opens Google's published limits, as an example.) Providers will also place limits on the number of email messages that may be sent in rapid succession, because this generally indicates an email spam sender. VTScada cannot change the limits imposed by your provider. Exceeding your provider's limits will likely cause them to block your account.

Procedure

Email configuration can be accessed using the Alarms tab of the Edit Properties dialog.

If using OAuth 2.0, you must enable that feature in the Administrative Settings (Options) dialog of the VTScada security system before using the tools in the Edit Properties dialog. Prerequisites and steps for OAuth 2.0 configuration is provided in OAuth 2.0 Protocol.

Both inbound and outbound connections can be configured here. You will need the inbound option only if your license includes the Alarm Notification System and you plan to allow alarm acknowledgment by email.

Email Aliases

You may add a list of email aliases, from which acknowledgments will be accepted. This is useful when an operator has forwarded one or more email accounts to another that is used more often. Use a colon character to separate the list of email addresses to which the alarm will be sent from the list of email addresses that are acceptable aliases for those accounts. There is no need to add an alias address if the operator will reply from one of the addresses to which the notification is sent.

  • A semicolon ; between addresses: Send a notification to each
  • A colon : between addresses: Notify the first and accept a response from the following.

Example 1 - A simple configuration.

JoeOperator@CountyUtility.com

Example 2 - Configured with multiple addresses for one operator. A notification is sent to both addresses. Joe can acknowledge from either.

JoeOperator@CountyUtility.com;JoeOperator@GigaMail.com

Example 3 - Joe has forwarded his CountyUtility account to his GigaMail account. Notification is sent to his CountyUtility account, but Joe reads and acknowledges the alarm using his GigaMail account.

JoeOperator@CountyUtility.com:JoeOperator@GigaMail.com

While there is no limit on the number of email addresses you may have, the combined total number of characters may not exceed 255.

Outbound Email Configuration

VTScada is not an email server. Ensure that you have access to an email server before configuring outbound email options.

  1. Protocol: Only the SMTP protocol is allowed, therefore there is nothing to configure for this field.
  2. Enter the name or IP address of the email server.
    Typically, this will take the form: "mail.yourcompany.com" or "smtp.provider.com" for an internal email server.
  3. Enter the port to use on your email server.
    Typically, 25 for local email servers and 587 if using Transport Layer Security.
  4. Select whether to use Transport Layer Security (TLS).
    A connection that does not use TLS is not safe. Consider another provider if your email server does not insist on a TLS connection.
  5. Provide a "From Address" that will be attached to your messages.
    Note that some email servers will check that this is a valid email address and will reject the message if it is not.
    If you are configuring for alarm acknowledgment by email, this field must include the email mailbox address configured in the Inbound Email tab of the dialog.
    Multiple addresses may be used, separated by semi-colons.
    In the case of alarm acknowledgment by email, the other addresses will be each receive a copy of the acknowledgment.
  6. Provide the username and password required by the email server for authentication.
    These are not your VTScada security credentials. The values you entered will be stored in an encrypted form for your security.

Troubleshooting:

  • Emails are not being sent.
    Refer to the Alarm History. If VTScada encounters an error while attempting to send an email, a report will be generated and saved to the alarm history.
  • No errors reported, but emails are still not arriving.
    Check the spam rules on the receiving end. An aggressive filter may be sending your alarm or report notifications to the junk-mail folder.
  • A Report doesn't email, and produces a non-specific error message. It may be one of the following three common problems:
    Can't connect to the email server after trying for 3 minutes. Check email server configuration.
    An image source wasn't found.
    Too many attachments (limit 35)

Inbound Email Configuration

Do not use a personal or business account for testing inbound email configuration. VTScada will always delete all messages from in the inbox after reading them. This is necessary to avoid having the inbox fill with old messages.

To accept alarm acknowledgments by email, configure the inbound email section after correctly configuring the outbound email section.

Alarms can be acknowledged by email, only in response to an alarm notification email sent from the application which will contain a unique code. The field, Email From Address must match the account on your mail server that this page is configured to access. If any part is left blank, there will be no attempt to receive emails. If incorrectly configured, an event notification (visible in the alarm history) will be generated for every failed attempt to access the server.

  1. Protocol: Only the POP3 protocol is allowed, therefore there is nothing to configure for this field.
  2. Enter the name or IP address of the email server.
    Typically takes the form: "pop.provider.com".
  3. Configure the port number to access on the email server.
    Unsecured servers often use 110. Secured ports often use 995. Check with your provider.
  4. Select whether the connection should be made using a secure socket link.
    A secured connection is strongly recommended.
  5. Enter the username and password, required to access the account on the POP3 server.
  6. Adjust the maximum message size if required.
    The maximum message size is measured in bytes. This is a safety feature, preventing large incoming messages from slowing the system. Messages larger than the defined size will be deleted from the server rather than downloaded.

Troubleshooting:

  • Operators send the alarm acknowledgment email back, but the alarm is not acknowledged.
    Ensure that their roster entry includes their current security account name for VTScada. An acknowledgment code is attached to emails only when the roster identifies the receiver's account name.


Allow Acknowledgment by Email or SMS Text

If you have configured the Roster to send alarm notifications by email or SMS text, you can also configure it to accept alarm acknowledgments by the same method. Operators will receive a unique acknowledgment code by email or text for each alarm in the system. By replying to the message and including the code , they acknowledge the alarm.

The acknowledgment code is tied to the specific alarm and to the operator's security account name. The acknowledgment code will not apply to any other alarm, including a later alarm triggered by the same tag, nor will it work for any other operator.

A limited time is allowed for acknowledging alarms by email or text. This avoids problems that might occur if an extended length of time is allowed to pass after the message is sent. The default is 43200 seconds, (12 hours) as set in AlarmAckCodeAgeLimit.

A confirmation message is sent upon successful alarm acknowledgment. No reply to the acknowledgment is sent otherwise. You can suppress confirmation messages by setting AlarmNotifyEmailAcknowledge or AlarmNotifySMSAcknowledge (as appropriate) to 0 (zero).

Configure for alarm acknowledgment by email:

  1. Configure the Email Options dialog as follows.
    1. The "From" address is the account where VTScada will receive acknowledgments. This is the address to which the operator's reply is sent.
    2. Configure a POP3 server with the account that VTScada will use to receive alarm acknowledgments.
  2. Configure the Roster so that entries that send notifications by email include the operator's security account username.
  3. [Optional] Configure the settings, "AlarmCheckMail" and "AlarmCheckMailFastPoll" to control the frequency at which VTScada checks for replies.
  4. [Optional] Configure "AlarmEditEmailAck" to choose whether the operator is required to edit the message before replying.

Some email servers will shut down an account that polls too often, as a suspected spam source. The default value of 60 seconds for AlarmCheckMailFastPoll may trigger this on some third-party email servers.

The message received by the operator will appear similar to the following. The alarm code is unique to the operator, the alarm and the time of the alarm, making it extremely difficult to guess. You cannot reuse codes or give them to another operator to use.

From: The VTScada System [mailto:The VTScada System]
 Sent: December-14-11 10:43 AM
 To: Joe Operator
 Subject: The VTScada System: 1 alarm
 12/14/2011, 10:42 AM. Zone3 Water Level LOW (23%).
 Code: LPXX
 To acknowledge the alarm, reply with ACK*XXXX, where XXXX is the alarm code in this email.

Configure for alarm acknowledgment by SMS text:

  1. Configure the Roster so that entries that send notifications by SMS text include the operator's security account username.
  2. [Optional] Ensure that AlarmNotifySMSAcknowledge is set to TRUE, to cause VTScada to send a follow-up text message, confirming that the alarm was acknowledged.

Alarm History

In the Alarm History, the "Device" column shows the method that was used to ack the alarm.

Related information:

Email Setup for Alarms and Reports Configure an email server to send or receive messages.

SMS Appliance Tags - Configure an SMS device.

AlarmNotifyEmailAcknowledge - Suppress email confirmation messages.


Create a Roster Tag

Roster tags can contain up to 39 contacts specifying who should be notified (and how) when alarms are not otherwise acknowledged. You may have as many Roster Tags in your system as you require.

Every VTScada installation includes a tag named Default Call-Out Off, which is meant to function as an off button for the default roster area. You are advised not to modify or delete this tag.

For all roster tags sharing the same area property, the following rules apply:

  • Only one can be active at any time.
  • One must always be active.

When two or more Roster tags share an Area, activating one will automatically deactivate the others.

If a Roster is a child of a custom AlarmDatabase, it will call out alarms only from that database rather than all. Alarms with a matching Area property but under another AlarmDatabase will not be called out by this Roster.
You may switch to the legacy behavior where all AlarmDatabases are searched, but this will be slower if you have a large number of AlarmDatabase tags. See: LimitRosterToParentDB

To update the contact list you must have the Edit Roster Contacts privilege.
Legacy applications used the Manual Data or Tag Parameter View privilege. Accounts with those privileges will be granted the Edit Roster Contacts privilege on upgrade. The older privileges will no longer serve to modify the roster.

The following generalized instructions will help to guide you through the configuration of a Roster tag. Detailed notes for each property are provided in the article describing Roster Tags.

Add a contact by selecting a blank row in the list and filling in the various property fields. Edit by selecting a configured row and changing property fields. The list itself allows only two functions: change the order by selecting a row and using the arrows below the list, to the left. Delete a contact by selecting a row and using the X button below the list, to the right.

  1. Open the Tag Browser and create a new tag, selecting Roster as the type.
  2. Give the tag a name describing its purpose. ("Evening shift", etc...)
  3. Leave the Area field Default unless you intend to send some alarms to one group of operators and other alarms to a different group.
    (See Roster Selection Hierarchy)
  4. Give the tag a meaningful description.
  5. Open the Contacts tab.
  6. Click the Add Contact button.
    A new row is added to the end of the roster list.
  7. Click under Method.
    A drop-down selection of the available communication methods is shown.
  8. Select the Communication Method option as appropriate.
  9. Enter an operator's name in the Name field.
    This is only a description and may include a note about the contact method as well as the name. For example, "Joe home phone", "Jane cellular phone".
  10. Enter a phone number (Voice, SMS message), pager number (Pager), or email address (Email) in the Phone Number / Email Address field.
    If email, you may enter a list of addresses, separated by commas.
  11. If the selected contact method for this operator is Pager, enter the pager's PIN number in the PIN Number field.
  12. Provide the user's security account name in the User Name field.
    Alarm acknowledgment by email or text is not possible without this.
  13. Repeat for Person 2 etc. until you have added all the designated operators you require for this roster.
  14. If any contact or set of contacts should have a delay or be repeated before the roster attempts the next, click the Add delay/repeat button.
  15. Configure the rules for delay or repeat or both as appropriate.
    The rule applies to all preceding contacts, up to the top of the list or to the previous rule.
    If no delay rule is set between consecutive contacts, then no delay is used.
  16. Drag rows up and down to change the order and to group contacts with delay/repeat rules.
  17. Open the Settings tab.
  18. Choose whether to repeat the entire list after the last contact is attempted.
  19. Click OK.
    The new Roster tag will now appear in your Tag Browser.

Phone number formatting matters. You must use a format that is acceptable for whichever service provider or device you have opted to use. You are generally safe using the E.164 standard of canonical phone numbers Closed Microsoft Azure Active Directory app registration, an OAuth 2.0 provider., however, you are advised to check your device manual or check with your service provider to confirm their formatting rules.

Troubleshooting:

  • The communication method you want to select is not enabled.

Communication methods are enabled only when VTScada can use those methods. For example, if you have not attached an SMS device and configured an SMS Appliance tag, then you cannot choose to send an alarm message by SMS text.

Related information:

Script a Custom View of a Roster (For advanced developers only.)


Roster Selection Hierarchy

Viewing: Develop > Alarms > Alarm Notification System - Alerts by Phone, Email or Text > Roster Selection Hierarchy

Concepts:

Alarm Notification System - Alerts by Phone, Email or Text

Tasks:

Email Setup for Alarms and Reports

Reference:

Roster Tags

Modem Tags

SMS Appliance Tags

Roster Selection Hierarchy

The system will select which active Roster to call for an alarm by matching its Area property to the source of the alarm. The following rules are applied to make that match. Note that rules for Alarm Area Filtering and Tag Area Filtering take precedence - operators are not called for an alarm that occurs in an area for which they are not authorized.

Whenever a device driver is referred to in these rules, it means the driver tag configured in the I/O tag. If that is a Polling Driver tag or a DriverMUX tag, then that is examined to the exclusion of other driver tags in the communication chain.

In general, Roster tags should use the area, Default, unless you intend to send different sets of alarms to different operators.

This rule applies only to I/O tags, status tags, control tags and the Data Flow Pulse Input. For Selector Switches, and legacy input tags and output tags, the area of the device driver is not checked when working through the roster hierarchy. Refer to the following table:

Support for the area property "GeneralAlarm" was removed in version 11.1.

I/O Type | Driver's Area Checked | Driver's Area Not Checked
I/O and Calculation | ✓ |
Analog Control | ✓ |
Analog Status | ✓ |
Digital Control | ✓ |
Digital Status | ✓ |
Data Flow Pulse Input | ✓ |
Pump Status | ✓ |
Selector Switch |  | ✓
String I/O |  | ✓
Analog Output |  | ✓
Analog Input |  | ✓
Digital Input |  | ✓
Digital Output |  | ✓

The rules are slightly different for alarms built into tags other than Alarm, and those for tags of type, Alarm.

Alarms built into I/O tags:

Alarm tags:


Using Twilio for Alarm Notifications

VTScada supports the Twilio messaging system, enabling you to send spoken or text alarm notifications to operator's phones. At least one of your VTScada servers must have an Internet connection. VTScada supports signature validation of incoming HTTP requests from Twilio as described in Twilio.com's documentation.

VTScada must be able to receive status notifications directly from Twilio using the HTTPS protocol. Therefore, Twilio is an option only for sites that are able to allow Twilio to post HTTPS requests to the VTScada Thin Client Server with a fixed IP address or domain. (Connections are made in both directions.)
If the only outside connection to your server is via a VPN, then you cannot use Twilio to send alarm notifications.
Learn more about configuring your Thin Client Server in the topic, Thin Clients: Mobile and Internet.

Microsoft does not permit Windows services to access SAPI (the built in Windows text-to-speech engine). This means that if you are using the VTScada Alarm Notification System and you configure your application to run as a Windows service, then outgoing alarm calls via voice modem are silent. VOIP and Twilio calls may work, but Microsoft is inconsistent with which versions of Windows will allow services to access SAPI. We cannot guarantee operation of VOIP when running VTScada as a service.

The current Alarm Notification server must be accessible from the Internet at the IP or domain specified in the Twilio settings. In a fully redundant system, this means that the Twilio settings must be workstation specific. Use the workstation selection tool in the Twilio Account Settings to choose the workstation you are configuring.

There is no requirement that the specified IP address be the current VTScada Thin Client Server or that the Alarm Server be on the Thin Client Server List.

The voice to be used by Twilio can be configured on a language-by-language basis using the #TwilioVoice setting in each languages *.csv file. The default is:

#TwilioVoice,woman

You will require a Twilio account. Obtain one from Twilio at https://www.twilio.com/try-twilio. Add the SID and the Auth Token for this account to the configuration of your application.

Enable Twilio

Select before proceeding with the following configuration options.

Workstation

Use when configuring systems that have multiple callback domains or Twilio accounts.
When using multiple alarm notification servers, with Twilio for voice alarm notification, each server requires its own fixed IP address or FQDN on the public Internet.

Twilio account SID

Your Twilio account identifier

Twilio auth token

Your authentication token, provided by Twilio.

Domain for Twilio verification

The domain, at which Twilio can reach your VTScada server. In most cases, this will be a direct connection to your secured server and will take the form "trihedral.com" for a domain of "https://www.trihedral.com".

Some sites make use of a secured proxy device that forwards connections to the VTScada server (secured or unsecured). In this case, the domain should be specified in the form "https://ProxyServer.com:123".

Twilio requires an HTTPS POST verification exchange with your site (either directly to the server or via a proxy). Your server must be visible to the Twilio server without the use of a VPN.

Realm for Twilio verification

The corresponding Internet Realm that you created for your application.
(Not a Realm Filtering realm.)

If running multiple applications (for example, hosted systems) then you cannot share modems, SMS devices, or Twilio accounts between applications. You must have independent modems or Twilio accounts for each application.

To connect, send a message, and disconnect, VTScada must be able to receive status notifications from Twilio. These are sent via HTTPS, therefore you must configure a VTScada Thin Client Server and a Realm and secure that using an X.509 certificate. See: Configure a VTScada Thin Client Server and Configure a Realm.

Do not use a realm defined for Realm Filtering or a security account limited to such a realm.

Note that if an operator hangs up within one second of pressing 1 in the menu system, data related to the call progress that would normally be logged can be lost. There is no significant harm to this, because the end-of-call status can be inferred.

If using Twilio, operators can provide their Alternative ID by either dialing it in or speaking it out loud.

Multiple Twilio Numbers / Multiple Applications

You can register multiple numbers with one Twilio account to send texts and calls. But in order for a VTScada application to be able to receive incoming texts and calls from Twilio, it must provision a specific number. VTScada's ability to select which number to provision changed with release 12.1.40

Prior to 12.1.40, applications were provisioning with all available Twilio numbers but only using the first one in the list to call and text. That meant that if you had more than one Twilio number, any number after the first one was not used for outbound calls/texts. The result was that customers would need one Twilio account per VTScada application even if you had multiple registered numbers on that account.

Since 12.1.40, you can select which number you would like to use for both inbound and outbound texts/calls, leaving the other numbers available for other applications. This means that you can use a single Twilio account with multiple registered numbers on multiple applications if you have configured a unique number with each. The 'Registered Number' droplist in the Twilio Account Settings will be populated after valid credentials are provided and will be cleared if the credentials are no longer valid. A dialog will inform you if bad credentials are provided.

For backward compatibility, applications that are being updated from an older version will still provision with all Twilio numbers. Also, if a specific number is not selected, the application will provision with all numbers.

Troubleshooting

If operators have trouble verifying their ID with Twilio, use the following to diagnose the problem:

  • Ensure that the option, "Speak digit after phone key press", is selected in the Alarm tab of the Application Configuration dialog. This provides an audible confirmation so that operators can know that each digit was indeed pressed.
  • For security purposes, key presses are masked in the Twilio logs unless the property TwilioShowCredentials is set to 1 (one) in the application. Set that property to 1 only while debugging a problem.
  • The Twilio logs are written once per day or after 1000 entries, whichever comes first. While troubleshooting, you can increase the frequency of logging intervals in order to check for problems more often. Refer to the properties, TwilioTraceInterval and TwilioTraceMax. By default, the log is written to C:\VTScada\<AppName>\Data\TwilioLogs


Using VoIP for Alarm Notification

VoIP configuration is done using the Alarms Tab of the Edit Properties Page.
Scroll to the end of that topic.

Definitions:

VoIP Closed Voice over Internet Protocol stands for Voice over Internet Protocol. "VoIP" is sometimes used as a generic reference to any phone connection via the Internet. VoIP is not a protocol itself; it is a collection of related protocols that support voice communication over the Internet. Those who are familiar with the technology can skip this collection of definitions.

For customers who are new to VoIP, the following may help guide you through the large set of related acronyms as you choose and install a system. There are several excellent references online that will be useful as you search for a VoIP solution, but also many that add more confusion than explanation. Hopefully, the following will help you get started.

SIP Closed Session Initiation Protocol. Used in connection with Voice over Internet Protocol.

Stands for Session Initiation Protocol. This protocol refers only to how sessions are connected. It does not specify how messages (including voice) are transferred. There are many methods of implementing VoIP, but nearly all rely on SIP for the initial connection.

Most of your VTScada configuration tasks related to VoIP specify how to connect to your provider using SIP.

FXO

Foreign Exchange Office, which in the case of telephone communications refers to an interface that connects an adapter to the telephone line coming from a "plain old telephone system". (POTS - or simply the standard telephone outlet on the wall.)

If you choose to implement a system using a VoIP ATA adapter (defined next) be sure to purchase one that has an FXO port.

ATA (Analog Telephone Adapter)/VoIP-to-FXO

Analog Telephone Adapter. Connects a VoIP-enabled device (such as a VoIP telephone or your VTScada server) to an old fashioned telephone system.

There are also ATA adapters that will connect an old fashioned telephone to a VoIP service. Those have an FXS port and are not relevant to this topic.

PBX

Private Branch Exchange. A private telephone switchboard.

Soft Phone

A program or application for making telephone calls over the Internet. (ex MicroSIP)

Requirements:

Before beginning, you must have a way to send and receive calls. This can be implemented using one of three methods:

  • A VoIP ATA adapter with an FXO port connected to a physical phone line and to your internal Ethernet network.
    You do not need a VoIP provider for this solution. You do need an account with your local telephone service.
  • An existing local exchange that supports SIP.
    This would be of interest in an environment with Internet-connected phones.
  • An Internet-based service that supports SIP and can make calls over the Internet such as VoIP.ms

Ensure that you have access to the relevant configuration details, either from your phone system administrator or the device manuals.

Trihedral has not tested alarm notifications with every VoIP provider and cannot guarantee that it will work with yours.

Microsoft does not permit Windows services to access SAPI (the built in Windows text-to-speech engine). This means that if you are using the VTScada Alarm Notification System and you configure your application to run as a Windows service, then outgoing alarm calls via voice modem are silent. VOIP and Twilio calls may work, but Microsoft is inconsistent with which versions of Windows will allow services to access SAPI. We cannot guarantee operation of VOIP when running VTScada as a service.

When configuring VoIP in more than one application, using separate accounts for each VTScada application is recommended. Some VoIP providers support creating separate sub-accounts, which can also be used for this purpose. Using a single VoIP provider account, which is typically linked to a single phone number, across multiple VTScada applications at the same time can lead to incoming calls/SMS being routed incorrectly with some VoIP providers.

Setup.INI properties for VoIP

EnableVOIPLog

Set to 1 by default, meaning that VOIP logs are saved to the folder TraceFiles\VOIPLogs.

VOIPPort

Do not change from the default value unless necessary.

If you have a VoIP soft phone or similar, there may be contention for the default SIP port of 5060. You can specify an alternate SIP port that VTScada will use via the VOIPPort setting. To change this value, edit your Setup.INI file using a text editor and then restart VTScada. This property affects all running applications.(See: System Properties - Setup.ini )

For example:

       VOIPPort = 5062

VoIP Settings (Alarms panel of the Application Configuration dialog)

Calling and SMS may be enabled separately per-workstation.

Enable VOIP Calls

If this box is selected, your application will use your VOIP settings for voice-based alarm notification.

Enable VOIP SMS

If this box is selected, your application will use your VOIP settings for SMS-based alarm notification. This feature works only with providers who support SMS and have enabled the MESSAGE extension for SIP. It does not work with Grandstream devices.

Workstation

Use when configuring systems that have multiple, workstation-specific options for connecting to a VoIP device. This allows you to configure the unique VoIP connection details for each Alarm Notification server.

SIP identity

The unique SIP uniform resource indicator URI Closed Uniform Resource Identifier. URIs Identify, whereas URLs Locate. In many cases, a URI looks a lot like a URL.) that identifies the application. The scheme for this URI is defined in RFC 3261.

If you have an internal VOIP PBX or virtual PBX, your phone system administrator must assign this to you. It will typically take the form, sip:11235551234@sip.myorg.com:5060

The port specification (:5060) is optional unless you have changed the property, VOIPPort, in your Setup.INI file.

If you are using a VoIP-to-FXO device, the identifier before the "@" sign may be configured arbitrarily. (For example: sip:bob@bob.mydomain.com). You would use this same URI to configure incoming calls from the VoIP-to-FXO device.

In all cases, the fully qualified domain name (FQDN) of the server that VTScada is running on must follow the "@" symbol.

SIP server

This field is optional.
f you are using an internal VOIP PBX, ask your phone system administrator for this information.

If you are using a VoIP-to-FXO device leave this blank. (SIP INVITE requests go directly to the device instead of via the server.)

If populated, this field should be a SIP URI. For example, if your administrator indicates that the SIP Server is an IP address (e.g. 192.168.2.21) the SIP Server field should contain "sip:192.168.2.21". If your administrator indicates that the SIP Server is an FQDN (e.g. "voip.mynetwork.com") Then the SIP Server field should contain "sip:voip.mynetwork.com". If your administrator has specified a port on the server to use (e.g. 5060, or 5090) it can be appended to the URI (e.g. "sip:voip.mynetwork.com:5090")

SIP proxy

If you are using an internal VOIP PBX, ask your phone system administrator for this information.

If you are using a VoIP-to-FXO device you may be able to leave this blank (SIP INVITE requests go directly to the device instead of via the proxy)

If populated, this field should be a SIP URI. For example, if your administrator indicates that the SIP Proxy is an IP address (e.g. 192.168.2.21) the SIP Proxy field should contain "sip:192.168.2.21". If your administrator indicates that the SIP Proxy is an FQDN (e.g. "voip.mynetwork.com") Then the SIP Proxy field should contain "sip:voip.mynetwork.com".

If your administrator has specified a port on the server to use (e.g. 5060, or 5090) it can be appended to the URI (e.g. "sip:voip.mynetwork.com:5090") If your administrator has not specified a proxy, you can enter the same information that you entered in the SIP Server field.

SIP domain

If you are using an internal VOIP PBX, ask your phone system administrator for this information. Typically this is the domain part of your SIP URI. For example, if the SIP URI is "sip:11235551234@sip.myorg.com:5062", the domain field is "sip.myorg.com".

If you are using a VoIP-to-FXO device this is the IP address of the device.

The domain field is used by VTScada to decorate phone numbers in the roster to turn them into SIP URIs for making outbound VOIP calls. For example, if the number of a roster contact is "19025551234", and the SIP domain field contains "192.168.2.21", VTScada will attempt to call using the following SIP URI: "sip:19025551234@192.168.2.21". If you are using VOIP for alarm notification, you can also just use the contact's SIP URI directly in the roster phone number field. If you are using a naked phone number, you should include the country code and the area code in the number, without spaces or extra characters. In North America this will be eleven digits in all. the one digit country code ("1"), the three digit area code, and the seven digit local number.

SIP login user ID

If you are using an internal VOIP PBX, ask your phone system administrator for this information.

If you are using a VoIP-to-FXO device this might be blank, depending on the device. Refer to the device documentation.

SIP password

If you are using an internal VOIP PBX, ask your phone system administrator for this information.

If you are using a VoIP-to-FXO device this might be blank, depending on the device.

Two stage VoIP dialing

If your internal phone system requires you to dial an external line or extension, you need to configure two stage dialing. This can be done in Application Configuration > Edit Properties (Basic) > Alarms > VOIP Settings.

"Enable VoIP calls" must be checked before you can populate "Prefix for phone numbers". If you disable VoIP calls, VTScada will preserve your configurations.

Use a comma to add a pause. This gives the system time to respond. (For example, Dial 9 to get an outside line, pause while it connects, and then dial the rest of the number.)

The dial pause length is 2 seconds by default. To customize the dial pause length, enter a number (in seconds) into the "Dial pause length" field.

In the following example, VTScada would dial a 9, pause for two seconds, and then dial the remaining numbers.

VoIP settings include the options needed for two-stage dialing

The other settings have been left blank in this example for simplicity-- but it is assumed they would also be populated in the course of your VoIP configuration.


Setting Up a Specific VoIP Connection

To use VoIP for alarm notifications, you must take the following steps:

  • Get a virtual phone number from a VoIP service provider.

  • Test it with a digital phone (a "softphone")

  • Configure VTScada to enable VoIP calls

  • Set up a roster tag

  • Test your configuration to ensure it works as expected.

In this topic we will set up a specific VoIP connection step-by-step, including testing and troubleshooting.

VTScada cannot provide a virtual phone number or a softphone. You will have to select a third-party provider.
There are many providers available. The features they offer, the quality of their services and the cost of their services are ever changing. Select providers that work best for you and remain vigilant.

For the sake of a practical example, this guide will use the VoIP service provider VOIP.ms and the open-source digital phone MicroSIP. VTScada is not officially affiliated with either of these third-party providers. We cannot guarantee their quality of service.

Get an Account with voip.ms

SMS messages sent to VTScada via VOIP.MS may not be receive by VTScada or may be received after considerable delay. This can affect the operator's ability to acknowledge alarms remotely via SMS.
(Reported June, 2025)

Get a virtual phone number from this paid service provider. This is the phone number VTScada will use to place calls and send texts. You must add funds to your account. The current minimum being $15USD. You may already have a VoIP phone number that is being used in another application. Be advised that using the same number or same account across multiple VTScada applications at the same time can lead to incoming calls and SMS messages being routed incorrectly. It is a best practice to use a separate account with a fresh phone number for each application. In the case of voip.ms you are able to create separate sub-accounts to avoid this complication.

Your SIP number is located on the Home Page:

This number is important, write it down and keep it handy.

Order a Phone Number (DID)

A virtual phone number is called a DID (That stands for Direct Inward Dialing). DIDs place calls from virtual devices through the telecommunications network to other devices or to real phones; If you have a DID assigned to your VoIP account, you can set it up to forward incoming calls (from VTScada) to another phone number such as a mobile phone or landline (ex. an operator's cell phone.)

A DID is like a virtual phone number

Find "Order DID(s)" in the DID Numbers menu at the top of the page.

From the menu, select an area. This will narrow down your options for phone numbers to local, familiar area-codes. You can select country, state/province/territory and city but beware, some smaller municipalities will not have phone numbers immediately available. You can still purchase one but it will be back-ordered and you must wait. Consider choosing another area such as a larger nearby municipality.

"Order Numbers" that are Carrier Order will be back-ordered. "View Numbers" means there is immediate availability.

You must select a server that will serve as an access point for your virtual number to the broader telecommunications infrastructure. These are called POP servers (Point of Presence) and may be referred to as a DID POP. It is a best practice to select one that is close to your actual location.

Appearances may vary

Your page might look something like this. Costs and locations displayed will vary depending on your selections and market conditions.

The last section, Routing Settings, can be left with default settings:

Confirm your order

View your DID number(s) and their current settings by navigating to "Manage DID(s)"

Set Up Call Display

Navigate to Account Settings

Find the General tab and for the CallerID Number field select "Use one of my DIDs"

Configuring a Password (OPTIONAL)

Note on Passwords: Customer Portal Password is the password you used to set up this voip.ms account. It works for logging into voip.ms AND accessing the SIP account UNLESS you configure Main SIP/IAX Password. If you configure a Main SIP/IAX Password, this will be the password you must provide to MicroSIP and VTScada during configuration. The reason one may take the extra step of creating a Main SIP/IAX Password is to try to resolve authentication errors.

Set Traffic to Encrypted

Navigate to the Advanced Settings. Change "Encrypted SIP Traffic" from No (Default) to Yes. Click "Apply All" to save.

Set up SMS (Texting) for your DID

To find the SMS/MMS settings menu go to Manage DID(s)

Find your DID and click the orange symbol to open "Edit DID"

Scroll to the very bottom to find a short section called "Message Service (SMS/MMS). Click "Enable SMS/MMS" to expand the section and reveal more options:

With SMS/MMS enabled, there are two more settings that must be configured.

  1. Link the SMS received to this DID to a SIP Account. Enable. Main account should be selected by default.

  2. If you are in North America, dialing Mode for SMS (3CX/API) must be set to NANPA Closed Death certificate for Sparkplug Edge Nodes.

Once you have set up your account with voip.ms you should have the following:

  1. SIP Number (a six-digit number, ex. 413555)

  2. Password

  3. DID POP Server Name (ex. Montreal1.voip.ms)

Verify and Debug with MicroSIP

We have just obtained a phone number using a VoIP service provider. To test it, we want to make a phone call with it. So we will use an application to act as a phone that has been assigned this phone number.

MicroSIP is a lightweight, open-source VoIP softphone application that can allow users to make voice calls and send texts over the internet using the SIP standard.

The latest version of MicroSIP can be found at https://www.microsip.org/downloads

There are two settings that must be changed:

  1. Change Source Port to 5061

  2. Change RTP Ports to 10000 and 20000

We are going to add an account to our MicroSIP application that we will connect to our VoIP phone number. This account will contain the credentials needed to use this phone number and some configuration settings. Back in the MicroSIP drop-down menu select "Add Account..."

Click save and the window should close. If it is not closing you may have a typo. Check the bottom of the MicroSIP dial-pad for hints. It may say "wrong password" if your SIP number or password is incorrect. When everything has been filled out correctly and the encryption settings have been configured it will show a green phone with a padlock and the word "Online":

To test your configuration:

  1. Place a call on MicroSIP - This is placing a call with the phone number you purchased on VoIP.ms

  2. Send a text with MicroSIP - This is sending a text from the phone number you purchased on VoIP.ms

  3. Call the virtual phone number from another phone.

  4. Text the virtual phone number from another phone.

If you are unable to successfully send and receive calls and texts, do not proceed. Start from the beginning of these instructions and check each setting one at a time to ensure they have been successfully duplicated and saved. Some of the most common problems at this stage are either a typing error in a form field or unsaved settings on voip.ms.

When you are finished with MicroSIP, you must disconnect it. From the MicroSIP drop-down menu you will see "Make Active" with a little check-mark next to it. Click it to uncheck. The dialpad will no longer display "Online" in the bottom left corner, only a grey phone symbol next to the word "MicroSIP".

VTScada VoIP Settings

For an in-depth understanding of VTScada's role in setting up a specific VoIP connection see Using VoIP for Alarm Notification

To use VoIP for alarm notification you will need to configure three parts:

  1. Application configuration - to enable VoIP and manage application-wide VoIP settings.

  2. Create a roster tag - to catalog those who will receive a call/SMS and set a trigger event.

  3. User account settings - to set ID codes for each person who may receive a voice call.

VoIP Application Configuration

Open the application configuration menu, navigate to "Edit Properties" and, in Basic Mode, find the Alarms tab. Scroll to the bottom to find VOIP Settings. Here is a functional example of these settings configured:

  • Note that it is a best practice to select a workstation and not leaving the setting as "Default"

  • In VTScada, your SIP identity is formatted "MyID <sip:YourSIP#@YourDIDPOPServerName>"

  • Your SIP login user ID is simply your six-digit SIP Number.

  • Your SIP password is the password needed for VTScada to log into voip.ms (Unless you have configured a main SIP/IAX Password on voip.ms as described in this topic)

For some Advanced Configuration, switch to Advanced Mode and find the property called "VOIPPickUpDelay" This property sets the time interval from when a VoIP call is initiated until speech starts. The default is 10 seconds. You may wish to copy this property, assign to the VoIP workstation and set a shorter delay (ex. 2 seconds)

Create a Roster Tag

For more information about Roster Tags see: Roster Tags

  • ID tab: Fill in a Name, Area and Description.

  • Contacts tab: Select "[+] Add contact" from the bottom. Work through the options as they appear from left to right. See the Roster reference page for more detail.

  • Settings tab: You must set an activation trigger to tell the roster tag when to activate.

For testing purposes, start by configuring the roster tag to send one text and one voice call to a nearby device. In the following example, a delay has also been added to space the calls out.

In the settings tab, change the delay before notifying priority 1 and 2 alarms to 5 seconds during configuration to facilitate a speedy test cycle and then lengthen it back to a reasonable delay for regular use.

User Account Settings

If the user receives a text, it will include a one-time code that may be used to acknowledge the alarm. However, if the user receives a voice call they must enter an ID code to access the ability to acknowledge the alarm. This ID code is set in each user's account.

  • Navigate to Accounts from the title bar.

  • Select a user who will be on the roster.

  • Click on the ellipse [...] next to "Alternate Identification"

  • Set a numerical pin, ex. "5555"

  • Apply changes

  • Repeat for every user on the roster and provide them with their pin.

For more information see Accounts and Roles

Testing and Troubleshooting

Quick-Build a Test Page

Confirm the configuration can send voice and text alerts that can be acknowledged by the recipient. There is a widget that will generate a false alarm and widgets for monitoring the process. In Idea Studio, create a new page and add these five widgets:

  1. Roster Alarm Test - Found in Basic Components > Specialty > Roster Control. Link to roster tag.

  2. Export Comm Log Button - Found in Analytics > Diagnostics. Helpful for troubleshooting.

  3. Alarm List - Found in Tools > Alarm Tools. Change the database drop-down to "System Alarm DB"

  4. Alarm List - Same as before. Change the database drop-down to "System Event DB"

  5. Call Manager Status - Found in Tools > System Status Tools.

Check the "Roster Alarm Test" box and wait. Watch the System Alarm DB Alarm List to see the mock alarm and the System Event DB Alarm List to see events happening in real time. Keep your device handy to acknowledge the alarm. Ensure you try this with both voice and text.

VoIP Testing and Troubleshooting Page Example

Troubleshooting

If Roster Alarm Test places a call but the call fails, click "Comm Log". This will create a folder, VTScada > TraceFiles > VOIPLogs. Every time you click "Comm Log" a text file will be generated in this location containing logs. Search for "401" or "403". These are error codes for Unauthorized or Forbidden and may indicate two possibilities:

  • The log-in credentials haven't been typed correctly somewhere along the way. If MicroSIP was able to place a call but VTScada was not, try retyping the VOIP Settings in your VTScada configuration dialog. It is not possible to see the password as it is typed. If you are in a secure location, consider typing the password in a text editor (like notepad) where you can see that it is typed correctly and then copy and paste it into VTScada.

  • MicroSIP is still active and it is blocking VTScada's access to voip.ms.

If you can send a text but cannot acknowledge the alarm via text:

  • The TLS Settings are incorrect.

  • If you are sharing an account or a DID number with another application it may cause routing errors.

You're getting Authentication Errors

  • See the section of this topic about passwords. Try setting a Main SIP/IAX Password.

If it still doesn't work:

  • Use someone else's device to call your test device. It is possible that your location may impact your phone's ability to receive calls and texts.

  • Use this step-by-step guide as a checklist to revisit each setting. Pay special attention to saving/applying settings in voip.ms and VTScada. The most common errors are typing errors and save errors where the fields have all been filled out but they have not successfully saved.

  • Before submitting a support request: In Idea Studio, go to the properties dialog of the Export Comm Log Button widget and check "System Logs". Attempt a voice and text call-- which will still fail-- to populate the log. This will gather helpful information for the support team.

Related information:

Using VoIP for Alarm Notification

Roster Tags

Export Comm Log Widget

Alarm List

Call Manager Status Widget

Roster Alarm Test Widget


Tips for Configuring a Grandstream VoIP ATA

Trihedral has no relationship with Grandstream Networks. The following is offered as a service to our customers who are attempting to configure a Grandstream HT813 for voice calling with the VTScada Alarm Notification System.
Support for Grandstream products can be offered only by Grandstream Networks, not by Trihedral.

The Grandstream HT813 has been used successfully by many customers. The following information may be helpful when configuring yours. It may not be complete for your specific situation.

Preparation:

  • Ensure that you have a working phone line.
    (A standard phone should produce a dial tone when connected to the line you intend to use.)
  • If you intend to configure the Alarm Notification System to accept incoming phone calls, ensure that you know the number assigned to that phone line.
  • Configure a static IP address on your network for use by the Grandstream VoIP ATA.
    This is likely to require the cooperation of your IT department or Internet Provider.
    Have that address ready for the following steps. You will also need the matching gateway address.
  • On the Grandstream VoIP ATA, ensure that analog phone line is plugged into the FXO port. VTScada does not use the FXS port.
  • Also on the Grandstream VoIP ATA, ensure that the Ethernet cable is plugged into the network LAN port, not the network WAN port.
  • Connect the other end of the Ethernet cable to your VTScada server, or to another computer where the network can be interrupted.
  • If not starting with a new device, perform a factory reset by holding in the reset button for 7 seconds.
  • Configure VTScada for VoIP as described in Using VoIP for Alarm Notification
    (Example follows)

Given a Grandstream at the fictional IP address of 1.1.1.1 and VTScada at the equally fictional address of 2.2.2.2, configuration would be as follows:

Setting | Value
SIP identity | VTScada <sip:vtscada@2.2.2.2>
SIP domain | 1.1.1.1

Configure the HT813

The HT813 has many configuration settings. Any that are not mentioned here can usually be ignored.

  1. Open a browser window on the machine connected to the Grandstream ATA and navigate to http://192.168.2.1/
  2. Sign in to the Admin account (default password, "admin").
  3. Open the Basic Settings tab of the configuration panel.
  4. We recommend you set a new password.
    The admin password can be changed using the Advanced Settings tab.
  5. In the section, IPv4 Protocol, select "Statically configured as".
  6. Set your preferred static IP address as configured during preparation.
  7. Add the default router address, matching the gateway for your static IP address.
  8. Select a “Device Mode” of WAN Only.
  9. Change the “Unconditional Call Forward to VOIP” as follows:
    1. Set a User ID that can be recognized if needed for debugging. (HT813, for example. This is not used by VTScada.)
  10. Select “Apply”
  11. Select “Reboot”.
  12. Reconnect your Internet cable to connect one end to a standard outlet for your network and the other end to the WAN port on the VoIP ATA.
  13. Following the reboot, point your browser at the new IP address.
  14. Sign in again.
  15. There is nothing to configure on the Advanced Settings tab.
  16. Open the FXS tab.
    VTScada does not use the FXS interface but there is a required configuration step here.
  17. Set "Account Active" to "No".
  18. Set "Local SIP Port" to a value that will not be used, such as "5064".
  19. Select "Apply".
    Do not reboot.
  20. Select the "FXO Port" tab.
  21. Ensure that "Account Active" is set to "Yes".
  22. Set "SIP Registration" to "No".
  23. Set "Local SIP Port" to "5060".
    This is the port that VTScada is configured to use in the VoIP account settings.
  24. Set "Number of Rings" to 1
  25. Set "Wait for Dial Tone" to "Yes".
  26. The stage method should always be set to 1 for VTScada. If two-stage dialing is required (ex dial 9, pause, dial number) it must be configured in the Application Configuration, alarm tab, under the VoIP settings: Prefix for phone numbers.
  27. Select "Apply".
    Do not reboot.

Your Grandstream VoIP ATA should be ready to place outgoing calls.


Voice Call Redundancy

The information in this topic applies only to voice calls, not to SMS messages or email.

For voice calls, VTScada keeps track, not only of each contact's phone number, but also the method used to place that call. If more than one method of placing a call is available (Twilio, VOIP, or modem) and one of those methods fails, VTScada will continue making calls using whatever method is still available. If all methods configured on a machine that can be reached by the Alarm Notification Server are working, all methods are used; VTScada does not define a primary call-out method and then switch to the alternate only when the primary fails. For example, with VOIP configured on Server-A and Twilio configured on Client-B, the server will round-robin between both VOIP and Twilio for voice callouts.

On any given workstation, you can have VOIP, Twilio, and voice modems configured. Only one VOIP configuration can be set up on a given workstation, and only one Twilio configuration can be set up on a given workstation. Any workstation that the application is running on can host any number of voice modems for redundancy. The Call Manager Status widget will only display one call interface for voice modems. You can use the Modem Status widget to display more detailed information on individual voice modems.

If a voice call method fails, an internal counter for that method will be incremented. If the counter exceeds the CallManagerBadCallLimit setting, a voice call failure alarm will become active. Further details are provided in Alarms for Voice Call Failure.

When configuring the order of servers, note that the Call Manager does not have its own service, but instead follows on the Alarm Notification service to define the order of backup servers.

In many cases, Twilio and VOIP configurations should be disabled globally and instead, enabled and configured for specific workstations. If a configuration is enabled globally, it will make calls only from the current Alarm Notification server. This might be desired if any one out of multiple servers will use the same VOIP settings when it is the current server.
A global configuration such as this will not work with all VOIP solutions or Twilio configurations.

Related Information:

Call Manager Status Widget


Alarms for Voice Call Failure

The voice call failure alarm is part of the voice call redundancy system. Every VOIP and Twilio configuration has its own corresponding voice call failure alarm, with the name of the alarm indicating the method and machine where it is configured. For example, if VOIP is configured on MachineA, the corresponding voice call failure alarm would have the name "VOIP_MachineA". You can have another VOIP configuration on another machine which would have its own associated voice call failure alarm with a different name, (e.g. "VOIP_MachineB"). The same applies if using Twilio.

The priority of the voice call failure alarm is given by CallManagerAlarmPriority, which defaults to 1 (Critical) so that it may be called out. This is a regular alarm that can be acked, shelved, cleared..etc. The alarm is cleared (normalized) when a successful voice call is made using the same method that failed earlier. A successful call-out using a method that did not fail will not clear the alarm on the failed method. You are encouraged to test your configuration to ensure that it works as expected.

Alarms from voice modems are handled somewhat differently because all voice modems on the system are treated as a single configuration. Therefore, there will be only one voice call failure alarm for modems. The modem voice call failure alarm will have a name of "VoiceModem". For example, a modem configured on MachineA and another configured on MachineB will both have a single VoiceModem voice call failure alarm associated with them. If the alarm is triggered by a failure of the modem on MachineA, a successful callout on MachineB will clear the alarm.

To prevent a callout when a voice call failure alarm triggers, lower the alarm's priority using the CallManagerAlarmPriority setting. You can increase the number of required consecutive failures before the alarm is triggered by increasing the CallManagerBadCallLimit setting. This defaults to 1, meaning that one failed call will raise the alarm.

In its current implementation, the voice call redundancy system will round robin across all configured voice call methods with no ability to prioritize one method over the other. For example, on a system with four voice configurations, where the first method fails, three callouts need to be made to cycle back to test the 1st configuration. You are advised to disable the other configurations in order to test the failing one and ensure it is working.

Create a page for diagnostic widgets. The Modem Status and the Event Log List widgets (among others) can provide helpful information about call status and failures.


Activate a Roster

For all the Roster tags that share an area, only one may be active at a time. As one roster becomes active, all other rosters for that area become inactive. This is typically done to create separate rosters to use at different times of day. For example, one roster for a day-shift and another for a night-shift.

Whether existing alarms are sent to a roster as it becomes active depends on the configuration of the rosters.

Alarms are not transferred: Given two rosters, the first having no contacts (since operators are assumed to be on-site) and the second having a list of contacts for when operators are not on-site. As the second roster becomes active, existing alarms are not sent to it.

Alarms are transferred: Given two rosters, each of which has a list of contacts. As the second roster becomes active, existing alarms that were being called out to the now-inactive roster will switch to the currently active roster.

Manual Activation

Operators can press the Make Active button to manually activate a Roster. Draw one on any page of your choice for every roster in your application. All operators with access privileges to the page can then switch active rosters at the click of a button. (Make Active Widget)

Automatic Activation

Rosters activate automatically if linked to any other tag that can change in value from zero to non-zero. The Trigger tag was created for exactly this purpose. You can configure a Trigger tag to activate and deactivate at specified times or in response to an external condition, making it a perfect choice for automatic switching of active rosters. (Trigger Tag)

These instructions show how to configure a Trigger tag and use it to activate a roster every morning at 9:00 a.m. Note that the Trigger tag is a powerful tool with many options. These instructions will cover only the most basic procedure.

The first set of steps will configure the trigger:

  1. Open the Tag Browser.
  2. Select a Trigger tag as the tag type.
  3. Click New.
  4. Provide a Name, Area and Description for the Trigger tag.
  5. Select the On Conditions tab.
  6. Set the Starting Time to today’s date at a time earlier than now.
  7. Set the Every box to "1" and the time frame to "Days".
  8. Ensure that all the days of the week are selected
    If you wish to activate a different roster on weekends, leave Saturday and Sunday unselected. You can repeat this procedure for as many rosters as you need.
  9. Leave the Expression box set to No Tag Selected.
    This option is used only if you wish to activate the trigger based on an external condition.
  10. Select the Off Conditions tab.
  11. Enter the number "1" for the Every field
  12. Press Tab or Enter to record the 1 and activate the other controls
  13. Set the time frame to Days
  14. Set the Starting Time to 5:00 PM on today’s date.
  15. Ensure that same days are selected as in the On Conditions tab.
  16. Click on OK to save the new Trigger tag.

Now that you have a trigger, you can use it to activate a roster automatically, as follows:

  1. Create a Roster tag or open the properties dialog for a Roster tag you created earlier.
  2. Select the Activation Tab
  3. Select the Trigger tag you created in the last set of steps.
  4. Click on OK to save the Roster.

Repeat the steps for as many Rosters as required.

Monitor and Reset Roster

Monitor the status information of rosters in the application and force a roster out of a failed state. A reset button will become enabled if a roster is in a failed state. Click the enabled reset button to kick the roster out of its failed state. This widget is subject to realm and Global Tag & Area filtering.

You can find this widget in the palette folder: Tools >> System Status Tools

For more information see Roster Control Status Widget


Alarm Notification Options

The Alarm Notifications section of the Alarms tab in the Edit Properties dialog is used to set the conditions under which your application's Alarm Notification System will contact registered operators.

Several alarm notification properties may be overridden on a case-by-case basis. See: Roster Control Using Properties

A selection of the available options.

The options in this section apply only to VTScada licenses that include the Alarm Notification System.

Property | Stored as | Description
Notification priority: Do not notify on alarms Notify on priority 1 alarms only Notify on priority 1 or 2 alarms | CallOutPriority | Use the options in this section to control which priority-level alarms will be sent to remote operators. The choice made here affects the following two options, since a delay before notifying does not apply to alarms that are sent. Note that when Notify on Priority 1 is set, Priority 2 alarms will also be read on a voice call, but only priority 1 alarms will cause a notification to be sent.
Delay to notify on priority 1 (critical) alarms | CallOutDelay1 | Controls the number of seconds that VTScada will wait for a priority 1 alarm to be acknowledged by a local operator before it is sent to a remote operator. Can be set independently within each Roster tag.
Delay to notify on priority 2 (high) alarms | CallOutDelay2 | Controls the number of seconds that VTScada will wait for a priority 2 alarm to be acknowledged by a local operator before it is sent to a remote operator. Can be set independently within each Roster tag.
Delay between calls | RosterDelay | Controls the default length of time that VTScada will wait between making calls. The call sequence is controlled by a roster, configured within the application. If the roster fails to send a notification to one contact, no delay is used before attempting the next (if any).Can be set independently within each Roster tag.
Initial section | IncomingCallSection | Alarms sent by phone are organized according to a menu. You may choose which page of the menu will be spoken first, allowing operators to immediately hear the most relevant information without needing to step through a menu.
Echo phone through speaker | EchoPhoneThroughSpeaker | If the server has a properly configured sound card and speaker, alarms that are dialed out can also be spoken at the server.
Answer Inbound Calls | AnswerAlarmCalls | Controls whether inbound calls are answered. If not selected, this prevents the Alarm Notification System audio discriminator from being registered with the Modem Manager. This would be useful in an application where the Alarm Notification System is not being used for incoming voice calls, but other drivers are registered for incoming data calls. 30 seconds of time can thereby be saved from each inbound call. Not to be confused with the Modem Manager property, AnswerCalls.
Dial when alarm triggers | DialOnActive | Controls whether active alarms should dialed out.
Dial when alarm clears | DialOnClear | Controls whether the alarm system will dial out when the alarm clears.
Cancel call when alarm is acknowledged | DialCancelOnAck | If one operator acknowledges the alarm while the notification system is calling another, this option will cancel the phone call.
Cancel call when alarm clears | DialCancelOnNormal | Controls whether unacknowledged alarms whose condition has become normal should be dialed out to operators
Speak digit on phone key press (VoIP or Voice Modem only) | DialDTMFFeedback | Controls whether all phone key presses are spoken back to the user.

Additional notes:

  • If DialCancelOnNormal is set and the alarm goes normal, records are removed from the notify list. Otherwise they are left on.
  • If DialCancelOnAck is set and the alarm is acknowledged, records are removed from the notify list.
  • If DialOnActive is set, and an alarm goes active, or becomes unacknowledged, it is added to the notify list.
  • If DialOnClear is set and the alarm goes normal, records are added to the notify list.
  • Active alarm records on the notify list are not resent to contacts who have already been notified once.
  • Normal alarm records on the notify list are only sent to contacts who have received an active notification.
  • After a single pass through the roster contact list, all records that are not on the Unacknowledged list (including any "Normal" records) are removed from the Notify list, unless the EnableRosterListRepeat setting is TRUE.
  • "Being notified" means that an email or SMS text message has been successfully sent to you, unless "Continue Roster Sequence" is checked. It does not guarantee that you have received it, because we have no control over the external network. For voice calls, if the contact logs in, a call is considered as having been notified.

When DialCancelOnAck is set to 0, the alarm notification will not stop after the alarm has been acked. When DialCancelOnNormal is set to 0, the alarm notification will not stop after the alarm has been cleared.
This means that if DialCancelOnNormal and DialCancelOnAck are both set to 0, the alarm notification will keep repeating indefinitely with no stop condition.


Roster Control Using Properties

Some aspects of Alarm Roster behavior can be controlled on a Roster-by-Roster basis using properties defined in a parent Context tag or parent Alarm Database tag.

(The following list of properties has been edited in version 12.1 to exclude those that are better managed within the Roster or the Alarm Notification System Properties dialog. )

Note that there are two lists on this page. For properties in the first list, the Context tag must be a parent of the Roster that is to be modified. For the second list, the Context tag must be a parent of the alarm tag or tag containing the built-in alarm.

If the default settings are suitable for all of your rosters, there is no need to also set them in a Context tag. Use the information in this topic only if you need to override the default behavior for certain rosters or alarms.

Settings that may be added to a Context parent of a Roster tag:

GiveUpCallTimeout

How long we wait before giving up on a voice call attempt.

HideMenuOnOutgoing

True to prevent navigation back to the main voice menu on an outgoing call.

SkipLogonDialOut

When set TRUE, the challenge / response for calls that dial out to the user will be disabled. The user will not be able to return to the main menu.

DialerLocation

The introductory phrase uttered by the dialer. Defaults to "This is the VTScada System".

LimitRosterToParentDB

When LimitRosterToParentDB is TRUE (default) a Roster that is a child of a custom AlarmDatabase will see only alarms in that database. If set to FALSE, the Roster will report alarms that have a matching area but exist in a different AlarmDatabase.

PINRetries

The number of times a user is allowed to attempt their PIN before the call will be disconnected.

DialerAckIndividualAlarms

If true, a user is given the option of acknowledging each alarm individually, as opposed to all or nothing.

MenuRepeatMax

The number of times a menu will repeat without a user response before the dialer hangs up.

NotificationErrorDelay

The delay between attempts that follow a failure to deliver the message on the first run-through of the Roster.

RepeatMenuTime

The delay in seconds between menu repetitions.

DialInControl

Enables access to control actions via the phone

Settings that may be added to a Context parent of the root tag of an alarm being sent:

CallOutPriority

Determines whether any alarms, only priority 1 alarms, or priority 1 and 2 alarms are called out.

MaxCallAlarmPriorityReported

Controls whether lower priority alarms are reported when higher priority alarms are called out.

DialOnActive

Dial when placed on the Active list or Unack list for Trip alarms.

DialOnClear

Dial when alarm removed from Active list.

DialCancelOnNormal

Cancel dial when alarm clears.

DialCancelOnAck

Cancel dial when alarm is acknowledged.


Log and Report

Fundamental Components of Every Report:

Reports are not just pieces of paper created by a reporting engine. Whenever you have all three of the following components, you have the essentials of a report. Viewed this way, you have many options.

A selection of data, collected for the purpose of a report.

This includes raw data from any I/O tag, processed data from VTScada analytic tags, driver quality statistics, alarm history, and operator notes. It can also include data pulled from outside sources.
In all cases, data stored within VTScada is logged using Historian tags, which offer several configurable options.

A process that calculates, filters and summarizes the raw data into meaningful information.

Sometimes you will want to see raw data as it was stored, but most often you will want to filter and summarize the information to identify trends or statistics.
VTScada's report generation tools provide a selection of ways to process information as it is retrieved. Analytic tags will do that processing before storage. If using a third-party reporting program, you might choose to export raw data for later processing using that program's tools.

The presentation of the information in a way that is appropriate to inform a target audience.

Options include the Historical Data Viewer (trend graph), the Reports Page where you can build reports, and a variety of tools to extract VTScada's data for processing and display in third-party programs.

Reports are not only those things created by report generators. This discussion takes a much broader view, where report generators are only one tool of many available to help you turn raw data into useful knowledge. Anything that achieves these three fundamental components can be considered a report. If your goal in creating a report is to take information that's on the screen and put it onto paper, why use a report generator when you can just click the print button from any VTScada page?

Choose Your Reporting Solution

Your choice of reporting solution will be influenced by the trade-off between several factors.

  • Whether the data for the report is found entirely within VTScada or if it is a mixture of data from several sources.

  • The amount of processing required to turn the raw data into meaningful information.
  • The amount of formatting required to present the information properly in your reports.
  • The skills and knowledge at your disposal. Any given solution may require knowledge of VTScada, VTScada's scripting language, VBA, SQL, and third-party programs.
  • The expense you are willing to make for third-party programs that provide either extra features or greater ease-of-use for reporting.
  • The time at your disposal for creating customized reports and learning new skills that may be required for a given reporting solution.

Integration With Third-Party Reporting Tools

You have several options for using third-party reporting tools with VTScada:

  • VTScada provides a data query add-in for Excel. Use this to connect to your application data and build custom queries that can be further refined using Excel's calculation and formatting tools. Excel Add-in for Data Retrieval
  • If your license includes the Remote Data Access option, you can use any ODBC-compatible program to query VTScada using SQL selection statements. See: SQL Queries
  • VTScada is compatible with XLReporter® from SyTech Incorporated. A datasheet is available from the Trihedral website: https://www.vtscada.com/wp-content/uploads/2014/10/Tech_VTScada.pdf
  • VTScada is compatible with DreamReport® from Ocean Data Systems®. A datasheet is available from the Trihedral website: https://www.vtscada.com/wp-content/uploads/2014/10/Dream-Report-Product-Overview-for-VTScada.pdf


Collecting Data

In VTScada, data comes from tag values. At a minimum, you can count on the following three pieces of information being available:

  • The name of the tag from which data is being collected.
  • A UTC timestamp recording when each value was collected.
  • The value of the tag.

Alarm history is similar:

  • The identity of the tag triggering the alarm.
  • A status describing the alarm transaction: triggered, normalized, acknowledged, shelved, etc.
  • The UTC time stamp recording when the transaction occurred.
  • The setpoint of the alarm and the value of the trigger at the time of the transaction.
  • Further details about the transaction...

Values from status tags (Analog, Digital, Pump) are logged automatically. For certain other tags, you must add a logger. If a tag is not logged, then historical information will not be collected for any report.

Logging isn't free. It costs CPU time and disk space.
Log everything that you need but think about your choices, especially the frequency at which tags poll and the deadband you set on analog values.

The frequency of data collection depends on the tag configuration. Status tags with a built-in Historian link write to the log when the value changes by an amount set in the tag configuration (deadband setting). Logger tags can write at a set interval or they can log on change (without the benefit of a deadband.)

The value being recorded depends on the tag to which the logger is attached. In most cases, this will be a simple measurement taken directly from a tag such as an Analog Status. If the data source for the logger is a calculation tag, then anything that can be calculated from the system (the sum of several other tags, an average over time, etc.) can be logged.

The logged data for each tag is stored in directories named after that tag. There will be one set of these directories for each Historian in the application, all of which are collected under a folder named DATA. (For example, C:\VTScada\MyAPP_AH\Data\History\[SystemHistorian]\.)

The data is stored using a proprietary format that is not published. You are advised to use the tools provided with VTScada to access the information.

As an alternative, you can configure the Historian tag(s) to save data to a 3rd party database such as Oracle or MySQL. If doing so, it is your responsibility to install and maintain the database program and data. Whether you use the VTScada data storage system or a 3rd party database, the primary tools for reviewing historical data are the History Data Viewer and the VTScada Reports Page.

Dealing with Daylight Savings Time:
VTScada records all data using UTC timestamps. In UTC, time advances at the rate of one second per second (barring leap-seconds) and if you were to plot your data against UTC time, you would see an uninterrupted line, assuming that your system is up and running, logging data.
Complications arise in places where daylight savings time (DST) is used. When DST starts in the spring, clocks jump forward from 2:00:00am to 3:00:00am. As far as UTC is concerned, data continues to be logged at the same rate, but if viewed on a graph that shows the local time, there will be a gap or a straight line showing no data for that hour. This is not a problem with VTScada. The gap exists because no time passed when the clock jumped forward, and therefore there is no data for that hour. Nothing can be shown.

Also, that day is 23 hours long, not 24, which may affect your reports. Again, this is not a problem with VTScada. According to your local clock, the DST-transition day had only 23 hours, therefore a daily report can include only 23 hours worth of data.

In the autumn, when daylight savings time ends, you can expect the same in reverse. It will appear that an hour's worth of data is over-written during the transition as the local clocks repeat that hour. That day is 25 hours long.

Rest assured that VTScada is faithfully and steadily recording your data, regardless of what your local clocks are doing.


Historian and Logger Configuration

VTScada uses its own storage system for saving data. It includes all the tools you need to extract data when and how you wish.

The task of collecting and saving data is managed by Historian tags. There are at least two in every application (SystemHistorian and SystemAlarmHistorian) and you can add more if required.

By default, information is written to a proprietary storage format, located in the Data folder of your application. You can choose to store your data in a 3rd party database such as Oracle®, PostgreSQL®, SQLite®, MS SQL Server® or MySQL®, but this is not a common configuration. Note that VTScada will use its own data storage system within these databases, therefore you should plan to query and retrieve your data using the VTScada tools, regardless of how and where it is stored.

Dealing with Daylight Savings Time:
VTScada records all data using UTC timestamps. In UTC, time advances at the rate of one second per second (barring leap-seconds) and if you were to plot your data against UTC time, you would see an uninterrupted line, assuming that your system is up and running, logging data.
Complications arise in places where daylight savings time (DST) is used. When DST starts in the spring, clocks jump forward from 2:00:00am to 3:00:00am. As far as UTC is concerned, data continues to be logged at the same rate, but if viewed on a graph that shows the local time, there will be a gap or a straight line showing no data for that hour. This is not a problem with VTScada. The gap exists because no time passed when the clock jumped forward, and therefore there is no data for that hour. Nothing can be shown.

Also, that day is 23 hours long, not 24, which may affect your reports. Again, this is not a problem with VTScada. According to your local clock, the DST-transition day had only 23 hours, therefore a daily report can include only 23 hours worth of data.

In the autumn, when daylight savings time ends, you can expect the same in reverse. It will appear that an hour's worth of data is over-written during the transition as the local clocks repeat that hour. That day is 25 hours long.

Rest assured that VTScada is faithfully and steadily recording your data, regardless of what your local clocks are doing.

When the connection to an Historian is built into a tag, that tag's values are written with every change. The use of a deadband on analog-value source tags is recommended to avoid logging system noise, and in fact is present by default in the tags, I/O and Calculations & Analog Status. See: Optimize Your Configuration for related steps that you should take to avoid problems when logging data.

If using tag types that do not have a built-in connection to the Historian, you must add a Logger tag (Logger Tags) to serve as a go-between, passing data from the collection tag to an Historian.

Historian tags have been designed to provide dependable, efficient service with minimal configuration. Refer to Historian Tags for configuration options.

Two additional configuration options for your Historians are done using the Edit Server Lists panel of the Application Configuration dialog:

  • Redundant storage locations. In a multi-server application, you can (and should) configure backup servers. Data will be copied automatically, and backup servers can take control when the primary is offline.
  • Load distribution between multiple Historian tags. By adding more Historian tags, each running on a separate server and saving to separate databases, you can ensure that the data logging requirements of extremely large systems does not exceed any one server's I/O capacity.

System Historian versus System Alarm Historian

Both are Historian tags and both write data to long-term storage. In general, it is best to keep process I/O data separate from the alarm history for the following reasons:

  • Retrieval speed.
    If alarm data were mixed with process I/O data, it would take longer to retrieve. The stored history of alarms and events tends to be very small compared to I/O process history.
  • Local storage.
    For applications that run on multiple workstations, every workstation will have its own copy of the alarm database so that alarm information remains available in the event that the workstation becomes separated from the rest of the network.
    This is not a good idea for your stored process I/O data. Therefore, the System Alarm Historian is configured to maintain a local copy of its database on all workstations, while the System Historian is not.
    (Caution: do not confuse this concept with that of backup Historians. Client / Server Configuration)


Historian Data Storage

Unless otherwise configured, Historian tags will save data to a VTScada proprietary database system within the application's data folder. These files are designed for use solely by VTScada. Values can be read only by VTScada and cannot be modified by any means without damaging system integrity.

Do not use the same storage location for multiple applications.
Do not attempt to use an external USB drive for your Historian data.
Do not configure your Historian to write to a storage device located elsewhere on your network.
For all the above, you run the risk of data loss or corruption. Your safest course is always to do initial data storage on the machine that is the current server, using the proprietary VTScada format. Rely on backup servers for remote storage, including the use of a third-party database.

While the properties described in this topic can be set in the Edit Properties dialog (StorageLocation & StorageType), you are strongly advised to use the configuration fields of the Historian tag instead. See: Historian properties Datastore tab

Storage Requirements

As a rough guideline, 1000 data changes per second will require 1500 GB per year. It is wise to use deadbands on I/O tags and set polling frequency as large as safely possible to minimize storage requirements. Also, do not save information that you will never need to retrieve in any report. Logging is enabled by default on every I/O tag, but may not be required in every case.

Storage Location

You can configure an Historian tag to send its data to an alternate location, or to a third-party database.

Compatible databases are as follows:

  • SQLite, using ODBC driver version 0.86 or later
  • Oracle version 10g or later. Requires the following Oracle privileges:

Create any index, Create any sequence, Create any table, Create any trigger, Create session, Create user, Drop any table, Drop user, Insert any table, Select any table, Update any table

  • SQLServer version 2000 or later
  • MySQL using the MySQL ODBC Connector versions between 5.1.6 and 8.00.11.00Versions of MySQL following 8.00.11.00 appear to have two bugs that affect its compatibility with VTScada (Bug #108434 and Bug #108452) For the time being, you are cautioned to avoid MySQL versions later than 8.00.11.00. 1. Requires the following MySQL privileges:

Select, Insert, Update, Delete, Create, Drop, Index

  • PostgreSQL version 9.4 or later

If using a third-party database, you do not need to create tables, as this will be done by VTScada. It is strongly recommended that a specific database and user be reserved for use only by the VTScada Historian.

VTScada stores data in a form that has been optimized for performance, reliability and synchronization. Informal testing shows that the native VTScada Historian can store data at a rate that is roughly an order of magnitude faster than SQL. You are advised to use an SQL database only on a backup server. (See notes later in this topic under Configure Alternate Data Stores.) If you are using a third-party SQL data store, then when creating queries, you will find that it is easier to use the VTScada ODBC Server for direct SQL access because it has been designed to handle the complexities of the data structures for you.

If using an Oracle database as a target for historian data, the database must have a "tablespace" named "Users", which is not present in a new Oracle DB. This is used as the default tablespace for the user created by a historian tag, and is where all the historian tables are stored.
All tables are created with the "owner" (or schema) named after the tag name. So, given a historian tag of "SystemHistorian", then all tables are created with the owner SYSTEMHISTORIAN and have a name such as "SYSTEMHISTORIAN.FRIENDLYTAGNAMELOOKUP".

If you are using the VTScada database system for data storage, then there is no need to set any value for the Historian tag's Storage Type property. You might set the Storage Location property if you want to save the data somewhere other than the default Data\History folder of your application. Writing across a network to another machine is strongly discouraged.

If writing to a third-party DBMS, the storage location should be either a connection string in the form:

Driver=ServerBrand;Server=ServerName;Database=DBName;Uid=user;Pwd=pwd

Alternatively, it may be a reference to a DSN, as follows:

DSN=MyDSNName

Use of a DSN is recommended to avoid having the user ID and password for your database visible in the Historian tag's configuration.

Prerequisites:

If modifying the location to a new folder on your computer, then the only prerequisite is that the folder exist on all Historian servers. This should be configured before commissioning the application.

  • In general, do not specify a network location other than the hard drive of the Historian server(s).
  • To configure for redundancy see Client / Server Configuration.
  • To configure for backups see Backups

If configuring VTScada to use a third-party database, all the following must be in place:

  • The database program must be installed and running.
  • An ODBC driver for your program must be installed. VTScada can work with either 32 or 64 bit ODBC drivers unless you are running the 32-bit version of VTScada.
  • You may use either a connection string or you may use a DSN, created using the Microsoft ODBC Administrator tool.
  • A database must be created for use by VTScada.
  • A user account must be created in your database for use by VTScada. This account must have CREATE and WRITE privileges in the database, so that VTScada can create tables and write data to those tables.
  • Choose whether to set your Historians' storage type to ODBC or ODBCSingleTable.
    This choice affects how your data is stored, and therefore how you can query it. See notes at the end of this topic and also Query a 3rd-Party DBMS
  • After completing all configuration steps, ensure that the database is running and then restart your application.
    VTScada will create the tables required to store data if you do not restart, but may not create support tables such as 'friendlytagnamelookup'.
    It may take up to 30 seconds for all tables to be created.

Example 1:

For example, to direct the System Historian to use a SQL Server database, identified by a connection string, the Historian tag's data store properties would be set as follows:

StorageName: SystemHistorian

Type: ODBC

Storage Location: Driver=SQL Server;Server=ServerName;Database=DBName;Uid=user;Pwd=pwd

Example 2:

Connecting to a MySQL database.

A database named 'vtscada' has been created.

A user named 'VTS' has been created.

'VTS' has been granted CREATE and WRITE privileges on 'vtscada'.

The ODBC connection is created as shown. The user and password are for the MySQL database, not a VTScada account.

Sample DSN creation, using the MySQL connector within the Microsoft ODBC Administrator tool.

The VTScada System Historian is configured as follows:

The storage type is ODBCSingleTable for ease of data access.
The DSN matches the previous example image.

When using ODBC Historians, it is suggested that you specify the Storage Name parameter. This will be used as the schema name in the database. If left blank, the unique id of the Historian tag will be used as the schema name rather than its short name. Note that the unique id's length and complexity may cause difficult for some database programs.
The Storage Name must be unique for each Historian.

Configure Alternate Data Stores

One Historian with two separate databases

To record to both the VTScada data store and a third party ODBC database, or to save to the C: drive on one machine and the D: drive on another, there must be at least two VTScada workstations in your system. You can then configure the Historian tags using parameter expressions that use a different configuration on each workstation. In the following examples, "SQLBackup" is the name of the computer where the ODBC database is installed. Parameter Expressions are added to the configuration fields of the Datastore tab of the System Historian as follows. These expressions check the workstation name using "WkStaInfo(0)", and configure for the ODBC database if the workstation is SQLBackup, or use default settings otherwise, by returning "Invalid". Note that the test for workstation name is case-sensitive.

StorageName:

WkStaInfo(0) == "SQLBackup" ? "SchemaNameForDB" : Invalid

Type:

WkStaInfo(0) ==  "SQLBackup" ? "ODBC" : Invalid

Storage Location:

WkStaInfo(0) ==  "SQLBackup" ? "Driver=SQL Server;Server=ServerName;Database=DBName;Uid=user;Pwd=pwd" : Invalid

Data store configuration should be done before the application begins to collect information. Upon changing any Historian's storage type or location, that Historian will lose access to previously collected values.

ODBCSingleTable - Single Table Schema Structure

When your Historians' storage type is set to ODBCSingleTable, tag values are stored using one of the schemas described here. Note that while the table name is the value shown in the column Table name, in your database that name may be prepended with other information including (but not limited to) the schema name for each Historian tag.

This table represents only standard tags in VTScada version 12 or later. Custom-coded tag types and data collected from applications running under VTScada versions prior to 11.5 are not reflected here.

If your application includes custom-coded tag types whose data cannot be stored with any of the default schemas, you must add new HistorianODBCTableNamesX properties to your Settings.Startup file.

Setting | Table name | Schema string
HistorianODBCTableNames0 | Numerics | Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-R8|Value!-UI4
HistorianODBCTableNames1 | Digitals | Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-UI1|Value!-UI4
HistorianODBCTableNames2 | Strings | Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-STR|Value!-UI4
HistorianODBCTableNames3 | Historians | Timestamp-TSTAMP-T|MachineID-STR-M|Availability-BOOL-U
HistorianODBCTableNames4 | Notebooks | Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-STR
HistorianODBCTableNames5 | Ports | Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-I2
HistorianODBCTableNames6 | Drivers | Timestamp-TSTAMP-T|GenTimestamp-UI4-A|ErrorValue-I2|FailedCount-I2|FailedRetryCount-I2|SuccessCount-I2|Quality-R8|ResponseTime-R8|ErrorAddress-STR
HistorianODBCTableNames7 | Modems | Timestamp-TSTAMP-T|GenTimestamp-UI4-A|LCallFailures-R8|LCallState-R8|LEnabled-R8|LFailure-R8|LMediaMode-R8|LOffHook-R8|LCurrentNumber-STR
HistorianODBCTableNames8 | Transactions | Timestamp-TSTAMP-T|GenTime-R8|TransactionID-BYTES|ErrorCode-I4|Encoding-I4|PackedData-BYTES
HistorianODBCTableNames9 | Alarms | Timestamp-TSTAMP-T|PackedData-PACK|Area-STR|Encrypted-BOOL|PackedInfo-PACK
HistorianODBCTableNames10 | DataFlowTag | Timestamp-TSTAMP-T|GenTimestamp-UI4-A|ErrData1-UI1|ErrData10-UI1|ErrData11-UI1|ErrData12-UI1|ErrData13-UI1|ErrData14-UI1|ErrData15-UI1|ErrData16-UI1|ErrData17-UI1|ErrData18-UI1|ErrData19-UI1|ErrData2-UI1|ErrData20-UI1|ErrData21-UI1|ErrData22-UI1|ErrData23-UI1|ErrData24-UI1|ErrData25-UI1|ErrData26-UI1|ErrData27-UI1|ErrData28-UI1|ErrData29-UI1|ErrData3-UI1|ErrData30-UI1|ErrData31-UI1|ErrData32-UI1|ErrData4-UI1|ErrData5-UI1|ErrData6-UI1|ErrData7-UI1|ErrData8-UI1|ErrData9-UI1|ErrMod-UI1|ErrorValue-I2|FailedCount-I2|FailedRetryCount-I2|SuccessCount-I2|Quality-R8|ResponseTime-R8|ErrorAddress-STR

If changing a legacy application to use ODBCSingleTable instead of ODBC, there is an advantage to allowing VTScada to rename the tables. Do so as follows.

Use this procedure only if changing from ODBC to ODBCSingleTable, and only after upgrading to VTScada version 12.0.08 or later.

  1. Ensure that you have configured primary and backup servers for your Historian(s), each with a local copy of the stored data.
    You may need to use the expressions provided earlier in this topic to configure separate Historian storage locations on different servers.
  2. Stop the backup server.
  3. Add the HistorianODBCTableNamesX properties to your application's Settings.Startup file.
    (You can copy these from HistorianODBCTableNames)
  4. Delete the tables from the database on your backup server.
  5. Restart the application on your backup server and allow data to synchronize.

  6. Repeat steps 2, 4 and 5 on any server that is writing to the 3rd party database.


Query a 3rd-Party DBMS

If you have chosen to store your VTScada data in a 3rd-party database management system, be aware that Historian redundancy may create multiple copies of data. This is done to ensure reliability, but can mean that retrieving data is not a simple matter of collecting sets of timestamps and values for a tag. In the case of conflicts, refer to the value in the arbitration column. As a general guide, you are advised to use VTScada's data retrieval tools including SQL Queries and SQLQuery rather than query a 3rd-party database directly.

If writing your own queries, the steps vary depending on whether you have chosen to store data in a single table for each type of tag, or to store each tag's data in its own table.

ODBC storage type

If you have configured your Historian tags with the storage type, ODBC, then tag data will be stored into separate tables for each tag. For example:

systemhistorian_rd29drhfxy7k8ye2o92s00000615zf

systemhistorian_rd29drhfxy7k8yenstx000000815zf

etc.

Assume that you have a tag named "\Station 1\ModDriver\Pump 1\Flow" and want to retrieve its logged data directly from your ODBC database. Using a series of queries, you can find this tag as follows:

SELECT * FROM systemhistorian_friendlytagnamelookup
WHERE friendlyname = 'Station 1\\ModDriver\\Pump 1\\Flow';
+-----------------------------------+---------------------------------------------+-------------------------------------------------+
| friendlyname                      | uniqueID                                    | tablename                                       |
+---------------------------------------------+---------------------------------------------+---------------------------------------+
| Station 1\ModDriver\Pump 1\Flow   | (rd29d~r}h\fxy7k!8@ye\#ssm(o~p#r\g#_t_m^2qz | SystemHistorian_rd29drhfxy7k8yessmop00000a15zfs |
+-----------------------------------+---------------------------------------------+-------------------------------------------------+

This tells us which table holds the tag's data. You can now query that table:

SELECT Timestamp, value from SystemHistorian_rd29drhfxy7k8yessmop00000a15zfs
WHERE Timestamp < '2020-04-07 16:25:50' AND Timestamp >= '2020-04-07 14:25:50';

It is not possible to combine these two queries into one with a JOIN operation because we do not know the name of the table that holds the tag's data until after performing the first query. For this reason, the storage type, ODBCSingleTable is generally preferred.

ODBCSingleTable storage type

If you have configured your Historian tags with the storage type, ODBCSingleTable, then tag data will be collected into tables according to their type. For example:

systemhistorian_numerics

systemhistorian_drivers

etc.

For clarity on data storage, the following examples use a single query for each step of the process of identifying where to look for a tag. In practice, a JOIN operation is recommended, both to simplify data retrieval into a single query and to avoid the need to escape backslash characters in 'uniqueID' values.

Assume that you have a tag named "\Station 1\ModDriver\Pump 1\Flow" and want to retrieve its logged data directly from your ODBC database. Using a series of queries, you can find this tag as follows:

SELECT * FROM systemhistorian_friendlytagnamelookup
WHERE friendlyname = 'Station 1\\ModDriver\\Pump 1\\Flow';
+-----------------------------------+---------------------------------------------+--------------------------+
| friendlyname                      | uniqueID                                    | tablename                |
+-----------------------------------+---------------------------------------------+--------------------------+
| Station 1\ModDriver\Pump 1\Flow   | (rd29d~r}h\fxy7k!8@ye\#ssm(o~p#r\g#_t_m^2qz | systemhistorian_Numerics |
+-----------------------------------+---------------------------------------------+--------------------------+

This tells us which table holds the information and what the tag's unique ID looks like to the database.

Before querying that table, note two details:

  • The uniqueID value contains backslash characters. If performing multiple queries as shown, you may need to configure your database to allow these to be treated as simple characters rather than as escape characters. That step is not required if using a JOIN operation, as shown in the example at the end of this topic.
  • systemhistorian_Numerics doesn't have a uniqueID column, identifying the tags. Instead, tags are identified using an integer ID, stored in the column TagID. To discover the TagID for our Flow tag, we must query systemhistorian_tagidentifierlookup as follows, using the UniqueID from the previous query.

SELECT * FROM systemhistorian_tagidentifierlookup
WHERE tagname = '(rd29d~r}h\fxy7k!8@ye\#ssm(o~p#r\g#_t_m^2qz';
+----+---------------------------------------------+----------------------------+
| id | tagname                                     | tagidentifier              |
+----+---------------------------------------------+----------------------------+
| 10 | (rd29d~r}h\fxy7k!8@ye\#ssm(o~p#r\g#_t_m^2qz | rd29drhfxy7k8yessmop00000a |
+----+---------------------------------------------+----------------------------+

This tells us that the tag's id value is 10. Finally, we can query for the stored flow values:

SELECT Timestamp, Value FROM systemhistorian_numerics WHERE TagID = 10
AND Timestamp < '2020-04-07 16:25:50' AND Timestamp >= '2020-04-07 14:25:50';
+---------------------+-------+
| Timestamp           | Value |
+---------------------+-------+
| 2020-04-07 14:27:09 |    10 |
| 2020-04-07 14:27:11 |   325 |
| 2020-04-07 14:27:13 |   482 |
...

Merging the three previous queries into a single query with JOIN operations will avoid the need to handle backslash characters in the tag's Unique ID / tagname. For example:

SELECT Timestamp, Value FROM systemhistorian_numerics
INNER JOIN systemhistorian_tagidentifierlookup ON TagID = id
INNER JOIN systemhistorian_friendlytagnamelookup ON tagname = uniqueID
WHERE friendlyname = 'Station 1\\ModDriver\\Pump 1\\Flow'
AND Timestamp < '2020-04-07 16:25:50' AND Timestamp >= '2020-04-07 14:25:50';

Historian Redundancy and Edited Values

As noted elsewhere (Historian Data Storage), VTScada may record redundant values to ensure data integrity in a multi-server environment. It is also possible for authorized users to Edit Data, although this means adding new values with matching timestamps rather than changing values.

To deal with either situation, use the Arbitration column. Larger values mean a later addition. When using VTScada's built-in tools to query history, if two records with matching timestamps are found, the one with the larger arbitration value is chosen automatically.

For example, consider the following result set:

+---------------------+---------------------+-------------+-------+
| Timestamp           | VTS_Historian_TS    | Arbitration | value |
+---------------------+---------------------+-------------+-------+
| 2020-04-08 11:57:49 | 1586347068836000000 |  1586347068 |   629 |
| 2020-04-08 11:57:51 | 1586347070839000064 |  1586347070 |   619 |
| 2020-04-08 11:57:53 | 1586347072842000128 |  1586347072 |     0 |
| 2020-04-08 11:57:49 | 1586347068836000000 |  1586349734 |   700 |
+---------------------+---------------------+-------------+-------+

The first and last records in this sample have identical timestamps. Only the Arbitration column tells us that the last record (700) was added later. Referring to the grid view of the VTScada Historical Data Viewer (raw data mode) we can see the history of this change:

(Stored timestamps are in UTC. The image from the Historical Data Viewer shows timestamps adjusted to Atlantic Daylight Time.)

Related information:

SQL Queries


Historians and Multiple Servers

In most smaller systems (ranging up to a few thousand tags) you may not need to have more than a single Historian tag.

Reasons why you might consider adding one or more additional Historians include:

  • Load distribution in larger systems - each Historian can be configured to save its data to a separate server, thus reducing load on any individual server.
  • Alternate storage locations for selected tags - you may configure each historian to save to a different directory, or to a different storage format.
  • Alternate configurations for data limiting - you may choose to limit the amount of data stored for some tags, but not limit data collected from others. Each Historian can have its own configuration.

This is the default configuration of a multi-server application running on a primary and backup server. HistorianA is the System Historian, saving data on the primary server, then copying it to the backup. The advantage of this configuration is that it creates a fully redundant copy of all data. If Server 1 is the primary, it will direct Server 2 to also write all data as it arrives. If one or the other server goes offline for a period of time, data will be synchronized when access to that server is restored.

A variation of the above is to configure the Historian to save data to specific database on one server. Typically, this is done only by sites that use a 3rd-party database. On one server, data is stored using the default VTScada system but on the other, data is stored using the commercial database. Users will see no difference.

To prevent data loss, ODBC Historians should always have a backup server using a distinct, alternate data store. The VTScada database format is always to be preferred for reliability.

Using only a 3rd-party database

For this configuration, while both Historians will write to a single database, they will be writing to separate schemas on that database. This configuration would occur if the following configuration is one on the primary VTScada server and left unchanged when the application is installed on the remote server.

SystemHistorianStorageType      = ODBC
SystemHistorianStorageLocation  =  Driver=SQLite;Server=DBServer;Database=DBName;Uid=user;Pwd=pwd

There is no particular advantage to having the System Historian write to separate schemas on the same server. Therefore, if using an ODBC storage type you should consider using a workstation configuration file to set a unique StorageLocation value on each server.

Two Historians

This figure compares the difference between having one versus two Historians on a single server. There is no advantage to this configuration - it merely illustrates the difference.

Historian Load Distribution

This example is designed to handle an extremely high data-logging load by providing three Historians, each with one redundant server. It is assumed that each Historian is logging data from 1/3 of the tags.

Configured for load distribution and backups

In this configuration, each of the machines will carry 2/3 of the disk activity load.

Server detail shown from the Advanced Interface of the Edit Server Lists page of the Application Configuration dialog.

Server list matches previous figure


Monitor the Historian's Connection

You can use a VTScada expression to verify that any given Historian is connected to the data store on a given server. This expression may be created within an I/O and Calculation tag or as the condition for an Alarm tag.

Given an Historian named, "SystemHistorian" storing data on a server named "LogServer1" the expression to use is as follows:

Scope(\Code, "SystemHistorian")\GetServerStatus("LogServer1")

This expression will return a valid FALSE if disconnected. Invalid means that no data is available for that server, or it is a client, not a server.

By monitoring the connection, you can quickly raise an alarm if there is a loss of communication.

Related information:

Historian Status Widget - Library object for monitoring all Historians in an application.


View Legacy Data

Applications that were in use and logging data prior to the introduction of the Historian tag will have legacy data. The Historian tag can read this legacy data, but it must be configured to do so.

Three application properties are used by the Historian tag to find legacy data. The property, UseLegacyHistoryPriorTo will be configured for you when you convert an older application to the current format but, you may need to adjust the values for your particular application.

UseLegacyHistoryPriorTo

Sets a time stamp marking the latest date and time that legacy data was recorded. This will usually be the moment that the application was converted from one system to the other but, if your application is configured to use a time-delay when logging data, then you may need to adjust the UseLegacyHistoryPriorTo value to account for the offset.

LegacyHistoryPath

Required only on a workstation that does not have its own copy of the data. Typically set to a network path, identifying the machine and the folder (usually "History") where the legacy data is stored.

LogPath

This legacy property predates the Historian tag. If present, it should be left unchanged.

Legacy data is not synchronized between servers in a multi-server application. It exists only on the computers that you explicitly copy it to. You should copy it to the primary server and all backup servers to ensure that the data is continuously available. In a multi-server application, copy the data from whichever server is deemed to have the most complete copy of the data.

Should a workstation client lose its connection to all servers, it will not have access to the legacy data.


HDV Configuration

As a system developer, you have access to several tools to customize the Historical Data Viewer (HDV) and to provide in-page tools that make it easier for your operators to open and use the HDV, or use similar features such as the widgets, Plot Data or Sparklines.

Choose from any of the following:

Historical Data Viewer Tab of Edit Properties
Control the colors used for the Historical Data Viewer

Change Pen Styles
Modify how pens are shown on a trend plot.

Draw HDV Widget
The widget can provide all the features of the HDV, or a customized subset. Draw one or more on any page.

HDV Button Widget and HDV Hotbox Widget
Use these to give operators a quick link to the HDV with a predefined tag selection and timespan.

Plot Data Widget
An older but very useful widget that shows a trend of a single tag.

Sparklines Widget
An at-a-glance widget that shows whether a value is trending up, down, or remaining the same.


Edit Data

It is not possible to change or delete values logged by VTScada. View the original value by clicking the note symbol displayed beside the edited value.

Authorized users can add or amend logged values by creating overrides. This may be useful for a number of situations:

  • It may be necessary to adjust a single data point to replace an incorrect value.
  • A broken instrument reports a series of bad values during a time range. This can happen when a sensor breaks. When a worker takes a manual measurement they need a way to replace the range of bad values with a single manual reading.
  • After editing a historical value, a correction may need to be entered at a later time.
  • After editing a historical value, the edit may have to be removed because the wrong value was changed.
  • There may be a need to annotate a single value or a range of values.
  • In a situation where measurements are taken manually, a value might be obtained at 2pm but not entered until 5pm.

For routinely entering values not monitored by I/O tags, consider using Data Entry Forms. Forms-enabled widgets can enter values with flexible time offsets.

How to Edit Data:

Override values are created or removed using the Grid View of the Historical Data Viewer.

Data editing tools are enabled only when viewing the Raw Data mode, and when one or more records in the grid view are selected.
Only users with the Edit Data security privilege may use these tools.

  1. Open the Historical Data Viewer, with one or more tags (pens) selected.
  2. Switch to the grid view.
  3. Ensure that the data mode is set to Raw Data. (A)
  4. To change an existing entry or to add a new entry, select one row. (B)
    To change a range of entries to a single new value, use the shift key to select several rows.
    (Is it not possible to use the Ctrl key to select a random set of rows.)
  5. Click the pen tool in the Data Editing tools. (C)
    The Edit Historical Data dialog opens.
  6. Provide a new value and enter a note for auditing purposes.
    See following discussion relating to the use of Start Time and End Time.
  7. Click OK.

The overridden value will be indicated by an exclamation mark (!) and a notebook symbol.

If there is a notebook symbol but no exclamation mark, then either the original value was restored or a note was added without changing the value. See: Symbols for Edited Values

To create a new record, change the Start Time in the Edit Historical Data dialog after opening. If Start Time matches an existing value, that value will be overridden. If there is no existing record for the specified Start Time, then a new record will be created.

As an alternative to selecting a range of rows in the grid, you can set both a Start Time and an End Time in the Edit Historical Data dialog. The result will be the same: all selected values / all values between the start and the end, will be overridden with the new value.

Restore a Value

Original values are never lost as a result of data editing. They can be restored as follows:

  1. Do steps 1 through 3 in the instructions for editing to enable the tools.
    (Previous set of instructions in this topic.)
  2. Select the value or range of values whose values are to be restored.
  3. Click the Remove Selected Data Override(s) tool.
    The Revert to Original Value dialog will open.
  4. Enter a note for auditing purposes.
  5. Click OK.

The original values are restored. All notes are maintained, as is the history of edits made. As with Operator notes, there is no means to remove or edit any note after creation.

If the value at a selected timestamp exists only because it was entered manually using the Edit Historical Data dialog, then there is no logged VTScada value to which it can revert. In this case, the most recent value (logged or overridden) prior to the selected timestamp will be assigned. The manually-entered row cannot be deleted.


Symbols for Edited Values

The value column in the grid view, or the value in the legend of the plot view may include any of an exclamation mark (!), a question mark (?) or a notebook icon. Here's an example from the grid view showing all three:

The question mark indicates that the Questionable Data flag was set at the time the value was recorded. This does not mean that there is anything wrong with the value, only that the flag was set. Refer to Questionable Data for more information.

An exclamation mark beside a notebook symbol indicates that someone used the Data Editing feature to set this value manually. A note is always created when a value is edited to record when it was changed, what it was changed from, and who changed it. The ability to edit values to correct errors or to add values that were measured manually is an advanced feature, protected by a security privilege. Refer to Edit Data for more information and instructions.

It is also possible to add notes without changing the value, in which case there will be a notebook symbol without an exclamation mark. You must have the Edit Data privilege to create these notes, but you do not need any extra privileges to click the notebook symbol and read those notes. Operators who do not have the Edit Data privilege can still create notes as described in Add a Note to the Graph.

An exclamation mark without a notebook symbol indicates that the Manual Data property of this tag is set.


Import Tag History

VTScada can import history data from CSV files that you provide. This is typically done when you have data that was collected outside VTScada and want to bring it into your SCADA system.

This feature has no user interface. All that is required is to create tags and files according to the following conditions, then restart VTScada. If operational needs prevent you from stopping VTScada on the workstation, then you can use the Source Debugger to set a property that will trigger the import.

There are strict requirements for the CSV history files. The import will not succeed unless all of the following conditions are met precisely.

  • Spreadsheet programs can add extra formatting that will ruin the import. Ensure that your files match the examples in this topic exactly.
  • Do this work on the current primary historian server.
  • You must create a folder named CSVHistory within your application's Data folder structure.
  • (e.g. C:\VTScada\MyApplication\Data\CSVHistory)
  • Copy the CSV history files to this folder.
  • Files are destroyed after importing so that the data will not be imported twice. Save a copy elsewhere.
  • CSV history files can have any name.
  • Each file may contain data for only one tag.
  • Data for any given tag may be split across multiple files.
  • Within the CSVHistory folder, create a text file named TagMapping.CSV
  • For each file that is to be imported, TagMapping.CSV must contain a line mapping that file to an existing VTScada tag name:
TagHistoryFile_1.CSV,Full\Path\To\VTScadaTagName_1
TagHistoryFile_2.CSV,Full\Path\To\VTScadaTagName_2

(Do not copy "Full\Path\To\". This is meant as an example. Use the full name of your VTScada tags. If tag names have spaces, include those here.)

  • The VTScada tags must exist and must have a link to a Historian.
  • Each CSV history file must have exactly the following structure:
UTC TimeStamp_1,Value_1
UTC TimeStamp_2,Value_2
  • If the comma or value is missing, the timestamp will be imported but the value will be logged as Invalid.
  • Values that begin with a space will be logged as Invalid.
  • The time stamp must be UTC and must be in the form:
YYYY-MM-DD HH:MM:SS.mmm

(If working Excel to generate the CSV, that would be YYY-MM-DD HH:MM:SS.000)

  • Future data or data prior to Jan 1, 1970 is considered out of range and will not be imported.
  • The time stamps must be in chronologically ascending order.

Restart the application. The values will be imported to the local Historian. If there are backup Historians, data will not be synchronized to those machines until they are restarted. Note that this will generate a large amount of network traffic and should be done at an otherwise quiet time.

If you may not restart the application on this workstation, do the following:

  1. Open the VTScada Source Debugger application.
  2. Select your application from the list of running applications.
  3. Select CSVHistoryImporter within the module tree.
  4. Scroll through the module list to find and select DoImport.
  5. Set this value to 1.

DoImport will reset to 0 following the import operation. TagMapping.CSV will be deleted only if all listed files are imported successfully.


Excel Add-in for Data Retrieval

The VTScada data retrieval add-in for Microsoft Excel® puts VTScada query tools directly into your worksheets. Create multiple queries that you can update on demand, then use Excel's features to analyze and present the information.

The VTScada toolbar within Excel

Preparation

The use of a secured connection (X.509 certificate) is mandatory. The VTScada Excel add-in will not connect to an unsecured server.
You can use a self-signed certificate, provided that you add a local loop-back exemption if both Excel and VTScada are running on the same workstation. Refer to Microsoft's trouble-shooting instructions. (Link opens in a new tab or window.)

The instructions for creating a self-signed certificate are well outside the scope of this documentation. There are many references available on the Internet, as well as many guides to the risks and benefits. Ensure that you take all necessary security precautions.

The Excel Add-in does not support connection through OpenID Connect. Ensure that the setting "Permit remote sign-in using VTScada account credentials" in the application's Security options is enabled.

The connection uses the VTScada Internet Server. Follow the instructions within Configure a VTScada Thin Client Server and Configure a Realm.

Your VTScada license must include the Remote Data Access feature.

For greater security, consider using one or more of the SQL View Tag, each of which can be assigned a custom privilege.
The Remote Tag Value / History Retrieve privilege is necessary in order to run custom SQL queries. Accounts with only the Remote Data Access privilege can see only their assigned SQL views or AlarmHistory, and cannot run their own SQL queries or browse the tag parameter tables.

The add-in will work best with the 1.4 version or later of the Excel API. It is compatible with the 1.1 API version, but may not perform as well.

In terms of Excel version, the add-in is compatible with Office 2016 build 16.0.4390.1000 or later and any version of Office Online.
An uncommon configuration requirement is to allow for Domain Aliases (CORS).

Following installation, your next steps will be to Create and Manage Connections, then Create Queries.
You may also wish to adjust the Settings for the Excel Add-in.

Installation of the Add-in

Your goal is to navigate to Microsoft's store for adding Office Add-ins. The route will vary depending on your version of Excel. In older versions, you would open the Insert ribbon and select Get Add-ins. In the version that was current as these notes were written, the Add-ins tool was found in the Home ribbon. If neither works for you, consult your Excel documentation.

When you arrive at the Office Add-ins dialog, it should be similar to the following. Type "VTScada" into the search field and press [enter].

Getting the add-in from the Office store by searching for "vtscada".


Create and Manage Connections

The use of a secured connection (X.509 certificate) is mandatory. The VTScada Excel add-in will not connect to an unsecured server.
You can use a self-signed certificate, provided that you add a local loop-back exemption if both Excel and VTScada are running on the same workstation. Refer to Microsoft's trouble-shooting instructions. (Link opens in a new tab or window.)

The instructions for creating a self-signed certificate are well outside the scope of this documentation. There are many references available on the Internet, as well as many guides to the risks and benefits. Ensure that you take all necessary security precautions.

The Excel Add-in does not support connection through OpenID Connect. Ensure that the setting "Permit remote sign-in using VTScada account credentials" in the application's Security options is enabled.

The connection uses the VTScada Internet Server. Follow the instructions within Configure a VTScada Thin Client Server and Configure a Realm.

Your VTScada license must include the Remote Data Access feature.

For greater security, consider using one or more of the SQL View Tag, each of which can be assigned a custom privilege.
The Remote Tag Value / History Retrieve privilege is necessary in order to run custom SQL queries. Accounts with only the Remote Data Access privilege can see only their assigned SQL views or AlarmHistory, and cannot run their own SQL queries or browse the tag parameter tables.

The add-in will work best with the 1.4 version or later of the Excel API. It is compatible with the 1.1 API version, but may not perform as well.

In terms of Excel version, the add-in is compatible with Office 2016 build 16.0.4390.1000 or later and any version of Office Online.
An uncommon configuration requirement is to allow for Domain Aliases (CORS).

When each tool of the VTScada Add-in is opened, there will be a fly-out menu at the upper right. Use this to learn more about the tool.

Connections are saved in the current workbook. Note that the History panel will guide you through the creation of your first connection. You need only use the Manage Connections panel if you intend to set up multiple connections, edit, or delete an existing connection.

The procedure to create your first connection is the same whether you do so using the Manage Connections panel or the History panel.

You must connect to your VTScada server and sign in before creating or running queries. To do so:

  1. Open the VTScada toolbar in Excel and select either the Manage Connections tool or the History tool.
  2. The Connections panel will open beside your worksheet.
    If you have not already created a connection in this workbook the Connection sub-panel opens automatically when you select the History tool. Otherwise, select New Connection.

The Connection panel.
Note the X in the upper right corner, which will close this sub-panel.

  3. Provide the following information:
  • A name for the connection.
    Any name may be used, but it may be helpful to create a connection name that matches the server name.
  • The URL for the server. This will typically include the realm name, where the application can be found.
    This must use a secured connection. If you are using the standard port of 443, it need not be specified.
  • An account name for the VTScada application.
    The account must have the Remote Data Access privilege.
  • The password for that account.
  4. Choose whether or not to remember the user name and password.
  5. Select Sign-in .

If successful(*), the connection name will be listed in the Connections panel. If you began the process by selecting the History tool, the Tag History Query panel will open immediately.

The Connections panel is available only after successfully creating a connection.
Use the Manage Connections tool to open.

Select the editing tool [image] to change the name, change the server address or to sign-out.

Within the expandable menu, you can also edit, as well as copy or delete the saved connection.

You may choose to create additional connections for any of the following reasons:

  • You have more than one server.
  • You connect to more than one realm.
  • You have more than one application.

(*)Troubleshooting

An attempt to connect might fail for any of the following reasons:

A bad server address

Make sure the address can be reached from the local computer. If the address works for the VIC or Anywhere Client, it should work for the add-in.

Unsecured server

Make sure that the server is secured with a certificate.

Wrong or missing realm name

Provide the necessary realm as part of the server address.

The application is not running on the VTScada server.

Ensure that the application is running.

The VTScada server does not support the Excel add-in

Ensure that the server is running VTScada version 12.0 or later.

The VTScada server is not licensed to allow remote data retrievals

Purchase the required option for your VTScada license.


Create Queries

You can build several queries within the same worksheet. Query results are returned in a tabular format, starting in the cell that is selected when you create that query. Before creating a new query, ensure that you have selected the cell where you the results to be sent. See notes later in this topic for using cut and paste within Excel to move the query result to a new location.

Queries are saved in the current workbook.

Be sure to leave space for the full query result. Every selected tag and every calculation you make will require a column(*). If you are querying for a day's data with hourly summaries, you will need 24 rows for the data and one for the title. The first time a query runs, it will use every cell that it needs, whether empty or not.

On subsequent queries, cells that contain other information will be moved as needed in order to accommodate a block that changes in size. Formulas within those cells may not adjust correctly. You are advised to find the space that will be needed by your query results and leave room.
(*) Or row rather than column if you choose to flip the result. These notes will refer to the default orientation where tags are listed across the columns and data fills the rows below each tag name.

If you need a presentation-quality report, you might choose to send the query results to a second sheet in the workbook. The first sheet can be used for the presentation layout, with links to data that is sent to the second sheet.

A query is built of several parts: Tag Selection, Time Ranges, Query Attributes (including calculations) and a choice of More Settings.
For each part, there are many options. Therefore, these notes do not attempt to provide a single set of steps to build a query. Instead, each part is discussed on its own, the options presented, and instructions or notes are provided to help you use each option.

Tag Selection

Ensure that you have selected an appropriate target cell in the worksheet before beginning. See the notes at the beginning of this topic. The initial stages of query building can be presented as a series of steps:

There is no "show children" option when browsing tags. Only one level at a time is shown.

  1. Begin the process of building a query by selecting the History tool in the VTScada toolbar to open the Tag History Queries panel.

The Tag History Queries panel with no saved queries

  2. Select the New Query tool.
    The Tag History Query panel opens. (see following image)
  3. Give the query a name that describes its purpose.

Creating a query named "Starts and Run Time"

  4. Select the Add tags tool (circled in previous figure).
    The VTScada Tag Browser opens:

The Excel Reporting Tag Browser showing one tag selected for addition to the set.

Note the two filters. The name filter (left) assumes wildcards. In the example shown, "Start" would find both "Start Pump" and "StartSignal". Do not add your own wildcard characters.
The type filter (right) will limit the view by group such as "Analogs", "Digitals" etc. Only types that are present in your application are available in the filter.

Filters apply only to the current level in the tag hierarchy; there is no "Show Children" option.
The digit beside each parent tag in the left window indicates the number of tags selected below that parent tag.

  5. Use the Add selected tool to finish creating the tag selection.

You can select several tags at once. There is no need to use "Add selected" until you have finished selecting tags. Selected tags will remain selected as you navigate through the tag hierarchy.

After using the Add selected tool, you will be given a chance to rename the selection set, and to review and edit the list (adding more tags if you clicked "Add selected" before you were finished.)

  6. Select "Save" when you have finished selecting tags.

Saving your tag selection
The option, "Tag list is relative to a parent tag" is described later in this topic.

The default name for a tag selection set is the list of tags within the set. You may find it easier to manage sets if you provide your own descriptive names instead.

You are returned to the Tag History Query panel.

A named selection set.

You can modify the tag selection at any time. (The edit tool is circled.) You can also switch to another saved tag selection.
But, only one named tag selection can be used in any query.

Variation: Tag list is relative to a parent tag

If your tags were built according to the advice in Plan your tag structures carefully, you will have a number of pumps, stations, generators, etc. that each contain a set of tags with the same names. Rather than select the same tags in every instance, you can select the tags from one instance, then create a list of stations or equipment instances containing those tags.

  1. Start by selecting the tags in one instance using the instructions from the preceding section. In the following example, one tag is chosen from Pump 1: Running State.
  2. Use the "Add selected" tool to return to the Tag History Query panel.
  3. Select the option, Tag list is relative to a parent tag.
  4. Select the closest parent to the set of tags. In this example, that is the Pump 1 context.
  5. Save the tag selection.
    You will have a chance in a later step to select Pump 2, Pump 3, etc.

The tag list consists of one tag: Running State. It's parent is identified as Pump 1.

  6. After selecting Save, you are returned to the Tag History Query panel. Note the new option, circled in the following figure.

Parent tag selection is available only when the tag list is flagged as relative to a parent tag

  7. Select the Add tags tool below Parent tag selection.
    The Tag Browser reopens.
  8. Select the parent tags that include the tag(s) you chose in the previous step.
    Note that you must select the parent as indicated earlier. In this example, those are Pumps. If you select a grandparent instead, VTScada will not search it for all the matching parents that it might contain.

A set of selected parent tags.

  9. Finish by clicking the Add selected tool, then Save.

You are returned to the Query panel, which will display the named Tag Selection and the set of selected parents that contain tags in that named selection.

A tag selection that is relative to a set of parent tags.

Time Ranges

All times are specified using the current time zone as set for your workstation. You do not need to calculate for UTC time values.

You can specify either a fixed time range with a defined beginning and end:

A sample fixed time range.

Or, you can specify a time range that is in some way relative to when the report is run. This option is more likely for reports that you save in order to run on a regular basis.

Three groups of preset relative time ranges are provided (Relative to now. Relative to the start of the day or week. Previous day or week.), with each group holding several options. You can select any of these to use as-in, modify one for your own purposes, or create your own.

The same tools are used both to edit and to create time ranges, therefore these notes will describe only the process of creating a new range.

  1. Select the "Create a new time range" tool.
    The Time Range panel opens

The time range creation tools

  2. Give the range a descriptive name.
  3. Using the three tools in the Relative time range section:
  4. Choose between Last, Current, or Previous
  5. Set the number of time units
  6. Set the size of the time units, ranging from minutes to years.
  7. Optionally, set an offset measured in seconds, into the range.
  8. If you chose "weeks" as the size of the time units, then you have the option of specifying the first day of the week. Sunday is the default.
  9. Select Save.
    The time range panel will close, returning you to the Tag History Query panel.

Query Attributes

Choose between calculated data and raw data (value property). If you select raw data, there are no other choices to make in this section. Note that raw data, even for a short time span, can require many rows.

There are more options for calculated data:

Default query attributes section of the Tag History Query panel

Use "Single value only" to run the selected calculations for all values in the time frame as a whole. For example, the average, minimum and maximum temperature values recorded yesterday. Or, you can repeat those calculations every X time units over the time frame. For example, hourly averages yesterday.

To display both, you could create a second query, located in a cell below the first, or you could use Excel tools to calculate a grand total.

The Calculation types selection tool allows you to choose as many as you like of:

  • Average
  • Minimum
  • Maximum
  • Total
  • Change in value
  • Value at start (snapshot)
  • Time of minimum
  • Time of maximum
  • Number of starts (zero to non-zero transitions)
  • Runtime (non-zero time)

Each selected calculation adds another column for each tag in the selection set. Columns are ordered first by tags, then by calculation for each tag.

Calculations are performed for data collected over a time span (the time per record). For example the average of an hour's data, or the maximum of a day's data. For calculated data, timestamps always indicate the start of each time span.

More Settings

The following options are available to refine your query:

  • By default, queries are limited to 10,000 records. You may adjust this number as required.
  • You may choose to include a timestamp column (not included when calculating a single value for the entire time range).
  • You may choose to sort by timestamp in descending order rather than the default of ascending (older later).
  • You may choose to include title row above the columns (default)
  • Format the cell data type according to the result returned rather than allowing Excel to choose. The add-in performs the following formatting:
    • converts timestamps to yyyy-mm-dd HH:mm:ss
    • converts values to integer or double depending on the tag type
    • converts Runtimes to HHH:mm:ss
  • To change this after running a report once, you may need to format the result cells as "general" before running the report again.
  • Adjust column widths to fit. Ensures that each tag title is fully displayed.
  • Flip rows and columns. Given cell A1 as the location for the query result, the default is to display titles in row 1 with data filling downward through the rows. Select this to place titles in Column A with data filling to the right through the columns.

Run (and refresh) your query

When ready, select the Run button. Output will go to the indicated row and column. After running once, the space required by the output is displayed and you have the option run the query again or to save.

Options after the first run of the query.

Your saved queries for the current workbook are available in the Tag History Queries panel. (The default panel opened by the History tool in the VTScada toolbar, and when none of the sub-panels used to generate a query are open.)

The panel with one query: "Starts and run time"

The default tool for each query is Refresh, as indicated by the circular arrow. If your workbook has more than one query, there will be a Refresh All tool.

Expand the menu to access other tools as shown. Of particular note is Find. This tool will select all the cells in the worksheet that are the result of a query.

Move a query result to a new location

Queries are tied to the cell and worksheet that was selected when you began the process of creating the query. To move the result to a new location:

  1. Refresh the query.
  2. Select the Find tool from the menu.
    The cells holding the query result will be selected on the worksheet.
  3. Cut those cells.
  4. Paste them to a new location on the worksheet.


Settings for the Excel Add-in

In addition to the following three options, the Settings menu is also where you will find a link to the About menu, where you can check the version number, the privacy policy and review a list of third-party software used by the add-in.

Select data range when editing a query.

When opening the edit query panel, automatically select the cells where the results of the query are located.

Deselect if you have typically have other cells selected and do not wish to have the selection area change.

Select data range when running a query.

When running a query by using the refresh button, this selects the cells where the results query are located.

Show welcome screen.

The welcome screen is shown automatically when the history query panel is first opened.


SQL Queries

You can generate reports of VTScada data using Structured Query Language (SQL) queries in third-party programs such as XLReporter™, Dream Report™, a REST or JODBC interface, Microsoft Access or Excel™. These queries are handled by VTScada's Remote Data Access feature, an optional component that must be purchased with your license agreement. An ODBC driver is provided free of charge, for installation on any workstation that is to send queries to your VTScada server.

A significant advantage of using ODBC is the ability to query VTScada from computers that do not have VTScada installed. Managers, engineers, operators and others can view up-to-date reports from any location that has network access to your VTScada server.

Using this interface, you can treat a VTScada application as if it were a relational database containing logged tag values, aggregate tag data, and alarm data. After the connection is configured, your reporting program can send SQL queries to VTScada to retrieve tag values that are being logged. (Tags that are not being logged have no stored history to query.)

VTScada stores history using only it's own proprietary format, which is not a relational database.
The SQL interface allows a limited subset of the SQL language to be used as if querying SQL tables.

Requirements:

  • If querying from another program, a license key that includes the Remote Data Access option is required. Check by clicking the License Management button in the VAM.
    VTScada modules that use the SQL functions need no special licensing.
  • Install the VTScada ODBC Driver on any computer that is to generate the queries. To do so, run the program VTScadaODBCDriverInstall.exe.
  • Secure your application, and grant the required data access privileges to at least one account. We recommend that a dedicated account be created for remote data access, possessing no other privileges.
    The privileges required depend on the level of access to be granted. Refer to the table later in this topic.
  • If you plan to query tag parameters, ensure that the account has the Tag Parameter View privilege.
  • If using Realm Filtering, A realm, in which the application has been selected.
  • A system DSN, configured using the Microsoft Windows™ ODBC Administrator program, or knowledge of the configuration so that you can build your own connection string.

The results of an SQL query are sorted by ASCII value as opposed to an alphabetical or lexicographical order.

Realm filtering (if configured) will limit the tags that can be queried within a realm. This may be useful to limit access due to security concerns or to avoid overwhelming your query viewer with an excessive number of tags.

Security and Remote Data Access

At a minimum, you will need access to a VTScada user account that has the Remote Data Access privilege. A common configuration is to create one or more accounts with only that privilege and one or more of the following privileges as required. Such a user will not have any access to the system other what is required to run reports.

For greater security, consider using one or more of the SQL View Tag, each of which can be assigned a custom privilege.
The Remote Tag Value / History Retrieve privilege is necessary in order to run custom SQL queries. Accounts with only the Remote Data Access privilege can see only their assigned SQL views or AlarmHistory, and cannot run their own SQL queries or browse the tag parameter tables.

Access to... | Requires the additional privilege...
The History table and time-based summary tables | Remote Data Access.
The Alarm history and time-based summary tables of the same. | Remote Data Access.
SQL View tables | Remote Data Access. Any custom privilege assigned to the view tag.
Control locks, tokens and token request tables. | Remote Data Access.
Tag parameter tables | Tag Parameter View
Other custom tables | Custom privileges specified when registering the table. (This feature is for advanced programmers.)


Configure an ODBC Server

To create an ODBC connection to your application (including REST and Java ODBC), at least one server must be configured as an ODBC server.Note to VTScada programmers: Configuration of an ODBC server is necessary for those making remote data connections to VTScada from third-party programs. It is not required for those writing SQLQuery statements in their VTScada modules. 1

The steps are much the same as those to set up VTScada Thin Client Server and Realm, with a few small exceptions. For example, the Max Clients setting has no effect in this context. That setting is relevant to thin client connections, rather than ODBC clients.

While this topic provides an overview of the steps required to configure your ODBC server, you are urged to refer to Thin Clients: Mobile and Internet, where the process is described in much more detail.

A security certificate is optional but strongly recommended. Internet Security (TLS, X.509, SSL)

  1. Ensure that your application is secured and that the account you will use for queries has the Remote Data Access privilege.
    (While testing the connection, it may be helpful to have the Thin Client privilege. Once configured, we recommend the use of an account that has few or no privileges other than Remote Data Access.
    The privilege, Remote Tag Value / History Retrieve, may be granted if users are allowed to browse the virtual tables.
    The Tag Parameter View privilege may be useful in some instances.)
  2. In the VTScada Application Manager (VAM), select Thin Client/Server Setup to open a dialog.

Adding a realm in the Thin Client/Server Setup dialog

  3. (This step is optional for intranet-only configurations. For Internet-connections, it is optional but strongly recommended).
    Open the Certificate tab and configure a security certificate according to the instructions in Internet Security (TLS, X.509, SSL).
  4. Open the Server Setup tab and add the name of your primary thin client server. (Define the Server Setup)
    If using a security certificate, this will match the name of the server listed there. Otherwise, it is likely the name of server where you are working.
  5. Open the Connection Addresses tab and define a default address list. (Define the Connection Addresses).
  6. Open the Realms tab and create a unique name for your ODBC connection, then add your application to that realm. Configure a Realm

The name should clearly indicate what the server is. As a suggestion: by including the letters "ODBC" you will make the name easier to recognize later when configuring the ODBC connection. If using Security Realms, your choice will be limited to realms created for that feature.

    Do not name any realm, "Rest" or "SQLQuery". Doing so will interfere with remote access to VTScada data.

  7. Save the new Realm

To check your configuration, give your account the Internet Client Access privilege and then test the connection using the Anywhere client. If you can connect that way, the steps you've just completed are correct.

The property, SoapServicesRealmName, is no longer used. If your technology relies on SOAP services, request a copy of the VTScada version 11.3 ODBC driver. As of version 12, we now use REST.

Optional Step:

(This is not required for queries. It is used only for convenience when using an external program that presents these summary tables as if they existed as real tables. You may query any TPP time frame without defining any value for SQLQueryTableTPPs)

You can take advantage of VTScada's ability to group data records by time interval. By adding the application property, SQLQueryTableTPPs, you can retrieve tag data from specific time intervals. The format of the statement is:

SQLQueryTableTPPs    =    <time frame specifier>

where the time frame specifier takes the form of a digit and a letter. The letter indicates the units in which time interval is measured (hours: h , weeks: w, etc.) and the digit specifies the number of units of each interval that should pass between each record.

Note that you can have only one TPP statement in a settings file, but that statement can have multiple values, separated by semi-colons and no spaces.

Two examples follow:

; two hours...
SQLQueryTableTPPs    =    2H

...or, using the Add Property dialog and configuring two TPP values:

Adding TPP values for aggregated reports

The available time interval units are:

  • MS - milliseconds
  • S - seconds (this is the default; the S may be omitted)
  • M - minutes
  • H - hours
  • D - days
  • W - weeks
  • Y - years

Connect to the ODBC Server

Any computer that has a network connection to the ODBC Server may connect. There is no need for VTScada to be installed on that computer, but the Trihedral-supplied ODBC Driver must be. On each computer that is to connect to the server, run VTScadaODBCDriverInstall.exe. This will install the ODBC driver needed to connect to the server.

Connection parameters must be supplied to the program that will run the query. This can be done using a data source name (DSN) configured using the Microsoft ODBC Data Source Administrator, or you may use an ODBC connection string.

If using an ODBC connection string, it will take the following generalized form. Note that none of the parameters are encrypted or hidden.

DRIVER=VTScada ODBC Driver;SERVER=Your_Server_Address;REALM=Your_Realm;UID=Account_Name;PWD=Password

If using a DSN, open the Microsoft ODBC Administrator utility on your computer. There will be two such utilities: one for 32-bit connections and one for 64-bit connections. A search for "ODBC" from the Windows Start button should find both. Choose based on the program you will be using to generate the queries. VTScada can work with either.

Open the System DSN tab of the Administrator utility and create a new connection, selecting the VTScada ODBC Driver.

Examples:

  • A configured DSN. The password cannot be viewed.

Example of a new DSN in the ODBC Admin tool

In the following examples, square brackets indicate text for you to replace. They are not part of the connection string.

  • Connection string for a secured application:
DRIVER=VTScada ODBC Driver;SERVER=123.456.123.456;REALM=[RealmName];UID=[Username];PWD=[Password]
  • Connection string for a realm configured to use a port other than the default 80, or to use a security certificate:
DRIVER=VTScada ODBC Driver;SERVER=[ServerAddress];REALM=[RealmName];UID=[Username];PWD=[Password];PORT=443;SSL=YES

Connection string that includes a five-minute timeout:

DRIVER=VTScada ODBC Driver;SERVER=[ServerAddress];REALM=[RealmName];QUERYTIMEOUT=300;UID=[UserName];PWD=[Password]

Notes:

  • The DSN name you enter should be as descriptive as possible. Be aware that long names might not save properly.
  • For the VTScada Server field, enter the fully qualified domain name of the machine running the VTScada application.
  • The port should match what was configured in VTScada for the Realm.
  • The SSL box is selected only if the VTScada Thin Client Server has been configured to use a security certificate. (Strongly recommended.)
  • Selecting 'Use Backup Servers' causes a list of VTScada Thin Client Servers to be retrieved from the VTScada ODBC server and stored, any time a successful connection is made. If future attempts to connect to this server fail, the list of VTScada Thin Client Servers will be tried one-by-one for a connection
  • Connection Timeout. Initially blank, defaults to 10 seconds. The connection timeout is how long the driver waits for a response from the target VTScada server. If the user application is making many concurrent queries then if the actual number of attempted concurrent connections through the driver instance exceeds the configured amount, then a new connection will be stalled until a connection "slot" becomes available. In such a case the user might need to increase the timeout or max. number of concurrent connections.
  • Queries that take longer than one minute to complete will time-out. If you have queries that need more time, you can set a value larger than 60 here.
  • Use the Max. concurrent connections option to adjust the limit of concurrent connections. If the application is running multiple long-running queries then increasing this number might reduce timeouts at a cost of increased resource usage on both the driver host and the target VTScada server. Simply increasing this number because a client is making lots of expensive queries will cause performance issues on the target VTScada server.

If security realms are enabled (NameSpaceDelimiter is set), then the username for ODBC queries should be configured for the realm. For example, if you have a security realm named "ODBC" and a NameSpaceDelimiter of ":", then you need a VTScada Thin Client Server realm named "ODBC" and a user account within the matching security realm, "ODBC:username".
If querying tag parameters, the account must have the Remote Data Access and Tag Parameter View privileges.

  • The Test Connection button should succeed if the application is running.

Troubleshooting:

If there is no connection, confirm that all the following are in place:

  • Server and Realm configuration completed on the VTScada server.
  • Security is active and the user account has the VTScada Thin Client privilege.
  • The querying workstation is able to connect to the server.
  • If using a DSN, you are using 32-bit or 64-bit as required by your querying program.
  • The connection string or DSN uses the correct names and addresses as configured on the Server.


Table Structure and Notes

Viewing: Develop > Log and Report > SQL Queries > Table Structure and Notes

Concepts:

SQL: Reference and Examples

Reference:

SQLDataQueryDriverMaxTagsPerQuery

SQLQueryHideLegacyTables

SQLQueryHistoryNoOverridesTableName

SQLQueryHistoryNoOverridesTableSupportsTPP

SQLQueryMaxResultRows

SQLQueryTableTPPs

Table Structure and Notes

VTScada stores history using only it's own proprietary format, which is not a relational database.
The SQL interface allows a limited subset of the SQL language to be used as if querying SQL tables.

The SQL interface exposes the following information for you to query. Fields for each "table" are described within this topic.

For greater security, consider using one or more of the SQL View Tag, each of which can be assigned a custom privilege.
The Remote Tag Value / History Retrieve privilege is necessary in order to run custom SQL queries. Accounts with only the Remote Data Access privilege can see only their assigned SQL views or AlarmHistory, and cannot run their own SQL queries or browse the tag parameter tables.

Alarms | The configuration of all alarms in your system
AlarmHistory | Provides a record of all alarm events at all priorities
ActiveAlarms | A table to retrieve active alarms
CurrentAlarms | A table to retrieve current alarms
DisabledAlarms | A table to retrieve disabled alarms
ShelvedAlarms | A table to retrieve shelved alarms
SuppressedAlarms | A table to retrieve suppressed alarms
UnackedAlarms | A table to retrieve unacked alarms
ControlLocks | A table to retrieve control locks
ControlTokens | A table to retrieve control tokens
ControlTokenRequests | A table to retrieve control token requests
History | All data collected from tags that have loggers built-in or attached. (Notebook values are retrieved in their encrypted form. There is no method to decrypt notes during retrieval.
History_TPPvalue | Summary values over a defined period of time. There can be multiple iterations of the defined time period within the bounds of the query.
TagTypes | A list of all VTScada tag types, noting which are present in this application.
Parm_TagTypeName | A list of all parameters defined for a given tag type. Substitute the name of the tag type for "TagTypeName".
Parm_AllTypes | Similar to Parms_TagTypeName but the fields of this table are the combined parameters of all tag types. Furthermore, the available fields for these tables have been extended to include not just tag parameters, but also extra information such as TagType, UniqueID, ShortName, Value (i.e. the current value of the tag), DisplayAddress (i.e. the address parm as it appears in the Tag Browser), NChildren (i.e. the number of immediate children under the tag). The extra non-parm columns are specified by the SQLTagParmExtraColumns setting
Parms_GroupName | Like Parms_AllTypes, you can also query on specific tag groups. For example, groups such as "Inputs" and "Container" can be accessed via tables such as Parms_Inputs and Parms_Container. The fields of these tables are the combined parameters of all tag types in the group.
TagGroups | A list of all the tag groups defined in VTScada
TagGroupMembers | A list of all tags that belong to a specified tag group.
TagLoggedFields | A list of all fields logged for a specified tag type.

Since version 11.1, VTScada stores all data using UTC timestamps. This ensures that time zone and daylight savings time boundaries have no effect on data storage. Your queries will need to take this into account.

For queries against the table, History, you can query two available time stamp values:

  • Timestamp - The time reported by the I/O device. If a time stamp is not provided with the value, then the time at which the value was read or calculated will be used.
    This value is indexed, and should be used in all WHERE clauses.
  • StorageTimestamp - The time when the value was written by the Historian.
    This value is not indexed and should not be used in a WHERE clause. Doing so may result in a very slow query response time. StorageTimestamp is not available to be queried in the derivative, data-aggregated :TPP tables.

Prior to release 11.1 of VTScada, tag data was stored in a separate table for each tag, using the server's time rather than UTC. These legacy tables may still be viewed if the application property SQLQueryHideLegacyTables is set to 0.

In applications with more than 10000 tags of any type, you may need to adjust the limits for ODBC query results. Large result sets may take time to retrieve.

To view tag parameter information, the account used to make the query must have the Tag Parameter View privilege. Any tags that are not available to that account due security privileges or Realm-Area Filtering will not be included in the query result. Disabled tags are not returned by the query.

You are strongly advised to include a time range in the where clause of every query. The BETWEEN clause is recommended.

Result sets are limited to 64 columns. Use care if attempting to do a SELECT * query.

Querying Value Attributes

Version 12 of VTScada introduced value attributes. These can be queried using "Value!" rather than "Value" for the field name or array of field names. Value! stores bitwise values according the following table.

Attributes flagged with a star (*) apply only if the I/O tag is attached to a DNP3 driver or a custom driver supporting this feature.

Refer to the constant, #NUM_DATA_ATTR_BITS, to discover the number of bits in data attributes for your version of VTScada.

Bit Number | Defined Constant Name | Meaning
0 | #DATA_ATTR_MANUAL_DATA | The value was from the tag's ManualData parameter
1 | #DATA_ATTR_MANUAL_ENTRY | The value was manually entered
2 | #DATA_ATTR_EDITED_DATA | The historical value was manually edited
3 | #DATA_ATTR_QUESTIONABLE | The tag was marked as questionable
4 | #DATA_ATTR_STALE_DATA | The value was reported as stale by VTSDriver
5 | #DATA_ATTR_IMPORTED | The value was imported from a CSV file
6 | #DATA_ATTR_COMMFAIL | The driver experienced a comm failure
7 | #DATA_ATTR_QUALITY | The tag has marked the value as unreliable
8 | #DATA_ATTR_DRIVER_COMMFAIL | The PLC reported a downstream comm failure
9 | #DATA_ATTR_DRIVER_QUALITY | The PLC reported the value may be unreliable
10 | #DATA_ATTR_DRIVER_OVERRIDDEN | (*) The PLC reported the value was overridden
11 | #DATA_ATTR_DRIVER_NODATA | (*) The PLC reported there is no data available

Alarms table

Contains all configured alarms.

Column name | Data Type | Description
ID | Text | Unique ID of the alarm
Name | Text | Name of the alarm
Area | Text | The area the alarm belongs to
Description | Text | Description from the alarms table or the alarm
Status | Text | Text description of alarm status
Active | Integer | 0 for inactive, 1 for active
Disabled | Integer | 0 if enabled, 1 if disabled
Shelved | Integer | 0 if unshelved, 1 if shelved
Suppressed | Integer | 0 if unsuppressed, 1 if suppressed
Unacked | Integer | 1 if unacknowledged, 0 if acknowledged
PriorityNum | Integer | Priority attached to alarm (numeric, not text)
Priority | Text | Priority attached to alarm (text, not numeric)
Units | Text | Units attached to alarm
Setpoint | Double | Setpoint attached to alarm
SetpointLabel | Text | Setpoint label attached to alarm
Custom | Text | A customizable variable that is JSON encoded if it is not plain text
AlarmDatabase | Text | Name of the Alarm Database

The following columns have been deprecated from the Alarms table: Message, SubName, and HookPointUnits.
Description may serve as an alternative to message.
The SubName can be found at the end of the ID after ":#:"
Units replaces HookPointUnits.

Alarm Status Tables

Tables containing records of configured alarms of a specific status. These records are retrieved from the alarms table.

  • ActiveAlarms
  • CurrentAlarms
  • DisabledAlarms
  • ShelvedAlarms
  • SuppressedAlarms
  • UnackedAlarms

The table will contain the following columns.

Column Name | Data Type | Description
Timestamp | Date/Time | Alarm timestamp (UTC)
DateTime | Text | Date and time
ExpiryTime | Date/Time | The expiry time of shelved alarms
ID | Text | unique ID for the event
Name | Text | Alarm Name
Area | Text | Alarm tag area
Description | Text | Alarm tag description
Status | Text | Alarm status
Active | Integer | 0 for inactive, 1 for active
Disabled | Integer | 0 if enabled, 1 if disabled
Shelved | Integer | 0 if unshelved, 1 if shelved
Suppressed | Integer | 0 if unsuppressed, 1 if suppressed
Unacked | Integer | 1 if unacknowledged, 0 if acknowledged
PriorityNum | Integer | Numeric value of the alarm priority.
Priority | Text | Priority of the alarm (as text, not numeric)
Units | Text | Phrase key of setpoint units
Value | Double | Tag value
Setpoint | Double | Setpoint of alarm evaluation
SetpointLabel | Text | Label to display instead of setpoint
ValueLabel | Text | Label to display instead of value
Custom | Text | Information that can be retrieved by querying for the custom column. The response is JSON encoded if the data is not plain text.
AlarmDatabase | Text | Name of the Alarm Database

The following columns have been deprecated from the AlarmStatus table: Message, SubName, HookPointValue, and HookPointUnits.
Description may serve as an adequate alternative to Message.
The Alarm SubName can be found at the end of the ID after ":#:".
HookPointValue has become ValueLabel.
HookPointUnits has become Units.

Please note:

  • The ExpiryTime will only have a value for Shelved Alarms.
  • Only the DisabledAlarms table can show the Active and Unacked status of Disabled alarms.
  • Only the SuppressedAlarms table can show the Active and Unacked status of a suppressed alarm.
  • Only ShelvedAlarms can show the Active and Unacked status of shelved alarms.

AlarmHistory table

Contains a record of all alarms that have occurred in the application, including event alarms for operator actions.

Column Name | Data Type | Description
Timestamp | Date/Time | Alarm timestamp (UTC)
DateTime | Text | Date and time
ID | Text | unique ID for the event
Name | Text | Alarm Name
Area | Text | Alarm tag area
Description | Text | The alarm description
Event | Text | Text description of the alarm event. (e.g. Enabled, Acknowledged, Cleared, Event, etc.)
PriorityNum | Integer | Numeric value of the alarm priority.
Priority | Text | Priority of the alarm (as text, not numeric)
Units | Text | Unit associated with the value of the alarming or event tag
Value | Double | Tag value
Setpoint | Double | Setpoint of alarm evaluation
SetpointLabel | Text | Label to display instead of setpoint
ValueLabel | Text | Label to display instead of value
User | Text | (formerly Operator) account signed in when alarm originated
Workstation | Text | workstation from which alarm originated
Device | Text | Name of the client device
Custom | Text | Information that can be retrieved by querying for the custom column. The response is JSON encoded if the data is not plain text.
AlarmDatabase | Text | Name of the Alarm Database

The following columns have been deprecated from the AlarmHistory table: Message, SubName, HookPointValue, HookPointUnits and Operator.
Description may serve as an adequate alternative to Message.
The Alarm SubName can be found at the end of the ID after ":#:".
HookPointValue has become ValueLabel.
HookPointUnits has become Units.
Operator has become User.

Locks And Tokens Tables

Tables containing a record of all configured locks, tokens and token requests can be queried as follows:

  • ControlLocks
  • ControlTokens
  • ControlTokenRequests

Locks and Tokens tables will contain the following columns:

Column Name | Data Type | Description
Timestamp (UTC) | Date/Time | Alarm timestamp (UTC)
DateTime | Text | Date and time
ID | Text | Unique ID for the event
Name | Text | Tag name
Area | Text | Tag area
Description | Text | Tag description
Level | Integer | Lock/token level
User | Text | The account signed in when alarm originated
AlarmDatabase | Text | Name of the Alarm Database

TagTypes table

A list of all tag types that are defined in the application. Those for which instances exist are flagged with a 1 in the InUse column.

Column Name | Data Type | Description
TagType | Text | The name of a tag type. (example: ABDriver)
Label | Text | The displayed label for the type. (Allen Bradley DF1 Compatible PLC/RTU)
InUse | Numeric | Boolean indication of whether the application includes instances of this type

Example:

Select * from TagTypes

History table

Contains time stamps, values from all logged tags and recorded statistics from each driver tag in your application. Column names will vary according to tag type.

The history table supports pagination when using REST SQL queries if the number of rows to retrieve exceeds the setting SQLQueryMaxResultRows

Data column names will be the full name of each tag, with the name of the logged property appended. For most I/O tags, this suffix will be ":value".

Column Name | Data Type | Description
Timestamp | Date/Time | The UTC time reported by the I/O device. If a time stamp is not provided with the value, then the time at which the value was read or calculated will be used. This value is indexed, and should be used in all WHERE clauses.
StorageTimestamp | Date/Time | The UTC time when the value was written by the Historian. This value is not indexed and should not be used in a WHERE clause. Doing so may result in a very slow query response time. StorageTimestamp is not available to be queried in the derivative, data-aggregated :TPP tables.
Tagname:Value | Varies | Usually numeric, with exceptions such as for String I/O tags.
Drivername:ErrorValue | Numeric | Only for driver tags. An error value or code associated with a driver's communication error.
Drivername:FailedCount | Numeric | Only for driver tags. Incrementd on each communication error.
Drivername:FailedRetryCount | Numeric | Only for driver tags. Incremented if failure occurs on a retry. Drivers will usually retry more than once before designating an error to be an "error on retry". Thus, this count will always be less than or equal to the FailedCount.
Drivername:SuccessCount | Numeric | Only for driver tags. Count for successful reads and writes, incremented on each successful operation.
Drivername:Quality | Numeric | Only for driver tags. A mathematically derived indication of communication error rates. Used to show the driver's overall "health".
Drivername:ResponseTime | Numeric | Only for driver tags. The time it takes the PLC/RTU to receive a command, process it and send a response.
Drivername:ErrorAddress | Text | Only for driver tags. If an address was associated with the error, it will be recorded here.
<<Other>> | Varies | Placeholder in this table for columns that may be available for some but not all tags. Query the TagLoggedFields table for the tag type in which you are interested.

Example:

SELECT 'Station 1\PLC1\Level:value', Timestamp FROM History ORDER BY Timestamp DESC LIMIT 10

If your query includes two or more tag names, the result set will be sparse if viewed as a table. For any given timestamp, it is likely that there will be only one logged tag value. Other tag values are marked as "null" for that timestamp. In this case, there is no way to distinguish between values that were not logged at a given time, and values that were logged as null.

Tag value attributes cannot be queried.

Multiple Values per Time Stamp

In most situations, if there are multiple values from one tag with the same time stamp, it is because duplicates were recorded, or values edited ( Edit Data). VTScada will store all the values (each with its own sequence ID), but a query will return only the one with the largest sequence ID.

There are situations where different events can be logged to the same tag with an identical timestamp as provided by the I/O device. If this matches your situation, you can tell VTScada to return all the values for that timestamp by adding the property, SQLQueryHistoryNoOverridesTableName to your list of application properties and setting the value to a name you wish to use for the table in your queries.

If using this option, it usually will not make sense to query TPP values other than minimums or maximums. Add the property SQLQueryHistoryNoOverridesTableSupportsTPP as well, setting the value to FALSE to explicitly deny TTP value queries when retrieving duplicates.

Adding the No Overrides property

History_TPPvalue tables

The standard GetTagHistory Modes (Average, Minimum, Maximum, etc.) can be used to retrieve data aggregations over defined time periods referred to as TPP values.

Values that appear to come from a History_TPP table are calculated in response to your queries.

Use care to avoid querying a time span that extends into the future. The last known value will be projected for all time periods after the current date. Your query must provide both a start time and an end time.

Four default values for TPP are specified in the application property SQLQueryTableTPPs, but this is a legacy setting. Your query can be for any TPP value. For example, you may query from the History_15m even though it is not specified in the SQLQueryTableTPPs property.

Example table names: History_1M, History_1H

For each logged tag in the application, and for the recorded statistics of every driver, this table will contain a column named after the tag and having a suffix identifying the statistic calculated for each time period.

Column name showing suffix | Data type | Description
Timestamp | Date/Time | UTC date and time at the beginning of each time span
Tag Name:Value:Average | Double | Average value within each time span
Tag Name:Value:Minimum | Double | Minimum value recorded in the time span
Tag Name:Value:Maximum | Double | Maximum value recorded in the time span
Tag Name:Value:Delta | Double | Change in value during the time span
Tag Name:Value:ValueAtStart | Double | Value at the beginning of the time span
Tag Name:Value:TimeOfMin | Date/Time | Time of the minimum value recorded in the range
Tag Name:Value:TimeOfMax | Date/Time | Time of the maximum value recorded in the range
Tag Name:Value:ZToNZCount | Long | Count of zero to non-zero transitions during the span
Tag Name:Value:NonZeroTime | Double | Total time within the span that the value is not zero or invalid
Tag Name:Value:Total | Double | Arithmetic sum of the recorded values in the time span
Tag Name:Value:Interpolated | Double | A value interpolated across a range of time spans.
Tag Name:Value:BitwiseOR | Long | A summary of all bits set in any of the values of the range.
Tag Name:Value:BitwiseAND | Long | A summary of any bits set in every value of the range
Tag Name:Value:ValueAtEnd | Double | Value at the end of the time span

Parms_TagTypeName table

There is one table for each tag type. Column names within the tables match the names of each configuration parameter and rows contain the current value of that parameter for each tag at the time of the query. In the case of parameters that are set by expression, the value at the time of the query is returned, not the text of the expression. Relative tag references will resolve to the tag name. Parameters that are phrases will be converted based on the language configured for the user making the request. Note that parameters marked as encrypted in custom tags will be revealed by the query.

The account used to make the query must have the Tag Parameter View privilege. Any tags that are not available to that account due security privileges or Realm-Area Filtering will not be included in the query result. Disabled tags are not returned by the query.

If a new type is created, it is immediately available to queries. Custom types that are removed will remain available to the query until the next application restart.

See Tag Names in Code or query the TagTypes table for a list of type names.

Column Name | Data Type | Data Source | Description
Name | text | parameter | Tag name
Area | text | parameter | Tag area
Description | text | parameter | Tag description
... |  | parameter | Other tag parameters specific to the tag type
TagType | text | extra field | Name of tag type
TagTypeLabel | text | extra field | Friendly tag type label
UniqueID | text | extra field | Tag's unique identifier
<etc> | text | extra field | <fill in the rest of the extra fields defined in SQLTagParmExtraColumns

Examples:

Select * from Parms_AnalogStatus
Select * from Parms_DigitalStatus

The following query will fail: Select * from Parms_IO. Result sets are limited to 64 columns and the parameter count of the IO tag exceeds this number. Use the following query instead: GET COLUMNS Parms_IO
The available GET queries are listed in SQL: Reference and Examples

TagGroupMembers table

All tags are members of one or more groups; Analogs, Digitals, Containers, etc.

This table contains a list of all tag types and their matching group name. TagGroup names repeat, with an entry for each matching TagType name.

Column Name | Data Type | Description
TagGroup | Text | The name of a tag group. (example: Analogs)
TagType | Text | The name of a type that is a member of a matching group.

TagGroups table

All tags are members of one or more groups; Analogs, Digitals, Containers, etc.

This table contains a list of all the tag group names.

Column Name | Data Type | Description
TagGroup | Text | The name of a tag group. (example: Analogs)
Label | Text | How that group name is displayed in the VTScada user interface.

Example:

SELECT * FROM TagGroups

TagLoggedFields table

For most tags, the logged field is named Value, but this is not true of all tags. For example, every driver has seven logged fields as described in Communication Driver Log-Enabled Variables.

Column Name | Data Type | Description
TagType | Text | The name (not the label) of a tag type. Repeats for types that have more than one logged field. See the TagTypes table or Tag Names in Code
LoggedField | Text | The name of the field logged for that type.

Example:

Select * from TagLoggedFields where TagType = 'IO'


SQL: Reference and Examples

Viewing: Develop > Log and Report > SQL Queries > SQL: Reference and Examples

Concepts:

Table Structure and Notes

Reference:

SQLDataQueryDriverMaxTagsPerQuery

SQLQueryHideLegacyTables

SQLQueryHistoryNoOverridesTableName

SQLQueryHistoryNoOverridesTableSupportsTPP

SQLQueryMaxResultRows

SQLQueryTableTPPs

SQL: Reference and Examples

Read the following warnings before writing your queries. These may affect your ability to obtain the results you want.

Limit on result set size

The size of the result set is limited by the application property, SQLQueryMaxResultRows (default 10000) and SQLQueryMaxResultCells (default 1000000). The size of the result set is calculated using the following rules:

  • The number of rows that will be returned is the smaller one between SQLQueryMaxResultRows and the number calculated by SQLQueryMaxResultCells.
  • When calculating the number of columns in the query, all columns in the WHERE and ORDER BY clause are included. The Timestamp column is excluded.

If you are changing SQLQueryMaxResultRows and SQLQueryMaxResultCells to be higher than their default values and are using a WHERE clause that filters on something other than time ranges, you may also need to increase SQLQueryMaxResultRowsPreFilter and SQLQueryMaxResultCellsPreFilter.

  • SQLQueryMaxResultRowsPreFilter specifies the maximum number of records that can exist in memory before the WHERE filter is applied. Defaults to 1000000.
  • SQLQueryMaxResultCellsPreFilter specifies the maximum number of the cells, which is the number of rows times the number of columns, that can exist in memory before the WHERE filter is applied. Defaults to 10000000.

You are strongly advised to use a time range having both a start date and end date in every query. Doing otherwise may take excessive time and return an extremely large Data Set.

The property, SQLQueryParserDepthLimit, limits how deeply nested a recursive query can be. You may increase this value above the default of 300 but do so with caution. An high number of recursions can consume resources to the point of causing a crash.

Limit on the number of columns returned

A maximum of 64 columns will be returned in any query. This cannot be changed.

All data is stored with UTC timestamps

Your query must adjust for local time. If you are located in GMT -4 then data recorded at 8am in your local time zone (08:00:00) was stored as being recorded at noon GMT (12:00:00).

Results are sorted based on ASCII value

As opposed to alphabetically or lexicographically. The results may resemble alphabetical order with some differences such as uppercase and lowercase being ranked separately.

Table names with spaces, etc.

Wrap table names in single quotation marks so that full tag names, which may include spaces and backslashes, are treated as a single name. For example: SELECT 'Station 1\PLC1\Level:value', Timestamp FROM History ORDER BY Timestamp DESC LIMIT 10

History_TPP tables will not report an error if queried for a time span that extends into the future.

If querying a History_TPP table with a time span that extends into the future, the last known value will be carried forward.

For greater security, consider using one or more of the SQL View Tag, each of which can be assigned a custom privilege.
The Remote Tag Value / History Retrieve privilege is necessary in order to run custom SQL queries. Accounts with only the Remote Data Access privilege can see only their assigned SQL views or AlarmHistory, and cannot run their own SQL queries or browse the tag parameter tables.

GET queries

When querying a relational database using SQL, all queries begin with SELECT. But you are querying VTScada's proprietary data storage system, using an interface that simulates a subset of SQL. In addition to SELECT, the following queries are supported:

GET TABLES

Returns all table names in the data store.

GET COLUMNS table-name

Returns a description of each column of the specified table.

GET PRIMARY_KEYS table-name

Returns the primary key of the specified table.

Supported SQL syntax follows the format:

SELECT [DISTINCT | ALL] 'columnspecifier-1', 'columnspecifier-2', ...

FROM 'tablename-1', 'tablename-2'

[WHERE where-expression]

[ORDER BY 'columnspecifier-1' [ASC | DESC], 'columnspecifier-2'...]

[LIMIT [offset, ] row_count]

For the above ...

  • Where the column specifier refers to a tag's value, it must include the full tag name with the suffix, ":value".
  • In the alarm tables and the TPP tables, you may use a * to indicate all columns, but you cannot use it as a wildcard to select columns having a common root.
  • Column name aliases may be used in the SELECT clause to make the result more readable, but they are not supported in the WHERE clause. All column names in WHERE clauses must be fully specified.
  • The table name is either the table name or 'table-name AS alias-name'. Quotes may be used around table or column names, and must be used if the names contain special characters such as a space or colon.
  • When a table-alias name is specified it may be used in place of the table-name in the column specifier. Table names are only required in the column specifier when querying multiple tables.
  • The WHERE expression filters the data that will be retrieved by the query. Refer to the following table for functions and operators that may be used in the WHERE expression.
  • ORDER BY uses a simple binary sort rather than a linguistic sort. This may produce unexpected ordering in some situations. For example, "1" has code 49 and "\" has code 92, therefore "RTU1\" will come before "RTU\" in an ascending sort.
  • Use the limit clause to restrict the number of rows that will be returned, and optionally add an offset (0-based), which allows pagination. LIMIT is applied after WHERE filtering and after sorting. If there is no explicit LIMIT clause in the query there is an implicit "LIMIT SQLQueryMaxResultRows" (Settings.Dynamic setting) added.

When more than one table is specified, the tables are automatically joined based on their Timestamp columns and must have matching time periods.

A JOIN expression may be used in place of a table list, but it is only parsed to extract the tables specified. VTScada's implementation of SQL does not support JOIN operations.

Functions, Operators and Expressions

Only WHERE clauses may use functions, operators and expressions. In the SELECT clause, mathematic operators will be ignored and functions will return a "column not found" error.

Entries in the following table are grouped in order of decreasing precedence, where entries in each group have the same level.

Operator, function or keyword | Description
First Level
() | Use parenthesis to enclose the parameters of a function and to group expressions, thereby controlling the precedence of operations.
Constant (including sign) | Any constant value to which you are comparing a field.
Column Reference | Tag name and logged property. WHERE 'Tank1Level:Value' > 10
Second Level
ABS | Absolute value function.
CASE | The CASE statement is a standard SQL command, but in VTScada only the following form is supported: CASE WHEN condition THEN result1 ELSE result2 END
CONCAT | String concatenation. Limited to two parameters. WHERE CONCAT(Area, Operator) = "Western zoneFred"
INTEGER | Function to truncate a numeric value to the integer portion. WHERE INTEGER('TankLevel:Average:Value' / 'TankVolume:Average:Value') > 50
LENGTH | Function to count the number of characters in a field. WHERE LENGTH(HookPointUnits) > 5
LOWER | Function to convert a string value to lowercase letters. WHERE LOWER(Area) = "water tower"
SQRT | Function to calculate the square root.
UPPER | Function to convert a string value to uppercase letters. WHERE UPPER(Area) = "WATER TOWER"
Unary + and - | Use the positive or negative sign before the value that is to be incremented or decremented by one.
Third Level
* | Multiplication operator.
/ | Division operator.
% | Modulus division operator.
Fourth Level
+ and - | Regular addition and subtraction operators.
Fifth Level of Precedence
> | Greater than comparison operator.
>= | Greater than or equal to comparison operator.
< | Less than comparison operator.
<= | Less than or equal to comparison operator.
BETWEEN ... AND ... | Example: WHERE x BETWEEN y AND z. Functionally equivalent to WHERE x >= y and x < z
= | Equivalency comparison operator. Note that any comparison to NULL will return NULL, or false. Use IS NULL or IS NOT NULL instead.
!= and <> | Not equal comparison operator.
IS NULL | Do a test for a null value. WHERE 'Tagname:value' IS NULL When communication fails, VTScada will record one null (Invalid) for the tag's value at the time of failure.
IS NOT NULL | Test for a value that is not null. WHERE 'Tagname:value' IS NOT NULL
LIKE | Test for a value that includes a wildcard. Wildcards may be either: % (equivalent to the VTScada *) or _ (equivalent to the VTScada ?) You may use the ESCAPE operator to do a LIKE search that includes the literal character % or _.
Sixth Level
NOT | Negation clause for comparisons.
Seventh Level
AND | Both clauses must be true in order for a true response to be true.
Eighth Level
OR | Either clause must be true in order for a true response.

Remember that the Timestamp in all tables is stored using UTC. You will need to adjust the time in your query for your time zone and possibly for daylight savings time.
In legacy tables (created prior to version 11.1) the timestamp column used the server's local time zone.

Example 1:

To retrieve error values from a driver called ModDriver1, recorded during a particular one-minute period and adjusted for UTC time.

SELECT Timestamp, 'ModDriver1:ErrorValue' from History
WHERE Timestamp BETWEEN '2014-03-01 16:54:00' AND '2014-03-01 16:55:00'

Example 2:

To retrieve several driver statistics from a driver named ModDriver1, during a day, using a TPP of 1 minute: This query is being run in the Eastern Standard time zone (GMT - 5), during standard time.

SELECT Timestamp, 'ModDriver1:ErrorValue:Average', 'ModDriver1:ErrorValue:ValueAtStart,
'ModDriver1:Quality:Average, 'ModDriver1:Quality:ValueAtStart' from History_1M
WHERE Timestamp BETWEEN '2014-03-01 05:00:00' AND '2014-03-02 05:00:00'

Example 2:

To retrieve weekly minimum values from two Analog Input tags called ai1 and ai2 during November 2013, sorted with most recent values first: (Given a SQLQueryTableTPPs property that includes the 1W flag.) This query is being run in Greenwich, England.

SELECT Timestamp,
'ai1:Value:Minimum' AS ai1Min,
"ai2:Value:Minimum' AS ai2Min FROM History_1W
WHERE Timestamp BETWEEN '2013-11-01' AND '2013-11-30'
ORDER BY Timestamp DESC

This will return a result set with columns Timestamp, ai1Min, and ai2Min.

Example 3:

To select all the values recoded by a tag named Tank1Level for one hour on April 1 2008.

SELECT Timestamp, Tank1Level:Value
FROM History
WHERE Timestamp BETWEEN '2008-04-01 13:00:00' AND '2008-04-01 14:00:00'

or

SELECT Timestamp, Tank1Level:StorageTimeStamp, Tank1Level:Value
FROM History
WHERE Timestamp BETWEEN '2008-04-01 13:00:00' AND '2008-04-01 14:00:00'

Example 4:

To retrieve a list of all active alarms:

SELECT Name, Priority
FROM   Alarms
WHERE  Active = 1

Example 5:

To retrieve the names of all disabled alarms in the area "MyArea":

SELECT  Name
FROM    Alarms
WHERE   Disabled = 1 and Area = 'MyArea'

Example 6:

To retrieve all events associated with the operator, Bob, on April 10, 2008. This query is being run in the Eastern Standard time zone (GMT - 5), during standard time.

SELECT Timestamp, Name, SubName, Event
FROM   AlarmHistory
WHERE  Timestamp >= '2008-04-11 5:00:00' AND Timestamp < '2008-04-12 5:00:00'
       AND Operator = "Bob"

Example 7:

To find the names of Analog Status tags with an area beginning with 'Plant', followed by anything.

SELECT Name
FROM   Parms_AnalogStatus
WHERE  Area LIKE 'Plant%'

Example 8:

To find the names of Analog Status tags with an area beginning with 'Plant ', followed by a single character. (Plant 1, Plant 2, but not Plant1)

SELECT Name
FROM   Parms_AnalogStatus
WHERE  Area LIKE 'Plant _'

Example 9:

To find the names of Analog Status tags with an area beginning with 'Plant_', followed by anything. The underscore must be escaped so that it is not treated as a wildcard.

SELECT Name
FROM   Parms_AnalogStatus
WHERE  Area LIKE 'Plant~_%' ESCAPE '~'


REST Queries - Notes & Examples

REST stands for REpresentational State Transfer. It allows web applications to query data using either HTTP GET or POST requests, and a subset of SQL. Results are returned in the JSON format of name and value pairs. Result sets are limited in size and pagination codes are used to allow you to retrieve subsequent portions of data returned from the original query. This greatly reduces the time required if querying a large Data Set.

Information is returned as a (potentially large) set of name / value pairs, suitable for a application that can process JSON data. It is up to you to create that application in order to organize and format the results. Part of this should include a convenient user-interface to build the queries and to request the next page of a large Data Set.

The pagination is supported only when retrieving historical data from the History table, the custom table name set by \SQLQueryHistoryNoOverridesTableName, and the History TPP tables.

Retrieving alarm history doesn’t support pagination.

Given a VTScada server configured for ODBC (Configure an ODBC Server) and a user account that has the Remote Data privilege plus other privileges as described inSecurity and Remote Data Access, you can query data using a URL in the following form:

https://Your.ServerName.com/RealmName/REST/SQLQuery?query=Select Something...

(Example assumes that you have configured security as recommended in Internet Security (TLS, X.509, SSL) Use "http://" otherwise.)

Do not name any realm, "Rest" or "SQLQuery". Doing so will interfere with remote access to VTScada data.

Examples of several common queries are provided in the file REST Interface Demo.html, distributed with your copy of VTScada. Assuming that you installed to C:\VTScada, you will find the file within the folder: C:\VTScada\Examples\REST Interface Example.
To use the examples file, you must have an application configured for Remote Data Access and a user account in that application with the Remote Data privilege. Full instructions are provided within the HTML file.

For greater security, consider using one or more of the SQL View Tag, each of which can be assigned a custom privilege.
The Remote Tag Value / History Retrieve privilege is necessary in order to run custom SQL queries. Accounts with only the Remote Data Access privilege can see only their assigned SQL views or AlarmHistory, and cannot run their own SQL queries or browse the tag parameter tables.

For GET requests, the query parameter should always be fully URL encoded. For example, '%' must be encoded as '%25', and spaces should be escaped as '+' or '%20'. This applies to all special characters. (Further information is available at https://en.wikipedia.org/wiki/URL_encoding and https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding)

If using JavaScript you might do this with encodeURIComponent:

const encodedQuery = encodeURIComponent("GET Tables");

If using .NET, you might do this with URLEncode:

System.Web.HTTPUtility.URLEncode

Notes for using POST requests

For POST requests, the query parameter should never be URL encoded.

If using POST requests, the body of the request cannot be empty and must be a JSON encoded string that contains the query and an optional pageToken parameter. The pageToken parameter may be empty if not using pagination. For example:

       {
         "parameters":{
           "query": "...",
           "pageToken": "..."
         }
       }

The only accepted "Content-Type" header value is "application/json".

Samples of queries are provided in SQL: Reference and Examples.

Limitations

The default limit for the POST request body size is 32768 bytes (32KB), which is same as the limit for GET requests. You can send POST requests longer than 32KB by adjusting the setting SQLQueryMaxRequestLength in SETUP.INI.

By default, a maximum of 64 columns and 10,000 rows will be returned, and a pagination token added to the return structure if there are more rows available. You can disable pagination by setting the property SQLPaginationEnabled to 0 (FALSE).

If your query uses the wildcard "Select * from...", it is likely that the interface will return an error message due to the result containing more than 64 columns, unless the application has very few tags.

URL encoding will be required for some characters. An example follows.

When making queries with GET requests, if your query includes a LIKE clause you must encode the % wildcard character as %25. For example:

...WHERE Area LIKE 'East%'

Will fail because the browser will not encode the % properly. Instead, use:

...WHERE Area LIKE 'East%25'

Returned data

Examples in this discussion use data returned from the following query:

select timestamp,'Station 1\PLC1\Level:value' from history

would be placed in the URL and encoded as follows:

.../REST/SQLQuery?query=select%20timestamp%2C'Station%201%5CPLC1%5CLevel%3Avalue'%20from%20history

Header

The header describes the names and types of the returned data. Values follow immediately after. For the query shown, this will look like the following. Note that timestamps are always returned as UTC values.

{"results":{"fieldNames":["timestamp","Station 1\\PLC1\\Level:value"],
"fieldTypeNames":["TIMESTAMP","DOUBLE"],"values":[[1562084981.054,12.603042138914],
[1562085057.977,12.503052503053], ...

Body

The body of the returned data consists of the comma-separated values of the returned data where each record is enclosed in square brackets. Two records are shown in the preceding example.

Footer

The footer provides summary information describing the query including error messages, number of results and a timestamp describing when the data was retrieved. If more data is available, a page token is included in the footer as shown in this example:

"returnCode":0,"errorMessage":null,"nextPageToken":"eyJ0aW1lc3RhbXAiOjE1NjIwODg3NDUuNDQxLCJudW1SZXRya
WV2ZWQiOjEwMDAsIm51bVJlc3VsdHMiOjEwMDAsIm9mZnNldCI6MCwiZmlyc3RUaW1lc3RhbXAiOm51bGx9","paginationStats":
{"numRetrieved":1000,"numResults":1000,"timestampRetrieved":1562088735.43}}

Retrieve the next page

To continue pulling data from a query, resubmit the same query with the page token. Note that the URL parameter for the token takes the form, "PageToken" rather than the name used in the footer of "nextPageToken". For example:

.../REST/SQLQuery?query=select%20timestamp%2C'Station%201%5CPLC1%5CLevel%3Avalue'%20from%20history&PageToken=eyJ ...

REST Interface Authentication

Two authentication methods are supported by the REST interface. Regardless of the header used, the credentials must be sent in every request made to VTScada's REST interface.

1. The custom X-VTScadaAuth header. This exists as an alternative to the Authorization header to prevent browsers from retaining and automatically sending credentials, as can happen with the Authorization header. The value of this header follows the format of the HTTP basic authentication header where the header value is calculated by Base64-encoding the username followed by ":", which is in turn followed by the password. This method is recommended when queries are being made from a web browser. (See the following caution note.)

In VTScada script code this can be constructed as follows:

    HeaderValue = Base64Encoder(Concat(Username, ":", Password));
    Header = Concat("X-VTScadaAuth: ", HeaderValue);

2. HTTP basic authentication which uses the Authorization HTTP header. While this is widely supported by third party platforms and tools it should be used with caution and only over a secure connection. This method is recommended when queries are not being made from a web browser.

Basic Authorization (username and password) is sent in clear text and must only be used over a secure connection such as HTTPS.

Examples of REST queries

1) The following GET query, copied into a browser's address field, will retrieve data from Trihedral's online demo application

On first running the query, you will be prompted for a user name and password. Reply with demo and demo

Query:

Select Timestamp, 'WaterTreatmentPlantDemo\TCPIP Port\WaterTreatPlantSim\Tanks\Tank0\TankLevel:value' from history order by timestamp desc limit 10

URL:

https://vts.trihedral.com/waterdemo/REST/SQLQuery?query=Select%20Timestamp%2C%20'WaterTreatmentPlantDemo%5CTCPIP%20Port%5CWaterTreatPlantSim%5CTanks%5CTank0%5CTankLevel%3Avalue'%20from%20history%20order%20by%20timestamp%20desc%20limit%2010

2) For this example, you can use either Command Prompt or a Windows PowerShell window. It will not work from a web browser. This is GET request using basic authentication:

curl.exe -u demo:demo https://vts.trihedral.com/waterdemo/REST/SQLQuery?query=GET+Tables

3) This next example works only in PowerShell due to quoting being PowerShell-specific. This is a POST request using basic authentication.

curl.exe "https://vts.trihedral.com/waterdemo/REST/SQLQuery" -X POST -u demo:demo -H "Content-Type: application/json" --data-raw """{""""parameters"""": {""""query"""": """"GET Tables""""}}"""

4) The final POST example stores the query in a JSON file, "query.json". To run this, create a file named query.json and within it store the following:

{
  "parameters": {
    "query": "GET Tables"
  }
}

You can now run the following query:

curl.exe "https://vts.trihedral.com/waterdemo/REST/SQLQuery" -X POST -u demo:demo -H "Content-Type: application/json" --data "@query.json"


Java to ODBC Connection

You must have release 1.3 or later of the VTScada ODBC driver to connect from a Java® program.

The following Java code sample assumes that ODBC access has been configured on the same workstation, as described elsewhere in this chapter, that your application is available via a realm named "SQLServicesRealm", and that your application has a logged Analog Input tag named "ai1".

import java.sql.*;
public class VTScadaJdbcDemo {
  public static void main(String args[]) throws Exception {
    Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");
    Connection con = DriverManager.getConnection("jdbc:odbc:DRIVER=VTSODBC Driver;SERVER=127.0.0.1;PORT=80;REALM=SQLServicesRealm;");
    Statement stmt = con.createStatement();

    System.out.println("");
    System.out.println("All configured alarms:");
    ResultSet rs = stmt.executeQuery("SELECT * From :Alarms");
    while (rs.next()) {
      String name = rs.getString("Name");
      String pri = rs.getString("Priority");
      System.out.println(name + ": " + pri);
    }

    System.out.println("");
    System.out.println("All notes from SystemNotes:");
    ResultSet rs2 = stmt.executeQuery("SELECT * From SystemNotes");
    while (rs2.next()) {
      Timestamp time = rs2.getTimestamp("Timestamp");
      String value = rs2.getString("Value");
      System.out.println(time + ": " + value);
    }

    System.out.println("");
    System.out.println("All Security events from alarm history:");
    ResultSet rs3 = stmt.executeQuery("SELECT * From :AlarmHistory WHERE Area=\"Security\"");
    while (rs3.next()) {
      Timestamp time = rs3.getTimestamp("Timestamp");
      String message = rs3.getString("Message");
      System.out.println(time + ": " + message);
    }

    System.out.println("");
    System.out.println("Weekly interpolated values for ai1 for November 2006:");
    ResultSet rs4 = stmt.executeQuery("SELECT * FROM ai1:1W where Timestamp > '2006-11-01 0:00:00' and   Timestamp < '2006-12-01 0:00:00'");
    while (rs4.next()) {
      Timestamp time = rs4.getTimestamp("Timestamp");
      Double message = rs4.getDouble("Value:Interpolated");
      System.out.println(time + ": " + message);
    }

    con.close();
  }
}


Monitor the ODBC Interface

Through the Trace Viewer application, you can monitor incoming SQL queries. The Trace Viewer (Trace Viewer Application) is a diagnostic application that ships with VTScada and can be found in the list of applications loaded in the VTScada Application Manager (VAM). Note that you may need to add this as an existing application to see it in the applications list.

In brief, to monitor SQL queries from the ODBC interface:

  1. From the VAM, start the Trace Viewer application.
  2. Click on the lighting bolt button in the upper left corner.
  3. Click on the View option beside SOAP Message Tracing in the Live Data Capture Selection dialog that opened in the previous step.
  4. Close the Live Data Capture Selection dialog.


Alarm Data Logging

VTScada automatically stores all transactions & events that occur in the system. Every alarm configuration event is logged as is every alarm occurrence and operator response.

Alarm Event Reference - Describes the possible event types.

VTScada applications start with two Alarm Database tags: the System Alarm DB and the System Event DB. Both store information using the System Alarm Historian tag. While rarely necessary, you may add more Alarm Databases and may create more Historians for use by those databases.

Do not use the same Historian to record both process values (tag I/O data) and alarm information.

The System Event DB will store all security-related events (operators signing in or out, managers changing permissions), all operational tasks that write to a device, a record of automatic report generation events, errors such as failed attempts to send email notifications, and more.

The System Alarm DB stores more than just a history of alarm activations and acknowledgments. All transactional information such as changes of alarm state and changes to alarm configuration are also recorded.

Logging of Operator Control Actions

Event-priority alarms are built into all VTScada actions that write values to equipment. The following actions are recorded in the History alarm list:

  • Changing the value of an output tag
  • Transmitting data via a Modem tag
  • Receiving data via a Modem tag
  • Creating, editing or deleting a page note. (Does not write to equipment, but is considered an operator action.)

For each operator control action-related event in the History list, the following information is logged:

  • The name of the PC on which the security event occurred (e.g. [WorkstationX])
  • The name of the tag that the operator used to perform the control action
  • The username of the user who was signed in when the control action occurred.
  • The area property of the tag.
  • A message field is used to add information about specific events.

The message format can controlled by property, OperatorLogTemplate as follows. Note that this is an older property and must be added. It is not present in newer VTScada applications.

OperatorLogTemplate = ^C ^F ^O ^I ^N

The following control codes are available:

^M | [Deprecated] Machine name
^U | [Deprecated] User name
^T | Tag name
^D | Quoted tag description
^d | Unquoted tag description
^A | Tag area
^O | Old value
^N | New value
^C | ChangedLabel (Phrase identifier key) or OperatorLogChangedLabel (Property value)
^F | FromLabel (Phrase identifier key) or OperatorLogFromLabel (Property value)
^I | ToLabel (Phrase identifier key) or OperatorLogToLabel (Property value)

For example:

[Workstation19] [JSmith] Changed DO_2 "Motor Power" from 0 to 1

Logging of Security Events

VTScada logs the following events related to security to the alarm history:

  • User logs on
  • User logs off
  • New account or role added
  • Account copied
  • Account modified
  • Account deleted
  • Administrative settings modified

For each security-related event in the History list, the following information is logged:

  • The name of the PC on which the security event occurred (e.g. [WorkstationX])
  • The name of the tag that the operator used to perform the security action
  • The username of the user who was signed in when the security action occurred.
  • The area field is "Security".
  • A message field is used to add information about specific events.

An example of a security-related event entry in the History list:

Event Priority Time Date Area Message
 Event Event 09:57:10 Nov 29 Security [WRKSTNX] JSmith has signed in

Logging of Alarm Notification System & Related Events

VTScada logs the following events related to the Alarm Notification System to the alarm history:

  • An operator is notified by voice, email, SMS text or pager of one or more alarms
  • An email has not reached its destination

The following events are also included in this section:

  • Email configuration error (server time-out, failed attempt...)
  • Scheduled report was created or not.
  • Modem error.

For alarm-notification events, the following information is logged:

  • The name of the operator contacted (taken from the Roster tag’s contact records)
  • The email address for the operator contacted
  • The pager terminal phone number and the pager’s phone number/PIN for the operator contacted
  • The phone number for the operator contacted
  • The number of alarms reported
  • The number of alarms not reported (for voice calls only)
  • Other messages describing the event.

Other events in this section will log the name of the logged-on user, the time of the alarm, priority and event, and a message describing the event.

  • The Area for Alarm Notification System - related events is always "Alarm Dialer"
  • Schedule reports will have the area, Report.
  • Modem events will have the area, Modem.
  • Email configuration errors will have the area, System.

Examples of Alarm Notification System-related event entries in the History list:

Event Priority Time Date Area Message
 Event Event 09:57:10 Nov 29 Alarm Notification Email sent to ryan@YourCompany.com with 2 alarms
 Event Event 09:56:06 Nov 29 Alarm notification Paged 453-6487/4585041 with 2 alarms
 Event Event 09:55:23 Nov 29 Alarm notification Called 835-1575 - 1 alarm reported, 1 not reported

For pager entries, the first number is the pager terminal phone number, and the second number is the pager’s phone number/PIN. Also, the event descriptions for voice calls are slightly different than pager or email calls because voice calls are interactive. The Alarm Notification System might report all the alarms, it might only report some of the alarms before the operator hangs up, or it might report zero alarms if the operator does not enter their PIN.


Keyboard Shortcuts

VTScada Application Manager (VAM)

Key Combo | Description
Ctrl + D | Opens the VTScada Debugger Utility (Not the Source Debugger).
Ctrl + L | Opens the Working Copy Lock Closed Grants the lock-owner (module) permission to read/write configuration files. info dialog.

Title Bar

Key Combo | Description
Ctrl + T | Opens the Tag Browser.
Ctrl + D | Opens the Idea Studio.
Ctrl + P | Opens the Print dialog for current page. (No preview)
Ctrl + ~ | Opens the Application Configuration.

Keyboard shortcuts for the title bar are only active if the user has the necessary security privileges.
None of the Title Bar keyboard shortcuts (Ctrl + ~ excepted) are compatible with the Anywhere Client where browser shortcuts take priority.

Tag Browser

Key Combo | Description
Esc | Close the tag browser
Tab | Change focus (Tree View > Grid List > Import > Discover > New > Properties > Draw > Close > Search > Show Children > Show Disabled > Tree View)
Shift + Tab | Change focus in the opposite order.
Arrow Left/Right | Closes/Opens tag trees.
↵Enter | Navigate inside to display children.
Ctrl + N | Create a new tag as if you had clicked the "New" button.
Ctrl + Shift + N | In the grid list, create a new child tag under the selected tag.
Ctrl + Shift + V | In the grid list, pastes a copied tag as a child of the selected tag.
Delete | Deletes a single selected tag in the grid list.
Alt + Enter | Opens the properties dialog for the selected tag.
Alt + Up | Navigate up one level in the tag hierarchy
Alt + Left or Alt + Right | Navigate back and forward through the tag browser's navigation history.

Keypress search is available. In grid view and in the select type panel, you can jump to a specific name by starting to type it in. This feature is more intuitive to use if Show Children is disabled.

Keypress search also works in the Select Type tag dialog and the Source Debugger.

Tag Properties Dialog

Key Combo | Description
Ctrl + Z | Undo last action in a numeric or string field. Click on the field that you want the undo to apply to. May be used up until the state of the field the last time changes were applied.
Ctrl + Y | Redo last action in a numeric or string field. Click on the field that you want the redo to apply to. May be used up until the most recent new change.
Ctrl + Tab or Ctrl + PgDn | Switches to the next tab.
Shift + Ctrl + Tab or Ctrl + PgUp | Switches to the previous tab.

Historical Data Viewer (HDV)

Key Combo | Description
Arrow Keys (Left/Right) | Pan backwards and forwards in time.
Shift + Arrow Keys (Left/Right) | Pan backwards and forwards in time in larger increments.
Ctrl + Minus sign (-) | Zoom out (x-axis).
Ctrl + Plus sign (+) | Zoom in (x-axis).
Ctrl + 0 or Ctrl + * | Return to live mode.
Esc | Exit selection choice in 'Pan & Zoom'

Idea Studio

Key Combo | Description
Ctrl + N | Creates a new standard page.
Ctrl + O | Opens an existing page or widget
Ctrl + T | Open the Tag Browser.
Ctrl+ L | Link the selected widget to a tag. Enable Show Children when the tag browser opens.
Ctrl + Plus sign (+) | Zoom in.
Ctrl + Minus sign (-) | Zoom out.
Ctrl + Scroll Wheel | Zoom in and out.
Shift + Scroll Wheel | Move left and right instead of up and down.
Ctrl + TAB or Ctrl + PageDown | With multiple pages/popups/widgets open, switch to the next tab.
Shift + Ctrl + TAB or Ctrl + PageUp | With multiple pages/popups/widgets open, switch to the last tab.
Ctrl + Z | Undo the last action. May be used more than once.
Ctrl + Y | Redo last action. May be used more than once.
Ctrl + A | Select all the graphics.
Ctrl + Click | Select all graphics under cursor.
↵Enter | Open the properties of the selected widget, image or shape.
Arrow Keys | Move selections.
Shift + Arrow Keys | Move selections 10x faster.
Shift + Drag | Move selection orthogonally.
Del | Deletes selected graphics.
Ctrl + C | Copies the selected graphics.
Ctrl + X | Cuts the selected graphics.
Ctrl + V | Paste the graphics from the clipboard at the cursor location.
Alt + Arrow Keys | Re-size selection.
Alt + Shift + Arrow Keys | Re-size selection while maintaining aspect ratio.
Esc | While resizing/nudging/drawing a pipe et cetera, hit escape to cancel process.
Ctrl + [ | Bring the selected object forward.
Ctrl + ] | Send the selected object back.
Shift + Ctrl + [ | Bring the selected object to the front.
Shift + Ctrl + ] | Send the selected object to the back.
F2 | Align left.
Shift + F2 | Align right.
F3 | Align top.
Shift + F3 | Align bottom.
F4 | Align center.
Shift + F4 | Align middle.
F5 | Match height.
Shift + F5 | Match width.
Ctrl + B | Changes selected text to bold.*
Ctrl + I | Changes the selected text to italic.*
Ctrl + U | Underlines the selected text.*
Backspace or DEL | When drawing a line or pipe, remove last vertex in path.

*Text as in using the Text tool, not widget labels. Widget labels use font tags through their property dialog.

Keyboard Shortcuts in the Anywhere Client

Please note that some shortcuts will not work in the Anywhere Client because pre-existing browser shortcuts will be prioritized. These exceptions include:

  • Ctrl+T in the title bar
  • Ctrl + P in the title bar
  • Tab/Shift + Tab in the Tag Browser
  • Ctrl + N in the Tag Browser
  • Ctrl + Tab/Ctrl + Shift + Tab in the Tag Properties dialog.

Related information:

VTScada Application Manager (VAM)

Find and Open Pages Within an Application

The Tag Browser

Add a New Tag or Child Tag

Historical Data Viewer (HDV)

Display Building (Idea Studio)


Client / Server Configuration

This chapter refers to the configuration of primary and backup servers for redundancy and load distribution. If you are interested in configuring a VTScada Thin Client Server for thin client connections, refer to Thin Clients: Mobile and Internet. If you are wondering how to configure VTScada to run as a Windows service, refer to VTScada as a Windows® Service.

One of VTScada's most powerful features is its ability to run on multiple servers, synchronizing both configuration and historical data. Backup servers take over instantly when the primary server goes offline, ensuring that your application suffers no downtime due to computer failure. Services within VTScada (Alarm Manager, Historians, Drivers, etc.) can have separate server lists, thereby distributing the load across many machines, each with its own independent backups.

Multi-server applications can also have client workstations, which are simply VTScada workstations that are not configured as servers. Operators can work and developers can build at these stations, but the client workstation cannot take over in the event of server failure.

VTScada uses the IANA-registered port, 5780

Never enable Internet access to any VTScada listening ports. These should be visible only to devices or workstations on your network as operationally necessary.

All computers must be running the same version of VTScada.

It is important to keep the server clocks synchronized. Errors in logging and synchronizing data can occur if the server clocks disagree significantly about the time.

Requirements:

  • A VTScada license for each computer, where those that are to be servers have the license options, Server Capability and Redundancy Capability.
  • An intranet connecting the workstations.

Configuration Process:

Preparation:

  1. Obtain VTScada licenses that permit server operation and install on two or more computers.
  2. Ensure that the computers can communicate across your network.
  3. Create an application that you want to run on multiple servers.
  4. Enable security and create one or more accounts.
    After security is enabled, only users with the Configure or the Manager privilege may pull the application to another workstation.
  5. Run the application only on a single workstation.
    Do not copy the application to the other workstations.

Steps:

On the workstation with the application:

  1. In your application, open the VTScada Application Configuration dialog.
  2. Expand the Edit Server Lists tab.
  3. Your workstation should be listed as an available server. If not, type in the name of your workstation as an available server.
  4. Click the + button.
  5. Click the Apply button at the bottom-right of the dialog and save your configuration.

On another workstation:

  1. Go to another workstation where you have installed VTScada.
  2. Open the Add Application Wizard from the VAM.
    (Menu item: Add New Application)
  3. Select the Advanced option in the first panel, then click Next.
  4. Select the Get From Workstation option in the second panel, then click Next.
  5. Select (or type) the name of the workstation where your application is currently running, then click Next.
  6. Select your application from the list of those available, then click Next.
    You will be prompted for your username and password. You must have configuration privileges.
  7. Click Finish.
  8. Repeat from step 6 for the other workstations.

On any workstation:

  1. On any workstation, open the Application Configuration dialog to the Edit Server Lists tab.
  2. Add the names of the backup servers to the list.
    The workstation name at the top of the Common Server List is the primary server, followed by backup servers in order down the list.

In a basic configuration, as created by the preceding steps, all I/O communication is handled by the primary server. Control actions from other workstations go first to the primary server, then to equipment. Data logging is done on the primary server, then copied to the backup servers.

Name resolution must be properly configured for VTScada networking to operate correctly. In the case of a local network with no DNS, set the Setup.INI property RPCConnectStrategy (RPCConnectStrategy) to a valid value.

VTScada relies on a Windows® operating system function call to obtain the NetBios name of workstations. That function will truncate names that are longer than 15 characters. You are advised to limit workstation names to be 15 characters or less.

If your network becomes partitioned (communication is broken) you are advised to repair the break if possible before stopping and restarting VTScada servers.

VTScada and NATs

Network Address Translation (NAT) routers are not compatible with VTScada. Do not use.
Each thick-client server must have a unique IP address. A NAT device will cause the same IP address to be assigned to more than one server. VTScada cannot operate in this environment.
As shown in the following illustration, a NAT device will cause Server B and Server C both appear to Server A as if they were on the same IP address.

Multi-Homed Systems and Name Resolution

VTScada relies on name resolution to identify the addresses of other VTScada systems that are multi-homed. VTScada maintains connections to other VTScada servers over each subnet for which there are IP addresses configured.

Using DNS:

The recommended way of providing name resolution is by using a DNS Closed Domain Name Server server. Your DNS server needs to return each IP address that can be used to communicate between multi-homed VTScada systems. Typically, you would configure multiple records, listing each IP addresses for each multi-homed VTScada computer.

A dual-homed pair of systems can be configured to support multi-homed connections without a DNS server. These methods are not recommended but may be used for small systems whose addressing remains static.

Using Hosts Files:

A hosts file can only provide one IP address for a given name. A workaround is to configure your hosts file on computer A to resolve computer B to an IP address on subnet 1. Configure your hosts file on computer B to resolve A to an IP on subnet 2. When one of the computers connects to the other, the receiving computer will recognize the other, do a name look-up that yields an IP address for the sender on the other subnet and make a connection there.

Using VTScada Server Lists:

You can configure your server lists to include both the names and IP addresses of your VTScada servers for one service. For example, configure a server list consisting of the names of both servers and all the IP addresses that are used. So, for a two-server system, you would have two server names and four IP addresses. You need only do this to one server list.

Note that this adds a small overhead when VTScada is starting your application and that such a server list is not portable.


Get From Workstation

At some point in the process of setting up multiple servers, you must install the application on those computers.

The Get from workstation option is preferred for distributing an application between computers that are connected on a network. By using this method, you ensure that the most up-to-date version of the application is installed, and that future updates are distributed automatically. (Assuming a properly configured server list.)

If the application is based on an OEM layer, and that OEM layer is present on the server, it will also be retrieved at the same time as the application.

If the application is secured, you must sign in with an account that has either the Configure or Manager privilege, and that is not a member of any security group.

  1. Begin by opening the Add Application Wizard,
    ... choose Advanced and click Next,
    ... choose Get from Workstation and click Next.
    You will arrive at the Get from Workstation page.

Machine names are preferred over IP Addresses.
Type the name if the list is not populated automatically.

  2. Enter the machine name or IP address of the workstation containing the application.
    On a network with a properly configured domain name server, all local machines that have VTScada installed should be available for selection in the drop-down list.
  3. Click Next.
    Applications available on the selected workstation are shown. An asterisk will mark ones that already exist on your workstation.

Typical list of applications.

  4. Select the application you want.
  5. Click Next.
    A confirmation page opens, where you may review your choices before clicking Finish.

If the application is secured, you must logon before the transfer will take place. Get From Workstation operations are exempt from TOTP. You will not need to perform a TOTP check even if there is a device registered to the account.

After clicking Finish, the application is copied to your workstation and added to your list of available applications in the VAM.

When adding a backup server, you can monitor VTScada's progress while copying data to the new server by using the Historian Status widget. When the status returns to "Ready", your data is synchronized.

Troubleshooting:

  • No servers are shown in the Choose Server dialog.

This may indicate that your network domain name server (DNS) is not properly configured. You can ignore this problem and type in the name of the computer where the VTScada configuration server is running.

  • The Find Servers dialog reports that the requested computer is unavailable. This may be preceded by a "Contacting Workstation..." message.

The specified workstation is not available, or VTScada is not running on that computer.

  • The application you expected to find is not listed.

Applications that exist on both computers are not shown. If it is not listed in your VAM, try the Find Existing option.


Servers for Specific Services

In larger applications, there may be reasons to divide the load of running VTScada between more than one server. For example, you may want to configure one server to look after alarms while another does the logging. Another example is to define primary and secondary servers for sets of I/O device drivers (See: Driver Server Lists).

Load distribution is configured using the advanced tab of the Edit Server Lists dialog.

Parts of an advanced server list.
Note that the Default Server List must never be empty. This is handling everything that is not otherwise specified.

The following instructions use an existing tag (System Historian) to define a service-specific list. When creating a service-specific list for a driver or Historian, there is an advantage to creating the list first, typing in a name rather than selecting the existing tag. After the list has been created, create the matching tag using the same name. By doing so, you ensure that the service uses the custom server list immediately rather than using the default list for a period of time.

To add a service for which you intend to designate primary and backup servers:

  1. Open the Application Configuration dialog.
  2. Select the Edit Server Lists option from the menu.
  3. Click on the button labeled "Advanced Mode"
  4. Right-click on the node, Server Lists

  5. Click on Add Service-Specific Lists

The Add Service-specific Lists dialog opens

  6. Select the service for which you want to define Primary and Backup Servers.

The example shows a service-specific list being created for the System Historian.

I/O services are selected by the Server List name you create for your device drivers if any. (See: Driver Server Lists) These will appear in the server list only while the application is running, as is the case with all tag-related services such as the SystemHistorian.

  7. Click on OK.

The service is listed in the menu.

If left in the state shown here, the System Historian would use the default server list.

  8. Right-Click on the service name to open the context menu.

The Add Workstation-specific or Default List dialog opens

  9. Select the option, "Default for Workstations" and click OK. (1)

The entry Default for Workstations is added to the tree.

  10. Right-click on Default for Workstations

  11. Click on Add Server to List
  12. Select the computer that is to serve as the Primary Server for this service.
  13. Click OK

Repeat the last three steps for the backup servers you want to designate for this service.

  14. Click Apply

(1)It is possible to define a server list that is in effect only for a named workstation.

If creating tag-based server lists and using a legacy application created prior to version 10.2, refer to notes in FriendlyTagServiceNames


Services Page

Access to this page is controlled by the privilege Services Page Access.
The ability to change servers is controlled by the privilege Switch Servers. Additionally, Setup.INI properties can disable any of the switch server options for all users. Refer to the list at the end of this topic.

The Services page allows you to monitor the status of every networked service in your application, view the architecture of your server lists, and to control which workstation should be the current server for any service. It does not provide a method for creating or modifying a server list. The status of each service is presented from the point of view of the workstation on which you are viewing this page. This workstation's understanding of the status of each service could potentially be different from another workstation's.

In addition to this page, you can add a Service Status Widget to a page of your choice. The Switch Servers privilege will still apply, but you must create a custom privilege to restrict access to your own pages.

Service Status including the optional legend

The Service Architecture list provides the following columns, describing the configuration of your server lists:

Service | Server List | Primary Server | Backup Server 1 | [ Backup Server 2 ... if present ]

Service Tools

The tools across the top of the page work when either list is shown.

Switch All Away

Any service that is currently using this workstation as its server will be directed to use the next available backup instead.

Switch All to Next Server

Forces all services to switch to the next available server, according to the server list.

Switch All to the Primary Server

Forces all services to switch to the configured Primary Server, if available.

Switch to Next Server

Forces the selected service to switch to the next available server, according to the server list. It is not possible to select multiple services.

Switch to Primary Server

Forces the selected service to switch to the configured Primary Server, if available.

Advanced Filtering

The Advanced Filtering Dialog can be used to restrict which services are shown in either list.

  • Name - Filter by the name of the service (not a server).
  • Server List - "Default" will be the only entry unless you have created your own server lists.
  • Server in Server List - Select from the list of servers used by your server lists.
  • Current Server - Select a server. The list will show only those services currently using that workstation as the server.
  • Status ("with" or "not") - Choices include "Disconnecting", "Syncing", "Client", or "Current Server".
  • Type - Choices include:
    "VTScada Service" Currently, only the configuration service.
    "Application Service" Fundamental Services such as AlarmNotification and TimeSyncManager.
    "Tag Service" Services related to tags, including all historians and drivers.
    "Driver Service" Services related only to drivers.
  • Tag Type- Select between historians, drivers, or any custom type that might have a service

Service Details Dialog

Enabled only when a service is selected in a list. Click to open a dialog showing status and configuration information about the selected service.

Properties

Enabled only when a tag-related service such as SystemHistorian or a driver is selected. Opens the properties dialog for the matching tag.

Text Size

Adjusts the relative text size used in the list from small to large in steps of two points.

Legend

When selected a legend is superimposed on the current list. This is a guide to the meaning of the colors and symbol used for each server in the list:

Daytime / Nighttime

Toggles the background between light and dark

Related information:

DrawServiceListEnableSwitchingAll

DrawServiceListEnableSwitchingSelected

DrawServiceListServerSwitchAllRequiresConfirmation

DrawServiceListServerSwitchRequiresConfirmation

DrawServiceListUpdateRate


Workstation-Specific Server Lists

There are two reasons for creating a workstation-specific server list:

Separate server lists for separate zones

There may be an advantage for one or more servers to work independently. For example, in an application that spans many widely-distributed sites, the local sites might maintain their own server lists.
This can minimize traffic across a slow network link when there are multiple sites on both sides of the link. One computer at the remote site should be configured to use the regular list, looking at the servers on the other side of the link for data. Other stations at the remote site are configured to treat that workstation as their server. The first computer acts as a client for getting data, then as a server to push that data out to its clients.

Machines A-1, A-2, A-3 and B-1 use the same server list, where machines A-1 and A-2 are primary and backup server.

Machines B-2 and B-3 share a workstation-specific list, where B-1 is the primary server and B-2 is the backup.

Offline development

Developers may be working in an environment where they do not have an active connection to the primary server. By adding a server list that applies only to their computer, then setting their computer as their own primary server and no back-up servers, they can work without VTScada attempting to synchronize with the real primary server.

Create a workstation-specific server list:

  1. Open the Application Configuration dialog.
  2. Select the Edit Server Lists option from the menu.
  3. Click on the Advanced Mode button.
  4. Create a default server list that will apply to all workstations other than the ones you are about to configure.

  5. Right-click on the service name.

  6. Click on the Add Workstation-specific or Default List option.
  7. Select the name of the first workstation for which a workstation-specific list will be defined.

In this example, the workstation is named "Hobbes"

  8. Right-click on that workstation
  9. Select the primary server for the service on that workstation.
  10. Repeat as required for other services and for backup servers.


Server Configuration Examples

The following examples are provided to help you see how server configuration might be used to your advantage.

In its simplest form, server configuration consists of one primary server, one or more backup servers, and optionally, one or more pure clients. A pure client is simply a workstation that is running the application, but which will not take over as a server in the event that the primary is lost.

Fail-over from primary to backup

The Primary and backup servers are continuously synchronized. If the primary goes offline for any reason, the backup will immediately take over. When the primary is restored to service, the backup will synchronize configuration and data with it, following which the primary will again take over its role.

The Client computer can be used for monitoring and control and it is possible to make configuration changes using it. But, communication to the hardware is done by the current server, never by the client. Configuration updates are first sent to the server, then distributed to the other workstations.

Simple Configuration for Redundant Operation

ServerA is designated Primary for all services. ServerB is designated as backup.

In the event that ServerA is offline, ServerB will take over all operations.

Detail shown from the Basic Interface of the Edit Server Lists page of the Application Configuration dialog.

Simple configuration with a primary and backup server

Simple Configuration for Load Distribution and Redundant Operation

ServerA is the Primary for the application's driver (tag I/O) and the Alarm Manager and is backup for all other services. ServerB is Backup where ServerA is Primary and is Primary where ServerA is Backup.

This balances the load so that I/O operations and Alarming are concentrated on one server while disk-intensive operations including logging are handled by the other.

In the event that either server fails, the other will continue running all services.

Detail shown from the Advanced Interface of the Edit Server Lists page of the Application Configuration dialog.

Configured for load distribution

Historian Load Distribution

This example is designed to handle an extremely high data-logging load by providing three Historians, each with one redundant server. It is assumed that each Historian is logging data from 1/3 of the tags.

Configured for load distribution and backups

In this configuration, each of the machines will carry 2/3 of the disk activity load.

Server detail shown from the Advanced Interface of the Edit Server Lists page of the Application Configuration dialog.

Server list matches previous figure


VTScada Services Reference

When planning your server configuration, you should consider the balance between services that are I/O intensive and those that place a heavy load on hard drive access. In larger systems, there can be significant benefit to distributing the load to separate these types of services. Your design should also consider system redundancy for risk management planning.

Each of the following VTScada services can be assigned its own server list. Some place a heavier load on data I/O while others require more disk access. Some of the services listed here place minimal load on a system, and therefore may be assigned to servers at your discretion.

every system will have different requirements and different priorities. No single guideline can be used for the design of all systems.

Alarm Notification

Used to decide which workstation should dispatch alarm notifications. This service is registered only on workstations that have the alarm notification feature enabled in their license key. Backup servers will assume the role if the higher-level servers don't have alarm notification feature enabled.

Configuration

The service responsible for distributing deployed changes to all workstations. In a working system, configuration changes usually do not occur often, but may place some load on disk access when they do. Some developers prefer to keep the configuration server separate from the primary server for tag I/O in larger applications.

ControlTokenManager

The service that monitors for stale control tokens.

Device Drivers

All I/O will route through the current primary server to reach the attached device. Ensure that listed server can connect to your devices. In a larger application, consider separating these services from those that require intensive hard drive activity such as Historians. If there are several device drivers on a server, consider creating a set of named Driver Server Lists for ease of configuration.

DriverDiscovery

Currently, applies to the BACnet driver discovery feature.

Modem Manager

Used in VTScada installations that include the Alarm Notification System option. Provides data and voice telephony services for standard VTScada applications and enables modems connected to different machines to be managed as a common pool. This service seldom places a heavy load on a system.

MultiSpeakRPCService

Ensures that only the designated server will send out a notification to Milsoft-OMS when a tag value changes.

Network Values

This service is in charge of updating changes on all PCs for multi-server applications when a change to a Network Value variable has occurred. Involves data transfers to all PCs in the network therefore there is little advantage to separating this service from others.

OAuth2

Servers to be contacted for OAuth 2.0 authentication. These do not need be thin client servers.

Page Parameters

Responsible for (in part) synchronizing task bar page buttons. Places minimal load on a system.

Service Control

May be used by custom code to provide application-level control of RPC servership.

SlippyMapService

Identifies the server where map tiles are stored. All other workstations will obtain their tiles from this server rather than downloading from the Internet.

SMS Manager

Used in VTScada installations that include the Alarm Notification System option. Provides SMS messaging services for alarm notifications. This service seldom places a heavy load on a system.

System Alarm Historian

The System Alarm Historian service takes care of alarm storage and retrieval. This service will not place the same load on system resources as Historians logging process I/O. This historian is normally configured so that a local copy of data is maintained on all workstations, allowing alarms to function normally on a workstation that is separated from the current primary server.

System Historian

The System Historian service takes care of data storage and retrieval. This service is disk access intensive and is often separated from services that involve tag I/O and alarming.

User-Defined Historians

Developers may create their own Historian tags in addition to the SystemHistorian, thereby distributing the task of logging data. In a large application, setting different servers for each Historian is an effective way of distributing the load of disk access.

Value Synchronization Service

Used only in the Totalizer tag, Counter tag, Selector Switch and (possibly) user-defined custom tags. Places minimal load on most systems.


Configuration Deployment

Every change to an application is considered to be a version change. If the Auto-Deploy option is not selected, changes are "Local" and not distributed to other computers until you choose to deploy them. Otherwise, all changes are immediately sent to all computers on which the application is active.

Toggle the Auto-Deploy option using the check box within the "Other" tab of the Application Properties dialog, Edit Properties page.
(Other Tab of the Edit Properties Page)

Step 1:

A developer makes a change to an application on workstation Wks1.

Step 2:

The change is deployed. It is sent to the current configuration server, Srv1 which then sends it to workstations Wks2 and Wks3

Step 3:

Workstations Wks2 and Wks3 send an acknowledgment back to the server. This acknowledgment shows the current version number on those workstations.

Step 4:

After a few moments, the server distributes those acknowledgments to all the workstations. The result is that every workstation always contains a complete local copy of every other workstation's change history.

Should the primary configuration server go offline, the backup configuration server will immediately take over all of its duties.


Shared RPC

Every driver has a SharedRPC value that you can set in the advanced mode of the Edit Properties dialog. Each is named after its driver: ABSharedRPC, DNP3SharedRPC. drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

When set TRUE (1) and if your application runs on multiple servers, you only have to declare a single entry in the application server list for all drivers of that type, rather than create an entry for each driver. All drivers of that type will switch between client and server modes together.

SharedRPC mode is not compatible with DriverMUX tags.

In many cases, there is an advantage to creating Driver Server Lists rather than configure shared RPC.

Do not set if:

  • You have set NoSoftDriverFailure = 0.
    Soft driver failure means that certain errors in drivers can cause the ‘driver service’ to switch to the alternate server. Therefore, this would mean even a correctly functioning driver could be ‘switched’ based on errors in a poorly operating instance.
  • You wish to share the driver load on different I/O servers. To share load you would have to assign each driver to a server list entry that you create.
  • You have a small application with few drivers.
  • You have a basic server list, common to all services and workstations.
  • You are using a Driver Multiplexer tag with your drivers.

Possibly set if:

  • All driver instances of the same type share a resource that would be adversely affected by drivers attempting to poll from different workstations at the same time. For example, a radio or other intervening hardware.
  • You are concerned about and wish to reduce system resources such as memory, CPU, and synchronization time, that are associated with multiple RPC services.


Sites & Maps

Sites and maps are typically used together but refer to separate features. It is not uncommon to find applications that use maps but not site lists, while other applications will use site lists without ever displaying a map. Both features have their own relative advantages.

Site:

A tag that is designed to contain other tags.

A site list is a useful way to view I/O, grouped together in meaningful units. While the term "site" implies location, equipment such as pumps and valves can also be considered as sites, with or without location information.

Sites include:

  • Polling drivers and Data Flow Station tags. The concept of site tags began with these two drivers.
  • Context tags and user-defined types derived from context tags. These are defined as sites whether you add site configuration parameters to those tags.
  • Station tags including MultiSmart, MPE Duplexer and MPE SC types.
  • Analog Statistics and Digital Statistics tags.
  • Alarm Database tags.

Only the listed types can be considered "sites". Adding child tags to other types, for example adding a Logger as a child of an Analog Input, does not make that tag a site.

Map:

A display screen of map tiles, which may display pins or other icons marking the location of site tags that have latitude and longitude coordinates.

Map tiles are downloaded on demand from a host site of your choice, or they may be cached locally on servers that do not have an Internet connection.

If permitted under your map provider's terms of service, then you may use the bulk download tool to retrieve and cache tiles for a given area and given resolution.

Site List Display

You have control over whether and how site tags are shown in the site list display. Refer to Site List Display Options for more information.

Disable / Enable Maps

The VTScada installation wizard gives you an option of not using maps, but this refers only to Open Street maps. Carto® maps are always enabled.

To enable Open Street maps later, if you choose not to during installation, edit your Setup.INI file to change the value assigned to SlippyMapOSMDisable from 1 to 0, then restart VTScada.

To disable all maps, open your Setup.INI file and locate the [SlippyMapRemoteTileSourceN] sections (where N is a number from 1 to 4). Comment-out every property in each of the sections by adding a semicolon at the beginning of each line. DO NOT DELETE PROPERTIES. If you do, and then decide to re-enable maps, you will need to reinstall VTScada. Better to simply disable the properties by adding semicolons. Save the edited file and restart VTScada.


Sites List Display Options

The Sites page (or Site List page), found in the menu of every new application, will show a hierarchical list of all tags that are considered sites Closed Tags designed to contain other tags. Includes Polling drivers and DFS stations, Context tags and user-defined types derived from Context tags, Stations, Analog Statistics and Digital Statistics.. Site tags include the Polling Driver, DataFlow RTU, MultiSmart, MPE Duplexer, MPE SC, Context tags and user-defined types derived from Context tags, Analog Statistics and Digital Statistics.

You have extensive control over the Sites page including which sites are displayed, how they should be displayed, and whether and how a map is included. Control is exercised through tools in the page and through configuration of the site tags.

Sites Page Controls:

Four controls are provided across the top of the page:

Sites Page display options

You can change the background color of the page by adding the application property, ThemedPageBGColor.

There are three situations where it is helpful to set Exclude from Site List on your Context tags:

- When requesting a Go To Page on any Context tag (or other container type) from the Tag Browser or Alarm Page, the Sites page will be included in the list of possible pages and might be the default.
- The above is also true for child tags of the Context tag.
- Context tags (and new types created from them) are always included in the list of a Sites List Display Options. This may not be appropriate if the Context represents equipment rather than a site.

To prevent these actions, do the following:
1. Select the Add Site Properties button in the Settings tab of the Context tag.
(See: Change the Parameter List if you have already turned the Context into a new type.)
2. Delete all site properties except for SiteListDisplay.
3. In the Display tab, select the option Exclude from the site list
(If any child tags should be included in a site list then select Display as a Folder instead.)

Customers upgrading from a version of VTScada released prior to 12.0 might expect the following behavior: Clicking the bottom-most node in a sites hierarchy would open the Site Details page as a pop-up. If an intermediate node in the sites hierarchy contained I/O as well as child sites, the I/O values were displayed below the child sites in the Sites List portion of the Sites Page.
The Site Details page now opens within the same page, occupying the space where the map was displayed. You can override this behavior by adding the property OpenSitesAsPopup, setting its value to 1.
The in-page Site Details page also includes an Open as Popup button in its title bar, providing a way for those who prefer to have the page open as a pop-up to continue opening it as such.

Site List Display Options

For all site tags in your application, you have control over whether and how it will be displayed in the list. Use the tag's configuration panel to adjust settings. Note that for Context Tags and user-defined types based on Context tags, you must add site properties to the tag before you can choose any option other than the default.

Variation between options by tag type

  • Automatic: If this tag contains child sites and there are other tags like this one, folder display will be used. Otherwise, site display will be used.
  • Display as Site: A click will open the Site Details page.
  • Display as Folder: Indicated by an arrow. A click will change the list to show the child sites. At the top of the new list a back arrow will be added to allow operators to navigate back out of the site.
  • Exclude: This tag and its children will not be shown in the Sites page list.
  • Only display child tags. This tag is effectively transparent and its child tags will be shown instead of this site.

Example: The Volcano Monitoring Application

(This example is intended only as an illustration of Site List Display options. It shows an example of how and why you might choose each of the options.)

Volcano monitoring tag structure:

Key parts of the hierarchy: Countries -> Regions -> Volcanoes -> Stations -> Equipment

Countries --> Display as a Folder

These are not drawn on maps (monitoring stations are.) Countries are treated as "Folders" within the site list and are used only to organize the monitoring stations.

Note that if there is only a single site, VTScada will automatically navigate into that site. There must be at least two sites configured as folders.

Countries, displayed as folders

Regions --> Only display child tags

If a country has many volcanoes, they are grouped into regions for administrative purposes. But when looking at a list of a country's volcanoes, we have decided not to force people to click into each region; instead all volcanoes are shown. Regions therefore, are configured as "Only Display Child Tags", effectively making the region itself transparent when viewing the site list.

Navigating into Iceland. Regions are not shown (set to only display child tags).

Mobile Equipment --> Exclude from the site list

At the same level as the regions, each country has a collection of mobile and miscellaneous equipment. Some of this collects data and therefore has tags, but none of this equipment is relevant to a Site List or a map.
The Mobile Equipment tag is configured as "Exclude from site list display" and has no other site properties. Mobile equipment might be drawn on other pages and can be included in reports but you won't see anything from that part of the hierarchy in a Sites display list.

<< No image / nothing to be seen >>

Volcanoes --> Automatic

<< See previous image showing all volcanoes >>

Some volcanoes have multiple monitoring stations (each pinned on the map) and some have just one set of monitoring equipment. Volcanoes are configured as "Automatic" meaning that if one has monitoring stations it will be treated as a folder, and if it directly contains the monitoring equipment it will be treated as a site. Click the site (at the top of the list) to toggle between the two display options:

Eyjafjallajökull as a folder

Eyjafjallajökull as a site

The "self" button indicates that this is the parent site. The self button is shown only for sites that contain both I/O and child sites, and then only when you have navigated into that site.

Stations --> Display as a Site

These are configured to be sites, always and only. They need latitude and longitude parameters to be placed on a map and they can be configured to (when clicked) open either the built-in Site Details page or a parameterized page of your choice.


Site Details Page

The Site Details page shows communication, alarm and I/O information for site and station tags. These include the Polling Driver, DataFlow RTU, MultiSmart, MPE Duplexer, and MPE SC tag types, as well as all custom types that you create, based on Context tags.

The Site Details page is automatically generated for you by VTScada. It can be opened within the Sites page or as a pop-up page. You may choose to use pages of your own creation instead, on a site-by-site basis.

Example for a Polling Driver site, as viewed within the Sites page

There are four methods that operators can use to open this page:

  • Click on a site that is included in the list of the Sites page.
  • If you use the Site Draw widget to draw a Polling tag or DataFlow RTU, then operators can click on the Site Draw to open this page.
  • If you have drawn any of the available site types as a Site Icon or Site Summary, (this includes a pin, drawn on a Site Map), then operators can open the Site Details page by clicking on the icon or pin.
  • You can draw the page within any other application page. In general, this method is discouraged in favor of the previous three. You are likely to encounter scaling problems when the Site Details is drawn inside a standard VTScada page.

Components of the Site Details page:

Title Bar Controls

Visible only when the Site Details is viewed as a component of the Sites page, not as a pop-up.

Tabs:

Every Site Details page has two tabs: I/O and Map. The map is simply a Site Map, showing the location of the station.

Driver Statistics Section:

Applies only to sites that are Polling drivers or DataFlow Station drivers. Visible when the I/O tab is selected. Shows statistics associated with the driver. Also included are buttons that open the Comm Messages dialog or the Comm Statistics dialog for the driver.

Alarms Section:

The Alarms list will be populated with all current alarms associated with the driver. Operators may use the Ack button here to acknowledge any given alarm.

Only alarms whose area matches the area of the site tag will be displayed. If two site tags share the same area, it is possible to see alarms from both. In general, each site tag should have its own area.

I/O Section:

All of the I/O tags associated with the site are shown at the bottom of the page. These are grouped into separate columns according to the type of I/O: analog or digital, input or output. Input tags that allow writing are still considered input tags. Selector switch tags are included with the digital outputs.

Any unacknowledged alarm on an I/O tag will be indicated by the color red. Red text for analog tags and a red dot for digitals. Controls are provided for all output tags associated with the station.

The application property, SiteToolsConfirmOutput, controls whether a confirmation prompt will be shown before new output values are sent.

I/O Section Filtering:

If the site tag has a parameter named CustomSiteListFilterType, then the I/O list will be filtered to show only the type, or types in the group, specified for that parameter.

You can change the background color of the page by adding the application property, ThemedPageBGColor.


Site Details Configuration

The Site Details page normally opens within the Sites page, unless an operator navigates to the site by clicking a Site Icon. You can configure it to open in the main display window in response to the Site Icon as well by setting the application property SiteDetailsWindowed to false (0).

You can control the colors used for digital values (Digital Input, Digital Status and Pump Status). The application properties are included in the following table, which also shows the default color for each state.

State | Color | Property
Invalid | black | DigitalIndicatorInvalidColor
0 | light gray | DigitalIndicator0Color
1 | green | DigitalIndicator1Color
2 | blue | DigitalIndicator2Color
3 | purple | DigitalIndicator3Color
alarm active | red (blinking if unacknowledged) | DigitalIndicatorAlarmColor
bad quality | orange | BadQualityColor

Related information:

BadQualityColor

DigitalIndicatorInvalidColor

DigitalIndicator0Color

DigitalIndicator1Color

DigitalIndicator2Color

DigitalIndicator3Color

DigitalIndicatorAlarmColor

SiteDetailsWindowed


Create a Custom Site Details Page

You may prefer to create your own site details page in place of the built-in version. Any page can be used as a Site Details page, but in general these tend to be parameterized pages (Parameterized Pages) designed to show the I/O values, controls, and other information associated with a site. Therefore, custom site pages should be configured to have a parameter of type tag, by which you will pass in the site that should be displayed.

If your intent is for operators to open your custom page from the Site Details list, your page must have only one parameter, which is of type Tag and which can be linked to the site. Everything shown on that page should be held in a single Tag Widget, linked to the parameter.
If opened from a Site Icon, there are more options for parameter configuration.

While you can certainly create custom site details pages for Context tags, it's far easier to keep track of which page is for which type of site if you first turn your Context tags into custom types. (Design Your Own Tags).

The Manage Parameters dialog for custom site page.

In this example, SupplyPump is a custom type (site) with several child I/O tags.

In this example, everything that you see on the Pump Control page is drawn within a Tag Widget, designed to show child tags of the user-defined tag, SupplyPump.

There are two methods to specify a custom site details page:

Method 1: Configure your site tag:

  1. Configure your site tag so that it has the parameter, CustomDetailsPage.
    This parameter is part of every station tag, and can be added to your Context tags with the button Add Site Properties in the Display tab. If you have already turned your context tag into a custom type, use the same button in the Manage Types page of the Application Configuration dialog.

If the Context has been turned into a new type, use the Manage Types dialog (Modify a Custom Type).

  2. For each instance of your site tag, select the page to use.

Selection of a custom details page. The page must take a parameter matching this tag type.

Method 2: Configure the Site Summary or Site Icon widget that displays your site tag.

  1. If your site is linked to a Site Summary widget or Site Icon widget, then configure that widget to use the custom site details page.

This option gives more control over matching tags to parameters.

Advanced Configuration:

The default page selection dialog has a filter for "all pages" or "site pages", meaning those that take a site tag as the first parameter.

You can add either of the following two properties in the Edit Properties page of the Application Configuration dialog to restrict this filter:

LimitPageListToSitesPages

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog for all users.

LimitPageListToSitesPagesIfRealmUser

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog if the user belongs to a security group.


Site Map

A Site Map is a dynamically-loaded map, primarily used to show the location of any of the site-related tags: Polling drivers, DataFlow RTU drivers, MultiSmart™ stations, MPE™ Duplexer stations, or MPE™ SC stations. You can also link a Context tag (or a user-created type derived from a Context tag) to a map by adding the properties "Latitude" and "Longitude" to the parameter list. A Site Map is a standard part of the menu, and is built into every automatically-generated lift station details page and into the Site Details page. While you can add extra Site Maps to pages within your application using the Site Tools palette or the Menu, it is usually not necessary or beneficial to do so.

In addition to the Site Map page, maps are also an optional part of the Sites page and the Site details page. If viewed in a Sites page, you can choose to add a legend to the map. This is the Site Legend widget, which can be drawn on any of your application pages.

Use the controls at the upper right to zoom or to select the map style.

Set the location of a site:

To set the location of a site based on a Context tag, that tag must have Latitude and Longitude properties. See: Add Site Properties. in the description of the Context Tag.

While you could open a tag's configuration panel and type in Latitude and Longitude values, it is usually easier to click a location on the map. In order to do so, you must be viewing a single site using the Site Details page, or by drilling down to the site in the Sites page. When doing so, an Update Site Location button will be provided at the bottom left corner of the map.

Map scale controls

The currently selected site is indicated by a pulsing beacon. This is useful when the Show All Sites option is enabled, allowing more than the currently selected site to be seen.

Display Control

Use the scroll wheel of your mouse or the plus and minus buttons at the upper right corner of the map to change the scale. For each magnification level, a new set of map tiles must be downloaded to your workstation. A reset button is provided below the scale, allowing you to return quickly to the original display.

You can set a default scale factor for each site tag in the Site Display tab of its configuration panel.

Map scale controls

Sites:

Sites are displayed using markers, either the default pin or a shape of your own creation. Open the Site Map page for a specific tag to access the Update Location button to place or move the site.

Any of the following tags can be a site when configured to have Latitude and Longitude values, and to be shown on a map:

  • Context tags and user-defined types based on Context tags, if they have site properties.
  • Polling drivers.
  • DataFlow RTU drivers.
  • MultiSmart™ stations.
  • MPE™ Duplexer stations.
  • MPE™ SC stations.

Overlapping Sites:

It is typical for sites to be near together. At a close scale, it is easy to tell one from another, but when viewing a larger area, only one pin can be seen.

If sites appear to overlap, a click on the pin icon will open a menu of sites near that location. Choose the site that you want to view in more detail.

The setting SitesPageIconLoadTime is the time interval VTScada waits to see if a particular site icon has finished loading on a map. The default is 0.1. If this is too short, the following symptoms may occur. On a map with many site icons, if any icons overlap, clicking on the overlapping area might cause both of the site pages to open in addition to a site selection dialog. Increasing this timeout to 1 second can alleviate this problem.

Connectors:

Connectors are displayed as a line or pipe between two Sites. The color and style of the connector is configurable, but not the width. Connectors are displayed only when two sites with latitude and longitude values have been selected, and when the connector is configured to be shown. Only Context tags or user defined types derived from a Context tag can be connectors. A connector will remain visible if you zoom in to a map tile between two sites.

Because a connector is based on a Context tag, it can have user-defined properties and child I/O tags.

Slippy Map

The map is sometimes referred to as a "slippy map" because of the way it can be moved within its frame. Operators can pan and zoom to change the area displayed.

The map display is built of "tiles" - static images. At each higher magnification level, four times the number of tiles are used for a given area. As the operator moves the display or changes magnification level, new tiles must be downloaded. After being downloaded, they will be cached locally on your computer. These tiles are not distributed with VTScada, therefore your server must have an active Internet connection to be able to download tiles that have not been cached.

It is possible to switch from map view to satellite view, or to a different map provider. See the task list at the end of this topic.

Any instance of the tag types listed above can be located on a Site Map as a pin. Operators can click on the pin to open the associated Site Details Page. Instructions for create your own pin shapes are provided elsewhere. Refer to the list of tasks at the end of this topic.

The primary site associated with a map will be marked by an animated bubble. The head of the standard marker pin uses the same color-indication system as the Site Draw Drawing Method and described by the Site Legend widget.

(c) OpenStreetMap Contributors © [CARTO]

The copyright notices at the bottom corner of every map are each click-able links, allowing you to learn more about the source of the tiles you are viewing.

Map tiles are downloaded only once and cached on your hard drive. In a networked application, they are downloaded only the primary server. All other servers and workstations copy from there. If you believe that newer images are available, delete the files from sub-folders of C:\VTScada\Data\SlippyMapTiles. New tiles will be downloaded the next time you view the map.

Available controls for the map include: (*)

Control | Action
Show All Sites | A check box to enable or disable pin display for sites other than the root.
Update Site Location | After clicking this button, the next click within the map area will re-locate the site.
Magnification Control | (+) and (-) buttons. Provides a way to increase or decrease the magnification (zoom level) one step at a time.
Reset | A button below the magnification control slider. Resets the scale and location to the original view, as seen when the map was opened.
Map Selection | Opens a list of maps configured in your Setup.INI file.
Legend Display | Toggles the display of a legend describing the colors in a site icon (pin)
Click on any pin | Opens the Site Details page for that tag, as appropriate for the type.
Click and drag | Relocate the focus of the map.
Mouse-wheel | Zoom in or out.
Double-click | Zoom in, one step, at the location clicked.

(*) Some controls will not be available, depending on how the map is viewed.

Disable / Enable Maps

The VTScada installation wizard gives you an option of not using maps, but this refers only to Open Street maps. Carto® maps are always enabled.

To enable Open Street maps later, if you choose not to during installation, edit your Setup.INI file to change the value assigned to SlippyMapOSMDisable from 1 to 0, then restart VTScada.

To disable all maps, open your Setup.INI file and locate the [SlippyMapRemoteTileSourceN] sections (where N is a number from 1 to 4). Comment-out every property in each of the sections by adding a semicolon at the beginning of each line. DO NOT DELETE PROPERTIES. If you do, and then decide to re-enable maps, you will need to reinstall VTScada. Better to simply disable the properties by adding semicolons. Save the edited file and restart VTScada.


Change the Map Source

The default configuration of the Site Map page is a basic map showing roads and towns and using tiles from Carto™ / Open Street Maps™.

Click the Map Selection tool, available on any map, to choose an alternate tile source. A pop-up will open, showing a preview of each. Your choice of map is stored with your user account and will be the map you see regardless of which workstation you use. Other users can make their own selection.

As an advanced feature, it is possible to change the list of available maps as you see fit. You can change to another source, including:

  • Any other third-party provider of map tile images.
  • Satellite image tiles rather than map tiles.

You are free to edit your Setup.INI file to change map sources, add new ones, or remove options. Note that changes to Setup.INI do not take effect until VTScada is restarted. Map sources are stored in sections headed [SlippyMapRemoteTileSourceN] where N must be a number starting at 1 and increasing consecutively for each source.

Do not edit tile sources from CARTO, unless you are removing those sources. CARTO maps are supplied by licensing agreement and include an API key that is unique to each VTScada installation. API keys cannot be shared.

To disable all maps, edit your Setup.INI file to add a comment character (a semi-colon) to the beginning of every line in every SlippyMapRemoteTileSourceX section.

In all cases, the images that make up the map (or satellite view) are square tiles, downloaded to the folder C:\VTScada\Data\SlippyMapTiles\MapTypeN where N is a number starting at 1 and matching the number for the SlippyMapRemoteTileSourceN property.
Within each folder, sub-folders are used for each zoom level, with the numeric folder name corresponding to the zoom level. Map tiles should use the .PNG file format.

If you change the URL for a map source, you must delete all existing tiles from the previous source. New map tiles are downloaded only when not found on your workstation.

If a URL is not going to be used because you have a static tile set on a server, a URL must still be provided. Use a placeholder such as "Localhost".

A copyright attribution should be included with the tile source. This will become a click-able link on the map.

Procedure:

  1. Stop VTScada.
  2. Using a text editor, open the file, Setup.INI
  3. Search for [SlippyMapRemoteTileSource1]
  4. Copy the entire section changing the 1 to the next unused number and editing properties are required.
    (At time of writing this will be [SlippyMapRemoteTileSource5], but that may vary.)
  5. Save the file.
  6. Restart VTScada and run your application.

Default values for the second tile source:

[SlippyMapRemoteTileSource2]
URL1 = https://enterprise-a.basemaps.cartocdn.com/rastertiles/voyager/
URL2 = https://enterprise-b.basemaps.cartocdn.com/rastertiles/voyager/
URL3 = https://enterprise-c.basemaps.cartocdn.com/rastertiles/voyager/
URL4 = https://enterprise-d.basemaps.cartocdn.com/rastertiles/voyager/
Label = MapVoyagerLabel
APIKeyName = api_key
APIKeyValue = SAsfaFFKUUVfARJM2LzyE7d1LkENJ6udok5vmwejZWSoOe7glZ7zYSqJPLI3P3UP/
APIKeyEncrypted = 1
BulkDownload = 1
CopyrightURL1 = www.openstreetmap.org/copyright
CopyrightLabel1 = © [OpenStreetMap contributors]
CopyrightURL2 = https://carto.com/attribution
CopyrightLabel2 = © [CARTO]
Default = 1
BGColor = <FFC0C0C0>
Extension = .png

Do not skip numbers when defining tile sources. If you have [ SlippyMapRemoteTileSource1], [ SlippyMapRemoteTileSource2] and [SlippyMapRemoteTileSource4], then only the first two will be available for users to select.

Troubleshooting:

  • No map or satellite image is shown.

Check for typos in the setting of SlippyMapRemoteTileSourceN, where N is a number matching the selected map.

Ensure that the computer can connect to the Internet.

Related information:

[SlippyMapRemoteTileSourceN] Section - Discussion of each property within the SlippyMapRemoteTileSource section

MobileSlippyMapTilesSource1 - Control the location where map tiles are stored.


Bulk Downloads of Map Tiles

The tool to begin a bulk download of map tiles can be found in the Application Configuration dialog, Edit Properties page, under the Display tab (using the basic mode of the Edit Properties page).

Notes:

  • The button is enabled only while your application is running.
  • If the provider of your currently selected map style does not allow bulk downloads under their terms of service, you will be warned upon opening the tool. The start button will be disabled.

Depending on the area and the zoom level that you select, a bulk download can include nearly 450Mb of map tiles. The tool limits the area or zoom level or both so that no more can be downloaded in a single session.

Controls within the Bulk Download dialog

  • The larger map (to the left) defines the area for which tiles will be downloaded.
  • The smaller map (to the right) defines the zoom level.
    While not displayed numerically, zoom levels range from 2 (far) to 18 (near). The zoom level of this map must always be greater than or equal to the zoom level of the area selection map.
    (New York was chosen for the focus of this map because it contains detail down to the nearest zoom level, which may not be the case in your selected area. This does not affect the area for which you will be downloading tiles.)
  • Tiles will be downloaded for the entire area in the larger window, for all zoom levels from that shown in the area selection map down to that shown in the zoom level map.
  • The depth bar indicates the range of zoom levels that will be included, where the furthest zoom level (2) is to the left and the nearest (18) is to the right.
  • You can resize the Bulk Download dialog as needed to match the area selection window to the area of the map you are interested in.
  • The display of Total Tiles tells you the number and disk space required. The estimated time will update during the download.

To download map tiles in bulk:

  1. Ensure that the application is running.
  2. Open the Application Configuration dialog.
  3. Select the Edit Properties Page.
  4. Ensure that the Basic Mode is selected, and that you are viewing the Display tab.
  5. Scroll to find the Mapping section, then click the Bulk Download button.
    The Bulk Download dialog opens.
  6. Use the larger map (left window) to define the area for which tiles will be downloaded.
    Resize the overall dialog box as required so that the larger map shows only the area you need.
  7. Use the smaller map (right window) to define the zoom level to which tiles will be downloaded.
  8. Review the information displayed beside Total Tiles.
  9. Chose whether to overwrite existing tiles (refreshing the view if newer tiles are available) or not (reducing the time required for the download).
  10. Click the Start button.
    You may click Stop at any time to cancel the download.


Limit the Map Area

Users with the configuration privilege can limit the area and zoom factors allowed when viewing maps. Doing so will stop operators from spending time (and network bandwidth) browsing maps outside the area of concern for your SCADA system.

This feature is available only while the application is running.

You can define area limiting for the application as a whole using the Display tab of the Edit Properties page of the Application Configuration dialog. You can define area limiting for thin-client connections to a given realm using the Realm Display Setup tag.

Within the Set Area Limiting dialog, use the larger map to set both the permitted area and the minimum (furthest) zoom level. If the map does not show the full area that you need at your minimum zoom level, resize the Set Area Limiting dialog to allow a greater (or smaller) area.

Use the smaller, inset map to set the maximum (closest) zoom level. This map does not show content from your selected area. Instead, it uses a block from a large city, thereby ensuring that you will see "something" as you zoom in. For this map, the visible area is not relevant. Only the zoom factor is used.


Use Maps Without an Internet Connection

In many instances, VTScada will be running on a computer where internet access is forbidden or severely restricted. You can still use slippy maps by copying the map tiles that you need from a computer that has internet access to the computer that does not. The following method works because each time you view the same map again, VTScada will use the tiles that are in the cache, rather than pulling new copies from the Internet.

Due to licensing restrictions, Trihedral cannot supply map tiles. The files must be downloaded.

  1. On a computer that has Internet access and a copy of VTScada (possibly a trial version or VTScadaLight), view all map areas that will be required for your application. Ensure that you view all areas at all zoom factors.
  2. Copy the folder and sub-folders C:\VTScada\Data\SlippyMapTiles[N] (where N matches the map style you are using) to the station that does not have Internet access.

For networked applications, ensure that the map tiles are copied to the primary server. All other workstations and backup servers will copy their tiles from the current primary server rather than downloading the tiles from the Internet. If using the advanced mode of the Edit Server Lists dialog, look for SlippyMapService.

The names of the folders and the map tiles match the area and zoom factor viewed and are not unique to your computer or VTScada in any way.

VTScada will expect the map tiles to use the .PNG file format.

Troubleshooting:

  • The steps were followed, but the map is not displayed.

Ensure that the tile images are in the folder "Data\SlippyMapTiles" under your VTScada installation.

Ensure that you are attempting to view an area that matches what was saved in the map tiles.

Related information:

MobileSlippyMapTilesSource1 - Control the location where map tiles are stores.


Custom Map Icons

You can create your own custom map icons (pins). For example, you may wish to provide visual clues to help operators identify sites when more than one is displayed on a map.

Custom map icons showing flags rather than pins.

Each icon is a Tag Widget that you create. To function as a map icon, various parameters will need to be set and mapping-related VTScada widgets will need to be included. A pulse beacon will be added automatically for you. When an operator clicks your icon, it will open a site page (or your custom page). You do not need to add a hotbox.

VTScada will not add animation to the colors within your icon. If you want the functions of a Site Icon Widget, add one to your custom map icon. Be sure to edit the site icon widget's properties to useLinked Tag Properties. Alternatively, you could add an Alarm Priority Icon, or you could write expressions that will control the color of shapes within your icon.

This topic contains the following sub-sections: General Steps to Create a Custom Map Icon:, Use Your Custom Map Icon, and Key Details:.

General Steps to Create a Custom Map Icon:

  1. Create a new Tag Widget.
  2. When prompted to select tag types, choose only the types that this icon will be used with.
    For example, Context, Polling Driver or your user-defined types.
  3. When prompted for a name, choose one that will help you remember what the widget is for.
  4. Choose whether to keep the options of including operator interaction features and the Tag Icon Marker.
  5. Add the graphics that you want for your custom icon.
    See the following list of key details.
  6. Instruct your site tag to use that widget instead of the built-in pin using one of the following methods.

Use Your Custom Map Icon

There are four ways to select the custom map icon:

After changing the selected icon, you may need to refresh the map or update a site's location before the new icon will load in place of the old.

To use the icon for a specific site that has display / site properties.

  1. Open the tag's configuration folder.
  2. Within the Display tab, choose the custom map icon widget.

Note: this assumes that, when creating the widget, you configured it to be a tag-widget for the type of site you are now trying to configure.
If the site is a custom type, ensure that the type definition includes site parameters, including Custom Map Icon.

To use the icon for a group of sites that are the children or grandchildren of a specific Context tag:

  1. Ensure that the parent tag has been assigned the site display parameters.
  2. Ensure that the icon widget can be linked to all the child tag types.
  3. Set the Custom Map icon property to the name of your widget.

To use the icon for all instances of a given type of site

** For the following, note that the type name for a tag may differ from the name displayed in the Tag Browser. See:

Tag Names in Code

Similarly, widget names in code will match the file name of the widget, and may differ from the displayed name.)

  1. Edit Properties with the Basic Mode of the Application Configuration dialog to Add a Property to the [System] section of your Settings.Dynamic file.
  2. Name the property after the type of tag you are configuring by putting the type name in front of the keyword, "MapIconName".
    For example, PollingMapIconName or ContextTagMapIconName.
  3. Set the value of the property to the widget name
    For example MyMapIconsModuleName

To use the icon for all sites of all types:

  1. The widget must have been named and therefore stored in a file name, "CustomMapIcon".
    Note that this is the name of the widget, matching the file it is stored in. This is not its title.

Key Details:

Image or Shape:

You may wish to keep the following details of the default pin shape in mind while creating your new icon:
The default icon is approximately 30x30 pixels in size.
It uses a pin image that has a transparent background.

Pin Center:

The center of the new site icon's bounding box will be used as the pin location when shown on a map. The center's location is calculated using the bounding box of all graphics that make up the whole.

Pulse Beacon:

Automatically a part of map icons.

Site Icon:

If the widget is to indicate an alarm, or if the operator is to be able to click your custom widget to open a site map, then include a Site Icon. Within the properties dialog of the Site Icon, change "Tag" to "Linked Tag Property".

Parameters

Give your widget the following parameters to take advantage of all the available features. Parameter names need not match those shown here, but you are advised to use these names for clarity and simplicity. What does matter is the order.

Not all parameters need be created, but none can be skipped from the middle of the list. If your widget is to have a ZoomLevel parameter, it must also have the three preceding parameters.

DisableTrend

(Status) Should exist and be selected using the Values tool in the Widget Properties ribbon. This will prevent the HDV window opening when an operator clicks the icon to open a map.

DisableNavigation

(Status) Should exist if you want to allow developers to choose whether operators can right-click the widget to open the pop-up tools dialog.

DisableTooltip

(Status) Should exist if you want to allow developers to choose whether operators will see a tooltip with the tag's name and description when they hover the pointer over the widget.

ZoomLevel

(Short with allowed values ranging from 2-18) With this parameter, your widget can know what the current zoom level of the map is because VTScada will automatically set its value. The value, "2", corresponds to the furthest out that an operator can zoom on any map and "18" is the closest in.
A possible use for this information is to set the opacity property of component parts to use ZoomLevel in an expression that will be become zero, thereby hiding the icon, or portions of it, when the operator has zoomed past a given value.

ConnectorAngle

(Double with allowed values ranging from 0-360) If your site is configured as a Connector, this is the angle at which the connector is drawn, from the start site to the end site.

ConnectorColor

(Color) If your site is configured as a Connector, this the color of the connector.

Example:

  1. Open the Idea Studio
  2. Click the File button, then New
  3. Select Tag Widget.
  4. Provide a name for the widget.
    For simplicity of use, avoid spaces.
  5. Make note of the name.
    This is the file name, and therefore the module name that you must provide when using the icon. You may change the title of this widget later, but the file name will remain the same and will continue to be the module name.

Note: If you have previously created a page or widget of the same name, then the new file name will have a "0" or "1" appended to the end.

  6. Select all the types of site for which you might use the map icon (Polling driver, Station tag, custom types...).

The new widget will be created, and will open in the Idea Studio.

  7. Delete the Tag Icon marker (yellow diamond).
  8. Ensure that the Widget Properties ribbon is open.
  9. Click, Manage Parameters in the Widget Properties ribbon.
  10. In the Parameters tab, click Add.
  11. Set the name to "ZoomLevel," and the type to "Short".
    Any of the numeric options would work, but short is the most appropriate.
    A description is recommended.
  12. Click OK to save the new parameter and close the properties dialog.
  13. Add the image(s) that you wish to use for the pin.
    • For reference, the Site Icon marker is 14x14 pixels. A Pulse Beacon will extend to 82x82 pixels. Your pin should be somewhere within this range of dimensions.
    • You may wish to add a Site Icon to the custom icon pin. This provides a visual indication to operators, showing the status of the site and also allows them to click on the pin to open the related Site Page. Note that the Site Icon's data source must be linked to the Drawn Tag.
  14. Adjust the position of all objects so that the center of the overall bounding box of all objects coincides with the location that you wish to use as the pin-point. The location of the objects within the Idea Studio does not matter for custom map icons.

Put the new icon to use as described earlier in this topic.


Site Map Widget

VTScada has built-in links to site maps, both within the menu, and within Site Pages and Site Details pages. These are usually sufficient for most applications, but if you wish, you may add a Site Map to any page.

To add a site map to a page:

  1. Open the Idea Studio and the page to which you intend to add a map.
  2. Open the Site Tools palette (found within the Widgets palette section).
  3. Locate the Site Map widget and drag it onto the page.
  4. Provide parameters as appropriate. Parameters are described later in this topic.

Note that the map is drawn within its own window, which will have a higher z-order than the page it is being placed on. The result can be loss of part of the VTScada header or footer if the map is larger than the page.

Site Map Properties:

Parent

The station tag instance (and any child tags that also have valid latitude and longitude values) that is to be the primary target of this site map. All sites shown will be marked by a pin, but the root site will be further indicated by an animated dot.

Show All Sites

Choose whether this map instance should show only the root site, or if all sites visible in the map area should be shown. In either case, the pin marking the root site for the map is the only one highlighted by an animated bubble.

Use Theme

Choose whether the borders of the map should use the VTScada color theme

Text Color

Specify the color to be used for the labels below the map.

Disable Zoom Buttons, Disable Reset Button, Disable Style Button, Disable Legend Button

Use the listed controls to hide any of the tools labeled in the following image, which would otherwise be available on your map.
"Zoom Buttons" refers to the controls for the display scale. "Style" refers to the tool for map selection.

Map scale controls

Widget Folders:

Basic Components\Specialty\Mapping\

Tools\Site Tool Library\


Add a Site Map Page to the Menu

A Site Map page is included in the menu of every new application. You will need the information in this topic if you are upgrading an application that was created before version 10.1, or if you have removed the Site Map page from the menu and need to add it back. Other than those examples, it is extremely rare to need this procedure.

It is important to configure the parameters correctly. To have the page open with no parameters, and without prompting for parameters, you must ensure that the three choices are cleared.

The default parameters are as shown:

In nearly all cases, the default values will be the best to use, but you may adjust these as needed.

Parent: You may choose a specific site, or the parent of a set of sites.

Use Theme: This option controls whether the application's color theme will apply to the overall look of the Site Map page. This is recommended in most cases.

Text Color: Defaults to black (0 as defined in the VTScada color palette). You may choose any other number, or specify an RGB value.

It is expected that there will seldom be a reason to add additional Site Map pages, beyond the one already in the menu of every new application.

The Site Map page is a Site Map that fills an application page. The scale of the map will adjust automatically each time that it opens to display all sites within the application. When the site map is opened as a page, you cannot specify a root tag.


MapTiler as a Map Source

Any online map source that uses OpenStreetMap can be used for your map tiles. Instructions are provided in Change the Map Source.

One of the sources used by VTScada is MapTiler™. If you have a MapTiler account, you can download your choice of map tiles to create a static image set on your server, or you can use their online service if you are interested in a map style that includes vector or image data, including GIS information(*).

(* VTScada can use 3rd party software to generate map tiles that contain layers of map and GIS data. But note that as far as VTScada is concerned, these maps are only raster images. To display additional information about sites on your maps, refer to Design Your Own Tagsand Custom Map Icons.)

To generate a static image set using MapTiler™ Desktop:

This option is best if you wish to pay only a one-time fee for MapTiler™, or would like to add a custom image/vector set to a machine that is not connected to the internet. A trial of MapTiler™ Desktop is available at https://www.maptiler.com/desktop/

  1. After downloading and installing MapTiler™ Desktop, load in your image or vector-set and cross reference this with a real-map location if necessary.
  2. When asked for the output format and settings, choose “Folder with tiles”. Select "No" for transparency (and choose a background color, if desired), and select "png" for compression.
    Changes to any other settings are optional, but take note of the specified max and min zoom levels.
  3. Click “Render” and export to an empty folder.
    Inspect the preview to ensure that your work appears as expected.
  4. Create a new VTScada Map source. See: Change the Map Source.
    • To improve the look of the map, ensure you set the BGColor to the same color as was set when exporting the files from MapTiler™ Desktop.
    • If a URL is defined from which to download additional map tiles, these will not mesh seamlessly with those produced by MapTiler™ Desktop. This can be mitigated through Map Area limiting: (Limit the Map Area)
  5. If this behavior is not sufficient, consider using MapTiler™ Cloud.
  6. Copy the folder contents, excluding any .html and .json files, into your VTScada folder’s appropriate Data\SlippyMapTiles\MapTypeN folder
  7. Restart VTScada.
    On a page containing a map, navigate to the map location you have specified and choose the new map type you have created. Ensure you are at a zoom-level for which you have generated map tiles. You should be able to view your map. You can now add widgets on top of your custom map.

To use a custom full map style containing vector or image data using MapTiler™ Cloud:

This option is best if you are able to pay the subscription fee to MapTiler™, and would like to incorporate GIS data and/or images onto a full, custom styled map. A trial of MapTiler™ Cloud is available at: https://www.maptiler.com/cloud/

  1. First, add your custom data sources.
    1. To upload GIS/vector data, go to the data section, click New DataSet and then upload files.
      Upload your .geojson, .gpx, .kml, .shp or .zip shapefile.
    2. For uploading a custom image-set, use the MapTiler™ Desktop process described earlier, but choose “GeoPackage” or “MBtiles” output, rather than “Folder With Tiles”.
      In MapTiler™ Cloud, go the the Tiles section and click “New Tileset”.
      Upload the GeoPackage or MBTiles file you created.
  2. Create your custom map as follows:
    Navigate to the maps section of MapTiler™ Cloud.
    Choose one of the standard maps as a starting point and click to open it.
    Click "Customize a copy" and save the map with a name of your choice. (Make note of the name)
    You can perform some basic styling in this window, but to add your own custom data and images, click advanced editing and then convert.
  3. Add your datasources. Click Data Sources at the top of the window and add the layer(s) you would like to include in the map.
  4. Click "Add a layer"
    Give it an appropriate name and choose the way you would like it to be drawn.
    For custom images, choose Raster. For vectors, choose the appropriate type.
    Select your data source and add the layer.
  5. You can customize the way the layers appear on the map using the editor in this window. After you are done editing, click Save and then Close.
  6. To access the map in VTScada, navigate to your new nap and click Publish if the map is not already published.
    Look under the Raster tiles section on your map’s page and copy the 512x512 XYZ URL. This should contain “.png” somewhere within it, not “.json”.
  7. Create a new VTScada Map source.
    See: Change the Map Source and [SlippyMapRemoteTileSourceN] Section
  8. For the URL, paste that copied from MapTiler™ Cloud in the previous step and replace “/{z}/{x}/{y}” with “%Z/%X/%Y”. Optionally, you can cut the text after “key=” with “%KEY”, and paste it into the APIKeyValue field in the Setup.INI section. Ensure the APIKeyEncrypted is set to 0 in this case.
  9. Restart VTScada. On a page containing a map, navigate to the map location you have specified and choose the new map type you have created. You should be able to view your map. You can now add widgets on top of your custom map.

VTScada will download the map tiles only once and cache them for improved performance. If a change is made to the map in MapTiler cloud, these will not be brought into VTScada automatically. There are two ways to force a fresh download:

Navigate to the [VTScada Installation Folder]Data\SlippyMapTiles\MapTypeN folder and delete the contents. VTScada will download the necessary tiles as you browse maps.

Use of Bulk tile downloading tool and select the “Overwrite existing tiles” option. (Bulk Downloads of Map Tiles Bulk Downloads of Map Tiles.)

Note that VTScada uses a service to share map tiles between workstations in networked applications. In this case a Client or Backup Server will get their map tiles from the Primary Server, rather than directly from the URL.

An additional service is available from MapTiler™ called MapTiler™ Server. This allows a networked machine to act as the map server, rather than connecting to the cloud. This has the benefit of allowing custom map tiles served from an internal network, rather than using a cloud-based service. Tilesets and maps can be created on a source machine and uploaded to the server. Here the map service (raster tiles) URL can be used in the Setup.INI file for sourcing map information on your network.


Secure Your Application

Overview

Newly created applications run in an unsecured state until you decide that the time has come to secure them. When you first open the security dialogs, you must choose to secure the system and then create at least one account that you will use for managing it. From that moment on, all users (including you) must sign into the application to make any configuration changes.

After the application is secured, configuration is no longer available without signing in.

You can manage user accounts with VTScada or Windows or both.

  • If using VTScada authentication and authorization, all accounts and security privileges are managed within VTScada. The SCADA manager has full control over all aspects of each account.
  • If using Windows authentication, VTScada privileges are assigned only to roles, which are then associated with Windows groups. The Domain Administrator has control over creating and managing accounts, including which accounts are associated with which VTScada roles. The VTScada manager controls roles and the privilege set associated with each role.

Multifactor Authentication (MFA) / Two-factor authentication.
There are three options for this:
1) For those using the Anywhere thin client, you can configure OpenID Connect Authentication. Choose an OpenID provider that supports multifactor authentication. This option applies only to those will Connect Using the Anywhere Client.
2) For those using the VIC thin client or a workstation with VTScada installed, enable Windows Security Integration with Smart Card Support.
3) For those using a workstation with VTScada installed, the anywhere client or the VIC thin client who are looking for a multifactor authentication solution that does not require a constant, active internet connection, there is 2-factor authentication with TOTP (Time sensitive One-Time Password)

If you enable outside connections to your SCADA system then you must also take steps to secure the communication between the remote site and your server. This is done by implementing a Virtual Private Network (VPN) or by purchasing and installing a TLS/SSL Certificate. Refer to Internet Security (TLS, X.509, SSL).

The VTScada Internet Client (VIC), Anywhere Client, and the Mobile Browser Client (MIC) cannot access any application that is running in an unsecured state. Only a secured application will allow remote access and alarm acknowledgment via phone, email or text message, and then only to authorized accounts.
Similarly, you must secure your application before you can make use of the ODBC interface to query the VTScada database, or use the VTScada Excel Add-in. Note that the Excel Add-in cannot connect to a VTScada server that is not protected by a certificate.

"SSL" is the acronym for the Secure Sockets Layer security protocol. SSL is an older technology, but the term has become the de facto name for Internet security. VTScada uses the more modern Transport Layer Security (TLS) protocol (although, for the sake of compatibility with older Windows operating systems, it can use SSL.)
While the term "SSL Certificate" is in common use, "X.509 Certificate" is the correct term.

Privileges built into VTScada restrict access to VTScada features such as access to the built-in pages. To control access to your own pages and to operator controls that you build, you must create new privileges and apply them to the features that are to have restricted access. By default, all operator controls are protected from use when no-one is signed in, but most sites prefer to create a set of privileges so that they can control the access that each operator has.

Roles should be used to simplify account management, whether you are using VTScada or Windows authentication. A role is a named set of privileges and can be thought of as a job description. Changes made to a role's privilege set are automatically applied to the operators who have been assigned to that role. You can assign several roles to any account and one role can include another.

A set of functions and properties within the security manager are available to programmers, allowing them to check who is signed in or what privileges are in effect for the signed in user. With this information they can design their custom modules to enable or disable features for that user.

Terms:

General Privilege

A permission to access or use one of the VTScada system tools. Access to the Idea Studio, the ability to acknowledge alarms, etc., are controlled by general privileges.

Custom Privilege

A permission created by a VTScada developer. You can apply custom privileges to pages and to output tags to restrict access to these user-created items.

Alternate ID

A numeric identification associated with an account. Used to verify an account when signing in via the Alarm Notification System, or a proximity card reader. There can be only one alternate ID associated with any account.

Security Role

A named set of permissions. You can assign one or more security roles a user account to grant common privileges to people with similar job descriptions.

Security Rule

Refers to conditionally-granted privileges. You can limit the scope of a custom privilege so that it applies only to certain tags, or of any privilege be in effect only when a user is signed in at a named workstation.

Security Menu

Where you will find tools to open the various security-related dialogs. Available in the Application Configuration dialog in the Edit Security tab, and (after signing in) from the button at the top-right of the VTScada application window, labeled with your account name.

Account Locking / Multiple Sign-in Attempts

If a user fails to type their password correctly several times while attempting to sign in, their account will be locked for a period of time. This helps to protect your system from automated password-cracking programs. From the user's point of view, there is no difference between a sign-in that is denied due to an incorrect password and a sign-in attempt while the account is locked.

The number of incorrect attempts and the duration of the lock-out period are controlled by application properties. Refer to Security Property List in the table of contents for a list of all security-related properties. The locking time will increase gradually if an account is locked multiple times within a short period.

A trip alarm will be generated when an account is locked.

Trip alarms do not have an active or inactive state. Something has happened to trip the alarm, and that is all that matters. A trip alarm is not included in the list of Active alarms, but it is Current and must be Acknowledged. If you shelve a trip alarm, the act of unshelving it (or allowing its shelving time to expire) is equivalent to acknowledgment.

A security manager can use the Accounts dialog to view the time remaining before an account is unlocked and also to unlock that account immediately.

Disable Windows Controls (Kiosk Installations)

VTScada cannot disable access to Windows controls (file menu, close, minimize...) or keyboard commands (Ctrl-Esc, Alt-Tab, and Ctrl-Alt-Delete). This could be accomplished with a Windows logon script. Refer to:
https://docs.microsoft.com/en-us/windows/configuration/kiosk-single-app

Related information:

AccountLockoutTime

MaxFailedLoginAttempts

MaxRateFailedLoginAttempts


Best Practices for Security

SCADA Security Guidelines Manual

A best-practices guide is included with every copy of VTScada. This is a stand-alone document (not part of these help files), which can be found in the Documents sub-folder of your installation folder.
(C:\VTScada\Documents\VTScada_Security_Guidelines_Manual.html

The manual provides guidance for installing, commissioning, verifying and maintaining the cybersecurity-certified capability of VTScada in accordance with applicable IEC 62443 cybersecurity standards.

Do not assume that your site is too small to be worth hacking.

All SCADA systems are targeted by hackers. You are running a SCADA system. Your site is a target.

Design your pages and tag structures with security in mind.

You can save a large amount of work, and greatly reduce the number of custom privileges you will need by creating a well-organized set of roles and corresponding rule scopes.

Enforce strong passwords.

Use the available options to enforce strong passwords (minimum length, combination of letters, numbers and other characters). Advise operators against re-using passwords for multiple applications.

Whenever there is ever a security update for your version of VTScada, apply it as soon as possible.

Typically, vulnerabilities are published a short time after a security update is distributed. Hackers will immediately seek to exploit that vulnerability on sites that have failed to protect themselves by applying the update.

Protect your control objects with custom privileges so only designated operators may use them.

This will limit the number of operators who will have access to controls and pages.

Place operator controls on pop-up pages.

By placing controls on a pop-up page, you reduce the chances of an operator accidentally issuing a control action.

Pop-up pages can also be used strategically to restrict access by applying a custom privilege. Only users with the custom privilege will have access to the pop-up. Use with caution: this approach is not effective if users with the "Control Outputs" privilege also have "Tag Parameter View Privilege". Such users will still be able to operate tags from the Tag Browser, and are not limited to widgets within pop-ups and pages.

Use care when granting the Thin Client Access privilege and configuring a VTScada Thin Client Server.

VTScada cannot secure the networks between the remote client and the server.
Thin clients transmit the user credentials (username and password) using Basic Authentication, which is a simple non-encrypted Base 64 encoding of "username:password", and which is easily decoded by capturing network traffic.
It is essential that you use an X.509 certificate (commonly referred to as an SSL certificate*) to secure the communications from packet sniffing software connected to a local machine or switch. Do not overlook the possibility that attacks might originate from within your trusted network.

The use of a VPN is a reasonable second choice.

*Transport Layer Security (TLS) replaced Secure Socket Layer (SSL) security years ago.

If allowing Thin Client access, test the TLS connection using 3rd party tools, looking for weak ciphers, etc.

Smaller sites that do not have a dedicated IT department may need to find a contractor to help with this.

Do not grant privileges to the Logged Off account. (Exceptions may apply in rare circumstances.)

Do not grant unnecessary privileges to any account or role.

Configure the VAM to be hidden while the application runs to prevent access to the various diagnostic utilities by unauthorized persons.

This action is recommended for all sites. Use the "Other" tab of the Edit Properties page of the Application Configuration dialog to hide the VAM from all who do not have the required privilege, while the application runs. (see Hide the VAM).

Secure the Source Debugger and other diagnostic applications

This step is urged for sites that may prefer not to hide the VAM.

Before running the Import File Changes tool in the VAM, review the list of changes that will be imported using the Import/Export files tool of the Application Configuration dialog.

Note that the Import/Export tool will not add new files to your application. For that, you must use the File Manifest.

Consider running VTScada as a Windows™ service and using only thin clients to access applications.

This option provides maximum control over the choice of account under which VTScada runs, its permissions, and user-access to applications.

Use Windows security techniques to prevent unauthorized persons from accessing the VTScada program directory. Keep the workstations that are running VTScada in a secure location.

All other security measures are in vain if someone can destroy your application by deleting files or taking a hammer to the server.


Activate Security

To activate security, you must open the Accounts dialog and create an account having the Manager privilege.

Open the Accounts Dialog:

Within the application:

Within an application, click on the Sign in button at the upper-right of the screen. After you sign in, this button displays your user name instead of "Sign in". Click this to expand the security menu.

The examples within this chapter use this method to access VTScada's security features.

The Security Menu provides access to
security dialogs within the application

From the VTScada Application Manager (VAM)

Select the application and click on Properties.

In the Application Configuration dialog that opens, select the Security entry in the menu.

Security menu within the Application Configuration dialog

Within the Page Properties ribbon of the Idea Studio

Open the Idea Studio

Select the Page Properties ribbon

Expand the Page Security drop down and select Secure Application.

Security menu within the Page Properties ribbon

In all cases, you will be prompted for whether you want to activate security. Choosing Yes allows you to proceed, but security is not activated until you have your first account with the Manager privilege.

The first step in securing an application

Create the first account:

After selecting Yes to proceed, the Account dialog will open. Use this to create a manager's account, which you will then use each time you want to create or modify other user accounts.

You may configure the initial account with any username, password and privilege set that you want, but if you remove the Manager privilege your application will not be secured. The privileges Administrator, Configure and Application Stop are also suggested (and initially configured) for this account.

The Accounts dialog with an initial (example) manager's account

Use care when granting privileges. In general, it is safest to grant only the privileges that are absolutely required.

Troubleshooting:

  • The Apply button is not enabled. You cannot save the new account.

The account name is missing or matches an existing account.

The password is missing or has not been verified.
Ensure that you press Enter or Tab after typing each word.

  • After creating the account, you see more (or fewer) dots than characters entered for the password.

This is by design, to hide the number of characters in the password.

  • You have forgotten a password.

A manager can reset an operator's password.

Do not forget the password for the manager account.

To Deactivate Security

If an application does not have an active account with the Manager privilege, then it will return to the unsecured state. All other accounts will remain but will not be required.

If your application uses Windows Authentication and does not have locally defined accounts, then deselecting that option in the Administrative Settings dialog will deactivate security.

You can return an application to the unsecured state by removing or deactivating all the accounts that have the Manager privilege. Warning messages are displayed before the application is unsecured. For example, if you delete the final account the following dialog will appear:

Warning before the application is unsecured

Click OK to continue. The application will return to the unsecured state.

Goodbye message

Reactivate security using the same steps that activate security. Existing accounts continue to exist. The account you create to reactivate security must differ from any existing account.

Troubleshooting:

  • I deactivated the manager account, but security is still enabled.

There is still at least one account having the manager privilege.

  • After deactivating security, I cannot use the VTScada Internet or Mobile browser client.

Remote access is allowed only to an application that is secured.


Accounts and Roles

If your application uses Windows Security Integration, refer to implementation notes in the topic: Windows Security Integration

Accounts

When security is enabled, everyone who uses the application must have an account. The account is used to identify and authenticate the user, hold the list of granted privileges, and store features that are unique to the user such as a custom automatic sign out period.

Use care with special characters in account names and passwords. While valuable from a security standpoint, some characters may cause problems with certain Alarm Notification devices.

It has been reported that an @ symbol (and possibly others) in a password will not work with the Twilio® interface.

Reopen the Accounts Dialog (one of several ways)

Features of an account:

It's easier to work with one section of this dialog if you minimize the other sections.

General section

Realm: Only if realm logins are enabled. Identifies the user's realm.

Username: Identifies the user.

Password section

Password: Used to authenticate the user.

Force Reset: When creating accounts for operators, it is standard to require that they change their password on first sign-in.

Advanced section

Disable option: Prevent sign in without deleting that account.

Alternate ID: For installations that include the Alarm Notification System. The numeric password they will use when signing in by phone.

Default sign out time period: Set between 0 and 720 minutes if the default time period does not apply to this user. Zero means no automatic sign out.

Multi-Factor Authentication

See Two Factor Authentication with TOTP for information about this topic.

Privileges section

Roles: The "job descriptions" that apply to the account.

Privileges: Additional rights specific to this one account.

Recommended practice is to assign privileges to roles, then assign roles to accounts.

A sample Accounts dialog after the first account is created.

If security realms are enabled, managers who are members of a realm can see only those accounts and roles that are within the same realm.
If using security realms, it is important that you keep one manager account with no realm membership.

Roles:

Similar to an account, but defines the privileges required by a job description rather than defining an individual. Account management is greatly simplified by defining roles for tasks, then assigning those roles to accounts. Changes made to a role are applied immediately to the accounts that hold the role.
You can assign roles to other roles, and multiple roles to an account. Privileges are additive, meaning that the account will gain all privileges defined in all assigned roles.

It is not possible to sign into an application using a role.

To help you configure a new application, several roles are built in. (Built-In Roles) These are examples, containing sets of permissions for various possible job descriptions. While useful to help you start your security configuration, you should plan to modify or remove the built-in roles and add your own as required.

For sites using Security Realms, you have the option of making roles at the root level visible to all realms. Doing so can greatly reduce the number of roles you need to create for your various realms.
Otherwise, managers within a realm can see and assign only those roles that are part of their realm.

Features of a role:

  • Realm: Only if realm logins are enabled. Identifies the role's realm.
  • Name: Identifies the role. Roles have no other authentication information.
  • Description: Contextual information about the role. May describe the role's intended use.
  • Disable option: Immediately removes the privilege set from all accounts that have this role, without needing to delete it. You cannot assign a disabled role to accounts.
  • List of assigned privileges and roles, and the tag or workstation scope that those apply within.

Default privileges for the Operator role

The predefined roles:

Privileges associated with the built-in example roles.

Role | Privileges allow...
Logged Off | Nothing. Logged Off is a special role, defining the privileges in effect when nobody is signed in. You cannot assign this role to accounts and cannot delete or rename it. You can grant privileges to this role, such as the ability to view the alarm page, but be very careful.
Operator | Acknowledge and mute alarms. View all of the VTScada system pages. Create and edit page notes.
Configurer | Operator plus all privileges required to create and configure an application
SuperUser | Configurer plus security configuration privileges. All VTScada privileges except Thin Client Access, Remote Data Access, and Modify Types, which must be granted explicitly.


Create Accounts and Roles

If your application uses Windows Security Integration, refer to implementation notes in the topic: Windows Security Integration

Use the Accounts dialog to create and manage all accounts and roles. Your account must have the Manager privilege. The following instructions are for creating an account, but apply identically to creating a role, excepting that roles do not have passwords, alternate identification or automatic sign off periods.

Reopen the Accounts Dialog (one of several ways)

Recommended practice is to assign privileges to roles, then assign roles to accounts.

The Accounts dialog. To open for the first time, click Sign In and choose to activate security.

There are several ways to create an account or role.

  • Create a new account or role
  • Copy an existing account or role
  • Copy a role to an account
  • Copy an account to a role

If a manager is a member of a security realm (Security Realms), any new user accounts and roles created by that manager will automatically belong to the same realm. In this case, you must enter new user names as simply "UserName" rather than "GroupDelimiterUserName".
Managers who are members of a realm cannot see accounts or roles that are not also members of the same realm.
Use a manager account that is not a member of a realm when creating roles, unless you need roles that exist only for a specific realm.

If an asterisk is visible beside the name of an account or role, the changes have not been saved. Use care when closing the dialog.

Naming Rules for Accounts and Passwords

  • Account names cannot begin or end with spaces.
  • Do not use the following characters in VTScada account names:

" \ / [ ] : | < > + = ; , ? * @

  • The following characters are not allowed in Windows account names: (spaces are accepted but not advised)

" / \ [ ] : ; | = , + * ? < >

Use care with special characters in account names and passwords. While valuable from a security standpoint, some characters may cause problems with certain Alarm Notification devices.
* As an example, it has been reported that many symbols other than letters and numbers in a password will not work with the Twilio® interface. To be safe, use only alpha-numeric symbols in account passwords.

Create a new account or role:

  1. Right-click in the list of accounts and select "Add User" or click the Plus button above the list of accounts.
    The same tools are found in the Roles section, immediately below the Accounts section.

Either technique works to create a new account or role.

An asterisk appears, marking the place for the new account or role.

The asterisk is used to mark any account that has unsaved changes. You can switch between accounts to compare settings without losing changes made so far, and without losing track of which account has unsaved changes.

  2. Enter a name for the new user.
    Similarly, enter a name if creating a new role.
  3. Enter and confirm a password.
    Does not apply to roles.

You might wish to make this password a temporary, generic password and have the user change it when they first sign in. Users do not need the Account Modify privilege to change an expiring password, but they will need that privilege to change their password at other times.

Copy an existing account or role:

Creates a clone of the account or role, differing only in name and (in the case of accounts) password. Useful when creating a series of similar accounts or roles.

  1. Click once to select the account to copy.
  2. Right-click to open the menu, then click "Copy User" or click the Copy button.

Again, the same applies if copying a role.

An asterisk will appear in the user list, marking a place for the new account or role.

  3. Enter a name for the new account or role.
  4. Enter and confirm a password.
    Applies only to accounts.

The new account or role will have all the privileges and other settings of the old account or role.
For accounts only, if the original used Alternate Identification, you will need to create a unique password for the new account.

Copy a role to a new user

Creates a new account having all the privileges that belonged to the role. This is not recommended as it is far more efficient to create a new account using one of the preceding methods, then assign the role.

  1. Click once to select the role to copy.
  2. Right-click on the role to copy and from the menu, select "Create User From Role" or, select the role then click the Copy button at the bottom of the list.

An asterisk will appear in the account list, marking the place where the new account is being added.

  3. Enter an Account Name for the new user.
  4. Enter and confirm a password.

Copy an account to a role

Creates a new role, having all the privileges that belonged to the account. This is useful if you originally assigned privileges to the account and now wish to manage rights using roles instead.

  1. Click once to select the account to copy.
  2. Right-click on the account to copy and from the menu, select "Create Role From User" or, select the account then click the Copy button at the bottom of the list.

An asterisk will appear in the user list, marking the place where the new role is being added.

  3. Enter a name for the new role and apply changes.

Delete an account or role

Select the account or the role then click the trash can (delete) button below the list. Note that nothing is deleted until you press Apply. Deleted roles will remain visible in other parts of the dialog until the change is applied.

If you delete the last account that possesses the Manager privilege, your application will return to the unsecured state. You will be warned.

Duplicate User Names

VTScada will not allow two accounts with the same name. The following warning dialog is displayed and the second account not saved.

Troubleshooting:

  • Unable to open the Accounts dialog.

Your account does not include the privileges required to use this feature.

  • The New and Copy features will not work

Your account does not include the privileges required to use these features.

  • A "Discard Changes" dialog appears whenever I try to close the dialog.

Click Apply before trying to close the dialog

  • Wrong name given to the account or role.

Click on the Name field, type a new name, then click, "Apply".


Assign Privileges

While you could add privileges directly to accounts, you are advised to add privileges to roles instead, then add roles to accounts. Used this way, roles define job descriptions. If you add a new custom privilege for a job description, you need only add it to a role to grant to everyone holding that role.

Privileges control what each user is allowed to do within VTScada. (System Privilege Reference for Developers) By default, all new accounts (other than the very first one) start with no privileges. A user who possesses the Manager privilege can choose what privileges to add (or grant) to each account.

Of the four roles that come with VTScada, three are intended as examples. You are advised to modify (or delete) these and to create your own roles. The process for creating new roles is identical to the process for creating new accounts.

The fourth role, Logged Off, belongs to VTScada and cannot be removed or renamed.

When managing privileges for a user or role, you can gain more space by minimizing the General, Password, and Advanced sections:

The Accounts dialog with General, Password, and Advanced sections minimized.

While VTScada comes with a large set of privileges, most of these protect only VTScada features.
Control Outputs is the exception, designed to protect all of your output tags from use when no-one is signed in. It is granted by default to the sample Operator role.
If you want to control which outputs are available to which operators, you must create custom privileges. See: Protect Pages and Output Tags.

Add versus Manage

Use either dialog to add privileges to an account or to a role. The difference is in the information presented.

  • Add is the most straightforward, but least informative. It shows a list of only the privileges that the account or role does not have. Select those that you want to add.
  • Manage also allows you to add privileges, but is far more informative after you know the symbols. All privileges are shown. Those that the account or role already has are marked according to how the privilege was assigned.
    With the Manage dialog, you can remove privileges that were assigned directly, but not those granted by virtue of membership in a role.
    You are advised to remove direct assignments of privileges that are also granted by role membership.

Custom privileges are discussed in Protect Pages and Output Tags.

The Add Privileges dialog, as seen for the default Super User role.

The Manage Privileges dialog, as seen for an account that is
a Super User and also has the Thin Client Access privilege.

The following tools and symbols apply to the Manage dialog:

  • A selected check box to the left of the privilege name indicates that the privilege is granted directly.
    You can select and deselect privileges here.
  • A green check mark indicates that the privilege is granted, either directly or by virtue of role membership.
    This is an indicator, not a control.
  • A people symbol indicates that the privilege is granted by virtue of role membership.
    You cannot change this using the Manage dialog.

Recommended process for assigning privileges:

Preparation: Define the roles.

  1. Select each of the default roles in turn and click the Manage button to review the assigned privileges.
  2. Add or remove privileges in those roles as you see fit.
    (Warning: think carefully before adding privileges to the Logged Off role.)
  3. Optionally, change the names of the roles as you see fit.
    (You cannot change the name of the Logged Off role.)
  4. Create new roles, named for job descriptions at your site, where each role will require a different set of privileges.
    A role should not encompass multiple job descriptions. You can assign several roles to an operator who does more than one job.
    (See: Create Accounts and Roles)
  5. For each new role in turn, use the Add dialog to assign privileges to that role.
  6. Review your work, carefully considering whether each role has the privileges it will require and no more.

Assign roles to accounts:

  1. Create an account for each operator and developer at your site.
    (See: Create Accounts and Roles)
  2. For each account, select the roles matching the jobs that person will perform.

Assigning roles to an account.

For sites that use Windows Security Integration, the process is similar but performed by an IT administrator using Windows Active Directory groups to map user accounts to VTScada roles.

Related information:

System Privilege Reference for Developers


Configure Alternate Identification

A numeric PIN, used with the Alarm Notification System so that operators can sign in with their phone.

Alternate Identification is the same, whether your system uses VTScada authentication or Windows® authentication.

Alternate identification is required by accounts that may sign in using a telephone using the Alarm Notification System or by using a proximity card reader. A

Any account can have only one alternate ID. If a user requires Alternate Identification and your site uses Proximity Card Readers, you must create two accounts for that user because the credentials are stored in the same space.

Sign in using an account that has the Manager privilege to configure user accounts.

Set an Alternate ID for the Alarm Notification System

  1. Open the Accounts dialog and select the user.
  2. Expand the Advanced section if it is not visible.
  3. Click the Set button in the Alternate Identification section.

Alternate Identification is configured in the Advanced section of the Accounts dialog.

The Set Alternate ID dialog will open:

A configured Set Alternate ID dialog

  1. Type a series of numbers into the Alternate Identification field. A dot will appear for each digit.
    These are the numbers that the user will press on their phone to verify their identity to the Alarm Notification System.
    The status field will update to tell you whether the identification is valid. No two users may share the same alternate identification.
  2. Type the same series of numbers into the confirmation field and press enter or tab.
  3. Click OK to save and exit.

Set an Alternate ID for a proximity card reader:

  1. Install a proximity card reader.
    This is done outside VTScada. Follow the manufacturer's instructions.
  2. Open the VTScada Application Configuration dialog, Edit Properties page.
  3. Set the application property, pcProxEnable to 1.
    VTScada will scan for the device.
  4. Close the Application Configuration dialog.
  5. Open the Accounts dialog and select the user.
  6. Swipe that user's proximity card through the card reader.
    (Do not open the Alternate Identification dialog.)

You may want to sign out, then swipe the card again to verify that it will work to allow the user to sign in to their account.


Security Realms

VTScada provides the ability to create security realms (referred to as "user groups" in earlier versions). Realms must exist on a hierarchy under at least one layer of management that is not assigned to any realm. A manager who is part of a realm (A realm manager) can see only the roles and accounts that belong to the realm they belong to. All new accounts and roles created by a realm manager will automatically belong to the same realm. A manager who is a member of a realm cannot change or remove their realm membership.

Realms, intended for large hierarchies, must be administrated by at least one user with account privileges that are not restricted to a realm. If you have only one manager account, DO NOT assign a realm to that account. A user with administrator privileges who has been assigned to a realm will no longer have access to Administrative Settings via the Options button in the drop down menu from the user account in the application or via the Application Configuration menu.
If you disregard this warning, you can recover using the Version Control system.

The account, Kelly, is being created by a manager who is a member of realm, Zone 1
There is no choice but to assign Kelly to the same realm.

Why Create Security Realms?

In general, security realms are used by larger organizations with clear separation of duties between groups of users. If using realms, you can expect the following:

  • Managers in a realm can access only user accounts and roles in the same realm. Useful for larger organizations with layers of management.
  • A manager who is part of a realm can no long access administrator security settings for the application.
  • You will be able to use Realm Filtering to restrict user's access to alarm lists and tag lists.

Why Not Create Security Realms?

  • The use of security realms requires some extra work during configuration. If creating manager accounts within a realm, it is necessary to populate the realm with it's own roles.
    A manager within a realm cannot see the root-level roles unless those have been configured to allow visibility across realms. A manager who is not part of a realm can see all roles and may assign the root-level roles to any account without restriction.
    (Roles for one realm should not be assigned to accounts in another realm.)
  • When security realms have been enabled, Thin Client sign-ins can be done only to an Internet realm matching the user's security realm. Use the RootNamespace property to designate an Internet realm for users who do not belong to any security realm.The value of RootNamespace must not match any defined security realm. 1
  • Both management of ODBC connections and integration with Windows Authentication will require more steps, meaning more chances for mistakes.

You can allow users to set their own filters for tag and alarm lists without defining security realms. Refer to Global Tag & Area Filtering.

When security realms are in use, the sign in process will begin with a prompt for the user's realm before asking for their username (account name). Users who are not a member of a realm can use the tab key or the arrow to step past this.

Step 1 of a regular sign in versus a realm sign in.

Security Realms and Realm Filtering

Security Realms are a key part of Realm Filtering, which is a VTScada feature that:

  • Restricts the display of alarms to those in areas or tags assigned to the user's realm.
  • Restricts the tag browser, limiting the list of tags displayed to those in areas or tags assigned to the user's realm.
  • Restricts the selection of tags available for reports to those in areas or tags assigned to the user's realm.
  • Restricts the selection of tags available for the Historical Data viewer to those in tag areas assigned to the user's realm.
  • Restricts VTScada Thin Client access for the application, forcing users to log into a realm that matches the name of their security realm.

Enable Security Realm Configuration

Security Realms are enabled by changing two application properties using the Administrative Settings dialog. (To open, select "Options" within the security menu.) You must have the Administrative privilege and be a root level user(not part of any realm).

Enabling security realms with the standard delimiter, a semi-colon.

The realm delimiter must be a symbol (neither a letter or a number). While several symbols will work, you are advised to use a colon, which will serve reliably in all situations. You must define the realm delimiter before you can select the option of using separate realm-entry during sign in. Remember that it is necessary to press tab or enter after typing in a VTScada text field.

Do not use characters that could also be part of account names as the NameSpaceDelimiter. For example, a dot is typically part of an account name for any system using Windows Authentication.
While several characters are legal, you are strongly advised to use a colon, which will work dependably in all situations.

Within Settings.Dynamic, these properties are stored as:

  • NameSpaceDelimiter= User Realm Delimiter.
  • GroupLogin = Separate Realm Entry During Sign In

Create Security Realms & Assign Users to Realms

These two tasks are the same. Realms are created while being assigned to user accounts.

Do not name any realm, "Rest" or "SQLQuery". Doing so will interfere with remote access to VTScada data.

If using Windows Security Integrationand Security Realms, you must add the realm name and prefix to the account using the VTScada accounts dialog. (e.g. realm:username@company.com)
AutoAddADUsers cannot be enabled when a security realm delimiter is defined.

A realm user is one who is associated with a specific security realm. The Realm option is available only after completing the steps described earlier in this topic. (See NameSpaceDelimiter Property above). Realm names are stored as part of the user name, separated by the NameSpaceDelimiter character. (For example, Western:Chris)

When a realm user signs in, they will be prompted for their realm before they can enter their username. Superusers, who do not have a realm, can step past the realm field, leaving it blank.
If signing in with a VTScada Thin Client, users must connect to a realm name that matches their security-realm. You must ensure that the realm is configured in the VTScada Thin Client Server.

Super users, who are not members of any realm, will not be able to sign in via the Internet unless the application property RootNamespace is added, and its value set to the name of a thin client realm created for the use of these accounts.

Visibility of Root-Level Roles With Realms

By default, users within a realm can see only the roles that are also within the same security realm. You can choose to allow roles at the root level (those that are not part of any realm) to be visible (and therefore selectable) within realms. Do so within each role:


Protect Pages and Output Tags

With one exception, Control Outputs(*), the general privileges protect only what is built into VTScada, not anything that you create. You must create custom privileges to protect what you build. (Steps are provided in Restrict Access to a Page, and Restrict Access to Output Tags.)

(*) The general privilege, Control Outputs, is applied to every tag by default, but is not shown in any tag's Properties dialog. If a tag is not otherwise protected by a custom privilege of your creation, then it is protected by Control Outputs instead (but not both).

These privileges are referred to as "custom privileges" because they are always custom-built for an application. (In earlier versions, they were known as "application privileges")

A custom privilege applied to an output tag will prevent an unauthorized user from operating the associated controls, but still allow them to see the tag. A custom privilege applied to a page will prevent an unauthorized user from opening the page, thereby hiding its contents from view.

As a suggestion, ensure that the start page for your application is one that may be viewed freely when no-one is signed in.

Users with the Administrator privilege can create custom privileges within the Privileges dialog. You can also use this dialog to suppress general privileges so that they cannot be seen in the Accounts dialog, thus preventing anyone (including yourself) from granting that privilege to an account or role while it is suppressed.

You can create hundreds of privileges if necessary. But, before creating large numbers of privileges, you should consider whether rules that limit a privilege by scope or workstation might help you keep the number to a manageable level.

For programmers: Every general privileges has a negative index number starting at -1. User privileges have an positive index number, starting at 16. The index number can be seen in the Privileges dialog, available from the security menu.
See also: System Privilege Reference for Programmers

Add new privileges

Only users who possess the Administrator privilege can add new privileges.

To create or change custom privileges:

  1. Sign in to the application using an account that has the Administrator privilege.
  2. Click your name (formerly labeled "Sign in").
  3. The Security menu expands.
  4. Click Privileges to open the Privileges dialog.

  5. Click the button labeled New Privilege.
    A data-editing field opens in the Custom Privileges list, pre-filled with the name "New Privilege".

Section of the Privileges dialog with numbers shown.
For instructions to suppress general privileges, see Suppress or Reveal Privileges

  6. Replace the default name with one that is appropriate for the privilege's purpose.
  7. Press the Enter key to save the new privilege name.
  8. You may repeat these steps for as many new privileges as required.
  9. Click the Apply button when done before closing the dialog.

Privileges are not granted automatically to any user account, including your own.

New section

Create named dividers within your list of custom privileges. This can be helpful for organizing privileges by purpose so that they are easier to find. The structure you create will also be used in the Add Privileges dialog when granting privileges to accounts or roles.

Privileges and sections can be reorganized using the up / down arrows at the bottom right of the list.

Sections can be indented so that they appear as sub-sections, using the left / right arrows

on the selected section.

Two custom privileges, each in its own section.

Rename or delete privileges

You can rename a custom privilege by double-clicking on it within the Privileges dialog (or by selecting it and clicking the pencil icon) to open the editing field, then typing over the old name. Because applications privileges are tied to tags, pages and accounts by an identifying number, changing the name has no other effect.

There is no delete button for the list of privileges. If one becomes obsolete, rename it and use it for a new purpose, or rename it to "unused".

Troubleshooting:

  • Difficulty entering the new privilege name.

Ensure that you click within the name entry field before starting to type, and press <Enter> or <tab> after typing the name.


Restrict Access to a Page

You can deny access to pages for unauthorized users by applying a custom privilege to the page. Only users who have been granted that privilege will be able to open the page. Further, users with configuration privileges will not be able to access the page's properties and will not see it in the Idea Studio if they do not also have the required privilege.

Privileges required to open a page (or perform any other native VTScada operation) must not be limited by tag scope rules. Pages are independent of tags, therefore if the privilege has a tag-scope rule applied, the result is to deny access to the page for that account.

  1. In the Idea Studio, open the page and its associated Page Properties toolbar.
  2. Click the Security tool.
  3. Select the privilege, Pump Page, which you created earlier for this purpose.

If you have not yet created a custom privilege, you may click Manage Privileges to do so.

A related feature is the application property, DisableGoToPage. This disables the right-click GoTo Page feature, available in alarm lists, among other places. Not required if you have restricted access to the page using a custom privilege, but might be useful if page security relies only on making it difficult for operators to reach a page by hiding navigational controls.

Troubleshooting:

  • There is no privilege to apply.

Create a custom privilege to apply to the page.

  • The page was open, but vanished immediately after the privilege was selected.

Your account does not possess this custom privilege. You will need that privilege to open or make any further changes to the page.

  • Operators have been granted the matching privilege to open the page, but cannot do so.

Ensure that the privilege has not been limited by a tag-scope rule in the operator's account or the role that provides the privilege to the operator. (Rules for Privilege Scope)


Restrict Access to Output Tags

The built-in Control Outputs privilege will disable writes from all I/O tags when no-one is signed in. This is a general privilege that is granted to the Operator role by default.

Feature | Effect | Use... | Reference
Security Privileges | Control who is allowed to write to an output. | Use in all applications | Restrict Access to Output Tags
Control Locks | Prevent use and operation of selected equipment via the VTScada screens. If the tag is protected by a privilege, users must also have that security privilege. | Only where there is a need to lock controls for all users, regardless of privilege. | Control Locks
Control Tokens | Ensure that only the current token owner can write to an output tag. Users must also have the required security privilege and the tag must not be locked. Only one user at a time can hold a Control Token. | Only where there is a need to restrict control to one operator at a time. | Control Tokens

Most sites prefer to create a set of custom privileges in order to have control over which tags are available to which operators. You can assign a custom privilege to any tag that can write values to equipment. Anyone may view a control widget linked to that tag, but only users who have the correct privilege can use it to write a value to the PLC or RTU. (A user does not need the Control Outputs privilege in addition to their custom privileges.)

You can also assign a custom privilege to protect certain operational tags. These include Modem, SMS Appliance, and Trigger tags.

When used with tags, custom privileges may be further defined by a rule scope. Under this system, an operator who has the matching privilege can use it only for tags in a defined scope. For example, the operator may be allowed to operate eastern-zone pumps, but not western-zone pumps even though the same privilege protects both.

As an alternative to creating a set of privileges for your output tags as described in this topic, you might try the following instead.

  1. Ensure that no roles (including Operator) have the Control Outputs privilege.
    This method works only if no role has the Control Outputs privilege without a scope-limiting rule.
  2. Create a set of roles matching sets of tags that operators will have access to. (Northern Operations, Generator A, Station 1, ...)
  3. For each role, assign the Control Outputs privilege, but add a scope-limiting rule to restrict that privilege to only the tags that the role-holder should be able to control. See: Rules for Privilege Scope.
  4. Assign roles to operators as appropriate.

To restrict access to output controls:

  1. Open the tag's configuration dialog.
  2. Search the tabs for a drop-down menu titled "Privilege".
    The precise location of the Privilege setting depends on the tag type.
    For example:
    For I/O and Calculations and the Analog Status tags, it is found in the I/O tab.
    In a Multi-Write tag it can be found in the Activation tab.
    In a Trigger tag, the Options tab.
    and in a Digital Status tag, it can be found in the Quality tag.
  3. In the Privilege drop-down control, select the custom privilege that was created earlier for this tag.
  4. Click OK to save your work.

This is just one example of a tab containing the Privilege setting. Your dialog may look different.

Troubleshooting:

  • There is no privilege to apply.

Create a custom privilege to apply to the tag.


Rules for Privilege Scope

A "rule" is defined as a limit placed on a privilege. The operator may have the privilege of acknowledging an alarm for a pump, but only pumps under one context (station or site) within the Tag Browser. Or, only when signed-in at a certain workstation.

Tag Scope Rules

Security rules can be thought of as a simpler form of Realm Filtering. They are especially useful when you have organized your tags into parent-child hierarchies that group similar parts of the application together. For example, a city utility may have grouped all of the tags for the eastern half of the city under one Context tag named EasternZone. All of the tags for the western side are grouped under a Context tag named WesternZone. For operators who work in the EasternZone, you can restrict tag-related privileges within their job description role to apply only to tags in that zone, even though all tags are protected by a single privilege.

Detail from the Accounts dialog, showing with one privilege subject to tag scope rule.
The square in the selection box of Filtration Control indicates that it is limited by a rule.

The example in the previous figure shows an example "Eastern Zone Operations" role. The role contains two custom privileges, Filtration Control and Filtration Monitoring. Filtration control is meant to be applied to I/O tags and is therefore limited by a scope rule to tags in the Eastern Zone context. (Examples follow, showing how the rule is applied.) The custom privilege, Filtration Monitoring, is meant to be applied to pages and therefore is not limited by a tag-scope rule.

Use the Manage Rules dialog (following figure) both to add and to remove rules. Removing the privilege (then re-adding it) is an inefficient way to remove rules.

Privileges that can be limited by tag-scope rules:

By definition, tag-scope rules are meant for privileges that affect tags. They should never be used for other privileges and in more recent versions of VTScada, cannot be. For a broader method of limiting operator access to portions of the application, refer to Realm Filtering.

Custom (User-defined) Privileges (*) |
Alarm Inhibit | Edit Data
Alarm Acknowledge | Edit Roster Contacts
Alarm Shelve | HDV Pen Modify
Batch Run | Manual Data
Control Outputs | Note Add
Control Lock Add/Remove | Questionable
Control Lock Admin | Recipe Edit
Control Token Request/Release | Tag Parameter View
Control Token Admin | Tag Modify

(*) Use care with custom privileges. Apply tag rule scope restrictions only to those that are being used with tags, and never to those being used to restrict access to pages.

Steps to apply rule-scope:

  1. Find the privilege in the list of Additional Privileges.
    If the privilege has not been granted to the account or role, add it. (Assign Privileges)
  2. Expand the menu for that privilege as shown:

Step 1 of adding a rule to a privilege.

  3. In the Manage Rules dialog, click the plus button to open the New Rule dialog.

Use the New Rule dialog for both Tag Scope rules and Workstation Scope.

  4. In the New Rule dialog, use the Tag Selection button to open the Tag Browser.
  5. Select the tag (or better, the parent context) for which the rule is to apply.
  6. Optionally, select more tags for which the rule should apply.
  7. Click OK through all dialog boxes to exit.
  8. Click Apply in the Accounts dialog to save your work.
    The square instead of a check mark indicates that the privilege is granted conditionally.

Workstation Rules

You can also create a rule such that the privilege is valid only when the user is signed in on a named workstation. For example, if you have created a Manager account, with permissions to modify user accounts, you may wish to restrict that privilege so that it may only be used at a given workstation. Even if someone were to guess the manager's password, they would not be able to modify accounts unless they were also at that person's workstation.

Take care that the workstation you select is or will be available. Don't lock yourself out!

Workstation rules are not intended for use with Internet or Mobile client connections. It is not possible to determine the name of the remote device. The rule scope will apply to the VTScada Thin Client Server, affecting all connections.

The steps to apply a workstation rule to a privilege are the same as those to apply a tag scope rule, excepting only that you will choose one or more workstations instead of one or more tags.


Suppress or Reveal Privileges

You can suppress general privileges from view using the Privileges dialog. This will prevent managers from granting a privilege as well as preventing users from knowing that the privilege exists. You cannot suppress custom privileges.

Suppressing the Administrator privilege.

To suppress general privileges:

  1. Select the privilege you wish to suppress in the list of General Privileges.
  2. Click the Suppress button.

The text on the Suppress button changes to the word "Unsuppress".

To reveal suppressed general privileges using the Administrative Settings dialog:

  1. Select the privilege you wish to unsuppress from the General Privileges list.

The Unsuppress button will become enabled if the privilege is suppressed, whereas the Suppress button will become enabled if the privilege is not.

  2. Click the Unsuppress button.

The text changes to "Suppress".


Administrative Settings

Accounts that possess the Administrator privilege and that are not assigned to a realm can control options such as minimum password length, automatic log-off time and more. You can find these controls within the Administrative Settings dialog, which opens in response to "Options" in the security menu.

Opening the Administrative Settings dialog

This panel is used to control security configuration options that apply to all accounts.

Refer to the documentation menu system, subtopics of this chapter, for details of each group of settings.

Change the automatic sign out settings, password options, advanced security settings. Configure 2-factor authentication with OpenID Connect or TOTP

It's easier to work with one section of this dialog if you minimize the other sections.

Not all security configuration options are available in this menu. For example, the automatic lock-out feature, where users are locked out of their accounts for a period of time after N failed password attempts, is not configured in the user interface. For this and others, refer to the Security Propertieschapter in the reference section.

Notes:

  • If it is your intention to share security between applications by selecting an OEM layer to provide the security configuration, do that before spending time configuring accounts and other security options in the current application.
  • The Enable Logged Off VIC Sessions option is used for VTScada Internet Client (VIC) connections. When selected, a remote user can sign out, but retain a connection to the VTScada Thin Client Server. This ensures that the user can log back in, but at the cost of a client connection that is not freed for use by others while the client window remains open.


Automatic Sign Out Time Period

VTScada can sign users out when the application is left idle for a defined period of time. The setting in the Administrative Options dialog will apply to all users, but you may also set a unique sign out time for each user in the Accounts dialog.

The default time period is 15 minutes. The valid range is from 0 (no automatic sign out) to 720 minutes (12 hours). You may also disable this feature by selecting the No Automatic Sign Out option (0 minutes).

Related information:

cAutoLogOff, AutoLogOffMin , and AutoLogOffMax - Application properties


Password Options

The four spin boxes define the required strength of passwords. Password strength is a measure of how difficult it is to guess the word. In general, words from a dictionary are easily guessed by a hacker. Words that include a mix of letters, numbers and symbols are more difficult. The longer the password, the more difficult to hack.

When you change any of these values, all existing users will be required to change their password on their next log-on.

Minimum Length - Sets the overall minimum number of characters. It ranges from 1 character to 255 characters. The minimum password length is at least the sum of the other 3 minimum values.

If anyone attempts to set a password shorter than this length, a warning dialog will be displayed.

Minimum Alphabetic Characters - Sets how many letters must be included in the password.

Minimum Numeric Characters - Set to a number greater than 0 if you want to require passwords to contain numbers.

Minimum Special Characters - Set to a value greater than 0 if you want to require passwords that contain symbols such as @#$%, etc.

If an attempt is made to set a password that does not have the required number of any type of character, a warning dialog is displayed. This will also tell the user how many of each required type of character must be used.

VTScada also limits the number of attempts an operator can make before being locked out and the length of time for which they will be locked out. Settings for both those numbers and much more can be found in Security Properties.

Password Expiration sets the number of days between forced updates to every user's password. When the expiration date is reached or passed, existing passwords will work one more time, but users must provide a new password before continuing. Choosing not to set a new password simply returns you to the Sign in stage, allowing time to consider a new password before continuing.


Advanced

Shared Security (Security Provider) is a deprecated feature.
Do not use.
Windows Security Integration is suggested as an alternative.

Enable Windows Security Integration

Requires coordination with your IT department. Refer to notes in Windows Security Integration.

User Realm Delimiter

Must be defined before enabling Separate Realm Entry During Sign In. Refer to notes in Security Realms.

Enable Smart Card Authentication

Available only in combination with Windows Security Integration. Refer to notes in Smart Card Support

Enable Signed Out VIC Sessions

If Enable Signed Out VIC Sessions is selected, behavior on sign-out will be similar to a desktop session, where the application remains visible waiting for the next sign-in. Applies only to VIC clients, not Mobile or Anywhere.

By default, signing out of a VIC session causes the connection to close, freeing the license. When selected, the client license is not released until the connection is closed.

Permit remote sign-in using VTScada account credentials

Applies to thin client connections, remote data access including REST queries, and SOAP service access.

When enabled, authorized users can sign in using their VTScada account credentials, as the label states. If using OpenID Connect to enforce two-factor authentication, this option should be disabled so that remote users do not have the option of using their account credentials instead of OpenID Connect.

See: OpenID Connect Authentication

Enable OAuth2

Requires coordination with your IT department. Refer to notes in OAuth 2.0 Protocol


OpenID Connect Authentication

Before using OpenID Connect, your site must implement or have access to an OpenID Connect Provider (https://openid.net).
Trihedral does not endorse or recommend any provider over another.
The VTScada documentation does not, and can not, provide instructions for the configuration of an OpenID Connect Provider.

OpenID Connect logons are supported only on the VTScada Anywhere Client.

OpenID Connect is a standard for user-authentication. If enabled in VTScada, operators can connect to the VTScada Anywhere client using their OpenID Connect credentials. This may be useful at sites where a user must logon once, then access several business applications throughout their day without needing to logon again. It can also provide enhanced security through the use of two-factor or multi-factor authentication. Refer to the OpenID Foundation website for further information.

OpenID Connect accounts are mapped to each user's VTScada account by matching the content of a claim Closed In OpenID Connect, each field of information describing a user's account is referred to as a "claim". field from the provider to the VTScada account names. Every user must have both an OpenID Connect account and a VTScada account.

If you have implemented Windows Security Integration (WSI), the claim can be "email", assuming that the email addresses match the Active Directory user principal names. Because VTScada account names can include @ symbols only when WSI is enabled, some other claim that specifies the VTScada account name must be used if WSI is not enabled. It may be necessary to configure your provider to add an appropriate claim field and populate it with your user's VTScada account names.

You will continue to manage privileges and roles within VTScada. OpenID Connect is used to authenticate users when signing in. It does not specify what they can or cannot do within an application.

As with any Internet and Mobile device connection, you must first enable security, create at least one account with the Thin Client Access privilege, and you must configure a VTScada Thin Client Server with your application made available through a named realm. A TLS/SSL certificate is strongly recommended.

If a company portal is being used to direct users to the VTScada Anywhere Client then Anywhere Client URLs can be converted into URLs that will automatically initiate an OpenID Connect login. For example https://example.vtscada.com/realm/app/ANYWHERE/Page would become https://example.vtscada.com/realm/app/ANYWHERE-OIDC/Page

The redirect URIs sent by VTScada to the OpenID Connect provider take the form "https://hostname/vtscada/oidc/return" where hostname matches the address of the VTScada Thin Client Server. This must be a secure (https:) connection.

All of the possible hosts used to access your Anywhere Client servers must be accepted or registered with the OpenID Connect Provider.

Sign in using OpenID Connect

OpenID Connect is available only for the VTScada Anywhere Client. The following steps assume that you have finished configuration and now signing in as an authorized user.

  1. Use your preferred browser to navigate to your Anywhere Client's sign in page.
  2. After sign-in, you should see two options, the regular username / password route to sign in, and below it the Sign In with OpenID Connect button. If not, your system is not yet configured.
  3. Select the OpenID Connect button, which should redirect you to your configured OpenID Connect provider.
  4. Sign in with the username and password assigned for your enterprise's OpenID applications.
    (Not required if you are already signed in to another of your enterprise's applications. You may need to provide further authentication, for example if two-factor authentication has been configured.)
  5. Upon successful authentication, the Anywhere Client should start and you will be signed in.

OpenID Configuration

All of the URLs configured in the OpenID Connect settings dialogue must be HTTPS, using a certificate trusted by the system running VTScada.

OpenID Connect is enabled and configured within the Administrative Settings dialog:

Enable OpenID Connect

You can choose to allow connections using OpenID Connect, standard VTScada username and password connections, or both.

If you disable both of OpenID Connect and remote sign-in using VTScada account credentials, users cannot connect through Internet or Mobile clients, remote data access (REST) or SOAP services.

Ensure that Enable OpenID Connect is selected before proceeding to the other options in this dialog.

OpenID Connect Provider

Enter the URI (Uniform Resource Indicator) to the metadata endpoint of your OpenID Connect provider. This will have a form similar to: https://your.provider.com/adfs/.well-known/openid-configuration (*)

After entering the URI, select the Discover button. The Issuer and Endpoint fields will be populated automatically from the information found there.

Alternatively, you may enter this information yourself, if known.

(*) "adfs" refers to Active Director Federation Services, provided by Microsoft. Your URI may vary.

Client ID

The Client ID that you have registered with your OpenID Connect provider for use with VTScada.

Shared Secret

The Shared Secret provided by the OpenID Connect provider for use with VTScada. Note that client certificates are not supported.

Account Name Field

Do not enter a VTScada Account Name.

This field specifies the claim that contains the VTScada account name and it will vary depending on how your OpenID Connect provider is configured. This may be "email", or "upn" etc.

Refer to the notes earlier in this discussion for more information about mapping OpenID Connect accounts to VTScada accounts.

Token Age Limit

Sets the maximum accepted age of tokens issued by the OpenID Connect provider.

Requested OAuth 2.0 Scopes

Scope is used to limit the authorization granted to the client by VTScada.

Additional Trusted Audiences

As part of the OpenID Connect process, you must check several things. One of these is that the token was issued for VTScada and is not one issued for another application and substituted in. This is done by the OpenID Connect Provider sending a list of audiences the token is intended for, and in some situations this can be a list of several audiences. VTScada must have a list of any other audiences that may be included in the ID token and any ID tokens received by VTScada that contain audiences not in this list will be rejected.

The entries added to the list are other Client IDs besides VTScada that are considered trustworthy.

This is unlikely to be required for most installations and may be left blank.

Related information:

Enable - property controlling whether OpenID Connect authorizations are allowed.

RemoteAuthMethodsDisallowed - property controlling whether username/password authorizations are allowed on VTScada Thin Client Servers.

Workstation-Specific Properties - Includes an example of setting RemoteAuthMethodsDisallowed for one VTScada Thin Client Server but not another. An example is provided in the topic,


System Privilege Reference for Developers

For programmers: Every general privileges has a negative index number starting at -1. User privileges have an positive index number, starting at 16. The index number can be seen in the Privileges dialog, available from the security menu.
See also: System Privilege Reference for Programmers

--Accounts & Security Configuration--

Administrator Privilege (-4)

Role configuration (create, edit, delete) but only if the user also has the Manager privilege and is not part of a realm.

Access the security Options dialog (Administrative Settings) to do any of the following:

  • Change the default automatic sign-out time
  • Set rules for password complexity.
  • Enable Windows Security Integration
  • Set the realm delimiter and enable separate realm entry during sign-in.
  • Enable signed-out VIC sessions
  • Enable OAuth 2.0
  • Configure for OpenID Connect.

Administrative Settings

Manager Privilege (-3)

Security is not enabled unless at least one active user has this privilege.

Access the Accounts dialog and modify accounts other than your own.

To create and modify roles, you must also have the Administrator privilege.

Configure Subordinate Application tags (Must possess the Manager privilege or the Configuration privilege in the subordinate application.)

Accounts and Roles

Account Modify Privilege (-2)

Open the Accounts dialog to modify your own password. You cannot change your privileges or other settings.

Change Your Password

Account View Privilege (-1)

Open the Accounts dialog to view your own settings. You cannot change anything.

*On password expiry, everyone can give themselves a new password, regardless of privileges.

Thin Client Access Privilege

Sign in using a thin client (VIC, Anywhere or Mobile).

Thin Clients: Mobile and Internet

Remote Data Access Privilege (-47)

Use the ODBC (REST) interface to query application data from outside VTScada.

SQL Queries, Excel Add-in for Data Retrieval

Remote Tag Value / History Retrieve Privilege (-54)

Restrict access to the main History table.
Users with Remote Data Access can access SQL Views on a tag-by-tag basis depending on the custom privilege defined for each.

SQL Queries, Excel Add-in for Data Retrieval, SQL View Tag

--Application Control--

Application Stop Privilege (-9)

Stop a running application.

Start and Stop

Application Manager View (-40)

Applies only if the application property, HideVAM from users without "Application Manager View" privilege is set.

VTScada Application Manager (VAM)

Switch Servers (-56)

Switch a service from one server to another.

Services Page

--Version Control--

Advanced Version Control Privilege (-39)

Open and use the Show Version Log dialog

Version Control

Deploy Changes Privilege (-15)

Applies only if the application property, "Automatically deploy local changes", is not set on the current workstation. Allows the user to deploy local changes.

Local versus Deployed Changes

Revert Changes Privilege (-16)

Similar to Deploy Changes. Required in order to use the Revert Changes tool in application configuration.

Local versus Deployed Changes

--Application Configuration--

Edit Files Privilege (-14)

Use the Import File Changes tool.

Manage files in the File Manifest.

File Management Tools

Page Add Privilege (-17)

Create new pages using the Idea Studio.

Pages

Page Modify Privilege (-18)

View and edit existing, user-created pages in the Idea Studio.

Display Building (Idea Studio)

Page Delete Privilege (-19)

Delete pages in the Idea Studio. Users must also have the Page Modify privilege.

Delete a Page

Tag Parameter View Privilege (-11)

View (but not edit) the properties of other tags.

Users with this privilege who also have the "Control Outputs Privilege" can operate tags that they can see in the Tag Browser.

Not required if the user has the Tag Modify privilege.

The Tag Browser, Roster Tags

Tag Add / Copy Privilege (-20)

Meaningless without the Tag Modify privilege.

Required in order to create new tags.

Add a New Tag or Child Tag

Tag Modify Privilege (-18)

Required in order to configure tags, including those being created.

The Tag Browser, Roster Tags

Tag Delete Privilege (-19)

Allows the user to delete tags.

Delete a Tag

Manage Tag Types (-41)

Required in order to use any of:

  • Create New Type (Tag Browser)
  • Redefine Type (Tag Browser)
  • Manage Types (Application Configuration dialog. Access to that dialog is restricted to those with the Application Configuration privilege.)

Design Your Own Tags

--Alarm Operations--

Alarm Acknowledge Privilege (-8)

Acknowledge alarms.

Acknowledge Alarms

Alarm Disable Privilege (-5)

Disable alarms using the right-click menu on a widget.
(Changes through the Tag Browser require the Tag Modify privilege.)

Disable or Enable Alarms

Alarm Mute Privilege (-24)

Stop all alarm sounds (current and new) for a user-specified length of time.

Silence or Mute Alarms

Alarm Silence Privilege (-25)

Stop all current alarm sounds indefinitely. New alarms will sound.

Silence or Mute Alarms

Alarm Shelve Privilege (-42)

Shelve selected alarms

Shelve Alarms

Tag Operations

Manual Data Privilege (-6)

Use the right-click menu of a widget to set the Manual Data value of the linked tag.

Not needed by users who have the Tag Modify privilege.

Special Symbols for Tags

Questionable Privilege (-7)

Use the right-click menu of a widget to change the Questionable flag of the linked tag.

Not needed by users who have the Tag Modify privilege.

Special Symbols for Tags

Control Outputs Privilege (-48)

Applies only to tags that are not otherwise protected by a custom (user-created) privilege.

Must be granted in order to write values to equipment.

Restrict Access to Output Tags

Lock Add / Remove (-57)

Able to create locks and to remove locks over which the user has "ownership".

Control Locks

Lock Administrator (-58)

Able to remove any control lock from any tag. This privilege is not limited by lock ownership.

Lock Administrators who do not have the Lock Add / Remove privilege cannot create Control Locks.

Control Locks

Token Request / Release (-59)

Able to request tokens and to release tokens over which the user has "ownership".

Control Tokens

Token Administrator (-60)

Able to release a control token from any tag. This privilege is not limited by token ownership.

Token Administrators do not have the Token Request / Release privilege and cannot request tokens.

Control Tokens

Edit Roster Contacts (-53)

Operators with this privilege can add, edit and remove entries in the Contacts list of any Roster tag.

Roster Tags

--Historical Data & Notes--

Group Modify Privilege (-26)

Open the Tag Selector in the Historical Data Viewer (HDV) and select tags or queries.

Does not allow you to save or delete existing groups.

Pen Groups - Save Tag Selections

Group Save Privilege (-27)

Save tag selections as named groups in the HDV's Tag Selector dialog.
Operators must also have the Group Modify privilege.

Select Pens (Tags) to Plot

Group Delete Privilege (-28)

Delete pen groups from the HDV's Tag Selector dialog.
Operators must also have the Group Modify privilege.

Pen Groups - Save Tag Selections

Note Add Privilege (-30)

Required in order to create a note in any notebook, any page.

Add Operator Notes

Pen Modify Privilege (-29)

Change properties associated with a pen (tag) in the Historical Data Viewer.

Change Pen Styles

Edit Data Privilege (-46)

Add or edit data in the grid tab, Raw Data view of the Historical Data Viewer

Edit Data

--Page Access--

Alarm Page Access Privilege (-31)

Open the alarm page.

Alarm Display & Tasks

History Page Access Privilege (-33)

Open the Historical Data Viewer page.

Historical Data Viewer (HDV)

Thin Client Monitor Admin Privilege (-36)

Use tools within the Thin Client Monitor page within an application. Users must also have the Thin Client Monitor Access privilege in order to view that page.

Monitor Internet Connections

Maps Page Access Privilege (-44)

View maps within an application.

Site Map

Operator Notes Page Access Privilege (-45)

Open the Operator Notes page.

Users must have the Note Add privilege to create notes.

Operator Notes Page

Reports Page Access Privilege (-32)

Open and use the Reports page.

Reports Page

Sites Page Access Privilege (-43)

Open and use the Sites page. View Site Lists.

Sites & Maps

Services Page Access Privilege (-55)

Stop a running application.

Services Page

--Recipe Operations--

Recipe Page Access Privilege (-52)

Open the Recipe & Batch Management Page.

To use the page, users must also either or both of Recipe Edit and Run Batch privileges.

The Batch & Recipe Management Page

Recipe Edit Privilege (-50)

Create and modify recipes for batch processing operations.

Batch & Recipe Management

Run Batch Privilege (-51)

Start a recipe batch run.

Batch & Recipe Management

--Miscellaneous--

Global Tag & Area Filter (-49)

Enables the Global Tag & Area Filter button at the top of every page. With this, operators can create their own filters for tag and alarm lists.

Global Tag & Area Filtering

Page Note Edit Privilege (-37)

Add, modify and delete page notes.

Page Notes

Page Note Hide Privilege (-38)

Hide page notes from view (temporarily).

Hide a Page Note

Thin Client Monitor Access Privilege (-35)

Open the Thin Client Monitor page within an application.

Monitor Internet Connections


OAuth 2.0 Protocol

OAuth stands for Open Authorization (not authentication). "2.0" refers to the second (and current) generation. It is an open standard, used by Microsoft, Google and many other companies. OAuth 2.0 is related to, but distinct from, OpenID Connect. This protocol is used to allow defined access between web or desktop applications. It can be configured for authenticating specific users or to verify application credentials (with no user interaction required).

To put it very simply, OAuth 2.0 is a standard that uses a third party provider to facilitate access to tokens.

While configuring OAuth 2.0, you can define the specific protected resources that can be accessed and for how long that access will last. OAuth 2.0 supports several flows, but VTScada currently supports these two:

  • Authorization Code flow - On behalf of a user.
  • Client Credentials flow - On behalf of an application (server-to-server).

If using OAuth 2.0 ensure that all servers are using the same VTScada version 12.0, 12.1 or 12.2. OAuth tokens will not be handled properly if your servers run a mix of different versions.

OAuth 2.0 Terms & Definitions

Terminology | OAuth 2.0 Definition
OAuth | "Open Authorization", OAuth 2.0 specification as defined in RFC 6749.
Authorization Code flow | As defined in RFC 6749, this flow allows a client to obtain an access token on behalf of a user via an authorization code.
Client Credentials flow | As defined in RFC 6749, this flow enables a client to obtain an access token using only its own credentials, without user involvement.
Client ID | A public identifier of the client application.
Client Secret | A confidential key for client authentication. The application and the authenticating server both confidentially know the secret.
Resource | What you want access to. For example, a user may want access to an email service. An application may want access to a device status or analytics.
Resource Provider | Source from which a resource is offered.
Resource Server | Server where access tokens are expected to be used.
Resource Owner | An entity registered with the resource provider to which specific resources are assigned. For example, a user registered email.
OAuth 2.0 Provider | The third party that vouches for the user or application. OAuth 2.0 providers and VTScada engage in protected communication, and the OAuth 2.0 provider authenticates and enables token access.
OAuth 2.0 Grant | The consent given by a resource owner for a specific set of permissions to be given to a third-party application registered with the OAuth 2.0 provider. A token is tied to the grant. In Authorization Code flow, the bearer of the grant is the account that will be used during normal operation and requires the scopes you are defining as allowed for use by VTScada (ie. reply email.)
User Agent | Often a web browser. Used as a means of confirming the resource owner’s credentials during the OAuth 2.0 consent process. This browser provides a means for the credentials to be sent directly to the OAuth 2.0 provider without passing by the application which is requesting access to the resources. For VTScada, this is the users default web browser.
OAuth 2.0 Provider Authorization Endpoint | A publicly available REST endpoint offered by the OAuth 2.0 provider. This is used to confirm the resource owner credentials during an access request by a third-party application.
OAuth 2.0 Provider Token Endpoint | A publicly available REST endpoint offered by the OAuth 2.0 provider. This is where a third-party application can acquire the tokens required to access the resource owner’s protected resources.
Redirect URI | URL identifying a server registered as a potential system to receive the single use code during the OAuth 2 consent flow. There may be multiple redirect URIs registered for a single third-party application registration. Due to the handling of the communication during a consent operation, the redirect URI needs only be resolvable by the system which is running the user agent.
Access Token | A short-lived token that is exchanged by a third-party application when attempting to access a resource owner’s resources.
Refresh Token | A longer-lived token that permits the third-party application to acquire a new access token without requiring the user provide consent each time. The permissions given for the new access token are the same as the previous. This token can be invalidated by the resource owner when desired.

VTScada references RFC 6749 for OAuth 2.0 Terms and Definitions. Not all OAuth 2.0 providers adhere strictly to this standard, so while you will see these terms while configuring VTScada, your chosen OAuth 2.0 Provider might use different jargon. See Common Provider Tips for provider-specific cross-referencing and setup guidance.

Third-Party OAuth 2.0 Providers

VTScada does not recommend any specific service providers over others. There are many providers available. The features they offer, the quality of their services and the cost of their services are ever changing and outside of VTScada's control. Select providers that work best for you and remain vigilant about the service they provide.

These are the third-parties that are responsible for:

  • Verifying a user login
  • managing client IDs/secrets
  • Issuing access tokens and refresh tokens
  • Enforcing scopes and permissions
Service Provider | URL | Used for...
Microsoft Entra ID | https://entra.microsoft.com | Enterprise identity & access management. OAuth 2.0 and OpenID Connect provider.
Microsoft AAD | https://aad.portal.azure.com | Absorbed into Entra ID in 2023. Still accessible but with less features.
Google Cloud | https://console.cloud.google.com | Alphabet's OAuth 2.0 Provider. Not recommended for Client Credentials flow.
Auth0 | https://auth0.com | Specialized identity-as-a-service platform.
Okta | https://okta.com | Enterprise-focused identity & access platform
LogTo | https://logto.io | Open-source identity provider designed for modern application frameworks.


OAuth 2.0 Authorization Code flow

Use OAuth 2.0 Authorization Code flow for User Authorization. In VTScada, this method is used for the configuration of an email server for the purpose of sending alarm notifications or reports.

How it works in simplified terms.

VTScada uses an OAuth 2.0 Authorization code flow to access resources on behalf of a user. The user verifies their identity with a third party (like Google or Microsoft) and that third party vouches for the user. Here is a general summary of the process:

  1. The user is redirected to an authenticating server (OAuth 2.0 Provider such as Microsoft or Google) and logs in with credentials kept between the user and the provider.
  2. The user grants consent for specific scopes of access.
  3. The authenticating server sends the user back to VTScada's server with a code that says 'Yep, I vouch for this user.' VTScada exchanges the code for an access token and a refresh token. The tokens are tied to the user.
  4. The user holding the tokens is granted access to the authorized resource.

VTScada Authentication Code Flow Details

A VTScada server will direct a user agent to the OAuth 2.0 provider authorization endpoint. After the resource owner is successfully authenticated, the OAuth 2.0 provider authorization endpoint will redirect the user agent to the VTScada server with a single use code. This code can then be exchanged by the VTScada server for a pair of tokens by providing it to the OAuth 2.0 provider token endpoint. These tokens can then be used by VTScada to access to the resource for which the resource owner granted consent. Continued use of the resource by VTScada for services such as the alarm email system require a refresh token.

In order to authenticate the user agent with the VTScada server, a VTScada client will first direct the user agent to the server. At this point, the server will establish information required to protect the different elements of the OAuth 2.0 consent flow when communicating with the OAuth 2.0 provider. This is an additional step prior to beginning the general OAuth 2.0 consent flow.

The consent flow process. Numbers refer to the following steps...

  1. VTScada client invokes the user agent.
  2. The user agent is directed to the VTScada OAuth 2.0 redirect server to establish common identifying information.
  3. The user agent is redirected to the OAuth 2.0 provider’s authorization endpoint.
  4. The user agent contacts the authorization endpoint and authenticates the resource owner.
  5. The authorization endpoint redirects the user agent to the VTScada OAuth 2.0 redirect server with the single use code.
  6. The user agent provides the VTScada OAuth 2.0 redirect server with the code.
  7. The VTScada OAuth 2.0 redirect server contacts the OAuth 2.0 provider token endpoint with the single use code.
  8. The token endpoint responds with the appropriate tokens.
  9. The VTScada OAuth 2.0 redirect server passes the acquired tokens to the primary server for the OAuth 2.0 implementation. This may be the same server as that handling the OAuth 2.0 redirect.

Preparation

To configure OAuth 2.0 Authorization Code flow in VTScada you are going to need some specific information and values. Some of these come from VTScada and some of them will come from your OAuth 2.0 provider.

An OAuth 2.0 provider

A provider looks after user authentication and provides authorization for the service (email) that you want to access from VTScada. Examples include Microsoft AAD Closed Microsoft Azure Active Directory app registration, an OAuth 2.0 provider..

You must obtain all of the following from your selected OAuth 2.0 provider before proceeding to configure VTScada.

Authorization Endpoint URL

A publicly available REST endpoint offered by the OAuth 2.0 provider. Used to confirm the resource owner's credentials during an access request by a third-party application.

Token Endpoint URL

A publicly available REST endpoint offered by the OAuth 2.0 provider. This is where a third-party application such as VTScada can get the tokens needed to access the resource owner’s protected resources.

Revocation Endpoint URL

Optional. Not supported by all providers. A publicly available REST endpoint offered by the OAuth 2 provider. This allows clients to indicate to the authorization server that an access token is no longer needed. Used to enable a "sign out" feature in clients, allowing the authorization server to clean up any security credentials associated with the authorization.

Client ID

An identifier for your application. This will be generated for you as part of the provider configuration.

Client Secret

Similar to a password, this is known only to your application and your provider. You must copy this to a secure location after it is created during the provider configuration process.

Requested Scopes

Optional. Not supported by all providers. The authorization and token endpoints allow the client to specify the scope of the access request using the "scope" request parameter. If the OAuth provider has implemented this feature, it will provide this information.

Resource URIs

Optional. Not supported by all providers. Indicates the target service or resource to which access is being requested. This is defined in RFC 8780. Each OAuth provider may implement it differently, so follow the provider’s instructions to obtain the Audience or Resource information.

A certificate for your VTScada server(s)

Commonly (but incorrectly) referred to as an SSL certificate. Every provider will have its own set of restrictions on what it will accept as the redirect URI Closed The URL identifying a server registered as a potential system to receive the single use code during the OAuth 2 consent flow.. The VTScada OAuth server(s) need not be exposed to the public Internet by being included in a VTScada Thin Client server list, but must be capable of making a connection to the public OAuth servers.

The certificate may be self-signed so long as it is trusted by the user-agent (browser).

An email account with your selected provider.

For example, a Workspace account if using Google as a provider. An MS 365 account if using Azure.
Create an account for VTScada. Do not use your personal email account.

A server list specifying at least one OAuth 2.0 server

Referring to client / server configuration, not a Thin Client Server. This is not strictly necessary but is recommended even if your application runs on only a single server.

Your application must be secured and you must be signed in with an account that has the Administrator privilege

The Redirect URI must be resolvable on your internal network.

Assuming that these items are in place, proceed as follows:

Part 1: Enable OAuth 2.0 configuration in VTScada.

  1. Open the security Options dialog (Administrative Settings)
  2. Select the option, Enable OAuth 2.0, found within the Advanced section.
  3. Select OK to save your changes.
  4. Close the Administrative Settings dialog.
    The OAuth 2.0 Settings dialog option is now enabled.

Part 2: Configure VTScada to use OAuth 2.0 Authorization Code flow.

  1. Open the Edit Server Lists page of the Application Configuration dialog.
  2. Select the server(s) that will respond to OAuth grant requests.
    In the case of an application that runs on only a single server, this step is not required, but it is recommended.
  3. Open the OAuth 2.0 settings dialog.
    Available from either the drop-down security menu in the screen or the Edit Security page of the Application Configuration dialog.
  4. Create a new Provider by clicking the [image] button under the providers list.
    This enables the data entry fields.
  5. Create a Provider Name as desired.
    Create an easily recognized name to identify the purpose of the registration and the resource provider

The OAuth 2.0 Settings dialog for Authorization Code flow. All fields are disabled until you begin configuration of a provider.
Note that Providers and Grants can both be deleted using the trashcan buttons below the respective lists.

Grant Scopes and Redirect URI entries can be edited by double-clicking. Editing may require you to grant consent again.

  6. Make sure the Type is set to Authorization Code Flow. The fields that are displayed are specific to the Type. If the Type is incorrect, the fields will look different.

  7. Enter the Authorization Endpoint URL for your chosen OAuth 2.0 provider.

  8. Enter the Token Endpoint URL for your chosen OAuth 2.0 provider.
  9. Enter the Revocation Endpoint URL for your chosen OAuth 2.0 provider, if one exists.
  10. Set the Client ID and Client secret to the values created when configuring your OAuth 2.0 provider.
  11. Set the Refresh Token Lifetime to as appropriate.
    This field is measured in seconds and must match the token lifetime used by your provider. This value refers to the time between uses of the refresh token, and not the overall lifetime of the token.
    For reference, standard values from two commonly-used providers are:

    • Google: 6 months of inactivity (15552000 seconds )

    • Microsoft: 2 weeks of inactivity (1209600 seconds )

  12. Select Pen icon next to the Provider Scopes field to open the Scope Editor.

  14. Scope Editor

    Example showing the scope if configuring for GSuite authentication.

  15. Enter the URI for the provider scope.
    The scope is the service for which you are authorizing access.
  16. Select the pen beside the Redirect URIs field to open the Redirect URIs editor.

  17. Your OAuth 2.0 server(s) need not be visible to the Internet, but must be secured.

  18. Set the OAuth Redirect URIs as given when configuring your OAuth 2.0 provider.
    These will be the FQDN Closed Fully Qualified Domain Name's of your VTScada OAuth servers, along with the VTScada OAuth path which is "/vtscada/oauth/return".
    Do not include any realm name for your application. Do not include the port number unless it is non-standard.
  19. Set the OAuth Resource URI as given when configuring your OAuth 2.0 provider. This field is optional, and it should be set to either Audience or Resource URI.
  20. Create a new Grant by clicking the [image] button under the Grants List.
  21. Create a name for the grant.
    This is used to identify the service to which you are granting authorization. Naming the grant to match your provider's email service might be appropriate.
  22. In the Grant Bearer field, enter the identification of the user who will be running the consent operation. Typically, this will be an email address.
    This must be an email account registered with your provider.
  23. Select the pen beside the Requested (Grant) Scopes field to open the Grant Scopes editor.

  24. Example showing selection of a GSuite email scope.

  25. Select the relevant email scope then click OK to close the dialog.
    Scopes are the set of access permissions to be requested for the bearer. This must be a subset of those configured for the OAuth 2.0 provider registration.
  26. Select the Apply button.
  27. Select the Grant button to grant authority for VTScada to access the designated email account.
    You need not grant consent immediately, but must do so before using the service. See the following notes under Granting Consent
Closed Example of a configured OAuth 2.0 Settings dialog

Sample OAuth 2 Settings dialog, as configured for GSuite.

Grant Selection

If you configure more than one OAuth 2.0 grant, then you will have a selection of which to use within the Alarms tab of the Edit Properties / Application Configuration dialog. Outgoing and Incoming Alarm Email Acknowledgments will each have a Grant Selection.

To use:

  1. Select the appropriate grant.

  2. Initiate the consent operation for that grant.

  3. Optionally, you can use this to revoke consent for a grant.

Granting Consent

Do not use your personal email to send and receive alarm notifications. VTScada will erase all messages in the Inbox after retrieval. Always use an account that is dedicated for VTScada's use.

Your default browser is open, waiting for you to complete the operation there.

You must grant consent for VTScada to use an email account through your provider. The dialogs will vary according to your selected provider, but the process will be similar. First you must confirm the account to use. Then confirm that access is granted. Note that this operation will always happen within your default browser, not within VTScada.

The Security Admin who configures the provider and grant may not be the one with the credentials to actually give consent, therefore, grant consumers (alarm emails) are able to grant consent.

Revoking Consent

You may revoke consent for a grant at any time. Use the Revoke button and confirm that you wish to proceed.


Setup Tips for Authorization Code Flow

VTScada does not recommend any specific service providers over others. There are many providers available. The features they offer, the quality of their services and the cost of their services are ever changing and outside of VTScada's control. Select providers that work best for you and remain vigilant about the service they provide.

You will have to choose a service provider and navigate through some configuration menus. Each provider is a little different, but you will be looking for specific values that will take you through the same approximate steps.

As you work through the setup process, record the following values for later use:

  • Authorization Endpoint URL
  • Token Endpoint URL
  • Client ID
  • Client Secret
  • Requested Scopes
  • Redirect URIs

Depending on the provider you choose, you may also need:

  • Revocation Endpoint URL
  • Audience
  • Resource

Approximate Steps:

Create a New OAuth Application

  • 1. In your OAuth provider’s management console, register a new application.

  • 2. Assign a clear, descriptive name, such as VTScada.

  • 3. Select an application type that supports the Authorization Code Flow.

  • The new application will provide the following URLs, which are required later:

    • Authorization Endpoint URL

    • Token Endpoint URL

    • Revocation Endpoint URL (if available)

    • Configure Redirect URIs

  • Add one or more Redirect URIs, which define where the OAuth provider sends users after successful authentication.
    These will be the FQDNs of the VTScada OAuth servers along with the VTScada OAuth path (/vtscada/oauth/return), for example: https://scada.example.com/vtscada/oauth/return.

  • You may configure multiple URIs to support different environments.

    • Define Scopes and Permissions

  • Specify the scopes that determine which resources VTScada can access.

  • If required, configure a Resource URI or Audience to define the target API or service.

  • These values must match the VTScada configuration to ensure proper authorization.

    • Create Client Credentials

  • Generate a Client Secret, which VTScada will use to securely exchange authorization codes for access tokens.

  • Copy and store the Client Secret securely as soon as it is generated. Many providers will hide or mask the secret after you leave the page.

  • Treat the Client Secret as you would any sensitive password.

    • Trihedral and VTScada are registered trade marks of Trihedral Engineering Limited


OAuth 2.0 Client Credentials flow

How it works in simplified terms.

VTScada uses OAuth 2.0 Client Credentials flow so that an application can authenticate itself using an OAuth 2.0 Provider. This authentication process does not require user input. Once it has been configured, the process is done machine-to-machine.

Here is a general explanation of how it works:

  1. The VTScada application authenticates itself directly with an OAuth 2.0 Provider using a Client ID and a Client Secret.
  2. The application receives tokens.
  3. As long as the application has a valid token, it is granted access to authorized resources like APIs.

VTScada Client Credentials flow details

In most cases, the credentials used in the Client Credentials flow are pre-authorized to request tokens for a defined set of scopes.

Client Credentials flow does not involve user interaction so all permissions must be granted in advance.

Preparation

To configure OAuth 2.0 Client Credentials flow in VTScada you are going to need some specific information and values. Some of these come from VTScada and some of them will come from your OAuth 2.0 provider.

An OAuth 2.0 provider

In Client Credentials flow, the OAuth 2.0 Provider

You must obtain all of the following from your selected OAuth 2.0 provider before proceeding to configure VTScada.

Token Endpoint URL

A publicly available REST endpoint offered by the OAuth 2.0 provider. This is where a third-party application such as VTScada can get the tokens needed to access the resource owner’s protected resources.

Client ID

An identifier for your application. This will be generated for you as part of the provider configuration.

Client Secret

Similar to a password, this is known only to your application and your provider. You must copy this to a secure location after it is created during the provider configuration process.

Requested Scopes

Optional. Not supported by all providers. The authorization and token endpoints allow the client to specify the scope of the access request using the "scope" request parameter. If the OAuth provider has implemented this feature, it will provide this information.

Resource URIs

Optional. Not supported by all providers. Indicates the target service or resource to which access is being requested. This is defined in RFC 8780. Each OAuth provider may implement it differently, so follow the provider’s instructions to obtain the Audience or Resource information.

A certificate for your VTScada server(s)

Commonly (but incorrectly) referred to as an SSL certificate. Every provider will have its own set of restrictions on what it will accept as the redirect URI Closed The URL identifying a server registered as a potential system to receive the single use code during the OAuth 2 consent flow.. The VTScada OAuth server(s) need not be exposed to the public Internet by being included in a VTScada Thin Client server list, but must be capable of making a connection to the public OAuth servers.

The certificate may be self-signed so long as it is trusted by the user-agent (browser).

A server list specifying at least one OAuth 2.0 server

Referring to client / server configuration, not a Thin Client Server. This is not strictly necessary but is recommended even if your application runs on only a single server.

Your application must be secured and you must be signed in with an account that has the Administrator privilege

Part 1: Enable OAuth 2.0 configuration in VTScada.

  1. Open the security Options dialog (Administrative Settings)
  2. Select the option, Enable OAuth 2.0, found within the Advanced section.
  3. Select OK to save your changes.
  4. Close the Administrative Settings dialog.

    The OAuth 2.0 Settings dialog option is now enabled.

Part 2: Configure VTScada to use OAuth 2.0 Client Credentials Flow

  1. Open the Edit Server Lists page of the Application Configuration dialog.
  2. Select the server(s) that will respond to OAuth grant requests.
    In the case of an application that runs on only a single server, this step is not required, but it is recommended.
  3. Open the OAuth 2.0 settings dialog.
    Available from either the drop-down security menu in the screen or the Security page of the Application Configuration dialog.
  4. Create a new Provider by clicking the [image] button under the providers list.
    This enables the data entry fields.
  5. Create a Provider Name as desired.
    Create an easily recognized name to identify the purpose of the registration and the resource provider
  6. As the Type, select "Client Credentials Flow". The settings dialog will display all fields required for Client Credentials flow.

The OAuth 2.0 Settings dialog for Client Credentials flow. All fields are disabled until you begin configuration of a provider.
Note that Providers and Grants can both be deleted using the trashcan buttons below the respective lists.

  7. Enter the Token Endpoint URL for your chosen OAuth 2.0 Provider.
  8. Set the Client ID and Client Secret to the values you created when configuring your OAuth 2.0 provider.
  9. Select the pen next to the Request Scopes field to open the Requested Scopes editor.
  10. Add and select the relevant scope and click OK to close the dialog. Scopes are the set of access permissions to be requested for the bearer. This must be a subset of those configured for the OAuth 2.0 provider registration.
  11. Set the OAuth Resource URI as given when configuring your OAuth 2.0 provider. This field is optional, and it should be set to either Audience or Resource URI.


Setup Tips for Client Credential Flow

VTScada does not recommend any specific service providers over others. There are many providers available. The features they offer, the quality of their services and the cost of their services are ever changing and outside of VTScada's control. Select providers that work best for you and remain vigilant about the service they provide.

You will have to choose a service provider and navigate through some configuration menus. Each provider is a little different, but you will be looking for specific values to copy down for later use, and following the same approximate steps.

As you work through the setup process, record the following values for later use:

  • Token Endpoint URL
  • Client ID
  • Client Secret

Depending on the provider you choose, you may also need:

  • Requested Scopes
  • Audience
  • Resource

Approximate Steps:

Create a New OAuth Application

  • 1. In your OAuth provider’s management console, register a new application.

  • 2. Assign a clear, descriptive name, such as VTScada.

  • 3. Select an application type that supports the Client Credentials Flow..

  • Once created, the application should provide:

    • Token Endpoint URL – Used to request access tokens

    • Client ID – The unique identifier for the application

    • Client Secret – Used for secure authentication

    • Define Scopes and Permissions

  • Specify the scopes that determine which resources VTScada can access.

  • If required, configure a Resource URI or Audience to define the target API or service.

  • These values must match the VTScada configuration to ensure proper authorization.

    • Create Client Credentials

  • Create a Client Secret for the application.

  • Copy and store the Client Secret securely as soon as it is generated. Many providers will hide or mask the secret after you leave the page.

  • Treat the Client Secret as you would any sensitive password.

    • Google technically supports the OAuth 2.0 Client Credentials Flow, but it is not intended for accessing user data or most Google APIs. This flow is only supported in limited scenarios, such as calling custom APIs protected by Google's Identity-Aware Proxy (IAP).
    For most use cases, especially involving Google services like Gmail or Drive, this flow is not supported.


OAuth 2.0 Troubleshooting

Have you completed all the steps described in the topic, OAuth 2.0 Protocol?

The following is a trouble-shooting guide to errors that may occur and how you might solve them. Troubleshooting should begin by reviewing the list of what you must do before configuring OAuth 2.0. See the topic "Preparation" within OAuth 2.0 Protocol

Error Messages related to Provider Configuration

The provided URL is invalid

The URL you provided does not follow the standard form. Check for errors.
(VTScada has not checked whether the location is valid, only that the URL is written in a way that will not access any location.) For reference, the URLs for two common providers are shown here:

https://login.microsoftonline.com/ 236fb237-d18f-42c0-b59a-845ad5e04584 /oauth2/v2.0/authorize

https://accounts.google.com/o/oauth2/v2/auth

A Provider Name must be unique

You have attempted to give a new provider the same name as an existing provider. Choose a new name for the new provider.

Empty Provider Name

Each configured provider must be given a unique name. Names can be anything you like, but we suggest creating one that clearly identifies the provider.

Failed to add OAuth 2.0 Provider

VTScada was unable to complete the process of adding this provider. Check all fields for errors. Ensure that all URLs can be reached from this workstation.

Failed to modify OAuth 2.0 Provider

VTScada was unable to complete the process of changing this provider. This will fail if a grant is still active and using the information that will be modified.

Failed to delete OAuth 2.0 Provider

This will fail if a grant is still active for this provider. VTScada attempts to revoke the grants, but may not be able to do so in all cases.

Empty Redirect URI

Each grant must have a defined redirect URI Closed Uniform Resource Identifier. URIs Identify, whereas URLs Locate. In many cases, a URI looks a lot like a URL.. Select one using the Redirect URI Editor in the OAuth 2.0 Protocol's Settings dialog.

Duplicate Redirect URI

The Redirect URI you are attempting to create already exists.

Provider scope contains spaces

Spaces are not permitted in the provider scope field.

Duplicate Provider Scope

The provider scope you are attempting to create already exists.

Empty Resource URL

The Provider Resource URL must have an audience or resource URL defined.

Duplicate Resource URL

The Resource URL you are attempting to create already exists.

Error Messages related to Grant Configuration

Empty Grant Name

Each configured grant must be given a unique name. Names can be anything you like, but we suggest creating one that clearly identifies the grant.

Duplicate Grant Name

You have attempted to give a new grant the same name as an existing grant under the selected provider. Grant names may be reused so long as each is under a different provider. In the current case, choose a new name for the new grant.

Empty Scope

Each grant must have a defined scope. Select one using the Scope Editor in the OAuth 2.0 Protocol's Settings dialog.

Failed to add OAuth 2.0 Grant

VTScada was unable to complete the process of adding this grant. Check all fields for errors.

Failed to modify OAuth 2.0 Grant

VTScada was unable to complete the process of changing this grant. Check all fields for errors. Modifying the grant will also fail if the grant is still active and the modification will affect information sent to external sources.

Failed to delete OAuth 2.0 Grant

An attempt to delete a grant will fail if it is not revoked. This revocation is handled by VTScada but it may not be possible to do automatically in all cases.

Empty Grant Bearer

Incomplete configuration. You must define the Grant Bearer.

Warning on deleting a provider - associated grants

Grants are linked to providers and will be removed when the provider is removed. Use the OK button in this dialog to confirm that you wish to proceed.

Warning: Grant revocation on provider scope removal

This warning appears when editing scopes for the provider. Any grants using a scope deleted for this provider will be revoked. Use the OK button to continue.

Warning: Grant not revoked on provider scope removal

A grant could not be revoked while attempting to modify the provider scopes. Look for the active grant and attempt to revoke it using the Revoke button.


Two Factor Authentication with TOTP

What is Two-Factor Authentication with TOTP Closed Time-based One-Time Password and Who is it for?

Authentication is the process of verifying that users are who they claim to be. If you signed in to your computer today using a password, that was an example of single-factor authentication. An authentication factor is:

  • Something you know (e.g. a password)
  • Something you have (e.g. a key fob)
  • Something you are (e.g. a fingerprint)

Two-factor authentication with TOTP demands two factors from a user to prove who they are and gain access to a secured account. One of those factors is a password, and the other is a TOTP code provided by something you have, a registered device.

Once two factor authentication is enabled and a device is registered, the user has to provide both of these authentication factors with every sign-in.

TOTP does not need the Internet to work. When a device is registered, your application and the device will share a secret. This tidbit of information and the current time are combined and hashed to produce a secure, unique, and time sensitive passcode. The device and the machine will generate coordinated passcodes because they both know the secret and the time. This makes TOTP especially well-suited for air-gapped systems or systems in places with an irregular connection.

Two factor authentication with TOTP is easy and inexpensive to implement. Once it has been implemented nearly every user account should be using it with very few exceptions. Two factor authentication with TOTP is for everyone except for a single break-glass account.

The few exceptions for exempt users and workstations

You have the final say on exemptions. But the more exemptions that are made, the weaker your security will be.

The break-glass account

Resist the urge to exempt the system admin or super user. Create an account just for this purpose. Exempt only this account. Make sure to use a high-security password and write it down on a slip of paper in a sealed and signed envelope. Keep the envelope in the office in a place where a limited number of people know to look. In the event that the application must be accessed by an account without TOTP, someone will have to retrieve and open the envelope, and then sign in (which is recorded as an timestamped event). The one-time use envelope acts as a substitute authentication factor. It is an alternative to TOTP without sacrificing security.

Users accounts that don't use the user interface

For example, accounts that only use REST API queries or the VTScada Excel Add In. When TOTP is enabled, the Excel Add In works only for exempted users. It is recommended that only remote data access is granted for such user accounts to prevent sign ins or control by less secure accounts. As a general principle, grant no privileges that are not absolutely necessary. General purpose accounts are dangerous.

Workstations that already have MFA

If users must provide multiple factors of authentication to even physically access a workstation (eg. A security check or a key fob to enter the building...), TOTP may be considered redundant.

Special consideration for script-only apps accessed by thin-client

TOTP registration is not supported during thin client sign-in when signing into a script app (eg Application Manager, Source Debugger, etc...).
If you are running VTScada as a service and want to enable TOTP for the Application Manager accounts, you will need to configure it from the Accounts screen.
It is imperative that you register a device for your account (or exempt your account) before signing out from the Application Manager. Otherwise, you will be locked out unless you stop your service and run VTScada interactively.

Configuring two factor with TOTP on your application

To configure TOTP on your application the first step is to enable it for all users.

Enable TOTP in the Administrative Settings dialog. Here, you have the option to reconfigure the time tolerance window, create workstation exemptions or select the label that will be registered in the authenticator. You can find this menu by clicking on your username in the title bar and selecting "Options" (Assuming you have the privileges required.)

This is the menu you can expect to find (You may have to expand the section):

Check the box next to Enable TOTP.

The next time all users sign in, they will be prompted to provide their password and then prompted to register a device. See Two Factor Authentication for Operators for more information on what will be asked of operators. You have the option to access each user account from the Accounts settings to register a device on their behalf or configure user exemptions.

It is a best practice to always have one account that is exempt from TOTP. Ideally this is the emergency bypass "break-glass" account. Credentials for that account should be kept in a secure location and not used otherwise.

Advanced Configuration Settings for TOTP

TOTP Issuer Label

This is the label that will appear in an authenticator.

TOTP Tolerance Window Width (+-)

The number of time periods out-of-sync that can be accepted as a passcode. For example, a width of 1 means we accept the current code, the previous code (-1) and the next code (+1). The minimum setting is 1 to allow for some clock sync tolerance and the natural delay from seeing and typing out the code. The maximum acceptable tolerance is 3 (This would accept the current code, 3 codes before (-3) and 3 codes after (+3).)

The lowest tolerance possible is the most secure configuration. Clock synchronization issues should be resolved instead of weakening the system to accommodate them.

Workstations

To exempt a workstation you must enter the workstation's name exactly how it appears under Workstation Name in the information panel of the application configuration dialog (for that workstation). It also appears in the workstation's PlatformInfo file. Add the workstation by filling in the name and clicking [+].

TOTP-Exempted Workstations

A list of all workstations that have been exempted from TOTP. Remove workstations by clicking to highlight and then clicking the [ - ] button.

If you exempt a thin client server, all thin client connections to that server are exempt from TOTP authentication.

Registering or Removing Devices as a System Administrator

You can register a device on behalf of a user (You will need the physical device in hand). Click on your username in the title bar and go to the Accounts menu. Find the account under "Users" and click on it. Under the section "Multi-Factor Authentication" you will find a box labeled "Devices" with [+][ - ] buttons. Click the [+] button to begin the process.

The other sections have been collapsed for the sake of clarity

Just like a typical TOTP registration process, you will be prompted for a Device Nickname and then presented with a QR code to scan with the device. After the code is scanned, you must type in a code from the device. This guarantees that the device has successfully registered the secret.

To remove a device, click on the device in the "Devices" list and then click the [ - ] button.

If a device is reported missing or stolen, remove it from the user account immediately. Encourage users ahead of time to swiftly report stolen or lost devices. Should the device be recovered, it can always be re-added later. Removing a compromised device as an authenticator is just as pragmatic as having the locks changed if the keys go missing and yet much easier, reversible and an inexpensive security measure.

Syncing Clocks

TOTP uses a shared secret and the current time to coordinate the generation of secure passcodes. This requires clocks on both the VTScada system and the user's authenticator to be closely aligned within a tolerance of seconds. Machine clocks, if not externally controlled, can drift considerably. In an Active Directory system, machines usually take their time from the domain controllers (DCs). It is paramount that the DCs get their time from a reliable source.

For air-gapped systems with no access to an external time source, use of a GPS-controlled network time server will be required. This solution is relatively inexpensive.

Security Best Practices

TOTP has some inherent weaknesses. It is important to be aware and to plan and enforce counter-measures to keep your system secured.

  • Consider communication vulnerabilities in all of the devices used in TOTP. Use TLS 1.2 or 1.3 for all communication.
  • Encourage secure practices for devices used to retrieve an OTP. Phones should be password protected, and users must be educated about phishing attacks.
  • Be mindful of shoulder-surfing when the passcode and QR code are displayed. Just like at the ATM, keep secure information shielded from line-of-sight.
  • Complete registrations quickly to avoid long-standing unregistered accounts.
  • Have as few exemptions as possible.

How to create exemptions for specific accounts

There are a few rare reasons to exempt an account from two factor TOTP. The more exempt accounts you have, the less security you have. It is a Worst Practice to exempt administrators or super users. TOTP will work for users or workstations with unreliable or no access to the internet.

To exempt an account, go to the Accounts menu. Find the account under "Users" and click on it. Under the section "Multi-Factor Authentication" you will find a check box labeled "TOTP Exempt User". Check to enable and exempt the user. Don't forget to apply the changes.

Related information:

TOTP Definitions and Key Concepts

Two Factor Authentication for Operators


TOTP Definitions and Key Concepts

Terms used with TOTP

TOTP/OTP

Time-based One-Time Password as defined in RFC 6238. VTScada's OTPs are numeric.

Authentication

Authentication is the process of verifying that a user is who they claim to be. TOTP authentication proves the user by requiring them to possess a registered and (presumably) secured device in order to provide a time-sensitive one-time password to log in.

Authenticator

A tool or application that verifies the user is who they claim to be. Two popular authenticators are Microsoft Authenticator and Google Authenticator.

Prover

Prover is the term used in RFC 6238 for what is often called the authenticator. You made need to select the prover from a droplist if you have registered multiple provers.

Two-Factor Authentication (2FA)

A security method that requires users to provide two independent forms of verification to prove their identity.

Multifactor Authentication (MFA)

A security method that requires two or more independent forms of verification to prove identity.

Key Concepts - TOTP Essentials

TOTP makes use of a simple algorithm to enable two isolated machines (like a cell phone and a workstation) to independently generate identical passcodes.

By going through the registration process, a secret known by VTScada is shared with the registered device. Each generated secret is random and time sensitive. VTScada only displays the secret at registration time for 90 seconds. After the secret is shared, the user must enter a time-sensitive one-time passcode from the device they're registering. This guarantees that the secret was successfully shared.

At this point, the VTScada application and the registered device share a secret. The secret is combined with the current time and both machines use the same secure hashing method to independently produce an identical 6-digit time-sensitive one-time passcode.

Using the same secret, same time and same secure hash method, your device and VTScada expect matching passcodes.

GPS controlled network time server

In an air-gapped system, for accurate clock synchronization you can use a GPS controlled network time server. This is a dedicated server that receives precise time data from GPS satellites without the need for external network access. GPS controlled network time servers can be purchased inexpensively from specialist retailers.


Troubleshooting Two Factor with TOTP

The following troubleshooting guide is intended to explain error and warning dialogs and offer advice for resolving common stumbling blocks when configuring two factor with TOTP.

Troubleshooting should begin by reviewing Two Factor Authentication with TOTP

Error and Warning Dialogs

Registering a Prover (device) has failed due to bad code

The passcode that you have entered does not match the passcode that VTScada expects. There are a few possibilities:

  • The passcode was not entered correctly
  • The passcode was not submitted within the allocated time
  • VTScada and the authenticator are using clocks that are out of sync with each other

If this error is occurring frequently you may be able to resolve it by increasing the TOTP Tolerance Window Width, however, if the cause of this re-occurring error is due to out-of-sync clocks, the most secure solution is to correct the clocks.

Registering a Prover (device) has failed because of a duplicate name

You have attempted to use a Device Nickname that already exists for that user account. User accounts can have more than one device. The first device is typically added by the operator at sign-in time and subsequent devices can be added by a user with Account Modify privileges. Or any administrator with the privilege to access and modified Account Settings. You can see all of the devices registered to a user from the Account Settings.

  • If you are trying to register a new device with the same name as a device that is registered but no longer used, remove the old device first.
  • If you are trying to register more than one device with the same name, consider adding a unique identifier to the end of the name. Ex. Phone 1, Phone 2.

Warning: You are about to remove a registered device from a user account

  • If a device is removed, it can no longer be used to authenticate a user.
  • Devices can be re-registered after they have been removed. (For example, recovering a lost phone)
  • If the user account has no registered devices and is not exempt from TOTP, the next time they sign in they will have to provide their password and register a new device.

Exempting a workstation failed because a workstation by that name is already exempt

You have attempted to exempt a workstation by a name that is already on the exemption list.

  • Confirm that the workstation you intend to exempt is already on the list
  • Confirm the exact spelling of the workstation you intended to exempt.

Troubleshooting

Users report several failed attempts to enter passcode

The most likely culprit is that the clocks are out of sync so the workstation and the authenticator disagree on which passcode is currently valid. To confirm this, try to increase the TOTP Tolerance Window Width in the Administrative Settings dialog. This will permit the use of a passcode that is one or two steps removed from what the workstation believes is the current passcode. This solution should be temporary. Once you have confirmed the clocks are out of sync, synchronizing them should be the priority.

This scenario illustrates a good reason to have a break-glass account. If the clock on one or more servers has fallen significantly out-of-sync and cannot be corrected all TOTP authenticators would generate mismatched passcodes. In this case, the break-glass account would give you emergency access to take corrective action.

Passcodes are one-time use. VTScada does not let you sign in with the same TOTP code more than once, even if the code is still current. If you sign in, out and in rapidly the passcode will fail even if it is current. When registering a device, you are asked immediately to provide a code to complete registration of a device. If you try to use the same code to sign in shortly after, it will fail. You will have to wait 30 seconds for a new code to be generated.
This is by design to mitigate the risk of replay attacks. If someone knows your password and is watching you as you type in your OTP code, they cannot quickly log in from another device with the same code.


Windows Security Integration

You can choose to use Windows® security integration in place of, or in addition to, VTScada user accounts. The VTScada Security system has three basic elements: Accounts, Roles & Privileges. When using Windows Security Integration, accounts (users) are managed in Windows. The privileges that are related to VTScada functionality are managed within the VTScada Security Manager, via assignment to roles. Windows accounts are linked to VTScada roles using Active Directory Groups that are named for the VTScada roles.

Benefits and differences:

  • External account control.
  • Fewer passwords for users to remember.
  • Privilege sets are created only for roles, which are then assigned to accounts.
    It is not possible to assign privileges directly to Windows-based accounts.
  • Rule-Scope can be applied to privileges within a role, but not to roles assigned to accounts.
  • Limited control over domain account configuration within VTScada. Passwords cannot be changed and privileges cannot be granted

When Windows Security Integration (WSI) is in effect, VTScada managers (accounts with both the Manager privilege and the Administrator privilege) retain responsibility for granting privileges to roles. They may also disable individual accounts and can set the automatic log-out time for each account.

Alternative ID values, for the Alarm Notification system and other purposes, are still controlled within the VTScada interface.

Using Both Windows and VTScada Authentication

It is possible to have both VTScada accounts and Windows accounts. Accounts that existed prior to the enabling of WSI will continue to exist, but it is expected that many sites will prefer to disable or delete some or all of those accounts. If there are users who should have access to the SCADA system but not have an account on the domain, they should be given a VTScada account within the application. This feature might be used to send out application ChangeSets to someone who is trusted to work on the application, but who will not be given access to the corporate network.

A feature of WSI is that authorized users may logon with their full account name (myname@company.com) or with their user name (myname). If that user name matches a valid VTScada account name, then it will be assumed that the user intends to logon with the VTScada account. A dialog will open during the logon process to remind you of this.


Enable Windows® Authentication

All VTScada accounts will continue to exist when Windows Security Integration (WSI) is enabled. You may choose to disable some or all local accounts in favor of domain accounts.

Windows security groups map to VTScada roles with the addition of "VTScada-" before the role name. Thus, the role "Operator" maps to the security group, "VTScada-Operator" and the role, "SuperUser" maps to the group, "VTScada-SuperUser".

The prefix "VTScada-" is stored in the application property, ADGroupPrefix, where you may change it if desired. VTScada roles, including role names and assigned privilege sets, are under the control of anyone with the Manager security privilege.

Review the related notes before proceeding: Windows Authentication Notes

Clicking the option, Enable Windows Security Integration in the Administrative Settings dialog is step 6 in the instructions, which follow two steps of preparation. Do not rush ahead.

Preparation

  1. Ensure that the VTScada workstation is running as a member of a Windows domain.
    The "Enable Windows Security Integration" check box is disabled if VTScada is started on a machine that is not a member of a Windows domain.
  2. Ensure that you are a Windows Domain Administrator, or that you have access to one who is available to assist with certain steps in the following procedure.

Enable Windows Security Integration

  1. Enable VTScada Security and create an account with the Manager and Administrator privileges.
  2. You are advised to set up preliminary VTScada roles and custom privileges at this time.
    Windows accounts are associated with VTScada roles as described above. You can add new roles and adjust privilege sets at any time.
  3. Have your Windows Domain Administrator create security groups that are named for the roles in your application.
    The Active Directory Security Group names should use the form "VTScada-RoleName".
  4. Ensure that your Windows user account is given membership in the appropriate Active Directory Security Groups from the previous step.
  5. Decide whether to enable the property AutoAddADUsers.
    Cannot be enabled when security realms are in use. (A user realm delimiter has been defined.)
    If enabled, domain accounts are created within VTScada with each successful logon.
    If not enabled, you must create a domain account in VTScada, using the form "username@company.com" for each user.
  6. Open the VTScada Administrative Settings dialog.
    ("Options" in the security menu.
    Ensure that the Advanced section of the dialog is expanded.)
  7. Select the option, Enable Windows Security Integration.
  8. Read, then acknowledge the warning.
  9. Click, OK.

Test by logging out, then sign in using your Windows account and password.

It is not possible to assign privileges or passwords to domain accounts. Privileges for these accounts are determined by their membership in domain groups, matching VTScada roles.

Troubleshooting:

  • Unable to sign in with your Windows account.

Ensure that your Windows account is associated with a Security Group, named correctly for the VTScada role.

You may need to allow the domain controllers several minutes for the change to propagate.

  • Upon signing in with just your user name, you are now signed in with a VTScada account rather than your Windows account.

Both a Windows account and a VTScada account exist with a matching user name. If this is by intent, use care to sign in with your full Windows account name, "User@company.com" when using your Windows account, and just "User" when using your VTScada account.


Windows Authentication Notes

Definitions:

  • Authentication ensures that you are who you say you are.
  • Authorization relates to the privileges accorded to your account following authentication.
  • WSI = Windows Security Integration
  • LDAP = Lightweight Directory Access Protocol
  • AD = Active Directory
  • SG = Security Group
  • The prefix "VTScada-" is set by the property, ADGroupPrefix.

When enabled, VTScada uses Windows® Authentication services, which connect to the domain controllers using a secure channel. For your applications, Windows Security Integration is enabled through the VTScada Security Manager's Administrative Settings dialog.

After an account is authenticated, the privileges accorded to that account are determined by its membership in Active Directory Security Groups that are named for VTScada roles. VTScada privileges are assigned to roles, not to domain accounts. The queries are performed using the default settings for the machine, which are set in the domain group policy.

Windows accounts that do not have membership in at least one of these security groups cannot sign in to VTScada.

WSI mode uses the LDAP default naming context for the host machine as a basis for the AD account query operations. This is the LDAP equivalent of the domain to which the host machine is joined and thus does not support user accounts from a domain other than that of the host machine.

Upon logon, and at regular intervals while an account is signed in, VTScada will check that the domain account is still enabled and the list of active directory groups it is a member of, updating the logged-on account's privileges as needed.

Active Directory Security Groups

Active Directory Security Groups must be created by someone who has permission to modify AD security groups. To work with VTScada, these must be named by prepending the letters "VTScada-" before the VTScada role name. For example, "VTScada-Operator" and "VTScada-Configurer".

The prefix "VTScada-" is set in the application property, ADGroupPrefix. Role names are under the control of the VTScada manager, and so may vary from these examples. This property can be edited only by working directly in the application's Settings.Dynamic file.

Accounts are accorded privileges in VTScada according to their role (SG) membership. It is not possible to grant privileges to accounts directly.

The title bar will display the Windows account "displayname" attribute rather than the Windows logon name, e.g. "Another User" rather than "another.user@company.com".

Realm Filtering

If you are using realm filtering within your VTScada application, Active Directory users cannot be added automatically. You must add each AD user directly in VTScada, along with the realm:

"realm:another.user@company.com"

An AD account can be associated with only one realm. VTScada does not support having the same AD account in multiple realms or using the same AD account as both a member of a realm, and also a super-user who is not a member of a realm.

Running Multiple Applications with WSI

In the situation where two or more VTScada applications are running, it may be necessary to distinguish between them for logons. The recommended practice is to set a different ADPrefix value for each application. For example, if a site has both a water treatment application and a power generation application, then instead of using "VTScada-" for both, they might use "Power-" for one and "Water-" for the other. It would then be clear whether an account was a member of the "Power-Operators" security group, "Water-Operators" security group, or both.

Alternatively, you could ensure that role names are unique in each application.

If you have enabled WSI for two or more applications, you have not set a unique ADPrefix value per application, and you have not created unique role names in each applications, then an account with access to the ADPrefix-RoleName role will have that role in both applications. (For example, VTScada-Operator.) This may cause confusion if the privileges assigned to the role vary between the two applications.

Account caching

For accounts that have been added to the VTScada Security Manager, either automatically or manually, the VTScada host machine will cache Windows logon credentials (if permitted by AD Group Policy) such that if the machine is temporarily isolated from the domain, e.g. a laptop out in the field, then user logons will succeed for those logons that have been cached.

Account roles are not updated when isolated from the domain. Attempts to logon with an account that has not been cached on the host machine will fail.

Credentials are stored in a manner that meets current industry best practice.

You can configure the VTScada Security Manager to add Windows accounts automatically upon first successful log-on. By default, automatic storage is enabled. To change the configuration of automatic storage of domain accounts on, add the property, AutoAddADUsers, to the <SecurityManager> section of your application's Settings.Dynamic file.

If Windows domain accounts are not being stored automatically, then a user with the Manager privilege must add accounts to VTScada individually.

When connected to the domain, the Security Manager's cached set of account rules are updated on each domain logon. A periodic check (default 15 minutes) is made to ensure that each logged-on Windows account is still enabled, updating its assigned roles if necessary.

If the WSI option is deselected, cached domain users remain in the cache and may continue to logon using their domain accounts until those accounts are deleted from within VTScada.

Application Properties

The following privileges in Settings.Dynamic are used when Windows Authentication and Active Directory Authorization are in effect:

  • ADGroupPrefix - The prefix added to a VTScada role name for the equivalent AD Security Group.
  • ADRefreshPeriod - The interval in seconds between checks for changes to the signed in users account in Active Directory.
  • AutoAddADUsers - Enable within the security Options dialog (Administrative Settings) if you want VTScada to automatically add domain accounts to the local cache upon successful logon. If a domain account is not cached in VTScada, logon is not possible when the workstation is disconnected from the domain.

If using Windows Security Integrationand Security Realms, you must add the realm name and prefix to the account using the VTScada accounts dialog. (e.g. realm:username@company.com)
AutoAddADUsers cannot be enabled when a security realm delimiter is defined.

VTScada as a Windows service

Windows Security Integration can be used when VTScada is run as a service, but the account that the service is run under must allow the COM operations required for the AD queries. A domain account must be used.

Warning for Internet and Mobile Client Connections

Thin clients transmit the user sign in credentials (username and password) using Basic Authentication, which is a simple, non-encrypted, Base 64 encoding of "username:password", and which can be decoded by network snooping tools if they can capture the message content. Wireshark as one example, will show the decoded credentials if connected to a local machine or switch that performs the communications (Because switches don't broadcast network traffic for all to hear, the "listener" must be local to the communications path versus being anywhere on the network.) If Windows Security Integration mode is enabled, then the potential consequences will extend beyond the SCADA system should the operator's Windows credentials be stolen.

To secure user credentials against listeners that may have access to switches or workstations carrying this traffic, it is essential that you encrypt thin client sessions with TLS (transport layer security) by installing an X.509 certificate on the VTScada Internet server. The certificate can be obtained from a 3rd party issuer such as Verisign, Thawte, GoDaddy, from an organization's own Certificate Authority (CA) infrastructure, or via local ad-hoc creation. (e.g. By using Open SSL tools.) To allow clients (browsers) to verify the certificate and not display an untrusted warning, they need the "root" certificate from the CA to be installed. The root certificate for most third-party issuers is already installed in most Web browsers.

VTScada maintains a salted, key-stretched, SHA2-512 hash of the Windows Logon password in the same manner as Security Manager logon passwords and this meets current industry best practice.

Authentication is always carried out by the server the client is connected to. Thin clients use the thin client server they are connecting to for authentication. If the application is configured for WSI mode, then the thin client server MUST be able to authenticate the user with the domain controller and successfully make the required LDAP queries against the domain. If the domains are in separate forests (e.g. servers.com and users.com) then a forest trust will have to be configured so that the users domain trusts the servers domain.

Slow Sign ins Due to Large Numbers of AD Groups

In circumstances where the user belongs to a large number of AD security groups (where large is defined as greater than 100), the LDAP query can take time to execute, resulting in a slow logon.

You can improve logon performance by configuring VTScada to restrict AD LDAP queries for the user and group to a specific portion of the AD LDAP tree.

Use the following information only when absolutely necessary in the circumstance noted. A side effect is that external changes to the AD such as renaming an OU specified in a search base will then cause all AD logons for VTScada to fail.

You can add two options for Security Manager configuration to the <SECURITYMANAGER-ADMIN> section of the application's Settings.Dynamic file.

  • ADUserSearchBase
  • ADGroupSearchBase

These entries are used to restrict the AD LDAP queries for the user and group respectively to a particular portion of the AD LDAP tree.

By default, if the entries are not present the Default Naming Context (DFN) is used, which points to the root of the AD forest. For example, for a domain "example.com" the DFN is "dc=example, dc=com".

Each entry can be set to a portion of the AD LDAP tree using LDAP syntax, e.g. "OU=SCADA, dc=example, dc=com" to restrict that particular search to the SCADA OU in the example.com domain.

Related information:

AutoAddADUsers

ADGroupPrefix

ADRefreshPeriod

VTScada as a Windows® Service

ADGroupSearchBase

ADUserSearchBase


Smart Card Support

As of version 12.0.09, VTScada supports the use of smart cards, which provide a form of 2-factor authentication. Successful authentication requires something you have (the smart card itself) and something you know, (the Personal Identification Number (PIN) for the smartcard).

Smart cards can be used only in conjunction with Windows Security Integration (WSI) on both a thick client (workstation) and the VIC thin client.
Smart cards are not supported on the VTScada Anywhere client, nor on the Mobile Internet Client (MIC).

* Computer names (aka NetBIOS names) or IPs can be used in a server list only if all machines, including your VTScada Internet Servers and thin clients, are on an internal network.

* If some machines, clients or servers, are in different domains, then the list should include only fully-qualified domain names (FQDNs).

* If the names used by external clients to connect to your servers, (that is, names that are resolvable by an external DNS) are different from the internal machine names (those that are resolvable by your internal DNS or other methods) then your server list should use the external/public FQDN (the TLS certificate name) in the server/connection list; on the LAN, ensure that same FQDN resolves to internal IPs via split DNS or a HOSTS entry. Your internal name resolution mechanism (DNS or other) should be configured to resolve those names to the internal IPs of the servers.

For example: sitewatchanywhere.co.uk in Connection Addresses --> internally resolves to 10.10.10.5, 10.10.10.6

* Do not attempt to provide both internal and external names for the same server. Doing so will only cause slower overall performance.

Smart cards must contain a certificate that can used to authenticate a user in an Active Directory (AD) domain. To do this, the certificate should have a Subject Alternative Name (SAN) entry containing the User Principal Name (UPN) of the user account. For example, "a.user@example.com". Use of WSI mode is a prerequisite for smart cards and the smart cards can be used only for AD account sign-ins, not local VTScada Security Manager sign-ins.

Windows Security Integration is required for smart card Authentication

At a workstation, a smart card can be used to sign in with dialog that is associated with the application title bar. No other sign-in dialogs are supported.

Sign in at a workstation using your smart card

  1. Insert your smart card into the provided reader, attached to your workstation machine.
    The card is read and the certificates on the card are examined. If a single suitable certificate is found and no user is currently signed in on this workstation, the sign-in dialog opens.
  2. Enter the PIN associated with your smart card.

If you are running multiple applications and can sign in to each with your smart card, then you must do so for each independently.

If you remove your smart card from the reader, or the reader from the workstation, you will be signed out immediately from all applications that use the card.

If the smart card contains multiple certificates, then after VTScada reads those the certificates, it presents a dialog allowing you to select the certificate to be used. You can preselect a certificate by defining the property, SmartcardUPNMatch within the [System] section of the Setup.INI file in your VTScada installation folder, thereby avoiding the chooser dialog.

A certificate is shown:

Use the More choices link to view and select from other certificates.

After choosing a certificate, select the OK button. If you select Cancel, you must remove and re-insert the smart card to begin the process again.

The following section applies only to VTScada Internet Client (VIC) connections.

Active Directory Configuration to Support VIC Sign-ins

Two work flows are supported:

  • The first involves starting the VIC session with smart card support and is suitable when a given workstation is used by a single operator.
  • The second involves starting the VIC session normally (not with smart card support) and then signing in using the smart card. This is suitable when a workstation is used by several operators.

For both work flows, you must ensure that WSI mode is enabled for the application. Your Active Directory (AD) setup must be configured as follows:

A Service Principal Name (SPN) must be set in AD for all the VIC servers and the user account under which VTScada is running on the servers.

Domain Admin privileges may be required to set the SPN using the SetSPN command from an elevated command prompt:

SetSPN -U -S HTTP/<FQDN.Of.VICServer> <user.account>

Where <FQDN.Of.VICServer> is the fully qualified domain name of the VIC server, (for example: SCADA1.EXAMPLE.COM) and <user.account> is the sign-in name of the account without the "@my.domain" portion.

The SPN can be verified using the command:

SetSPN -L <user.account>

The preceding command shows the SPN’s for the account and should list the entries for VIC servers in the form:

HTTP/<FQDN.Of.VICServer>

1) Starting the VTScada Internet Client with smart card support

For this work flow, the VIC must be started from the command line, not Internet Explorer, following the examples within this section.

No extra configuration of your VTScada Thin Client Server is required when starting a VIC session with smart card sign-in support. To enable smart cards, the VIC command line must include the -c argument, along with -s and -a arguments.

  1. Start the VIC using the following command line, or a Windows shortcut you create that contains this command line:
Path\to\VTSX.exe -s URL_of_VIC_Server -a Realm_of_application -c

A dialog will prompt for the smart card:

  2. Insert your smart card into the reader. The following dialog will be shown:

If a single suitable certificate found on the smart card the VIC proceeds to display the Personal Identification Number (PIN) entry dialog. If more than one certificate is found on the smart card, a dialog is displayed as described in the workstation section. After a certificate is chosen, a PIN entry dialog is displayed:

  3. Enter your PIN and select the Connect button.
    If the PIN is correct, the client will connect to the VTScada Thin Client Server and you will be signed in.

Removal of the smart card from the reader, or the reader from the workstation will cause VTScada to sign you out immediately. If you were signed in using the VIC, the connection will be closed.

2) Use a smart card to sign in to an ordinary VIC session

If using this method, operators can remove their smart card to sign out without causing the VIC connection to close.

When an operator signs in or out with a smart card, the entries in the System Event history are annotated with “using Smartcard” to distinguish them from “manual” logons.

This requires that the Security Manager option to "Enable Signed Out VIC Sessions" is set to maintain the session after Smartcard removal and sign out.

  1. Ensure that WSI mode is enabled for the application as described earlier.
  2. Perform the tasks described in Active Directory Configuration to Support VIC Sign-ins
  3. Add the following value to the <SECURITYMANAGER-ADMIN> section of your application's Settings.Dynamic file:
    VICSmartcardsEnable = 1
  4. Use the Import File Changes Tool to put that change into effect.
  5. To prevent the session from closing on sign-out, ensure that Enable Signed Out VIC Sessions is selected.

Operators can open a thin client (VIC) connection and authenticate their sign-in by inserting their smart card in the reader. On removal of the card from the reader, they will be signed out immediately, but the session will remain active, waiting for the next operator to sign in.

If the user fails to authenticate with Active Directory, a dialog is displayed to indicate the authentication has failed and an event is logged in the System Event DB.


Proximity Card Readers

Proximity card readers are RF (Radio Frequency) devices, commonly issued to employees to permit access to a secured area by swiping or holding the card near a detector.

You can attach a proximity card reader to your workstations, then associate an employee's account to their card. Users can then sign into their VTScada account by simply swiping their card by a reader.

While a proximity card can be used for several purposes, this topic refers only to signing in to your VTScada account.
The instructions here will not help you to sign in to Windows or integrate physical security at your site with your VTScada application.

USB - connected devices are supported. Install and configure your device according to the manufacturer's instructions.

Set the property pcProxEnable to 1 so that VTScada can recognize the device.

After this property is set, VTScada will begin scanning all ports between those identified by the properties pcProxPortScanLow (3) and pcProxPortScanHigh (16), excluding those on which a modem has previously been detected. When the device is found, VTScada creates a connection to it.

Following this, all that remains is to associate each user's account with their card

Set an Alternate ID for a proximity card reader:

  1. Install a proximity card reader.
    This is done outside VTScada. Follow the manufacturer's instructions.
  2. Open the VTScada Application Configuration dialog, Edit Properties page.
  3. Set the application property, pcProxEnable to 1.
    VTScada will scan for the device.
  4. Close the Application Configuration dialog.
  5. Open the Accounts dialog and select the user.
  6. Swipe that user's proximity card through the card reader.
    (Do not open the Alternate Identification dialog.)

You may want to sign out, then swipe the card again to verify that it will work to allow the user to sign in to their account.

Close the accounts dialog. From this point onwards, the user can sign in to their account by allowing the device to detect their card.

At the time of writing, only proximity card readers from RF Ideas that support serial port emulation are supported by VTScada.
Readers that use only keyboard emulation are not supported.

Proximity card readers cannot be used for thin-client connections. (VIC, MIC and Anywhere Client)

Related information:

pcProxEnable - Application property setting to enable a proximity sensor.

Related Tasks:

Create Accounts and Roles

Configure Alternate Identification


Read-Only Workstation

The default system privilege mask for a read-only workstation does not grant the configuration privilege or the edit files privilege. If you configure the workstation you are using to be read-only, you will have no means to do further configuration at that workstation, or even to reverse that change. Your only recourse will be to move to another workstation on your system and use the Version Control system to reverse the change.
*******************************************************
*** DEFINING A WORKSTATION TO BE READ-ONLY ***
*** IS BEST DONE FROM ANOTHER WORKSTATION. ***
*******************************************************
(A remote connection using a VIC or Anywhere client does not count as working at another workstation. Do not proceed unless your application has a Client / Server Configuration)

You can configure a workstation to have read-only access to an application, regardless of the privileges assigned to the logged-in user at that workstation.

This is especially useful for workstations located in unsecured areas or for a server providing VTScada Thin Client access. If the workstation configured as read-only is also a VTScada Thin Client Server, then all VTScada Thin Client connections to that server will have read-only access.

Configuration of what can be done from a read-only workstation is done using three workstation-specific properties:

ReadOnlyStation

When set, the station can display I/O data but not write to hardware. No operator will be able to write to hardware from this station, regardless of their privileges, and without exception. Attempting to write reports to a read-only station from another station is also not possible. This setting places no other restriction on the signed-on operator and they will be able to do all other tasks within the application according to their privilege set.

StationMaskSys

Relevant only on workstations where ReadOnlyStation is set. Does not apply otherwise. This is a bitwise value that controls which system privileges are enabled at a read-only workstation. By default, only the following privileges are granted. (Assuming that the signed-in operator has also been granted these privileges.)

  • Account Modify
  • Application Stop
  • Thin Client Access
  • Alarm Page Access
  • History Page Access
  • Page Note Hide
  • Sites Page Access
  • Maps Page Access
  • Global Tag & Area Filter
  • Recipe Page Access
  • Remote Tag Value/History Retrieve
  • Services Page Access
  • Parameter View
  • Remote Data Access

StationMaskApp

Relevant only on workstations where ReadOnlyStation is set. Does not apply otherwise. This is a bitwise value that disables specified custom privileges for all operators who sign in on that station, regardless of the privilege set granted to their account. None are disabled by default.

The read-only workstation setting takes precedence over all security privileges related to writing I/O. If set for a particular workstation, then all I/O write access is denied. Attempts to operate any control can result in the Access Denied dialog box being displayed. Attempting to write reports to a read-only workstation, even from a station with privileges, simply won't work.
There are no exceptions to this rule. There are no methods to enable partial write access at this workstation, or to grant write access to some users but not others at this workstation.

Note that you can also create Rules for Privilege Scope so that an operator's privileges are in effect only at named workstations. This provides more flexibility in controlling who can do what from where, but at the cost of not providing simple, blanket-coverage that applies to all operators.

To configure a workstation as read-only, add the following line to the [System] section of that computer’s Workstation.Dynamic file, and import the file into the application's working set.

[System]
ReadOnlyStation = 1

a Workstation.Dynamic file is not named "Workstation.Dynamic". Substitute the name of the computer to which the configuration variables should apply, for the word "workstation". You can have a different workstation. dynamic file for each workstation in your network.

To add or change application properties, you must have the Configuration privilege or the Edit Files privilege. Note that this means than anyone with those privileges can make changes to these settings.

Steps to define a read-only workstation:

  1. Open the Application Configuration dialog.
  2. Click on the Insert button

The Add Property dialog will open.

  3. Set the property name to ReadOnlyStation
  4. The section should remain as System
  5. Set the value to 1.
  6. Select the workstation where this will apply.
    In most cases, it is unlikely that you want your current workstation to become read-only.
  7. Enter a comment, describing the new property.

Comments will be stored on the line below the property in the Workstation.Dynamic file.

  8. Select OK

The dialog closes. Note that the new property is not saved until you apply your changes.

  9. Select Apply.

The Comment dialog will appear.

  10. Type a comment into the Comments dialog and click OK.

This comment is for the VTScada version control system and should explain why the new property is being added, unlike the earlier comment that explains what the property does.

Station Masks

A mask is a series of bits (0's and 1's) that are compared to a template using a bitwise AND. Every bit has a unique meaning. If the same bit is set in both the template and the mask, the meaning assigned to that bit is enabled. Typically, all bits are set to 1 in the template.

Numbering is zero-based and bits are counted from right to left. For example, a mask that is one-byte wide (eight bits) might be written as the following:

StationMaskSys = 00000010;

In this example, only the second bit (bit number 1 - Account View privilege) is set. (The bit furthest to the right is bit number 0.) For the purpose of a station mask, custom privileges are numbered in the same way, even though the number shown in the Privileges dialog will be 16 greater than the matching bit number.

The first four bits of the station privilege template are defined as:

Bit # | Meaning
0 | Configure privilege
1 | Account view privilege
2 | Account modify privilege
3 | Accounts manager privilege

For further information, refer to the two station mask properties: StationMaskApp and StationMaskSys


Internet Security (TLS, X.509, SSL)

VTScada supports TLS version 1.3

"SSL" is the acronym for the Secure Sockets Layer security protocol. SSL is an older technology, but the term has become the de facto name for Internet security. VTScada uses the more modern Transport Layer Security (TLS) protocol (although, for the sake of compatibility with older Windows operating systems, it can use SSL.)
While the term "SSL Certificate" is in common use, "X.509 Certificate" is the correct term.

Installing a Certificate and configuring VTScada to use it, is not an inherently difficult process, but it is frequently a cause of frustration. Sometimes significantly so. Every step in the process must be followed carefully, skipping none.

Certificates expire and must be renewed. After purchasing your certificate, take note of the expiry date and create one or more Trigger Tag + Alarm Tag pairs, configured to alert you when it is time to renew the certificate.

Terms:

CA.

A Certificate Authority. Responsible for issuing certificates and maintaining Certificate Revocation Lists (CRL).

Private key

Most often held in PEM format, this is a Base64 encoded blob surrounded by "-----BEGIN PRIVATE KEY-----" and "-----END PRIVATE KEY-----". Can also be be encrypted and then has the header "-----BEGIN RSA PRIVATE KEY-----" followed by "Proc-Type: 4,ENCRYPTED". This MUST be held securely, if lost, the certificate is useless and must be re-issued. If leaked, others could pretend to be your host.

X.509 certificate

This contains, among other things a public key corresponding to a private key, and identifying information for the subject (host) of the certificate and the issuing authority. Usually in PEM format, surrounded by "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".

Often a text version of the certificate is also in the file, this is ignored by OpenSSL and the Windows certificate manager. Can be re-issued by the CA.

PFX file

This is a #PKCS12 format file containing a certificate and a private key. Often includes additional root and intermediate certificates. Encrypted.

An X.509 certificate is a digitally-signed authentication that fulfills the following requirements:

  • Identifies a host computer, organization, or individual, carrying with it an assurance (warranted by a Certification Authority (CA)) that the host computer, organization, or individual is whom they represent themselves to be, and providing an electronic means of verifying that a communication came from that individual, and not from someone else posing as them.
  • Contains a public key and provides assurance that the key has not been tampered with.

A certificate that is digitally-signed by a CA can be trusted on the basis that a CA will not digitally sign a certificate unless they have adequate proof that the host computer or individual has a right to represent itself by that information.

Account name and password authentication is all that protects access to the VTScada Thin Client Server, unless you use other security mechanisms, such as a virtual private network (VPN)). The web or mobile browser needs to be sure that it is communicating with a legitimate VTScada Thin Client Server before transmitting a name and password. To protect these authentication credentials, Transport Layer Security (TLS) is used, with the VTScada server providing a certificate to the web browser or VIC.

A certificate carries with it a public key that is secure and has not been tampered with. This public key is half of a pair of an asymmetric set of keys. One key is called the private key, while its mate is called the public key. Data encrypted using the private key can only be decrypted using the public key, and data encrypted using the public key can only be decrypted using the private key.

The private key is held securely by the organization that owns the certificate containing the public key (e.g. your organization). No one, not even the CA who issues the certificates knows the private key, rather the CA knows only the public key, and digitally signs the certificate to provide assurance that the public key it holds is the mate to the private key held by the party receiving the certificate.

You must safeguard and keep backups of the private key, as well as the X.509 certificate.

VTScada provides tools to help you generate a request for a certificate from a Certification Authority (such as VeriSign) using the X.509 Certificate tab of the VTScada Thin Client/Server Setup dialog. This request is formed and deposited on your Windows® operating system clipboard. You may then send this request to the CA, either by email, or using an online form (if provided by the CA at their web site). The request is persistently lodged in the VTScada Thin Client Server request store, and when the reply arrives from the CA, the VTScada Thin Client/Server Setup dialog must be used again to process the reply from the clipboard into the server's store. This processing phase removes the request from the request store and places the certificate into the server's certificate store, binding it to the correct private key.

It is highly recommended that you use the Microsoft Management Console (MMC) to backup the certificate and private key. If the registry has to be restored or is lost, the private key will be permanently lost as well. If you do not have a backup of your private key, there is no way to re-generate it. If you irretrievably lose your private key, you will have to purchase a new certificate. Therefore, you should ensure that you store your certificate request and subsequent certificate in PKCS #12 (.PFX) format, and include the private key in the backup.

Before processing a certificate, you must sign in to Windows using an account that has administrative privileges. Make the certificate request on the same PC that will be the VTScada Thin Client Server. After you've done so, you may back up the certificate and copy it to the PC for which the request was made.

The key is encrypted to protect it during the backup process. You are therefore required to enter a password.

Best practices for thin client servers in a DMZ (demilitarized zone)

A VTScada thin client server can support VICs, Anywhere Clients and MICs. The thin client server is a full featured VTScada RPC client that can connect to any other VTScada "thick" server that will accept connections and can also accept inbound connections from a thick server. When RPC communications is established, data flows in both directions over the RPC channel. The thin client can be configured to be "Read-Only" but this only affects tags so that the client can't write tag outputs, but it can still write many other kinds of data to the thick servers.

Given this, the current best practice for deploying a thin client server would be:

  • Deploy the minimum number of thin client servers that are required for the redundancy \ geographic distribution \ load requirements of the system.
  • Deploy the thin client servers in a separate firewall zone from the thick clients. The firewall will have to allow TCP access on port 5780 between the thick clients and the thin client servers but this can be restricted to only allow connections to be initiated from the thick client servers.
  • Consider using a secure channel for the connection between the thick and thin client servers, e.g. IPSec.
  • Client access to the thin client server (i.e. VIC etc.) should be controlled via firewalls as required in a further zone and protected by TLS as required.
  • Disable all unused ports on the DMZ server(s). VTScada only requires TCP/5780 for RPC communication, plus whichever port(s) thin client connections use.
  • Always use TLS connections to thin clients.

Limit Connections to Allow Only Newer Versions of TLS

VTScada uses the SChannel TLS settings provided by the host operating system (Windows), therefore that must be configured to restrict TLS versions that are deprecated. This task cannot be done within VTScada. Refer to the instructions provide by Microsoft at the following URL:https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings

Note that for VTScada as a server (thin client or otherwise) the "Server" settings will be required. To modify client use (that is, when VTScada connects to other TLS servers or when running the VIC) the "Client" settings will be required.

Related:

Define the Connection Addresses

Internet Realm

Securing a VTScada Thin Client Server

Secure Your Application


Generate a Request for an X.509 Certificate

Use the X.509 Certificate tab of the VTScada Thin Client/Server Setup dialog to request new certificates for your VTScada Thin Client Server.

Notes:

The Windows certificate store has two locations: one is per-user (the Current User store) and other, per-machine (the Local Computer store). When you generate the certificate request, it is held in the per-user store for the user making the certificate request.

When the certificate comes back from the CA, it is processed by associating it with the original request. As the original request is held in the Current User store, this processing must be done by the same user who made the certificate request, on the same computer as the request was made on.

The completed certificate must then be moved from the per-user store to the per-machine store.

You must use an account in the local administrators group, as access to the per-machine store is restricted. If your site follows good security management procedures, this is unlikely to be either your personal account, or the account under which VTScada is running.

Those who ignore this warning typically fail to complete the process of requesting and processing an X.509 certificate.

  1. Choose a Certificate Authority such as Thawte, VeriSign, GoDaddy or other.
  2. Open a web browser to their page related to purchasing a certificate.
    This will have pricing and instructions for certificate options. Leave the page open while continuing with these steps.
  3. Open the VTScada Application Manager (VAM)
  4. Expand the menu and select the VTScada Thin Client/Server Setup option.
    The VTScada Thin Client/Server Setup dialog opens.
  5. Click the X.509 Certificate tab. The dialog appears as shown.

  6. Enter the host and domain name in the Host + Domain Name field.
    The name you supply must exactly match the host + domain name supplied in the URL used to access the VTScada Thin Client Server. For example:

myserver.trihedral.com

Where, "myserver.trihedral.com" is the host + domain name, "myserver" being the host, and "trihedral.com" being the domain name. You may also use a wildcard, if applicable to your situation:

*.trihedral.com
  7. Enter the Subject Alternative Names (DNS) using the + button below the field.

Clicking the + button creates a data input field within the SAN block as shown:

The field accepts a fully qualified domain name (FQDN). We only support DNS entries in the SAN fields.

  8. Enter the name of your organization in the Organization field.
  9. Fill in the remaining identifying fields.
  10. Select the cipher you wish to use for cryptography from the Cipher drop-down list.

Note that there is normally only one cipher ("Microsoft RSA SChannel Cryptographic Provider (RSA/SChannel)") available for selection, unless you have installed a custom cryptographic package.

After all fields have been entered, the Generate Request button becomes enabled.

  11. Click the Generate Request button.
    VTScada compiles the data you've entered and displays the following dialog:

If the request failed, the Enrollment Status dialog will display an error message relevant to the problem. For example:

  12. If your chosen Certificate Authority has an online form, paste (Ctrl + V) the clipboard contents into the appropriate field of that form.
    - Otherwise -
  13. Open the text editor of your choice (Notepad, UltraEdit.) Paste (Ctrl + V) the certificate request into your text editor.
    The pasted request begins with "-----BEGIN CERTIFICATE REQUEST-----" and ends with "-----END CERTIFICATE REQUEST-----".
  14. Save the text file.
  15. Send the text file to your Certificate Authority.

When VTScada generates the certificate request, a matching public/private key pair is generated. The public key is encoded into the certificate request and is sent to the CA. The private key is placed in a secure, encrypted key store. If you do not take a backup of your private key, a system restore operation or catastrophic computer failure will cause loss of the private key. This will require that you generate a new key and a new request. Therefore, it is highly recommended that you use the Microsoft Management Console (MMC) to backup the certificate request and private key. After you receive your certificate and subsequently process it, you should again do a backup using MMC.

After you generate the certificate, do not use Clear Response. Process the response. The data will still be in the boxes. When you need to renew the certificate, you can generate a new request from the data already there.
Use Clear Response only when you need to change a parameter and generate a new request.


Process an X.509 Certificate

After you send an X.509 certificate request to a Certificate Authority (CA) and the CA has validated your request, you will receive a reply containing the certificate. To process this information, use the steps in this topic.

The certificate is generated in the certificate store for the signed in user. After processing the certificate reply, you must export the certificate and its private key from the user account's certificate store and import those into the local computer's certificate store using the Microsoft Management Console. You must have administrative rights to do so.

VTScada processes the reply by removing the request from the Current User's Certificate Requests store and placing the SSL certificate into the Current User's Personal Certificate store, binding it to the correct private key.
The CA's reply must be processed into the store of the computer on which the request was made, using the same user account.
After you've done so, you should back up the X.509 certificate and copy it to the computer for which the request was made.

The certificate response may be in a ZIP file containing your certificate and related information. If this is the case, extract the certificate to a temporary folder on your computer and open it using Notepad in order to continue with the steps. The content should include the lines,

--------BEGIN CERTIFICATE--------

and

--------END CERTIFICATE--------

  1. Ensure that you are signed in to Windows with the same account you used to generate the request.
    Skipping this step is a common cause of failure.
  2. From Notepad or a text editor of your choice, copy the CA's reply to the Windows clipboard by selecting the certificate including the "--------BEGIN CERTIFICATE--------" and "--------END CERTIFICATE--------" lines, and pressing Ctrl + C.
  3. Open the SSL Certificate tab of the VTScada Thin Client/Server Setup dialog.
  4. Click the Process Reply button.
  5. Run the Microsoft Management Console (MMC) under the user account that VTScada will run in.
    1. From the File menu, add the Certificates snap-in for "My user account".
    2. In the tree on the left, expand "Certificates - Current User"
    3. Expand "Personal" and click "Certificates".
    4. In the right-hand pane you will see the certificate.
    5. Right-click on the certificate and from the "All Tasks" sub-menu, select "Export".
    6. Follow the Wizard, selecting to export the private key and to delete the private key if the export is successful.The private key must be exported with the certificate if the certificate is to be installed on another computer. It is good practice to keep a backup of the certificate with the private key. 1
    7. Complete the wizard, exporting the certificate to a *.PFX file.
    8. If the export is successful, right-click the certificate in the right-hand pane of MMC and select Delete to delete the certificate from the user account certificate store.
  6. On the computer that is your VTScada Thin Client Server, run the Microsoft Management console.
    Note that you must be signed in as a user with local computer administrative rights. The process will not succeed otherwise.
    1. From the File menu, add the Certificates snap-in for "Computer account".
    2. In the tree on the left of the MMC, expand "Certificates (Local Computer) - Personal" then right-click on "Personal".
    3. From the "All Tasks" sub-menu, select "Import".
    4. Follow the wizard selecting the certificate file that you saved earlier.
  7. Locate the newly added certificate in Personal\Certificates, right-click it and pick Manage Private Keys… from the All Tasks sub-menu.
  8. Click Add and add the user account you will be running VTScada under to the security list, granting Read access.
  9. Open the certificate by double-clicking.
  10. Locate the Subject field of the certificate, noting the line: CN = YourServer.Name.Com.
  11. Edit the VTScada SETUP.INI file as follows:
    In the [SYSTEM] section, add SSLCertName = YourServer.Name.Com where YourServer.Name.Com should be replaced by the actual text from your certificate.

If your certificate has a Friendly Name property, you must use the full text of that field.

Comments (if provided) must be on a following line, and must begin with a semi-colon.

  12. Restart VTScada and configure a secure realm.

As an alternative to setting permissions to a specific user account in MMC, you can set them for a group, such as Domain Users.

VTScada will now be able to access the X.509 certificates and run HTTPS connections for VICs, after those are configured.

It is highly recommended that you use the Microsoft Management Console (MMC) to backup the certificate and private key. If the registry must be restored or is lost, the private key will be permanently lost as well. The key will be encrypted to protect it during the backup process; you will therefore be required to enter a password.


X.509 Certificate Renewal

"SSL" is the acronym for the Secure Sockets Layer security protocol. SSL is an older technology, but the term has become the de facto name for Internet security. VTScada uses the more modern Transport Layer Security (TLS) protocol (although, for the sake of compatibility with older Windows operating systems, it can use SSL.)
While the term "SSL Certificate" is in common use, "X.509 Certificate" is the correct term.

X.509 certificates expire. You must renew it according to the terms under which you purchased your certificate.

Renewal consists of obtaining a new certificate, which contains a new public key (among other things), and combining it with the existing private key. The process is not disruptive. Before beginning, ensure that you have installed the OpenSSL toolkitThe OpenSSL toolkit may be obtained from https://www.openssl.org/ 1 and that you are using a windows account with administrative rights.

With the introduction of RFC 6125 (2011), modern browsers now require the SAN (Subject Alternative Name) field to be present in certificates for proper validation. Older certificates that were originally generated without a SAN field and now require renewal must be replaced.

  1. Sign in to your certificate provider's website.
  2. Select your certificate and follow the instructions to renew and to pay for the renewal.
  3. After your provider has verified the purchase, you may download a new certificate.
    This will contain two .CRT files. One is the certificate for your host (referred to here as "certificate.crt") and the other is the intermediate certificate from your provider (referred to here as "intermediate.crt"), verifying that they can issue certificates. (There may be a separate download for intermediate.crt.)

Certificate.crt contains a new public key with a new expiration date. The old certificate and private key should be put into a PFX file for internal use and storage. You will use the OpenSSL library to do so.

  4. Obtain your existing private key file.
  5. Run the following command in OpenSSL to extract the private key. (You may need to provide the path to OpenSSL.exe.)
OpenSSL pkcs12 -in certname.pfx -nocerts -out key.pem -nodes
  6. Optional step:
OpenSSL rsa -in key.pem -out private.key

You need a password-protected PFX file to store the new certificate where it is needed. This includes the private key, certificate.crt, and intermediate.crt from your provider.

  7. Run the following command in OpenSSL, where "certificate.pfx" should be given a name that combines host and year (for example: test.trihedral.com-2018.pfx).
OpenSSL pkcs12 -export -out certificate.pfx -inkey key.pem -in certificate.crt -certfile intermediate.crt
  8. OpenSSL will prompt for a password. Use the same as the one used to secure the previous PFX file.
  9. Save the certificate and install where needed.
  10. After ensuring that the .pfx has been safely stored, clean up by deleting all the files used and created during this procedure.


Redundant TLS-Protected Servers

If you want redundant TLS Closed Transport Layer Security-protected VIC servers, you can use one of the following options:

  • One certificate per server, in the case that each server uses a different URL.

For example, if you had two servers named vtscada1.countyscada.com and vtscada2.countyscada.com, then you will need one X.509 certificate per server name.

Each server has its own certificate installed and the server list contains both server names.

  • You can use a wildcard X.509 certificate (which costs more) and install the same certificate on both servers. Do this if you need to increase the number of servers, while continuing to use the same certificate.
  • One certificate installed on multiple servers, in the case that the URL resolves to a networking device and that networking device automatically detects failure of one server and port forwards new connections to the other server or contains some sort of load balancer.


TLS Certificate Warnings

The following errors may occur. If a validity check fails, the code still attempts to load the certificate and use it if possible.

The messages all begin "TLS Certificate for subject: <cert_subject_name>", and then have further info as follows:

Error Message | Meaning | Fix
Was not found | The certificate for the requested subject wasn't found in the certificate store | Check certificate in store and certificate name in Setup.INI.
Is not yet valid | The computer's clock is earlier than the certificate "Not Before" field | Check clock and certificate
Has expired | The computer's clock is later than the certificate "Not After" field | Check clock and certificate
Does not have the required Enhanced Key Usage | The certificate does not have the correct Enhanced Key Usage value | Check certificate
Unable to open certificate store | The process is unable to open the appropriate certificate store | Unknown
Unable to acquire private key | The process is unable to access the certificate private key | Key permissions for the process user
Unable to obtain SChannel handle | The process is unable to open a Secure Channel using the certificate | Key permissions for the process user


Certificate Management

Viewing: Develop > Secure Your Application > Internet Security (TLS, X.509, SSL) > Certificate Management

Certificate Management UI

Several tabs in the OPC UA Client Driver configuration possess a Certificate Droplist, a Certificate Summary and a button that opens a 'Manage Certificates' window. It is important that you understand this tool before proceeding with configuration of the client driver. In particular, take time to review the information in the topic Certificate Name Description.

Certificate Droplist and Summary

When a certificate is required for data exchange authentication, it is accessible through the Certificate Droplist. When a certificate is selected it will populate the Certificate Summary section with the certificate's name, issuer, the start of its validity window, the end of its validity window (the certificate's expiry date) and its thumbprint.

If two or more certificates possess the same name, only the certificate with the furthest expiry date will be accessible in the Droplist. If a certificate that expires sooner is required, select the 'Manage Certificates' button and delete the certificate or certificates that expire later than it does.

Selecting the 'Select a certificate...' field will reveal a list of available certificates from a store as determined by your application's Client / Server Configuration.

When a certificate is selected, its relevant data will populate the Certificate Summary section.

A selected certificate with an expiry date of more than 30 days from the present.

A selected certificate's expiry date will appear in orange text if it is less than 30 days away from the present.

A selected certificate's expiry date will appear in red text if it has expired.

Certificate Not Available

This message is displayed beneath the Certificate Droplist instead of the certificate details if the certificate is deleted or otherwise unavailable within the user's system. Only the name of the ticket will remain if it was selected at the time of its deletion, if another certificate is selected it will be removed from the Droplist.

If you cannot find the certificate you need, you may select the 'Manage Certificates' button and view the available certificates within the Certificate Grid.

Certificate Grid

The principal feature of the 'Manage Certificates' window, the Certificate Grid displays the collection of certificates in a certificate store (which store depends on which grid is displayed) and a set of action buttons.

Grid Columns

Certificate Name

The leftmost grid column shows the "Friendly Name" of the certificate, if it has one, and the "Common Name" of the certificate if it does not. Details follow in Certificate Name Description.

Issuer Name

Shows the issuer of the certificate. Self-signed certificates often have the same name as the certificate Common Name, while certificates issued by a Certificate Authority (whether in-house or external) bear the issuer’s name.

Valid

Indicates whether the certificate is valid for the purpose intended. This means slightly different things on different grids.

On the 'Connection' tab or 'Client Certificate' tab (on the OPC UA Client Driver for example), a certificate is considered valid if it still within its validity period. Certificates in the same certificate store that are inappropriate for use are not displayed. Although a certificate might not be marked as valid, it may still be allowed for use by the server or client.

Note that on the 'Server Certificate' tab, the 'Valid' column means that the certificate is within its validity period and the name on the certificate matches the name of the server supplied on the 'Connection' tab Endpoint URL field. This helps you spot if the server responding to the configured Endpoint URL holds a valid certificate for that server.

Expiry Date

The precise time at which the certificate will no longer be valid. The expiry is avoidable by selecting the certificate from the grid and then 'Renew', opening the 'Renew' window (see 'Renew Button' below).

Control buttons

Create New Button

The 'Create New' button will generate a self-signed certificate and place it in the store being displayed on the certificate grid. Self-signed certificates won't be trusted by other hosts unless the certificate is manually "trusted", which is typically done using the UA server configuration tools.

Click this button to display the following dialog, the content of which will be incorporated in the new certificate.

Certificate Name Description

The certificate name is the "Friendly Name" of the certificate. After a certificate is created, the Common Name (CN) cannot be changed, but the Friendly Name can using the Microsoft Management Console (MMC) or by renewing the certificate.

The Friendly Name is what the OPC UA Client Driver holds as a parameter to its tag and is propagated across computers participating in the distributed application.

Previously, if the 'ClientCertificateName' parameter had a value it was not possible to create a new client transport certificate with a different name. Now (12.1.53+), even if the 'ClientCertificateName' parameter has a value, you can create a new client transport certificate with a new name.

Consider the case of a pair of I/O servers (primary and backup). Normally, the primary will connect to the OPC UA server and retrieve data. To do this (assuming the driver is not running in unsecured mode) it needs to provide a Client Certificate to the server. It uses its 'ClientCertificateName' tag parameter to find the certificate it should supply. As the backup I/O server contains an exact copy of the tag, it too has the same tag parameter and will therefore look for a certificate of that name in its certificate store.

There is no issue if you install the same certificate (and private key) on both I/O servers. However, you can use different certificates so long as they have the same 'Friendly Name', as this is the key used by the OPC UA Client to locate its transport certificate. If using secure communication to the OPC UA server, the server must trust both client certificates. This normally requires a manual intervention at your OPC UA server.

You will also have to trust the server certificate on the VTScada client / backup server. See OPC UA Client Driver properties Server Certificate tab in this topic.

You must create/update certificates with the same names on all backup machines. If you modify ClientCertificateName on your primary you must also ensure that your backup machines have a matching certificate.

Certificate Subject

The certificate subject should be modified. It is the Distinguished Name of the certificate and defaults to "CN=<driver name>", setting the Common Name to the name of the driver tag.

It is advisable to change the certificate subject to the fully qualified domain name (FQDN) of the local machine, to make certificate identification on your OPC UA server easier. If you use the same certificate for you backup machines then choose a meaningful subject name to allow you to identify the certificate on your OPC UA server.

Key Strength

This allows you to set the key strength (number of bits) in the asymmetric key pair that will be generated for this certificate. Currently, the dialog only permits RSA keys (that is all the current OPC UA servers support) of key strengths between 2048 and 4096 bits.

The client and server certificates can have different key strengths.

VTScada will only generate RSA public/private key pairs that are classed as acceptable by:

https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar2.pdf

This mandates at least "112 bits of security", which means an RSA key length of at least 2048 bits.

Referring to Table 4 within the following document, this is sufficient up to the year 2030.

https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r4.pdf

Validity

The key validity period can be set to be between 30 and 36500 days (approximately one month to 10 years).

When a certificate expires, any entity receiving that certificate should decline it. A shorter validity period may seem inconvenient, but this reduces the length of time that a compromised or stolen certificate remains undetected.

VTScada will raise an alarm when a certificate is within 30 days of expiry to give you time to install newer certificates.

Subject Alternative Names (SAN)

Supply any DNS (Domain Name Service) names that the client computer may be known by. These will be incorporated into the certificate extended properties' Subject Alternative Name field as entries. Enter each value on a separate line, including prefixes like:

DNS=host.example.com,
IP=127.0.0.1
URL=urn:EXAMPLE.trihedral.com:OPCUA:SimulationServer

The certificate will also have an automatically-created URL and a DNS entry. The URL is composed from the application GUID and is unique to this application. The DNS entry contains the host name of the workstation on which you are creating this certificate (not the fully qualified domain name (FQDN)).

Some OPC UA servers may require that one of the DNS names provided can be matched to a white list, this field gives you an opportunity to provide such a DNS name. The FQDN, as provided in the Certificate Subject, should be included.

Import Button

Use to import a certificate and private key from a Personal Information Exchange format file (.PFX or .P12). This file format is commonly used to securely transport certificates and private keys between computers.

The Microsoft Management Console’s Certificate Management snap-in is one way to export certificates and their private key to such files.

On clicking the button, the following dialog is displayed, which allows you to select the file and supply the password associated with the private key (which is encrypted within the file).

Remove Button

Removes the currently selected certificate (and its private key) from the grid and the associated certificate store.

After removal, a certificate can be restored only if you have a backup of that certificate in a suitable format (e.g. a .PFX or .P12 file). Confirmation is required before the certificate is deleted.

Renew Button

Enabled after selecting a certificate from the grid, this will open a 'Renew Self-Signed Certificate' dialogue. Consistent with the 'Create New' window, this allows you to extend the certificate's validity period and edit its other features.


Technical Reference for Security

Technical details for various features of the security system are provided in the following topics.

Proximity Card Readers - Configuration details

System Privilege Reference for Developers - Formatted to match the user interface.

Storage of Security Data and Configuration - Files holding security-related information.

Security Properties - Configuration settings that are found in, or may be added to, Settings.Dynamic.

Security Manager - Scripting language features for security.


Storage of Security Data and Configuration

Security-related information is stored in two separate files, each having a specific function. Details for each file follow the list.

  • Settings.Dynamic (formerly, SecurityManager.ini was used)

Stores security-related administrative settings for the application.

  • Accounts.Dynamic

Stores user account information (i.e. username, password, and privileges).

Settings.Dynamic

Changes to this file will not take effect until they are imported into an application using the Import File Edits feature of the Application Configuration dialog. In a secured application this action can only be performed by a user with configuration and file modification rights. Unauthorized users cannot change security settings by tampering with application properties.

Application properties related to security can be used to configure:

  • The default automatic sign out time period. This is the amount of idle time after which the signed in user will automatically be logged off by the system. Each user may be given their own automatic sign out time.
  • The minimum length for user passwords.
  • Suppressed privileges (see: Suppression of System Privileges).

Accounts.Dynamic

The Accounts.Dynamic data file is used by the Security Manager to store user account data. This file is automatically generated by VTScada when you create your application.

Password hashing uses a salted, key-stretched, SHA2-512 algorithm. An AES-256 block cipher is used to encrypt account data. In addition, every user account has its own generated key. The only means of adding, copying, modifying, and deleting user accounts and their related passwords and privileges is by using the security dialogs provided by VTScada. Information taken from one application's Accounts.Dynamic file will not be valid in another.


Security Property List

Certain configuration settings related to security are stored in the file, Settings.Dynamic. Many of these variables can be changed only by directly editing this file in your application's root directory, and then importing the edited file using the Application Configuration dialog. Only authorized accounts may import a file that has been edited.

All custom privileges that you create in an application are named according to the pattern PrivDescN where N is a number starting at 0.

For example, if you have added 4 customized custom privileges to your application, they would appear as follows:

<SECURITYMANAGER-PRIVAPP>
PrivBitsTotal = 4
PrivDesc0 = Zone A Operation,0
PrivDesc1 = Zone B Operation,1
PrivDesc2 = Zone C Operation,2
PrivDesc3 = Zone D Operation,3

The label is used for display purposes, including the selection drop-down in each output tag's Merit tab and the security property of each page.

The number following the property sets its value, which is to be used in code. Note that this value is an offset from 16. Referring to the preceding example, where the page has been protected with the custom privilege "Zone A Operation", the first few lines of the source code of that page will look like the following:

[
Title = "Overview";
Color = "<FFFFFFFF>";
SecBit = 16;
]

PrivDes0, having number 0 in the list above, means that it's actual value to be used in code is 16 + 0 = 16.

Take careful note of each property's section. Three distinct sections are used for security-related properties. A property will be ignored if it is associated with the wrong section.


Built-In Roles

The built-in roles are provided as examples to help you begin security configuration. It is expected that you will modify these and create your own roles.

Logged Off - The privileges available at a workstation when no user is signed in.

No privileges

A VTScada application continues to run whether an operator is signed in or not. Anyone can view any user-created page that is not protected by a custom privilege. All such control actions are logged and attributed to a role named "Logged-Off". This is a role that is built into and standard with every VTScada application.

Use care in granting privileges to the Logged Off account. If you wish to allow certain access to the application for all, then it is better to create a public user account with a carefully restricted set of privileges and publish that user name and password than to grant those privileges to the Logged Off user account.

Thin clients and the Logged Off role:
Many sites will enable signed-out VIC sessions, essentially allowing the Logged Off role to become "signed in" after any other user has signed out. This maintains the connection, which would otherwise close. This applies only to VIC clients, not Anywhere clients.
Look for the option in the Advanced section of the security Administrative Settings (Options) dialog.

Operator - Permits basic operation of a VTScada application.

  • Alarm Mute
  • Alarm Silence
  • Alarm Page Access
  • Reports Page Access
  • History Page Access
  • Page Note Edit
  • Sites Page Access
  • Maps Page Access
  • Operator Notes Page Access
  • Control Outputs
  • Run Batch
  • Recipe Page Access
  • Services Page Access
  • Alarm Acknowledge

Configurer - Permits development of a VTScada application

  • Includes the Operator role, plus:
  • Account View
  • Tag Parameter View
  • Edit Files
  • Deploy Changes
  • Revert Changes
  • Page Add
  • Page Modify
  • Page Delete
  • Tag Add/Copy
  • Tag Modify
  • Tag Delete
  • Group Modify
  • Group Save
  • Group Delete
  • Pen Modify
  • Note Add
  • Thin Client Monitor Access
  • Page Note Hide
  • Advanced Version Control
  • Alarm Shelve
  • Alarm Disable
  • Recipe Edit
  • Edit Roster Contacts
  • Switch Servers
  • Manual Data
  • Questionable
  • Application Stop
  • Configure

SuperUser - Configuration and security management

Includes the Configurer role (and therefore, the Operator role), plus:

  • Account Modify
  • Manager
  • Thin Client Monitor Admin
  • Administrator
  • Application Manager View
  • Edit Data
  • Global Tag & Area Filter

Privileges not granted to any built-in role:

  • Thin Client Access
  • Remote Data Access
  • Remote Tag Value / History Retrieve
  • Manage Tag Types
  • Lock Add/Remove
  • Lock Administrator
  • User-created custom privileges


Account Lockout Alarm

With security enabled, repeated failed attempts to log in will trigger a security alarm as a 'Trip Event' and if tied to a specific account it will be locked for a period of one minute by default. During this period, another user with Manager and Administrator privileges may sign in, view the alarm and unlock the account on the user's behalf (see Account Locking / Multiple Sign-in Attempts for a detailed explanation).

The alarm itself is an essential tool for security and as such is not directly configurable, but there are ways to customize the lockout behavior surrounding it through related properties.

Account Lockout Alarm Related Properties

Review the individual documentation entries for each property before altering them. See Edit Properties for instruction on how to add or change properties.

AccountLockoutTime

The length of time an account will be locked out after using an incorrect password 'MaxFailedLoginAttempts' number of times, or 'MaxRateFailedLoginAttempts' within the 'AccountRateWindow' period of time. Defaults to '1' minute.

AccountRateWindow

The window of time in which the account will be locked if the user makes 'MaxRateFailedLoginAttempts'. This is intended to deter automated attacks which occur in rapid succession. Defaults to '15' seconds.

MaxFailedLoginAttempts

The number of times in a row a user may sign in with an incorrect password before the account is locked for 'AccountLockoutTime' minutes. Defaults to '25' attempts.

MaxRateFailedLoginAttempts

The number of times in a row a user may sign in with an incorrect password within 'AccountRateWindow' seconds before the account is locked for 'AccountLockoutTime' minutes. Defaults to '3' attempts.

SecurityAlarmArea

Determines the area the alarm belongs to. Defaults to 'Security'.

SecurityAlarmPriority

Sets the priority of Security Manager alarms. Defaults to '4', see Alarm Priority Tags for a breakdown of the available priorities and what they describe.

Required Privileges

See Assign Privileges for information on how to view and update user privileges.

To effectively manage the Account Lockout Alarm and restore account access to the user, all four of the following privileges are required:

  • Administrator: Grants permission to unlock the account but not the ability to access it nor the ability to acknowledge the alarm via the 'Alarms' page.

  • Manager: Grants access to view the account but not the ability to unlock the account nor the ability to acknowledge the alarm via the 'Alarms' page.

  • Alarm Page Access: Grants the ability to view the 'Alarms' page but not acknowledge any active alarms.

  • Alarm Acknowledge: Grants the ability to acknowledge the alarm but not access to the 'Alarms' page.


Thin Clients: Mobile and Internet

Overview of the VTScada Thin Client Server

The VTScada Thin Client Server allows operators to connect to an application from a remote computer or mobile Internet client. Your VTScada license must permit thin client (Internet) connections. The number of concurrent thin client connections allowed can be pooled between machines that both have a full production server license.

The VTScada Thin Client Server must be configured if you are using any of the following technologies:

  • Thin client connections (VIC, Mobile and VTScada Anywhere)
  • Remote data access (Needed for the Excel add-in, ODBC connections, and REST queries.)
  • Alarm notifications using Twilio

If you are running VTScada as a Windows service, it is typical to require connections to that server to use a thin client connection. Depending on the choice of client (there are three) you can still do all development of an application and you can Access the VAM from a Thin Client. (This last is available only if you are running VTScada as a Windows Service.)

There are three ways to connect. Each of the clients has its own relative advantages. All allow operators to monitor and control the application. Users can identify which client they are using by looking at the URL Closed Uniform Resource Locator. The address of a web page..

  • Address ends with "Anywhere"
    You are using the VTScada Anywhere Client. This will work on most devices and operating systems. The screens will be nearly identical to those at a VTScada run-time installation. (Connect Using the Anywhere Client)
  • Address ends with "Mobile"
    You are using the VTScada Mobile Client (MIC Closed Mobile Internet Client. Allows you to connect to a minimalized version of the application, suitable for mobile devices.). This has been optimized for use on mobile devices to minimize your connection charges. With the MIC, you have the option of switching to full display screens when needed, but most often you will probably prefer to use the optimized display. (Connect Using a Mobile Device)
  • Otherwise...
    You are using the VTScada Internet Client (VIC Closed VTScada Internet Client. Allows you to connect to an application over the Internet with many of the features of a full VTScada workstation.). This uses a native Windows application that must be installed on your computer. This can run within your browser, or you can download the VTSX installer to run it as a stand-alone application. (Connect Using the VTSX Program)

VIC clients and servers should have matching versions. We work to maintain backward compatibility, but there is no guarantee that a client from one release will work properly with a server from another release.

If you have more than one VTScada Thin Client Server, then upon the loss of one server, both the VTScada Anywhere client and the VIC will fail-over automatically to the backup server. New sessions must connect to the backup server at its URL, which will differ from that used by the primary server. If the backup server does not have a full production license, it will manage fail-overs in a limited capacity; active connections will be maintained but new connections will be limited to the connection limit of the back-up server. The mobile client does not have support for automatic fail-over and must be directed to connect to the backup server.

Licensing

A license defines the features that are enabled on a single installed instance of VTScada, including the number of simultaneous thin client connections you can have and if they can be pooled with other licensed machines.See Server Requirements and Licensing to learn more about how licenses apply to servers and workstations.

In a standard setup, VTScada operates under a full production license. However, there are exceptions where VTScada runs with a limited license. For instance, VTScadaLIGHT is designed and authorized for use in miniature production systems. Meanwhile, a developer's license is a special license that provides developers with all the resources needed to build applications, but it is restricted from being used for running production systems.

VTScadaLIGHT requires a VPN for thin client access outside your local network.

Security

Security must be enabled in an application, and the Thin Client Access privilege granted before anyone can connect. As a safety measure, the Thin Client Access privilege is not included in any of the pre-configured roles. You must choose to grant it to designated users. After signing in, operators may proceed as their other security privileges permit.

The entire Internet lies between your client and server, and all communication that is not encrypted is visible. Be assured that no SCADA site goes unnoticed if connected to the Internet.

A hacker who is able to intercept communication packets as they route through the Internet can easily decipher all information that is not encrypted, including user-names and passwords.

You must use at least one of:

  • A virtual private network (VPN) for all communications.
  • An X.509 certificate. (Also known as a TLS/SSL Certificate and available from many online providers).

Tools in VTScada help you to obtain the required certificate. Using the third tab of the VTScada Internet Client/Server Setup dialog, you can fill in the blanks to generate a request that can then be sent to an organization such as VeriSign. If successful, the request will be placed on your Windows™ clipboard. Internet Security (TLS, X.509, SSL)

For those using Twilio for alarm notification (Using Twilio for Alarm Notifications), there is no choice other than to have a publicly-accessible server protected by a certificate. These sites might also configure a VPN link for thin client access, but the Twilio connection cannot be made over a VPN.

For air-gapped applications using the VIC.

By default, during the process of validating your TLS certificate, Windows may attempt to reach out to Windows Update to refresh its trusted root certificate list. This will not succeed because your system is not internet connected. This will cause the launch of the VIC to be delayed or fail.

To mitigate this, you may turn off automatic root certificate updates from Windows Update on a per-user basis. This can be done locally via the Local Group Policy Editor (gpedit.msc) or domain-wide via domain group policy.

To do this via the Local Group Policy Editor:
1. In your Windows Explorer search, type gpedit and hit enter to open your Local Group Policy Editor (gpedit.msc)
2. Navigate to:
Computer Configuration → Administrative Templates → System → Internet Communications Management → Internet Communication settings.
3. Enable the policy: Turn off Automatic Root Certificates Update.

Using Browser Bookmarks and Windows Shortcuts

Bookmarks start with a URL that serves up a web page, through which users sign into. After sign-in, Internet clients receive server lists from the server, and hence can fail over to a backup if the server disconnects. There is a difference if you create a VIC shortcut by using the Bookmark Page item in the VIC window's system menu. The resulting shortcut (stored, for example, on your desktop) contains a VIC server list, so, from that point on, you can start a connection as long as any one of those servers is running.

When you try to start a VIC or Anywhere Client connection through a web browser, you provide a single URL to a server, and that server must be able to respond to that request. The VIC shortcut provides a way around this for VICs, but there is no way around this limitation for the Anywhere Client, which can connect only to the URL provided by the browser.

Redundancy and Thin Client Connections

A frequent question is how to switch to a backup server automatically when the current primary server is unavailable. (Thin client failover) The answer depends on several factors:

  • Which client you use for your connection.
  • Whether you are connecting from an internal network or across the Internet.
  • Whether you have an existing connection at the time of server failure or are a client attempting to connect to a server that you do not know is unavailable.
  • Whether your backup server has compatible licensing.

The VIC keeps a list of servers and will automatically connect to the next when the current server goes offline. Browser-based clients do not have this feature, but if connected internally and if the server goes offline, it will fail to the next. External connections from browser-based clients are limited by the network gateway.

Scenario 1. Session in progress

Applies to both the VIC and the Anywhere client. If the session has already started and a thin client is connected to a server that subsequently fails, the clients have an active server list and will fail over to the next active server in the list.

Scenario 2. New session

If the session has not already started and a Client tries to connect to an offline server, the VIC Client has the Server List cached and will connect to the next Active Server in the list.

An Anywhere Client will only attempt to connect to the server attached to the URL so will fail to connect. In this situation, you should create a second URL shortcut, specifying the backup server.

Scenario 3. Incompatible Licenses

The number of permitted thin client connections are only pooled between machines with full-production licenses. However, there are limited additional allowances made in the event of a failover.

Say a server can host 5 connections and the backup is running an instance of VTScada with a limited license (like a demo or developer's license) that only allows for 2. In the event of a failover, the backup may host all connections that are currently connected, temporarily exceeding the backup server's limit of 2. This is to mitigate a disruption in service. New connections cannot be made. If all but 2 of those connections end, they cannot be reconnected on the backup server in this configuration. Limited licenses are not designed or intended to be used as long-term fixtures in full-production systems.

Custom Disclaimer Message

You may choose to add an HTML file to your application, which will be displayed to all who connect. This must be a complete HTML file that is part of your application (Import File Changes Tool). Note that JavaScript content will not execute and should not be included. You can find an example thin client disclaimer in ..\Examples\ExampleThinClientDisclaimer.html

After adding the file to your application, create an application property named ThinClientDisclaimer, whose value is the name of your HTML file.

Thin Client Landing Page Configuration

The appearance of the standard VIC landing page is protected by branding requirements. But with application property settings, you can control which parts of it are enabled without needing to license customized Branding Files. Note that these properties will take precedence over configuration in custom branding files. Referring to the following image:

ShowDisplayVIC

ShowDownloadStandalone

ShowDisplayAnywhere

ShowDisplayMobile


Capabilities of Internet Thin Clients

Tools and features vary by choice of thin client. Capabilities of each client are listed here, starting with the most restrictive connection option:

The Mobile Internet Client (MIC) provides the following features:

  • For any application page, operators may choose between an minimal display optimized to reduce bandwidth, or a full display including all widgets and graphics.
  • Operators can view I/O tag values on a page by page basis.
  • Operators can set output tag values.
  • View and acknowledge current alarms.
  • View the alarm history.
  • View a trend graph (HDV display) for any I/O tag.
    Graphs are images, updated only when recreated using a refresh. Data cannot be exported
  • View a slippy map.
  • If the mobile device supports the "pinch" user interface, operators may scale the HDV display.
  • No access to the following system pages: Reports page, Operator Notes, the full HDV page, Thin Client Monitor.
  • No access to the VAM as an application.

The mobile client is intended for use with a personal mobile device. It does not include a "sign out" option. The sign-out will occur automatically several minutes after closing the application. If sharing a device, you should use one of the following clients for increased security.

The Fast Scan Immediately option of the Fast Scan Widget does not work with a Mobile Internet Thin Client (MIC)

The VTScada Anywhere Client adds the following features. Operators may:

  • View and use all pages, subject to each operator's security privileges.
  • Perform limited configuration operations to a standard application, including:
    • Copy existing tags
    • Modify the properties of an existing tag, excepting font selection within a Font tag.
    • Delete a tag
    • Add new tags
  • Modify Alarm Notification System options and pronunciation.
  • Work with security
  • Access the Application Configuration dialog to:
    • Edit properties
    • Edit server lists
    • Edit security
    • Import/Export Files
    • Maintain the File Manifest
    • Deploy changes
    • Revert changes
    • Show the version log
    • Open the Information page.
  • Add and edit page notes.
  • Run a script application.
    Only one instance of a script application may run at a time - if it is running on a workstation, it may not also run on an Internet connection.
  • Managers may work with security accounts.
  • Administrators may configure security.
  • Run and download reports, generated as text files. (See following note.)
  • Create and download ChangeSets.
  • Export and download data from the HDV.
  • Unique to the Anywhere client: sign in using OpenID Connect Authentication.
  • Run the VAM as an application with the following exceptions:
    • Cannot use Get From ChangeSet
    • Cannot use Clone From ChangeSet
    • Cannot use Find Existing.

Edge and Chrome block PDFs shown in the Web Browser widget when using the Anywhere Client. This is related to the sandbox attribute set on the iframe.

If generating a file using the VTScada Anywhere Client, it will be transferred to your browser automatically. Check your browser's download history. (Will vary by browser.)
Only text files can be generated by a thin client, not spreadsheet or database files.
Similarly, Excel templates cannot be used when reporting via a thin client.

This applies to report generation, HDV exports, note exports, ChangeSet creation, and tag exports.
You cannot view a generated file (such as a report) within the Anywhere Client. The client shows only the VTScada user interface.

The VTScada Internet Connection (VIC) adds the following features to those listed above:

  • Open and use the VTScada Idea Studio. (Subject to your license restrictions and account permissions. Note that it is not possible to select images for the Animated Bitmap Widget via a thin client.)
  • View a list of available VTScada applications (as permitted by the Thin Client Server).
  • Display the VTScada screens on multiple monitors by configuring Realm Display Setup Tags.
  • Use the VTScada print icon to print pages.
  • Create and apply a ChangeSet.
  • Export/Sync tags.
  • Manage Types. (User-defined tags)
  • Open and use the Idea Studio, if permitted by your license key.
  • Maintain logged-off sessions.
  • Maintain a list of available servers and automatically connect to the next in the list if one is not available.
  • Provides the option of creating a desktop shortcut that operators can use for subsequent connections.
  • Provides Smart Card Support.
  • Run the VAM as an application with the following exceptions:
    • Cannot use Find Existing.
  • As with all clients, only text files can be generated by a thin client, not spreadsheet or database files.


Server Requirements and Licensing

A minimum recommended configuration for a Thin Client Server is:

  • Installation of VTScada, licensed for thin client connections.
  • Access across a network.
  • The server name should contain only letters, numbers and hyphens (as defined in Section 3.5 of RFC 1034 and Section 2.1 of RFC 1123 of the Internet Engineering Task Force). Characters such as underscores are not recognized by this standard and may cause unexpected behavior.
  • In the event that the clients connect to the Thin Client Server via proxy servers (common where a firewall is used), it is advisable that the proxy servers support the HTTP 1.1 protocol, rather than only HTTP 1.0.

VTS/IS Clusters and Server Lists

A cluster is defined as the list of machines configured in the VTScada Internet Setup dialog >Server Setup tab. Machines within the same cluster that are licensed to run full-production versions of VTScada share the sum of their licensed connection limits. These must be computers running VTScada that can see each other via VTScada Remote Procedure Calls (RPC). Machines with limited licenses (ex. demos, VTScadaLIGHT) can be configured in a cluster but do not pool their connection limit. Demos do not pool with paid licenses.

Licensing for VTScada Thin Client Servers

VTScada Thin Client Servers and the connections made to them are subject to the following licensing restrictions:

  • There is a limit to the number of concurrent thin client connections that can be hosted by the server.
    It is possible to have as few as 0 and as many as Unlimited connections depending on the licensing options you purchased with VTScada.
  • Thin client connection limits are pooled between full-production licenses. They are not pooled between instances of VTScada with limited licenses such as a demo license or a VTScadaLIGHT license.
  • Limited license machines (excluding VTScadaLIGHT) can be joined into a cluster as backups and connections may failover to them in a limited capacity.
  • If your backup is running with a limited license, in the event of a failover, the backup will host active thin client connections in excess of its connection limit (to maintain system stability) but new thin client sessions cannot be started in excess of the failover server's limit.

Servers within a cluster that have full-production licenses will pool their licensed resources. For example, if one server in the cluster has a full-production license for 5 connections and another has 10, you will always have 15 available connections. If the 10-license server goes offline temporarily, your available license count will not drop to the remaining 5 but will remain at 15 on the server that is still running. No existing connections will be lost.

VTScadaLight licenses may have one Thin Client connection from the local network.
Remote computers must connect to the local network using a VPN.

You can find the number of licensed thin client connections for any server in the License Management dialog, available from the VTScada Application Manager (VAM).

The number of licenses in use is counted on the basis of concurrent sessions, regardless of whether these are from one computer or from many computers. Each connection to a VTScada Thin Client Server counts as one license in use. If, for example, you opened two tabs in Internet Explorer and connected to your VTScada Thin Client Server from each tab, then that would count as two licenses in use. Pop-up windows do not consume extra licenses.

An exception is that for support purposes, certain Trihedral-supplied debugging tools (such as the "Debugger", "Profiler", etc.) can always be accessed via the VTScada Thin Client, even if their use would exceed the license allocation.


Preparation for Mobile and Internet Access

Assuming that you have a VTScada license permitting thin client (Internet) connections, the first step in configuring VTScada to allow thin client connections is to secure your site. Note that the following applies to all VTScada technologies that make use of the VTScada Thin Client Server.

At least one of Enable OpenID Connect or Permit Thin Client sign in with username and password, must be selected. If not, all Internet and Mobile sign in attempts will be met with the message "No sign in methods are available".

See also, OpenID Connect Authentication.

Features available to a thin client depend on the type. Refer to Capabilities of Internet Thin Clients.

Client display characteristics can be controlled by Realm Display Setup Tags. This tag is where you will be able to configure multi-monitor displays for VIC clients. The default minimum Width by Height for an Anywhere Client is 1366 x 768. It is not recommended that you set a minimum Width by Height less than this as some standard VTScada dialogs may become unusable.

To allow or deny specific IP address (or a range of IP addresses) at the VTScada server level instead of your firewall, create the properties, HTTPAllow and HTTPDeny in your SETUP.INI file.

HTTP access to files and folders is restricted to those listed in the [HTTP-Unauthenticated] section of your Setup.INI file. Application folders do not need to be added to this list to run those applications on a thin client. ([HTTP-Unauthenticated] Section)

When configuring your server, ensure that you select a port that is not in use by any other process on your server. Port 80, the default HTTP port, is often used by other programs. You can check your server by opening a command prompt as an administrator, then running "netstat -ao". You can then check the process ID value in the Windows task manager. For example:

C:\WINDOWS\system32>NETSTAT -AO

Active Connections
Proto Local Address Foreign Address State PID
TCP 0.0.0.0:80 MYSTATION-PC:0 LISTENING 4
TCP 0.0.0.0:81 MYSTATION-PC:0 LISTENING 10916

This example shows that port 80 is in use by process id #4, which belongs to Windows. Port 81 is in use by process #10916, which happens to be a configured VTScada server in this example.

Thin clients transmit the user sign in credentials (username and password) using Basic Authentication, which is a simple, non-encrypted, Base 64 encoding of "username:password", and which can be decoded by network snooping tools if they can capture the message content. Wireshark as one example, will show the decoded credentials if connected to a local machine or switch that performs the communications (Because switches don't broadcast network traffic for all to hear, the "listener" must be local to the communications path versus being anywhere on the network.) If Windows Security Integration mode is enabled, then the potential consequences will extend beyond the SCADA system should the operator's Windows credentials be stolen.

To secure user credentials against listeners that may have access to switches or workstations carrying this traffic, it is essential that you encrypt thin client sessions with TLS (transport layer security) by installing an X.509 certificate on the VTScada Internet server. The certificate can be obtained from a 3rd party issuer such as Verisign, Thawte, GoDaddy, from an organization's own Certificate Authority (CA) infrastructure, or via local ad-hoc creation. (e.g. By using Open SSL tools.) To allow clients (browsers) to verify the certificate and not display an untrusted warning, they need the "root" certificate from the CA to be installed. The root certificate for most third-party issuers is already installed in most Web browsers.

If you have more than one VTScada Thin Client Server, then upon the loss of one server, both the VTScada Anywhere client and the VIC will fail-over automatically to the backup server. The mobile client does not have this ability and must be directed to connect to the backup server.

If your pages include tabbed folders, then the Unique Key property of the folder must be set in order for tabs to function when viewed using a Mobile Internet Client.


Configure a VTScada Thin Client Server

The following is a generalized list of the major tasks required to configure a VTScada Thin Client Server. Each of these tasks is fully described in the linked topics. Technical details that apply only in specific cases are listed at the end of this topic. You are advised to review that list to confirm whether your situation matches one of these specific cases.

Step 1: Within your secured application, grant the privilege Thin Client Access or Remote Data Access to Selected Operators

Full description and instructions: Accounts and Roles, Assign Privileges

VTScada does not permit mobile or Internet access to any unsecured application. Users must have the Thin Client Access privilege.

  1. Enable security if you have not already done so.
  2. Sign into the application with an account that has the Manager privilege.
  3. Ensure that selected user accounts have the Thin Client Access privilege, either directly or through one of their assigned roles.
  4. For accounts that will make ODBC (REST) connections, including those using the Excel Add-In, grant the Remote Data privilege. (The Remote Tag Value/History Retrieve privilege is optional.)

Step 2: Establish the VTScada Thin Client Server Security parameters

When credentials are transmitted between the VIC and the server, the account name and the password are both transmitted using Base64 encoding. This encoding system is public knowledge and is entirely reversible, therefore the account name and password can be extracted by knowledgeable persons who can intercept the communication. An HTTPS connection is strongly recommended.

Full description and instructions: Internet Security (TLS, X.509, SSL), Securing a VTScada Thin Client Server, Servers in a Demilitarized Zone (DMZ)

Access to the VTScada Thin Client Server is protected by the account name and password credentials held for each application by the VTScada Security Manager. This is the sole protection that is afforded to a VTScada Thin Client Server from unauthorized access. Therefore, these credentials must be guarded.

Security is provided by implementing a virtual private network (VPN), or by using HTTPS (Transport Layer Security, or TLS). This establishes an encrypted communications connection that is secure against decryption, relay attacks and many other hacking attempts.

All systems that use a thin client on a WAN (wide area network) should use a VPN or TLS to secure their communication. Optionally, consider configuring the properties, HTTPAllow, HTTPDeny to limit connections to known addresses. You might also consider configuring the Thin Client Server as a Read-Only Workstation in your network's DMZ Closed Demilitarized zone. A physical or logical subnetwork that contains and exposes an organizations's external-facing services to an untrusted network such as the Internet..

The VTScada Security Options dialog includes an option that controls whether VIC (VTScada Internet Client) connections are maintained after a user logs out, but leaves the browser open. Choosing that option allows a faster re-connection time and ensures that the operator can reconnect, but at the cost of tying up a license for an undetermined time.

Step 3: Configure one or more VTScada Servers as VTScada Thin Client Servers

It is common for one of your server keys to allow many thin client connections and the others to have few or none. Licenses are shared between servers after configuration. Always do the work of configuring your Thin Client Server list on the computer that has the licenses. It will be the first server added to the server list. When you add other computers to the list, the licenses will be synchronized to those other servers and saved to them.
After the setup is complete, the order of the server list may be changed, but the name of the server with the licenses can never be removed from the list. If you do this, all the other servers will also lose the licenses.

Full description and instructions: Define the Server Setup

Use the VTScada Thin Client/Server Setup dialog to add the computer where you are working to the server list and configure connection parameters. If your application runs on multiple servers, you may also set up redundant operation.

You may configure the Thin Client Server and realms on any port you prefer. However, if connecting from a public network (e.g. the Internet), you will likely have to traverse firewalls and other security mechanisms. Configuring a realm or Thin Client Server to operate on ports other than the standard ports (port 80 for plain text HTTP, or port 443 for HTTPS), will likely require special configuration of such interposing security mechanisms. It is therefore advisable to operate on the standard ports whenever possible and assuming that no other service on your computer is already using your chosen port.

The list can be configured only from a machine that is a member of the list, and will remain a member after configuration.
If you attempt to remove the last local server, the entire server list and all related connection addresses will be removed from the local machine.

At smaller locations where there may not be a DNS or a network administrator who can take care of such things, you should do the following. It is also worthwhile to review the documentation topic RPCConnectStrategy.

  1. Run Notepad as an administrator.
  2. Open the file, HOSTS.
    This is located in the directory C:\WINDOWS\SYSTEM32\DRIVERS\ETC
  3. Add a line for your computer name and its IP address.
    For example:
    192.165.6.2 MyComputerName
    ...where "MyComputerName" must precisely match a computer name on the X.509 certificate installed on the server.
  4. Save the HOSTS file.

The local indicator will not immediately show a check mark. Upon saving the server setup and reopening the dialog, the check mark will be there if VTScada is able to recognize that this computer is the Thin Client Server.

Step 4: Add the Connection Addresses for Those Servers.

Full description and instructions: Define the Connection Addresses

A need for an address list other than "Default Address List" is extremely rare.

You must define how operators will connect to the servers in the license cluster. The set of connection addresses can include the public URL configured for your security certificate and also the address of a specific server for use by local connections.

Step 5: Establish a Realm Containing One or More Applications

Full description and instructions: Internet Realm

In short, a realm is a named list of one or more applications that are to be made available to VIC and Mobile Internet Client connections.

If Security Realms are enabled, you must create one Internet realm for each security realm, matching the names. Operators may connect only to the Internet realm that matches their security realm. Super-users (those not belonging to any security realm) may not connect to any Internet realm unless you also add the application property, RootNamespace, setting its value to the name of a realm to which those users should connect.

The value of RootNamespace must not match any defined security realm.

Step 6: [Optional] Add a Realm Display Setup tag

You may choose to add one of these tags for each realm. Realm Display Setup Tags allow you to define the level of control that operators will have over their display parameters.

Step 7: [Optional] Add a disclaimer message

You may choose to add an HTML file to your application, which will be displayed to all who connect. This must be a complete HTML file that is part of your application (Import File Changes Tool). Note that JavaScript content will not execute and should not be included. You can find an example thin client disclaimer in the VTScada examples folder: (C:\VTScada\Examples\ExampleThinClientDisclaimer.html)

After adding the file to your application, create an application property named ThinClientDisclaimer whose value is the name of your HTML file.

Specific cases requiring further configuration:

  • For those who want to allow VIC connections from outside their firewall to their VTScada Thin Client Server, where their site has a simple router and no internal network infrastructure services (e.g. DHCP/DNS), refer to Network Configuration
  • Cross-Origin Resource Sharing" (CORS). You may need to use this at a smaller site if connecting using a machine alias, or at a larger site if using a third-party load-balancing server. Refer to Domain Aliases (CORS)
  • Enable HTTP Strict Transport Security (HSTS). You might choose to do this to ensure that only HTTPS connections are allowed. This mitigates the danger of an attacker hijacking session cookies.


Securing a VTScada Thin Client Server

Before configuring the Thin Client Server, you must understand the relevant security issues. All devices attached to the Internet are open to all eyes unless properly secured.

Access to the VTScada Thin Client Server is protected by the account name and password credentials held for each application by the Security Manager. This is the sole protection that is afforded to a VTScada Thin Client Server from unauthorized access. Therefore, these credentials must be guarded.

When credentials are transmitted between the client and the server, the account name and the password are both transmitted using Base64-encoding. The encoding is public knowledge and is entirely reversible, therefore the name and password can be extracted easily.

Credentials are secured by using Transport Layer Security (TLS). This establishes an encrypted communications connection that is secure against decryption, replay attacks and many other hacking attempts.

It is strongly recommended that all systems that allow connections from the Internet use TLS to secure their communication.

To use TLS on a VTScada Thin Client Server, you must purchase and install an X.509 certificate. Instructions are provided in the Security chapter: Internet Security (TLS, X.509, SSL). Once configured, you may wish to take this a step further and allow only secured connections by configuring HTTP Strict Transport Security (HSTS)

Security involves the server providing an X.509-compliant digital certificate to the client, permitting the client machine software (web browser) to positively validate that the server is genuine before engaging in encrypted communication. Only a Certifying Authority (CA) can issue an X.509 certificate that a web browser or VIC will accept without warning you that the certificate cannot be properly validated. This means that you may use a "test" certificate (available from most CAs), but will receive conspicuous warnings by both your web browser and VIC, ensuring that you cannot be "fooled" by a fake certificate. Only a properly issued certificate for the correct host and domain name will be accepted silently. The domain name is usually be registered to your company and will be verified to be so by the CA.

The asymmetric keys used by TLS ensure that your VIC (only your VIC - no other VIC or other program) can decrypt the communication stream from the server. The keys also ensure that only the server to which you are talking can decrypt any communication from your VIC. Only after secure communication has been established are your authentication credentials supplied to the server.

In addition to securing the line of communication, you must address several additional security issues related to your VTScada Thin Client Server:

  • Remote users must have a valid user account within the VTScada applications they wish to access remotely using a thin client.
  • User accounts of clients wishing to access VTScada applications remotely on a thin client must have the "Thin Client" security privilege, which allows the user to remotely view the application.
  • You should consider whether you wish some pages within a standard VTScada application to be protected from specific users, through the use of custom privileges.
  • If security realms have been enabled, then users in a security realm can connect only to a VTScada Thin Client Server realm with a name that matches.
  • If the VTScada Thin Client Server is a workstation that has been configured for read-only access (Read-Only Workstation), then all thin client connections to that server will have read-only access.

    HTTP access to files and folders is restricted to those listed in the [HTTP-Unauthenticated] section of your Setup.INI file. Application folders do not need to be added to this list to run those applications on a thin client. ([HTTP-Unauthenticated] Section)

For publicly-accessible kiosks or demonstration applications where access should be open, use one of the following options:

  • Create an account with a carefully selected (restricted) set of privileges, then provide the username and password to that account in the disclaimer banner. You can find an example of a thin client disclaimer (ThinClientDisclaimer) in ..\Examples\ExampleThinClientDisclaimer.html
    Note that the thin client disclaimer is shown to connections using the Anywhere client and the VIC client, but not the Mobile client.
  • If a VTSX client connection is possible (Connect Using the VTSX Program Connect Using the VTSX Program) use the Save Password option of the ActiveX client and save a shortcut that includes the password to the workstation's desktop.
  • If using the Anywhere client, set a long duration for credential storage using the RememberLoginDuration setting, then have an authorized user sign in as needed (using the carefully restricted public account) before leaving the workstation available for public access.

Files with one of the supported MIME type extensions, (.HTML, .HTM, .JS and .XML) are not served without authentication unless added to the [HTTP-Unauthenticated] section of your Setup.INI file.
Regardless of that protection, use care if storing sensitive information in a file having one of the listed extensions.

Privileges Related to Thin Client Servers

VTScada has several security privileges that enables users of a VIC to view and perform limited configuration operations to VTScada applications running on a VTScada Thin Client Server.

Thin Client Access privilege

Must be granted before any account or process can access the server.

Thin Client Monitor Access privilege

Must be granted for users to open the thin client monitor page.

Thin Client Monitor Admin privilege

Required for users to enable or disable connections via the Thin Client Monitor page.

Remote Data Access Privilege

Required for remote users to connect to VTScada data via ODBC (REST) or OPC .


HTTP Strict Transport Security (HSTS)

HTTP Strict Transport Security (HSTS) is an optional security feature that instructs a web browser to communicate with VTScada using only HTTPS. When enabled and the browser has communicated with VTScada over HTTPS once, the browser will refuse to make any attempt to communicate with that same domain (and sub-domains) in the future using plain text HTTP, requiring HTTPS instead.

Why use HSTS?

HSTS addresses threats posed by an attacker hijacking session cookies when User Agents (such as a browser or the VIC) use unencrypted communication. It does this by including an HTTP header requiring the User Agent to use HTTPS communication exclusively for a domain. Any attempt to communicate with the domain (or subdomains) using HTTP is refused by the User Agent. Your browser (or VIC) will refuse to make an attempt.

Enabling HSTS

HTTP Strict Transport Security is enabled and configured within the Realms tab of the Thin Client/Server Setup dialog. Refer to Configure a Realm

HSTS can be enabled only after all your realms and connection addresses are configured to use HTTPS. If you attempt to enable HSTS while there is still an HTTP connection configured, you will be presented with a warning message reminding you of this fact.

Maximum HSTS Age

HSTS causes User Agents to enforce HTTPS usage for a period of time (measured in seconds), which is known as the Maximum HSTS Age. A value of zero disables the feature. Note that once a User Agent has received an HSTS header with a non-zero Maximum HSTS Age over HTTPS (not over HTTP) it will apply the enforcement. Setting the HSTS Maximum Age back to zero has no effect on the User Agent until it receives the updated Maximum Age information over an HSTS connection. The HSTS Maximum Age defines the period of time since a User Agent last communicated with your VTScada server.

You therefore cannot simply set the HSTS Maximum Age to zero and switch from HTTPS to HTTP without taking manual action at the User Agent to turn HSTS off, because only User Agents that are connected to your VTScada server at the time you modify the HSTS Maximum Age will know about the change.

The HSTS Maximum Age can be configured on the Thin Client/Server Setup dialog. Note that the minimum setting for HSTS Maximum Age that will enforce HSTS is 7 days (604800 seconds). This is a restriction of Windows.

Reverting to plain HTTP communication

Should you wish to allow plain HTTP communication with your VTScada server when HSTS has been enforced, you can set the Maximum HSTS Age to zero in the Internet Client/Server Setup dialog and then allow a period of time for all systems using thin clients to communicate with the server in order to receive the instruction to remove their HSTS enforcement. Inevitably, there will be some systems that do not communicate with the server during this period of time. For those systems, you must manually reset them:

  • For Chrome/Edge, visit chrome://net-internals/#hsts (or edge://net-internals/#hsts for Edge). In the "Delete domain security policies" edit field, type in the domain you for which you wish to clear HSTS.
  • For Firefox, open the history window with the keyboard shortcut Ctrl + Shift + H. Find the site for which you want to delete the HSTS settings. Right-click the site from the list of items and click Forget About This Site. You will need to restart Firefox.
  • For the VIC, Open the Windows Control Panel, and select Internet Options. On the General tab, click the Delete button (Browsing history). Make sure that the option, "Temporary Internet Files" is selected and click Delete. Note that you do not need any other options selected on this dialog.
  • For Safari, quit Safari and then edit the file ~/Library/Cookies/HSTS.plist. Remove all entries for your server from that file. You may need to restart your device.

It is sensible to plan the introduction of HSTS enforcement by configuring a short HSTS Maximum Age initially so that any problems resulting from its use are short lived. For example, you could set an HSTS Maximum Age of 10 minutes so that a User Agent will turn off its HSTS enforcement 10 minutes after it last communicated with your VTScada server. The avoids having to tell the User Agent to forget about HSTS. After a time, you can increase the HSTS Maximum Age value. Commonly used values are in the range of one to two years, but you can set any value that is sensible in your situation.


Servers in a Demilitarized Zone (DMZ)

For additional security, many sites choose to locate their VTScada Thin Client Server in a demilitarized zone of their network. (Separated from the Internet by one firewall, and from the internal network by another.) This configuration can allow both effective and secure external connectivity (for 3rd party connections and remote Thin Client connections) to a VTScada application without endangering the internal network.

  • Install a separate VTScada server in the DMZ. If serving external ODBC or OPC connections, the license must be either a Development Runtime, or a Runtime with the Connectivity Package (ODBC Server & OPC Server.)
  • Configure the firewall between the SCADA network and the DMZ to allow only connections on the VTScada RPC port 5780 that are initiated from the SCADA network side.
    VTScada does not require any additional configuration for this, as long as at least one VTScada service includes the DMZ computer as a backup server on its server list.
  • Add the DMZ computer as a backup server on the list of Historian servers. (Or to the Default Servers list if there is no separate System Historian servers list.)
  • If all connections to an external thin client should be prevented from performing operational control actions, the DMZ computer can be configured as a Read-Only Workstation Read-Only Workstation. This can be configured to lock out control for all Thin Clients connected to this computer, regardless of the operator's privilege set.
    If specific external users require the ability to perform operational control actions, use standard Accounts and Roles Accounts and Roles configuration.


Define the Server Setup

Use the VTScada Thin Client/Server Setup dialog -> Server Setup tab, to identify each VTScada Thin Client Server in your system. These are the machines where you have installed a copy of VTScada licensed for thin client connections. (See notes later in this topic as well as Server Requirements and Licensing)

Server Lists - Procedure

Refer to the notes that follow these instructions before configuring your list of servers.

  1. In the VAM, click on the VTScada Thin Client/Server Setup button.

The VTScada Thin Client/Server Setup dialog opens.

  2. Select the Server Setup tab.

Colors within the list have meaning. Refer to the notes later in this topic.

  3. Click Add. The Add Server dialog opens.

  4. Enter the name of the first server you wish to add to the VTScada Thin Client Server list in the Server field.
    The list can be reordered later.

In general, it is better to use a name than an IP address.

  5. Click OK. The Add Server dialog closes, and you are returned to the Server Setup tab, where the server has been added to the server list.
  6. Repeat steps 2 through to 5 to add any other servers that should be part of this license cluster.

The list can be configured only from a machine that is a member of the list, and will remain a member after configuration.
If you attempt to remove the last local server, the entire server list and all related connection addresses will be removed from the local machine.

Notes:

Server Lists - Discussion

The Server Setup tab defines a "cluster" of thin client servers. (VTS/IS Clusters and Server Lists)

For example, the following image shows a cluster with two members: Bridge-PC and Engineering-PC.

Color Coding:

After saving the list, entries are color-coded as follows:

  • Black text: VTScada has contacted the listed server and all is well.
  • Gray text: The server cannot be reached. It may be offline or there may be network issues.
  • Red text: The server can be reached and has been found to be a member of another cluster.
    Servers cannot be members of two clusters simultaneously. It must be removed from one or the other.

In installations with many servers, there is no requirement that all of the servers be listed in a single license cluster. You might decide to maintain two or more smaller server lists in order to better manage license clusters.

If the Load Balancing option is selected, client connections will be distributed between servers automatically, reducing the load on any one particular server.

Configuration updates:

Thin client servers in a cluster share information about all the connected thin client sessions across the cluster, along with license and configuration details. Updates to either the Realms or the Server Setup on any one server in the cluster are automatically propagated to all. Changes on the Connection Addresses tab are automatically sent to all client sessions.

Clusters and Thin Client Connection licenses:

A cluster is a group of servers that serve Thin Clients. The servers in the cluster provide redundant failover for thin clients should one of the servers fail or be taken offline. You can have multiple clusters. As each thin client periodically tests the connection to each server in the cluster it is using, the more servers you have in a cluster, the higher the network traffic will be. A thin client that starts up and cannot contact all servers near the top of the server list for the cluster rapidly will have a slow startup. Therefore the number of servers in a cluster is a balance between redundancy and performance. If you have many thin client servers, it is better to organize the servers into small clusters. Note that a thin client cannot fail over across clusters - only to servers within a cluster.

License counts are combined within a cluster. You can connect more clients to any one server than would otherwise be allowed by its license limit, so long as the total number of connections within the cluster does not exceed the cluster’s license limit.

If only one server in the list holds Thin Client Connection licenses, that machine must be added to the list first. If that machine is removed from the list, the remaining machines do not retain the ability to act as VTScada Thin Client Servers.

If a server fails, you do not lose its license count from the total during the time it is offline. All VIC connections to that machine are immediately re-routed to the remaining servers in the cluster that are running the application, even if this would exceed the licenses available on the remaining machines.

If sub-networks within the organization become isolated such that the servers are temporarily unable to communicate with each other, each server will maintain the full license compliment of the cluster, even though this may exceed the license limit of that one machine.

When isolated servers reconnect, if the combined total number of connections exceeds the license cluster limit, no new connections can be made, but existing connections in excess of the limit are maintained.

While the server list maintains excess connections, an event will be logged in the alarm history every 10 minutes, warning of this state.

Realm session limits are maintained across a cluster such that the total number of connections to a realm throughout the cluster may not exceed the configured limit.

Redundancy and Fail-Over

The following applies only to VIC and Anywhere connections. Both will receive a list of Connection Addresses from whichever server it connects to and will periodically test each Connection Address. If the Connection Address the client is connected to fails, the client will automatically connect to the next server in the Connection Addresses list. (See Connection Addresses tab).

If the server to which a Mobile client (MIC) is connected fails, the connection is simply lost. The MIC makes no attempt to connect to an alternate server.

Server List / License Cluster Examples:

Reminder: The term "thin client cluster" refers to a pool of thin client servers that provide redundancy and can share thin client licenses.

The list can be configured only from a machine that is a member of the list, and will remain a member after configuration.
If you attempt to remove the last local server, the entire server list and all related connection addresses will be removed from the local machine.

Servers A, B, C, D and E are all part of one network. VTScada is able to communicate across all.

On any of A, B or C, the following list is defined:

Server List

| A

| B

| C

This constitutes cluster 1. VTScada shares the thin client licenses from each of these servers between all three.

On any of D or E, the following list is used to define cluster 2:

Server List

| D

| E

If D were to be added to the server list for cluster 1, it would appear as follows:

Server List

| A

| B

| C

| D

The red color indicates that D is already of member of another cluster and cannot be added to cluster 1. Its status in cluster 2 does not change. Cluster 1 cannot "steal" a server from another cluster.

If your intent is to move D from Cluster 2 to Cluster 1, then first remove it from Cluster 2. Then add it to Cluster 1. Note that you cannot perform the second part of this action while working on machine D, as per the earlier warning. D cannot force itself into a cluster. This is a security feature - you must have the ability to edit the server list for a cluster in order to add a new server to it.


Define the Connection Addresses

Use the VTScada Thin Client/Server Setup dialog / Connection Addresses tab to identify the connection information that thin clients will use to connect to the servers in your system.

The instructions to configure a server are the same for all client connection methods. It is the presence of the word "/mobile" or "/anywhere" in the connection address that distinguishes mobile device and Anywhere client connections from VIC connections.

Localhost addresses are not permitted. ("Localhost", "127.0.0.1", and variants.) These are ambiguous when there is more than one VTScada server.

Connection Addresses - Procedure

Refer to the notes that follow these instructions before configuring your connection addresses.

There will always be a Default Address List. This list and its associated connection parameters will be provided to a thin client if the server it is connecting to does not have a custom address list.

In very rare instances, you might select a server from the "Address list for server" droplist and deselect the "Use default list" option to configure a custom address list and associated connection parameters. This list and its associated connection parameters will be provided to thin clients connecting to that particular server. This is an uncommon configuration. Do this only if you are sure that you need custom connection parameters for different servers.

  1. In the VAM, click on the VTScada Thin Client/Server Setup button.

The VTScada Thin Client/Server Setup dialog opens.

  2. Select the Connection Address tab.

  3. In most cases, leave "Address list for server" set to "Default Address List".
    In very rare cases, you might select an alternate server and then deselect the "Use default list" option. Connections to that server would then be made via an alternative connection address.
    In either case, the remaining steps are the same.
  4. Click Add. The Add Connection Address dialog opens.

  5. Enter the connection address.

The name must be one to which clients can connect. In general, it is better to use a name than an IP address.
For local connections, you can provide the name of the server. External connections must use the canonical name that you have configured. (for example: scada.mycompany.com)
If you are using secure connections, this must be a valid name listed in your certificate.

  6. Enter the port number on which you wish this server to listen in the Port Number field.

The default port number is 443, the secure Hypertext Transfer Protocol (HTTPS) port.
Ensure that the port is not already in use by other processes on the server.

If you are creating a local connection, the standard port number is 80 but watch for other software using that port.

  7. Select the "Secure" check box if you wish to use Transport Layer Security to secure data that is transferred across the connection.

If this check box is not enabled, refer to discussion and instructions in the "Secure Your Application" topic, Internet Security (TLS, X.509, SSL)

The completed Add Server dialog for a remote server (not the local PC) should appear similar to the one displayed here.

  8. Click OK. The Add Connection Address dialog closes, and you are returned to the Connection Addresses tab, where the connection has been added.
  9. Repeat steps 2 through to 8 to add any other addresses that should be part of this set of Connection Addresses.
  10. Click OK to save the address list and close the VTScada Thin Client/Server Setup dialog.

Notes:

Connection Addresses - Discussion

The connection addresses list provides the ordered list of servers that the thin clients will use to communicate with a server.
Under redundant operation, when the connection is lost to the current server, the thin client will attempt to use the next available server in the order given.

Port:

Set the port number to use on the selected server.

When configuring your server, ensure that you select a port that is not in use by any other process on your server. Port 80, the default HTTP port, is often used by other programs. You can check your server by opening a command prompt as an administrator, then running "netstat -ao". You can then check the process ID value in the Windows task manager. For example:

C:\WINDOWS\system32>NETSTAT -AO

Active Connections
Proto Local Address Foreign Address State PID
TCP 0.0.0.0:80 MYSTATION-PC:0 LISTENING 4
TCP 0.0.0.0:81 MYSTATION-PC:0 LISTENING 10916

This example shows that port 80 is in use by process id #4, which belongs to Windows. Port 81 is in use by process #10916, which happens to be a configured VTScada server in this example.

Fully Qualified Domain Names

* Computer names (aka NetBIOS names) or IPs can be used in a server list only if all machines, including your VTScada Internet Servers and thin clients, are on an internal network.

* If some machines, clients or servers, are in different domains, then the list should include only fully-qualified domain names (FQDNs).

* If the names used by external clients to connect to your servers, (that is, names that are resolvable by an external DNS) are different from the internal machine names (those that are resolvable by your internal DNS or other methods) then your server list should use the external/public FQDN (the TLS certificate name) in the server/connection list; on the LAN, ensure that same FQDN resolves to internal IPs via split DNS or a HOSTS entry. Your internal name resolution mechanism (DNS or other) should be configured to resolve those names to the internal IPs of the servers.

For example: sitewatchanywhere.co.uk in Connection Addresses --> internally resolves to 10.10.10.5, 10.10.10.6

* Do not attempt to provide both internal and external names for the same server. Doing so will only cause slower overall performance.

Secure

Select if this server uses transport layer security, as described in Internet Security (TLS, X.509, SSL).

Connection Parameters: Read Timeout, Session Timeout and Mode

These parameters are used to control whether VIC and Anywhere Client sessions will switch servers in the event that a higher-order connection that was lost becomes available again.

Detecting a Lost Connection - Read Timeout

Under normal operation, thin clients work by sending requests to a VTScada Thin Client Server. The server will respond with data if there is any to send, or with an empty response if there is none.

If no response is sent to the thin client by the end of the read timeout period, then the client detects that a server has not responded. A loss of connection is assumed.

Therefore:

  • A shorter read timeout results in more rapid detection of loss of the server, at the expense of increased network traffic.
  • Too short a timeout may result in false detection of server failure.
  • There is no increase in the update rate of data displayed by the thin client by having a shorter timeout.

If the client detects that the server has not responded, it closes its connection to that server and makes one attempt at re-establishing the connection. If this fails, the client will attempt to connect to the next highest-ranked server available, according to the order of the server list.

A read timeout of 15 seconds is recommended as the maximum setting for a LAN, and the minimum setting for a WAN. If your network serves both LAN and WAN connections then 15 seconds is recommended. Otherwise, adjust the value up or down as needed.

Because there is always one attempt to reconnect after a timeout, the time required for the VIC detect irrecoverable loss of communication with its server is twice the read timeout value.

Orphaned Sessions - Session Timeout

Loss of a connection between a client and the server will result in an orphaned session taking up resources on the server. The session timeout exists to let the server know when it should recover those resources and clean up such orphaned sessions.

When the server detects that there has been no communication from the client for the period of time specified in the Session Timeout, it destroys all resources used by the orphaned session.

The minimum session timeout that you can specify is four times the read timeout value. An orphaned session will remain visible in the Thin Client Monitor display until the server destroys it at the end of the session timeout.

For the Anywhere Client, Session Timeout has no effect on the length of time that the Stay Signed In option is effective. See: RememberLoginDuration

Mode of Operation

The Mode of Operation determines how a client will behave when a higher-ranked server than the one currently connected to becomes available.

There are two choices for the Mode: Priority or Sticky.

Priority Mode:

When the client detects that a server of higher priority than the one it is connected to becomes available, it will connect to that server and terminate the older connection.

Sticky Mode:

The client will not switch connections if it detects that a server of higher priority than the one it is connected to becomes available.

Note that the timeouts and Mode are transmitted to the client at the start of each session, therefore the client will operate with whatever is configured on the server when it connects to it.

When the client makes its initial connection, it simultaneously attempts to connect to each server in the list and uses the server nearest the top of the list that it can successfully establish a session with. The client waits for an initial period of time, or until the highest-order server responds - whichever is shorter - then it selects and connects to a server. This initial timeout is left up to the TCP subsystem of the client computer and is normally around 20 seconds.

If there are no servers available, the client will continue to try to connect to each server.

Load Balancing

This box is selected by default, but relevant only if you have more than one VTScada Thin Client Server for an application. When selected, new connections will automatically go to whichever server in a cluster has the fewest connections.

Prefer Local Server

Enabled only for Sticky mode. Checking this option puts the server that the thin client initially connects to at the top of the Connection Address list that is supplied to the thin client on initial connection, making the client prefer to use the server it obtained the Connection Address list from.. Load balancing cannot be used in this case.

Troubleshooting:

  • Port conflicts.

You may configure a realm or a VTScada Thin Client Server on any port you desire. However, if connecting from a public network (e.g. the Internet), you will likely have to traverse firewalls and other security mechanisms. Configuring a realm or VTScada Thin Client Server to operate on other than the standard ports (port 80 for plain text HTTP, or port 443 for secured HTTPS), will likely require special configuration. It is therefore advisable to operate on the standard ports whenever possible.

  • 404 errors or cannot reach server.

Use a valid Realm URL (see Internet Realm). In Connection Addresses, list the external/public FQDN (TLS cert name) and make sure it resolves to internal IPs on the LAN (split DNS; see Network Configuration). Verify port/protocol and that VTScada is listening. If using a load balancer/alias, allow it via Clients-AdditionalAllowedOrigins (See Domain Aliases (CORS)).


Error Dialogs (Add Server / Add Connection Address)

You may configure the same VTScada Thin Client Server on multiple ports, and you may configure different VTScada Thin Client Servers on the same port. However, should you inadvertently attempt to duplicate the name and port of a VTScada Thin Client Server or a Connection Address that has already been added to the list, an error dialog opens.

Also, there are restrictions on names as described in the following error message:


MIME Types Supported

In addition to allowing clients to remotely monitor VTScada applications, the VTScada Thin Client Server will also send files of the following MIME types to a client:

  • MIME type: text/html.
    Hyper Text Markup Language. Both .HTML and .HTM file extensions supported.
  • MIME type: application/JavaScript
    JavaScript content - .js file extension
  • MIME type: text/xml
    Extensible Markup Language - .XML file extension

For example, if you have a configured VTScada Thin Client Server and any of your application folders contain an HTML Closed Hyper Text Markup Language. Used for web pages. file, the server will serve that page to any client that requests it. Examples of URLs to access these files from a VTScada Thin Client Server can be found in the topic: URL Interpretation.

Clients attempting to access files of any type other than those specified in the preceding list will see an "Access denied" message rather than the file. This means that the VTScada Thin Client Server will not distribute your application’s .SRC, .INI or other files.

Files with one of the supported MIME type extensions, (.HTML, .HTM, .JS and .XML) are not served without authentication unless added to the [HTTP-Unauthenticated] section of your Setup.INI file.
Regardless of that protection, use care if storing sensitive information in a file having one of the listed extensions.


Network Configuration

This topic is for those who want to allow VIC connections from outside their firewall to their VTScada Thin Client Server, where their site has a simple router and no internal network infrastructure services (e.g. DHCP/DNS). Trihedral strongly advises that you use Transport Layer Security for accessing your VTScada Thin Client Server from outside your firewall.

Typically, in its default configuration, the router blocks all incoming connections. The router will probably have an embedded DHCP Closed Dynamic Host Control Protocol server (for allocating local, non-routable IP addresses on the local network) and a DNS Closed Domain Name Server forwarder (for resolving names using public, or ISP Closed Internet Service Provider-provided DNS servers). Most such routers allow the DHCP server to be disabled if address allocation is done by another means (such as an internal DHCP server or static IP assignments), but rarely provide DNS capabilities other than forwarding. This means that name resolution requests that cannot be directly resolved by the workstation are passed to the router, which forwards the request to an external DNS server

Name resolution is typically done by a machine inside the network perimeter by two means:

  • A machine name without a domain being specified [e.g. VTSCADA1] results in a NetBIOS name resolution and yields a non-routable internal IP address [e.g. 192.168.0.5].
  • A fully-qualified domain name (FQDN) being specified [e.g. vtscada1.trihedral.com] results in a DNS query being made to the router which forwards it to a DNS server on the internet to obtain a publicly-accessible IP address. This is normally the external IP of the router.

So long as the servers and clients (thick or thin) are within the network perimeter and these machines use NetBIOS-type names, this works. It will not work when someone wants to access a VIC server from outside the network perimeter. As the router's firewall blocks all incoming connections by default, to access the VIC server from outside the local network perimeter requires:

  • Port forwarding must be configured on the firewall such that the ports used by the VTScada Thin Client Server are forwarded to the VTScada Thin Client Server.
  • Install a DNS server on the internal network that resolves the server's fully qualified domain name (FQDN Closed Fully Qualified Domain Name) to its local IP address.
  • Configure all servers and clients to use that DNS server when inside the network perimeter. Typically this is done by disabling the DHCP server on the router and installing a DHCP server on the same machine as the DNS server. DHCP can then provide the correct IP addresses to use for DNS, the domain suffix to apply internally (e.g. trihedral.com) and the gateway (router) address.

This is sometimes referred to as "split DNS", "split horizon DNS", "split view DNS" or "split brain DNS". With this setup, you configure the VIC server list to use just the server's FQDN. When a machine is inside the network perimeter, the internal DNS server resolves the server FQDN to a local IP address and when outside the network perimeter, public DNS resolves the FQDN to the router which port-forwards to the server.

In order for TLS to work, the FQDN of the server must be listed on the X.509 certificate and resolve to the server, whether the client machine is on the internal or external network. In other words, you need the name resolution of vtscada1.trihedral.com to yield two different addresses depending on the location of the client - hence the use of a split DNS in this network configuration is recommended.


Domain Aliases (CORS)

Applies to Anywhere Client and Excel Add-In connections, not to VIC connections.

This topic describes the configuration of "cross-origin resource sharing" (CORS). You may need to use this at a smaller site if connecting using a machine alias, or at a larger site if using a third-party load-balancing server.

Intranet aliases

Servers can have aliases. For example your machine "scada1" is reachable from within your network using both http://scada1 and http://scada1.CompanyName.com. If you were to add only "scada1" to your VTScada Thin Client server list, you would find that the Anywhere Client works when you visit it via http://scada1 but fails immediately after logging in if you access it via http://scada1.CompanyName.com because that name is not on the server list.

To work around this, you can tell VTScada that the Anywhere Client may also be started when the address in the URL bar of the browser is "http://scada1.CompanyName.com" by adding "scada1.CompanyName.com = 1" into the Clients-AdditionalAllowedOrigins section of Setup.INI.

[Clients-AdditionalAllowedOrigins]
scada1.CompanyName.com = 1

VTScada will automatically allow "scada1" if "scada1.CompanyName.com" is on the server list, so if you have a working DNS setup, put the full domain name (including .CompanyName.com ) on the server list as it will work in more situations than simply entering "pn2" would.

Internet aliases for load-balancing

You may need to provide users with a single URL that, depending on which of the VTScada Thin Client Servers are presently running, will automatically refer to one or the another server. This configuration of a single URL with failover is sometimes used by hosted solution providers. It enables them to take one or the other server offline without needing to notify customers that they must use a backup URL pointing to the backup server. The ability to do this is known as "cross-origin resource sharing" (CORS).

Example

As an example, given the following VTScada Thin Client Server list:

  • primary.CompanyName.com
  • backup.CompanyName.com

If customers connect to the Anywhere Client using https://primary.CompanyName.com or https://backup.CompanyName.com, then no additional configuration is necessary beyond what is normally done for configuring VIC servers.

Further Notes

Customers with the resources to do so may prefer to install a load balancing server, ScadaCentral.CompanyName.com. This will not run VTScada or host a VTScada Thin Client Server and therefore will never be part of your VTScada Thin Client server list.

The "ScadaCentral.CompanyName.com" address would resolve externally to the load balancer, which would pick one of the VTScada servers and fetch the sign in page from there. Typically such a load balancer would handle any of the servers being unreachable and send the request to one of the backups, meaning that when primary.CompanyName.com is unreachable the load balancer would route the request to backup.CompanyName.com. This is ideal for the end user as they only have to be aware of a single address.

The problem with this scenario is that none of the actual VTScada servers are aware of the ScadaCentral.CompanyName.com address, and signing into the Anywhere Client will fail. The solution is to add "ScadaCentral.CompanyName.com = 1" into the Clients-AdditionalAllowedOrigins section in Setup.INI:

[Clients-AdditionalAllowedOrigins]
ScadaCentral.CompanyName.com = 1

Related Information:

[Clients-AdditionalAllowedOrigins]

[Clients-AdditionalAllowedHosts]


Coded VTScada Thin Client Server Lists

The following is an advanced process, to be used only by experienced VTScada developers when dealing with complex server configurations. For most situations, it is easier to use the option in the Connection Addresses tab of the Thin Client/Server Setup dialog to define a custom list for one or more servers.

If you do not have experience writing code with the VTScada scripting language and do not have a good understanding of Thin Client Server configuration in general, do not proceed in this topic. By design, steps that would be known to an experienced VTScada programmer are not included in the following procedure. Example code is not provided.

In multi-server installations, VTScada Thin Client Server lists are shared between servers, just as all other services are shared. The server list defines a "cluster" of servers that communicate with each other to share thin client sessions. (VTS/IS Clusters and Server Lists) The default behavior is that when a thin client connects to a VTScada Thin Client server, it is provided with this list.

By writing code, you can supply a custom server list to a thin client when that thin client connects to the Thin Client Server. Note that a thin client can change-over to another Thin Client Server in the same cluster, but cannot cross cluster boundaries.

To supply a custom list to a client upon connection, create a variable or a subroutine module at the Code scope, declared as VICServerList. If you supply a variable, your application must initialize it to an array of Thin Client Servers that will be passed to the thin client when it connects. If you supply a subroutine, then that subroutine is called when a thin client connects and returns an array of servers that will be passed to the thin client.

If using a subroutine, it must have two parameters:

(
  Realm        { The realm to which the client is connecting };
  Servers      { The array of server names in the cluster    };
)

Servers is a one-dimensional array of server names, as supplied to the VTScada Thin Client/Server Setup dialog, under the Server Setup tab.

The elements of the Servers array are server names with an optional port number (default 80), a comma and the character U or S for unsecure HTTP or secure HTTPS).

The array returned by the subroutine or the array initialized during startup must be a one-dimensional array consisting of the server names to be passed to the thin client. Each array element consists of the server name, optionally with a port number, a comma and the character U for unsecure HTTP or S for secure HTTPS. For example:

"myserver.example.com:80,U"

This runs on the server to which the client is making the initial connect request. If done via a web browser, this will be on the workstation that services that URL request.


Internet Realms

Viewing: Develop > Thin Clients: Mobile and Internet > Internet Realms

Internet Realm

The word"realm" in VTScada has two meanings:

  • It is a name given to configuration options that include the connection protocol (HTTP / HTTPS) and port (usually 80 or 443). Without a realm there will be no port for Internet communications.
  • It is a security grouping.

This chapter refers to realms that identify an application on a VTScada Internet Server. Realms are required and used by:

  • VTScada Thin Client Server operations including VIC and Mobile Internet Client connections.
  • ODBC Interface to VTScada History
  • Web services via the REST interface
  • Realm-Area Filtering
  • OAuth services
  • Twilio services

Do not name any realm, "Rest" or "SQLQuery". Doing so will interfere with remote access to VTScada data.

Any number of realms can be created, and any application can be placed into one or more realms. Each realm can contain only one application.

When connecting to an application, the name of the realm is included as part of the connection URL Closed Uniform Resource Locator. The address of a web page..

Ports

The default port number is 80, the standard Hypertext Transfer Protocol (HTTP) port. If you are using Transport Layer Security (TLS), you must first have obtained an X.509 certificate (see Internet Security (TLS, X.509, SSL)), and installed it. Supply the TLS standard port number of 443, in this case, and look at the "Secure" check box. If this check box is disabled, you need to supply the host + domain name for the certificate in VTScada's Setup.ini configuration file (located in the installation directory). Add the following line to the [SYSTEM] section:

SSLCertName = <host+domain>

where <host+domain> is the host and domain name you specified when obtaining an X.509-compliant certificate. (Do not include the angle brackets.) This must exactly match the "CN=" field of your certificate. After modifying the Setup.ini configuration file, you must stop and restart VTScada for your change to take effect.

If connecting from a public network (e.g. the Internet), you will likely have to traverse firewalls and other security mechanisms. Configuring a realm or VTScada Thin Client Server to operate on other than the standard ports (port 80 for plain text HTTP, or port 443 for secured HTTPS), will likely require special configuration of such interposing security mechanisms. It is therefore advisable to operate on the standard ports whenever possible.

Note that there is no requirement that the port(s) used by your realms match those used in the server tab. The port on the realm is used to configure the address to which the client will connect to authenticate. After successful authentication, an XML packet will be passed back to the client, which will include the list of servers as configured on the servers tab. The client will use that list to connect to a server.

Security-Realm Sign-ins with Thin Client Realms

If you are using security realms (groups) and realm-area filtering, then you must create a thin client realm having the same name as each security realm. Operators who would normally sign on using their realm name, account name, and password will instead open a URL having a realm that matches the security realm name and sign in using just their account name and password. They will not be allowed to connect to any other realm.

Users who are not members of any security realm, will not be able to sign in over the Internet unless the application property RootNamespace (RootNamespace) is added and its value set to the name of a thin client realm created for the use of these accounts.


Configure a Realm

If exposing diagnostic applications to the Internet you are advised to take all possible precautions to prevent their use by unauthorized persons.

Do not name any realm, "Rest" or "SQLQuery". Doing so will interfere with remote access to VTScada data.

Configure a Realm

Preparation

Before configuring a realm, the following must be in place:

  • Secure the application. See: Best Practices for Security.
  • Configure the VTScada Thin Client Server. See: Configure a VTScada Thin Client Server.

If you plan to allow programmers and developers to access diagnostic applications such as the Source Debugger or TraceViewer from an Internet connection then you must secure those applications.

Script applications will run when accessed by an Thin Client. Do not configure them to start automatically.

If exposing diagnostic applications to the Internet you are strongly advised to take all possible precautions to prevent their use by unauthorized persons.

The Realms configuration panel

Steps:

  1. Open the VTScada Thin Client / Setup dialog, from the VAM Closed VTScada Application Manager.
  2. Ensure that the Realms tab is selected.
  3. Click Add in the Authorization Realms section of the dialog.

The Add Realm dialog opens.

  4. Enter a meaningful name for the realm in the Realm Name field.

Realm names should not include spaces. Use a hyphen, underscore or mixed case to indicate word boundaries (e.g. "My-Realm", "My_Realm" or "MyRealm" ).

  5. Enable the HTTP protocol.
  6. Enter the port number that connections to the server should use.

    This may vary from the port number configured in the Connection Addresses tab, depending on your network configuration.
  7. Select the number of clients.

    Some sites might allow all possible connections to the same realm while others divide their licensed connections between
  8. Click OK.

The new realm is created, and you are returned to the VTScada Thin Client / Server Setup dialog where the new realm appears in the Realm drop-down list.

  9. In the section, Applications Available on [RealmName], click the Add button.
  10. Select the VTScada application you wish to add to this realm from the Application drop-down list.
  11. Click the OK button.

    The application must be running in order for it to be found.
  12. Test using one of the three connection options.
  13. Repeat from step 9 if you intend to make multiple applications available on this realm.

    It is generally more secure to have only one application per realm, but if your site uses Active Directory credentials, it may be necessary for one realm to include all the applications to which operators might connect.

  14. Click OK.

Your application is now available to VTScada thin clients.

If all connection addresses are secure, you may choose to enable HTTP Strict Transport Security. This mitigates the danger of an attacker hijacking session cookies. Refer to HTTP Strict Transport Security (HSTS)

Test

Having successfully configured a VTScada Thin Client Server, and a Realm, you can test your work directly from the Realm configuration dialog.

It must be possible to create a local connection to the VTScada Thin Client Server to test using this dialog. If the "Local" box option is not selected in the Server Setup page of this dialog, you should review your Name Resolution service. If there is no network connection, this might be done by editing the HOSTS file in your C:\Windows\System32\Drv\ folder to configure the IP address for your computer name. Also, the application must be running.

Remove

Removes the selected realm (and the application attached to it) from the list.

You will be prompted to confirm this action before the realm is removed. (When removing an application from the realm, there is no prompt.)

In the case that you have more than one Thin Client Server, the realm will be removed from all. Any users who are connected to the realm will be disconnected immediately.

Troubleshooting:

  • Unable to connect.

Check that no other service is using the configured port.

If trying to connect using the server computer, ensure that the Local option is selected (done automatically). If not, it is likely that the domain is not being recognized.

If trying to connect remotely, check that the server is visible on the network. Firewall or proxy server configuration may be required.

Check that the VTScada Thin Client Server configuration was completed correctly.

Check that security is enabled in the application, and that your account has the Thin Client Access privilege.


Connect Using the Anywhere Client

URL format, assuming that you have enabled TLS/SSL security:
https://YourCompany.com/RealmName/anywhere

The VTScada Anywhere Client is a JavaScript-based technology that enables you to view and operate your application on any device, using any of the major browsers. The Anywhere Client has been tested on Windows, iOS, MacOS, and Android operating systems and will work using Chromium-based browsers and newer FireFox, and Safari browsers.

Not all combinations of operating systems and browsers have been tested.

Most browsers (including Chrome, Edge, Firefox, Safari...) require that the user clicks / taps on the page before it allows audio playback, including alarm sounds. This also applies when the Anywhere Client has been added to the home screen.
It is strongly recommended that you proactively adjust browser settings to always enable sound playback for VTScada. This is especially critical for setting up Anywhere Clients using the Stay Signed In option on workstations.

Refer to the support pages for your browser for the latest guidance.
Example 1: Change site settings permissions - Computer - Google Chrome Help
Example 2: How to Enable or Disable Media Autoplay in Microsoft Edge in Windows - Microsoft Community

A note of caution: Users should only enable autoplay for their specific VTScada Anywhere Client URL (e.g., https://YourCompany.com/RealmName).. Enabling autoplay globally may lead to intrusive behavior from other sources.

If operators will use the Anywhere Client to view your screens, avoid the Momentary Button Widget. No browser interface allows for a long press.
Use a digital I/O tag with a configured pulse duration instead.

The client is zero-footprint, meaning that no code and no applications are installed on your computer. Everything runs within the browser.

Anywhere Client enables you to store your authentication session temporarily using the Stay Signed In check box. This will remain in your browser's cache for the time specified by the application property, RememberLoginDuration. This defaults to 20160 minutes (14 days). You may choose to set this to 0, which will effectively prevents caching of credentials.

Of the three clients provided for VTScada, only the Anywhere client can be used with OpenID Connect Authentication. See also Domain Aliases (CORS)

The Anywhere Client logon screen, showing the Stay Signed In option.

The user interface is nearly identical to a full VTScada workstation installation, allowing for minor differences in font and window details that may occur from one browser to another. All the features of a run-time VTScada installation are enabled except for:

  • The Select Color dialog has limited functionality. The color-picker eyedropper tool will not work.
  • Some limits to client-side file reading or writing, therefore...
    • Not able to apply a ChangeSet.
    • Not able to synchronize tags.
    • No access to the Lexicon dialog.
  • Internet Explorer version 11 does not support sound with the Anywhere Client.

If generating a file using the VTScada Anywhere Client, it will be transferred to your browser automatically. Check your browser's download history. (Will vary by browser.)
Only text files can be generated by a thin client, not spreadsheet or database files.
Similarly, Excel templates cannot be used when reporting via a thin client.

This applies to report generation, HDV exports, note exports, ChangeSet creation, and tag exports.
You cannot view a generated file (such as a report) within the Anywhere Client. The client shows only the VTScada user interface.

A sample application, with a pop-up window and a trend, running in Chrome using the Anywhere Client.

Related information:

Programmer's Notes for the Anywhere Client


Programmer's Notes for the Anywhere Client

Due to limitations of what can be done in a web browser, the following features will not work in the Anywhere Client. These notes are of interest primarily to VTScada programmers, and much of the following will have meaning only for advanced VTScada programmers. See also: IsVICSession

  • It is not possible to read or write files on the client using "session-aware" FileStreams. Calling FileStream with the Flags set so as to be session-aware causes FileStream to do nothing and return Invalid.
  • The following functions do nothing in Anywhere client sessions:
    • FileDialogBox,
    • PrintDialogBox,
    • FontDialog,
    • WindowSnapshot,
    • ZEditField,
    • Text,
    • Beep,
    • Table,
    • Line,
    • Pipe,
    • PrtScr,
    • ActiveX
    • ClipboardGet
    • ClipboardPut
  • The Spawn function can be used, but only to open a web link.
  • The following WindowOptions that work on the VIC will not work on the Anywhere Client: 9, 10, 11, 14.
  • WinToolTipCtrl only supports style bit 128 within the Anywhere Client. All others are ignored.
  • GUIButtons with rotation, or sides not equal to 0 or 4, are not displayed.
  • Changes to Application Window Behavior and Application Window Size settings do not take effect on Anywhere clients until they restart.
  • "Enable Logged Off VIC Sessions" has no effect on Anywhere clients. They disconnect on logout.
  • WinShiftKeys only reports the state of Shift, Ctrl, and Alt on Anywhere clients. Those keys plus the Caps, Num and Scroll lock keys work on VICs.
  • Pages may contain regions that must respond independently to select, touch and panning messages. For example, a Sites page containing a map. The Pick() function has options to suppress horizontal and vertical panning events over a region.
  • All resizable Windows with scroll bars disabled (those with bits 2 and three set to zero and bit 8 set to one) will have unlimited maximum size when running on the Anywhere client. This will affect the virtual size reported by the VStatus tool.

  • The Anywhere Client doesn't support WMF or EMF file display. If an additional file like, "ImageName.wmf.svg" or "ImageName.wmf.png" exists, then this will be sent to the client and displayed in its place. SVG files will be prioritized over PNG files. PNG files are raster images, not vector images, so they will not scale. The images must be fully converted, not just renamed.


Connect Using a Mobile Device

URL format, assuming that you have enabled TLS/SSL security:
https://YourCompany.com/RealmName/mobile

The Mobile Internet Client (MIC) provides functional access to an application in a format that is optimized for use on mobile devices such as smart phones.

There is no "Sign Out" button in the mobile interface. Clients are automatically signed out and their session ended when the time specified by IdleWebSessionTimeout passes after closing the connection.
Sessions will endure and clients will remain signed in so long as the connection is left open.

The optimized display of the MIC

The following browsers (and later versions) are supported. Note that JavaScript must be enabled in all cases.

  • iOS™ (iPhone™ and iPad™) (iOS 4.3.5+)
  • Android™ 2.1+
  • Blackberry™ 6.0+

You can also access the "mobile view" from desktop browsers using any operating system. Supported browsers include the following:

  • Firefox™ 3.6+
  • Internet Explorer™ 9+
  • Safari™ 5.1+

Others may also work.

The syntax of the request is as follows. The only difference between this and the VIC connection URL is the addition of "/Mobile".

https://Your.ServerName.Com/YourRealmName/Mobile

Upon establishing a connection, you will be prompted to sign in:

MIC logon screen

The mobile client will open. Note that the screen does not update continuously, but will refresh automatically based on the value set for the application propertyMobileBrowserAutoRefreshPeriod, which defaults to 60 seconds. A graphic display (actual page view) will refresh based on the property MobileBrowserSnapshotRefreshPeriod, which defaults to 600 seconds.

You can force the display to update at any time by touching the Refresh button. Note that each refresh of a graphic display may result in a significant amount of data being transferred to your device.

The MIC version of the page menu page

The word "Sites", found in the Remote Sites sub-menu, is controlled by the application property, ContainerTerm (ContainerTerm).

The alarm display of the Mobile Internet Client is limited to a maximum of the 100 most recent alarms and does not display alarms from previous days.

Realm Display Setup tags do not apply to mobile device connections.

Troubleshooting

  • No connection is made.
    • Ensure that you are providing a fully qualified domain name, beginning with HTTPS://. (HTTP:// if not secured.)
    • There may be issues related the configuration of your company's firewall. Check with your IT department.
  • It seems to create a connection, but access is denied.
    • You may not have Internet Access privileges. Check with your manager.
    Error messages: VTScada Thin Client Server Error Messages


Mobile Internet Client - Alarms Page

The Alarms page will show current alarms in the system. "Current" alarms are those that are either active (the condition that caused the alarm still exists), or unacknowledged.

Alarm display on the MIC

The alarm display of the Mobile Internet Client is limited to a maximum of the 100 most recent alarms. MobileBrowserAlarmHistoryMaxRecords, MobileBrowserAlarmHistoryTimeRange

Active alarms are indicated by a red dot. Unacknowledged alarms can be acknowledged by touching on the Ack button.

If your Developer has applied Realm Filtering, then the list will be restricted to those alarms that match the filter.

The text shown on each line is:

  • The description of the alarm tag. If no description is available, the name of the tag will be shown.
  • The alarm status (critical, high, etc.).
  • If the alarm is built into a Status tag type, the current value of the tag will be shown. Also, for Analog Status tags, the word "HIGH" or "LOW" will be shown to indicate which of the two alarms this is.
  • The time and date when the alarm was activated.

You can touch the History tab to view a history of the last 100 alarms recorded in the system. Note that this includes all alarms, including event-level operator actions.


Mobile Internet Client - Application Pages

Application pages can be viewed in either of two formats: A list designed for minimal bandwidth, or a graphic view of the application page, scaled to fit your device's display.

Toggle controls for the MIC display

To return to the main menu from any page, touch the VTScada logo at the top left corner of the display.

List View:

Optimized view, matching the following figure.

Tag values, as of the last browser-refresh, are shown to the right of each tag name. If a tag is in an alarm state, the value will be shown in red.

Graphic View:

Standard (graphic) view, matching the preceding figure.

The graphic view matching the preceding list view. (Taken from the Completed Tutorial Application.) All widgets are fully functional, but page hotboxes may not be visible on every device and touching a slider opens a data entry field rather than sliding the control to a new value. As with other MIC pages, this view is not updated continuously.

A touch on a widget in the graphic view will cause a dialog window to open. If the tag can be viewed in the HDV, a link will offer the option of opening a trend window. If a control tag is clicked, the window will provide an output control for that tag.

Updating a graphic view that contains many widgets can involve a significant data transfer to your mobile device.

In the list view, analog tags are indicated by a sine wave symbol. Digital tags are indicated by a square wave.

If the symbol is blue, the tag's values can be plotted. You can touch anywhere on the tag row to open a trend graph, just as you can click on a tag on a VTScada page to do the same. Touch a second tag to view multiple pens on the same graph. Each tag will be plotted in a different color, as indicated by a matching highlight color around the tag's row in the display.

Touch on the tag symbol a second time to remove the pen from the graph. When the last pen has been removed, the trend graph will close, or you can click the X at the top of the graph to close it immediately for all pens.

HDV trend graph in the MIC

In the graphic view, the trend graph works much like it would on a VTScada workstation. Touching a tag will open a full-screen trend graph. (You will be prompted as to whether you meant to open that graph.)

You can drag the graph left and right to change the displayed time period. If your device supports the "pinch" user interface, drag two fingers together or apart to change the scale of the display. Use the control at the top of the graph to display a time frame other than the default of one hour.

Controls at the top of the display allow you to change the amount of time displayed.


Mobile Internet Client - Application Control

You can use your Mobile Internet Client to change the value of Control and Output tag types (provided that your user account is authorized to do so).

Analog Output and Analog Control tag types will show a user interface similar to the following. This display is browser-specific - your device may show only a simple input field and not the up-down buttons.

Analog Controls

The current value, as of the last browser-refresh will be shown. Use the up and down arrows to select a new value to write or type directly into the data entry field. Touch the Set button when you are ready to write the value. This is done as a two-step process to minimize the chance of accidentally setting an incorrect value.

Note that, a slider control widget, when touched in the page view mode, will not actually slide, but will open a similar value input field.

Digital Output and Digital Control tag types will show a user interface similar to the following:

Digital Controls

Touch the On or Off button to write a 1 or a 0 to the tag. Note that this does not allow for a pulsed-type output. The mobile interface will write only a steady 1 or 0.

If the widget has been configured to prompt for confirmation, a dialog similar to the following will open:

Digital Control tag confirmation prompt

Depending on your device, you may also see a JavaScript confirmation prompt:

MIC JavaScript prompt


Mobile Internet Client - Site Pages

Some applications will have tags organized into hierarchies. These are used to group all the I/O tags within a pumping station, well or other component. A common example is the use of the MultiSmart tag or one of the MPE station tags.

If this is the case for your application, then the mobile browser interface will include a Sites(*) entry in the menu.

A sites list, as shown by the MIC

You can use this to browse into these tag hierarchies to view or control the various I/O tags within the structure. The following illustration is taken from the VTScada tutorial - the tags you see on your own screen will match the contents of your application.

(*) The word "Sites" is controlled by an application property, ContainerTerm (ContainerTerm).

A site details display, as shown by the MIC

Viewing a map may require a very large data transfer to your device.


Connect Using The VTScada Internet Client

An installed version of the VTScada Internet Client can be launched by most browsers or as a stand-alone application that you can launch from your desktop. With the release of version 12.1, Internet Explorer is no longer used.

URL format, assuming that you have enabled TLS/SSL security:
https://YourCompany.com/RealmName

You may be prompted to allow a pop-up and to trust content from Trihedral Engineering Limited. It is safe to do so.

The VTScada Internet Client (VIC) is not compatible across versions before and after 11.5 / 12.0. If connecting to an 11.5 / 12.0 server, you must use the 11.5 / 12.0 client. If using the 11.3 or earlier server, you must use a pre-11.5 client.
Clients will function, but symbols and certain characters will not display properly.

To connect:

  1. Start your favorite web browser.
  2. In the address field, provide the URL for your server and application.

Your manager or VTScada developer must provide this. It will be similar to:

https://vtsdemo.trihedral.com/exceldemo

  3. When prompted, enter your account name and password.
  4. Click OK.

To establish a connection within an isolated network , it may be required to deactivate the Certificate Revocation List (CRL) in your Windows settings. Depending on configuration, Windows may check the revocation status of a given client certificate when a secure network connection is being attempted. Without an internet connection, the verification process fails and the connection request is denied by default.

If the connection is authenticated, the first application in the realm will open in a new window. The original Internet Explorer window may be closed.

Upon connecting, the VTS Internet Client will identify and store your entire server list. On subsequent connections, it will automatically connect to the first available server.

Create a Shortcut

  1. Select Internet Explorer's system menu (upper left of the screen).
  2. Select Bookmark
  3. Save the bookmark to your desktop or other preferred location.

The bookmark will be saved as a shortcut file (*.LNK)

Creating a shortcut using the Bookmark tool creates a bookmark containing the list of redundant thin client servers. The thin client will attempt to connect to each one in turn.

Copies of the shortcut file can be distributed to users throughout your site.

Edit the Command Line to Modify Launch Behavior

The shortcut file contains the command used to launch the VIC. You can edit the command line in the shortcut to modify the launch behavior using the following configurable parameters.

These parameters can be used to auto-fill the username and password, connect to a specific realm, open on a specific page or display a parameterized page with an initial set of parameters.

Parameter | Name | Description
-s | url | URL of the VTScada system to make the initial connection to. In response, the VTScada system will provide the a set of "Connection Addresses" that the VIC will use to establish a session and provide fail-over. This can include the realm, application name or GUID, page name and parameters. e.g. "http://myscada.example.com/myrealm/MainApplication/WTP?Site=Local". Any URL components omitted will be defaulted, if possible.
-a | realm | Optional. The realm to connect to.
-n | username | The username to authenticate with.
-p | encrypted password | The encrypted password associated with the username. This parameter should not be manually specified. When a user saves a VIC shortcut including the password, the VIC encrypts the password in a manner that keys it to the current Windows user account and the computer. Therefore copying a shortcut containing an encrypted password to any other computer or a different user account won't work. You may choose between -p and the unencrypted option, -t if you wish to specify a password. If you don't specify a password, you will be prompted for one.

  1. Right-click the bookmark you've made following the steps in this topic.

  2. Select "Properties" and find the field "Target"

  3. Copy and paste the contents of "Target" into a word processor like Notepad. This step is optional, but it is much easier to see what you're working with, modify or add, and troubleshoot from notepad or your word processor of choice.

  4. Assess the target contents. You will notice that many command line parameters are already in use. In the following example, -s (URL), -a (Realm Name), -d (Page Name), and -o (Options) were auto generated with the bookmark. Notice how the value for each option is a string value, with "quote marks" on either end. If you wanted to change the page displayed on startup, you would modify -d (Page Name).

  5. Add new parameters. For example, To auto fill the username and password, you add those credentials to the target text like this:

  6. Copy and paste the modified target back into the target field. Apply the changes and test it out by using the bookmark.

If all of the mandatory parameters are met, clicking the bookmark will automatically launch the VIC without displaying a login dialog. These settings may be especially handy for a read-only workstation at a kiosk.

When launching the VTScada Internet Client from a shortcut, you can supply more than one server address, separated by a comma. If the first URL is not reachable, the VIC will attempt to connect with the next. You do not need to configure this in the properties target, as you would to modify launch behavior. You can add additional URLs in the VTScada Server Login dialog and "Save As..." to commit the change.

Troubleshooting:

Check that the add-in is enabled:

Open the Manage add-ons dialog from Internet Explorer

Enable the VT Class add-on

  • No connection. The message is "... cannot display the webpage"

1) There is no VTScada Thin Client Server at this URL. Ensure that the server is running and that you have typed the correct address.
2) Test for a conflict with your selected port by changing the thin client server configuration to use an alternate port number.

  • Error 403 = Request forbidden -- authorization will not help

There is a VTScada Thin Client Server at this address, but a properly-configured application is not available. Ensure that the realm includes an application, that the application is running, and that there is at least one security account with the Thin Client Access privilege.

  • The VIC session runs. The Establishing Connection dialog remains.

No user account has the Internet Connection privilege. Security must be enabled and at least one account must have the Thin Client Access privilege.

  • Error code 401 - No permission

Three failed attempts to logon have been made. Check with your VTScada manager to confirm your account permissions, and to confirm that you are connecting to the correct realm name for your account.


Syntax of Internet Client Requests

The following applies to any form of connection to a VIC server (not Mobile or Anywhere).

The address that you use to make the VIC Closed VTScada Internet Client. Allows you to connect to an application over the Internet with many of the features of a full VTScada workstation. connection is termed a Uniform Resource Locator (URL).

The general format of a URL is defined as:

{Protocol}Server{:Port}/Realm{/Verb}{/Page}{?Parameters}

where curly braces {} enclose optional components of the URL.

Forward slash (/) characters, the colon (:) character, and the question mark (?) character are to be typed as shown because they serve as delimiters between components of the URL. If an optional component is omitted, the delimiter immediately preceding it is also omitted.

URL Component | Description
Protocol | The {Protocol} component is optional when using a browser, but mandatory when using the VTSX program. If specified, it must be either of the following, according to whether you have configured secure connections. http:// or https://
Server | The Server component is mandatory, and specifies the name or IP address of the thin client server. The Server component may be as simple as just a host name, if operating over a company intranet, or it may take the form of a fully qualified host and domain name, if operating over a wide area network or the Internet.
:Port | If the server uses a port number other than the default of 80, then a colon and the configured port number must be provided.
Realm | The name used for a connection. If only one realm has been configured on the server, it will be found automatically, and therefore need not be included in the URL. If more than one realm exists, then you must specify the one you intend to connect to.


Command Parameters of Internet Client Requests

If any of the mandatory parametersare not provided, the user will be prompted to provide more information.

If you want the user to provide the username and password every time, do not supply those parameters.

Parameter | Name | Description
-s | url | URL of the VTScada system to make the initial connection to. In response, the VTScada system will provide the a set of "Connection Addresses" that the VIC will use to establish a session and provide fail-over. This can include the realm, application name or GUID, page name and parameters. e.g. "http://myscada.example.com/myrealm/MainApplication/WTP?Site=Local". Any URL components omitted will be defaulted, if possible.
-a | realm | Optional. The realm to connect to.
-n | username | The username to authenticate with.
-p | encrypted password | The encrypted password associated with the username. This parameter should not be manually specified. When a user saves a VIC shortcut including the password, the VIC encrypts the password in a manner that keys it to the current Windows user account and the computer. Therefore copying a shortcut containing an encrypted password to any other computer or a different user account won't work. You may choose between -p and the unencrypted option, -t if you wish to specify a password. If you don't specify a password, you will be prompted for one.


VTScada Thin Client Server Error Messages

The HTML server embedded within Thin Client Servers can generate error messages under certain conditions. All error messages are generated using the standard HTML error reporting method, giving an error number and explanatory text.

An example of an error response:

Error Code | Message
400 Protocol not "HTTP" or request header malformed.
PageList request issued for a non-VTScada application.
401

Any of:

  • Originating IP address is on a DENY list or is not on an ALLOW list.
  • AppsList request issued, but user not authenticated by the VTScada Security Manager.
  • PageList request issued, but user not authenticated by the VTScada Security Manager.
  • VTS-BIN request issued, but user not authenticated by the VTScada Security Manager.

Note:You may receive a 401 error code if no VTScada application is running (i.e. the VTScada Security Manager cannot authenticate against any user accounts), or if the application you are requesting is not running.

403 | This request would exceed the number of licensed connections.
404 GUID or application name in request specifies an unknown application.
A request was received for a file that could not be located.
500 | Unused.
501 | The HTTP request specified an unimplemented method (only "Get" is implemented).


The VIC Status Dialog

Whenever the VIC is not connected to a server, a status dialog is displayed, informing you what the VIC is attempting to do:

The activity text gives the reason that the dialog has been displayed. It can be one of the following:

  • Establishing initial connection -the VIC is attempting to establish the initial connection to a VTScada Thin Client Server.
  • Connection to server <servername> lost - the VIC has lost connection to its current server.
  • Higher priority server available - the VIC was maintaining communication with its current server when a higher-ranked server became available. This is only displayed in priority mode.
  • Application stopped on server <servername> - the operator stopped the application on the VTScada Thin Client Server, but VTScada continued to run.
  • Authentication failure - During a VIC session, the credentials of the user were changed and are no longer valid. This is a terminal condition.
  • Session signed out - During a VIC session, the user manually signed out or the SecurityManager inactivity timeout expired, causing the user to be forcibly signed out. This is a terminal condition.
  • Session terminated by operator - During a VIC session, the operator forcibly terminated the session, via the ICM. This is a terminal condition.
  • Change-over forced by operator - During a VIC session, the operator forced the VIC to changeover to its next best server.

The Connection Status Text tells you what the VIC is attempting to do. It can be one of the following:

  • Blank - The connection process has recently begun and the message has not yet been updated
  • Connecting to <servername> - the VIC is in the process of connecting to the named server.
  • Connected to <servername> - the VIC is now connected to the named server.
  • Waiting for an available server - none of the servers are contactable by the VIC. The VIC will continue to try to establish a connection.
  • Unable to continue. Please exit program. - a terminal condition has arisen and the VIC cannot continue.

The Status Icon can be one of three pictures:

  • An information icon - the status dialog is simply telling you something. The VIC is operating normally
  • A warning icon - the status dialog is advising you of a non-fatal (yet) problem.
  • An error icon - the status dialog is advising you of a serious problem, usually meaning that the VIC cannot operate.
  • The Close Button will dismiss the dialog. It can have one of two texts:
    • Close - Clicking the button will cause the dialog to simply close.
    • Exit Program - Clicking the button will cause the VIC to terminate.

Clicking the X button on the title bar of the status dialog has the same effect as clicking the Close Button.

  • The Activity Indicator animates when the VIC is attempting to establish a session with a server.
  • The Auto-Close check box, when selected, causes the dialog to dismiss automatically when the VIC is connected to a server. The dialog will always appear when the VIC is not connected to a server. The state of the check box is persisted in the registry and so is remembered even if a newer version of the VIC is downloaded from a VTScada Thin Client Server


Connect Using the VTSX Program

The VTSX program, provided with the VTScada installation as VICsetup.EXE, provides VIC Closed VTScada Internet Client. Allows you to connect to an application over the Internet with many of the features of a full VTScada workstation. access without the need for Microsoft Internet Explorer or any other program.

The default installation folder will be C:\Program Files (x86)\Trihedral\. You will probably want to create a desktop shortcut to the executable file, VTSX.EXE, but note that the user interface itself contains an option to create that shortcut for you. The steps are provided in the next topic.

Assuming that a VTScada Thin Client Server has been configured to make your application available over the Internet, then the connection process is as follows:

The VTScada Internet Client (VIC) is not compatible across versions before and after 11.5 / 12.0. If connecting to an 11.5 / 12.0 server, you must use the 11.5 / 12.0 client. If using the 11.3 or earlier server, you must use a pre-11.5 client.
Clients will function, but symbols and certain characters will not display properly.

  1. Run the VTSX program.

The VTScada Server Login dialog appears.

  2. Enter the Server address and realm name. The protocol portion, "HTTPS://" is optional.
    If not using a secured connection, you must use the protocol specification, "HTTP://"

For example: https://vtsdemo.trihedral.com/exceldemo

  3. Enter the username and password for an account that has been granted the Thin Client Access privilege.

The Connect button will be enabled.

  4. Click on Connect.

The "Establishing Server Connection" dialog will be displayed while the application opens on your computer. In the case that a connection cannot be made, an error dialog will be displayed to describe the source of the problem.

The Save As... button can be used to store a link to the VTSX program, including the server address, as a shortcut on your desktop. Double-click the shortcut to create a new connection to your application.

Optional items to include in the server address:

Page Name: Following the realm name, you might choose to include a page name. If so, add it following the realm.

Example: https://vtsdemo.trihedral.com/exceldemo/anywhere/alarm

Save a shortcut to the VTSX program.

To simplify the process of making future connections to a Thin Client Server, you can save the connection information as a shortcut on the desktop. Double-click on the shortcut to re-open the VTScada Server Sign-in dialog, preconfigured with the saved information.

To create the shortcut:

  1. Create the link file with URL & username (2) launch lnk file, type in username make connection, bookmark session - over writing lnk file. (3) launch lnk file from bookmarked session, enter password, and again save and overwrite lnk file.
  2. After filling in the connection information fields of the VTScada Server Login dialog, click the "Save As…" button.
  3. Launch the program by double-clicking the link.
  4. Type in your username to make the connection.
  5. Bookmark the session, overwriting the link file.
  6. Close the session.
  7. Launch again using the link.
  8. Enter your password.
  9. Save, again overwriting the link file.

You can edit the shortcut as required. In particular, some users might prefer to select a given server rather than allow the client to connect automatically to the first available from the defined server list. To do so, open the shortcut's properties dialog and select the Shortcut tab. In the Target string identify the -s parameter, which stores the server list.

Alternatively, you can create a VIC shortcut containing the client's full server list by accessing the system menu (i.e. the Windows menu that contains Move, Size, Minimize, Maximize, and Close) on the main VIC's window while connected and select the "Bookmark Page"

Copies of the shortcut file can be distributed to users throughout your site.

Security Notes for Saved Passwords

If you choose to save the password for your account in the shortcut file, then anyone who has access to your Windows account on this computer may access the application.

Passwords are saved using the standard Windows™ password caching policy. Under this policy, saved passwords are protected by the user authentication credentials for the Windows user account. That is, after a user has signed in to a workstation, any passwords saved for that user on that workstation are automatically filled in for dialog boxes requiring them. Password theft is mitigated by encrypting the stored passwords using a key unique to that user and that workstation. Any other user on that workstation cannot use saved passwords for another user on that workstation and cached encrypted passwords cannot be transferred to another workstation.

Troubleshooting

  • No connection is made.
    • Ensure that you are providing a fully qualified domain name, beginning with HTTPS://.
      Use HTTP:// if not using a secured connection.
    • There may be issues related the configuration of your company's firewall. Check with your IT department.
  • It seems to create a connection, but access is denied.
    • You may not have Internet Access privileges, or you may not be allowed to connect to the named realm. Check with your manager.


Uninstall the ActiveX Component

If you have installed the stand-alone VTSX program, there will be an Uninstall utility in the program folder. For example, "C:\Program Files\Trihedral\UNINSTAL.EXE". Run this program to uninstall the VTSX program. This removes only the VTSX ActiveX control, not the VTScada program if that is also installed on the computer.

If using Internet Explorer™, the process is somewhat more complicated. The Microsoft Internet Explorer Component Download does not provide automated support for uninstalling ActiveX components. To completely remove the ActiveX component from a VIC:

(Instructions and screens may vary by Windows™ version.)

  1. In Microsoft Internet Explorer, click "Tools" in the menu, and choose "Internet Options".

  2. Open the "Programs" tab.
  3. Click the Manage Add-ons button.
  4. Select the VTScada Class add-on from the list.

  5. Click the Disable button in the lower right of the dialog.
  6. Close the dialogs, applying your changes.


Monitor Internet Connections

Use the Thin Client Monitor to view active connections, disable or enable access to an application, send messages and slay connections. Technical details for each connection are displayed, and options exist to log connections and to diagnose problems.

There are two versions of Thin Client Monitor. The first is a script application, accessible from the VAM. The second is a page that is a standard part of all new applications.

There are two differences in the feature set of the two versions:

  • The application version will show all connections to all accessible applications. The page version will show only the connections to the application it is within.
  • The application version has a "pin on top" button, to ensure that it is not hidden behind other windows.

Thin Client Monitor display

If the Thin Client Monitor application does not appear in the VAM, you may have to add it. The application directory for the Thin Client Monitor application is named "BrowserMon" and is stored in the VTScada installation directory.

You can sort all the columns in ascending or descending order. Click on a column title to sort by that column - the first click will sort the rows in ascending order and the next will sort by descending order. An arrow appears beside the column title to indicate the sort order.

Controls:

Button | Function
Event Logging | Enables connection event logging. The output file is stored in the VTScada installation directory as "VICMonitorLog.txt". This file contains the logged data as comma-separated values.
Diagnostics Logging | Turns on diagnostic logging for subsequent VIC connections. Should you experience problems with your VIC connections, this log may help engineers at Trihedral Engineering Ltd. discover the source. Refer to notes within this topic.
Detail | Controls whether information is displayed for the Client IP, Bytes Transferred, Bytes Received and Compression Ratio columns. By default, detail is not displayed.
Daytime/Nighttime mode | Change the background to either white or black.
Slay Connection | Terminates the highlighted VIC session from the VTScada Thin Client Server.
Force Changeover | Force thin clients to disconnect from this server. If you have configured for Redundant VIC, the client will automatically connect to the next highest ranked available server as defined by the VTScada Thin Client Server List. An intended use for this button and the following one is to allow you to take the current server off-line for maintenance without interrupting any client sessions.
Send Message | Send a message to a selected connection, or to all connections.
Enable New Clients | Enable or disable new connections to this server. Note: Use of the Disable New Clients button while you are remotely connected is a risky thing to do. If your own connection is broken before you re-enable new client connections, you will have to travel to a VTScada workstation.
The following button is available only to the application version.
On Top | Available only to the script application. The Pin button enables you to set the Thin Client Monitor on top of all other windows.

Columns

Server Name | Because the Thin Client monitor displays information from all servers in the VTScada Thin Client Server cluster, it is important to know which server a particular client is connected to.
Client Name | The name of the computer that is viewing the application.
Application | The name of the VTScada application that is being viewed by each connection.
Realm | The name of the realm to which each client is connected.
UserName | The UserName column displays the name of the user account for each signed in user.
Page Name | The name of the page within the VTScada application that is being viewed (does not apply to script applications).
Page Information | Additional information about page may be displayed. A developer must code this information into the page's source code. For example, if the client is viewing the Historical Data Viewer page, the Page Information column will show which named pen group is being viewed. Page information is stored into a variable named "VICMonitorPageInfo", which is updated in the page's main state.
Session Time | The length of time that the session was connected.
Client Type | VIC, Mobile Client or Anywhere Client.
Client Version | The version of client viewer. Useful if the client is using an older VIC ActiveX utility.
Client IP Address | Displays the IP address corresponding to each connection. (Shown only when detail view is enabled)
Bytes Txd | The number of bytes transmitted from the server to the client. (Shown only when detail view is enabled)
Bytes Rxd | The number of bytes received by the server from the client. (Shown only when detail view is enabled)
Comp Ratio | The compression ratio (i.e. the percentage that data was compressed). (Shown only when detail view is enabled)
Ping Time | An approximation of the time (in milliseconds) taken to communicate between the server and the client. (Shown only when detail view is enabled)

Clicking the Diagnostics button will cause the VTScada Thin Client Name Filter dialog to open:

Thin Client Name Filter

Enter an asterisk, * to enable logging for all clients. If using the ActiveX Internet Client (VIC) the log file is named VICDiag.TXT and saved to the connected user’s My Documents directory.

If using the Anywhere client, this button will turn on communication diagnostics for Anywhere Client sessions that start after the option is turned on. (For existing sessions, refresh the browser.) These diagnostics are written out to the browser's Developer Tools Console, which is accessed in most browsers by pressing F12. From there, you can save the file to disk.

Android and IOS operating systems do not allow direct access to developer tools. The following links are provided for those interested in a work-around. Trihedral cannot guarantee that the instructions at those sites will work for your device.
General notes by Operating System:
Android: https://developer.chrome.com/docs/devtools/remote-debugging/
iOS: https://developer.apple.com/documentation/safari-developer-tools/inspecting-ios
Instructions by Browser:
Edge: https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/overview#open-devtools
Chrome: https://developer.chrome.com/docs/devtools/open
Safari: https://developer.apple.com/documentation/safari-developer-tools/inspecting-safari-macos
Firefox: https://firefox-source-docs.mozilla.org/devtools-user/

The Send Message dialog:

Select a connection before clicking the Send Message button to send that message to only one connection. Check the Broadcast to all box to send the message to all connections.

Data Logged by the Thin Client Monitor

Only one log file is maintained, regardless of how many backup servers have been configured. This file is located on the current primary server.

If change-over occurs to another server, two messages are recorded in the log: a Connection Closed message, followed by a Changeover message. The log will not show which server the client is connected to (or was disconnected from in the event of a change-over).

The following information is stored in the VICMonitorLog.txt file, which is located in the VTScada installation folder.

  • Time stamp, recorded as date and time.
  • The action that initiated the event being logged. Some of the possible actions include:
    • Connection Opened
    • Connection Closed
    • VIC changed servers ("change-over")
    • Page Changed
    • User Changed
  • GUID (Globally Unique Identifier) of the connection
  • IP address of the connected client
  • Number of bytes sent
  • Number of bytes received
  • Round trip time. The time required to send a packet of information from the server to the client and then receive a response packet back.
  • Connected client's computer name
  • The name of the application to which the client is connected
  • The name of the realm to which the client is connected
  • The name of the logged-in user
  • The current page being displayed on the connection.


The Oil & Gas Solutions Layer

With Trihedral’s Oil & Gas Solutions layer, you can build systems that handle process control SCADA information along with providing regulatory-compliant Electronic Flow Monitoring (EFM) systems for collection, storage, and reporting of custodial transfer data in a single application with no dependencies on third party software.

To begin, use the Advanced option of the Add New Applications Wizard to create a new application. In the Create New page of that process, ensure that the Type is set to Oil and Gas Solutions.

(Early versions of the Oil & Gas Solutions layer relied on a Driver Pack Layer. This is no longer the case. All required drivers are native to a standard VTScada installation. The Oil & Gas Solutions layer is protected so that it cannot be started. You must build your own application using this type, rather than work directly within that layer.)

Definitions

You will find the following acronyms throughout this document:

AER

Alberta Energy Regulator

AGA

American Gas Association

API

American Petroleum Institute

EFM

Electronic Flow Monitoring

ODBC

Open Database Connectivity

POC

Pump-Off Controller

PVR

Production Volume Reporting


Tag Types in Oil & Gas Solutions

The Oil & Gas Solutions layer consists of a number of specialized tag types designed to allow fast and easy configuration of industry specific applications using VTScada. While some of these tags are designed to be created directly by users, others are created automatically by other tag types and are not normally created by system users.

The following chart provides an outline of each of the custom tag types in the Oil & Gas Solutions layer. Those tag types in the left-hand column are major tag types, which are meant to be configured by users. Those in the second column are child tags that are typically configured automatically as part of one of the major tag structures.

Major Tag Type | Child Tag Type | Notes
Flow Computer | Provides a complete interface to a flow computer (a.k.a. EFM device) for logged data, alarms and events, and process data.
Meter Run*

Parent to a group of tags within the flow computer that represent a single meter/flow run. Logs all of the configuration information for the Flow Computer tags.

*It is a best practice to auto generate the first 11 Meter Run tags through the Flow Computer tag. Additional Meter Run tags can be created manually anywhere in the application.

Alarm and Event Log | Captures and logs alarms and events read from a Flow Computer
Driver Redirect | When used as a node in a tag tree, appears to be a driver to those tags underneath it. Actually, it redirects them to an existing driver somewhere else in the tree.
POC-Lufkin SAM Well Manager | Provides a complete interface to a Lufkin SAM pump-off controller for process data, alarms, setpoints and dynacards.
Dynacard Input | Stores Dynacard data from a pump-off controller, triggers reads of said data, and controls the look of that data on the Dynacard Graph page.
Dynacard Reference | Used to configure and manage the Dynacard Graph page as a whole.
Dynacard Upload Driver | Instructs a Modicon driver on the series of messages necessary to read Dynacard data from the pump-off controller.
PVR Report Definition | Referenced by a Flow Computer tag or other PVRSource to define the data (tags, values, text, etc.) that should appear in a PVR report run on that tag.
PVR Report Entity | Used to define the data which appears in a single row of a PVR report.
Filtered Tag List | If a PVR report is run against a Filtered Tag List tag, it will instead be run again all tags which match the filter.
PVR Report Line Item | Allows custom sites or other tags that weren't developed as an explicit PVRSource to be included in a PVR report.
TeleBUS Driver | Driver used to communicate using the TeleBUS protocol. This protocol may be used by RealFlo, among others.
Polling Control | Used in conjunction with a standard VTScada Polling Driver tag to provide increased options for poll scheduling and for on-demand polling.
Well Test | Enables the logging of a number of different tag values as a single well test record. This record can later be accepted or rejected, and optionally some of its values may be edited.
PLC Alarm | Enables the VTScada Alarm Manager to follow the state of a function or alarm block in a PLC.


Flow Computer Overview and Design

With Flow Computer Tags , Trihedral sought to develop an industry-specific solution with the following requirements in mind:

  • Single SCADA platform for process data and compliance data collection, storage, and reporting with no reliance on 3rd party software.
  • Compliance with Alberta Directive 17 requirements for custodial transfer data.
  • Common configuration user interface for several RTU/Flow Computer hardware platforms.
  • Common operator user interface for several RTU/Flow Computer hardware platforms.
  • Leverage all existing VTScada functionality to allow SCADA system integrators and operators to quickly and easily build SCADA systems to meet their specific needs.
  • Use standard VTScada drivers for efficient communication on limited bandwidth connections to field I/O devices.

The Flow Computer tag is the basic building block of the Oil & Gas Solutions approach to EFM devices. This tag allows a complete field I/O device (i.e. a flow computer) to be defined as a single tag. Every Flow Computer tag includes several child tags that perform the necessary device communication, data reading and logging for compliance data, as well as provide a means of defining the device-specific I/O tags used for process monitoring and control functions.

Which child tags are started and how they operate depends on the configuration of the Flow Computer tag.

The following figure shows how the Flow Computer meets these requirements.

Key points shown in this figure include:

  • A common I/O driver is used within VTScada for both operational process values and compliance reporting data.
  • For each I/O device (flow computer or RTU), the driver can use communication link options that include direct serial, TCP/IP, UDP/IP, cellular, TCP/IP to serial, etc.
    Multiple field I/O devices can use the same link, or multiple links can be deployed easily in a single application.
  • Tags that collect compliance data are built automatically based on the field I/O device in use. These tags log all collected data to the VTScada Historian, automatically on data change, using the same format that it is received from the I/O device. No scaling calculations or other manipulations are performed on the received data values.
  • SCADA system developers use standard VTScada tags to monitor process data. These tags are used to build the displays that operators use to interact with the process and can include standard VTScada tools for visualization and control, along with custom calculations to meet application specific needs.
  • The VTScada reporting engine is used to generate reports from the Historian. These can be tailor-made to the end user’s requirements.
    The Oil & Gas Solutions layer contains a number of reports specifically designed as industry compliance reports (CFX files for example) but all logged data, including process and compliance values, is readily available using a number of built-in VTScada report types.
    All Historian data is also available via the VTScada ODBC driver for report generation using 3ʳᵈ party reporting tools.

Flow Computer Tag Structure

The following figure shows the general structure of Flow Computer Tags , built automatically whenever they are created. Note that the structure will vary depending on configuration choices made while creating the parent tag. Also, you may choose to add your own tags within this structure to collect extra information. In the following diagram, A&E stands for Alarm & Event.

Communications Driver Tags

Four independent Polling Driver tags in combination with four independent I/O driver tags are created, based on the field I/O device selected when configuring the Flow Computer tag. The four independent drivers are created to allow custom polling schedules for each of the major types of data that the SCADA system will need to read from the remote devices:

  • Real-time process values
  • Alarm and event logs
  • Hourly history logs
  • Daily history logs

VTScada allows all four drivers to communicate with the same field I/O device over the same communication medium. Note that the Flow Computer tag also reads configuration data, and that this is usually done using the real-time process value driver tag using an ad-hoc read.

Alarm and Event Handler Tag

The Alarm & Event Handler tag is a layer-specific tag that is automatically started by Flow Computer tags as a child tag. Its role is to capture inbound alarm and event information (aka Audit Log or Audit Trail data) from the field I/O device that is read by the I/O Driver tag and to convert these device-specific messages into a common format for storage in the VTScada Historian. Once logged in the historian in this format, the alarm and event data can be reported in a device-independent manner using the VTScada reporting tools.

Notebook Tags

The Flow Computer tag automatically starts one or more Notebook tags; one for the device as a whole and one for each flow meter run that is configured within the device. These are standard VTScada Notebook tags and can be accessed, read, and reported on in the same way as any Notebook tag.

Process Data Tag

The Process Data tag is a standard Context tag that is a direct child of the Flow Computer tag. It is used as a container for any process Analog Status or Digital Status tags that are not associated with a particular meter run (e.g. RTU battery life). Just by creating an Analog Status or digital Status tag as a child of the Process Data tag, that tag will automatically find the correct driver tag and will use the standard process polling cycle.

Meter Run #1 through Meter Run #11 tags

Meter Run tags can be manually created anywhere in your application and configured however you prefer from there. The Flow Computer Tags offers a centralized interface to manage your first 11 Meter Run tags from one place with some automatic configuration options.

The Meter Run tags are Oil & Gas Solutions tags that provide three distinct functions:

  • Provide a container to hold hourly logs, daily logs, and process values
  • Provide a user interface to change commonly adjusted configuration settings for the flow meter run
  • Provide the tools to accept and store the meter run configuration values from the field I/O device

The first of these is accomplished using the standard container features of VTScada – it treats all log tags and process tags as its children.

For the second function, user interface for configuration, a standard device configuration display is available to allow users to adjust several settings for the flow meter run, including the gas compositions.

For the third function, RTU configuration data, the Meter Run tags capture all details of the flow meter run from the RTU and log this data to the VTScada Historian. Reading and logging of this data may be triggered by three actions:

  • Timed update interval (typically in days)
  • User-initiated read of the data
  • On events received from the field I/O device that may indicate changes in the field to the device’s configuration

Refer to RTU Configuration Log Format for details on the format of the meter run configuration logs produced by this tag. The format will need to be understood if you are using the ODBC interface to generate reports of device flow meter run configuration.

Daily and Hourly Tags

These two children of the Meter Run tag are standard VTScada Context tags used to group together the individual hourly and daily Analog Status tags, which are used to capture compliance reporting data logs from the RTU or flow computer. Some of these Analog Status tags are started automatically as child tags of the Meter Run tags based on the configuration of the individual meter runs in the Flow Computer – refer to section Flow Computer Tags for details on configuring the flow meter runs in the Flow Computer tag. An address entered in the relevant field in that configuration folder is what determines whether the associated daily/hourly history tag is started or not. Additional user-defined tags may be added to capture further historical data, as long as they are added under the ‘Hourly’ or the ‘Daily’ context.

Note that the daily and hourly log tags are not started unless required. For example, if meter runs #1 and #4 are configured in a Flow Computer tag then only the hourly and daily log tags for flow meter runs #1 and #4 will be started. This helps to reduce the tag count by not starting I/O tags for flow meter runs that are not used in the field I/O device.

Process Tag

The Process tag, a child of the Meter Run tag, is a device-specific “Driver Redirect” tag that provides the following two functions:

  • Acts as a container tag for all process data tags related to the meter run – these are configured as child tags of the Process tag
  • Performs the proper linking of the process data to the poll driver required for reading and writing of process tags

By default, several Analog Status tags are configured as child tags within the Process context. Users can add additional status tags that are associated with a particular flow meter run by adding them as children within the Process context.

As mentioned above, if additional status tags need to be added to the application that are not part of a specific meter run, these tags can be added directly as children of to the main Process Data tag instead.

Data Logging

Compliance Data Recording

All I/O tags configured as part of Flow Computer Tags are automatically logged to the VTScada Historian. The Compliance Data consists of several components that are recorded to the VTScada Historian in different ways:

Information | Recording
Alarms & Events | Log all received alarms and events
RTU Configuration | Log whenever data received (manual, timed, or event driven)
Hourly/Daily History Readings | Log all received readings regardless of value change magnitude

Process Data Recording

All process data tags configured automatically by the Flow Computer tag, as well as those configured by the user, are recorded to the VTScada Historian using the standard mechanisms for these tags. In short:

Tag Type | Recording
I/O and Calculation | Recorded on change of value that exceeds the tag’s deadband amount
Analog Status | Recorded on change of value that exceeds the tag’s deadband amount
Digital Status | Recorded on change
Drivers Statistics | Recorded as per VTScada standards for driver data logging
Calculation | Recorded on change of value that exceeds the tag’s deadband amount
All Others | Recorded on a timed basis only when a Logger tag is attached to the calculation

Compliance Reporting

The Oil & Gas Solutions layer records and reports data in a way that is compliant with major oil and gas industry specifications for custodial transfer data. The following sections demonstrate how the Oil & Gas Solutions layer meets these requirements.

AER Directive 017: Measurement Requirements for Oil and Gas Operations, section 14.11 Records, outlines a number of records that must be kept for all metering equipment. These reports include

Section # | D017 Report Requirement | Addressed in Oil & Gas Solutions via
14.11.1 | The Daily Report | Hourly Log Tags
14.11.2 | The Monthly Report | Daily Log Tags
14.11.3 | The Event Log | Alarm and Event Tag Log
14.11.5 | The Daily Report (EFM specific) | Hourly Log Tags
14.11.6 | The Meter Report (EFM Specific) | Daily Log Tags
14.11.7 | The Alarm Log (EFM Specific) | Alarm and Event Tag Log

PVR Reporting

Settings in the Meter Run tag allow your site to be easily linked to a PVR Report for customized data reporting.

See Meter Run Tags

RTU & Flow Computer Compatibility

Flow Computer Tags will work with Flow Computers and RTUs from several manufacturers using different communication protocols. The currently supported devices include

Manufacturer | Device | Protocol
Fisher | FloBoss 103 | ROC*
Fisher | FloBoss 107 | ROC*
Fisher | FloBoss 407 | ROC
Fisher | ROC300 | ROC
Fisher | ROC800 | ROC/ROC+
Schneider Electric | RealFlo on SCADAPack RTUs | Enron Modbus, TeleBUS
Semaphore | TFlo on TBox RTUs | Enron Modbus
CalScan | DCR-1000 | Enron Modbus
CalScan | Hawk 9500 | Enron Modbus
ABB | Totalflow | Totalflow**
Bristol | ControlWave | IBP
Bristol | 33XX Series | BSAP

* Note that FloBoss 103 and 107 units also support ROCNOC and Emerson’s Well Optimization Manager/Surface Control Manager products.

**Note that the Totalflow driver will only work in conjunction with the QCSI VTScada Helper Service from Quintessential Computing Ltd. Please contact Quintessential or Trihedral for more information.

New devices can be added.


Flow Computer Displays

The Flow Computer tag creates its own display dialog allowing users to view most aspects of the device on a single page. The same dialog is used for the display of all Flow Computer tags, with specifics changing to meet the configuration of the individual Flow Computer tag.

Sample shows the Meter Run Display tab selected.

The display includes four areas:

Communications

(Upper left) Displays communication statistics for the site. The Fast Poll button will trigger immediate reading of all process data (but not history, alarms, events or configuration data).
(Note to developers: This section of the display is also known as a "Flow Computer Device Summary".)

Notes

(Lower left) Displays operator notes for the site. Users with the appropriate privileges can add notes as required.

Alarms

(Lower right) Displays the current process alarms for the site. Note that these are the alarms generated by VTScada based on the user-added process tags, not the alarms from the RTU’s Alarm & Event logs.

Site Data Window

(Upper right) Displays the data and mapping for the site in several formats. This display allows you to display information common to the entire flow computer or display data for each individual meter run.

This section of the display includes several tabs, each with its own components, as described in the following sections.

Meter Runs tag Display Tab

In the sample image at the beginning of this topic, the Run 1 tab is selected, showing the Meter Run component of the page. A tab will be available for each Meter Run within your Flow Meter. This display includes a number of tabs, as follows:

Process / Custom Tab

The process display shows a number of the automatically configured process Analog Status tags in numeric, bar graph, and trend format. If a custom page has been selected in the Meter Displays tab of the Flow Computer tag’s configuration folder then that custom page will appear in place of the standard Process Tab.

Configuration Tab

The configuration display allows users to view and update a number of commonly changed meter run specific configuration settings. Provided that the user has sufficient privileges to make these changes, the values may be edited directly and saved to the RTU using the “Write” button. When editing, any value changed by the user is highlighted in green until written to the field I/O device using the Write button. At any time, the display may be updated from the field I/O device by clicking on the “Refresh” button.

This figure shows a device configuration. Note that the gas Composition section MUST balance out to 100.00% before it can be written to the device. If not balanced, the “Write” button will not be enabled and the “Gas Total” value will display in orange instead of white as shown in the following example:

If you would like to put a similar limitation on your Beta ratio, you can edit the high and low limits using the application settings OGBetaRatioHigh and OGBetaRatioLow.

Closing the window or switching to another tab at any time abandons the current set of edited values and will NOT write them to the field I/O device.

Importing Gas Composition Lab Results from a CSV File

There are several different labs that will analyze a sample from a well and provide a CSV file with its composition. VTScada allows you to import the data from CSV files using the controls of the bottom of the Configuration tab. (Refer to the preceding figure.) Note the droplist, which provides a choice of file formats to import. Each lab formats their files slightly differently, and VTScada needs to know which format to use in order to properly extract the information.

After a format has been selected, press the “Select File” button to choose the file to read. Pressing the “Import” button will read the file and fill in the appropriate fields on the screen, but the data will not be written back to the flow computer until the “Write” button has been pressed.

Alarms, Events, Hourly Values and Daily Values Tabs

These tabs are similar to the Reports discussed above, except that they show only the data relevant to this particular meter run and not to the flow computer as a whole.

Notes

Similar to the flow computer’s notes tab discussed above, you can add notes specific to each meter run as well.

Disabling Meter Tabs

Meter tab visibility can be toggled on a tag by tag basis, or globally, affecting all Flow Computer tags. Adding the following properties to the application will allow control of which meter tabs are visible across all Flow Computer tags in the application:

  • All-OGFCDisableProcessTab
  • All-OGFCDisableConfigTab
  • All-OGFCDisableAlarmsTab
  • All-OGFCDisableEventsTab
  • All-OGFCDisableHourlyTab
  • All-OGFCDisableDailyTab
  • All-OGFCDisableNotesTab

Setting the value of these properties to 1 will cause the associated tab to be hidden. Setting the value to 0 will cause the associated tab to be displayed.

Tab visibility can also be controlled on a tag by tag basis by replacing the characters “All” in the previously listed property names with a specific meter tag name. Any meter-specific setting will override the global “All” setting. Any space characters “ “ in the tag name must be replace by an underscore “_” character. For example, to disable the process tab for “ROC Com 1\Site1\Meter 1” meter tag, a property named “ROC_Com_1\Site_1\Meter_1-OGFCDisableProcessTab” must be added to the application and its value set to 1.


POC-DV8 Overview

To navigate to this page, draw a POC-DV8 tag as a Site Icon. Operators can click that to open the page.

The overview page displays a lot of information from the DV8 controller. You can manually poll for fresh data and add or view notes.


Lab Data Import Page

This is a pop-up page that you can use to import a Lab Result CSV file.

Each lab formats their files slightly differently, and VTScada needs to know which format to use in order to properly extract the information.

Use the drop-down list to select the correct format for your file.

After a format has been selected, press the “Select File” button to choose the file to read. Pressing the “Import” button will read the file and fill in the appropriate fields on the screen, but the data will not be written back to the flow computer until the “Write” button has been pressed.

After the file has been loaded, the "Select" buttons will allow you to choose the Meter Run tag to be associated with each line of data.

You will be prompted to confirm the action before the values are written.


Weatherford Overview

To navigate to this page, draw a Weatherford tag as a Site Icon. Operators can click that to open the page.


Flow Computer Application Properties

The following properties are relevant to your Flow Computer configuration:

Setting Name | Default | Description
OGBetaRatioHigh | 1 | High end of the acceptable beta ratio range
OGBetaRatioLow | 0 | Low end of the acceptable beta ratio range
OGFastPollDefaultActive | 0 | Flag - True to automatically activate fast polling when a well's details page is opened
OGFastPollInterval | 1 | Polling interval in seconds when fast poll is active
OGFastPollPersistent | 0 | Flag - True to continue fast polling after leaving the well's details page
OGGasCompDeadband | 0.00001 | Error allowed on either side of 100% when totaling gas compositions for writing to the RTU
OGGasCompDisplayDefault | 0 | Gas Composition default display units - 0:Percentage, 1:Mole Fractions
OGGasCompNumDecPlaces | 2 | Number of decimal places in Gas Composition configuration tab
OGHideGasComps | 0 | Flag - True to hide gas compositions from the configuration screen
OGHideHeatingVal | 0 | Flag - True to hide heating value from the configuration screen
OGHideOrificeInfo | 0 | Flag - True to hide orifice information from the configuration screen
OGHidePipeInfo | 0 | Flag - True to hide pipe information from the configuration screen
OGHideSpecGrav | 0 | Flag - True to hide specific gravity from the configuration screen
OGHideViscosity | 0 | Flag - True to hide viscosity from the configuration screen
OGMinimumColWidth | 60 | Minimum pixel width of columns on alarm/event/history page gridlist
OGReadMeterConfigOnPageOpen | 0 | Flag - True to automatically read configuration values when site details configuration tab is opened


Customize Your Flow Computer Tags

Some applications will be able to use tags like the Flow Computer or the SAM Well Manager as provided. Other system designers prefer to have finer control over which tags are read from the device. Often, once these changes are made, the same setup will be used again for different sites. In these cases, it is recommended that the Flow Computer or SAM tag be created underneath a Context tag which is made into a custom tag type. For more information about this process, refer to Automated Tag Configuration and Design Your Own Tags.

The following describes modifications to the Flow Computer tag that can be done outside of the tag’s configuration folder.

Reading Additional History Log Addresses

Analog Status tags representing the daily and hourly history logs can be configured while working within the Flow Computer tag’s configuration folder. If you will need to run FloCal CFX reports then you must configure your tags there.

You may want to add additional Analog Status tags to capture elements of the history log that are not listed as options in the configuration folder. You can do this by adding tags directly to the appropriate Meter Run tag’s Hourly or Daily contexts as shown here:

Take care to specify the I/O address using the Historical Address field rather than the standard Address field – this allows them to retrieve time-stamped data along with the other history values.

Any tags added in this way will be polled on the same schedule as all of the other history tags. They will also be included in any of the Daily/Hourly history reports or summary pages, but will not be included in FloCal CFX reports.

Reading Additional Process Data

All standard well configuration data required by Alberta’s Directive 17 is automatically collected and stored by the Meter Run tags. However, you may wish to read or write additional information from the device such as process information (for example, “Last Month’s Total) or system setpoints. These tags can be added, either to the Meter Run tag’s Process context if they are run-specific, or to the Flow Computer’s Process Data context if they are related to information that affects the flow computer.

Tags may be placed directly under these context tags or, if there are a lot of tags to read, further divided into child contexts for the sake of organization. Any tags that are placed on the tree below the Process or the Process Data tags will be polled using the Flow Computer’s Process Data poll rate.


CSV Override Files for Flow Computers

In addition to the Flow Computer Tags child tags, which read in all of the history and process data, the flow computer also collects configuration records. These configuration records, which include gas composition and pipe orifice details, are logged to the VTScada historian as a single entry by the Meter Run tag.

Every flow computer device type selection has its own specific address mapping that tells the flow computer tag how to read that device. This usually happens automatically when configuring a flow computer tag. However, if you have a custom program in your flow computer or if you are using a device that is not officially supported by the flow computer tag (for example, one that uses a generic protocol like Enron Modbus) you may need to make changes, as follows.

Types of Override Files

There are three types of override files, which must be used in conjunction with one another: the configuration override file, the read definition file and the write definition file.The fourth override file, the CFX Mapping Override, is only important if you plan to use VTScada's CFX report to generate Flow-Cal CFX files.

The configuration override file is the master map of all configuration addresses within the RTU. It details the address of each piece of information for every potential meter run number, as well as the units that should be used in association with that information. In addition, you can add in alarm messages associated with error codes that are read from the alarm and event logs.

The read override file contains instructions for how the individual read messages should be configured, as defined by a starting address and by the number of registers to read starting from that address. These blocks of addresses must encompass every meter run address that is defined in the configuration file.

The write override file is structured similarly to the read file; however, it does not have the same requirement that every meter run address from the configuration file be accounted for.

Adding an Override File to your Application

Override files are imported on the I/O Device tab of the Flow Computer tag’s configuration folder, by selecting the appropriate ‘Browse’ button. When selecting an override file, it does not matter which directory your file is in. As soon as you select the file, a copy is made and placed in a directory under your application called CSV_Overrides (e.g. C:\VTScada\MyApp\CSV_Overrides\MyFileName.CSV). This file is also added to your application as a permanent part of the repository, meaning it will automatically be shared between servers and will be included in any ChangeSets of the application. Any further updates to these files should be imported like any other application changes so that the changes can be passed around to all of the other potential servers.

Building a Configuration Override File

We recommend that you start your configuration file with the template provided within the Oil & Gas Solutions layer (C:\VTScada\Oil&GasSolutions\BuildInfo\ConfigurationTemplate.CSV). For a completed example, refer to the Bristol Controlwave file that is shipped as part of the Oil & Gas Solutions layer in the CSV_Overrides directory (e.g. C:\VTScada\Oil&GasSolutions\CSV_Overrides\Bristol_CWave_Config.CSV). The following descriptions refer to both the template and to the completed file.

Configuration Template Columns

MeterRunVarNum

This is an internal variable used by VTScada code and must be unique for each entry. This value should not be changed for any of the 372 rows that are included in the template. When adding additional rows for the purposes of adding alarm messages (more details in the alarm messages section below) the number in this column can be anything, provided it is unique.

MeterRunVarName

Another internal variable used when logging history records, this field should not be changed. When adding additional rows for alarm messages this can be left blank.

Description

A basic text description used to help identify the variable. This is purely for the benefit of the person editing this file and is not used by VTScada.

AlarmEventText

When alarms or events are reported by the RTU they are associated with a single address. The flow computer tag will look for that address in this configuration file, and if it is found then the text in the associated Alarm-EventText field is what will be saved as the alarm description.

UsedOnMeterConfigTab

All entries that have a 1 in this column will be user-editable on the meter configuration tab, assuming that an address is provided for that meter run. This field is not read by VTScada and is strictly for the information of the person building this configuration file.

UsedInCFX

All entries that have a 1 in this column will be included in any CFX reports that are generated based on this flow computer. This field is not read by VTScada and is strictly for the information of the person building this configuration file.

RunXAddress

The address of this entry for the given meter run. This address should be provided in the same format that you would use if you were entering it into the address field of an analog status tag.

GeneralAddress

The address of this entry if it is not associated with a particular meter run. These are most often used for general alarms and events; for example, there may be an alarm that gets generated by the RTU when it shuts down or boots up.

Droplist

This column is currently only used by two entries: 028_PipeMaterial and 031_OrificeMaterial. It maps the values sent back from the RTU to the droplist selections for those variables on the meter configuration tab. The con-tents of the field should be the droplist selections, separated by a semicolon, ordered based on their numerical value (starting from zero). For example, in RealFlo the three possible pipe materials are Stainless Steel (0), Monel (1), and Carbon Steel (2). The droplist field for such an entry should read:

Stainless Steel;Monel;Carbon Steel

In some cases, the values for the drop list entries may not be the standard 0, 1, 2, etc. In these cases the value associated with each entry may be entered alongside the label, seperated by a "|" character, as shown below:

Stainless Steel|9.61;Monel|7.72;Carbon Steel|6.2

Units

The units in this column will be shown on the meter configuration tab.

If you are adding more than 11 Meter Run tags there is an important configuration note for ConfigurationTemplate.csv. You cannot change the template by inserting columns Run12Addr, Run13Addr and so forth immediately to the right of Run11Addr. You must place these columns on the end-- to the right of the Units column. The column letter matters to this template.

Customizing Alarm Messages

When an event is read from the RTU’s alarm and event log, the RTU provides the register, or address, that is associated with that event. When VTScada logs this data for screen display and reporting, it takes that address and looks it up in an internal mapping table to see whether we know what that alarm/event represents. If the address can’t be found in the table, the alarm/event is still logged but the associated message is set to “Unknown”.

If you are entering a custom set of configuration addresses you will also need to provide the alarm/event message mapping. Many of the messages will be covered by the variables in the template; for example, if the orifice material is changed in one of the meter runs then the address passed back from the RTU will usually be one listed next to the 031_OrificeMaterial entry. However, some alarms/events are not associated with a particular meter run variable. These messages will need to be added explicitly, at the end of the configuration CSV. Some examples are shown in the following figure.

Note that for these alarm messages only three fields are important.

  • MeterRunVarNum can be set to any value, but must be unique. In this example we started numbering the events at 10001, but this was an arbitrary choice.
  • AlarmEventMessage contains the text that should go into the alarm record.
  • The GeneralAddress column contains the address that should be associated with this text. An address (or ad-dresses) could also be placed in any of the other RunXAddress columns in addition to or in place of the GeneralAddress column.

Building a Read Override File

The Read Override File, based on ReadParmTemplate.CSV, is used to define the read messages that VTScada will use to retrieve all of the variables defined in the Configuration Override File. Please note that every address that is defined in the configuration file must be captured as part of the messages in this read file.

Read Template Columns

  • RunXStart – The first address in the request message.
  • RunXQuantity – The number of addresses to ask for in the request message.

If your addresses are numeric, like the Enron Modbus addresses in the RealFlo example below, then it is usually more efficient to ask for larger blocks of addresses at a time. Be careful not to exceed the maximum number of addresses that can be returned in a single message. Some knowledge of the message protocol may be required.

Some protocols may use text addressing, and in these cases VTScada is unable to define a numeric block in the usual way. In these cases, such as in the Bristol ControlWave example that follows, the quantity field must be set to 1 for each of the reads. This is not efficient, but this information is read infrequently and this is the only way to include all of the addresses.

Building a Write Override File

The Write Override File, based on WriteParmTemplate.CSV, is structured identically to the Read Override File. Unlike the read file, however, the write file need not include every address from the configuration file. Instead, this file need only include the parameters that may be changed by the user on the meter configuration tab, shown following:

RunXStart

The first address in the request message.

RunXQuantity

The number of addresses to ask for in the request message.

ReadParmTemplate and WriteParmTemplate can be expanded following the current pattern to have more run numbers supported. The column letter and order matters so it is important to follow the current pattern when adding new meter runs.


Customize the Flow Computer Site Dialog

Adding a Custom Well Page

You may wish to add a tab to your flow computer site dialog that leads to a custom page that you have built to represent your well as a whole. The first step is to build the page using the VTScada Idea Studio. Once the page is completed, open the Flow Computer tag’s configuration folder and click on the Misc. tab. The Page to Display in Custom Tab parameter allows you to select the page that you just created. The Custom Tab Label parameter allows you to give a label to the tab that will bring up that page. When a custom page has been selected in this way, the site dialog will show the extra tab as seen in the following figure:

Creating a Parameterized Page

This section details only aspects that are unique to creating a parameterized page (Parameterized Pages) for use in the flow computer site dialog.

When you load the custom page from within the flow computer site dialog, that page is passed a single parameter: the Flow Computer tag. For this reason, when you build the page you should include only one parameter and that parameter should be a Flow Computer tag object.

When adding a widget to the page, you cannot use the Link option to connect it to a tag. Referring to the following figure, the procedure is to open the properties dialog, select the tag parameter and then navigate to one of Flow Computer’s child tags as shown:

Adding a Custom Meter Run Page

By default, there is a Process tab created for each meter run, which shows a few basic values. You may wish to replace the page on this tab with one of your own. The first step is to build a parameterized page(Parameterized Pages) using the VTScada Idea Studio. Once the page is completed, open the Flow Computer tag’s configuration folder and click on the Meter Displays tab. For each meter that you have configured you can select a custom page and a custom label for that page. When a custom page has been selected in this way, the site dialog will show the new tab as shown in the following figure:

Removing Tabs from the Flow Computer Site Dialog

If your flow computer is being used to measure liquids then it doesn’t make any sense to show the default Configuration tab that includes the gas composition information. If you would like to remove the Configuration tab for a particular well, this can be done by checking the Hide Gas Configuration box under the Misc. tab of the Flow Computer tag’s configuration folder.

Although they don’t have a dedicated check box, all of the other tabs can be hidden as well on either a system-wide or on a well-by-well basis. Refer to Disabling Meter Tabs.

Replacing the Flow Computer Site Dialog

You may not want to use the standard flow computer site dialog at all, but would instead like your own page to be displayed after selecting a Flow Computer tag from the sites page. In this case, you should select your custom page using the Standard Site Dialog Override drop list under the Misc. tab of the Flow Computer tag’s configuration folder.


Importing Multiple Gas Well Lab Results Files

The process to import individual gas compositions from a lab results CSV file is described in Importing Gas Composition Lab Results from a CSV File.

Some users may want to automate this process rather than uploading file manually. By using the process described in this topic, you can instruct VTScada to read any file placed in a particular directory on the server, uploading the gas configuration results from that file into the appropriate flow computer devices. A report is logged each time this takes place, and you can also configure the system to send an email containing the report to any interested parties.

Workflow Overview

One directory on your system must be designated as the source directory for the lab results CSV files. By default, the system looks for a directory called “Lab Results” within your application’s Data directory (e.g. C:\VTScada\MyAppName\Data\Lab Results). If you wish to use this service you must create this directory. If using an alternative location, you must edit the path stored in the OGLabImportDir application setting.

VTScada scans the specified directory every 10 seconds. If any files are detected in the directory, they will be read. Any gas composition entries that match one of the meter runs in the application will be written immediately to the appropriate flow computer. All of the files that were read will be moved from the source directory to an archive directory, or deleted if you prefer.

Reports

Each time a file is read, whether the read was successful or not, all actions taken are logged. By default, these logs are placed within an “Archive” directory underneath Lab Results (e.g. C:\VTScada\MyAppName\Data\Lab Results\Archive) but this can be changed to a different location using the OGLabImportLogDir application setting. The log files, as well as the archived copies of the original CSV files, are sorted by year and month. If more than one import is done in a day, the log will be appended to the end of the existing daily log file.

Optionally, a copy of the log file (or a shorter summary) can be emailed to any interested recipients. This email can be enabled using the OGEmailLabImportResults application setting, and the destination addresses can be configured using the OGGasCompReportEmail setting (multiple addresses should be separated by the “;” character). An email server must be configured, as described in Email Configuration for Alarms and Reports

Linking Meter Run Tags to the Lab Results

As described in Meter Run Tags , each meter run tag can be configured with three pieces of information relating to lab results: a file name, a file type, and a unique ID key.

The file name is used to link a meter run tag with its proper lab result during an import. When a file is detected in the source directory, VTScada tries to match its file name to the file name specified in each meter run. To allow for some variance in the lab file names, such as an optional date stamp, the meter run’s string need only match part of the actual file name. If, for example, the actual file name is “OAS Chart System 06082017.csv”, entering “OAS Chart System” or simply “OAS” in the meter run’s string would be enough to create a match. This matching is not case sensitive.

The file type is selected from a droplist of all of the currently supported lab results formats. When a file is found whose name matches what a meter run is looking for, VTScada will then analyze it based on the format chosen in this parameter.

These lab reports frequently contain more than one meter run’s worth of data. For this reason, each file type has one of its columns designated as a unique ID or key field. In order for the gas composition results to be uploaded to the flow computer, the value in this unique ID / key field must exactly match the Unique ID Key value that was used when configuring the meter runs. Refer to the following table for more information on the unique ID key fields for the various lab result formats. Any entries in the lab results that do not match one of the meter runs in the system are simply ignored.

File Type | Unique ID Key Column Number | Unique ID Key Column Name
AGAT | 3 | Sample Point Name
Cygnet | 3 | ProTrend_MeterCode
MaxxLink Common | (Row) 16 | Tag ID
Netflow | 2 | Meter Code
OAS Chart | 2 | Meter ID
ProChart | 3 | Sample Point
PVR | 3 | Sample Point
PVR FDC | 5 | ProTrend Meter Code

Application Configuration Settings for Importing Multiple Gas Well Lab Results Files

Setting Name | Default | Description
OGArchiveLabResultsFiles | 1 | Flag - True to archive a copy of the gas composition lab result CSV files after the data has been imported (instead of deleting them)
OGEmailLabImportResults | 0 | Flag - True to email a copy of the gas composition lab import results (in addition to saving a local copy)
OGEmailSummaryResultsOnly | 0 | Flag - True to limit the gas composition import results that are sent via email to a summary
OGGasCompReportEmail |  | Email address that the gas composition lab import results are sent to
OGLabImportCheckPeriod | 10 | Rate in seconds at which to check for new gas composition lab results
OGLabImportDir | AppPath\Data\Lab Results | Directory to monitor for new gas composition lab results
OGLabImportLogDir | AppPath\Data\Lab Results\Archive | Directory in which to place the log files detailing what was done by the gas composition lab results import


Production Volume Reporting (PVR) Process

Several tags are used when defining a PVR report. Some are created automatically, some must be created manually, and some that are created automatically must be configured manually. The process is as follows:

The data for a Production Volume Report comes from the Meter Run Tags within your Flow Computer Tags . Begin by creating a Flow Computer tag and use the tools within it to create that Meter Run tags that will monitor your system.

The structure of a PVR report (that is, the selection of columns of data to display) is defined by PVR Report Entity Tag, which are created automatically when you create and define PVR Report Definition Tags. While the PVR Report Definition tags are created automatically, each must be configured manually. Up to 20 columns may be defined in any definition tag.

Meter Run tags are matched to PVR Entity tags using the Flow Computer Tags of the Flow computer tag. When you run the report, using either the Reports Page or Report Tags, data from the Meter Run tags is extracted and displayed according to the PVR Report Entity tag to which it is linked. Note that for any meter run / report entity match you create, you have further control to select which columns defined in the entity should be used for the matching meter run within the report.

Expressing this as a series of steps, you would do the following.
(Detailed information for configuration referred to in the steps can be found in the topics describing each of the tags referred to.)

  1. Create and configure a Flow Computer tag, and within it the Meter Run tags.
    Do not configure the PVR Reporting tab of the Flow Computer tag at this step.
  2. Create a PVR Report Definition tag, and within it select the number of PVR Report Entity tags you plan to use.
    If all rows in the report will contain exactly the same set of columns, you need create only one PVR Report Entity tag.
    If one section of the report will have a selection of data columns, and another will have a different selection, create two.
    You can have up to 20 PVR Report Entity tags within a PVR Report Definition tag.
  3. For each PVR Report Entity tag, open the PVR Report Entity properties Entity Parameters tab and define the columns to be created for this entity's row.
    As you work, make a note of which columns (by number) contain what information. You will need this later.
    You will have an option later to select which of these columns to use for any meter run being matched to this report entity.
  4. Return to the Flow Computer tag and open the PVR Report tab.
  5. For each meter in this flow computer, select the PVR Report Entity tag that defines which columns to display.
  6. For each of the matches made in the previous step, select the columns to be displayed for that meter.
  7. Save your tag configurations.
  8. To run the report, open the VTScada Reports page and select Oil/Gas PVR Report as the report type.
  9. Select one or more Flow Computers.
    Select the Start Time and date for the report.
    The end time is configured automatically for the report, relative to the start time.
  10. Select the destination.
  11. Run the report.

You can schedule reports to run automatically and on schedule by using Report Tags.


Pump-Off Controller Design

This article describes the basic architecture of the Oil and Gas Solutions Pump-Off Controller tags and how they are used.

The Pump-Off Controller (POC) tags are designed as a structure beneath a single tag that will allow you to control and monitor a pump-off controller device. They contain drivers that have been pre-configured with the addresses and poll sequences necessary for reading Dynacard data, setpoints and other telemetry values. Pump-Off Controllers include:

...POC-DV8 Tag

POC-Lufkin SAM Well Manager

POC-Unico Tags

Weatherford Tag

When a Pump-Off Controller tag is created, several child tags are added automatically, as shown in the following figure. Note the tags shown in white are user-defined and not created automatically when a Pump-Off Controller tag is added.

The tags created under the Process Data context are standard analog and digital tags that address a single point in the driver. They directly reference the Process Driver’s poller as their driver.

Dynacard Tags

Dynacard data is read from the device using a series of Modbus commands rather than from a single address. For example, a “read” might consist of first writing to the controller, loading its registers with the data you’re looking for, and then sending several read messages to bring back a large block of data. The Dynacard Upload driver handles all of this sequencing and overhead, but uses the Process Driver, a standard Modbus tag, to send and receive the actual messages.

If you need to customize a pump-off controller tag to read a device that is not explicitly supported in the Oil and Gas layer, refer toSequencing Reads in a Pump-Off Controller for details on how to change the sequence of reads and writes performed by the Dynacard Upload driver.

The Dynacard data read from the device is logged by the Dynacard Input tags. These tags store all the card data in the historian (Min / Max Load, Stroke Length, etc.) but currently the only data shown onscreen are the position / load pairs that make up the Dynacard graph.

Related tags:

Dynacard Upload Driver Tag

Dynacard Input Tag

Dynacard Reference Tag


Pump-Off Controller Displays

The controller overview displays are meant to be at-a-glance overviews of the pump-off controller’s values. These display telemetry information and provide certain controls.

Closed POC-DV8 Display

Closed POC-Lufkin SAM Well Manager Display

Closed POC-UNICO Display

Closed Weatherford Display

POC Overview Display Buttons

Although the displays for these pump-off controllers have different telemetry values, the three controls are the same:

Poll

Initiates a poll of each of the pump-off controller’s process tags a single time. Clicking the Poll button will bring back the latest telemetry data, but not the Dynacard data.

Add Note and View Notes

These buttons allow quick access to the pump-off controller’s notebook tag, allowing users of the system to write, read and respond to notes.

Each opens a pop-up page containing the configured notebook. Refer also to: Operator Notes Page

Dynacard

The Dynacard button launches the Dynacard display screen. (Dynacard Display)


Dynacard Display

The Dynacard shows curves that model the load profiles of the pump-off controllers.

There are three principal components to this display:

  • The graph is the central object on the display.
  • The legend is located to the right of the graph. It allows filtering and selection of individual data sets.
  • The toolbar is located above the graph.

Toolbar

The toolbar above the graph controls how the graph is displayed:

  • The Surface drop list controls the type of line used to draw the surface pump profiles.
  • The Downhole drop list controls the type of line used to draw the downhole pump profiles.
  • Note that the width of the setpoint lines can be controlled using the DynacardSPLineWidth application property.
  • The Increase Zoom Level and Decrease Zoom Level controls are two magnifying glass icons. The slider bar between them indicates the current zoom level but is not selectable itself. These can also be accessed with the + and - keys.
  • Area Select Zoom allows the user to select a rectangular area on the graph to be zoomed in. This can also be accessed by pressing Ctrl-R.
  • Pan Left, Pan Down, Pan Right, and Pan Up are used to move the graph along the x-axis and the y-axis. The arrow keys can also be used for this purpose.
  • Reset Chart Pan and Zoom reverts the graph to the default position. This can also be accomplished by pressing the Esc key.
  • Show Cursor Value will cause a small popup window to follow the mouse cursor on the graph, displaying the current coordinates of the pointer in scaled engineering units. Selecting Show Cursor Value again will make this popup window disappear. This can be toggled with Ctrl-T.
  • Print opens a confirmation dialog asking if the page should be printed. If the user selects "OK", the page will be printed on the system's default printer. This functionality is also accessible via Ctrl-P.
  • Hide All Graphs and Show All Graphs can be used to mask or display all data sets on the graph.

Legend

The legend section has three tabs, Cards, Timeline and Setpoints.

Cards

The legend shows a line entry for each card. The following tools are available:

  • Hide All Cards’ Graphs and Show All Cards’ Graphs are used to mask or display all data sets for the corresponding cards.
  • Select Data by Time opens a dialog for the user to pick which data sets to display.
  • Enable Live Mode Data appears green when live data is being displayed for the card and red when historical data is being displayed. If historical data is currently being displayed, pressing this icon will switch to displaying live mode data.
  • Upload Data from Device signals VTScada to poll the device for data.
  • The circular polling indicator will rotate while the poll is active.

Several line entries appear beneath the title line of the card. These line entries correspond to data sets for that card. The following figure is an example of the data set for a card configured to display 5 data sets.

Key data available here includes

  • The Legend Line displays the color used to depict this cycle on the graph.
  • Toggle Surface Card Visibility causes the surface plot for this data set to hide or be shown.
  • Toggle Downhole Card Visibility causes the downhole plot for this data set to hide or be shown.
  • Save Card Data as Reference marks this data set record as a reference. It will appear as a data set under the "User References" card.

Timeline

The timeline section displays a single list of all downloaded cards within a specified time period. The user can toggle the display of each of these cards on the main Dynagraph plot.

Setpoints

The setpoints section displays all the setpoints that have been configured for this pump-off controller tag, both those that are visible as lines on the plot and those that are not. All setpoints can be changed from this screen.

Viewing Historical Data on the Dynacard

By default, the Dynacard displays the most recent data for a card. However, the user can manually select older data sets by pressing the “Select Data by Time” icon on the card's line item in the legend. Doing so will open the "Choose Datasets" window, as shown in the following figure:

This window will display one or more lines, depending on the configuration of the corresponding Dynacard Input tag. Pressing the red "X" icon on a line will clear it so that it reads "No Record Chosen". If the user clicks on the calendar icon for a line, it will open a picker window:

Initially the window will display line items for years. Each item will indicate how many records occurred within that year. To select a timestamp, do the following:

  1. Click on a year. This will expand and display months at a slight indent. Each month will likewise indicate how many records occurred within it.
  2. Click on a month. The list will expand, displaying every data set within that month. If the user clicks on one of the timestamps, the selection will turn a light grey.
  3. Press the OK button. This will close the picker window.
  4. To select additional datasets, open another picker window and follow steps 1-3 above. Otherwise, press the OK button in the "Choose Datasets" window to save the selections. This will refresh the graph display with historical data. The Toggle Live Mode Data icon will turn red to indicate live data is not being dis-played for this card


Dynacard Reporting

Dynacard data can be exported from the system using the VTScada reporting engine. The report type to use is the Dynacard Report. The report will require the selection of the Dynacard tags for which the data will be reported, as well as the time span over which the Dynagraphs will be included. The data will be exported in a columnar format which includes the following columns:

  • Tag Name – the name of the Dynacard tag
  • Date – The date the Dynagraph was recorded
  • Time – The time the Dynagraph was recorded
  • Parameter – The name of the parameter whose value is reported in the line item
  • Value 1(x) – The value of the parameter. For xy values, this is the x value
  • Value2(y) – The value of Y coordinate for xy values

Caution should be taken as to the number of Dynagraphs to include in a report, as each graph can exceed several hundred data points (rows).

When available, the report includes a line item for each surface xy data pair, as well as each downhole xy data pair. In addition, a data row will be included for each of the summary values included in the Dynagraph record.


Using the Well Test Table

The Well Test Table widget can be drawn on any page. Its only parameter is whether or not to show the Well LSD Closed Legal Subdivision address. filter. The content of the table is managed from the Well Test tag to which it is linked. No filters other than Well LSD are available. The properties dialog for the table allows you to hide this filter.

You can use the calendar buttons at the top of the widget to choose the time frame of the records that should be displayed.

Editing Records

If a column has been configured as editable, (for example, the “Val 2” column in the figure shown), you can edit the table by clicking on a field within that column and entering a new value. The background color of the field will change to green, indicating that there are unsaved changes. The changes to the record are not be saved until you use the Save Changes button.

After saving the edits, the field background color returns to normal. Any records that have been manually edited will be indicated by a "Yes" in the User Edited column.

Test State – Held, Accepted or Rejected

When a well test record is created, it is initially placed it the Held state. After an operator has had a chance to review and verify the information, and has made any necessary changes to the data, they can change the state to either Accepted or Rejected.

As with editing records, this state change will not be recorded until the Save Changes button is pressed.

Changing the test state does have any effect on the User Edited column.

Save Changes will save all changes that were made, regardless of whether the display is later filtered to show only some records.

Export

Exports the Well Test records from the table to a CSV file. Note that, like Save Changes, the LSD filter has no effect on the number of exported records.

Well Test Reports

A Well Test Report can be run using the standard VTScada reporting tools. All columns that would appear in the well test table are exported as part of this report.

Well Tests in PVR Reports

Individual columns of the well test report can be included in a PVR report by using the Complex Variable Log value type.


Oil & Gas Solutions ODBC Interface

The VTScada ODBC interface may be used to access all data recorded by the child tags of the Flow Computer tag. This includes process data tags, hourly data tags, daily data tags, alarm and event data, and RTU configuration. The following sections detail how data from these tags can be accessed from the ODBC interface.

Process Tags

Data values from process tags will be logged to the historian in the same format as standard VTScada tags and can be accessed via ODBC queries using the table and column names described in the VTScada user documentation.

Hourly & Daily Log Format

Data values from hourly and daily log tags will be logged to the historian in the same format as standard VTScada tags (they are Analog Status tags) and can be accessed via ODBC queries using the table and column names described in the VTScada user documentation.

Alarm and Event Log Format

Alarm and event tags use a special table name combined with custom field names to store and retrieve the alarm and event data. The standard VTScada historian table “History” will only provide a single record per tag for a single timestamp. With alarm and event data, multiple alarms and events can have the same timestamp so queries of this data must use a different mechanism to retrieve this data. To allow reporting of all alarm and event logs, all queries of alarm and event data must use the table “HistoryWithDuplicates”.

Unlike most VTScada tags, the Alarm and Event tag in the Flow Computer has a number of fields that may be read from the historian table. These fields and their contents are listed in the following table.

Field Name | Data Type | Contains
IsAlarm | Boolean | True (1) if the record is an alarm, false (0) if it's an event
IsEvent | Boolean | True (1) if the record is an alarm, false (0) if it's an event
EnronBitmap | Integer | The original "Bitmap" value read from the Enron device for both alarms and events
MeterRunNum | Integer | The meter run number that the alarm or event is associated with. Null for alarm and events not associated with a specific run number
ROCAlarmCode | Integer | The original "Alarm Code" value read from the ROC protocol device on alarm reports
ROCAlarmType | Integer | The original "Alarm Type" value read from the ROC protocol device on alarm reports
ROCFSTNum | Integer | The original "FST" value read from the ROC protocol device on event reports
ROCCalInfo | Integer | The original "Call Info" value read from the ROC protocol device on event reports
ROCCalType | Integer | The original "Cal Type" value read from the ROC protocol device on event reports
ROCParamNum | Integer | The original "Parameter Number" value read from the ROC protocol device on event reports
ROCPointType | Integer | The original "Point Type" value read from the ROC protocol device on event reports
ROCPointNum | Integer | The original "Point Number" value read from the ROC protocol device on event reports
AlarmValue | Float | The value of the alarm that was exceeded. Not supported (i.e. null) for ROC and Enron field I/O devices
EventValue | Float | The value for the event, sometimes known as the "Current value"
PrevValue | Float | The previous value for an event
ROCTimePerEvent | Float | The original "Time Per Event" value read from the ROC protocol device on event reports
AlarmAction | Text | The alarm action being reported. Possible values are device dependent but may be one of the following: • Clear • Set • Pulse Input Clear • Pulse Input Set • SRBX Clear • SRBX Set
AlarmType | Text | The alarm action being reported. Possible values are device dependent but may be one of the following: • Lo • LoLo • Hi • HiHi • Rate • Status Change • A/D Failure • Manual Mode • Redundant Total Count • Redundant Flow • No Flow • Logic • Input Freeze • EIA-485 Fail • Sensor Comm Fail • Off Scan Mode • Sequence Out of Order • Phase Discrepancy Detected • Inconsistent Pulse Count • Frequency Discrepancy • Channel A Failure • Channel B Failure
Descriptor | Text | A human readable description of the alarm or event
DeviceTypeCode | Text | A code indicating the type of device that generated the alarm. Possible values are: • 0 (RealFlo) • 1 (TFlo) • 16 (ROC800) • 18 (FloBoss 103) • 20 (FloBoss 107) • 29 (FloBoss 107 with Alternate ROCNOC addressing)
IOAddress | Text | The address for the value
ROCEventText | Text | The original "Event Text" value read from the ROC protocol device on event reports
ROCOperatorID | Text | The original "Operator ID" value read from the ROC protocol device on event reports

Example Queries of Alarms and Events

For a Flow Computer tag with the name “Well 27-102569”, the following query will return a list of all alarms for the month of October 2014:

SELECT Timestamp,
'Well 27-102569\Alarm and Event Log:MeterRunNum',
'Well 27-102569\Alarm and Event Log:Descriptor',
'Well 27-102569\Alarm and Event Log:EventValue',
'Well 27-102569\Alarm and Event Log:AlarmType',
'Well 27-102569\Alarm and Event Log:AlarmAction',
'Well 27-102569\Alarm and Event Log:IOAddress'
FROM HistoryWithDuplicates
WHERE 'Well 27-102569\Alarm and Event Log:IsAlarm' = 1
AND Timestamp >= '2014-10-01 03:00:00'
AND Timestamp < '2014-10-15 03:00:00'
ORDER BY Timestamp ASC

Note that the field names are a concatenation of the Flow Computer’s alarm and event tag name and the field name from the table above. This is the standard format for the VTScada ODBC interface, refer to SQL Queries.

To query alarms or events for specific flow meter run within the flow computer, include the meter run number in the Where clause of the ODBC query. The example below shows a query for all events from meter run #1 from Flow Computer tag “Well 27-102569” for the month of October 2014:

SELECT Timestamp,
'Well 27-102569\Alarm and Event Log:MeterRunNum',
'Well 27-102569\Alarm and Event Log:Descriptor',
'Well 27-102569\Alarm and Event Log:EventValue',
'Well 27-102569\Alarm and Event Log:PrevValue',
'Well 27-102569\Alarm and Event Log:IOAddress'
FROM HistoryWithDuplicates
WHERE 'Well 27-102569\Alarm and Event Log:IsEvent' = 1
AND 'Well 27-102569\Alarm and Event Log:MeterRunNum' = 1
AND Timestamp >= '2014-10-01 03:00:00'
AND Timestamp < '2014-10-15 03:00:00'
ORDER BY Timestamp ASC

Note the use of the “IsEvent” field in the event query vs. the use of the “IsAlarm” field in the alarm query. To get a re-port of all recorded alarms and events, leave the IsAlarm and IsEvent fields out of the where clause but add them to the selected fields to show what the report contains.

RTU Configuration Log Format

The RTU configuration log is recorded by the individual Meter Run tags primarily for the purpose of producing CFX file type reports and any others requiring detailed information regarding the configuration of the RTU. The configuration information recorded by VTScada consists of over 300 individual readings and settings, the details of which are beyond the scope of this manual. For a complete list of the fields available, use your ODBC reporting tool to explore the available values. The display below shows a small number of these as discovered by 3rd party ODBC query tool.

Dynacard Interface

Dynacard data can be retrieved by querying the DYNACARD_RECORDS table. The table fields are as follows:

Field Name | Data Type | Contains
NAME | Text | Name of the Dynacard tag
TIMESTAMP | Timestamp | The Dynagraph timestamp
PARAMETER | Text | Name of the parameter whose value is contained in the row
VALUE1 | Float | Parameter value for summary data, X value for a XY data pair
VALUE2 | Float | Y value for an XY data pair


Email Excel Template

The email Excel template option provides a means to use the VTScada email tools to email a report sent to an Excel template. This option is available only in the VTScada Oil & Gas Layer. Your application must use this layer for the email Excel template option to be available in your application.

The following explains how to use the built-in VTScada feature. Instructions for writing VBA code in Excel are beyond the scope of this document. See also: Use an Excel Macro Template.

Preparation:

  1. You will need to create an Excel macro-enabled template (*.xtlm) file to format data from the VTScada Historian into a suitable report.
    1. Any formatting that you wish to apply via your macro is up to you and will vary depending on how you would like to summarize and present your report.
    2. At a minimum, your macro must save the resulting file using the name that VTScada places in cell B1 of tab, "Report Info".
    3. The macro that you create must be named "Complete".
  2. Configure your system to enable sending reports by email.
    Refer to Email Setup for Alarms and Reports
  3. You will need to configure your Report tag or Reports page to send the report by email.
    Refer to the example in the following image:

Report Creation Process

When the report runs, VTScada will create a new Excel file based on your macro-enabled template.

Within that file, VTScada will insert a tab named “Report Info” and populate cells A1 through A7 and B1 through B5 as shown in the following example:

Your macro will run to format the report data. It must save the file using the name in cell B1. It may use cell B6 to provide a more user-friendly name for the file attachment. If your macro will generate a PDF or other file, use cell B7 to specify the absolute path to that file (include the file name) .

Cell | Title (Column A) | Description
B1 | Save File Name | The file name, including the absolute file location. Even if a file is designated in B7, your Excel template must create this file. Created by VTScada and should not be modified by your macro.
B2 | Email Recipients | List of recipients that will be sent the report. Created by VTScada and should not be modified by your macro.
B3 | Email Subject | The subject that will be used when sending the email. Created by VTScada and should not be modified by your macro.
B4 | Email Content | The body of the email to be sent. Created by VTScada and should not be modified by your macro.
B5 | Report Type | The type of report that was generated. Created by VTScada and should not be modified by your macro.
B6 | Email Attachment File Name | Optional. A user-friendly file name to be given to the attachment when the email is sent. Your VB code is responsible for setting this (will default to "Attachment" if blank)
B7 | File to Attach | Optional. If populated, this file will be sent as the email attachment instead of the file in B1. Your VB Code is responsible to put the absolute path to that file (including file name) in this field. This does not have to be an Excel file; it can be a PDF or other file type.

Email Service

The VTScada Oil & Gas Layer email service will periodically scan the directory "\YourApp\Data\Email Outbox". The only files in this directory should be the Excel reports created by your Excel template.

Reports in this directory trigger the email service to open the report, process the contents on the tab "Report Info" (column B) and email an attachment, either the Excel report itself or an alternative file.

After a report is sent successfully, the Excel report will be moved to the directory "\YourApp\Data\Email Outbox\Sent".

If a report fails to send, the Excel report will be moved to the directory "\YourApp\Data\Email Outbox\Failed". A log file is maintained in the failed directory, containing a description of any failure.

Application Configuration Settings

Setting Name | Default | Description
OGTimeBetweenEmail | 0 | Time to wait between sending email messages using this service


Batch & Recipe Management

Within Alarms, Reports & Diagnostics > Recipes, are three pages dedicated to providing support for batch processing operations:

  • Batch & Recipe Management

  • Batch History

  • Batch Details

Within the tag browser there are several tags that are used to configure batch processing operations, chief among them is the Recipe Book tag which comes pre-configured with several default child tags.

Control over running the batch is expected to remain with the PLC. VTScada's role is to provide sets of values for the recipe used in a batch, start the run (if allowed by the PLC), and report when the batch has finished (if that information is provided by the PLC).

Recipes are not stored in databases

Recipes are stored under the VTScada Distributed Version Control System using CSV files, rather than under the Historian. Unlike other systems, where loss of access to the central database could cause downtime, the VTScada system ensures that production can continue because the files are synchronized across all workstations, automatically.

Any changes by an operator on any workstation will immediately be reflected in the running copy (and files) on all connected workstations. If a workstation was offline when an update was made, its copy of the recipes will be updated as soon as it comes back online.

The other benefit of storing recipes in the version control system is that you get a complete revision log of every change, including the ID of the operator and on which workstation that change was made.

Recipes can be imported from and exported to an external database to facilitate the use of other recipe management tools.

General Process

1) In all cases, the first step is to create a Recipe Book Tag. This will hold your recipes, give you access to key configuration settings, and define the communication link to the PLC. (Refer to Tag Structure for Recipes)

2) A Parameters context tag is automatically generated as a child of a Recipe Book tag. Parameters can hold values that are passed along at the start of each step in a batch to inform the PLC or controller how to operate. Each Parameter is stored in a Recipe Parameter Tag. These should be created as child tags of your RecipeBook\Parameters tag.

Each Recipe Parameter is a two-tag structure where the parent Parameter tag holds the overall description of what the Parameter is, and a child I/O tag holds the I/O address and other specifications required to write a value for that parameter to the PLC.

Optionally, some or all of your Recipe Parameters can use a Recipe Proportions Tag. Use these when parameter values should be multiplied by a given factor from one batch to another, or when values can vary proportionally to each other.

In each Recipe Book, there is only one Parameter tag structure for each parameter, no matter how many recipes or recipe versions call for that parameter by varying values (including the value of zero).

3) After creating the Recipe Book tag and a set of Recipe Parameter tags, open The Batch & Recipe Management Page to set, retrieve, edit, and store parameter values for each recipe and to add steps in the Recipe Book. (It is possible, but rarely necessary, to build your own recipe page using the library of Recipe Management Widgets

After setting values for the parameters that are included in a recipe, save them to a new recipe name. You cannot run the batch with unsaved changes. The option to set a version number is available only if you selected that feature when you created the Recipe Book tag.

Any parameter that is not used in a given recipe or step should have a blank (or zero) value.

4) If your Recipe Book tag has a Start address and a Done address, run the batch when ready. The following example uses a single (optional) Recipe Proportion tag for both the key parameters.

Read/Write Sequence of Events

VTScada's recipe system works in tandem with an external PLC to execute recipe batches. VTScada and the PLC must both be correctly configured to run a batch. To use some features (such as updating an ongoing batch) the PLC must also be capable of responding to these events. Here is a list of steps detailing this sequence of events as it relates to the PLC that is controlling the batch.

  1. Click the run button in VTScada to start the batch.

  2. An operator provides a Batch Number, an optional note and possibly a multiplier. This information is stored in the event log.

  3. Each Recipe Parameter tag linked to a Recipe Proportions tag is scaled (if scaling is enabled) and written to the address provided in the I/O tab of each Recipe Parameter tag.

    1. VTScada writes to the PLC and then reads back what was written. If the parameter value read back doesn't match the expected value, VTScada will pause, display the conflict at the bottom of the screen, and offer the option to skip the conflict or cancel the batch. If the operator selects "skip" VTScada will proceed with the batch without altering the conflicted value read from the PLC.

  4. VTScada will write to the start address provided in the I/O tab of the Recipe Parameter tag. This event signals to the PLC to begin the manufacturing process. Depending on how the PLC is configured, it may reassign a FALSE value to a Done address.

    1. If the recipe is updated while the batch is ongoing VTScada changes the values assigned to the applicable parameter address. This option must be enabled in VTScada and the PLC must be capable and configured to respond to these changes.

  5. VTScada monitors the state of the Done address in the Batch Complete tag nested under the Recipe Book tag. The batch is Done when the PLC signals that it is done by writing to the done address specified in the I/O tab of the Recipe Book tag. This address is being monitored by VTScada.

    1. If there is a Trigger tag configured to respond to a completed batch, writing to the done address is the event that triggers it.

    2. If the recipe is a multi-step recipe, the PLC writing to the done address will signal VTScada to start the whole process over again using the values for the next step. You can see what step is in progress from the caption at the bottom of the screen.

The start and done values may be cleared by the PLC or by VTScada depending on your configuration and the capabilities of your PLC. You may have two separate addresses that are written to and cleared by VTScada and the PLC in turn. Or you may have a single address to which VTScada writes a 1 to start the batch and the PLC writes a 0 to signal the batch is done (while simultaneously clearing the start)

The history tab of the alarm page displays Batch Started, Batch Complete and each time the value of a parameter is changed.

You can technically start a batch without providing a start or done address but it is extremely inadvisable because this will break many features and functions and the batch will never be flagged done.

It is possible to configure VTScada to operate with externally triggered recipe batches. In this configuration, VTScada does not write anything to the PLC, but simply monitors the changes as they are made by an external, third party HMI. VTScada will display information and record historical information about these batches as they occur. Read Externally Triggered Recipe Batches for more information.

Notes:

The value for each parameter in a recipe or recipe version is stored in a file that is controlled and maintained as part of the application's version control system. While parameter values can be set individually by working with your Recipe Parameter tags in the Recipe & Batch Management Page, it is also common to import parameter values from either of:

  • A Microsoft Access file
  • A Microsoft Excel file

See: Import / Export Recipes

You can also start the retrieve process from the Tag Browser by a Recipe Book then clicking the Import button.

In earlier versions of VTScada, Batch & Recipe related parameters were called ingredients and Recipe Parameter tags were called Recipe Ingredient tags. Some residual Easter eggs may still be found in the documentation and debugging tools.


The Batch & Recipe Management Page

You will need at least one Recipe Book tag before working with the Recipe & Batch Management Page.
This page is protected by the security privilege, Recipe Page Access.

Located under Page Menu > Alarms, Reports & Diagnostics > Recipes > Batch & Recipe Management.

Batch & Recipe Management Page. Text at the bottom of the page shows the current status and the last batch to run.

Data Entry Fields

The appearance will change according to data type of the parameter. For example, the following figure shows a set of parameters with Digital, Analog and String data types:

(Analog differs from Discrete only in the ability to specify a decimal value.)

Equipment Types and Recipe Parameters. All analog, discrete and string parameters will use an edit field as shown for Flour in the preceding example, unless they have been configured with an equipment type and that type has been assigned a set of value-label pairs using the Equipment tab of the linked Style Settings tag. In that case, a droplist will be used (as shown for Chocolate Chips).
Values set within an equipment type may be numeric or text. For each value, it is the matching label that will be shown here. For example, if "Chocolate Chips" is identified in the recipe by a product code, use the code for the value and "Chocolate Chips" for the label. Similarly, you might create an equipment type that has a set of decimal values, but fractional labels (0.25 => 1/4).

For a selected Recipe Book, the Batch & Recipe Management Page will always show the same list of adjustable parameters. Parameters that are not part of a given recipe within the book will have no value, but will not be removed from the display.

You cannot use this page to add new parameters manually. But, you can use this page to import the set of parameters that make up a recipe. Possible data sources include:

  • An Access database file containing recipe parameters.
  • An Excel spreadsheet file containing recipe parameters.

Parameter quantities can be adjusted as needed for a recipe or recipe version.

Tools within the page

For all sections, tools are described from left to right.

Select

Use this to select (from left to right) the Recipe Book, a recipe within that book, and (if versioning is enabled in the Recipe Book tag) the version number.

Run

Contains two tools: Start and Update. Both are protected by the "Run Batch" security privilege.

Start will run the selected batch. (Write the values within the recipe to the PLC). If the equipment supports a "start" address and if that is configured in the Recipe Book tag, this will be triggered.

The start button will prompt for a Batch Number (text or numeric) and a note to be associated with the current batch run. If a Recipe Proportions Tag has been assigned to any parameter, you will be prompted for the numeric value to be used for every proportion used in the recipe.

Status Bar If the Recipe Book has a Start Address and a Done Address, then you can monitor the progress of the batch while it runs.

Be sure that your PLC will set the value monitored by the Done address to 0 when each batch starts. VTScada knows that a batch is finished only when the Done value changes from 0 to 1.

Update will write changed values to a running recipe. This assumes that the Recipe Book is configured with the "done" address of the PLC, so that VTScada knows that a recently started recipe is still running.

Manage

Save - Enabled only when editing an existing recipe. You must confirm that you intend to update that recipe.

Save As - Use to save the current configuration as a new recipe name, version number or both, within the currently selected Recipe Book. The version number is available only if that feature is enabled in the Recipe Book. Note the calendar that you can use to add a timestamp to the version number.

If a recipe with the same name and version exists, you cannot use Save As. Use the Save dialog instead.

Revert - Discard unsaved changes and reload the last saved version of a recipe.

Retrieve - Read the current parameter values from the PLC and populate the existing Parameter tags with those values. This lets the operator know what parameters the PLC was last running with.

Delete - Discard the current recipe. You will be prompted to confirm this action. No backup is stored but recipes are under configuration management and could be recreated from the Version Control system.

If using Retrieve to load a new recipe, take care to use Save As rather than Save.

Steps

[+] Add - Add a step. You will be prompted to provide a name and the new column will appear to the right.

[-] Remove - Remove a step. Enable this button by checking the box at the top of the desired column. You must confirm that you want to remove the selected step.

Move Left - Move selected step to your left.

Move Right - Move selected step to your right.

Edit - Change the name of the step.

After adding a second step, it is a best practice to rename the first step from its default title to a custom name.

Import / Export

Refer to Import / Export Recipes for table and spreadsheet characteristics.

Import - Use to import data from all recipes in a recipe book from either Access or Excel.

Export - Send data from all recipes in a recipe book to either Access or Excel.

View

Text Size - Cycles through small, medium and large.

Daytime / Nighttime - Choose a light or dark background.

Extra Columns - By default, only the Parameter name and Value are shown.
You can also view the following information from the Recipe Parameter tag: Full name, Description, I/O Address.


Tag Structure for Recipes

The tag hierarchy for a fully-configured Recipe Book follows. To help clarify the structure, each tag in this example is named for its type or purpose. Every Recipe Book tag will require a driver (which will require a port) but those are not shown as part of this example.

Recipe Book Tag

May have any name. Must be linked to the PLC through a communication driver. Defines the overall structure and communication configuration for a set of recipes. Recipe Book Tag

Batch Complete

An I/O tag created and configured automatically if a Done address is provided in the Recipe Book.

Batch Number

An I/O tag created and configured automatically if a Batch Number address is provided in the Recipe Book.

Parameters

A Context tag created and configured automatically. Holds all the Recipe Parameter Tags for the recipes.

Parameter Tag (n)

The set of parameters that make up a recipe. May be created individually, but often created automatically by importing a recipe from a database, spreadsheet or PLC. Typically named for the parameter, although the display name for each parameter is a property of this tag. (Recipe Parameter Tag) Do not use "copy and paste as a child" to create more parameter tags.

Parameter Value Tag

An I/O tag, created and configured automatically. Holds the value to be written for the parent parameter. Values are stored in a defined CSV file and set or changed for each batch.

Never edit Parameter Value tags directly. Work only with the parent Recipe Parameter tag.
If the Parameter stores text, the Parameter value will show the matching phrase key when viewed in the Tag Browser.

Recipe Name (*)

A Recipe Parameter tag created and configured automatically. Like a parameter, values for a batch are stored in a defined CSV file and set or changed for each batch.

Recipe Version (*)

A Recipe Parameter tag created and configured automatically if the Recipe Book is configured to allow multiple versions. Like a parameter, values for each version of a recipe are stored in a defined CSV file and set or changed for each batch.

Step Name

A Recipe Parameter tag created and configured automatically to store the names of steps in a multi-step recipe. To use externally triggered recipe batches, an address must be provided in the I/O tab of the step name tag properties. See Externally Triggered Recipe Batches for more information.

(*) The Batch Number / Name / Version parameter tags might be used if you want to write the current batch number / name / version into the PLC. This is useful if the PLC can display such information on a panel. This will happen only if these parameter tags are given addresses. Otherwise these tags do nothing other than display their current values on the Recipe & Batch Management Page.

Process Values

A Context tag. Add child tags to populate the HDV portion of the Batch Details page. See The Batch Details Page for more information.

Recipe Trigger Tag

An optional tag that can be configured to start a batch automatically based on rules that you define. (Recipe Trigger Tag)

Start Batch

An I/O tag created and configured automatically if a Start address is provided in the Recipe Book.


The Batch Details Page

For more information about Batches see Batch & Recipe Management and its subsections. The Batch Details page displays historical information about a batch that has been run with the option to plot values from I/O tags that are relevant to the batch process. To access the Batch Details page, go to the Batch History page and right-click once or double-click on an entry. The Batch Details page will open and display information linked to the Recipe Book tag for that batch, relative to the start and end timestamps for that batch.

The batch details page displays a batch details widget, batch setpoints widget and an HDV linked to Process Values in your recipe book tag.

Alternatively, you can access the Batch Details page from the recipe folder by navigating to the Page Menu > Alarms, Reports & Diagnostics, > Recipes > Batch & Recipe Management. If you access the Batch Details page using this method, you will be prompted to link a recipe book tag and provide timestamps or a start and end time. The batch displayed will be the first batch to start running after the provided start time.

If you provide an end time, then the page will display as a snap shot in time showing only data known during that time span, for example a multi-step recipe that finished months ago may only show a single step, if the time span given did not fully cover the time period in which the batch took to run. The option to provide an end time enables you to capture a precision snapshot of the historical data viewer. It is a best practice to access the Batch Details page through the Batch History page. Selecting a batch (double-click, or right click) will auto-populate a Batch Details page with the most accurate configuration for that batch.

Populating the Historical Data Viewer with Process Values

The Historical Data Viewer (HDV) portion of the Batch Details page gets its values from the Process Values Context tag nested in the Recipe Book tag.

Process Values is a Context tag that is automatically generated within a Recipe Book tag. You must add child tags to plot values within the HDV.

The Batch Details page will plot values read from the child tags of Process Values. For example, you may add an I/O and Calculations tag that monitors the temperature of an autoclave, the flow rate of canola oil or the speed of a propeller as they were recorded during the batch time span. The HDV will plot the value read by this tag as a line graph for the duration of the batch. For more information, see Historical Data Viewer (HDV)

Related information:

Batch Setpoints Widget

Batch Details Widget

Draw HDV Widget


The Batch History Page

For more information see Batch & Recipe Management and its subsections. The Batch History page is an interactive list of batches run over a given time range. Filter results by Recipe Book tag, time span or by text phrases such as key words, username or batch numbers. Click on a heading to sort by that category. Double click on a row to open batch details for that row.

Batch History page displays all batches that have been run and is filterable by recipe book, time span and keyword.

Batch History Page. Select a Recipe Book and time span to see batch history information.

To navigate to the Batch History page, go to Page Menu > Alarms, Reports and Diagnostics > Recipes > Batch History.

See batch details for any entry in the Batch History page.

To open the Batch Details page and display batch details:

  • Find the batch in the Batch History page

  • Right-click or double-click the entry.

The Batch Details page will open and display details for that batch. The Batch Details page will use the Recipe Book tag and time stamps from the Batch History page entry to configure its results.

Settings

Recipe Book Selector

A drop-list containing all available recipe book tags and the option to display 'all'. If 'all' is not displayed, Recipe Book tags present in the application exceed the limit set in MaxRecipeBooksInBatchHistoryList. MaxRecipeBooksInBatchHistoryList

Time Span - Time Range Selector

A drop list with options to display results by daily, weekly, monthly, quarterly or yearly increments. The arrows at the bottom of the page browse back and forward in time in increments relevant to the selected time span.

Time Span - Calendar Button

Open a calendar to select a date to base the time span on.

Filter

Enter a text value with which to filter the batch history results. For example, a batch number, Recipe Book tag name or a keyword from a note. Defaults to a wildcard *. When a text value has been entered, this field will turn orange to indicate a filter is active.

View - Font Style

Cycles through font sizes small, medium and large.

View - Day/Night

Change the theme to either dark or light.

View - Batch Details

Only enabled when a batch row is selected. Browses to Batch Details page for the selected batch. You can also double click on a batch row to open the Batch Details page for that batch.


Externally Triggered Recipe Batches

A batch process can be triggered from outside of VTScada by another HMI device. VTScada will react by reading and writing values to the PLC, tracking values and maintaining historical data. To configure externally triggered recipe batches, you must perform the following configurations:

  1. In the I/O tab of the Recipe Book tag you must provide a valid start address and done address.

  2. Provide a batch number address so VTScada can retrieve the batch number written to the PLC by the external device.

  3. Provide a batch note address so VTScada can retrieve any operator notes written to the PLC by the external device.

  4. Select "Batches are externally triggered". This will switch VTScada to Reactive Mode. The radio buttons next to the batch number address and batch note address will switch to Input and grey out, signaling that VTScada is receiving this information externally as opposed to writing it to the PLC itself.

  5. Valid addresses must be configured in the Parameter tags.

  6. You must provide an address in the I/O tab of the Parameter tag called Step Name and in Recipe Name and Recipe Version Parameter tags if they are present.

  7. The time it takes to complete a step must be greater than the poll time of the driver. Otherwise, steps may be missed.

  8. Upon batch completion, the PLC must set the register at the Start Address to a value besides the Start Value configured in the Recipe Book tag I/O tab.

While VTScada is in reactive mode, Recipe Trigger tags and Recipe Proportions tags will not work. All pages or widgets with a button for starting a batch will become disabled. Only the external HMI device will be capable of starting a batch and must supply the PLC with the final parameter values.


Import / Export Recipes

Recipes can be read from and written to either Microsoft Excel™ spreadsheets or Access™ databases.

Spreadsheet format:

  • Each worksheet is named for a matching Recipe Book
  • Column A holds each Recipe (RecipeName) in the Recipe Book
  • If there are versions, then Column B (RecipeVersion) will hold those names.
    Versioning available only if the Recipe Book tag is so configured.
  • Step number and step name are displayed in the spreadsheet. Recipes with multiple steps will see an extra line of entry for each version and all steps in each version.
  • Other columns are named for each parameter within the recipe. All parameters for all recipes in the book are included in the spreadsheet. Recipes that do not include certain parameters have blank cells for those columns.
  • Parameter addresses are not imported or exported.
    These must be entered manually in the Parameter tags, along with any other configuration such as Data Type, Engineering Units and permitted value range.
  • Up to 16,384 recipes can be exported.

For example, a recipe book of kettle chip recipes with two steps and two versions might be similar to the following when viewed as an Excel worksheet:

Versioning enabled in the Recipe Book

Database format

Similar to the Spreadsheet format, noting:

  • Each table holds a set of recipes, with one recipe per row, where each column is a parameter value.
  • The primary key must be the column that contains the recipe name.
  • The secondary key (optional) must contain the recipe version.
  • The renaming columns are treated as parameter names. A Recipe Parameter tag will be created for each of the parameter columns.


Recipe Batch Report

This is a standard report type, found within the VTScada Reports Page and the Report tag. It can generate a report about one or more batches. The following information is included:

  • Name of recipe book
  • Recipe name and version
  • Batch number
  • Batch note
  • Start and end times and the duration of batch
  • Selected parameter names and values

Create a Recipe Batch Report:

(For a report that runs automatically at a scheduled time, create Report Tags. Otherwise work within the Reports Page. For those creating a Report tag, note that it is always easier to select the tags for the report while working in the Reports Page, saving them there before starting a Report Tag.)

  1. Set the Report Type to Recipe Batch Report.
  2. Select the parameters to include in the report.
    Do not select the Recipe Name, Step Name or Recipe Version tags. You can use the shift key to select a range.
  3. Save this list of parameters using the Save Group button.
    Saving the group is required in a Report tag and recommended in the Reports Page.
  4. Set the reporting period to include all the batches that should be part of the report.
    To report on only the most recently run batch, set the reporting period to 1 minute. The batch need not have run within that minute because the values from the most recent run will remain set until the next batch.
  5. Set the number of previous periods as needed.
  6. If configuring a Report tag, then on the Trigger tab of the properties dialog, choose to trigger the report manually (by drawing a Run Report button on your page), schedule it to run at a certain time, or trigger it to run as soon as the batch is complete. To trigger it when the batch completes, select the "By Tag" option and select the tag called "Report Trigger" under your recipe book tag.
  7. Choose your preferred destination for the report and options such as whether to use Excel for screen reports.
  8. Run the report.

Sample report

Recipe Batch Report for: Cookies

Data Point | Value | Value | Units
Recipe Name | Chocolate Chip Biscotti | Chocolate Chip Biscotti |
Recipe Version | v1 | v1 |
Step | First Bake | Second Bake |
Batch Number | 123 | 123 |
Note | Batch 123 Note | Auto Run Batch |
Batch Start Time | 2024-09-05 11:35 | 2024-09-05 12:17 |
Batch End Time | 2024-09-05 11:47 | 2024-09-05 12:25 |
Duration | 0:00:10 | 0:00:10 |
Bake Time | 12 | 8 | min
Baking Powder | 0 | 0 | tsp
Baking Soda | 1 | 0 | tsp
Brown Sugar | 1 | 0 | cup
Butter | 1 | 0 | cup
Eggs | 1 | 0 | egg
Flour | 2.25 | 0 | cup
RecipeName | Chocolate Chip |  |
Salt | 0.5 | 0 | tsp
Special Cup Name | Chocolate Chips |  |
Special Cup Qty | 2.25 | 0 | cup
Sugar | 0.75 | 0 | cup
Temperature | 350 | 0 | °F
Vanilla | 1 | 0 | tsp


Manage

In this section, you can learn about how to manage a VTScada application. Tasks include configuring backups, adding subordinate applications, distribution of applications, file management, and creating your own user documentation.

Backups
Options to store your application development and your collected data.

Master & Subordinate Applications
Monitor several specialized applications within one central application.

Version Control
Review and change development steps.

ChangeSets for Distribution
Send an application to a colleague or a customer.

Best Practices for Distributed Development
Tips for managing development when colleagues are not on the same network.

File Management Tools
Review changes made outside VTScada and then choose whether to import or discard those changes.

Document Your Application
Place useful notes and instructions where your users will find them.


Backups

The use of imaging (cloning) software to restore a lost VTScada server in a multi-server installation can cause significant configuration damage, not just on the machine being restored, but on all machines in your VTScada network.
Trihedral strongly advises you to avoid using such software for your VTScada backups.

Your VTScada application and your application data should be considered separately when designing a backup system.

Recommended (Online Backup):

If your application runs on two or more workstations, where one is designated the primary server and one or more others are designated as backup servers, then your application and your logged data are automatically stored and updated on all configured servers continuously.

If one server fails, install a replacement, do a Get From Workstation to load the application on it, and let VTScada synchronize the data from the current primary server. All of this can be done without interrupting the application. This is the most reliable method available for maintaining a backup of your logged data including operator notes and retained variables and is strongly recommended.

In this configuration, DO NOT use a copy or backup of the data directory to restore data to one server. Doing so will create a discontinuity between the computer that is being restored and the one(s) on which VTScada has been continuing to run. A ChangeSet should not be used to restore a single computer that is part of a VTScada network - always use Get From Workstation to obtain a current copy from another server instead.

DO NOT use imaging software to re-install VTScada and your application on any server.

Alternative Options / Offline Backups:

If you are running VTScada on a single computer only, or if there is a chance that all servers could be lost in an event such as a fire, then you should do the following:

Create a full (standard) ChangeSet of your application on a regular basis and store that ChangeSet file in a secure location, preferably off-site. If you do not have a copy of the VTS or VTScada installation program, a copy matching your last version can be obtained from Trihedral. Snapshot ChangeSets are not suitable for this purpose.

ChangeSet files do not include data or workstation & user - specific settings.
A ChangeSet should never be used to restore one workstation within a networked application. Use the Get From Workstation option in the Add Applications Wizard instead. See: ChangeSets for Distribution

Unless otherwise configured(*), VTScada stores logged data in a folder within your application. For example, if you have installed VTScada in the folder, C:\VTScada and are running an application named MyApp, then the history can be found in:

C:\VTScada\MyApp\Data\

Copy the Data folder and all of its sub-folders.

(*)If you have configured your system to use a 3rd party database program for your logged data instead of the VTScada history system, use the instructions in that program for creating and restoring backups.

Warning: If at all possible, VTScada should be stopped before the data folder backup is made. There are three reasons for this:

  • Write-access to the files will be blocked while they are being copied, potentially resulting in the loss of data or damage to the integrity of the system.
  • Because VTScada is continually writing data, the backup you create will be out of date by the time the process is complete. Worse, files copied earlier may be out of sync with files copied later during the backup.
  • The backup process can be demanding on system resources, possibly interfering with normal VTScada operations.

If it is not possible to stop VTScada before copying the data folder files, use a shadow backup solution.

Again, your best solution for maintaining a backup of the application and all data files is to have primary and backup VTScada servers.

Related information that you may need:

ChangeSets for Distribution - A way to keep a copy of your application itself (excluding logged data).

Cloning a VTScada Workstation


Master & Subordinate Applications

A master application is one that is able to monitor and control one or more subordinate applications. Master applications provide the following features:

  • Monitor the status (including alarms) of tags in one or more subordinate applications.
  • View, trend and report on logged data from tags in the subordinate applications.
  • View all pages in the subordinate applications for which you have security privileges.
    Pages are automatically added to the master application's menu, contained within a folder named for the subordinate application.
  • View tag configuration in the subordinate applications.
  • Acknowledge alarms in the subordinate application from the master application.
    (Alarm from subordinate applications do not sound in the master application, but are visible.)
  • Draw and use subordinate application tag instances in master application pages.
  • View page notes from subordinate applications.
  • Add page notes to subordinate applications.
  • View alarm database groups in subordinate applications.

Township A and Township B are completely separate applications.
Master Application can monitor both.

Related information:

Subordinate Application Tags

Copy Types to Other Applications

Windows Security Integration

Restrictions and Notes

  • There is no requirement that you layer the master application on top of the subordinate application. The concept of master and subordinate applications is distinctly different from VTScada's system of layered applications.
  • Once an application is a subordinate application, it cannot have subordinate applications. You cannot link nested applications.
  • The page menu items for the subordinate pages cannot be modified, disabled, or deleted. Cut, Copy, Paste (if you've copied a master app menu item), New, Delete, Properties are disabled if you right-click a menu item that was propagated from a subordinate app.
  • You must install the subordinate application in the same VTScada Application Manager as the master application. The subordinate application need not run when you create the Subordinate Application tag, but no tag values are available unless it is running.
  • User-defined tag types defined in any subordinate application must also be defined in the master application.
    It is significantly easier to manage master and subordinate applications when they are all built on a common layer. In particular, this will eliminate the need to copy tag type definitions (and updates to same) from subordinate applications to master applications. It also reduces the likelihood of conflicts if subordinate applications contain custom tag types with the same name but differing definitions.
  • Master applications do not have access to draw custom widgets from subordinate applications unless that widget is also copied to the master application. Likewise, master applications cannot edit pages from subordinate applications. (Subordinate pages and their custom widgets are visible to the master application.) Like custom tag types, custom widgets should be stored in a common OEM layer that both the subordinate and master application are built upon.
  • Idea Studio palettes from subordinate applications are not available in master applications.
  • System resource limitations may restrict the number of subordinate applications a master can monitor, especially if those applications are "large" with many thousands of tags. Numbers are not available because any hypothetical limit will depend on hardware and on the design of the subordinate applications.
  • Master applications cannot log data to subordinate applications.
    Nothing will stop you from selecting a subordinate application's Historian while working with logger tags in the master application, but no logging will occur. Likewise, do not link SQLLogger tags from a subordinate application to SQLLoggerGroup tags in the master application.
  • Master applications cannot publish live values from a subordinate application to a client You must publish values from the subordinate application. For example, the subordinate application with an IO & Calculations tag that is publishing values for OPC DA would need an OPC Classic driver tag to publish values to an OPC client.
  • If working in a master application and configuring any of Polling Drivers, DriverMux or Transaction tags, do not select child tags from the subordinate applications. Behavior in this situation is undefined.
    While master applications can write to tags in subordinate applications, you are advised to keep process control of an application within that application.
  • Subordinate alarms are labeled for their application, as viewed from the master application. They are not sent out by the alarm notification system in the master application.
  • Tag naming rules continue to apply. The overall length of a tag name, including components from both the master and the subordinate application cannot exceed 255 characters.
  • You can specify the startup page for a subordinate from the master application. In a typical application, you can specify the startup page using the setting Page where Page = <PageModuleName>. In a master/subordinate configuration it becomes Page = <SubordinateTagName>\<PageModuleName>
  • Specifying the startup page for subordinates works in conjunction with multi-monitor startup configuration. (Configure for Multiple Monitors)
  • If using realm filtering, refer to notes in [RealmName-REALMFILTER] Section

  • On root session (Server):

    • Master App plays all alarm sounds

    • When a Master App is running the Subordinate App:

      • Plays no sounds

      • Disables Mute and Silence buttons

  • On VIC/Anywhere connection:

    • All Apps play all sounds

Process

An application becomes a master application when you add a Subordinate Application tag, which is the parent for all tags in the subordinate application. Before creating a Subordinate Application tag, ensure that the following are in place:

  1. Configure security.
    • Enable security in what will become the master application.
      This is not a technical requirement, but it is strongly recommended.
    • Secure the subordinate application.
    • Ensure that you have access to an account with the Manager privilege in the subordinate application.
      After authentication, the Subordinate Application tag will continue to function regardless of any changes made to the account used for authentication.
    • If output tags in the subordinate application are protected by custom privileges and if you intend to write to those tags from the master application, then your security account in the master application must possess custom privileges that match the privilege index numbers (not the names) of those in the subordinate application.
    • By definition, master applications are meant to have extensive abilities to monitor subordinate applications. If your intention is to allow an employee to monitor application A and B, but not C, then it is better to have them sign in to applications A and B directly rather than a master application that monitors all three.
  2. Ensure that tag definitions and widgets are available to all applications.
    • All user-defined tag types in the subordinate application must also exist in the master application. This includes any defined in underlying OEM layers of subordinate application. The type and its child tags are not visible otherwise.
    • All user-defined widgets in the subordinate application must also exist in the master application.
    • The recommended approach is to ensure that the master application and subordinate applications are based on a common OEM layer where those tag types and widgets are defined. This is by far the easiest method to use in terms of long-term maintenance.
    • As an advanced option, steps to copy types are provided in Copy Types to Other Applications. This practice is not recommended, but may be necessary in rare circumstances.
  3. Create one Subordinate Application tag in the master application for each subordinate application.

Security Management for Subordinate Applications

It may be convenient for a user to have a single sign-in account that can be used across applications. The only practical way to bundle security access to multiple applications within a single account is to use Windows Security Integration with all the relevant applications.

Active Directory accounts are independent of your applications. They gain access to your applications through AD Security Groups, which map to roles within the applications for which you have enabled Windows Security Integration (WSI). By associating a Windows AD account with the AD Security Groups for several applications, you achieve your goal of creating a single account with access to multiple applications.

For example, consider three applications, A, B and C. They all have a common role Operator and each has a unique role, Role-A, Role-B and Role-C respectively. Assume that all three apps use a common ADGroupPrefix of "VTScada". The AD account will be a member of four AD Groups; VTScada-Operator, VTScada-Role-A, VTScada-Role-B and VTScada-Role-C. The AD account, when used in each app will be assigned two roles, the common Operator and the appropriate Role-X.

You may wish to differentiate the Operator role between the three applications. Do so either by setting a different ADGroupPrefix for each application (the preferred solution) or by creating unique names for roles within each application.

For more information, refer to the Windows Security Integration topics, starting with Running Multiple Applications with WSI.

Do not use the "Shared Security" feature of the Administrative dialog. Windows Security Integration is a better solution. If you attempt to select a subordinate application that uses shared security, a warning message will be displayed.


Version Control

Every step of application development is recorded to VTScada's version control system. You can return to an earlier stage of development at any time by using the commands in the Version Log.

Full access to the version control system is an optional feature that your company may or may not have purchased with your VTScada license. Check the list of features included with your VTScada license in the About VTScada dialog.

The version control system offers far greater flexibility than a simple Undo-Redo. Features include:

  • The ability to return directly to any earlier stage of development.
  • Because the act of switching to an earlier version is itself logged as a stage in the version control system, you have not "undone" and lost changes to intermediate stages of development but instead, have added a new change to the log.
  • Having reversed the work of several development steps, you can then merge back some or all of those steps.
  • You can reverse or merge changes from a range of versions.
  • You can view the version log of every connected workstation running your application.

In the version log, entries include both development steps and actions taken within the version control system such as switching to an earlier version. In this context, "reverse" and "merge" mean the following:

Reverse

To remove changes recorded in one or more version log entries.

Merge

To take one or more log entries that were reversed and are not part of the current version and make them part of the current version. This can also mean taking development work that is local on another workstation and making it part of the current version.

Automatic versus Manual Version Deployment

By default, all version changes are deployed automatically. This is controlled in the "Other" tab of the Edit Properties page of the Application Configuration dialog.

If you switch off the Automatically Deploy option, then you must choose when to deploy your changes, using the Deploy menu item in the Application Configuration dialog. All local changes will be included when deploying. (See: Local versus Deployed Changes)

You can use the Revert Changes tool only when there are local changes to revert. (That is, when the Automatically Deploy option is not selected.) The revert changes command will discard all local changes, returning your system to the last deployed version.

While automatic deploy is on, a variety of actions will cause deployment, including editing a tag, closing the Idea Studio, changing property settings, and more.

Version Changes and Security

When you add, modify or delete user accounts, these actions count as changes to your application and therefore become part of an application's version history.

If a switch to a different version of the application will affect user accounts, you will see a warning, asking if account information should be changed. You can say "Yes" in response to this dialog to apply all changes including those that will affect account information.

Use care when changing versions

If you select "No" only the changes that do not affect user accounts will be applied.

Having selected "Yes" you can still recover those account changes. Do so by merging back in, those revisions in which the account changes were made.

When reversing or merging changes, you can choose to exclude the Accounts.Dynamic from the list of files included in the action.

Security changes are always deployed immediately, regardless of the current setting of Auto-Deploy. There is no such thing as a "Local" version of security settings.

Commenting Changes

When you apply or deploy a change, VTScada will prompt you for a comment. The title of the dialog will vary according to the type of change being saved.

The version history for any application is likely to become large over time. By making a note of why each change was made, you can create a clear history documenting your application's development. There is no need for the comment to describe what was changed, as the version history will include that. Better to describe the reasons for the change.

Comments are not mandatory in the default configuration of VTScada. If you prefer to make comments mandatory, you can change the minimum length required. To do so, add the application property RepositoryCommentMinLento the Layer section of your Settings.Dynamic file.

After setting a value for the property RepositoryCommentMinLen, users will see a dialog similar to the following if they do not provide the required number of characters.

Mandatory minimums on comments


Local versus Deployed Changes

The last deployed change becomes the official version of the application. In a networked application, deployed changes are distributed and applied to all the workstations running that application. If you send someone a ChangeSet of your application, they will receive the last deployed version and will not see your local changes.

Until a change is deployed, it is said to be "local". Local changes are stored in a separate branch of the application's version history. They do not become active on other workstations (although they can be viewed there). They can be erased using the Revert Changes tool. While there are local changes on a workstation, the title bar will display a "Work-in-progress" image.

The undeployed changes indicator

All changes to an application are automatically and immediately deployed unless you configure it otherwise. In most cases, it is an advantage to have the Automatically Deploy Changes option selected because it ensures that your edits are always saved as the official version of the application in the repository. A situation where you might not want this feature is if you are making changes to a networked application and do not want your edits to be installed on the other workstations until you have finished and tested your work.

When auto-deploy is off, you must take extra care to deploy changes that need to be in effect on all servers.

To toggle the Auto-Deploy Setting:

  1. Open the Application Configuration dialog.
  2. Select the tab labeled "Other".
  3. Select or deselect the Automatically Deploy check box.

  4. Click Apply.

Changes related to security accounts are always deployed automatically and immediately.
* Auto-Deploy cannot be deactivated on a RunTime licensed workstation.
* Changes to the Automatically Deploy option affect only the current workstation. You cannot remotely change this value on other workstations.

Troubleshooting:

  • Critical updates are not being distributed to other servers.
    Use Deploy Changes or turn Auto Deploy back on.

Deploy Local Changes

(Except for the header text, the same screen is used when merging or reversing a range of changes.)

The Deploy Changes page is disabled while the Automatically Deploy Changes feature is in effect. The following information applies only while the Auto-Deploy feature is switched off.

Local changes can be deployed while you are working in the Idea Studio. Click the button provided in the title bar of the studio:

Deploy from the Idea Studio

A more powerful tool for deploying changes can be found in the Application Configuration dialog:

You can open this page as follows:

  1. Open the Application Configuration dialog.
  2. Click on "Deploy Changes" from the menu.

All changed files are listed

Use the Deploy Changes screen to see exactly what was done to each source file and tag. For example, clicking on the Analog Control tag (shown in the previous image) will open a display showing what was done to configure this tag:

Every change to every parameter is shown

Changes made to source code such as a page, will show green lines for what is new, and yellow for the previous values. (Circled numbers link to descriptions in the following text.)

Numbers refer to the following list

The following tools are available to help you work with this display:

(1) The number of changed files in each category is shown in parentheses.

(2) Before and after time stamp and file size.

(3) Columns can be sorted by type of change (addition + or removal -), line number, alphabetic.

(4) Move Next and Move Previous changes the focus box (5) from one change to the next.

(6) Changes throughout the file are shown in color bars on the side panel. The black rectangle shows how much of the file is visible and can be dragged to show the next change.

When you first open the Deploy Changes page, all changed items will be selected. By selecting individual items in the list and using the buttons at the bottom of the page, you can choose which changed items will be included when you click the Deploy Changes button.

Available command buttons

The Reload button will refresh the display. If you have made local changes while the Deploy Changes page was open, click this button to ensure that all changes are displayed before deploying.

Revert Local Changes

The Revert Changes page is disabled while the Automatically Deploy Changes feature is in effect. The following information applies only while the Auto-Deploy feature is switched off.

Local changes to an application (that is, those changes that have not yet been deployed) can be reverted or undone. If you need to undo local changes, use the Revert Changes page of the Application Configuration dialog.

You can open this page as follows:

  1. Open the Application Configuration dialog.
  2. Click on "Revert Changes" from the menu

You can revert all changes, returning to the last deployed stage of the application, or you can select particular changes to revert.

When you first open the Revert Changes page, all changed items will be selected. By selecting individual items in the list and using the buttons at the bottom of the page, you can choose which changed items will be included when you click the Revert button.

Development tasks often involve more than one file. Choosing to revert only some of the code changes required by a VTScada object may cause serious errors in your application.

The Reload button will refresh the display. If you have made local changes while the Revert Changes page was open, you should click this button to ensure that all changes are displayed before reverting.

Deployed changes are managed (and can be undone) using the Version Log.


The Version Log

Review development history by opening the Version Log:

  1. Open the Application Configuration dialog.
  2. Click on "Show Version Log" in the menu.

Detail from a version log

Versions are numbered as follows:

  • The computer name where the change was made.
  • Dash.
  • "D" indicates a deployed change.
  • "L" indicates a change that was local-only at the time it was made. Deploying the change later does not change this record.
  • The number following the "D" or "L" is a simple counter.

For example, version "ANDREWH-D4" is the 4th deployed change made on the workstation, ANDREWH.

To prevent the possibility of a faulty system clock creating out-of-sequence entries, the version counter takes priority over the "time applied" value.

You may see a recurrence of the same revision in the version log from time to time. For example, you might see a sequence of revisions such as: Wkstn-D18 > Wkstn-D19 > Wkstn-D20 > Wkstn-D19 > Wkstn-D20. What this typically means is that at the time the first D20 was recorded in the version log, the application was running and the changes in D20 include changes that cannot be integrated into the running application. Because of this, the application returns to revision D19, and the Version Log reflects this. At that time, the "Restart Required" dialog would appear. After the application restarts, it advances to version D20, and the version log reflects this.

Numbers refer to following notes

1) List of workstations running the application

If this is a multi-server application, all the workstations that the application runs on will be listed in this table. Note that, if a machine is isolated from the network, its version list will almost certainly be out of date. Color-coding is used so that you can see at a glance whether each workstation is running the most recently deployed version of the application.

Black Text: The workstation is running the most recently deployed version

Blue Text: The workstation has local changes that have not yet been deployed.

Red Text: The workstation is running an out-of-date version. That is, the version on the workstation is older than the most recently deployed version.

2) List of version changes for the selected workstation

Displays the list of version changes for the computer selected in the Workstations table. Information displayed includes:

Version number - The version numbering system is explained earlier in this topic (example: ANDREWH-D20).

Time applied - All version changes are logged using UTC time, however, the display will show local time at the current workstation.

User - The user signed into the workstation when the change was made. If security has not yet been enabled, the change will be attributed to the Logged Off user account.

Comment - When manually deploying a change, you will be prompted for a comment for the version. Automatically deployed changes will often, but not always, be assigned a comment from a list of standard change descriptions.

3) Right-click on a version to open the options menu

By right-clicking on an entry in the version table, you can open a menu that provides several options for learning more about what went into a version, or to select changes to make current.

The buttons, Next 100 and Show All are used to step through the list of version changes, which may become lengthy over time. The Reload button will refresh the display to show any version changes that may have happened since the page was opened.


Switch to This Version

Use this option to make any earlier version current. Changes made in versions since the one you are switching to are not lost. The act of switching versions becomes a version change itself. For example, your current version number is D12 and you switch to version D8. What will happen is that a new version will be added - D13 - which will be an identical copy of D8. Changes made in versions D9 though D12 will no longer be in the current version, but if required, you could easily switch to version D12 (thereby creating version D14, which is an identical copy of D12).

Switching between versions

Troubleshooting:

  • An error message indicates a conflict.

The change you are making affects an unsaved change, or possibly work being done by another developer. Examine the error message for details and resolve the conflict before re-attempting this action.

  • After this change, part of the application unexpectedly stops working.

The changes include a detail that may be critical to the operation, such as a changed I/O address. Restore the previous version, examine the version log in detail, then repeat your action taking care to avoid changes that will damage the application.


Reviewing Version Changes

A right-click on any entry in the Version Log will open the following menu, which allows you to view details of each change, switch to an earlier (or later) version, and merge or reverse changes.

Version details menu

If you choose the option, Show Version Changes, a complete record of how that version differs from the previous will be shown at a source code level.

In this change, the Questionable property of the tag, Percentage Full, was changed to 0 by Andrew on January 7th.

The menu at the left of the changes dialog indicates which part of the application changed – source files, tags, images, properties, etc. Within each category, only those files that changed from the previous version will be shown.

The menu of the Show Changes dialog.

Selecting any given file will open a display showing exactly what changed. Previous values (if any) are shown with a yellow highlight. The new value is shown with a green highlight. Lines that were deleted from the previous version would be shown in red.

In this way, the entire development history of the application can be reviewed.

Switch to This Version

Use this tool to make any earlier version current. Changes made in versions since the one you are switching to are not lost. The act of switching versions becomes a version change itself. For example, your current version number is D12 and you switch to version D8. What will happen is that a new version will be added - D13 - which will be an identical copy of D8. Changes made in versions D9 though D12 will no longer be in the current version, but if required, you could easily switch to version D12 (thereby creating version D14, which is an identical copy of D12).

Switching between versions

Closed Troubleshooting:
  • An error message indicates a conflict.

The change you are making affects an unsaved change, or possibly work being done by another developer. Examine the error message for details and resolve the conflict before re-attempting this action.

  • After this change, part of the application unexpectedly stops working.

The changes include a detail that may be critical to the operation, such as a changed I/O address. Restore the previous version, examine the version log in detail, then repeat your action taking care to avoid changes that will damage the application.


Reverse Version Changes

By reversing the changes made within a selected version, you can remove just the edits made to the application in that version.

For example, you have made the following changes to your application:

  1. Version D10 Added a page
  2. Version D11 Deleted a tag
  3. Version D12 Created a new tag

You then decide that it was a mistake to have deleted the tag in version D11. You can reverse just that one change as follows:

  1. Select the row D11 in the Version Log.
  2. Right-click to open the context menu.
  3. Choose "Reverse Version Changes".

All of the edits that separate version D11 from D10 are removed, but the new tag created in version D12 remains.

Use extreme caution when reversing a version change. If later versions depend upon work that was done in the version that you are reversing, your application will be damaged.

The act of reversing a version change does not remove those changes from the history. Instead, it adds a new version in which the change is the undoing of whatever was done in the reversed version. You could later decide to re-incorporate the changes from the reversed version by using the Merge Version Changes command.

Troubleshooting:

  • An error message indicates a conflict.

The change you are making affects an unsaved change, or possibly work being done by another developer. Examine the error message for details and resolve the conflict before re-attempting this action.

  • After this change, part of the application unexpectedly stops working.

The changes include a detail that may be critical to the operation, such as a changed I/O address. Restore the previous version, examine the version log in detail, then repeat your action taking care to avoid changes that will damage the application.

Reverse Version Range

Rather than reverse one version change at a time, you can select all the versions within a range. This feature includes the ability to select file-by-file, which changes within that range you want to reverse, leaving some changes intact. For example, in versions 19 and 20 you may have created and configured tag A. In steps 21 and 22, you created and configured tag B. In step 23 you made further changes to tag A.

You can reverse all the actions related to tag A without damaging tag B, by selecting items to reverse in a range that spans steps 19 to 23.

To reverse a range:

  1. Right-click on the version either beginning or ending the range.
  2. Select Reverse-Version Range from the pop-up menu.

The selected version will be highlighted to help you keep track. Note that this version is also highlighted in the workstation list - you can select a range across workstations as well as across the versions on your workstation.

  3. Right-click on the version marking the end of the range you wish to select.

  4. Optionally, remove items from the list of changes to be reversed.

Some development items will depend on others - use care in your selection.

  5. Click Apply and provide a comment in the dialog that appears.

Troubleshooting:

  • An error message indicates a conflict.

The change you are making affects an unsaved change, or possibly work being done by another developer. Examine the error message for details and resolve the conflict before re-attempting this action.

  • After this change, part of the application unexpectedly stops working.

The changes include a detail that may be critical to the operation, such as a changed I/O address. Restore the previous version, examine the version log in detail, then repeat your action taking care to avoid changes that will damage the application.


Merge Version Changes

If you have used either the Switch Version or the Reverse Version Changes command, then you can use the Merge Version Changes command to re-introduce the changes from a specific version. You can also use this tool to merge other machine's local changes into a new deployed version.

For example, your version log includes the following changes:

  1. Version 10 Added a page
  2. Version 11 Added a tag
  3. Version 12 Drew the tag on the page.

You decide that the creation of the page was a mistake, but that the creation of the tag was not. You can proceed as follows:

  1. Select version 9 in the table.
  2. Right-click to open the context menu.
  3. Click Switch to This Version

Changes made in versions 10, 11 and 12 vanish from the current version.

  4. Select version 11 in the table and right-click to open the menu.
  5. Click Merge Version Changes.

The tag is again part of the current version. The page does not exist and the tag is not drawn on the non-existent page.

Depending on the change you may need to re-start your application.

For this example, the same effect could have been achieved by reversing the changes in versions 10 and 12.

Closed Troubleshooting:
  • An error message indicates a conflict.

The change you are making affects an unsaved change, or possibly work being done by another developer. Examine the error message for details and resolve the conflict before re-attempting this action.

  • After this change, part of the application unexpectedly stops working.

The changes include a detail that may be critical to the operation, such as a changed I/O address. Restore the previous version, examine the version log in detail, then repeat your action taking care to avoid changes that will damage the application.

Merge Version Range

If you made an earlier version current, or reversed version changes, you can merge selected changes from a range of versions into your current version.

The steps are identical to those when reversing a version range. The difference is only that selected changes are merged into the current version rather than reversed from it.

To merge a version range:

  1. Right-click on a version marking the start of the range and select "Merge version range" from the menu.
  2. Right-click on the version marking the end of the range and select "Merge version range end".
  3. Optionally remove files from the list of changes that will be merged.
  4. Click Apply and provide a comment in the dialog that appears.
Closed Troubleshooting:
  • An error message indicates a conflict.

The change you are making affects an unsaved change, or possibly work being done by another developer. Examine the error message for details and resolve the conflict before re-attempting this action.

  • After this change, part of the application unexpectedly stops working.

The changes include a detail that may be critical to the operation, such as a changed I/O address. Restore the previous version, examine the version log in detail, then repeat your action taking care to avoid changes that will damage the application.


ChangeSets for Distribution

A ChangeSet is a file containing everything required to install a VTScada application on a workstation. They exist to distribute applications and updates for those applications to computers where "Get From Workstation" is not an option. The name describes the file: it is the set of changes that created the application. In other words, the version log.

Depending on how it was created, a ChangeSet may have the extension .ChangeSet, .Snapshot, or .Template. Each is a different type of a ChangeSet, meant for a different purpose. In this chapter, all are referred to as "ChangeSets".

Always use the right tool for the job:
* Use the VTScada Version Control system to roll back to an earlier version. NEVER use a ChangeSet for that purpose.

* In a networked environment, restore a workstation using Get From Workstation (Add New Applications). NEVER restore a networked workstation using a ChangeSet. A repository clash would be the likely result.

* If restoring a workstation that is not connected to a network, use a new ChangeSet created on a workstation that is up-to-date. NEVER use a ChangeSet that is older than the current version of your application.

* If planning a backup strategy, refer to Backups

* If branching an application, a ChangeSet is the right tool for the job. Branch an Application

ChangeSets do not include logged data, alarm history, I/O setpoint history, operator actions, or saved HDV pen groups.
The information in this chapter applies to only the application code, including tags, pages, custom drivers, etc.

ChangeSets do not include OEM layers. If your application was built on a layer other than VTScada, then for purposes of distribution, a separate ChangeSet must be created for that OEM application and distributed with your application's ChangeSet file.

ChangeSets and Evaluation Licenses or VTScadaLIGHT licenses:
If the ChangeSet was created under either an evaluation license, or a VTScadaLIGHT license, then it can be used to create a new application when running under a paid license.
It cannot be used to apply changes to an application already running under a paid license.
In short, developers must purchase a development license to do development.

Excepting template ChangeSets, do not store ChangeSet files in the application directory.

The details of what will happen when a ChangeSet is applied will depend on the type of ChangeSet you use - standard or snapshot, and if snapshot, with or without source files. It also matters whether the application runs on one or multiple servers. An incorrect choice may have undesirable results.

If you do development work for another site on an infrequent basis, keep your copy of the application up-to-date with the other site's. The best way to do this is to obtain ChangeSets from that site and apply them to your local copy. If you make changes to your out-of-date copy and then attempt to apply your ChangeSet to the customer's newer application, you run the risk of version conflicts. In the case of such a conflict, always choose to keep the existing version at the customer's site, never the one from your ChangeSet based on the out-of-date application.

To install a ChangeSet, you may either use the advanced menu of the Add Application Wizard, or simply double-click on the ChangeSet file.

ChangeSets and Version Control

ChangeSets contain an application's version history but should never be used as a substitute for version control. Consider the following example:

  1. On Monday, you create a ChangeSet of your application.
  2. You do development work through the week.
  3. On Friday, you use the Apply ChangeSet command in an attempt to roll back to the state of the application as it was on Monday.
  4. Nothing happens.

Apply Changes does not mean "over-write", it means "merge". Everything that is in your Monday ChangeSet file is still in Friday's version history, therefore there is nothing to merge. If your goal is to roll back to an earlier state of the application, use the Version Control system. (Version Control) Never attempt to roll back to an earlier version by deleting your application and then installing an older ChangeSet.

See also:Local versus Deployed Changes. If Auto-Deploy has been disabled on your workstation while making the changes that are included in the ChangeSet, then when applied to the destination computer, those changes will exist only in a local branch. Auto-Deploy relates to changes made to the application, not to the making of the ChangeSet.

Standard ChangeSets

These can include a full development history or just the history since a revision file was created. If auto-deploy is disabled at your workstation, you are advised to deploy changes before making a standard ChangeSet. Changes that are not deployed on your workstation will not be deployed on the destination workstation. (Local versus Deployed Changes)

This type of ChangeSet is used for the following tasks:

  • Initial installation of an application on a machine, but only if that workstation does not have a network connection to other workstations running that application.
  • Applying changes to an existing application, where those changes were made on a workstation that does not have a network connection.
    Changes within the ChangeSet will be merged into the current version.
    Note that one application's ChangeSet cannot be applied to other applications, including clones of the original.
  • Sending a copy of the application for technical support.
  • Creating a clone (identical copy) of an application to test changes without harming the running application or accidentally distributing your test to other workstations.
    The version history, stored in the ChangeSet, will not be visible unless you set the application property, RepositoryShowCloneHistory to 1. This property must be part of the section, "Layer" rather than "System".
  • Application recovery, using a recently created ChangeSet.
    You might choose to create a standard ChangeSet on a regular basis as part of a disaster recovery plan.
    If the application is still running on another server, do not use a ChangeSet to restore the lost workstation. Use "Get from workstation" instead.
    Remember that data is not included in a ChangeSet and must be managed separately.

Limited ChangeSets and Revision Files

When sending updates for a larger application, it can become cumbersome to include the entire version history with each new update. You can limit a ChangeSet to include only the changes that are not already present on the target machine.

Revision files will typically be created on the workstation that the ChangeSet is destined for, not on the machine where the ChangeSet is being created. The point is to find out what's already at the destination before creating the set of changes required to bring that workstation up to date.

Another use is to create a revision file immediately after creating each ChangeSet. (Both are created on the same machine.) When the time comes to send updates to the remote machine, you can use the revision file dating from the last ChangeSet to include and send only changes made since the previous update.

VTScada will compare the version information of the remote computer, as contained within the revision file, to the local version log to choose what new revisions need to be included in the ChangeSet being created.

As a best practice, you should obtain an updated revision file from the remote computer immediately before generating a ChangeSet destined for that computer. The following example illustrates the process, where changes need to be transferred from a development workstation to a remote workstation. The steps would be the same, but on opposite computers if the transfer needed to go the other direction.

Snapshot ChangeSets

These do not include version history. They hold only the current state of development of the application on the machine where the file is created. (Whether the current state includes local or deployed changes is not relevant. What is sent is the current state on that machine.)

Snapshots may or may not include source files, according to your choice. If source files are not included, it will not be possible to edit the pages, widgets or other components on the workstation where the Snapshot is installed.

When a Snapshot is applied to an application, it replaces the current version of the application, rather than being merged into it. Local changes will be lost.

An application distributed as a Snapshot without source files will run as a read-only application. The Idea Studio button will not, and can not, be enabled.

Snapshots are used for the following:

  • Installation of OEM layers, where the development work that went into that layer is proprietary knowledge.
  • Installation of applications on workstations that are licensed as run-time only.
  • Distribute changes to an application on a run-only workstation.
    If local changes exist, they will be lost when the snapshot is applied. This includes operational changes such as disabled alarms.
  • Return an application to a earlier state.
    In general, it is better to use the Version Control system for this purpose.
    Do not use a ChangeSet for this purpose if your application runs on multiple servers. Damage to the application on all servers may result.

You can install a ChangeSet by double-clicking the file on your desktop or in Windows Explorer™. If VTScada is not running, it will start.
Note that ChangeSets have a distinctive icon to help you distinguish these files from the shortcut to the VTScada executable file.

Troubleshooting:

  • If nothing happens when you double-click on a ChangeSet file in Windows explorer, it is likely that some other program has associated itself with this file type. Advanced users may check their Windows Registry settings to remove the following key, then reinstall VTScada to reset the file association and behavior. Proceed with care - damage to your system registry can leave a computer unable to operate.

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\FileExts\.changeset]

Template ChangeSets

Template ChangeSets are seldom required.

If you have a legacy OEM layer that made use of this technology, please consult with Trihedral Technical Support. It is likely that newer options exist, which will allow you to move away from the use of a Template ChangeSet.

The steps to create a Template ChangeSet are complex and will vary depending on your application and your plans for the ChangeSet. Consult Trihedral Technical Support before attempting to use this feature.


Create a ChangeSet File

ChangeSets do not include OEM layers. If your application is based on an OEM layer, you must create a ChangeSet for that as well.

Do no store ChangeSet files in the application directory. (With the exception of OEM Template ChangeSets.)

An application distributed as a Snapshot without source files will run as a read-only application. The Idea Studio button will not, and can not, be enabled.

If you intend to use a ChangeSet to distribute updates, you must select a type that matches how the application is running on the destination workstation. Do not send a Snapshot ChangeSet without source code if the application is running in development mode on the destination. Likewise, do not send a Complete ChangeSet if the application is in run-only mode on that target workstation.

To create a standard or snapshot ChangeSet:

  1. Ensure that changes are deployed if auto-deploy is switched off for your workstation. (Local versus Deployed Changes)
  2. Open the Application Configuration dialog to the Create ChangeSet File page.
  3. Select the type of ChangeSet to create.
    If creating a snapshot ChangeSet, choose whether to include source files.
  4. Click, Create.

A dialog box will open, prompting you for a file name. You can also select the directory where the ChangeSet will be stored. The extension ".changeset", ".snapshot" or ".template" will be added to whatever file name you provide.

  5. Type a file name for the ChangeSet.
  6. Click OK.

Revision Files

This applies only to standard ChangeSets, being used to update remote workstations.

When sending an update to a remote computer for a larger application, it may be helpful to limit the size of the ChangeSet by including only revisions that are not already on the remote computer. To do so, generate a revision file on the remote computer, and send that file for use when generating ChangeSet.

If you intend to send further updates to a remote workstation, you may wish to create a revision file on the current machine immediately after creating the ChangeSet. This can be used when generating the next ChangeSet to ensure that it includes only changes made since the previous one.

Optional step:

"Open containing folder after creating file" This option can save time if you intend to copy or otherwise work with the file immediately. This option is available for all types of ChangeSet.


Apply a ChangeSet File

Use the Apply ChangeSet page of the Application Configuration dialog when you want to import changes from another workstation that is running the same application, and is not visible via a network connection.

You cannot apply a ChangeSet file from one application to another.
Configuration privileges are required to apply a ChangeSet to a secured application.
If the ChangeSet is standard, then its contents will be merged into the application. If snapshot, then it will replace the application.

Do not attempt to apply a snapshot that does not include source files to an application that does.

It is possible that the changes coming from the ChangeSet may conflict with changes that have been made to the application on this machine. The Apply ChangeSet menu enables you to choose in advance, whether to use or discard the ChangeSet file's version in the event of a conflict.

ChangeSets and Security

If the ChangeSet you are applying includes modifications to user accounts and you do not have the Manager privilege then behavior varies depending on whether you are applying a .ChangeSet file or a .Snapshot file. (.ChangeSet files are typically used when remote developers are collaborating on the application. .Snapshot files are typically used by System Integrators when sending an update to a customer.)

  • If working with a .ChangeSet file, the security modifications are applied with the rest of the changes.

  • If working with a .Snapshot file, the security modifications are imported but not applied. You will be warned of this. A user who has the Manager security privilege can then use the VTScada Version Control system to merge the security modifications into the running version of the application. There is no need to apply the .Snapshot a second time.

Steps

The steps to apply a ChangeSet file are:

  1. Open the Application Configuration dialog.
  2. Select the Apply ChangeSet File option from the menu.
  3. Click on the Select button

A browse window will open, allowing you to find and select the .ChangeSet file.

  4. Select the file and click Open

A dialog will prompt you to confirm that you wish to apply the changes.

  5. Click "Yes"

The changes will be applied.

In the event of a conflict between versions, an error message will tell you which version was used and which ignored.

Add or upgrade a ChangeSet File by double-clicking it right in your file explorer. If the ChangeSet application already exists, it will be updated. If no application exists, a new application will be created and will appear in the VAM.

Related information:

Distribute OEM Layer Updates


Best Practices for Distributed Development

If you have a team of developers building an application, each using their own workstation, it is important to put procedures in place to manage updates. Whatever procedure you use will work best if it works in concert with the VTScada Version Control system, therefore this discussion begins with a review of that tool.

Proper configuration of your network configuration for VTScada is also important. Refer to Client / Server Configuration, and VTScada and VPNs, noting in particular the warning against using Network Address Translation (NAT) routers.

Version Control in a Networked Environment

Suppose that you have three workstations on your network, A, B and C, all of which are being used to develop your application. Machine A is the primary server in a simple server list, meaning that it is also the primary server for configuration. B is the backup server and C is a client workstation and therefore not part of the server list even though development work is done there.

The version control system works as follows. Assume that auto-deploy is enabled on all machines.
(Local versus Deployed Changes)

Example 1: Basic Changes

  1. A change is made on a workstation.
    Workstation B in this example. This creates a new entry in B's version log.
  2. That change is sent to the primary configuration server, A, where it is recorded in that version log.
  3. The configuration server sends the updated version log to all connected workstations including B where the change originated. This ensures that everyone is working with exactly the same revision and every machine can see the status of every other machine's version log.

What is transferred between machines is an update to the version log. The version log contains code for the triangle, which then shows up on the other workstation. But, it is important to note the distinction between transferring the code for the graphic (not what happens) versus transferring the update to the version log, which contains the code for that graphic. Because the version log update includes information about the time when the change was made, the machine where it was done, the developer who was signed in, and other contextual information about this change, it is possible to blend changes at a code level.

Suppose that another developer is at machine C and is working on improvements to the same page. Thanks to the version control system which is managed at a single server, that developer's changes can be merged with the changes being made at B. The only time there would be a conflict is if they both edit the same line of code and save their changes at almost exactly the same time. In that case, the first version to arrive wins and the second is lost. You are advised to avoid having two developers work on the same page, widget, or tag at the same time.

Example 2: Auto-Deploy Switched Off

If auto-deploy were turned off at machine B and the addition of the triangle was local, not deployed, the same process would still happen. Every version change, deployed and local, follows the process described, and the triangle will be included in the update distributed between machines. But developers at workstations A and C would not see the triangle until the developer at B chose to deploy changes. All updates to the version log (both local and deployed), made on all machines, continue to be sent to the primary server A, which then distributes the combined history back to all machines.

Suppose a deployed change is made on C while B continues to work with auto-deploy turned off. Thanks to the process just described, the developer at B will see the change from C immediately, but it will not interrupt any work that they are doing unless the changes conflict directly with their undeployed work.

Example 3: Verify a Merge Off-Site Before Applying to the Server

You may need to test a combination of changes at an off-site location before applying those to the server. This is a less common work flow, typically used when a workstation has been isolated from other servers for a time and you are unsure what work might have been done at that workstation in the meantime. The recommended steps in this case are:

  1. Create a ChangeSet on the server.
  2. Apply that ChangeSet to the off-site workstation.
  3. Review and test the changes at the off-site workstation.
  4. When satisfied, create a new ChangeSet on the off-site workstation, take it to site, and apply it to the server.

At this point, the configuration on the server will match the configuration on the server (with the addition of any changes that have been made on the server since the ChangeSet was created in step 1, which, like always, will merge with the changes being applied in the ChangeSet).

Example 4: Breaking the Version History

This is an example of a practice to avoid. Let's look at a way to break the version log using a ChangeSet.

The following is an example of how NOT to work. Do not do the following:

  1. On a Monday, the developer at workstation A creates a ChangeSet.

    A ChangeSet is a single file that contains the version log.
  2. The developer looks at the version history and notices that they are at A-D100 (for deployed revision 100 at workstation A).
  3. The developer does a day's work, advancing to revision A-D200.
  4. At that moment, they realize that they have bad information for the design and now want to rewind to the earlier state.
  5. Meanwhile, development has been continuing at B and C. The version history contains a mixture of revisions from all three workstations, each with a number, a timestamp and other contextual information.
  6. Developer A attempts to undo their work by deleting the application, then installing the ChangeSet.

This scenario does not end well. If the workstation A is connected to the network, then the repository is synchronized immediately and A is back at A-D200. If A is temporarily disconnected from the network, then the developer might create a new change, A-D101. Machine A is then reconnected to the network. But the recent A-D101 change is not the same as what B and C know as A-D101. This creates a "repository clash" with extremely disruptive results.

In a networked multi-server environment, NEVER attempt to restore an application on one server by using an old ChangeSet from that station.

Version Control in a Distributed Environment.

When attempting to bring a remote workstation up to date, a common impulse is to delete the application then re-install from a ChangeSet. Sometimes an older ChangeSet.
>> Don't do that. <<
It's better to apply a new ChangeSet from an up-to-date server and go. This is always the cleanest and fastest method to use.

In a distributed environment, workstations are not networked and the version control system cannot distribute updates continuously and automatically. To ensure that development continues smoothly, you need to mimic the function of that system by using ChangeSets. A ChangeSet is the set of changes that make up the application. In short, the version log.

Your first step is to select one workstation that will be designated the Primary Server. That might actually be the primary server within one office, or all workstations might be working completely independently with none having a server list. In either case, the step is the same - select a workstation and call it your Primary Server for configuration changes.

Implement the following work flow:

  1. Ensure that Auto-Deploy is turned ON.
    In this scenario, there is nothing to gain, and potentially much to lose by turning off Auto-Deploy. While there might be a case for the careful use of local changes in this scenario, these are difficult to manage in practice.
  2. Create the application on workstation A (the designated primary server in this example).
  3. Create a ChangeSet file.
  4. Send that ChangeSet file to B and C and tell them to use the Get From ChangeSet tool in the Add New Applications wizard.
  5. The same application now exists on all workstations and everyone can begin development.
  6. A set of changes are made on a workstation. (B)
    This might be a single change, a day's work, or a week's work, but the more often the better.
  7. At that workstation, create a full ChangeSet file.
  8. Send that ChangeSet to the designated primary configuration server.
  9. At workstation A, use the tool "Apply ChangeSet", found in the Application Configuration dialog.
    (Apply a ChangeSet File)
    All of B's changes will be merged into the master version log.
  10. If a ChangeSet has arrived from another workstation, apply it as well.
  11. At the Primary Server, create a full ChangeSet file.
  12. Send that file to B with instructions for them to use the Apply ChangeSet tool.
    This ensures that everyone is working with exactly the same revision.
  13. Repeat as necessary: When changes are made on C, send those from C to A and then send an updated ChangeSet back to C.

Best Practice Guidelines:

  • Ensure a two-way exchange of ChangeSets between remote workstations and a designated primary configuration server.
  • Do not exchange ChangeSets between the remote workstations. Send all updates back and forth only to the designated primary configuration server.
    (You are allowed to choose a different primary configuration server from time to time as needed. When doing so, ensure that it has the latest ChangeSet from the previous primary.)
  • Trade ChangeSets frequently so that all machines remain up-to-date.

It is possible but risky, to continue development while waiting for ChangeSets to flow back and forth. Better to wait for the exchange to be completed. If you must continue to work, do so on a new page or feature, thereby reducing the chance of conflict with another developer's work.

The following practices must be avoided:

  • Never restore a workstation with an old ChangeSet.
    In a networked environment, use Get From Workstation instead. Never use a ChangeSet, new or old.
    In a distributed environment, contact the developer at the designated Primary Server and request that a new ChangeSet be made.
  • In a distributed development environment, never send ChangeSet updates between machines that are not the designated Primary Server.
    All updates must flow to the Primary Server, then from that machine back to all development workstations. Never take shortcuts.


File Management Tools

A VTScada application is stored as a set of files within a folder.

If your VTScada license is for a run time only release and does not include configuration options, then only the run time version of your application files will have been distributed to you. You cannot view or edit those files. If you have a configuration license for your VTScada installation, and source code files for your application, then you can review pages and configuration settings directly in files, and may perform configuration by editing those files.

VTScada is able to detect when files of the recognized types have been added, removed or edited in the application folder. These are flagged, but not used until an authorized person uses either the Import File Changes button or the Import/Export Files dialog.

VTScada makes a distinction between "user files" (those that humans can be read), "working files" (compiled versions of the user files), and "repository files" (working files that are part of the version control system). Work only with the user files. Any attempt to modify a working file or repository file will either be ignored, or cause irreparable damage to your application.


Import File Changes Tool

The Import File Changes button in the VAM will import new files, import changes to known files and recompile the application. It will not provide a chance to review changes before doing any of those tasks. To review changed files use the Import File Changes Page

Only operators who possess the Edit Files privilege may use this feature. Do not use if there is any possibility that someone else has had access to your workstation to edit or add source code files.

  1. The application is activated if it was not already. This activates the version control system for the application.
  2. VTScada will scan for new files in your application folder and prompt you to confirm which ones you want to import (put under version control). Not all file types are included. For example, .BAK files are ignored.
  3. All changes to files under version control are imported. You are not given a chance to review those changes.
  4. All source code is recompiled if changes are found.

If no changes are found, and the application is not running, then you will have an opportunity to force a recompile. If the application is running, then the process ends with the "no changes detected" dialog.

The Import File Changes tool provides a convenient method for developers who are working directly with source code files to import their changes. (Changes and additions to source code files are ignored by VTScada until imported). Note however that the lack of an opportunity to review changes carries a certain degree of risk. If there is any chance that someone else may have edited the user files, then you are advised to use the Import/Export Files dialog, where you can review changes before importing them.

Dialogs associated with the Import File Changes operation:

Import New Files

VTScada has found new files in application folder. All are selected for inclusion if you click OK. You may choose to deselect any of the files before clicking OK, or you may click Cancel to abort the Import File Changes operation.

Note that all files that are deselected before you click OK to finish the Import File Changes operation are added to VTScada's "ignore" list. If you click Import File Changes a second time, you will see the message, "No changes detected". There is no second opportunity to select the files using this button. Use the File Manifest in the Application Configuration dialog if you wish to add those files to the application at a later time.

Compile - No changes detected

If you expected changes, ensure that the files you edited were saved using their original names and folders. Files that were not imported the last time this button was clicked are now being ignored. You can use the File Manifest page of the Application Configuration menu to add them now.


Import File Changes Page

See also: Import File Changes Tool

Changes made outside of VTScada to the files that are part of your application are ignored. An authorized operator (one who possesses the Configure and the Edit Files security privileges) must import the changed file before VTScada will use it.

Tasks in this topic:

Review changes before importing:

Import new or changed files:

Discard changes in files:

Export latest (VTScada changes to files):

For source code and text files, you may review the changes, line by line before importing them. The new version of the line (in the file being imported) is marked in green and the old version (the current version in change control) is marked in yellow.

Image files are compared on a side-by-side basis.

You should always review all the changes within a file before importing it into your application.

Review changes before importing:

  1. Open the Application Configuration dialog.
  2. Click Import File Changes.
  3. Look for categories of files with plus signs.

The plus sign and the number beside the category name indicate that new or changed files were found.

  4. Expand the category to view the file(s).
  5. Click on the name of a file to examine. Changes are highlighted as shown at the beginning of this topic.

Import new or changed files:

Check marks beside the file names indicate which files to include in this operation.

  1. Open the Application Configuration dialog.
  2. Click Import File Changes
  3. Examine the changes within the files you intend to import.
  4. Click to select each file to import. You may use Select All to speed this process.

Only files indicated with a check are imported.

  5. Click Import.

Discard changes in files:

After reviewing changes, you may decide to not import them. In this case you may wish to replace the contents of the file with whatever is in use within your application.

  1. Open the Application Configuration dialog.
  2. Click Import File Changes.
  3. Click to select each file to discard. You may use Select All to speed this process.

Only files indicated with a check are discarded.

  4. Click Discard

The file on disk are replaced by the current version in the application's repository.

Export latest (VTScada changes to files):

Export Latest will merge changes from VTScada into the file on disk. In normal operation, this is done automatically, but the button exists to allow you to force a merge.
The user copy file is not overwritten by VTScada, but changes made in VTScada are merged into that file. Changes within that file that have not yet been imported are preserved. Conflicts are reported on a line by line basis if they occur.

  1. Open the Application Configuration dialog.
  2. Click Import File Changes.
  3. Click to select each file to discard. You may use Select All to speed this process.

Only files marked with a check are discarded.

  4. Click Export Latest

The file on disk is updated with current version in the application's repository.

Troubleshooting:

  • Your edited file is not listed in the Import File Changes menu.

Ensure that edits are saved.

Click Reload to refresh the display.

  • A file you copied to your application folder with the intent of adding it to the application is not found.

Files with extensions that are common to other programs, such as .DOC, .XLS, .TXT, etc. are ignored. If needed, they can be added using the File Manifest. (Maintain the File Manifest)

  • An error message reports a conflict.

Review the conflict using the Version Log and a text editor. Depending on whether the changes in VTScada or in the file should have priority, you may edit the file to resolve conflicts, use the Import button, or use the Discard button.


Maintain the File Manifest

The File Manifest, a page of the Application Configuration dialog, lists those user files that are monitored and maintained by the VTScada version control system. You may add files to the list if you want to distribute them with the application and maintain them under change-control. You may also remove certain files from the list, although in the case of the VTScada-created files this is not advised. Files that you can remove are marked with green. VTScada files that you cannot remove from version control are indicated by red check boxes.

The File Manifest will not include empty files.

Removing a file from version control does not delete the file.
A file marked as ignored is not recognized by the Import/Export Files page until you add it back in using the Maintain File Manifest tool.
Ensure that files are not open in an editor before applying changes made using the File Manifest. Failure to obey this rule may result in version control conflicts.

Red boxes are for VTScada files that you cannot remove. Green boxes are for files that you can. Be warned that just because you can remove a file, does not mean that it is a good idea to do so.

Add a new file to your application using the File Manifest:

In this example, a new background image is copied to the Bitmaps\Backgrounds folder of the application. It is ignored by VTScada until made a part of the application, as follows:

  1. Open the Application Configuration dialog.
  2. Click Maintain File Manifest.
  3. Expand the folder tree to view the contents of the Bitmaps\Backgrounds folder.

Note: If you copy or move files while this dialog is open, click Reload to refresh the display.

  4. Click on the check box beside the name of the file to add to version control.
  5. Click Apply.
  6. Provide a comment when prompted, and click OK.

The selected file is now considered part of the application. It is subject to version control and included in a ChangeSet.

Remove a file using the File Manifest:

It is possible that files that were useful during development should not be included in a ChangeSet shipped to a customer. Best practice is not to save those files in the application folder, but if they were, you can remove them from the application (without also deleting them) as follows:

  1. Open the Application Configuration dialog.
  2. Click Maintain File Manifest.
  3. Expand the folder tree if required to view the contents of folder where the file resides.

Note: If you copy or move files while this dialog is open, click Reload to refresh the display.

  4. Click on the check box beside the name of the file that is to remove from version control, thereby clearing the check mark.
  5. Click Apply.
  6. Provide a comment when prompted, and click OK.

The selected file(s) are no longer considered part of the application. They will still exist in the application folder, but are not included in a ChangeSet.

Troubleshooting:

  • The file isn't shown in the File Manifest.

Empty files are ignored by VTScada. Ensure that this file is not empty.

If the file was recently copied, click Reload to refresh the display.


Document Your Application

After creating an application, it's not a bad idea to provide instruction for the people who will be using it. There are several ways that you can do this. The following is a list of your options from easiest to more challenging:

Place helpful text on your pages.

Use standard, single-line Text for short notes and Multi-Line Text Widget for paragraphs.

Use Tool Tip Widgets

These reduce screen clutter while still providing a brief note that is visible only when someone hovers over the widget.

Create context-sensitive labels with Multi-Text Widgets.

These can contain up to 16 messages, each of which is shown at progressively higher values of a linked tag.

Link Program Spawn Widgets to PDF files.

Use any text editor that can save to the PDF format to create concise instructions with all imperative details. There is no limit to how many program spawn widgets you can draw, so keep the content of each file focused on a specific task. When an operator clicks the widget, your file will open using the default PDF viewing program installed on your workstation. (This is usually your web browser, unless otherwise configured.)
When configuring the widget, there is no need to specify a viewing program. Simply enter the full path and name of the file to be opened. The label on each button should tell the user what they can expect to see after they click.

Create a user-defined help widget and a parameterized page.

You can create your own help pop-up that will display custom text that you store in tag instances. See Create a Help Widget for an instructional tutorial.

Use one of three methods to implement F1 help in your system.

These are advanced configuration options and two of the three require the purchase of a help authoring program, but they provide a way for you to implement the "press F1 for help" paradigm instead of using a label or button.
Refer to the reference topic, Custom Help Files.


Create a Help Widget

With a user-defined widget, a parameterized page, and a short expression, you place a "Help" button anywhere that is helpful to display instructions or other information that you store in any tag.

This advanced tutorial topic assumes that you are already know how to create Parameterized Pages and how to Create Widgets. If not, you are advised to learn to use those features before proceeding. This advanced tutorial skips steps that someone familiar with those technologies would know.

Elements:

Tags

You will use the Help Key field of your tags to store the instructions. This is a non-standard use of the property and therefore somewhat at risk of breaking should Trihedral change the definition of that property in a future release. However, due to the fact that this property is widely employed for non-standard use, that risk is remote.

User-defined widget

In the preceding example, the visible portion of this is simply a circle and a question mark. The widget is defined as a "Tag Widget" and configured such that it can be linked to a wide selection of tag types.

Within the widget is a page hotbox that uses an expression to pass contents of the linked tag's HelpKey field to a parameterized page.

Parameterized page

This is a pop-up page containing a Multi-Line Text widget. The widget is configured to display whatever is passed to the page via its parameter.

For visual clarity, the widget in the preceding example uses the Analog Font.

Steps:

A) Create the Parameterized Page

  1. Use the Idea Studio to create a new pop-up page.
    1. Give the page a descriptive name and title such as "Help Notes".
    2. Do NOT add it to the menu system.
  2. Add a parameter to the page.
    1. Give the parameter a name such as "TagWithHelp".
    2. Set the parameter type to Tag.
    3. Select all the tag types that you might want to use with this system. (You can edit the parameter later to add more.)
  3. Add a Multi-Line Text widget to the page. (Important - do not use any text or widget other than the Multi-Line Text.)
    1. Size the widget to accommodate any message that you might want to display.
    2. Select a font that is relatively easy to read. (You might create your own.)
  4. In the Home ribbon of the Idea Studio, click the Source Code tool to open the page in a text editor.
  5. [Important] Close the Idea Studio before making any changes to the page using the text editor.
  6. Within the text editor, look for the line that begins, Scope(\Code, "Library", TRUE)\DrawMultiText(
  7. Modify this line as follows. The example shows only a portion of the line, emphasizing what to modify in bold text. Do not delete code that follows this portion of the example.
 Scope(\Code, "Library", TRUE)\DrawMultiText(TagWithHelp\HelpKey, 0, 0,
  8. Save the text file.
  9. In the VAM, use the Import File Changes button for your application.

B) Create the Help Widget

  1. Working in the Idea Studio, use the File menu to create a new Tag Widget.
    1. Select all the tag types that you might want to use with this system. The selection set should match that of the parameter you created earlier.
    2. Give the widget a name such as "Help Reference".
    3. Deselect the "Include..." options.
  2. In the upper left corner of the widget, draw whatever shape you want to use to represent "click here for help". The example at the top of this topic used a circle with diameter 20 pixels and a question mark.
  3. Overlay the symbol with a Page Hotbox widget.
  4. In the Page Hotbox widget, select the "Help Notes" page.
  5. Configure the parameter to use Linked Tag as shown:
  6. Save your work.

Put it All Together

  1. Open the properties dialog of a tag (choose a type that was included in the lists earlier).
  2. Type a message in the Help Key parameter, then close the dialogs.
  3. Draw your new widget on a page, then link it to the tag you just modified.
  4. Close the Idea Studio, then click on your widget. A window should pop open, containing the message you put in to the tag's Help Key field.
  5. Refine the appearance of the page and widgets to suit.


Troubleshoot

VTScada provides a set of utilities to assist with troubleshooting, analysis, and debugging. In general, the diagnostic utilities are useful to:

  • Programmers when writing VTScada script code.
  • Customers when directed to use a tool by VTScada support staff, in order to diagnose a problem.

These tools are designed to be functional, rather than user-friendly. Most utilities are not listed in the VAM by default, but can be added using the Find Existing option of the Add Application Wizard. The most versatile and powerful of VTScada's diagnostic utilities is the Source Debugger. Start here when attempting to diagnose performance issues or debug code.

For a complete list of messages that can be written to the Windows Event Log, refer to Event Log Messages - Event ID 1001

A lack of memory or disk space can cause many problems including slow performance, difficult or failure to log, difficulty or failure to distribute updates.
Check the available space on every server on a regular basis. If the percentage available is becoming small, consider options to clear space or (if this is an Historian server) to install a larger drive.

Tips and Techniques
A collection of troubleshooting tips, optimization techniques, and assorted helpful suggestions.

Coordinates Application
Small window showing the coordinates of the cursor within any VTScada window.

Debugger Utility
Early version of the Source Debugger. Rarely used now.

Instance Count Application
Counts the number of instances of all modules in all running applications.

Memory Tracer Application
Can be used to trace high memory usage to specific modules.

RPC Timing Utility
Monitor the time required by server-to-server messages.

Test Framework Application
Use to run tests that you have created to prove that your script code is working properly.

Thread List Application
Shows a list of all threads in use by VTScada.

Trace Viewer Application
Monitor inter-server communications, device driver communication, or SOAP messages.

Trace VTScada Actions Application
Monitor actions of selected VTScada services.


Tips and Techniques

A collection, old and new, of troubleshooting tips, optimization techniques, and assorted helpful suggestions.

Refer to the side menu for navigation.


Add Scroll Bars to a Page

You may need to add scroll bars to the VTScada display if you are attempting to edit an application while using a monitor that is smaller than the one that the application was created on. This can be done in a way that affects only your workstation. To force scroll bars (when a page is larger than your monitor) set the width and height (DispMgrWidth and DispMgrHeight) to match your current screen size.

Step by step:

  1. Open the Application Configuration dialog.
  2. Select the Edit Properties page.
  3. Find and select the property DispMgrWidth.
  4. Click Copy.
  5. Set the width value to match your display.
  6. Enter your workstation name in the space provided. (You may be able to select it using the drop-down list.)

  7. Repeat for DispMgrHeight.
  8. Click Apply.
  9. Provide a comment in the dialog that opens and click OK.
  10. Click OK to acknowledge that the application must be restarted before the changes will go into effect.
  11. Re-start the application on your workstation.


Alarm on Low Disk Space

VTScada requires available disk space in order to continue logging and continue operating. Rather than checking the disk regularly, you might create an alarm that will warn you when the available space runs low.

The amount of space required for VTScada, and the setpoint at which you want to be notified so that you have time to take action will vary according to your application. For this example, 50Mb is used, but that number is randomly chosen for the sake of the example.

  1. Create a Workstation Status Tag
    The workstation name should match the machine you want to monitor.
    To monitor several workstations, create a Workstation Status tag for each.
  2. Create a new I/O and Calculations tag as a child of the Workstation Status tag.
    The remaining steps refer to the configuration of this tag.
  3. On the ID tab, set the mode to Analog.
  4. On the I/O tab, set the Read Address to FreeDiskSpaceC
    (Or, FreeDiskSpaceD if monitoring a D: drive. Refer to Workstation Status Driver I/O Addressing )
  5. On the Scaling tab, ensure that both Unscaled and Scaled process data values range from 0 to 100.
    The numbers chosen do not matter, so long as both the unscaled range and the scaled range match.
    If you prefer to work in Mb or Gb rather than bytes, configure the scaling as appropriate.
  6. On the logging tab, either disable logging, or if you choose to log this tag, set the deadband to a value of at least 1Mb (1048576) if not 10Mb (10485760).
    There is no need to log every one-byte change in the available space.
  7. On the Alarms tab, select a Low Alarm priority as appropriate.
  8. Configure the setpoint of that Low Alarm to be 52428800
    (50Mb in this example. You may choose a setpoint as seems appropriate.)


Anywhere Client Graphics are Blurred

This tends to happen when the application’s minimum window size has been set too small. This can be set in the Application Configuration dialog or via a Realm Display Setup tag, with the RDS tag settings taking precedent.

The default minimum window size (if the fields are left blank) is 1366x768. This will end up being the resolution of graphics displayed on a small screen like a phone. Smaller resolutions are not recommended as some VTScada dialogs will not be fully visible (particularly at smaller heights).

If the minimums are set to, say, 1, then what will happen is the client will be displayed using a resolution that matches the device’s CSS/viewport resolution, and not its physical resolution. The CSS viewport resolution is based on the screen’s size, not its resolution (the relationship between the screen size and CSS viewport resolution is the device’s "Device Pixel Ratio"). For example, the iPhone 6’s viewport resolution is 375 x 667. With only so many CSS pixels to work with, VTScada graphics look poor. The simple solution is to get rid of the minimum size setting so that it defaults back to 1366x768.

There is also a problem with going larger. For example, at 1920x1080, even though the graphics will be sharper on a phone, they will also be smaller and hence harder to interact with on the small screen.


Cloning a VTScada Workstation

Do not clone a VTScada workstation.

Cloning a VTScada workstation for installation on a new computer will also clone the unique machine identifier (UMID), which VTScada generates for each workstation. Running two machines with the same UMID may cause corruption of the configuration repository.

Recommended practice to avoid this situation is to install VTScada on the new machine and use the Get From Workstation tool in the VTScada Application Manager to transfer the application to that machine from another workstation.

If you have cloned a workstation, the existing UMID must be deleted from the registry before running VTScada on that machine. Contact Trihedral Technical Support before proceeding.

Related information:

Backups


Communications and Firewalls

Occasionally, a customer will report a communication issue that can be traced to their firewall rules. Because these may be managed by the Windows firewall utility, a third-party program, or both, it can be difficult to diagnose.

During installation, VTScada adds firewall rules only to enable communication in the domain and private profile. If VTScada must access a device in the public profile, you will need to create appropriate firewall rules. As a general principle, this is not encouraged. On a public profile, open only what is absolutely necessary. A better solution is to configure your systems so that VTScada can communicate with devices on the domain or private profile.

Instructions for Windows firewall configuration are well outside the scope of this documentation. You are encouraged to seek expert advice.


Email Error Codes

The following error codes are produced by VTScada. Your email server may produce others.

Error | Meaning
0 | Mail has been successfully sent.
1 | Unable to open a connection to the server.
2 | Server did not send a good SMTP welcome message.
3 | Server rejected SMTP HELO message.
4 | Server rejected SMTP MAIL message.
5 | Server rejected SMTP RCPT message.
6 | Server rejected SMTP DATA message.
7 | Server rejected message body.
8 | Badly formatted TO: address.
9 | Server does not support AUTH.
10 | Server does not support implemented AUTH. mechanisms.
11 | Failure to login to SMTP server.
12 | TLS wanted for SMTP, but not available
13 | TLS unavailable or negotiation with server failed
14 | Badly formatted bcc address


Ethernet to Serial Converters

VTScada supports the use of Ethernet to serial converters, also know as terminal servers, to allow connections from VTScada servers to serial I/O devices.

These provide a viable option to RS-232 cards, which are increasingly difficult to find. Experience indicates that USB to Serial converters may be unreliable. But, the most significant reason to consider a converter is redundancy. Unless the remote device has two serial ports, only one computer can be connected to it at a time. If the VTScada computer making that connection goes down, there is no failover until the second computer is connected.

With an Ethernet to serial converter however, the serial side can be connected to the device and the Ethernet side to a switch. VTScada can then be configured with a TCP port and any VTScada computer can become a redundant server for the IO.

Most of our drivers that support serial protocols can be used with these devices if you use the following configuration. (This list is the minimum required configuration. More steps may be required in some cases.)

  • Protocol mode set to "Raw"
  • Device listens for a connection from VTScada on a specific TCP or for packets on a UDP port
  • Device does not initiate the connection to VTScada
  • Device’s serial port settings (baud, parity, start & stop bits) are configured to match the I/O device
  • "Inactivity Time" automatic disconnect in the device set to a longer time period than the VTScada driver’s "Timeout" setting

After the driver is configured, use a TCP/IP or UDP/IP port tag with the appropriate VTScada serial driver to communicate through the device to your serial I/O device. If you are experiencing issues with communication when using the device that you do not see when connected directly using a serial port on your server, there could be problems with the device’s configuration. Common problems include:

  • The data packing scheme used by the device is based on it receiving specific characters that may not be present in the serial protocol.

Some devices allow multiple TCP/IP connections from multiple servers (VTScada and others). These setups work well with simple protocols that involve simple command response messaging (such as Modbus) but can cause problems with protocols that use more complex messaging schemes.

  • Devices sometimes "escape" data received on the serial port before forwarding to the Ethernet.

When this happens, specific characters received once on the serial port are doubled when the messages are sent on Ethernet. These typically show up as CRC or checksum errors in the VTScada drivers and can be difficult to diagnose without a good knowledge of the protocol details. The most common of these are on characters 0h10 (the ASCII DLE (Data Link Escape) character) and 0hFF. Note that many protocols also "escape" the ASCII DLE character, making this problem difficult to diagnose.

If you are having problems when using an Ethernet to serial converter that you don not have when connected directly via serial, search first for known issues with the device you are using.


HDV Problems in Remote Desktop Sessions

When connecting to VTScada through a remote desktop, you may find that the colors used for each pen in the legend appear to be the same. In particular, with remote desktop sessions accessing VTScada on a Windows Server 2008™ system, colors in the HDV may appear incorrectly, as the Windows Remote Desktop Session host, in its default setting, will limit remote desktop sessions to 16-bit color.

You can remedy this as follows:

  1. From the Windows Start button, click to open "Administrative Tools".
  2. Click to open, "Remote Desktop Services".
  3. Click to open, "Remote Desktop Session Host Configuration".
  4. Under the list of connections, right-click on the connection and select Properties from the menu that opens.
  5. Open the Client Settings tab of the properties dialog.
  6. Clear the Limit Maximum Color Depth check box.
  7. Click OK to save your work and close the dialog.

If a remote session desktop is running, both it and any running VTScada program on the remote machine, must be restarted before the change will go into effect.


Historian (or other files) Locked

When using paths outside of VTScada install folder, the user must be careful about NTFS permissions. VTScada has no control over these.

In particular, never run VTScada as administrator as the files it creates will be owned by the administrator group, and not writable by a normal account if you later run VTScada as a normal user. A similar problem will occur if switching the user accounts.

The VTScada installer sets appropriate permissions on it's own folder at install time, but external folders are out of the installer's control. To recover, use Windows configuration tools to switch ownership of the files in question so that they can be read by the account under which VTScada is now running.


Host is not in the Server List

This message might be seen when attempting to connect via a Thin Client. Typically, it means exactly what it says: the host to which you are attempting to connect is not part of the server list of available hosts. But there are a number of reasons why that might be the case.

Check all the following:

  1. Are you using a URL or IP address that is included in the server list?
    If not, the easiest fix is to use one that is. But perhaps the server list is missing an address that should have been configured.
  2. Are you using a reverse proxy and a version of VTScada older than 12.1.27?
    If so, there is a fix for this in newer versions of VTScada. The solution is to upgrade.
  3. Are the servers using a Network Address Translation table (NAT)?
    VTScada is not compatible with Network Address Translation tables.

For further notes see:

  • Thin Clients: Mobile and Internet
    • Servers in a Demilitarized Zone (DMZ)
    • Network Configuration
    • Domain Aliases (CORS)


Internet Connection Troubles

If you have configured a VTScada Thin Client Server, but are unable to connect to it, try the following options:

  • If you are using VTScada Light, you must use a VPN for Internet / mobile access from outside your network.

  • A common problem is that some other program is using port 80 on the server. Reconfigure to use port 81 or 8080.

  • Ensure that your application is secured and that you have granted the Thin Client Access privilege to the account you are using to sign in. This privilege is not granted to any of the default roles.

  • Realm Filtering is configured and you are trying to connect as a super-user without having made that possible by configuring the RootNamespace property to assign a realm for users who are not part of any security group. The value of RootNamespace must not match any defined security realm.

  • Realm Filtering is configured and you are trying to connect to a realm other than the one matching your security group.

  • VTScada Thin Client Servers can be configured only if you are signed in at one of the machines included in the server list. In other words, you cannot configure a Thin Client Server List unless you are working at one of the machines that is a member of that list.

  • If your VTScada Thin Client Server is protected behind a firewall, consult with your IT department to configure access.

  • Internet File Cache Failure. Typically indicates a full hard drive, a cache that has reached it maximum size, or both. Check the amount of free space on your hard drive and use the tools within your browser to clear the cache.


Generate a Crash Dump from the Source Debugger

While the following instructions are true, it is better to generate a dump file using the Windows Task Manager.

The Source Debugger is a script application that is included with every copy of VTScada. If you do not see it listed in the VAM, you will need to add it to the application list.

Dump files created by the Source Debugger will typically be between 150 and 200 megabytes in size.

  1. To start, run the Source Debugger.
  2. Ensure that your application is also running.
  3. Click on the Create Dump File button in the Source Debugger.

  4. Browse to the location where you wish to save the dump file. You can expand the dialog box to show the folders and files by using the Browse Folders button in the lower left corner of the dialog box.
  5. Enter a name for the dump file in the File Name field.
  6. Click the Save button. The dump file will be generated and saved in the specified location.
  7. Contact Trihedral Technical Support for instructions on where to send the dump file.


Modem Installation Issues

When installing a voice modem, ensure that you follow all the steps provided in Install a Voice Modem.

For example, if you encounter the error:

Call failed to [UserName] on [PhoneNumber]: TAPI error [14] -
The Telephon.ini file cannot be read or understood properly by TAPI because of internal
inconsistencies or formatting problems

The cause is failure to complete step 4 of the modem installation process.


Monitor Servers, Disk Space, and Memory

Customers frequently ask for a way to monitor server health, or the amount of free disk and memory space available. These tasks can be accomplished with Workstation Status Tag

To configure, create one Workstation Status tag for each server that runs your application. The Workstation tab of each tag holds a configuration field where you can select the workstation name.

A Workstation Status driver, configured to monitor the primary server.

Monitor Server Status

The Workstation Status tag will have a value of either 0 (meaning no error) or Invalid (meaning no connection). You can use this fact to create an alarm when a server is offline. In the following example, an Alarm tag was created as a child of the Workstation Status Driver, Primary Server. The triggering expression is

! Valid([Primary Server])

where [Primary Server] is the name of the Workstation Status tag in this example. Substitute the name of your own tag for your alarm expression.

The alarm is triggered when the connection to the parent tag, [Primary Server], is lost.

Add an On Delay of one or two seconds to the alarm configuration. Whenever the application restarts, there will be a moment between the tag starting and the workstation's status being reported. During that time, the driver's value will be INVALID and will trigger the alarm unless you configure a delay. This will also avoid alarms due to transient network interruptions.

Monitor Free Disk Space

Refer to Workstation Status Driver I/O Addressing for a list of workstation properties that you can monitor. For this example, the goal is to trigger an alarm when the free space on drive C: falls below 50Mb. (50Mb is 50*1024*1024 = 5324800 bytes)

To do this, create an I/O and Calculations tag as a child of your Workstation Status driver, configured as an analog. Key details of the configuration are shown in the following two figures.

Detail showing the read address of an Analog I/O tag attached to the Workstation Driver

Alarm setpoint detail from that same tag.

The disk space would be easier to read if measured in megabytes.
Do so with the Scaling tab, setting the Unscaled Process Data Max to 1048576
and the Scaled Process Data Max to 1.

Applying this to the previous example, you would then be able to use 50 as your alarm setpoint instead of 5324800.
To scale for gigabytes instead of megabytes, multiply the Unscaled Process Data Max by 1024 once more: 1073741824

Monitor Memory Space in Use

Refer to Workstation Status Driver I/O Addressing for a list of workstation properties that you can monitor. For this example, the goal is to trigger an alarm when the memory used by VTScada rises above a given level, or when the rate of change over a period of time remains positive.

To do this, create an I/O and Calculations tag as a child of your Workstation Status driver, configured as an analog and also a Rate of Change tag monitoring that I/O tag. Key details of the configuration are shown in the following figures.

In this example, the I/O tag is scaled from bytes (1048576 for the Unscaled Process Data Max) to megabytes (1 for the Scaled Process Data Max). High memory usage in this example is defined as 800Mb. Your value will differ. Monitor your system over several days to gain a sense of the normal memory requirement and choose an alarm setpoint above that.

Monitoring the memory in use:

Detail showing the read address of an Analog I/O tag attached to the Workstation Driver

Alarm setpoint detail from that same tag.

Monitor for increasing memory use over 15 minutes:

Detail of the Rate of Change tag. 900 seconds is a 15 minute period, refreshed every minute.

In this example, the rate of change must remain over 0.5 for five minutes (300s).

Estimate Days Left Before Your Hard Drive is Full

The following example is for advanced developers who are comfortable with scripting expressions.

It is possible to configure tags to provide a broad estimate of the time remaining before your hard drive fills up. You can do this by measuring the remaining space, measuring the rate at which space is being used and performing a calculation. The more consistent hard drive use is, the more accurate the estimate will be.

The scenario: You want to monitor hard drive C:\. Your application uses up space at a relatively steady rate and you'd like to know how many days of storage are left.

Four tags will be used:

  • Workstation Status tag
    • I/O & Calculations (Analog)
    • Rate of Change tag
    • I/O & Calculations (Analog Calculation) tag

Create a Workstation Status tag to detect remaining hard drive space.

Create an analog I/O tag as a child of a Workstation Status tag. Set the Read Address to "FreeDiskSpace" and select your drive (In our example, the read address displays "FreeDiskSpaceC".)

Find the Rate of Change over a day.

Create a Rate Of Change tag. Link it to the tag from the previous step. To get the rate of change over a day, set the period to 86400 (the number of seconds in a day) and set the refresh interval to 3600 (to refresh the value hourly).

Use an Expression in a Calculation tag to find days left.

Create an analog calculation I/O Calculation tag using an IO & Calculation tag. Use an expression like the following, where these refer to the two tags you just created...

[FreeDiskSpaceC] / [RateOfChange]

which should tell you approximately how many days you would get if the remaining space continued to decrease at the same rate each day.

Replace [Bracketed] terms with tag names. If your tags are not closely related, you may need to scope and specify \value in your expression.

Adapt to Your Application

If you have multiple historian servers you will need to configure multiple Workstation Status tags and pick the smallest remaining disk size to calculate the estimated days remaining.

In the provided scenario, the rate of change is on a per-day basis and it is updated once per hour.

Increasing the frequency may give your Rate of Change tag more data points but it will also impact your application performance.

If your application sees irregular spikes in hard disk space consumption, this will negatively impact the accuracy of your estimate. To smooth out spikes in the estimate, increase your sample size. (Collect the rate of change over a longer span and adjust your calculation expression to estimate days)

You won't see an estimate until a day has passed and under the assumption that there has been a change in hard disk space during this time.


Override Detection

This tool exists to help you detect the source of errors in an application. Here, the word "module" is used in the same sense as in the VTScada scripting language. Pages, tags, widgets and more are all stored as "modules".

Modules and properties that have been changed from the defaults of the Standard Application Layer are displayed. Modules and properties that exist only in your application (or its underlying layers) are not shown. You can expect "Pages\Overview.SRC" to be contain overrides in nearly every application.

There are two options: When Application Layer Only is selected, only the current application is examined. If not selected, underlying layers are also examined.

If there are properties that are defined in the application, but have the same value as those defined in Standard Application, they will not be shown in this list unless you deselect the option, Property Value Changing Overrides Only.


Performance Counter Registry Hive is Corrupted

This is a Microsoft operating system error, not a VTScada error.

You must rebuild the registry hive using the instructions available here (works across operating system versions)

https://support.microsoft.com/en-ca/help/2554336/how-to-manually-rebuild-performance-counters-for-windows-server-2008-6


PowerShell not installed

If you have removed Windows PowerShell from your operating system or modified system registry entries related to PowerShell, you may experience difficulty installing VTScada.


Tooltips Do Not Appear

There are two reasons for why tooltips may fail to appear:

  • Tooltip visibility in VTScada is controlled by an application property, ShowTip. Ensure that the value for this property is set to one (1).
  • Tooltip visibility in general is controlled by a Windows™ registry setting. Ensure that the following registry key is set to one (as a dword, 00000001).

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced]

"EnableBalloonTips"=dword:00000001


Unresponsive

VTScada appears to still be running, but is unresponsive. This can happen when there is a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog that is off-screen (minimized) or somehow behind another dialog.

Things to check:

  • Is the VTScada Application Manager window responsive? (Can you open the About dialog?)
  • Are graphics in the VTScada windows still being updated? (Is the time in the title bar correct?)

Before calling technical support, take note of the VTScada memory use (available from the About dialog).


Use the Windows® Event Viewer

The Windows Event Viewer® maintains a record of VTScada notifications and error messages.This may be useful in the event that you wish to review a message after closing the dialog.

Note to VTScada programmers: You can also add your own messages to the Windows Event Viewer using the function LogNTEvent in your scripting code.

Find your VTScada event messages as follows:

  1. Open the Windows Control Panel.
  2. Open the Administrative Tools group.
  3. Open the Event Viewer program.
    The Event Viewer starts with an overview of event logs to choose from.
  4. Using the panel on the left of the Event Viewer window, expand Event Viewer (Local)
  5. Expand Custom Views.
  6. Select Administrative Events.
    The Administrative Events list opens in the center panel.
  7. Sort the list by Source.
    Within each source, events are sorted by date and time.
  8. Scroll to find the VTScada events.
  9. Scroll within the VTScada events to find one with a timestamp closest to the event you wish to review.

The Event Log Online Help is a Microsoft® data store. If this is a purely VTScada message, the Event Log Online Help will not be useful.

Related Functions:

LogNTEvent


Workstation Status Driver Troubles

Troubleshooting

Values do not appear for anything other than battery checks

It is likely that the Windows performance counter needs to be reset on this machine. Test by opening a command prompt with administrative privileges and typing PERFMON. If this opens with an error message, close the performance monitor and type LODCTR /R

Note that the /R must be in uppercase. If you did not open the command prompt with administrative privileges, this command will fail with error 5.

Restart the workstation.

Values don't update when running VTScada as a Service

If running as a service under a regular user account, then to access Workstation Status Driver values e.g. CPU, the account must be a member of the local "Performance Monitor Users" group.

See also: Workstation Status Tag


Active Directory Query

This utility is included with every copy of VTScada, but must be added to the VAM using the Find Existing option of the Add Applications wizard.

Use this to gather information about accounts on your Windows Active Directory system. There are two functions, both of which require that you provide a valid username in the form shown.

Use the Test button to confirm the existence of an account, and check the password. If the combination of username and password will allow you to sign-in to Windows, the test will pass.

Use the Search (by Name or GUID) to gather information about a username as shown in the following example. A valid username must be provided, along with the Active Directory domain to be searched.


Coordinates Application

Included with VTScada is a simple, yet useful utility application named "Coordinates". This utility is useful when you need to determine the horizontal and vertical coordinates of the mouse pointer within any VTScada window (page or dialog).

If the Coordinates application is not referenced in the VAM, you must add it. The Coordinates application's directory is named "XY", and is stored within the VTScada installation directory.

When you run the Coordinates utility application, it appears as shown:

Use the Coordinates utility application to find the X and Y coordinates of any point of interest within a page or dialog by pointing within that page. Coordinates are always local the window under the pointer.


Debugger Utility

There are two similarly named utilities: "Debugger" and "Source Debugger". This topic refers to the older and less powerful of the two, the Debugger.
If you are new to VTScada and looking for a debugging utility, you should turn first to the Source Debugger

The Debugger utility can be used to examine the contents of modules and their properties and can be helpful in helping you to locate problems that happen only while your application is running. The information displayed in the Debugger is updated in real-time as the scripting code runs. This is an older technology than the Source Debugger, but some find that it is still useful.

The Debugger application is not listed in the VAM by default, therefore you must add it. The Debugger application's directory is named "Debugger".
Pressing the keys "Ctrl-D" in the VAM will launch the Debugger.

An example of the Debugger:

Examining the SupplyPump tag in the Completed Tutorial

The top of the Debugger displays the name of the module being examined and the name of the current active state, in parentheses following the module name.

Pin button

(pin / currently pinned)

Use this button to choose whether the Debugger window should remain on top of all other windows.

Select button

Use this to choose which graphics module to examine.

  1. Click the Select button.
  2. Click on a VTScada page to begin examining the variables in the graphics module for that page.

Parent button

After selecting a graphics module, use the Parent button to examine the parent of the current module.

Next button and Previous button

Step forward and backward through the history of modules you've recently viewed.

Instances button

The Instances button enables you to step through the different instances of the module if more than one is running. The current instance and the total number of instances are shown beneath the button.

Root button

Used to quickly select the root module of the current module.

For example, if you are interested in examining a tag that is drawn on a page, you would first use the Select button to choose the page, then the Root button to move up the module tree. The display would then include (among other things) all of the tags in the application, from which you could select the tag you are interested in.

Caller button

Use this to examine the caller of the current module.

Search field

Use by entering a search string by which you wish the list of variables to be restricted. The wildcard characters '?' and '*' may be used in combination with either a single character or 0 or more characters to locate specific variables. You can use the asterisk wildcard to stand for any combination of characters. For example, L* will return all variable names that begin with the letter "L", *L or *L* will return all variable names that contain an "L" anywhere in the body of their name.

Pressing the key combination, "Alt-Home" will perform the same function as clicking on the Root button.

Variables check box

Filters the list to include variables when selected.

Parameters check box

Filters the list to include parameters when selected.

Modules check box

Filters the list to include modules when selected.

Sort check box

Filters the list alphabetically when selected. If deselected, the items displayed in the list will appear in the order in which they were declared.

Global check box

Filters the list to include all variables that can be accessed from the current module. Otherwise, only the variables in the current module will be displayed.

When a new value is entered in the edit fields in the debugger, the Enter key must be pressed or it will not "register" (i.e. changing focus does not automatically enter values into the fields of the debugger). Further, if a text string is greater than 255 characters, only the first 255 characters are shown in the value field, but its full length is still registered.

Beneath the filtering and sorting check boxes appears the list of modules, variables and parameters. This list may be resized by dragging the divider between the Name and Value columns. If an item in the list is a module, an expand module button ">" will appear to the right of its "Value" column.

By clicking on this button you can expand the module and examine its contents.

Under the list of modules, variables and parameters is information about the items in the list. (example shows the list for an Analog Input tag with the UnscaledMax parameter selected)

Clicking on any item in the list of modules, variables and parameters will bring up information on the selected item, such as the value of the selected item, the data type (if the selected item is a variable), the attributes of the selected item, the class of the item, and if the selected item is a variable and the "Global" check box is selected, the module to which the variable belongs will be displayed. The name of the selected module, variable or parameter is centered above the Value field.

In the event that a selected variable has a value that can be modified, the Value field becomes enabled for modification, and includes a "clear value" button, which is marked with an "X". Any changes you make to the value of a selected variable will have an immediate effect in the running instance of the current module. Clicking on the clear value button will invalidate the current value.

If the selected variable is an array, the information displayed applies to the current element of the array only. The array contents are visible in the Array field at the bottom of the Debugger.

In the array display area, there is a scrollable listbox that contains a list of elements for the selected dimension. The current dimension can be changed at the top of this area. Selecting an element in this listbox will allow information on the element to display/edited in the variable information area.


Instance Count Application

The Instances utility provides a count of the instances (or copies) of modules that are running in all VTScada applications on the workstation.

If the Instances application is not listed in the VAM, you must manually add it. The Instances application's directory is named "Instance" and is stored within the VTScada installation directory.

The Instance tool can help you find potential problems in your application code. For instance, a high count for a particular module might indicate either:

  • Excessive numbers of instances of a module have been launched.
  • Module instances fail to stop executing when they should.

An example of the Instances utility:

Sample instance count

As shown, the Instances utility provides a count of how many instances of each module are running, and the file name where the module can be found. (Most of the files listed are accessible only to Trihedral employees.) For any file that is loaded from the .sync folder, there will usually be a user-accessible version elsewhere in the application folder. Do not edit any file in the .sync folder.

At the bottom left of the dialog are two values showing the total number of modules running and the total number of instances of those modules.

The display is not updated automatically. You can use the Re-Sample button, found at the lower right of the dialog, whenever you want a current count.


Memory Tracer Application

The Memory Tracer application can be used by Trihedral staff to analyze VTScada’s demand on computer memory. On rare occasions, technical support may ask you run this utility while diagnosing a problem. It is typically used to identify potential memory leaks. The Memory Tracer application must be loaded into the VAM before use.

Sample memory trace

Using the Memory Tracer Utility

VTScada memory allocation calls are each given a unique ID. A memory leak or other problem would be indicated by an unusually high count or total byte value, or by an allocation histogram that is not mostly empty. By referencing the caller ID associated with a high count value or that shows up many times during the time slice, programmer's can quickly find the code that is responsible for allocating this memory.

To begin capturing the VTScada memory usage, click the Capture button. The button will read "Capturing" for several seconds while data is being saved to the specified text file.

By default, VTScada creates a default memory trace file in the format of an encrypted text file named, "MemTrace.txt", which is stored within the MemTrace subdirectory of the VTScada installation directory (e.g. C:\VTScada\MemTrace\MemTrace.txt)

You may use the Pick File button or the Capture File field to specify an alternate location or file name if you wish. Memory Trace files may be used to send a trace to another computer for analysis.

The Filter Ranges, are used to restrict the capture to:

  • VTScada usage during a given time frame
  • Low and high byte sizes
  • Low and high caller ID values.

The Reset button in this area will restore the filter to the widest possible ranges.

Analyzing a Memory Trace File

After you’ve captured data to a memory trace file, or opened an existing file, you can analyze its data. To do so, simply click the Analyze button. When the progress bar reaches 100%, the Memory Tracer application’s elements will be populated with data. Click any column title to sort the table by that column.

For each Caller ID (identifying the line of VTScada code that allocated the memory) the following information will be displayed:

  • The count of times that line was called.
  • The total memory allocated by that code.
  • The Caller ID.
  • Timestamps, identifying the earliest and latest times that code identified by this ID allocated memory during the capture timeframe.

The histogram will normally display a large number of total bytes at the beginning of the time frame, with a few small byte allocations during the span. As you move the mouse across the graph, the date and time matching the cursor location will be displayed. Pausing the mouse over any blip in the histogram will cause a window to display showing the bytes allocated at that point in time, and the Caller ID's associated with code that allocated memory at that time.

Note that you can copy information from the Allocation Information table with a Control-C. This information can be pasted into any text file or spreadsheet. The copied information will not be sorted.

Viewing Smaller Segments of a Time Slice

Before using the Zoom button, drag the cursor over a section of the histogram to select a portion of the time span. If you click Zoom without selecting a region of the histogram, the result is unlikely to be useful.

There is no undo for the zoom command. Reopen the file and click the Analyze button to reset the histogram.


RPC Timing Utility

The RPC Timing Utility is included with VTScada, but not added to the default list of applications in the VAM. Use the Find Existing option of the Add Application Wizard to add it to your VAM.

This utility provides an assessment of remote procedure call (RPC) round-trips between the servers running an application. Use it to identify timing issues, especially in busy systems. It can also identify servers that are using unintended IP addresses (non-SCADA network cards) and servers that are being overloaded with RPC calls.

Timings are relative to the workstation where you run this application (never shown in the list). To refresh the display, click on the run button. A fixed number of test messages will be sent, from which timing statistics will be gathered.

"Q" is an abbreviation of "Queue" and refers to the time messages wait before being sent. Average, best and worst delays are collected while the run button is held.

The tolerance column refers to the configured link tolerance value. See: Link Tolerances for relevant information.

You may copy the displayed values to the Windows clipboard, or export them to a comma separated values file. The default file name will be "RPCTimes_" followed by a timestamp that identifies when the file was created (not when the values were collected.)


Source Debugger

The Source Debugger is the most powerful and comprehensive of the VTScada debugging tools. You can monitor several applications simultaneously, each within a separate instance of the Source Debugger.

Image does not show the full toolbar

If the Source Debugger application is not visible in the VAM, you must manually add it. The Source Debugger application's directory is named "Source Debugger" and is stored within the VTScada installation directory.

Use the Source Debugger to:

  • Examine the source code for the VTScada application you are debugging.
  • Pause execution of VTScada script code by setting breakpoints.
  • View the execution history of a specific thread when a breakpoint is "hot".
  • View and modify variable values.
  • Search for a specific instance of a module by specifying a Boolean expression.
  • Locate module instances that use a specific variable in steady-state, and find the module instance that is setting a variable in steady-state.
  • Build up to four watch-lists of selected variables that remain on view continuously.
  • Create profiles of modules, documenting the number of execution counts and execution time used during a sampling period.
  • Slay instances of modules.

In addition to the Source Debugger, VTScada includes an older application named "Debugger". While the older debugger can still be useful in certain situations, the Source Debugger is by far the more advanced of the two tools.

Select an application for debugging

There are several ways to select applications for debugging:

  1. Click the application’s name in the Applications section of the Summary (Live) Tab in the main window.
    With this method you can select either running or stopped applications. Note that while you can examine the source code of a stopped application, you will not see modules or values as none are running.

--OR--

  1. Within a VTScada application, navigate to the page you want to examine.
  2. In the Source Debugger, click the Select Window to Debug.

  3. Click on the appropriate window in your VTScada application. The Source Debugger will select the running module instance that contains the graphic statement under the mouse pointer as the current module instance, and will display the module trees, content list, and source code for that module window.

--OR--

The Source Debugger can examine a dump file in much the same way that it can examine a live system. To open a dump file for debugging:

  1. Click the Open Dump File tool in the toolbar.
    The Open Dump File dialog will open.
  2. Browse to and select the dump file you wish to analyze.
  3. Click the Open button.

The selected dump file will open in the code display window in its own separate tab labeled "Summary (Dump)".

You can also open any VTScada source code file for debugging by clicking the Open Source File button, then navigating to find and open the file. If the application is not running, no variables will be set and the module tree will not load.


Source Debugger Components

Viewing: Troubleshoot > Source Debugger > Source Debugger Components

Source Debugger Toolbar and Components

The source debugger displays everything under the hood of an application with tools to toggle and explore specific functions and modules.

Source Debugger. Image does not show the full toolbar.

The first part of the Source Debugger to learn is the toolbar. A keyboard shortcut is available for many of the tools. Hover over each for a tooltip describing the tool and the keyboard shortcut, if any.

The Source Debugger toolbar has a large array of tools for debugging with new features being added.

The full Source Debugger Toolbar

Listing the buttons from left to right, by group.

Closed Quick Links:

Navigation Group

Select Group

Dump File Group

Clipboard Group

Variables Group

Breakpoints Group

Watch Group

Options Group

Modules Group

Workspace Group

Code Coverage Group

Mouse Coordinates

Close Window

Navigation Group

Move to the previous screen or the next, move to the parent or child.

Back Button & Forward Button

Use these two buttons to move back and forth through the modules you have recently viewed. You may also use the keyboard combinations Alt + Left Arrow (move left) and Alt + Right Arrow(move right) to step through the modules.

Parent Button / Caller Button

Click to open the parent or the caller of the currently selected module.

Select Group

There are a number of ways to select what is displayed in the Source Debugger.

Select Window to Debug Button

Select this tool then click on any open VTScada window. Automatically selects the matching module in the Module Tree and opens that module in the Module Content List window.

Note that this may navigate to the module that owns the window rather than the module that provides the content for that window. For example, if you were debugging the Completed Tutorial, had opened the Overview page as a pop-up, then used this tool to select that page, the module would be DisplayManager >> Session >> Graphics. Within the module content list for that, you would find a link to the Overview page's module.

Open Source File Button

Click to browse for and open any VTScada source code file (*.SRC). Any file may be opened but breakpoints can be set and values read only for running applications.

Debug Test Framework Button

Launches the Test Framework application to run pre-written tests on the selected module.

See: Test Framework Application

Dump File Group

Open a dumpfile or create a dumpfile

A dump file is a snapshot of all the information that would be available for an application if you were viewing it live in the Source Debugger. A dump file is typically created to be sent to Trihedral Technical Support for analysis of a problem. (Note that it is often preferable to collect the dump from the Windows Task Manager rather than collecting it within the Source Debugger.)

See: Dump Files & Forcing Communication Log Files, Dump Files & Forcing Communication Log Files

Clipboard Group

You can copy and paste values in the Module Content List window. All VTScada data types can be copied. Behavior when pasting may vary depending the type of data held by the selected item and on whether you have simply selected the item or clicked twice on the item to enter edit mode.

If you highlight and then single left-click a variable to enter edit mode, the value on the clipboard will be pasted into the edit field as a text representation of the copied quantity (e.g. the name of an object is pasted, rather than an object value). The text representation of the value is also available to applications outside the Source Debugger and to processes outside VTScada.

Not all VTScada values can be represented as text. For those that cannot, the text "Valid" or "Invalid" will be pasted.

If you select an item in this window and paste without entering edit mode, then if the clipboard holds a data type that can be pasted into the selected item, it will be.

Variables Group

Show Module Data in New Window Button

Click to launch a new window displaying the objects associated with the selected module.

Refresh Trees Button

Refresh the module trees, ensuring that any new module instances that have been added are displayed.

See:

Sort Data Button

Sort the contents of the module content window in ascending alphabetic order.

Sort Tree Button

Sort the contents of the module tree in ascending alphabetic order.

Hide Constants Button

Hide constants that would otherwise be displayed in the module content window.

Show Only Parameters Button

Display only parameters for the selected module in the module content window.

Breakpoints Group

Toggle Breakpoint (F9) Button

Set a breakpoint in the code you are viewing. A breakpoint indicates to the Source Debugger that the selected application should pause execution at a certain point.

See: Breakpoints and Data Breakpoints

Enable/Disable Breakpoint (Ctrl + F9) Button

Disable an existing breakpoint or enable a disabled breakpoint in the code you are debugging or examining.

Breakpoint Properties (Alt + F9) Button

Open a window within which conditional breakpoints can be configured.

Continue (F5) Button

Continue execution of the code you are debugging or examining when a breakpoint has been hit and code execution paused.

Step Into (F11) Button

Steps into subroutine calls instead of over them.

Step Over (F10) Button

Stepping over a subroutine call runs it at full speed and halts execution of the stepped thread at the next function or statement.

Run to Cursor (F12) Button

The Run to Cursor button places a temporary breakpoint at the highlighted line of source code. If the Source Debugger has halted execution of a thread and that break is highlighted in the Breakpoints tab of the Action window, that thread’s execution will be resumed at full speed. The Run to Cursor button can be used like a shortcut that will run from a breakpoint to wherever the highlighted line of code is situated.

Step Out (Shift+F11) Button

Only enabled when you are on a breakpoint in a subroutine. Run the remainder of the subroutine at full speed and break on the next statement in the current thread after the subroutine's Return statement executes.

The next statement may be:

  • The script statement following the subroutine call.

  • If the subroutine call was the last statement in a script or a destructor, the next steady-state statement to be evaluated on the same thread.

  • If the subroutine was a constructor, the first statement of the freshly constructed module instance.

Watch Group

Add a watch, a watch expression or remove a watch

Add Watch (Ctrl + W) Button

Add the selected variable and its value from the module content window to the selected tab in the watch window.

See: Setting a Watch on a Variable

Add Watch Expression Button

Add the selected expression from the module content window to the selected tab in the watch window.

See: Set Data Breakpoints

Remove Watch (Del)

Remove the selected variable and its value from the watch window.

Options Group

Access interface options, change the font size or toggle between daytime and nighttime mode.

Set several options that affect the way the Source Debugger appears and behaves.

  • For the Options dialog, see: Source Debugger Options
  • Font Size is a toggle, cycling through four font heights.
  • Daytime / Nighttime toggles the screen between a light and dark background.

Daytime/Nighttime

Toggles the background between white (daytime) and black (nighttime) mode. The foreground (text) color will be the reverse.

Modules Group

Find Module

Enter a Boolean expression and search to find all instances of the current module where the Boolean expression evaluates to true. This will also open a tool where you can locate the parent object containing the currently-selected global variable.

See: Search for a Specific Module Instance

Slay

Terminate the execution of the selected module instance.

See: Slay a Module Instance

Workspace Group

Open Workspace

A workspace is the set of the selected module, the breakpoints, and the watches for a Source Debugger session, stored in a .DWS file. Use this button to re-open a workspace that you have saved with the Save Workspace button.

Save Workspace

See preceding description for Open Workspace. Use this button to save the breakpoints and watches, and the selected module that you are working with, from one session to another.

Reload Auto Workspace

If you have enabled the automatic workspace reload feature (done in the Options dialog - see: Source Debugger Options) then you may use this button to load the last automatically-saved workspace.

Code Coverage Group

Toggle, reset, refresh, change highlight or merge code coverage to and from file.

Toggle Code Coverage

Toggles the display of code coverage (the indicator of what modules, states, statements and parameters used)

Reset Code Coverage Information

Resets the code coverage counters to zero.

Refresh Code Coverage

Displays an up-to-date view of the code coverage.

Previous Highlight

Steps through the display to the previous statement (parameter…) highlighted as having been used by the module.

Next Highlight

Steps through the display to the next statement (parameter…) highlighted as having been used by the module.

Merge Code Coverage From File

Loads the code coverage record as stored in a file, into the current display. This is especially useful for team debugging where various team members are testing different parts of the code and wish to merge their results.

Merge Code Coverage To File

Saves the code coverage, from the current session to a file. This is especially useful for team debugging where various team members are testing different parts of the code and wish to merge their results.

Source Code

Enabled only when source code is available for the selected module. This tool will open the source code file using your default editor.

Mouse Coordinates

To the far right of the Source Debugger's tool bar is the mouse coordinates section. As you move your mouse pointer around on the screen, it reports the X and Y coordinates with respect to the origin of the VTScada window that the mouse pointer is over.

Close Window

This small "x" at the right-most edge of the toolbar will close the selected window in the Code Display area.


Summary (Live) Tab

Contains extensive information about the current state of your VTScada installation and running applications. Details are grouped into bands that you can expand or close as needed. Several bands include a button to open the content as a pop-up window instead of expanding the band. Where appropriate, there may be a Refresh button that you can use to update the display.

This window also holds the Code Display and (when displayed) the Summary (Dump). Use tabs (located along the bottom of the window) to select which to display.

Information in this window includes:

Operating System

One line, not expanding. Windows version, 64 or 32 bit, # of cpu's.

VTScada Info

Expanding section showing version and license details.

Applications

Expanding section with two sub-sections, Running and Stopped. Click any running module to populate the Module Tree with that application's modules.

Child Bubbles

Expanding section that lists all child bubbles of the currently selected module.

Modules

Expanding section that lists all running modules from all applications including those for the VTScada system layer and the Source Debugger itself. Provides the number of instances currently running for each module.

Structures

A list of structures in the system and the count of each.

Threads

Expanding section that lists all running threads from all applications including those for the VTScada system layer and the Source Debugger itself. Provides the number of instances currently running for each module. Identifies the module and state that spawned the thread and whether the thread is active or inactive as of the last refresh.

Execution History

Expanding section that lists recently executed statements in order of execution. Details show the module, state and thread ID of each statement. You can filter the list by module or by thread.

See: Working with the Execution History

Profiler

Monitors all processes over several seconds, allowing you to create a detailed profile of exactly what is happening in your VTScada application. Use this to catch errors in your code such as statements that use excessive system resources.

See: Profiler


Module Tree Window

The Module Tree occupies the window to the left edge of the Source Debugger.

As the implies, the module tree shows a list of all modules in the selected application, organized in a hierarchical structure. The modules shown in the trees are not dynamically updated in real-time. To do so would impose a significant execution overhead that would likely impair or affect the normal running of the system. The trees are automatically refreshed when a breakpoint is "hit", or when the "Refresh Trees" tool bar button is clicked.

A plus symbol indicates that a module has submodules.

Use the three tabs at the bottom of this window to change the type of modules that are displayed in the module tree as follows:

Static

The static tree represents the parent/child relationship between modules.

Scope:

The scope tree represents parent/child relationship between objects (aka module instances), which determines what variables an object sees when you scope out of it.

Call:

The call tree represents the caller/callee relationship between objects, which determines what objects get torn down when an object is slain, and what window an object displays its graphics within.

Use the Sort Tree button in the Variables group of the toolbar to sort the module tree alphabetically.

When you have added (or deleted) modules from an application while you are debugging, use the Refresh Trees tool in the toolbar to ensure you are viewing the application’s latest data.

Type the name of the module you are looking for to bring you straight to it in the module tree.


Module Content Window

The lower left portion of the screen is occupied by the Module Content window. The content is linked directly to the selected module in the Module Tree window. At the top edge of the window you can see the name of the module being examined and the specific instance. Step through the instances using the arrows provided.

Analog status tag in a module content window

Use this window to examine the current value of variables, constants, parameters, and declared submodules. You can also set values for variables, parameter values for launched objects or objects running as subroutines. You cannot set parameters for called objects, variables set in steady state or object values. Setting a value will affect the current running instance but not change underlying code - the next time the module runs values will be assigned normally. Use this feature to experiment with "what-if" scenarios, simulate user-input, or advance a counter.

The list can be sorted alphabetically using the Sort Data button in the toolbar. At times, the list may be easier to use when not sorted. For example, when viewing tags, the Name property will be first in the unsorted list, whereas you would need to scroll to find it in the sorted list.

If the module has a Return() statement, you can view (and set) the value that will be returned. Typically, you would use this window in combination with break points to examine values at selected points during execution. Breakpoints and Data Breakpoints.

Filter Data in the Module Content Window

You can filter the variable list being displayed in the module content window as follows. Note that the filter refers to variable names, not values.

  1. Enter a filtering condition in the Filter field in the module content window.
    (e.g. To view all variables whose name begins with "a" you could enter a*).
  2. Press the Enter key.

The module content window will display only those objects that meet the filtering condition.

To clear the filter, use the clear (x) button or clear the input in the Filter field and press the Enter key.

Buttons within the display

Buttons to the right of each entry in the list will vary according to the type of that value.

Toggle display formats. For most numeric values you can toggle the display between decimal, hex, octal, or timestamp.

Open a pop-up window. (See following example image)
If the variable points to another module or contains complex data such as an array, structure or dictionary, a window button can be clicked to open a pop-up dialog with detailed information about the contents of that variable. Tools within this window allow you to expand or collapse all nodes, enable or disable automatic refreshing of the displayed values, change the displayed format for all values, and filter for specific values and for keys in dictionaries.

Value pop-up window showing an array. Dictionaries are similar.

Navigate to submodule. Click this button to navigate to the module named in the associated variable in both this window and in the module tree. This is equivalent to using the Forward button in the toolbar.

Double-clicking a variable is equivalent to using both the window button and the forward button, as described in the previous two items.

Open Metadata window. Similar to opening a pop-up window for other types, this symbol is used expressly for variables with metadata.
Notes and examples for metadata can be found after the following example image of a value pop-up window.

Metadata

If the variable contains metadata, a [image] button will be provided, which you can click in order to view that metadata. The metadata button should not be taken as indicating whether a variable is a dictionary. For example, a dictionary created with several name/value pairs, but without a root value, will not have a metadata button.

A value in VTScada has properties, other than just its value. By resting the mouse pointer over a value in the module content window, a tool tip window is displayed for several seconds, listing the properties of the selected value. For example:

The rules for how dictionaries are displayed in the module window can be confusing if the dictionary has a root value. The following example may help:

Given the following code that creates two dictionaries, where the first has no root value and the second has a root value of 5: (*)

  If Watch(1);
  [
    DemoDictA = Dictionary();
    DemoDictA["A"] = "Data A";
    DemoDictA["B"] = "Data B";
    DemoDictA["C"] = "Data C";

    DemoDictB = Dictionary(1, 5);
    DemoDictB["A"] = "Data A";
    DemoDictB["B"] = "Data B";
    DemoDictB["C"] = "Data C";
  ]

The module content window will look like the following:

Hovering over each of the variables in turn will produce tool tips as shown next:

Note that only DemoDictB, which has a root value as well as metadata gets a metadata button.

DemoDictA gets the Window button, which in this case performs a somewhat similar function…

(* Note that root values are not common and should be used with caution. The preceding example shows how the Source Debugger works, not recommended practice for dictionaries.)

Tabs:

Local:

Displays only the variables and values that are local to the selected object or module. Values from parent objects that may be within the scope of the selected module are not shown.

Instance:

If a module has retained variables (which are persisted, instance-specific variables) and those variables have valid values, then these will be displayed in the Instance tab. As you cycle through the instances with the "Instance" spinbox, any different values are displayed.

Auto:

Referring to the Code Display window, this tab shows variables and values near the selected line of source code. (Near is defined as one source code line before and one after the selected one.) This is most useful when single-stepping through lines of code. Values are refreshed automatically as you step through the code.

Global:

Shows all variables and values within the scope of the selected object or module.


Code Display Window

The code display window occupies the center of the Source Debugger. This window also holds the Summary (Live) and (when displayed) the Summary (Dump). Use tabs (located along the bottom of the window) to select which to display. Code from several modules may be open at any time, each in its own tab.

Code is displayed immediately when you select a module from the Module Tree, but only if the source code for that module exists on your workstation. If you have only the compiled module (.RUN file) then you cannot examine its code.

Note also, the Source Code button in the toolbar. If the source code is available on your workstation, use this to open the file in your default editor.

Hover the pointer over variables in the code to see a tool tip that contains the variable's name, its current value, and a tool to change the display format (decimal, hex, etc.) or for complex types, open a pop-up window with detailed information about the variable's content. Double-click the variable's name within the tooltip to (briefly) highlight the line where that variable was declared.

For a given module, there may be several running instances or none. VTScada will make a "best attempt" to find a value for the variable for display within this window, but for greatest control over which instance's value you are examining, use the Module Content List window.


Action Window

The action window is the middle window along the lower edge of the Source Debugger. This window has three functions depending on the tab selected.

BreakPoints:

Displays a list of the currently set breakpoints, including the source file location, module, state, and statement in which they exist. A highlight will indicate any "hit" breakpoints and the running thread that has been paused. See: Breakpoints and Data Breakpoints

Use List:

Used in conjunction with the module content window, this displays the source file location of each running steady-state statement that depends on the value of a selected variable. These statements are referred to as the "consumers" of the value because they will be triggered for execution when the contents of the variable instance changes.

Set List:

Displays the source file location of each running steady-state statement that is setting the value of the variable selected in the module content window (i.e. the "producer" of the value). In correctly written code, there should only be one such reference. Multiple such references result in a "double-set" condition and yield an invalid value for the variable instance.


Watch Window

The module content window shows the current values for all variables within any given module, but it is likely that you will be interested in only a few of these, and typically you would need to scroll the module content list to see them. Use the Watch window to select only those variables that you are interested in monitoring. Variables can be selected from several module instances. Use the four tabs along the base of the watch window to create four separate lists.

The tools available to work with variables in this window are the same as those available in the module content window.

To watch a variable:

  1. Select the variable in the module content window whose value you wish to monitor.
  2. Select the watch tab to which you wish to add the selected variable. (There are four watch tabs along the base of the watch window.)
  3. Click the Add Watch tool in the toolbar.
    The variable will be added to the Watch window so that you can monitor it.

To watch a steady-state expression:

The Source Debugger enables you to set a conditional watch of steady-state modules using an expression. To do so:

  1. Select one of the four watch tabs.
  2. Click the Add Watch tool in the toolbar.
    A field will open on the selected watch tab to allow you to enter the expression to be watched.
  3. Enter an expression (e.g. X + 42).
  4. Press the Enter key. The expression will be added to the selected watch tab.

To watch a script expression:

This feature should be used by advanced programmers only.
If the expression could be compiled as either script or solid-state, it must be reformatted explicitly to avoid an infinite loop. See examples below for more details.

The Source Debugger enables you to set a conditional watch of a script expression. To do so:

  1. Select one of the four watch tabs.
  2. Click the Add Watch tool in the toolbar.
    A field will open on the selected watch tab to allow you to enter the expression to be watched.
  3. Enter an expression*.
  4. Press the Enter key. The expression will be added to the selected watch tab.

Formatting Script Expressions*:

If the expression can be run as steady-state, it will by default. Running as a steady-state expression will continue to return a value even if there has been no change. This loop will consume CPU resources. It is a best practice to avoid loops and explicitly format expressions to ask for a single instance of the target value. To update the value during the debugging process, use the refresh button located to the right of the value in the watch window.

1. Avoid If 1;

Consider the following subroutine module:

<
Increment
(
  A;
)

Add
[
  If 1;
  [
    Return(A+1);
  ]
]
>

The module will run as steady-state and repeat, continuously incrementing A by 1.

To avoid an infinite loop, replace "If 1;" with "If Watch(1);"

2. Reformat expressions that can run as a steady-state expression by explicitly calling for one instance.

Example:

The user wants to call the following subroutine to see the result at a critical moment (ex. when hitting the breakpoint)

Format(P1, P2...)

The module will be called in steady-state by default and update continuously, even if the variables remain unchanged. Reconfigure the statement as follows:

IfThen(True, Var = Format(P1, P2...))

Using IfThen will force the statement to run as a script block and the return value will be assigned to Var as the redundant temporary variable in the current scope.

To remove a watch:

To remove a watch set on a variable or expression:

  1. Working within the watch window, select the variable or expression whose value you no longer wish to monitor.
  2. Click the Remove Watch tool in the toolbar.

The variable or expression will be removed from the watch window.

Related information:

Launched Versus Called Modules


Summary (Dump) Tab

Similar to the Summary (Live) tab, but with several important differences. This tab is displayed only when you have loaded a dump file for examination in Source Debugger. The path to the dump file will be displayed at the top of the window.

All information in the Summary (Dump) window applies to the workstation on which the dump was created.

(For instructions to create a dump file, see: Dump Files & Forcing Communication Log Files.)

If the dump file was created on another workstation, you may not have a local copy of the source code for custom modules in that application. If that other workstation is on your network, you can direct the Source Debugger to open source code files from that computer rather than needing to copy the files to the local machine.

Differences from the System (Live) tab include:

  • Operating system, VTScada license information, and the list of applications all refer to the machine where the file was created.
  • The modules list will be empty as none from that workstation are loaded and running locally.
  • Threads: Identifies the set of threads that were running within VTScada at the time of the dump. The number to the right of the thread name is the Windows thread identifier. The module that last ran, its state, and its statement number are identified. Under the System subheading (within the Threads section) the sequence of execution that last took place prior to the dump is provided (this is the same information as is presented in the Thread List Application - time, module name, state, and statement number).

When examining a dump file, the last statement executed can be determined from the thread list. This can be helpful to identify the cause of a crash.


Working with Modules

Given that modules contain the code and the variables that you will want to examine using the Source Debugger, it's important to be able to navigate to those modules and work within them.

Navigational tools for finding modules:

  • Module Tree Window. A list of all the modules loaded with the currently selected application. The Sort Tree tool in the toolbar is recommended.
  • Links within the Module Content Window . For modules that declare other modules as variables, links are provided to navigate to those modules. These are shown as right-facing arrows.
  • Navigation Group of the Source Debugger toolbar. Used in combination with the module tree window, this provides tools to step through related modules.
  • Use the Select Window to Debug tool. (Select Group) Click on any open VTScada window to navigate to that module in the tree window, open its code in the code display window (if available), and populate the module content window with its variables.
  • Use the Find Module dialog to Search for a Specific Module Instance.

Remember that it is possible to sort the contents of both the module tree list window and the module content window using the two sort buttons in the toolbar. An alphabetically sorted list can be helpful at times but not always.

View the source code for a selected module:

Possible only if the source code is available on your workstation. For example, you can examine the Overview page of most applications, but not the code behind the Analog Status tag unless you are a Trihedral employee.

Any action that selects a module in the module tree window will open its source code, so long as that code is available. Note that code windows do not close automatically. It is possible to open an excessive number during a long debugging session, making it difficult to find one opened earlier.

View module content

Referring to variables, parameters, constants, etc. This is the role of the Module Content Window .

In addition, variables in the module content window list that contain other modules will have a link ( [image]) that opens a pop-up window showing the content of that submodule without navigating away from the current module.


Search for a Specific Module Instance

You can search for a specific module instance using a Boolean expression. This will be evaluated in the scope of each instance of the selected module. Note the last two words of the previous sentence. Only instances of the selected module are searched, not all modules in the module tree list.

Use this feature to locate a specific module instance among many. Each module in turn for which the expression evaluates to true is made the selected module. Use the Next button in the Find dialog to step through instances that match the expression if there is more than one.

To search for a specific instance of a module:

  1. Click the Find Module tool in the toolbar.
    The Find Module dialog will open.
  2. Enter a Boolean expression in the field provided.
    Every variable reference must start with a scope resolution operator ( \ or . ).
  3. Click the Find button at the top of the Find Module dialog.

This facility can be extremely useful where you are diagnosing a problem in a large application that may have many instances of the same module (such as a tag), and you need to locate a specific instance.

Find a Module Instance

Using the Completed Tutorial application as an example, perhaps you wish to locate the instance of the module "AnalogStatus" that corresponds to the tag "Tank Level". This module instance can be identified easily enough because you know that the variable "ShortName" within that module holds the tag's name. As a result, you would first select the AnalogStatus module in the module tree, then open the find tool. The script expression would be:

\ShortName == "Tank Level"

Note that the text value of the name is contained within quotes, as per a normal string literal, and that the variable "ShortName" is preceded by a scope resolution operator (\).

Three instances will be found and one loaded in the module content window. Press the "Next" button in the find dialog to step through the instances. A pop-up message will let you know when there are no more instances to find.

If no instances can be found or if the Source Debugger is unable to compile the supplied expression, an error dialog is displayed, describing the error.


Slay a Module Instance

The Source Debugger enables you to slay a module instance. This can be especially useful if you have created a launched module that contains an If 1 condition.

To slay a module instance:

  1. Use the Module Tree Window to select the module for which you wish to slay an instance.
  2. If there is more than one running instance, use the spin box at the upper right of the Module Content Window to scroll through the instance numbers. (Alternatively, by selecting a specific module instance from the scope or call tabs of the module window, you can go directly to a specific instance.)
  3. Click the Slay button.

    A dialog will open and request confirmation that you wish to slay the selected module instance.
  4. Click the Yes button.
    The instance of the module you have selected will be slain.


Profiler

Prior to VTScada version 11.3.09, the Profiler was run as a utility application. It is now an integrated part of the Source Debugger. Customers who have upgraded their systems, installing a newer version of VTScada over an older one will still have the older Profiler application. If this describes your situation, you are urged to remove the older application from the VAM and use only the newer version within the Source Debugger.

Use the Profiler to discover statements that are placing an excessive load on system resources. If a particular statement runs for a large percentage of the data collection time, it may be due to an "If 1" (continuously executing) condition. A statement that is called an extremely large number of times may indicate an inefficient algorithm in your code. Statements of this nature can have a severe impact on the speed and performance of an application. The Profiler can help you recognize such statements and correct any problems.

The meaning of "high number" will vary depending on your application. It is helpful to run the profiler at different times and under different conditions to gain a sense of what is normal for any given application.

In addition to running the Profiler within the Source Debugger, you can open it within a pop-up window. This will create a separate instance that does not share statistics with the original. Closing the Source Debugger will also close the pop-up window. If you have unsaved data in a pop-up Profiler window, VTScada will prompt before closing, giving you the opportunity to save your data. You can also open multiple pop-up windows, which can be useful for comparing multiple profiles.

While one profile is processing and another is waiting to stop, you cannot start another profile. The play button will become disabled until the profile that is waiting to stop moves to the processing state. If the profile waiting to stop is very long, this may take a few minutes.

The Profiler analysis tool can be used in two ways: by collecting statistics about running statements during a defined collection period, or by taking an instant count of the number of statements of various priorities that are pending when the Stats button is clicked.

An example of the Profiler follows. Note the "Settings" button. This will open a configuration dialog that can adjust how the profiler works. The notes in the Profiler Settings topic contain important information for anyone who intends to save the data collected by the profiler.

The Profiler includes the following elements:

Command Buttons

Pin

When selected, the Profiler will always be the top-most window. Enabled only when the Profiler has been opened as a pop-up window.

Start/Stop

Begins data collection. While the profile is running, the start button will become a Stop button.

Clear

Clears the history of the last profile collected. Does not apply to display of pending statements, collected by the Stats button.

Refresh Statistics

Click to collect information about the number of pending statements of various priorities. (These are described in the list of displayed information, later in these notes.)

Displayed Information

Running Profile

Displays an elapsed time count in seconds while a profile is being collected.

Last Profile

Shows the start time, end time and duration of the last data collection period.

Statistics

Updated at the end of each profile collection period or when the Refresh Statistics button is clicked. Includes the following information:

  • Statement Count
    Shows the number of statements that executed during the most recent profile.
  • Normal Pending
    Shows the number of normal statements that were awaiting execution when the Stats button was clicked. For example, if a tag value changed just before you clicked the stats button, then there may be statements pending execution to react to that tag value change. If the Normal Pending value is very high, it may indicate that the script-execution engine is heavily loaded. This value cannot be taken by itself to indicate system loading since an IF-1 condition may create a large load while only adding 1 statement to the list of those pending.
  • High Pending
    Similar to Normal Pending but shows the number of high priority statements that were awaiting execution.
  • Timers Pending - Shows the number of time-related functions that were pending. A large number of these may indicate poor design.
  • Priority Pending - Shows the number of priority statements that were awaiting execution. Steady-state priority functions generally place a heavy load on system resources.

Grid Display Items

All measured times in the source debugger, apart from Stall times, represent time spent within the scheduler lock, which is the exclusive lock that the vast majority of script execution happens within. This exclusive lock is the primary resource that the profiler is profiling.

Counts

The number of times each statement executed during the most recent profile.

Total Time

When the Profiler is in the normal (non-Flip Tree) view, the total time is the scheduler lock time taken by that statement and all statements under it in the tree.

In the Flip Tree view, total time is not meaningful.

Self Time

The time spent by that statement, not including all of the other profiler nodes underneath it in the tree.

Avg Time

Total time divided by Counts.

Stalled Time

The amount of time that a particular statement spent outside of the scheduler lock. For example, the ODBC() function stalls while the ODBC command executes. Statements on other threads can execute while a statement is stalled, but statements on the same thread as the stalling thread are held-up by the stall. A long stall on a GUI thread (eg Display Manager or VIC thread) leads to an unresponsive GUI. A long stall on the application thread leads to problems such as data not updating.

Module Name

The name of the module (within the identified source file) that contains each statement.

Code ID

For each statement, identifies the folder where the module file can be found, the module name, the running state within the module and the numerical index of the statement within that state. If you have access to the .SRC file of the module, you may click this item to open the file. Note that if you are using the pop-up profiler window, the file may open in the background.


Profiler Settings

This dialog is used to control how the profile collects information.

Profile Duration

You may set a fixed length of time for the data collection period. This value is always in seconds - if you enter a decimal value, it will be rounded down to the nearest full second. If a duration is set, you can still use the Stop button to end a data collection period whenever you wish.

Save Settings

When auto-save is enabled, a fresh save will occur each Sample Interval seconds while the profiler is collecting data.

Options in this box control how the profiler saves information to a file. The file is saved to the Data folder under the application's Data folder and will have the name Year-Month-Day_Hour-Minute-Second.extension. The extension may be either .Profiler or .CSV.

The .profile files contain much more information than the .CSV files, including all of the profile data organized in the tree hierarchy. When providing a profile to Trihedral, the .profile file should always be used.

When running the Source Debugger on a thin client, it is possible to save the profile to the local machine instead of the server. You cannot load a save file on a Thin Client. You must use a machine with an installed Thick Client. Auto Save will only save profiles to the server.

Max. Statements Per Log

The data file will contain information sorted in decreasing order by count, by running time or both. Within each section, there will be Max Statements Per Log rows.

Count Threshold

When selected, the file will contain statements sorted by execution count in decreasing order. At least one statement must be executed this many times within the data collection period to be included in the saved file. Assuming that one statement crossed the threshold level, exactly Max Statements Per Log rows will be included, regardless of how many statements crossed the threshold level.

Time Threshold (ms)

Same as Count Threshold, except that this group of statements is sorted by total execution time during the collection period.

If neither County Threshold or Time Threshold are selected, the profile results for logging are sorted by whichever column, and in whichever order is selected in the grid list display.

Hide Grid While Profiling

The statements that create the grid display in the profiler can be executed many times while data is being collected and will be included in the statistics. You may choose to disable the grid during data collection.

Auto Start

Not recommended for typical use. When selected, the profiler will begin collecting data as soon as it starts. You may use a set collection time, or the stop button to end the collection time period.


Dump Files

Viewing: Troubleshoot > Source Debugger > Dump Files

Dump Files & Forcing Communication Log Files

While the following instructions are true, it is better to generate a dump file using the Windows Task Manager.

You can generate a dump file as a snapshot of the current system. To generate a dump file:

  1. Click the Create Dump File button
  2. Browse to the location where you wish to save the dump file.
  3. Enter a name for the dump file in the File Name field.
  4. Click the Save button. The dump file will be generated and saved in the specified location.

Viewing the Contents of a Dump File

The Source Debugger can do all the same things with a dump file that you can do with a live system. To open a dump file for debugging:

  1. Click the Open Dump File button. The Open Dump File dialog will open.
  2. Browse to and select the dump file you wish to analyze.
  3. Click the Open button.

The selected dump file will open in the code display window in its own separate tab labeled "Summary (Dump)" (see Source Debugger: Summary (Dump) Tab).

While viewing a dump file, you cannot change the code coverage view. For example, if the dump file was created with code coverage turned on, you cannot turn that view off while viewing the dump file.

Flush Communication Trace Files

You can force VTScada to export communication log files instantly rather than waiting for a time or numeric limit to trigger the write. This is more easily done using the Export Comm Log Widget but can also be done using the Source Debugger.

  • To trigger all system logs (applies only to VoIP) search for System.DiagnosticLogTrigger and change it to any different value (usually 1).
  • To trigger all applicatio logs (applies to Twilio, SMS Appliances, and ModemManager), search for Code.DiagnosticLogTrigger and change it to any different value (usually 1).


Working with Breakpoints and Data Breakpoints

Viewing: Troubleshoot > Source Debugger > Working with Breakpoints and Data Breakpoints

Breakpoints and Data Breakpoints

Use breakpoints to test and debug programs by pausing thread execution so that the status of the application can be examined.

Breakpoints (and watches) can be saved from one debugging session to another using the Save Workspace and Open Workspace buttons. Breakpoints can be temporarily disabled without being removed by toggling the Disable tool in the toolbar, [image] (Ctrl + F9)

There are two types of breakpoints that are referred to throughout this document:

Breakpoint:

The word "breakpoint" used by itself means a code breakpoint. This is a programmer-defined break in code that when reached, triggers a temporary halt. See: Set and Clear Breakpoints

Data breakpoint:

A data breakpoint is set on a variable and triggers a break when the value is first set or when it is changed. See: Set Data Breakpoints

What happens when a breakpoint is hit:

Your application will run at full speed until a statement that contains a breakpoint is about to be executed. At that point, execution of the thread that is attempting to execute the statement containing the breakpoint will be suspended. A detail line will be added to the breakpoint tab of the action window, identifying the thread that has been suspended and the breakpoint that was hit. The breakpoint tab will be forced to the front of the action window, the tab containing the source code with the breakpoint will be forced to the front of the code display window, and the Source Debugger window itself will be made the active window. Additionally, the module trees will automatically be refreshed and positioned at the module instance that contains the breakpoint. This means that you can see a "snapshot" state of the module trees at the time that the breakpoint was encountered. A yellow arrow will be displayed beside the breakpoint that was hit.

If your application uses multiple threads, it is possible for different threads to execute a given statement.

What happens to other threads when a breakpoint is hit:

Note that only the thread that executes a statement containing a breakpoint will be suspended. Other threads within VTScada, including those within your application, will continue to run normally. If this were not the case, you wouldn't be able to use the Source Debugger. This means that while one thread is paused on a breakpoint, another thread may attempt to execute the same statement and cause another breakpoint. This would result in exactly the same sequence of events, with a second entry showing a hit breakpoint being made in the breakpoints tab of the action window. This might happen if a breakpoint is placed in a subroutine that can be called by modules running on different threads.

While a thread is paused at a breakpoint, you may navigate to any module in any of the module trees that you wish and examine or modify the contents of any data variable. In other words, suspension of execution of a thread affords you the time to examine the state of things at a given point in the execution of your application. This can be most useful in detecting transitional states that would otherwise be difficult to find.

Continue execution past a breakpoint:

To continue execution past a breakpoint, ensure that the breakpoint from which you wish to continue is selected in the breakpoints tab of the action window, then use any of the following. If multiple breakpoints are hit, only the thread for the selected breakpoint will be continued.

  • Continue tool (F5). Execution will continue normally.
  • Step Into tool (F11). If the breakpoint was set on a subroutine call, that module will open and execution will advance by one statement.
  • Step Out tool (Shift+F11). Run the remainder of the subroutine at full speed and break on the next statement in the current thread after the subroutine's Return statement executes. The "next statement" may be the script statement following the subroutine call, the next steady-state statement to be evaluated on the same thread, or the first statement of the freshly constructed module instance if stepping out of a constructor.
  • Step Over tool (F10). Execution will advance by one statement within the current module. If the next statement is a subroutine call, execution will proceed through that module without pause.
    Note that more than one statement might be written on a single line, as is sometimes the case with IfThen, IfElse, WhileLoop, DoLoop, Case, or an Execute clause. In this case, the step will advance through the statements without leaving the current line.
  • Run to Cursor tool (F12). To use this, you must first select a statement in the code display window other than where the breakpoint is set. Execution will continue to the selected statement then pause again.

Breakpoints in critical sections:

A breakpoint can be placed on any source code line including critical sections. When a breakpoint is hit within a critical section, the critical section is effectively released, then re-acquired when you continue execution. Depending on the code contained within the CriticalSection, this may cause behavioral differences within your application.


Setting a Breakpoint

Viewing: Troubleshoot > Source Debugger > Working with Breakpoints and Data Breakpoints > Setting a Breakpoint

Set and Clear Breakpoints

  1. Working in the code display window, select the statement line where the breakpoint is to be set.
    Only executable statements may have breakpoints. You cannot set one on variable declarations, state names, brackets, or comments.
  2. Click the Toggle Breakpoint tool or press F9.

An orange dot will be added beside the selected statement and a matching entry will be added to the breakpoints list.

Find code that has a breakpoint:

You can set breakpoints in several modules. Often, modules are long, and you may scroll well away from the statement where the breakpoint is set. In either case, you can reload the code display window by double-clicking the breakpoint in the breakpoints list.

Clear a breakpoint:

  1. Select the breakpoint, working either in the code display window or the breakpoints list.
  2. Click the Toggle Breakpoint tool or press F9.

Changing code when breakpoints are set:

If you edit and compile a module, within which a breakpoint is set, the breakpoint may shift to another statement. If you delete the module within which a breakpoint is set, it will disappear.


Setting a Data Breakpoint

Viewing: Troubleshoot > Source Debugger > Working with Breakpoints and Data Breakpoints > Setting a Data Breakpoint

Set Data Breakpoints

A data breakpoint can be set on standard variables, a static array and on the root value of a dictionary, but will not work with a pointer to a value, a dynamically allocated array or with values within a dictionary.

To set a data breakpoint:

  1. Ensure that the module containing the variable is running.
  2. Working within the module content window, select the variable on which you wish to set the data breakpoint.
  3. Click the Toggle Breakpoint tool in the toolbar or press F9.

By default, data breakpoints are triggered when data is set in the selected variable. If you prefer that the breakpoint be triggered whenever data changes in the variable, proceed as follows:

  1. Select the data breakpoint in the breakpoints tab of the action window.
  2. Click the Breakpoint Properties button in the toolbar or press Alt-F9.
    The Breakpoint Properties dialog opens.
  3. Select the option, Break on data change.


Conditional Breakpoints

You can create an expression to apply to any breakpoint, both code and data. For example, you might want a breakpoint to trigger only if a variable has a certain value or is above a certain level.

To apply a condition to a breakpoint:

  1. Click the Breakpoint Properties tool in the toolbar.

The Breakpoint Properties dialog will open.

  2. Select the Conditional Breakpoint check box.
  3. Click OK.

A question mark will appear in the breakpoint symbol, and a field will open to allow you to enter an expression in the action window.

  4. Enter a valid expression in the field, such as Name == "AI20_1".
  5. Click OK to the right of the field.


Working with the Execution History

The Execute History display of the System Summary panel shows a history of statements that have executed, sorted so that the most recent are at the top of the display. Color bands alternate light and dark with each change of thread ID in the list. It only records steady-state statements or top-level statements within a script. It does not separately record sub-statements inside WhileLoop, IfThen, etc.

The list does not update dynamically. You must click the Refresh button [image] to see new entries.

The arrows labeled Scroll List by Thread allow you to step over entries in the list having the same thread ID, thereby scrolling quickly through the display to see each thread that was running.

Double-click on any entry in the list to both:

  • Open that module in the module content list window.
  • Enable filtering of the display for modules that either call the selected module, or thread entries for modules matching the one selected.

Filter the Thread History

After double-clicking on an entry in the history list, you can filter the display for modules that call the one selected, or only for thread instances of the selected module.

By selecting the Show option., "Just Pump" and clicking the Update Filter button, you will limit the display to modules and threads related to module, Pump.

By selecting the Show option., "Just Pump [3 of 3]" and clicking the Update Filter button, you will limit the display to only threads belonging to the selected instance of Pump. The numbers in square brackets refer to the module instance and correspond to the instance selected in the module content list window:

Select the Thread to Display

Use the Thread selector to limit the display to instances of a given thread.

After selecting a thread to display, you must click the Update Filter button before the list will change.

Modules related to the Source Debugger are hidden from the thread history list by default.

You can use the Copy button to copy the window contents to the Windows™ clipboard for review elsewhere.


Source Debugger Options

You may configure certain basic options for the way the Source Debugger looks and works. To do so, open the Options dialog from the toolbar.

There are three tabs within this dialog, each of which requires its own topic:


General Tab

Debugger runs at high thread priority

The Source Debugger is a VTScada script application, and as such is subject to equal time-sharing of the CPU with other VTScada applications. If this check box is selected, the proportion of time the Source Debugger gets on the CPU (with respect to other VTScada applications) will be increased. This has the effect of allowing the Source Debugger user interface to respond more quickly when another VTScada application is consuming more CPU time than it should. It is useful to analyze the reason that another VTScada application is behaving in that way.

Timestamps automatically translated

Timestamps are represented in VTScada double-precision floating-point numbers (e.g. 1129884300.250). Checking the Timestamps automatically translated check box will cause doubles that are in the range for timestamps to display in a more readable format. For example, 1129884300.250 will translate to Oct 21, 2005 08:45:00.25.

Automatic workspace reload

If selected, your workspace ( selected module, breakpoints and watches) will automatically be saved while you work. When you stop the source debugger then re-open it, the automatically-saved workspace will be loaded immediately, allowing you to continue working from the point where you stopped.

Code coverage Colors

Three highlight colors are used when using the Code Coverage feature. If you find the default colors unsatisfactory, you may select others.


Source Paths Tab

It is important that the Source Debugger always opens the correct source file (.SRC or .WEB file) and symbol file (.SYM) for the module being examined.

The Source Paths tab enables the Source Debugger to specify the path to the correct version of a source file when the source file is stored on a PC other than the one on which the Source Debugger is running. It further enables the correct version of a source file to be opened when examining a dump file.

When there are no entries in the fields of the Source Paths tab, the Source Debugger attempts to open the file from which the .RUN file was compiled. For example, if C:\VTScada\VTS\AnalogIn.RUN is the .RUN file containing the module, "AnalogInput" and it was compiled from the source file C:\VTScada\VTSAnalogIn.SRC, the Source Debugger will attempt to open the source file C:\VTScada\VTS\AnalogIn.SRC and the symbol file C:\VTScada\VTS\AnalogIn.SYM.

A problem arises when the file C:\VTScada\VTS\AnalogIn.SRC is not the source file that was compiled to produce the .RUN file. A simple solution is to simply specify a list of paths to be searched for the source/symbol files. This, however, is not ideal, as it is possible for a module in an application layer to have the same name as one in another layer (e.g. the VTScada layer). Therefore, the specification of search paths is more complex. Thus there are three elements to the Source Paths tab of the Options dialog that control the source file searching behavior.

Substitute VTScada Installation Path

The Substitute VTScada Installation Path field will accept a path to an alternative VTScada installation folder tree. Any module compiled from a source file located within the VTScada installation folder tree will have their source/symbol files loaded from the path specified in this field.

External Folders

The External Folders list will accept one or more paths outside the VTScada installation folder tree. Any module compiled from a source file outside the VTScada installation folder tree will have their source/symbol files loaded from a path in the External Folders list. The list is parsed from top to bottom (That is, if the source/symbol files cannot be found in the path at the top of the list, the next path down the list will be searched). Searching stops when a file is found or the end of the list has been reached.

Always Search

The Source Debugger normally only searches the paths specified in the Substitute VTScada Installation Path field and the External Folders list if the source file indicated by the module is not found. If the Always Search check box is selected, the Source Debugger will be prevented from search for the source/symbol files in the path indicated by the .RUN file. Instead the Source Debugger will be forced to search for the source/symbol files in the paths specified in the Substitute VTScada Installation Path field and the External Folders list.

The following will assist you in the proper configuration of the Source Paths tab when you are analyzing a dump file.

Analyzing a Dump File

Most of the time, the version of VTScada that is contained in a dump file will not match the version of VTScada that is running the Source Debugger. In such cases, you want the Source Debugger to search a specific location for the source/symbol files, rather than searching the folder in which the version of VTScada running the Source Debugger is located.

For files within the dumped VTScada installation folder tree:

  1. Create a folder tree that mimics the dumped VTScada installation folder tree.
  2. Copy the source and symbol files for the version of VTScada corresponding to the dumped version.
  3. Paste the copied files into the new folder tree created in step 1.
  4. Enter the path of the new tree into the Substitute VTScada Installation Path field.
  5. Select the Always Search check box.

For files outside the dumped VTScada installation folder tree:

  1. Create one or more folders.
  2. Copy the source and symbol files for the version of VTScada corresponding to the dumped version.
  3. Paste the copied files into the new folder tree created in step 1.
  4. Enter the path(s) of the new folders into the External Folder list, using the Add button.
  5. Use the Move Selected buttons to arrange the folder list correctly.
  6. Select the Always Search check box.

Remote Debugging Using the VIC

For files within the dumped VTScada installation folder tree:

  1. Create a folder tree that mimics the dumped VTScada installation folder tree.
  2. Copy the source and symbol files for the version of VTScada corresponding to the dumped version.
  3. Paste the copied files into the new folder tree created in step 1.
  4. Enter the path of the new tree into the Substitute VTScada Installation Path field.
  5. Deselect the Always Search check box.

For files outside the dumped VTScada installation folder tree:

  1. Create one or more folders.
  2. Copy the source and symbol files for the version of VTScada corresponding to the dumped version.
  3. Paste the copied files into the new folder tree created in step 1.
  4. Enter the path(s) of the new folders into the External Folder list, using the Add button.
  5. Use the Move Selected buttons to arrange the folder list correctly.
  6. Deselect the Always Search check box.

The source files will be loaded from the server to which the VIC is connected, unless they are not found, in which case the files will be searched for on the PC running the VIC. The paths specified must therefore be on the PC running the VIC. This enables you to remotely debug a production system that does not have the source code installed on it, or has only a subset of the source code (e.g. an application layer).

Local Debugging of a Production System

For files within the dumped VTScada installation folder tree:

  1. Create a folder tree that mimics the dumped VTScada installation folder tree.
  2. Copy the source and symbol files for the version of VTScada corresponding to the dumped version.
  3. Paste the copied files into the new folder tree created in step 1.
  4. Enter the path of the new tree into the Substitute VTScada Installation Path field.
  5. Deselect the Always Search check box.

For files outside the dumped VTScada installation folder tree:

  1. Create one or more folders.
  2. Copy the source and symbol files for the version of VTScada corresponding to the dumped version.
  3. Paste the copied files into the new folder tree created in step 1.
  4. Enter the path(s) of the new folders into the External Folder list, using the Add button.
  5. Use the Move Selected buttons to arrange the folder list correctly.
  6. Deselect the Always Search check box.

By using paths that are either UNC names or shares on mapped drives, source files will be loaded from the production system unless they are not found, in which case they will be loaded from a networked file system.

This enables you to debug a production machine live on site, while not having to copy source files onto it.

Debugging a Production System Using Remote Control

For files within the dumped VTScada installation folder tree:

  1. Create a folder tree that mimics the dumped VTScada installation folder tree on the production system.
  2. Copy the source and symbol files for the version of VTScada corresponding to the dumped version.
  3. Paste the copied files into the new folder tree created in step 1.
  4. Enter the path of the new tree into the Substitute VTScada Installation Path field.
  5. Deselect the Always Search check box.

For files outside the dumped VTScada installation folder tree:

  1. Create one or more folders on the production system.
  2. Copy the source and symbol files for the version of VTScada corresponding to the dumped version.
  3. Paste the copied files into the new folder tree created in step 1.
  4. Enter the path(s) of the new folders into the External Folder list, using the Add button.
  5. Use the Move Selected buttons to arrange the folder list correctly.
  6. Deselect the Always Search check box.

As indicated in the instructions above, you will have to copy the source/symbol files onto the production system, however, you may copy the source/symbol files into separate folder trees on the production system, making tidy-up at the end of the debugging session easier by allowing you to later delete the source/symbol files from the separate tree. This minimizes the risk of your inadvertently deleting important files from the production system when debugging using source files that you do not want to leave on the production system when finished.

The user interface of your debugging session will be running on the production server’s display. Ensure that this does not interfere with system operation. While this method of debugging can be used, other methods are preferred.


Symbol Server Tab

In order to interpret the binary image that a dump file contains, the Source Debugger requires information about the internal structure of the VTScada engine (VTS.exe). As this changes from version to version of the engine, the Source Debugger uses a program database (.PDB) that is generated as part of the process of building VTS.exe.

How Does the Source Debugger Locate the Correct .PDB File?

The Symbol Server tab enables the Source Debugger to locate the correct .PDB file for the dump image being examined.

The default setting for the Local Symbol Cache Path field (which is pointed to the DumpTools subdirectory within the VTScada installation directory (e.g. C:\VTScada\DumpTools) where the .PDB file is stored) should result in the correct .PDB file being located by the Source Debugger. The Symbol Server Location field is for internal use by Trihedral only, and as such does not require input.

(Trihedral only) The Source Debugger uses a two-phase process to locate the correct .PDB file:

  • The Local Symbol Cache Path is examined for the .PDB file.
  • If the correct .PDB file is not located in the DumpTools directory, the Source Debugger will search a symbol server (Microsoft terminology) for the correct .PDB file.
  • A symbol server can hold many versions of .PDB (one for each version of VTScada that is released). Internally, this is normally a network share (e.g. \\<trihedralserver>\VTSSymbols), but can be a URL (e.g. http://<trihedralservername>.trihedral.com/VTSSymbols).

Both fields do not have to be filled in. If only the Local Symbol Cache Path field is filled in (as it is by default), the .PDB file is expected to be found there. If both fields are completed, the operation is as described as above, with PDBs fetched from the symbol server stored in the Local Symbol Cache Path, there by reducing network traffic for the remainder of this debugging session and for future sessions that require the same .PDB. The .PDB files cached locally can be manually deleted if no longer required.

If only the Symbol Server Location field is filled in, there is no local caching of the .PDB file, and all accesses to the desired .PDB file are done over the network. This is a slower process, but avoids storing a .PDB file on the local hard disk.


Save Your Workspace

A Workspace is the set of the selected module, the breakpoints, and the watches in your session. You may save a workspace explicitly by using the Save Workspace button in the toolbar, or you may set the Auto Workspace Reload check box in the Options menu.

When loading a workspace, either by using the Open Workspace button to load a selected workspace file that you saved earlier, or by using the Reload Auto Workspace button to load the last automatically saved workspace, you may choose to either replace the workspace you are working in, or you may merge the current workspace with the one you are opening.


Code Coverage

Use the code coverage feature to see what modules, states, statements and variables have been executed or used. This is useful in a number of ways, not least of which are:

  • Code that has not run cannot have caused an error.
  • Code that should have run but hasn't, may indicate the location of an error.

The following tasks are associated with code coverage. To interpret the display, see the following topic, The Code Coverage Display.

Refresh the code coverage display

The code coverage counter is always running, but the display does not update dynamically. To update the display, use the Refresh Code Coverage Information button in the toolbar. This will provide you with an up-to-date view of what statements and variables have been used.

Step between blocks of covered code

In a module with minimal code coverage, there may be long gaps between the uncovered highlights. The Next Highlight and Previous Highlight buttons allow you to quickly jump from one block of uncovered code to the next.

Use a code coverage merge file

You can save the current record of what code has been covered to a file, and then merge that information back to the current display. This can be useful in at least two situations:

  • If you are working as part of a team, each team member can test a different part of a large application and save their code coverage history to a file. These files can then be collected and merged into one display to provide a complete picture of what code and variables have been used in an application
  • You may wish to reset the counters to zero before running a test, but not want to lose your current code coverage information. You can save the current code coverage information to a file before performing the reset, then after you have finished your test, merge the code coverage information back into the current display.

Reset the code coverage counts

To reset all the counters to zero for a fresh start on the code coverage, use the Reset button in the toolbar. Use this to obtain a clear view of code coverage from a fresh starting point.

While viewing a dump file, you cannot change the code coverage view. For example, if the dump file was created with code coverage turned on, you cannot turn that view off while viewing the dump file.


The Code Coverage Display

When code coverage mode has been switched on, using the Toggle Code Coverage button, the module tree and the code display windows will change. The module tree will display each module with a colored indicator that shows what percentage of the module has been covered by running code.

Resting the mouse pointer over a module causes a tool tip to appear, showing the code coverage within the module, and within the entire module sub-tree.

The color indicators are as follows:

  • Gray - no code coverage.
  • Red - minimal code coverage.
  • Orange - medium coverage.
  • Yellow - high coverage.
  • Green - full coverage.

The code display window will look similar to the following:

The highlight colors are user-configurable. (See: Source Debugger Options). The default colors have the following meanings:

  • Green background: Indicates variables that have not been covered.
  • Red background: Indicates statements that have not been covered.
  • White lines indicate code that has been run and variables that have been used.

If the entire window changes to a yellow background, this indicates that the source code has been changed since the application was last compiled. For the code coverage system to work, all changes must be compiled. You may need to re-start the application.


Limited Thin Client Use

You can use the Source Debugger with a Thin Client (Both the VTScada Anywhere Client and the VTScada Internet Client (VIC)). There are some things to consider:

  • Child bubbles are not supported on Thin Clients.
  • Only one user can access the Source Debugger at a time. Multiple users cannot sign into the same Source Debugger through a Thin Client. It is not possible for a Thin Client user and a Thick Client user to use the same Source Debugger at the same time.

Saving Profiles

Saving Profiles using a Thin Client only works in a limited capacity.

You can save a profile but you cannot load it on the Thin Client. You must use a machine with an installed Thick Client to load a profile.

Auto Save on a Thin Client will save to the server. Manually saving a Profile through the Save Settings will save a .profile or .CSV file locally.

You will not be able to load a save file on your local machine on a Thin Client.

To load a save file, the machine must have an installed thick client.

Saving a profile to your local machine is useful if, for example, you want to send a .profiler or .CSV file to tech support and you don't have access to the server.


Test Framework Application

At Trihedral, all new code being written for VTScada is created using test-driven development. For an understanding of how to design and use tests, the following Internet sites may be of use:

http://www.agiledata.org/essays/tdd.html

http://en.wikipedia.org/wiki/Test-driven_development

Tests are written before code. After the related code has been written, the Test Framework application is used to run and analyze those tests to ensure that the code works as designed. This application can be launched from the Source Debugger or from the VAM.

Tests are organized on an application-by-application basis. You may choose which application to test, and Test Framework will load an independent copy of the application and automatically discover all tests that are defined within the application.

A tree showing all tests and all modules that directly or indirectly contain tests will be generated automatically. Tests may be enabled or disabled on an individual basis, or at a tree-node level.

It is the responsibility of the VTScada programmer to write their own tests for their individual applications. Instructions are provided in the following topics.

The Framework may be used by customers for their own modules, but no technical support is provided. Please request the Test Framework package, available from the Trihedral marketing department or technical support. This zip file contains examples of the files necessary for a test.


Test Framework Application Components

An example of the Test Framework application:

Select Application Window

Select a running application for testing.

Select Application from List

Launches the Select Application dialog, which displays a list of VTScada applications that can be selected for testing.

Message Area

To the right of the tool bar buttons appears the message area field. Any important information about the application selected for testing will be displayed in this field. (For example, the application needs to be compiled.)

Module Tree

The module tree area appears just under the toolbar to the left of the dialog, and displays the modules that are included in the current test. You may use the module tree to select/deselect the tests you wish to run within the loaded application (see Running a Test Using the Test Framework).

Summary Area

The summary area displays a summary of the testing, including statistics on:

Tests Failed | The number of tests that did not pass during this run.
Tests Passed | The number of tests that passed during this run.
Modules Failed | The number of modules that failed during this run.
Modules Passed | The number of modules that passed during this run.
Asserts Failed | The number of Asserts that failed during this run.
Asserts Passed | The number of Asserts that passed during this run.
Modules w/o Tests | The number of modules that did not include tests.
Modules with Tests | The number of modules that included tests.
Enabled Tests | The number of tests that were enabled.
Total Tests | The total number of tests that were run.
Elapsed Time | The total elapsed time (in hh:mm:ss) that it took to run the test.
Remaining Time | The total amount of time (in hh:mm:ss) outstanding for the test being run.

Run Tests

Run tests on the selected modules.

Pause Tests

Pause the tests that are running.

Resume Tests

Resume testing after a test has been paused.

Stop Tests

Stop the running tests.

Suppress Manual

Check this box to select that only the fully-automated portions of the tests should run. This depends on the test being written to support the automation flag.

Failures Only

Select this option if you wish the test list to display information only on those tests that failed .

Show All

Select this option if you wish the test list to display information on all tests, passed and failed.

Test List

Presents information on the tests that have passed or failed (depending upon whether the Failures Only or the Show All radio button has been selected). Tests that passed are presented in green text, while tests that failed are highlighted in red. The test list presents the following information for each test:

Test | The Test column identifies the name of the application directory, source file, and module for the test.
Message | The Message column presents a short message identifying the value that was expected and the value that was returned on completion of the test.
Comment | The Comment column displays any comments relevant to the test.
Status | The Status column indicates whether the test passed or failed.
Duration | The Duration column displays the amount of time (in milliseconds) that it took for the test to complete.
When | The When column indicates the exact time and date that the test was completed.
Counts | The Counts column indicates the number of times the test was run. (This count is incremented each time the Run Test button is clicked.)
Failures | The Failures column indicates the number of times the test failed within each testing session.


Writing Tests for the Test Framework

Tests are defined by creating a module of class Test within the module to be tested. This topic provides general information, but to write tests, customers must obtain a copy of the test framework package, available from Trihedral marketing or technical support.

Test guidelines:

  • A module may contain zero or more tests.
  • Tests may not contain other tests.
  • Each test must either return Invalid if it is a subroutine, or slay itself upon completion.
  • A test must call one or more Assert functions.
  • Tests are passed three parameters:

Framework: Object value of the Test Framework code where the Assert functions are defined.

Owner: Module value of the module to test (static parent of the test module)

Automated: If TRUE, indicates that only the automated tests should be run.

  • A test is responsible for creating the environment for the module under test (MUT). This can be done by defining globally-referenced variables and modules in the MUT within the Test module itself, or with the use of Fixtures, or both.
  • Variables outside the scope of the MUT Closed Module Under Test. Used by the Test Framework must exist in the Test module or in a fixture.
  • A test is run in its own thread.
  • The MUT is reloaded for each test to make sure all temporary variables are cleared before each test
  • Tests run with no parent scope aside from any fixtures declared.
  • The Automated parameter is often used to skip or end a test if manual actions are required.

Assert Subroutines and Statements

Asserts are either subroutines or steady state statements that are called within a test to validate the results of the test. Ideally, there should be one assert per test.

An assert called in steady state requires an additional parameter at the end (compared to an assert called as a subroutine), which sets an expiration time in seconds. If the test does not pass within that time, it will log as a failure and return TRUE, indicating test completion. A test that passes within the time frame will log the pass and return TRUE immediately.

A steady state assert call will not return the result of the test but instead, only document whether the test passed or failed, then return TRUE to signify that the test has completed. The return value can be used as a trigger to indicate when the test has completed and then allow code to move on to another section.

Eight Assert functions are defined:

  • AssertTRUE(Condition, Comment [, ExpireTime])
  • AssertFALSE(Condition, Comment [, ExpireTime])
  • AssertEqual(Expected, Actual, Comment[, Tolerance , ExpireTime])
  • AssertNotEqual(Expected, Actual, Comment[, Tolerance , ExpireTime])
  • AssertGreater(Expected, Actual, Comment [, ExpireTime]t)
  • AssertGreaterEqual(Expected, Actual, Comment [, ExpireTime])
  • AssertLess(Expected, Actual, Comment [, ExpireTime])
  • AssertLessEqual(Expected, Actual, Comment [, ExpireTime])

The parameters are:

Condition | Boolean condition determining pass/fail state of the test. Invalid is an acceptable condition.
Comment | The Comment will be displayed in the test and should be a brief statement of the test to help identify the source of a failure.
Expected | The value to be compared to the known value. Invalid may be used.
Actual | The value that the first parameter should be <test> than/to.
Tolerance | Maximum allowable difference between Expected and Actual for equivalence test of numbers. Defaults to 0 if Invalid or omitted.
ExpireTime | The time in seconds in which a steady state assert will run before logging a failure.

If the condition asserted by the call is true, then the Assert has passed and no failure will be recorded. All Asserts for a test must pass in order for the test to pass. When doing an AssertEqual, if both the condition and the expected value are Invalid, the test will pass.

Fixture Modules

Fixtures are a mechanism used to handle common test environments. A fixture is created by defining a module with no special class in a scope higher than the tests using the fixture. Fixtures are launched in the order declared within the test. They become the scope tree for the Test module.

To have a test use a fixture, you must define a variable of type FIXTURE with the same name as the fixture module within the test. The fixtures are launched in the order declared within the test.

Fixtures may optionally contain a FixtureReady variables. If this variable is defined, the Test Framework will wait until this variable becomes TRUE before launching the next fixture or the test itself.

Using the ThreadIdle Function

The ThreadIdle function has been created to help support testing. It takes a single parameter, which is an object value implying a thread. The return value is TRUE when there are no statements on the to do list for the thread. It does not consider timers in the return value.

This function is useful when instantiating the module under test (MUT) and waiting for the initialization of the MUT to complete before executing the Assert calls.

Related Functions:

SetOverride - used to override op codes with a specified script.


Running Tests

Your application must have tests written especially for it before you can use the Test Framework application to test it. Please read Writing Tests for the Test Framework to learn about writing tests for your application.

Select an application for testing using the Test Framework

There are two ways to select a VTScada application for testing using the Test Framework application.

A) Selecting a stopped application for testing

  1. Run the Test Framework application.
  2. Click the Select Application from List button (second button from the left in the tool bar). The Select Application dialog will open.
  3. Select the VTScada application containing your tests.
  4. Click OK. The Select Application dialog will close, and the selected application will load into the module tree of the Test Framework application.

B) Selecting a running application for testing

  1. Run the Test Framework application.
  2. Run the VTScada application you wish to test using the VAM.
  3. Click the Select Application Window button (first button from the left in the tool bar).
  4. Click anywhere on the running VTScada application containing your tests. The selected application will load into the module tree of the Test Framework application.

After the application has been loaded into the Test Framework application, you may run a test.

Run a test

  1. Select the modules containing the tests you wish to run for the loaded application.

To do so, click the plus button to the left of each module to expand the module tree. Any modules you wish to test should display a check mark to their left. If you wish to test all modules, ensure that the root module at the top of the tree displays a check mark.

  2. Click the Run Tests button. The progress of the tests will be indicated by the progress bar just above and to the left of the Run Tests button. After the tests are complete, the test list should populate with data.
  3. Select the test data you wish to review:
  4. Select the Show All radio button to review data on all tests, both passed and failed, OR
  5. Select the Failures Only radio button to review data on only those tests that failed.

Pause a test

If you wish to pause a running test, click the Pause Tests button.

Resume a paused test

If you have paused a test and wish to continue running it, click the Resume Tests button.

Stop a test

If you wish to stop a running test, click the Stop Tests button.


Viewing Test Results

View all tests (passed and failed)

Select the Show All radio button. The test list will display any passed tests in green text, while any failed tests will be highlighted in red.

View failed tests

Select the Failures Only radio button. The test list will display any failed tests highlighted in red. If no tests have failed and the Failures Only radio button has been selected, the test list will appear empty.

You can confirm whether a test has run by using the Code Coverage feature of the Source Debugger.


Thread List Application

Applications, as well as some system components, run in their own execution threads so that they do not interfere with the execution of other applications or components. The Thread List analysis utility provides a list of the separate threads of execution for which VTScada is responsible.

If the Thread List application is not listed in the VAM, you must manually add it. The Thread List application's directory is named "ThrdList", and is stored within the VTScada installation directory.

If an execution thread becomes blocked (i.e. freezes or gets stuck while executing a statement), the Thread List analysis tool can be used to identify the offending statement that is causing the blockage. This information provides a starting point for examining the scripting code that has caused the thread to be blocked.

The Thread List utility:

As shown, the Thread List is composed of the following elements:

Pin

The pin button can be selected to always keep the Thread List window on top, or can be deselected to allow the Thread List window to be minimized.

Refresh

The Refresh button can be clicked to update the display of threads.

Auto Refresh

The Auto Refresh button can be latched on to result in the display of threads being updated automatically twice a second.

Save

The Save button can be clicked to save the current thread list data to either a text file or a .CSV file. A file dialog will prompt for a name and provide a choice of setting the extension to either ".txt" or ".csv". In older versions of VTScada, this file name would have been "ThreadLog.txt", located within the ThrdList directory which is located within the VTScada installation directory (e.g. C:\VTScada\ThrdList\ThreadLog.txt).

Append

The append button can be selected to add new data to existing files rather than over-writing them.

Thread Name

The Thread Name column displays the name or title assigned to each thread.

File Name

The File Name column displays the path to and name of the document file that contains the executing statement.

Module Name

The Module Name column displays the name of the module within the document file (specified in the File Name column) that contains the executing statement.

State

The State column displays the state within the module that contains the executing statement.

Statement #

The Statement # column displays the numerical index of the executing statement within the state.

Thread ID

The Thread ID column displays the ID number for each thread.


Trace Viewer Application

Use the Trace Viewer application to monitor the content and parameters of driver messages and VTScada-related network traffic as it occurs. Depending on the license you purchased with VTScada, up to five sources of information are available. The collected data is also logged to standard Access database files for later viewing. Because data is always logged, there is no export tool in the Trace Viewer.

The Trace Viewer application should not be confused with the Trace VTScada Actions Application, which enables you to select different VTScada services (such as the RPC Manager and Modem Manager), and actions (the Navigator or SQL calls), and monitor the selected items by saving pertinent data about them (such as the date and time they executed) to disk.

There are three components involved in tracing:

  • The communications to be traced.
  • Each message source has its own format and therefore is stored in its own database.
  • The module that collects and writes the data to the database.
    This is DBTrace, a system-level module that maintains live communications with the Trace Viewer.
  • The viewer.
    This is the Trace Viewer application, where you can select, filter and display the communications data.

(Service names that contain a child-tag delimiter will be shown with a forward-slash, rather than the more usual back-slash.)

Trace files are regular Microsoft Access .MDB files, stored in the TraceFiles folder within the VTScada installation directory.

These files are deleted as they age, with the default set to 30 days. If you wish to modify this setting, you may do so using the DbTraceDaysToPreserve variable in Setup.ini. You may also control the size using DbTraceFileSize.This task is performed by the Trace Viewer, not the VTScada engine, and therefore older files are note deleted unless the Trace Viewer is running.

The Trace Viewer can collect the following information:

Driver Messages for running applications (always available while an application is running)

See: Driver Tracing

  • Timestamp, accurate to the nearest thousandth of a second
  • Direction (Sent or Received from the driver)
  • Service name
  • Driver name as entered in the tag
  • Driver area as entered in the tag
  • Driver description as entered in the tag
  • Port name that the driver is attached to
  • Data included in the communication to/from the driver (a string of hexadecimal values)

Historian Diagnostics (always available)

See: Historian Diagnostics

  • Error messages only. One or more Historians must be selected for tracing. Information collected includes:
  • Timestamp, accurate to the nearest thousandth of a second
  • Historian name
  • Trace type
  • Tag name - the source of the data that did not write.
  • Error code - a numeric code identifying the error.
  • Error text.
  • Message

RPC Diagnostics (always available)

See: Remote Procedure Call (RPC) Tracing

  • Timestamp, accurate to the nearest thousandth of a second
  • Identification of internal events
  • The message’s routing flag
  • Sequence number of the message
  • Direction (To or From the server identified by the IP address)
  • IP address of the message source or destination
  • Name of the application sending or receiving the message
  • Name of the service or machine
  • Data and parameters of the message

SOAP Messages (available only if you have a license for Remote Data Access)

See: Features for SOAP Message Tracing

  • Timestamp, accurate to the nearest thousandth of a second
  • Message number (large messages might be split across more than one line)
  • Message status (an HTML error code indicating success or failure)
  • Source IP address and Port number
  • Destination IP address and Port number
  • Indication of whether the message is incoming or outgoing.
  • The SOAP action (the function call being made)
  • Message size measured in bytes.
  • The SOAP-encoded XML message

OPC Server Trace Messages (available only if you have a license for the VTScada OPC Server and a running application is using that server)

Information collected includes:

  • Timestamp, accurate to the nearest thousandth of a second
  • Event description
  • Textual OPC item ID being read from or written to. (Often includes the tag name.)
  • Numeric ID of the OPC property
  • Write Value - the value being written to the tag
  • Result - depending on the nature of the read or write operation, may be one or more of the following:
  • the value being read or written,
  • the quality of the data transfer
  • the number of child nodes
  • the name of the tag
  • access rights
  • type
  • timestamp
  • Items such as quality, access rights, type, etc are numeric codes. See: Properties of Tag OPC Items.


Select a Data Source

Viewing versus logging a data source

There are two check boxes for each data source: View and Log. You can log data without viewing it, but cannot view without logging. Data must be collected to display.

Because each data source is collecting different types of information, only one data source may be viewed at a time. You may simultaneously log as many as you wish.

It is possible to continue logging data after closing the Trace Viewer. This enables you to collect traces over a period of time when you suspect that an intermittent problem may be occurring.

Trace files can quickly become large. Allowing the Trace Viewer to continue logging on a permanent basis is strongly discouraged.

Select a live data source:

To select a live data source for viewing in the Trace Viewer:

  1. Ensure the application you wish to examine is running.
  2. Select the Attach to Live Capture button. The Live Data Capture dialog will open and display the available data sources.

  3. Select the name of the data source you wish to view.

The data source will be highlighted to indicate that it is the one being viewed, and a check mark icon will appear in the Log column to its right, indicating that this data source is running.

  4. Select the Close button.

The Trace Viewer dialog’s list will be populated with data.

Select a log file to view

To review trace data stored in a log file:

  1. Select the Open File button [image] (or press Ctrl + O).

The Open File dialog will open to the TraceFiles directory, and will display the available data files. (If the Open File dialog is not pointed to the correct directory, browse to the TraceFiles directory within the VTScada installation directory.)

  2. Select the file you wish to view in the Trace Viewer.

Driver trace files may have somewhat cryptic names, beginning with "DriverDBTrace-". You may find that the date of the file gives the best indication to help choose which to open.

  3. Select the Open button.

The Trace Viewer dialog’s list will be populated with data.


Trace Viewer Controls

A typical Trace Viewer display with data will look similar to the following:

Note the row of control buttons across the top of the screen. Some vary according to the selected data source and are described in related topics within this chapter. Controls that are common to all data sources are described here or in the following topics:

Toggle the timestamp display

The first column of the Trace Viewer’s list can be toggled to display one of three formats:

  • Time: Displays the time to the nearest millisecond for each item in the list.
  • Date/Time: Displays the date in the format MM/DD/YYYY and the time to the nearest millisecond for each item in the list.
  • Record: Displays a record number for each item in the list. You might sometimes find that it is easier to navigate a sequentially numbered list than to look for time stamps that vary by milliseconds.

To switch between these options, select the Toggle Timestamp Display button. The column’s label and data will change to match.

Pause and run the live display

You can pause and resume the display of live data in the Trace Viewer using the Pause Live Display and Resume Live Display buttons. Pausing the live data display gives you to take the time to examine records in the list, especially in large applications where tracing moves quickly. Pausing the live display does not stop tracing and logging from continuing.

Clear the current trace

To clear a current trace, select the Clear Current Trace button. The trace you are viewing will be cleared and all logged data will be deleted from the trace file being viewed.

Clearing a trace file is a permanent and irreversible action.

Print the Trace Viewer's data

When printing from the Trace Viewer, you will have a chance to review and change the selected printer and options.

  1. Select the Print button. The Print dialog will open.
  2. Set the printing parameters as you require (i.e. select the printer, page range, number of copies, etc.).
  3. Select the Print button.

The recommended print layout for the Trace Viewer is landscape.

Highlight records [image], Next and Previous

You can highlight records of interest in the trace viewer. As a typical example, you might be interested in records from a single tag in a list of many. As you locate each record of interest, you would highlight it. You can then navigate from one highlighted record to another using the Previous Mark and Next mark buttons. (Note that the navigation buttons are disabled while highlight tool is active.)

Highlighted records will appear similarly to the example shown. Note that performing this action causes the live display to pause. Data will still be logged, but you will need to resume the live display to see it.

To highlight records:

    Select the Highlight Records button. The mouse cursor will appear as a highlight pen.

    Select the records you wish to highlight. The records will be highlighted in yellow.

    Select the Highlight Records button again to stop highlighting. The mouse cursor will revert to an arrow.

Highlights can be cleared individually by following the same procedure you used to set them. The highlight pen works as a toggle: select a record once to highlight it, then select the record a second time to remove the highlight. There is no "clear all" tool.

Keep the Trace Viewer on top

To keep the Trace Viewer dialog on top of all other windows, select the On Top Of Other Windows button.

Hide and reveal the Trace Viewer's list

When the Trace Viewer is pinned on top of other windows, it can obscure the view. You can shrink the Trace Viewer to just the toolbar, hiding and revealing the data display by using the Toggle Toolbar View button.

Trace Viewer settings

Within the settings dialog, you can modify the rate at which the display is updated from the server and the rate at which the rate is updated when running the Trace Viewer over an Internet connection. The default rate is one second for workstations (server) and five seconds for VIC connections.

The settings dialog can also be used to choose whether IP addresses should be translated to NetBIOS names (where possible).

Select the list font

If you find that the data being displayed in the Trace Viewer’s list is difficult to read, you may change the font, font style and font size used to display list items.

Displaying version information

You can find which version of the trace viewer you have installed by selecting the About button from the menu.


Filter the Trace Viewer's List

You can filter the data being displayed to show only the information of interest. Note that the filter applies only to the display: all data continues to be logged.

Which columns can be filtered and what criteria are available for filtering both depend on which live data source you are viewing. As a minimum, the ability to filter for only the highlighted records is always available. Other filters may allow multiple selections from a list of options, or free text input that will be searched for in the specified field.

In general, to filter the Trace Viewer’s display list:

  1. Select the Define Filter button. The Filter Selection dialog will open, showing the options appropriate to the type of trace you are viewing. The example shown here is for the Driver trace.

  2. Set the filtering options you require (see Filter Selection Dialog Options for detailed instructions).
  3. Select the Apply button. The list will be filtered according to the criteria you specified.
  4. Continue to adjust the filtering parameters as you require.
  5. Select the OK button to close the Filter Selection dialog.

When a filter is active (other than highlighted records only) the filtering button will have an orange highlight:

To remove filters from the Trace Viewer’s list:

Filters are removed the same way they are set. In the Filter Selection dialog, for each tab in which you have set a filter, open the tab and clear the filters from the list by selecting them and using the Delete key on your keypad.

Filtering Options

A filter can be applied to almost every column in the Trace Viewer display. Filters have one of two formats. They will either provide a list of possible values that you can filter for, or a text box where you can enter words that the column must contain.

In every case, there will be a NOT option that enables you to reverse the effect of each filter.

The Filter Selection dialog provides a number of options for filtering the Trace Viewer’s list. The elements of the Filter Selection dialog are described here to help assist you in filtering data. Tabs that contain active filters are highlighted. The following is an example of a pick filter.

For every instance of a pick filter, a list of the available values for each column will be displayed in the dialog. Select each value you want to filter for (or exclude, if using the NOT option) and then select the Apply button. You select an option by clicking in the Pick column.

The filter is cleared by removing all of the check marks from the Pick column.

Example of a Text Filter (RPC Data/Parameters)

Enter the words you wish to filter for (or exclude, if using the NOT option) in the space provided. Partial words are acceptable but wildcards are not. Spaces count as characters to be filtered for. New line characters are ignored unless the new line character is the first character in the filter. You cannot create multiple text filters. "AND" and "or" are not valid text filters unless you are looking for data/parameters that contain those words.

Note the extra line in the following image. The leading new line in this example will cause the filter to fail to find any matches. Leaving a new line character behind when clearing a filter is an easy mistake to make.


Select Columns for Display

You can choose to enable or disable the display of all columns except the timestamp. Not all columns that you may wish to view are displayed by default. Or, some of the columns that are displayed may not contain information in which you are interested.

To modify which columns are displayed:

  1. Click on the Select Displayed Columns button. The Select Displayed Columns dialog will open.
  2. Select the Show column to hide or show columns. Any column names that display a check mark in the Show column on their right will be displayed, while those column names that do not display a check mark in the Show column to their right will be hidden.
  3. Select the OK button. The Trace Viewer’s list will display only those columns that were selected for viewing.


Annotate Records

You can add notes to records. The notes are stored in the database with the log data but, unlike operator notes created in the Historical Data Viewer, these notes may be edited or deleted.

To add a note:

  1. Select the Annotate Record button.
  2. Select the record you wish to annotate in the list. The Annotate Record dialog will open.
  3. Enter the note in the field provided.

  4. Click OK. The record with which the note is associated will be highlighted in green, and a window displaying the note’s text will appear in a tool tip when the mouse pointer is rested on the record.
    If you had previously highlighted the record, the highlight will remain but will not be seen.

To edit or erase a Note:

Notes can be editing by following the same procedure you used to create them. Select the Annotate button, and then select a green record in the Trace Viewer. The Annotate Record dialog will re-open with the existing note displayed. Edit as you wish, then select OK. Empty notes are deleted rather than saved as empty text.


Driver Tracing

You must choose which drivers to trace by using the Select Drivers for Tracing dialog. This dialog displays a tree view of all the drivers used in the application. Select all, or only those that are of interest to you.

To open the dialog, click on the Select Drivers for Tracing Button.

This button is visible only after you have selected Driver Trace from the Live Data Capture Selection dialog.

The dialog will look similar to the following. Drivers are grouped by device type. Those that you have selected for tracing are marked with a check.

A driver trace will include the following information:

  • Time stamp
  • Direction - received or sent
  • Service Name - typically the same as the driver name.
  • Driver Name - matches the tag name
  • Driver Area - from the tag
  • Driver Description - also from the tag
  • Port Name - the port tag to which the driver is linked.
  • Data - packets sent and received, shown in hexadecimal notation


Historian Diagnostics

The Historian will log diagnostic messages upon startup. Following startup , diagnostic messages for the Trace Viewer will be logged only when errors occur. If neither of these conditions occur while you are capturing a trace, the display will be empty.

An empty list is to be taken as a sign that all is working properly, assuming that you have selected Historians for tracing.

You must select which historian's data to capture. When you first open the page, none will be selected by default. Click on the Select Historians Button.

These buttons are visible only after you have selected Historian Trace from the Live Data Capture Selection dialog.

The Select Historians dialog will present a list of all Historians active in running applications. Choose one or more by clicking on the Selected check box.

An Historian trace will include the following information:

  • Timestamp
  • The name of the Historian tag
  • The type of trace (debug or connection)
  • The name of the tag whose data was being logged by the Historian
  • An error code (of use only to Trihedral staff).
  • The text of the error.
  • A message describing the logged event.

The Trace Options dialog:

This dialog also contains a Write Poll Interval field, measured in milliseconds. You may adjust this value to change the frequency at which trace information is gathered.


Remote Procedure Call (RPC) Tracing

This tool adds a significant burden to RPC traffic while it is running.
Do not leave RPC diagnostics running.
Use Trace VTScada Actions for TraceRPC only to check for connection maintenance issues.

When RPC Diagnostics have been selected as the live capture data source, the toolbar will change to show three new buttons

From left to right, these are:

  • Settings button.
    Opens the settings dialog, where you can set parameters that will affect the behavior of RPC traces.
  • Services button
    Opens the Services dialog, which displays the current services and their state including which workstation is currently the server for that service.
  • Sockets button
    Opens the Inter-machine Sockets dialog, which displays the MachineNodes and their subordinate SocketNodes.

Interpreting RPC Diagnostics Data

The Trace Viewer performs the following translations and filters for RPC Diagnostics:

  • IPs are translated to names where possible
  • GUIDs are translated to application names
  • Filtering can be done by IP/name, AppGUID, Service, trace point in RPC, or data content.


RPC Diagnostics Settings Dialog

The RPC Diagnostics Settings dialog is launched when the RPC Diagnostics -Settings button is clicked in the Trace Viewer’s tool bar. Use the RPC Diagnostics Settings dialog to set the following parameters:

Detailed Trace:

Enables the display of routing between the local workstation's RPC serialization FIFO and the transmission FIFOs, providing more detailed information on the internal operation of the RPC Manager. (Not required by most users.)

Max String Length:

Specifies the maximum length for strings to be traced. The parameters for an RPC call are traced in the Data/Parameters column of the Trace Viewer’s list. Parameters that are text or streams may be of any length, and so must be truncated for display purposes. The default for Max String Length is 64, which should be suitable for the majority of users.


Inter-machine Sockets Dialog

The Inter-machine Sockets dialog is launched when the RPC Closed Remote Procedure Call Diagnostics - Sockets button in the Trace Viewer’s tool bar is clicked. This dialog presents information on sockets and machine nodes.

This tool adds a significant burden to RPC traffic while it is running.
Do not leave RPC diagnostics running.
Use Trace VTScada Actions for TraceRPC only to check for connection maintenance issues.

Queue Length

The queue length on the "Local" node is the length of the local machine's serialization queue. All RPCs processed by the local machine, whether executed or just routed to another machine, pass through this FIFO Closed First In, First Out queue. A high number means that there are more RPCs being produced than the local machine can process in a given time.

The queue length on each of the other nodes (representing remote machines) is the length of the queue waiting to be transmitted to that machine. A high number means that more RPCs are being produced than can be transmitted to that machine in a given time. This might be because the remote machine is too busy to accept them or the network link may be slow.

Excessive production of RPCs generally results from any of the following configuration issues:

  • An I/O scan rate that is set too high.
  • Failing to set reasonable deadbands on analog data.
  • Frequent resynchronization by machines.
    (This is usually a side effect of a machine being too busy to maintain a reasonably reliable connection or it may be due to networking issues.)

Socket Information

Each line displayed in the Inter-machine Sockets dialog displays the following information:

  • Name and IP address of each machine
  • State of each machine (either remote or local)
  • Dynamic display of the internal queue length
  • Connection status (either green for a working connection, or red for a connection failure)

You may expand any line to view the individual sockets available for each remote machine connection. Use the Reset button, located to the far right of each socket statistics line to reset the statistics.

Inter-machine Sockets Data for Remote Machines

Discards | The total number of messages thrown off the queue.
Floods | The total number of full queue exceptions
Execs | The total number of RPCs executed by this machine node
RemVersion | The version of VTScada running on this machine
Session | The status of the RPC session (either Open or Closed)
Lost | The total number of times communications were irrecoverably lost
SocketsOK | The number of open sockets
Resends | The total number of message floods

Inter-machine Sockets Data for the Local Machine

Discards | The total number of messages thrown off the queue.
Floods | The total number of full queue exceptions
Execs | The total number of RPCs executed by this machine node
CtxErrs | Total number of RPC that failed due to a bad execution context being specified
ModErrs | Total number of RPC that failed due to a bad target module name being specified
TxRPC | Total number of RPCs transmitted
RxRPC | Total number of RPCs received
Pings | Total number of pings received
Acks | Total number of acknowledgments received
Disc | Total number of times this socket has been lost
Lost | Total number of times communications have irrevocably been lost
Coll | Total number of collisions encountered
Sync | The number of bad sync string errors received
Hdr | The number of bad header errors received
Len | The number of bad length errors received
Pkt | The number of incomplete packet errors received


Services Dialog

This dialog provides the same information that is available in the Services Page, repeated here for convenience.

Service Status including the optional legend

The Service Architecture list provides the following columns, describing the configuration of your server lists:

Service | Server List | Primary Server | Backup Server 1 | [ Backup Server 2 ... if present ]

Service Tools

The tools across the top of the page work when either list is shown.

Switch All Away

Any service that is currently using this workstation as its server will be directed to use the next available backup instead.

Switch All to Next Server

Forces all services to switch to the next available server, according to the server list.

Switch All to the Primary Server

Forces all services to switch to the configured Primary Server, if available.

Switch to Next Server

Forces the selected service to switch to the next available server, according to the server list. It is not possible to select multiple services.

Switch to Primary Server

Forces the selected service to switch to the configured Primary Server, if available.

Advanced Filtering

The Advanced Filtering Dialog can be used to restrict which services are shown in either list.

  • Name - Filter by the name of the service (not a server).
  • Server List - "Default" will be the only entry unless you have created your own server lists.
  • Server in Server List - Select from the list of servers used by your server lists.
  • Current Server - Select a server. The list will show only those services currently using that workstation as the server.
  • Status ("with" or "not") - Choices include "Disconnecting", "Syncing", "Client", or "Current Server".
  • Type - Choices include:
    "VTScada Service" Currently, only the configuration service.
    "Application Service" Fundamental Services such as AlarmNotification and TimeSyncManager.
    "Tag Service" Services related to tags, including all historians and drivers.
    "Driver Service" Services related only to drivers.
  • Tag Type- Select between historians, drivers, or any custom type that might have a service

Service Details Dialog

Enabled only when a service is selected in a list. Click to open a dialog showing status and configuration information about the selected service.

Properties

Enabled only when a tag-related service such as SystemHistorian or a driver is selected. Opens the properties dialog for the matching tag.

Text Size

Adjusts the relative text size used in the list between small, medium, or large.

Legend

When selected a legend is superimposed on the current list. This is a guide to the meaning of the colors and symbol used for each server in the list:

Daytime / Nighttime

Toggles the background between light and dark


Trace Viewer Features Specific to SOAP Message Tracing

Viewing: Troubleshoot > Trace Viewer Application > Trace Viewer Features Specific to SOAP Message Tracing

Features for SOAP Message Tracing

SOAP message logging can generate large log files very quickly. For this reason, an option is provided to allow you to filter the messages that are being logged.

The Enable Conditional Logging dialog provides two options:

  • You may opt to log only errors
  • You may enter a comma separated list of IP addresses. Only messages coming from the specified addresses will be included in the log.

This dialog is displayed by selecting the Enable Conditional Logging button, [image] from the toolbar.


Trace VTScada Actions Application

Use the Trace VTScada Actions application to monitor selected VTScada services (such as the RPC Manager and Modem Manager), and their actions (the Navigator or SQL calls), by saving pertinent data (such as the date and time they executed) to disk.

The Trace VTScada Actions application should not be confused with the Trace Viewer Application, which can be used to view trace information for your applications in real-time.
This application is included with every copy of VTScada, but you may need to add it to the VAM.

Service names that contain a child-tag delimiter will be shown with a forward-slash.

Data is written to a text file named, "VTSTrace.txt". Additionally, VTScada traces all actions to disk, storing the data in a separate text file named, "VTSTraceAll.txt". Both the VTSTraceAll.txt and VTSTrace.txt files are automatically written to the VTScada installation directory when you exit your application.

An example of the Trace VTScada Actions dialog:

The Trace VTScada Actions utility consists of the following elements:

Start / Stop

Start and stop the tracing of the selected actions to a special text file named, "VTSTrace.txt" (located within your VTScada installation directory (e.g. C:\VTScada\VTSTrace.txt). When the button is toggled on (depressed and labeled "Stop"), VTScada is tracing the specified actions to file. When the button is toggled off (labeled "Start"), VTScada has stopped tracing the specified actions to file. As mentioned in the note above, by default, VTScada now traces all actions to a "VTSTraceAll.txt" file, located in your VTScada installation directory.

Erase

Deletes the tracing file (VTSTrace.txt) from disk when actions have been traced to file using the Start button. The Erase button is disabled while the Start button is selected.

Important / All

Selects the logging level. In most cases, the default, "Important", will suffice. Set to All only if the default level does not capture the necessary information, noting that the "All" level may capture an excessive number of irrelevant messages and degrade performance.

Records in RAM

Use to specify the number of trace actions you wish to be saved to RAM prior to being written to the VTSTrace.txt file. The default for Records in RAM is 256.

Parameter Byte Limit

Specify the maximum size of parameters. The default for Parameter Byte Limit is 256.

Trace Application Manager

Select whether all activities pertaining to the VAM are to be traced.

Trace Dialogs

Select whether all activities pertaining to dialogs are to be traced. This setting is useful if you wish to trace 4BtnDialog calls.

Trace Display Manager

Select whether to record all activities related to the Display Manager.

Trace Menu Editor

Select whether to trace all activities related to the Menu Editor.

Trace Modem Manager

Select whether to trace all activates related to the Modem Manager.

Trace Navigator

Select whether to trace all activities related to the shortcut menus in your application.

Trace Page Manager

Select whether to trace all activities related to the Page Manager.

Trace Expression Manager

Select whether to trace all calculations related to the Expression Manager.

Trace Remote Configuration

Select whether to trace all activities related to remote configuration.

Trace RPC Manager

Select whether to trace all activities related to the RPC manager and remote procedure calls.

Trace SQL Calls

Select whether to trace all SQL calls made in your application.

Trace Startup Synchronization

Select whether to trace all activities related to startup synchronization.

Trace Tag Browser

Select whether to trace all activities related to the Tag Browser.

Trace Tag Configuration

Select whether to trace all activities related to tag configuration.

Trace Tools

Obsolete as of VTScada release 11.

Each of the check boxes described above corresponds to a configuration variable in the system-wide Setup.ini file (stored in the VTScada installation directory). Information on these variables can be found in "Configuring Setup.ini".

Trace List

The list displayed on the Trace VTScada Actions dialog displays the actions that have been traced according to the check boxes you've selected. For each action traced in the list, the following data is displayed:

Date: The date for each action being traced is displayed in the first column of the trace list. The date is displayed using the format, "MM/DD/YY" (e.g. 10/24/05).

Time: The time at which each action was traced is displayed in the second column of the trace list. The time is displayed in milliseconds, using the format, "HH:MM:SS.MS" (e.g. 16:07:23.129).

Trace Action: The category of the action being traced is listed in the third column, according to the check boxes you have selected (e.g. TraceVAM or Trace RPC).

Data: The details about each action being traced are identified in the fourth column.

In the event that some items in the list are difficult to read, you can expand the Trace VTScada Actions dialog either using the Windows maximize button in its title bar, or by dragging its borders, or you can rest your mouse pointer over each entry in the list to view its details.


Reference

Tag Reference

Widget Reference

Property Reference

Function Reference

Colors, Fonts and Graphics
VTScada Color Palette
Constants for System Colors
Color Theme Definition
Fill Patterns
Font Character Sets
GUI Object Return Codes
Line Types

Time and Date
Date Formatting Codes
Date Formatting Strings
Time Formatting Codes
Time Formatting Strings
VTScada and Time Synchronization

Value Types and Language Support
SQL ODBC Types
Database Type Codes used in the ODBC Manager
VTScada Value Types
Value and Type Conversions
Using a Non-English Character Set

Help Files, Function Support, Other...
Defined Constants for Buffers
Custom Help Files
ParameterEdit Snap-ins
Known Path Aliases for File-Related Functions
[SlippyMapRemoteTileSourceN] Section
Uninstall VTScada


Tag Reference

The flexible nature of VTScada is due to the custom building blocks upon which it is based. These building blocks are called "tags".

Points? A tag is a point and a point is a tag. VTScada uses the word "tag" more often (that's what the T in VTScada is for, after all) but "point" was used first, and you'll still see it from time to time.

A tag is a software component that can communicate with objects in the physical world. For flexibility, each tag type is a specialized component that can be combined with other tag types to build diverse systems. For example:

  • Port tags handle communication between the VTScada server and the outside world, whether through a serial port or a TCP/IP port.
  • A specialized driver tag is available for nearly any brand of PLC hardware. Driver tags rely on port tags to communicate with the hardware.
  • Input and output tag types, both analog and digital, monitor and communicate with individual addresses on the remote PLC. I/O tags rely on driver tags to ensure that communications are properly formatted for the remote hardware.
  • Alarm tags and Logger tags can be linked to any I/O tag to monitor and record values.
  • Memory tags. A memory tag is an I/O and Calculations Tag, configured without an address. The data type can be Analog, Discrete, Digital, or String. 2-bit Digital, and all Calculation options of the I/O tag do not count as Memory Tags.

The term, "communications chain" describes the linkage of VTScada with remote hardware through the I/O tag, to the driver tag, to the port tag. By choosing appropriate tags for each link in the chain, you can build VTScada applications for nearly any situation.

It is typical to begin each application you create by configuring a port tag to accept the data that is flowing through your PC, and a device driver tag to provide an interface to physical I/O devices such as programmable logic controllers (PLC), remote terminal units (RTU), I/O boards, or to Windows system features such as Dynamic Data Exchange (DDE). After you have these essential tags in place, you can create analog, digital and other tag other types to make your application communicate with the outside world.

Standard versus Custom Types.

All of the various types of tags that come with VTScada are described in this chapter. These are known as the standard types.

VTScada also gives you the ability to define your own types of tag. This can be done by creating groups that include a port, a driver, I/O, alarm and other tags that fully describe a type of equipment, such as a pumping station, motor, well, etc. You are also able to use the VTScada programming language to build completely new types of tag, designed specifically for your needs. Custom-programmed tags do count towards your license limit.

Tips:

  • During a development session, each new tag of the same type will start out identical to the last of that type, save only the name. This can save time when making several similar tags since you won't have to set the same values over and over. But, if the majority of the fields in each new tag differ from the last, this feature may not be so useful. You can disable it by setting the application property, RememberNewTagParameters to 0.
  • Even with RememberNewTagParameters set, it's often easier to create new tags by copying and pasting existing tags, then changing a few properties to suit the new one.
  • You can export the tag database for editing in a spreadsheet and then import the modified database back into VTScada. This can save time when creating a lot of tags. It's especially helpful when you need to change one property in a long list of tags since the spreadsheet will allow you to do a search and replace on that property.
  • Advanced developers can obtain a list of tag areas in an application via a public variable. Refer to VTScada Constants and Public Variables


Tag Names in Code

There are several instances where you may need to refer to a tag type by its name in code. For example if using the ODBC interface to query tag parameter data (Select * from Parms_AnalogStatus).

Custom types that you create will use the name that you assigned in the original Context tag.

Tag | Name in code
Allen Bradley DF1 Compatible PLC/RTU (Replaced by the Rockwell driver) | ABDriver
Alarm Database | AlarmDatabase
Alarm | AlarmPoint
ABB Totalflow Driver | ABBTotalflowDriver
Alarm Point | AlarmPoint
Alarm Priority | AlarmPriority
Alarm Status | AlarmStatus
Analog Control | AnalogControl
Analog Input | AnalogInput
Analog Output | AnalogOutput
Analog Statistics | AnalogStatistics
Analog Status | AnalogStatus
BACnet Driver | BACnetDriver
Bristol Driver | BristolDriver
Bristol Network | BristolNetwork
Calculation | Calculation
Camera | Camera
CAT 5 MX Driver | CATM5XDriver
CCM Manager | CCMManager
Rockwell Driver | CIPENIPDriver
Context | ContextTag
Comm Link Sequencer | CommLinkSequencer
Counter | CounterTag
CSV Data Driver | CSVDataDriver
Grundfos Dedicated Controls | CU36XController
Grundfos Dedicated Controls Custom Data Log | CU36XControllerCustomDataLog
Grundfos Dedicated Controls Event Log | CU36XControllerEventLog
Grundfos Dedicated Controls\\Pump | CU36XControllerPump
Campbell Scientific Array Driver | CampbellRTU
Data Flow System RTU | DataFlow
CalAmp Diagnostic Driver | DataradioDriver
DDE Client | DDEDriver
Deadband Control | DeadbandControl
Delta Driver | DeltaDriver
Digital Control | DigitalControl
Digital Input | DigitalInput
Digital Output | DigitalOutput
Digital Statistics | DigitalStatistics
DNP3 Compatible RTU | DNP3Driver
Digital Status | DigitalStatus
Driver Multiplexer | DriverMUX
Enron MODBUS Driver | EnronDriver
Omron FINS Driver | FINSDriver
Font Style | FontValue
Function | Function
GE Series 90 Driver | GESeries90Driver
Grundfos Control MPC | GrundfosBooster
Grundfos Control MPC\\Pump | GrundfosBoosterPump
Historian | HistorianTag
History Statistics | HistoryStats
IEC 60870-5 Driver | IEC60870Driver
I/O and Calculations | IO
IP Network Listener | IPNetworkListener
JSON/XML Driver | JSONXMLDriver
Koyo DirectNET | KoyoDriver
Logger | LogPoint
MDS Diagnostic Driver | MDSDriver
Menu Item | MenuItemTag
Honeywell Mercury Driver | MercuryDriver
Mitsubishi Driver | MitsubishiDriver
Modem | Modem
Modbus Compatible Device | ModiconDriver
Motorola IP Gateway | MotorolaGateway
Motorola ACE RTU | MotorolaRTUDriver
MPE Duplexer Station | MPEDuplexer
MPE Duplexer Station\\Pump | MPEDuplexerPump
MPE SC Station | MPESC
MPE SC Station\\Pump | MPESCPump
MQTT Client Driver | MQTTClientDriver
MultiSmart Station | MultiSmart
MultiSmart Station\\Well\\Profile | MultiSmartProfile
MultiSmart Station\\Pump | MultiSmartPump
Multi-Write | MultiWrite
Network Status | NetworkStatus
NMEA 0183 Driver | NMEADriver
Notebook | Notebook
Omron Host Link PLC | OmronDriver
OPC Classic Client | OPCClientDriver
OPC UA Client Driver | OPCUAClientDriver
OPC Classic Client Server | OPCServerSetup
Opto Driver | OptoDriver
PLC Alarm | PLCAlarm
Campbell Scientific PakBus Driver | PakBusDriver
Polling Driver | PollDriver
Pulse Input | PulseInput
Pump Status | Pump
Rate of Change | RateOfChangeTag
Realm Display Setup | RealmDisplaySetup
Recipe Book | RecipeBook
Recipe Parameter | RecipeParameter
Recipe Proportions | RecipeProportions
Recipe Trigger | RecipeTrigger
Report | Report
Fisher ROC Driver | ROCDriver
Rockwell Driver | CIPENIPDriver
Roster | Roster
ScanCom Driver | ScanComDriver
Script | Script
Selector Switch | SelectorSwitch
Serial Port | SerialPort
Siemens S7 PLC | SiemensS7Driver
SMS Appliance | SMSAppliance
SNMP Managed Device | SNMPDriver
SQL Data Query Driver | SQLDataQueryDriver
SQL Logger | SQLLogger
SQL Logger Group | SQLLoggerGroup
SQL View | SQLView
String I/O | StringIO
Style Settings | StyleSettings
Subordinate Application | SubordinateApplication
TCP/IP Port | TCPIPPort
Tesco Data Express Plus Driver | TescoDriver
TI505 Device | TI505Driver
Totalizer | TotalizerTag
Toyopuc Driver | ToyopucDriver
Transaction Logger | TransactionTag
Trigger | TriggerTag
UDP/IP Port | UDPIPPort
Veeder Root Driver | VeederRootDriver
WorkStation Driver | WorkStationStatusDriver


Table of Type Characteristics

Viewing: Reference > Tag Reference > Table of Type Characteristics

Type Characteristics

The displayed name of a tag type does not always match the name used in VTScada code.

Context types are often used in expressions, particularly for Ancestor Relative tag paths.

Any tag that can be trended will have a log-enabled variable. This is almost always "Value" but drivers have seven.

Name | Name in code & exported tables | Context type | Group memberships | Log-enabled variables
Port Tags
SerialPort | SerialPort | *Port | Numeric, Ports, Trenders | Value (integer)
TCP/IP Port | TCPIPPort | *Port | Numeric, Ports, Trenders | Value (integer)
UDP/IP Port | UDPIPPort | *Port | Numeric, Ports, Trenders | Value (integer)
Driver Tags
ABB Totalflow Driver | ABBTotalflowDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
BACnet Driver | BACnetDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Bristol BSAP/IBP Driver | BristolDriver | *Driver *BristolDriver | Drivers, Numeric, Trenders, Loggers | *see note 1
Bristol BSAP/IBP Network | BristolNetwork | *Driver | Drivers, Numeric |
CalAmp Diagnostic Driver | DataRadioDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Campbell Scientific Array Driver | CampbellRTU | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Campbell Scientific PakBus Driver | PakBusDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
CAT 5 MX Driver | CATM5XDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
CSV Data Driver | CSVDataDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Data Flow System RTU | DataFlow | *Driver | Numeric, Container, Digitals, Drivers, LiftstationDrivers, Trenders, Loggers | *see note 1
DDE Client | DDEDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Delta Driver | DeltaDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
DNP3 Compatible Driver | DNP3Driver | *Driver | Drivers, Numeric, Trenders, LiftstationDrivers, Loggers | *see note 1
Driver Multiplexer | DriverMUX | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Driver Redirect | DriverRedirect | *Driver (points to the referenced driver) *DriverRedirect | Container | Value (Invalid)
Enron MODBUS Driver | EnronDriver | *Driver | Drivers, Numeric, Trenders, LiftstationDrivers, Loggers | *see note 1
Fisher ROC Driver | ROCDriver | *Driver | Drivers, Container, LiftstationDrivers, Numeric, Trenders, Loggers | *see note 1
GE Series 90 Driver | GESeries90Driver | *Driver | Drivers, Numeric, Trenders, LiftstationDrivers, Loggers | *see note 1
Honeywell Mercury Driver | MercuryDriver | *Driver | Drivers, Numeric, Trenders, LiftstationDrivers, Loggers | *see note 1
IEC 60870-5 Driver | IEC60870Driver | *Driver | Drivers, Numeric, Trenders, LiftstationDrivers, Loggers | *see note 1
JSON/XML Driver | JSONXMLDriver | *Driver | Drivers, Numeric, Trenders, LiftstationDrivers, Loggers | *see note 1
Koyo DirectNET | KoyoDriver | *Driver | Drivers, Numeric, Trenders, LiftstationDrivers, Loggers | *see note 1
MDS Diagnostic Driver | MDSDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Mitsubishi Driver | MitsubishiDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Modbus Compatible Device | ModiconDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Motorola ACE RTU | MotorolaRTUDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
MQTT Client | MCTTClientDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
NMEA 0183 Driver | NMEADriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Omron Host Link Driver | OmronDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Omron FINS Driver | FinsDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
OPCC Driver | OCPPDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
OPCC Users | OCPPUsers | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
OPC Classic Client Driver | OPCClientDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Opto22 Mux Driver | OptoDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Polling Driver | PollDriver | *Driver | Drivers, Container, LiftstationDrivers, Numeric, Trenders, Loggers | *see note 1
Rockwell Driver | CIPENIPDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
ScanCom Driver | ScanComDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Siemens S7 Driver | SiemensS7Driver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
SNMP Driver | SNMPDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
SQL Data Query Driver | SQLDataQueryDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Tesco Data Express Plus Driver | TescoDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
TI505 Device | TI505Driver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Toyopuc Driver | ToyopucDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Transaction Logger | TransactionLog | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Veeder Root Driver | VeederRootDriver | *Driver | Drivers, Numeric, Trenders, Loggers | *see note 1
Workstation Driver | WorkstationStatusDriver | *Driver | Drivers, Numeric, Trenders | *see note 1
Input and Input/Output Tags
I/O and Calculations | IO | *Numeric | Analogs, Numeric, Trenders | Value (varies by type)
Analog Input | AnalogInput | *Numeric | Analogs, Numeric, Trenders | Value (floating point)
Analog Status | AnalogStatus | *Numeric | Analogs, Numeric, Trenders | Value (floating point)
Digital Input | DigitalInput | *Numeric | Digitals, Numeric, Trenders | Value (byte)
Digital Status | DigitalStatus | *Numeric | Digitals, Numeric, Trenders | Value (byte)
Data Flow Pulse Input | PulseInput | *Numeric | Numeric, Analog | Value (integer)
Pump Status | Pump | *Numeric | Digitals, Loggers, Numeric, Trenders | Value (byte)
String | StringIO | none | Trenders | Value (text)
Output Tags
I/O and Calculations | IO | *Numeric | Analogs, Numeric, Trenders | Value (varies by type), Value!
Analog Control | AnalogControl | *Numeric | Analogs, Numeric, Trenders, Outputs | Value (floating point)
Analog Output | AnalogOutput | *Numeric | Analogs, Numeric, Trenders, Outputs | Value (floating point)
Deadband Control | DeadbandControl | *Numeric | Numeric, Trenders | Value (floating point)
Digital Control | DigitalControl | *Numeric | Digitals, Numeric, Trenders, Outputs | Value (byte)
Digital Output | DigitalOutput | *Numeric | Digitals, Numeric, Trenders, Outputs | Value (byte)
MultiWrite | MultiWrite | *Numeric | Outputs | Value (floating point)
Selector Switch | SelectorSwitch | *Numeric | Numeric, Trenders | Value (short)
Trigger | TriggerTag | *Trigger | Digitals, Numeric, Trenders | Value (byte)
Alarm Tags
Alarm | AlarmPoint | *Alarm | Digitals, Numeric | Value (logged by VTS)
Alarm Database | AlarmDatabase | *AlarmDatabase | Container |
Alarm Priority | AlarmPriority | *Alarm Priority | Digitals | Value (do not log)
Alarm Status | AlarmStatus | *Alarm Status | Numeric, Trenders | Value (integer)
Modem | Modem | *Modem | Numeric | Value (integer)
PLC Alarm | PLCAlarm | *Alarm | Digitals, Numeric |
Roster | Roster | *Roster | Digitals, Numeric | Value (Boolean)
SMS Appliance | SMSAppliance | (none) | Numeric | Value (integer)
Logging and Reporting Tags
Historian | HistorianTag | *Historian | Numeric | (none)
Logger | LogPoint | *Logger | Numeric | (none)
Notebook | Notebook | *Notebook | Trenders, Loggers | Value (text)
Report | Report | *Report | (none) | Value (0 or 1)
SQL Logger Group | SQLLoggerGroup | *SQL Logger Group | (none) | (none)
SQL Logger | SQLLogger | *SQL Logger | Numeric | Value (matches tag being logged)
SQL View | SQLView | *SQLView | (none) | (none)
Calculation and Inquiry Tags
Analog Statistics | AnalogStatistics | *AnalogStatistics | Container | Do not log. Selected child tags may be logged.
Calculation | Calculation | *Numeric | Loggers, Numeric, Trenders | Value (floating point)
Counter | CounterTag | *Numeric | Analogs, Numeric, Trenders | Value (integer)
Digital Statistics | DigitalStatistics | (none) | Container | Do not log. Selected child tags may be logged.
Function | Function | *Numeric | Numeric, Trenders | Value (floating point)
History Statistics | HistoryStats | *Numeric | Numeric, Trenders | Value (floating point)
Network Status | NetworkStatus | *Numeric | Digitals, Loggers, Numeric, Trenders | Value (byte)
Rate of Change | RateOfChangeTag | *Numeric | Analog, Numeric, Trenders | Value (floating point)
Totalizer | TotalizerTag | *Numeric | Analog, Loggers, Numeric, Trenders | Value (floating point)
Script | Script | *Script | Numeric, Trenders | Value (floating point)
Station Tags
 |  | *Driver refers to the active driver in a station. |  |
Grundfos Control MPC | GrundfosBooster | *Driver *Station | Container, Stations |
Grundfos Dedicated Controls | GrundfosBoosterPump | *Driver *Station | Container, Stations |
Multismart Station | Multismart | *Driver *Station | Container, Stations | Value (matches the driver's value)
MPE SC Station | MPESC | *Driver *Station | Container, Stations | Value (matches the driver's value)
MPE Duplexer Station | MPEDuplexer | *Driver *Station | Container, Stations | Value (matches the driver's value)
Configuration Tags
Camera | CameraTag | *Camera | (none) | Value (Integer)
Comm Link Sequencer | CommLinkSequencer | *CommSequencer | Numeric, Trenders | Value (Integer)
Context | ContextTag | Defined by configuration* | Container | (none)
Font Style | FontValue | *Font Style | (none) | (none)
IP Network Listener | IPNetworkListener | *Port | Numeric | Value (byte)
OPC Classic Server | OPCServerSetup | *Driver | Numeric, Trenders, Loggers |
Realm Display Setup | RealmDisplaySetup | *Realm Display Setup | (none) | (none)
Recipe Book | Recipe Book | *Driver (points to the referenced driver) *RecipeBook | (none) | Value (integer)
Recipe Parameter | RecipeParameter | none | (none) | Value (varies)
Style Settings | StyleSettings | *Style Settings | (none) | (none)
Subordinate Application | SubordinateApplication | *SubordinateApplication | Container, Numeric |

*Notes:

Context tags gain a * context type when turned into a user-defined type, according to their Type field.

1: See: Communication Driver Log-Enabled Variables


Port Tags

Driver tags need to know where to find the hardware they will communicate with. Rather than build this information into the driver tag, VTScada provides Port tags, allowing you to define the communication details once, then use that configuration for several drivers. If the configuration changes later, then you need only update one tag.

Port tags tell the VTScada drivers about the nature of the physical connection (serial port, TCP/IP over Ethernet, or UDP) and the required configuration details such as IP address, port number, transmission speed, whether a modem is attached, etc.

Monitor drivers, not ports. A port tag has a value only on the server that is communicating with hardware and will be blank on all other servers. The value of a port tag is not synchronized across all workstations. (Unlike I/O and driver tags.) If the alarm server and I/O servers are different machines, an alarm on a port tag will not activate. Do not attach an alarm to any port tag.
A port tag widget drawn on a page represents only state of the port on the local machine.

Ports (TCP & UDP), Drivers, and Timing

A port will detect when a driver is using it. If the port is not used for a period of time defined by it’s “Disconnect Delay (sec)” parameter, it will close the connection to the PLC abruptly.

Drivers will always poll for PLC changes upon startup (including when the application starts and when the driver tag is re-started). This check will not initiate a connection if none is active.

The port's Disconnect Delay setting should always be greater than the driver's timeout setting (where the label and type of that timeout will vary by driver). The values that you choose will depend on the reliability of your network. In general, for longer polling cycles, of 5 seconds or more, it is best to close the connection between cycles by setting the driver's timeout and not by setting the port's Disconnect Delay.

Related information:

Motorola IP Gateway

Serial Port Tags

TCP/IP Port Tags

UDP/IP Port Tags

Ethernet to Serial Converters - Troubleshooting.


Motorola IP Gateway Tags

Viewing: Reference > Tag Reference > Port Tags > Motorola IP Gateway Tags

Motorola IP Gateway

Not counted towards your tag license limit.

While not actually a port tag, these are required by the Motorola ACE driver tags in order to create an interface to a Motorola MDLC network.

Reference Notes:

In addition to adding an IP Gateway tag, you must also install a Motorola configuration file, named MDLC_TYP.CFG. This lists the possible RTU table configurations. If there are errors in this file, you can expect "type mismatch" error messages.

MDLC_TYP.CFG is a Motorola product. It is not supplied by Trihedral.

The MDLC_TYP.CFG file must be placed in your application folder, and imported to the application using VTScada configuration management. (see: Import File Changes or Manage Files with the File Manifest.)

The Motorola IP Gateway API is made available via a Component Object Module (COM) object, ACEIPGatewayAutomation.exe. This is installed and registered on your system when VTScada is installed.

(C:\Program Files\Trihedral\VTScada Version Folder\ACEIPGatewayAutomation.exe)

The gateway will support 20 concurrent polling requests.

Related information:

Motorola ACE Driver

Best Practices for Tags

Motorola IP Gateway: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Motorola IP Gateway: Settings tab

Use the settings tab to configure the primary gateway and to control the time synchronization feature.

Primary Gateway IP

Provide the gateway's primary address in this field. This must be in IPv4 format, rather than a named address.

Secondary Gateway IP

If using redundant gateways, provide the secondary gateway's address in this field. This must be in IPv4 format, rather than a named address.

System Time Sync

The enable box should be selected if you intend to use the system time synchronization broadcast, which sends the current local time to all devices on the MDLC network.

Use the Broadcast Interval control to select the appropriate timing for your system.

Motorola IP Gateway Tag Widgets

There are no widgets for the Motorola IP Gateway tag.


Motorola IP Gateway Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x00 | No Error
512 | 0x200 | General COM Error
513 | 0x201 | Invalid COM Status
514 | 0x202 | Operation Timeout
515 | 0x203 | Channel Reset
516 | 0x204 | Invalid SiteInfo
517 | 0x205 | RTU not responding
518 | 0x206 | Unexpected error
519 | 0x207 | MDLC_TYP.CFG not found
49 | 0x31 | General Error
50 | 0x32 | Busy Error
52 | 0x34 | Item is Empty
53 | 0x35 | Gateway is Busy
54 | 0x36 | Size Problem
58 | 0x3A | Data Problem
59 | 0x3B | Failure Problem
60 | 0x3C | Timeout
63 | 0x3F | Client Does Not Exist
64 | 0x40 | Illegal Type
129 | 0x81 | Communication Error
130 | 0x82 | Application Error
131 | 0x83 | Secondary Mode Error
132 | 0x84 | Duplicate Entries
133 | 0x85 | Illegal Name
134 | 0x86 | Memory Allocation Fail
135 | 0x87 | Error Accessing CFG Files
136 | 0x88 | Error in CFG Files
137 | 0x89 | SiteID Not Found
138 | 0x8A | System Error
139 | 0x8B | Row Error
140 | 0x8C | Column Error
141 | 0x8D | Table Error
142 | 0x8E | Data element coordinate unknown
146 | 0x92 | Bad Message Data
147 | 0x93 | Failure Response
149 | 0x95 | Illegal IP Address
151 | 0x97 | Channel Socket Error
152 | 0x98 | Field Type Mismatch
154 | 0x9A | Hash Table Full
155 | 0x9B | Parameter Error
156 | 0x9C | Workstation Name Too Long
157 | 0x9D | Requested Entry Not Found


Serial Port Tags

Not counted towards your tag license limit.

The Serial Port type opens an RS-232 connector port for use by a driver. If you intend to use a modem, either for communication to the remote telemetry unit, or for use by the Alarm Notification System, then you will need a Serial Port tag. (Ethernet to Serial Converters

with TCP/IP ports are a viable option when RS-232 cards are not available.)

Reference Notes:

Monitor drivers, not ports. A port tag has a value only on the server that is communicating with hardware and will be blank on all other servers. The value of a port tag is not synchronized across all workstations. (Unlike I/O and driver tags.) If the alarm server and I/O servers are different machines, an alarm on a port tag will not activate. Do not attach an alarm to any port tag.
A port tag widget drawn on a page represents only state of the port on the local machine.

The transmit and receive buffer lengths are fixed at 16384 bytes.

The Data Transmit Ready (DTR) parameter of the serial port is fixed at 1.

Serial port tags may use the same port for different purposes on two different PCs. This is achieved by the re-use of serial ports on backup machines in a multi-server application Closed An application that simultaneously runs on two or more computers. Usually configured with at least one primary server and one backup server..

The application property, SerialShareSemaphore has been marked as deprecated. In the unusual event that you have multiple devices attempting to use the same channel at the same time across multiple ports, you might consider adding Comm Link Sequencer Tags to serialize requests.

A valid Serial Port Tag will have one of two values:

  • 0 (zero) indicates a good connection.
  • 2 indicates that the port is not available.

Related information:

Comm Link Sequencer Tags - Serialize requests for the same communication channel across ports.

Best Practices for Tags

Modem Tags - Details about configuring Modem tags.

SerPortDisconnectDelay - Port Sharing: Multiple drivers can share a Serial Port tag when it is in ‘serial’ mode.

Serial Port properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Serial Port properties Settings tab

Use the settings tab to configure the tag for the communication parameters required by your hardware. The default settings for data bits, speed and parity are those which are most commonly in use.

When Use Modem is not selected, you must specify the COM port number in use. If Use Modem is selected, the Port Number field will be disabled and the Phone Number field enabled.

The required values for all the configuration options should be available from the specification provided with the hardware device connected to your serial port.

Serial Port settings tab

Use Modem

Provides control over whether a modem or a serial port is to be used.

This check box must be selected, and a remote phone number phone number provided if the driver attached to this port is to be a modem tag.

When the Use Modem check box is selected, the Phone Number and Modem Initialization fields will be enabled.

Port Number

Used to set the number of the serial port that is to be used. The corresponding serial port number must be configured in the Ports dialog box of the Windows Control Panel. The value should match your port number and be between 1 and 4096.

If the Use Modem check box is selected, the Port Number field will be disabled and the Phone Number and Modem Initialization fields will be enabled.

Phone Number

When a modem is to be used, fill in this field with the phone number that the modem must call to reach the remote system. Supply all the digits including area code, etc. Do not include spaces.

If the Use Modem check box is not selected, the Phone Number field will be disabled.

Modem Initialization String

Used only if your modem requires a customized initialization string. In most situations, you will leave this field blank. If configured, any initialization string must be prefixed by "AT". Note that the initialization string will be used only by the Trihedral TSP driver. It will be ignored by the Unimodem driver.

Data Bits

Select a number (either 7, or 8) specifying the number of data bits to use for each character. The 8 bit setting, matching the size of a byte, is used for almost all devices. The 7 bit setting might be needed for older devices that require ASCII values.

Stop Bits

Specify the number of stop bits for each data character. (In asynchronous communications, a stop bit is a bit that indicates that a byte has just been transmitted).

Baud Rate

Set the baud rate (bits per second) at which data should be transmitted.

Parity

The Parity section enables data quality verification based on one of the following parity formats. It must be set to match your device configuration.

No Parity - select to suspend parity checking for this serial port. By default, the No Parity check box is selected.

Odd Parity - select to use the odd parity mode of parity checking in which the number of mark bits (1's) in the data is counted, and the parity bit is asserted or unasserted to obtain an odd number of mark bits.

Even Parity - select to use the even parity mode of parity checking in which the number of mark bits in the data is counted, and the parity bit is asserted or unasserted to obtain an even number of mark bits.

Space Parity - select to use the mark parity mode of parity checking in which the parity bit is unasserted.

Mark Parity - select to use the mark parity mode of parity checking in which the parity bit is asserted.

Echo

Select whether the transmitted data should be echoed in the received data.

If the Echo check box is selected, the driver should expect that the transmitted data will be echoed in the received data.

By default, the Echo check box is not selected.

RTS Keying

Select if the driver should assert RTS (Request to Send) flow control while data is being transmitted.

RTS/CTS (Request to Send/Clear to Send) flow control is typically used with all high-speed modems, or modems that compress data.

Key Up Delay

The Key Up Delay property sets the delay in seconds prior to data transmission. The Key Up Delay field is only enabled if the RTS Keying check box is selected.

The default value for the Key Up Delay property is 0.1 seconds.

Serial Port properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed Serial Port Tag Widgets

The following widgets are available to display information about your application’s Serial Port tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Color Line Widget

Comm Indicator Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 7 Segment Widget

LCD 5x7 Matrix Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget


TCP/IP Port Tags

Not counted towards your tag license limit.

The TCP/IP port type is used to connect your VTScada application to a series of hosts, allowing you to send and receive data across a network or over the Internet. TCP/IP port tags can also open a TCP/IP socket to emulate a Serial Port tag for use with serial-based I/O drivers using TCP/IP-based terminal servers.

Standard Port Numbers: Refer to the table provided in the description of the Connection tab, within this topic.

Reference Notes:

Monitor drivers, not ports. A port tag has a value only on the server that is communicating with hardware and will be blank on all other servers. The value of a port tag is not synchronized across all workstations. (Unlike I/O and driver tags.) If the alarm server and I/O servers are different machines, an alarm on a port tag will not activate. Do not attach an alarm to any port tag.
A port tag widget drawn on a page represents only state of the port on the local machine.

Listener Ports

A TCP/IP port tag can act as a listener (accept incoming TCP/IP socket connections) if a port number is defined, but a TCP/IP address is left blank. This allows drivers to act as slaves on network connections.

Do not configure your TCP/IP port tag with a blank address and configured port number unless you are also using a driver configured to accept unsolicited data. Problems may occur if the port with no address takes communications meant for other TCP/IP ports.

A TCP/IP Port with no address and no port number will do nothing. TCP and UDP ports that were using the default port numbers (3001 for TCP and 3123 for UDP) will no longer use these port numbers automatically and will no longer function as a listener or a client. To resolve this, they will need to be edited to use those port numbers explicitly.

In the unusual event that you have multiple devices attempting to use the same channel at the same time across multiple ports, you might consider adding Comm Link Sequencer Tags to serialize requests.

TCP/IP Error Codes

A valid TCP/IP (and UDP/IP) port tag can have any of the following values.

Error codes from the underlying operating system may be passed through. For codes not listed here, refer to https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--9000-11999-

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No Error
259 | 0x103 | Port did not connect
260 | 0x104 | Connection was lost
-802 |  | Neither the Common Name (CN) or Subject Alternative Names (SAN) used in the X.509 certificate match the target device name.
-803 |  | There is no Local Security Authority (LSA) context for the operation
-804 |  | The clocks on the client and server machines are too far skewed.
-10048 |  | Only one usage of each socket address (protocol/network address/port) is normally permitted.
-10051 |  | Port unreachable
-10053 |  | Connection aborted
-10054 |  | Connection reset
-10060 |  | Connection timeout
-10061 |  | Connection refused
-10065 |  | Host unreachable

See also: Client Socket Error Codes

Related information:

Comm Link Sequencer Tags - Serialize requests for the same communication channel across ports.

Best Practices for Tags

Communications and Firewalls

Ethernet to Serial Converters - Troubleshooting.

TCP/IP Port properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

TCP/IP Port properties Connection tab

The Connection tab of the TCP/IP port tag properties folder contains properties that enable communications.

TCP/IP Port tag - connection tab

TCP/IP Name/Address

The TCP/IP Name/Address field provides a space for you to identify the name or IP address of the server to which to connect (for example, MyRTU.com, or 198.255.32.1).

If using IPv6 addressing, names are strongly recommended over specific addresses.

If using a numeric address, do not include leading zeros. These are likely to be reinterpreted as octal values.

Listener Ports

A TCP/IP port tag can act as a listener (accept incoming TCP/IP socket connections) if a port number is defined, but a TCP/IP address is left blank. This allows drivers to act as slaves on network connections.

Do not configure your TCP/IP port tag with a blank address and configured port number unless you are also using a driver configured to accept unsolicited data. Problems may occur if the port with no address takes communications meant for other TCP/IP ports.

A TCP/IP Port with no address and no port number will do nothing. TCP and UDP ports that were using the default port numbers (3001 for TCP and 3123 for UDP) will no longer use these port numbers automatically and will no longer function as a listener or a client. To resolve this, they will need to be edited to use those port numbers explicitly.

TCP/IP Port Number

The TCP/IP Port Number field refers to the port number on the host address through which communications are enabled. This information should be available from your hardware specification.

The following drivers have standard port numbers, although individual instances may vary.

Driver | Port
Allen-Bradley SLC | 2222
Allen-Bradley EIP | 2222 or 44818
Allen-Bradley Controllogix / CIP | 44818
DNP3 | 20000
GE Series 90 | 18245
Siemens S7 | 102
OpenModbus TCP | 502
CIP | 44818
MQTT | 1883
Secured MQTT | 8883

A TCP/IP port tag may also be used to accept incoming TCP/IP socket connections if a port number is defined, but a TCP/IP address is not defined (null or invalid), thus allowing drivers to act as slaves on network connections. Use caution: unintended consequences may result if the port with no address takes communications meant for other TCP/IP ports.

Disconnect Delay

Specify in seconds or fractions of a second, the amount of idle time that should pass before the connection to the server is terminated. Cannot be set to zero.

For example, in normal Modbus operation a continuous connection is used so Disconnect Delay is set to be bigger than the expected poll rate so that polls keep the port busy and open. For a non-continuous connection, then Disconnect Delay can be set to a short value so that the connection is terminated soon after a poll completes (whether successful or not). If set to a value less than the poll rate then this will cause the driver to have to "reconnect" on every poll, but for Modbus this is not onerous as it simply reopens the TCP connection.

If the RTU can only handle one connection and you have two masters that are attempting to connect to it, then it is likely that at some point both will try to connect at the same time, resulting in a failure. Setting the Disconnect Delay to a small value might help to minimize connection collisions.

Maximum Connections

Set the maximum number of concurrent connection between VTScada and the address configured in this tab. For any benefit to be seen, both the driver and the PLC must support multiple concurrent connections. On the VTScada side, the following drivers support this feature:

  • TI505 Device Driver
  • Delta Driver
  • Enron Modbus Driver
  • Mitsubishi Driver
  • Modbus Compatible Device Driver
  • Toyopuc Driver

May be changed only for client TCP connections (a valid address has been set), not server TCP connections (no valid address). If the tag is set to act as a server, then Max Connections is limited to 1 to preserve legacy behavior.

Echo

Select whether the transmitted data should be echoed in the received data.

If the Echo check box is selected, the driver should expect that the transmitted data will be echoed in the received data.

By default, the Echo check box is not selected.

TCP/IP properties TLS tab

The Transport Layer Security (TLS) tab is used only when mutual TLS authentication is required. This feature applies only to TCP/IP Port tags used as clients (the Name/Address and the Port Number properties on the Connection tab are configured), not as servers.
To create a TLS connection to VTScada as a server, refer to Configure a VTScada Thin Client Server.

Mutual Authentication is the process by which, in addition to a TLS server providing a certificate to verify its identity, the client also provides a certificate to verify its identity.

Before configuring the parameters on this tab, all of the following must be true:

  • An X.509 certificate for mutual authentication must be installed in the "Personal" store for the user account, under which VTScada runs.
  • That certificate...
    • must be valid,
    • must have a private key associated with it, and
    • must have an extended key usage that permits client authentication (1.3.6.1.5.5.7.3.2).
  • The Name/Address and the Port Number properties on the Connection tab must be configured.

Instructions to install an X.509 certificate are provided in Internet Security (TLS, X.509, SSL)

Enable TLS

When selected, VTScada will enforce the use of TLS for connections to the Name/Address specified on the Connection tab. Otherwise, the connection is "plaintext".

Selecting this option enables the "Enable mutual authentication" check box.

Enable mutual authentication

Select to enable mutual authentication using an X.509 certificate provided by the connection client.

Selecting this option also enables the radio buttons with which you can choose automatic or manual certificate selection.

Automatically pick a certificate / Choose one of these certificates

Requiring both TLS and Mutual Authentication to be enabled, this loads a certificate from your local stores. 'Manual Selection' is required to enable the 'Select a certificate...' drop-down and 'Manage Certificates' button, which creates an instance of the Certificate Management UI in a new dialog window.

In the automatic mode, the operating system will select a certificate that has a Certificate Authority (CA) matching one of the acceptable CAs that the server has dictated during the TLS handshake protocol, assuming that the server is configured to provide such a list.

A problem can arise where there is more than one suitable certificate for the client to choose from, or the server does not provide a list of CA's so that any certificate on the client could be used. In interactive use, (for example, a web browser), this results in a pop-up dialog allowing the user to choose which client certificate to supply to the server. For a system such as VTScada, an interactive pop-up from the operating system each time a connection is made is clearly undesirable. In such cases, you should select the correct certificate manually.
Manual certificate selection can be performed only on a computer that has an appropriate certificate installed because you must be able to see it in order to select it.

The certificate names shown in the 'Select a certificate...' drop-down field use the "friendly" name of the certificate if possible, defaulting to the subject name in the certificate in the absence of the friendly name. As manual certificate selection is based on the displayed name, this allows you to have different certificates installed on different computers for the same tag so long as you have set the friendly name on each certificate to be the same. As the configuration for a tag is replicated throughout your distributed application, the same name will be used on each computer for the certificate. This is useful when the subject name varies by computer. (For example, if the subject name is the computer name.)

The friendly name is an editable field and can be changed via the Windows user interface for certificates. For example, using the Microsoft Management Console (MMC.exe) with the certificates snap-in, double click the certificate you want to set the friendly name on and click "Edit Properties" on the Details tab.

A manually selected certificate is indicated by a colored background in the list.

For multi-server applications: Because a TCP/IP Port tag's configuration is distributed around the system, any computer that can establish a connection using the tag must have an appropriate certificate installed. Automatic certificate selection will pick an appropriate certificate from any hints provided by the server and manual selection will use a specific certificate as configured in this tag.

TCP/IP properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed TCP/IP Port Tag Widgets

The following widget is available to display information about your application’s TCP/IP port tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Color Line Widget

Comm Indicator Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 7 Segment Widget

LCD 5x7 Matrix Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget


UDP/IP Port Tags

Not counted towards your tag license limit.

The UDP/IP port type can be substituted for a TCP/IP port tag for a driver to use the User Datagram Protocol (UDP). This protocol differs from TCP in that it does not provide for error checking, but does provide good support for packet broadcasting and multi-casting.

In the unusual event that you have multiple devices attempting to use the same channel at the same time across multiple ports, you might consider adding Comm Link Sequencer Tags to serialize requests.

Monitor drivers, not ports. A port tag has a value only on the server that is communicating with hardware and will be blank on all other servers. The value of a port tag is not synchronized across all workstations. (Unlike I/O and driver tags.) If the alarm server and I/O servers are different machines, an alarm on a port tag will not activate. Do not attach an alarm to any port tag.
A port tag widget drawn on a page represents only state of the port on the local machine.

Warnings:

All UDP/IP port tags use an internal listener port to receive datagram responses. The is what the Local Port Number defines (it is also used as the transmit port number).

The engine will automatically route responses back to the UDP socket stream if the remote IP address matches that of the stream. This means that multiple UDP/IP port tags can make use of the same local port number (internally they share the UDP port listener). This UDP port listener requires that the port be free, thus any conflict for use of the port runs the risk of disrupting UDP/IP communications.

Take note of the following possible errors. Some may not cause problems until the next re-start of the application.

1) UDP/IP Port and IP Network Listener tag sharing the same port number.

The IP Network Listener tag uses a socket server to function. This can interfere with the UDP listener port used by the UDP/IP port tag. The VTScada engine will already listen for UDP/IP datagram packets and place them into existing UDP streams if the remote IP address matches that of the UDP stream.

In general, do not configure an IP Network Listener tag with a UDP port unless you are certain that one is required. If you are certain, then ensure that they do not share the same port number. See also, warnings 2 and 3.

2) UDP/IP address left blank

The UDP/IP port tag functions as a socket server when the Name/Address field is invalid (blank) but a port number is configured. It will listen on the defined port number for any datagram messages and will bind to the first one received. In this way it is similar to an IP Network Listener, only without the discrimination/filtering abilities. Note that you can have only one listener in the system, whether that be a UDP port configured to listen or a IP Network Listener.

If you are unsure of the remote address then enter 0.0.0.0 rather than leaving the field blank.

3) Disconnect Delay defined.

> Do not define unless you are using an IP Network Listener in combination with the UDP/IP port.

> Do not use an IP Network Listener with a UDP/IP port unless you are certain that one is required.

This option was included exclusively for use with IP Network Listener tags. There is one situation where the engine-level UDP handling is insufficient, which is when the remote device can respond with different IP addresses over time. Use the Disconnect Delay to disassociate the remote IP after a period of inactively. The VTScada engine is then able to establish new remote IP address associations with the remote device via IP Network Listener tags. It is extremely unlikely that there would be a reason to use an IP Network Listener with a UDP port unless this is the case.

UDP and TCP/IP Error Codes

A valid TCP/IP (and UDP/IP) port tag can have any of the following values.

Error codes from the underlying operating system may be passed through. For codes not listed here, refer to https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--9000-11999-

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No Error
259 | 0x103 | Port did not connect
260 | 0x104 | Connection was lost
-802 |  | Neither the Common Name (CN) or Subject Alternative Names (SAN) used in the X.509 certificate match the target device name.
-803 |  | There is no Local Security Authority (LSA) context for the operation
-804 |  | The clocks on the client and server machines are too far skewed.
-10048 |  | Only one usage of each socket address (protocol/network address/port) is normally permitted.
-10051 |  | Port unreachable
-10053 |  | Connection aborted
-10054 |  | Connection reset
-10060 |  | Connection timeout
-10061 |  | Connection refused
-10065 |  | Host unreachable

See also: Client Socket Error Codes

Related information:

Comm Link Sequencer Tags - Serialize requests for the same communication channel across ports.

Best Practices for Tags

Communications and Firewalls

Ethernet to Serial Converters - Troubleshooting.

Closed UDP/IP Port properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

UDP/IP Port properties Connection tab

The Connection tab of the UDP/IP port tag properties folder contains properties that enable communications.

If the UDP/IP Name/Address field is blank, then behavior will depend on the configuration of the Remote Port Number and Local Port Number as follows:

Remote Port Number and Local Port Number configured:

The tag will be a listener on the port and any inbound datagrams will sit in a bi-directional stream (i.e. a driver can both read and write to the stream). Writes to the stream cause datagrams to be issued to the device that originated the inbound datagram that created the stream and are transmitted to the "Remote Port Number" on the device.

Remote Port Number blank and Local Port Number configured:

The tag will be a listener on the specified local port.

Remote Port Number blank and Local Port Number blank:

The tag will do nothing.

UDP/IP Name/Address

The UDP/IP Name/Address field provides a space for the name or IP address of the server to which this tag will connect. (For example, MyRTU.com, or 198.255.32.1). If using IPv6 addressing, names are strongly recommended over specific addresses.

If using a numeric address, do not include leading zeros. These are likely to be reinterpreted as octal values.

Remote Port Number

Specifies the port number on the host address through which communications are enabled.

Local Port Number

Sets the port number on which the local PC should listen.

Disconnect Delay

Do not configure unless you have determined that an IP Network Listener is required and you are absolutely certain that a disconnect is required due to the RTU using differing IP addresses.

Specify in seconds or fractions of a second, the amount of idle time that should pass before the connection to the server is terminated. To be used only when the IP address of the remote device changes between each transmission, thus allowing a new connection.

Handle datagrams from different source ports as new connections/Only accept datagrams from the configured remote port

The label of this checkbox is "Handle datagrams from different source ports as new connections" when in server mode and "Only accept datagrams from the configured remote port" when in client mode.

  • VTScada sends messages from the local port to the remote destination port.
  • The remote device sends from the remote source port to the local port.
  • The remote destination port and remote source port are often the same port, but may not be. It is because of this difference that the following options are required.

If running in server mode (the UDP/IP Name/Address field is empty)

LABEL: "Handle datagrams from different source ports as new connections"

A UDP "stream" is initially created when the first datagram is received from the remote device. For subsequent datagrams:

  • If the remote device sends a datagram from the same port as the previous one, the datagram will appear in the same stream as the first one. Leave the check box unselected.
  • If the remote device sends a datagram from a different port as the previous one, then:
    • Check box selected: A new stream is created into which the datagram will be placed.
    • Check box NOT selected: The datagram is placed in the existing stream.

This has significance when the driver using the UDP port attempts to transmit using the existing stream. When the check box is selected, the stream is associated with a specific port on the remote device and will be sent there. When the check box is NOT selected, it will be sent to the port on the remote device that issued the datagram that created the stream.

If running in client mode (the UDP/IP Name/Address field is configured)

LABEL: "Only accept datagrams from the configured remote port"

A UDP "stream" is initially created when the driver requests it. For all datagrams:

  • If the remote device sends a datagram from the port matching the Remote Port Number in this driver, then the datagram will appear in the stream.
  • If the remote device sends a datagram from a different port then:
    • Checkbox selected: If there is no existing UDP tag that matches the remote port number the datagram is discarded.
    • Checkbox NOT selected: The datagram is placed in the existing stream.

With the check box selected, drivers that care about the remote port from which the datagram has been sent can utilize multiple UDP tags and have inbound datagrams from (for example) a pair of remote port numbers, stored in separate streams.

If you have more than one UDP/IP tag with the checkbox selected and with the same address and local port, the socket connection could fail and show "10048 error".
Under these conditions, regardless of the remote port numbers, more than one tag would appear to be an eligible recipient of the datagram, creating a conflict.

Maximum Connections

Set the maximum number of concurrent connection between VTScada and the address configured in this tab. For any benefit to be seen, both the driver and the PLC must support multiple concurrent connections. If the tag is running in server mode or the local port is not given, the maximum connections will be limited to 1.

On the VTScada side, the following drivers support this feature:

  • TI505 Device Driver
  • Delta Driver
  • Enron Modbus Driver
  • Mitsubishi Driver
  • Modbus Compatible Device Driver
  • Toyopuc Driver

Echo

Select whether the transmitted data should be echoed in the received data.

If the Echo check box is selected, the driver should expect that the transmitted data will be echoed in the received data.

By default, the Echo check box is not selected.

Closed UDP properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed UDP/lP Port Tag Widgets

The following widgets are available to display information about your application’s UDP/IP Port tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Color Line Widget

Comm Indicator Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 7 Segment Widget

LCD 5x7 Matrix Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget


Communication Driver Tags

Drivers connect to Ports and define the protocol used to communicate with your hardware. Which one you choose will depend on the specifications of that hardware. More than 35 drivers come with each copy of VTScada and many more are available on request. Each brand of PLC or RTU generally requires its own communication driver. (Some also allow an alternate protocol. For example, many have a Modbus Compatibility mode.)

For an up-to-date list of drivers included with VTScada, please refer to the Device Driver List page on the VTScada website

Details for compatible address formats can be found in the topic following each driver description.

Address Assist / Address Select

Many drivers support an "Address Assist" or "Address Select" dialog, which will be available as a button beside the Address field of all I/O tags using that driver. The content of the dialog will vary according to the driver. The one thing these dialogs have in common is that they will help you build addresses in the correct format. Note that the addresses cannot be populated until communication is established with the device.

Three examples of an I/O address assist.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

The timestamp (local timezone) of the last successful read is held in the driver's LastTime property. You can view this by drawing a Show Statistics Button Widget, or by writing an expression using [Driver Name]\LastTime. Note that a change in this value does not necessarily mean that the data is live. The remote server could return the same value and the timestamp would continue to increase.

Trihedral Engineering Limited has many communication drivers available beyond those included with the VTScada. Refer to the VTScada driver library on the Trihedral web site for further information.

Related information:

Communication Driver Log-Enabled Variables - Describes the variables that may be logged for your driver.

Data Suffixes for Tag I/O Addressing - Common strings to control how I/O data is interpreted.

Communication Driver Alarms - Example and instructions to create an alarm on any of the log-enabled variables.

Driver Server Lists - Specify the primary and backup servers for drivers.


Communication Driver Log-Enabled Variables

All of the standard drivers have 7 variables that may be logged. When recorded in a report, these allow you to monitor driver communications over time to spot problems or ensure that response times are acceptable.

Logged Variable | Description
1. ErrorValue | An error value or code associated with a driver's communication error.
2. FailedCount | Incremented on each communication error.
3. FailedRetryCount | Incremented if failure occurs on a retry. Drivers will usually retry more than once before designating an error to be an "error on retry". Thus, this count will always be less than or equal to the FailedCount.
4. SuccessCount | Count for successful reads and writes, incremented on each successful operation.
5. Quality | A mathematically derived indication of communication error rates. Used to show the driver's overall "health". (1)
6. ResponseTime | The time it takes the PLC/RTU to receive a command, process it and send a response. (2)
7. ErrorAddress | If an address was associated with the error, it will be recorded here.

A publicly accessible variable, CommStatsTimeStamp, holds the most recent timestamp that was used to update these variables and write them to a DAT file.

Monitoring Driver Health and Errors

To view errors, use the Reports Page. Two reports are standard for all communications drivers. The Driver Communication Error Detail Report and the Driver Communication Summary Report. Both are described in Report Types Described.

You can also place the appropriate Show Statistics Button Widget on a page to monitor the values in real-time.

On a busy system, it is dangerous to use these properties in expressions. SuccessCount and FailedCount in particular update with every read. Excessive RPC traffic may result, slowing your overall system performance.

Closed (1) Calculation of Quality:

Quality is an indication of a driver's ability to communicate without errors. The value ranges between 0 and 1 where the closer the quality is to 1 (100%) the fewer communication errors are happening. You will need to determine what an acceptable level of quality is for your situation. To put it simply, the closer the quality is to 1, the better the driver communication.

On an initial, successful communication with a device, a quality of 1 (or 100%) is recorded. If subsequent communications attempts end with errors, the level of quality drops according to the following formula. Successful communications serve to then raise the level of quality back to a maximum of 100%.

You may find that the quality calculation changes through the day. This might indicate interference from a source that can then be tracked down.

The quality calculation formula:

Q = Q * qF + (1 - qF) * (1 - !Error)

Where:

Q = Quality

qF = Quality Factor

Error is a Boolean stating whether the driver reported an error state.

The default Quality Factor is .99 & all drivers start with a default Quality of 1.

Every time the driver completes an operation, the quality is recalculated.

Thus, when it first starts and does a successful operation:

Q = 1 *.99 + .01*1 = 1

When an error occurs, Q = 1*.99 = .99

If a subsequent error occurs, Q = .99*.99 = .9801

If a subsequent success occurs, Q = .9801 *.99 + .01*1 = .980299

The quality value over time will reflect the drivers overall health. It should always be a value between 0 & 1.

Quality includes all errors including any low level errors, retries, or addressing errors.

Closed (2) Response Time

Response Time is calculated with the formula:

ResponseTime = EndTime - StartTime - XmitTime - RcvTime

Where:

XmitTime is the time it took to transmit any data

RcvTime is the time it took to receive any data, based on

  • the number of bytes sent,
  • the baud rate,
  • parity,
  • data bits and stop bits,
  • whether there is an echo expected,
  • whether RTS key delays are used.

The resulting Response Time is the time it took the PLC/RTU to receive a command, process it and send a response.

Related information:

Calculation properties Calc tab

Driver Communication Error Detail Report

Driver Communication Summary Report


Data Suffixes for Tag I/O Addressing

The data type to read from or write to is usually implied by the address. If it is not, the strings shown in the following table may be appended to the address (without spaces) to force the data to be interpreted as a specific type. Not all suffixes apply to all drivers.

Suffix | Meaning
/AB3Float | Allen-Bradley PLC/3 Floating Point (4 bytes) (Used for Allen-Bradley exclusively)
/AB5Float | Allen-Bradley PLC/5 Floating Point (4 bytes) (Used for Allen-Bradley exclusively)
/BCD2 | 2-digit (1 byte) Binary Coded Decimal
/BCD3 | 3-digit (2 bytes - lowest 12 bits) Binary Coded Decimal
/BCD4 | 4-digit (2 bytes) Binary Coded Decimal
/BCD8 | 8-digit (4 bytes) Binary Coded Decimal Note: while any driver may use this suffix to read data, only the Modbus Compatibly can use it to write data.
/Bit | Attempts to convert the value to a single bit. The bit number used is always 0. (ex: 40001/Bit)
/Double | IEEE Double Precision Floating Point (8 bytes)
/Float | IEEE Single Precision Floating Point (4 bytes)
/SByte | Signed Byte
/SDWord | Signed 32-bit Integer. If used in combination with /Bit, /SDword comes last: example: 40001/0/SDWord
/SWord | Signed 16-bit Integer
/UByte | Unsigned Byte
/UDWord | Unsigned 32-bit Integer
/UWord | Unsigned 16-bit Integer

For example:

40001/UDWord

Reading Strings

If reading string data, note that not all PLCs will store characters in the same in order in registers. Further, registers may vary in size from one PLC type to another.

If the string read from your registers has characters that are not in the order you expected, use the BuffOrder() function in an expression to swap the order of the characters so that they do match what is expected. Do this by creating one I/O and Calculations tag to read the value, then create a second with an expression to read the value in the first and apply the BuffOrder function. The second I/O and Calculations tag will not count against your license because it does not use a read or write address.

Better practice is to program the PLC to send an integer code that can be mapped to a phrase in VTScada. The result can be used in a multilingual application and can reduce the amount of data transmitted.

Example: A BuffOrder call for a word-sized register with the character order swapped:

BuffOrder([<SourceTag>], 0, 1, 2, N)

...where the value N should be the half the length of the buffer.

Related information:

Each I/O device uses a different addressing system. Details can be found in the following topics:

ABB Totalflow I/O Addressing

Allen-Bradley Driver I/O Addressing

BACnet Driver Addressing

Bristol BSAP/IBP Driver Addressing

CalAmp Driver I/O Addressing

Campbell Scientific Array I/O Addressing

Campbell Scientific PakBus I/O Addressing

CAT 5MX Addressing

CSV Data Driver Addressing

Delta Driver Addressing

DNP3 I/O Addressing

DriverMUX I/O Addressing

Enron Modbus I/O Addressing

Fisher ROC I/O Addressing

GE Series 90 Addressing

Honeywell Mercury Driver Addressing

IEC 60870-5-104 Addressing

Koyo Driver Addressing

MDS Diagnostic Driver I/O Addressing

Mitsubishi Addressing

Modbus Compatible Device I/O Addressing

Modbus Plus PLC Addressing

Motorola ACE Driver I/O Addressing

MQTT Client Addressing

Omron I/O Addressing

OPC Classic Client Driver I/O Addressing

NMEA 0183 Driver Addressing

Omron FINS I/O Addressing

Omron I/O Addressing

OPC Classic Client Driver I/O Addressing

OPC UA Addressing

Rockwell Driver I/O Addressing

ScanCom Driver I/O Addressing

Siemens S7 Driver I/O Addressing

SNMP I/O Addressing

SQL Data Query I/O Addressing

Tesco Driver Addressing

TI505 Driver Addressing

Toyopuc Driver Addressing

Veeder Root Tag Addressing

Workstation Status Driver I/O Addressing


Verify the Write?

When writing to hardware, you can be assured that the SCADA system will attempt to send the signal you requested. Ensuring that the signal arrives is another question, and it is the role of the driver to answer that.

For nearly all protocols supported by VTScada, including Modbus, DNP3, CIP, DF1/PCCC, Step 7, etc., the messages sent to a device will receive one of the following three results. (These are inherent to the protocol, not the VTScada driver.)

  • The device responds with a positive acknowledgment that the command was received and accepted.
  • The device responds with a negative acknowledgment that the command was received but NOT accepted.
  • The device does not respond at all

For case #1, the VTScada driver will receive the acknowledgment and know that the write succeeded. (The success count in the driver will increase, the error count will not, and the value of driver will remain 0.) Nothing more needs to be done.

For case #3, Most VTScada drivers will invoke their retry logic and automatically attempt the write a predefined number of times before giving up and declaring an error. This error is set into the value of the driver and you can then alarm on it to indicate that there was a problem. This varies by driver. For example, the Modbus protocol does not send a response to writes and therefore there is no point in using retry logic. Refer to the standards for your selected protocol. (Communication Driver Alarms)

Case #2 is more difficult in that it tends to be protocol-specific. For example, if you attempt to write to a non-existent address using a Modbus Compatible driver, you can expect a Modbus exception code response from the device. Attempting to write the same value again to the same address would not accomplish anything because the device has already signaled that it cannot do what is being asked (write to a non-existent register). As with case #3, the value of the driver will be set to the appropriate error code and can be used to generate an alarm.

In other drivers (for example, the Allen Bradley DF1), the device can respond with a NAK response if we send a message that becomes scrambled, as indicated by a bad CRC. In this case we DO want to retry the message and the retry logic is invoked. If the condition persists for the number of defined retries, the value of the driver tag is again set to an error code that can be alarmed on.

Beyond monitoring driver error codes and quality values, you can also ask the PLC to confirm your request. This is done by programming the PLC to set a verification value on a separate address when it receives a command from the SCADA system. By monitoring that address, you can be sure that the PLC received the command that you sent.


Communication Driver Alarms

The standard alarm on a communication driver simply watches for a value other than 0. (Zero meaning that there are no errors.) To avoid transient alarms on startup, it is a good idea to use a delay.

You could also use the information in the topic, Communication Driver Log-Enabled Variables to create Alarm tags to warn operators of a decrease in communication quality.

The alarm tag will use an expression as its trigger, where the expression refers to one of the log-enabled variables in the communication driver. It is recommended that you create the alarm tag as a child of the driver tag.

Example:

In most cases you will want an alarm that triggers when the driver fails. To do so, watch for the value of the driver tag to become a number greater than 0. A delay on this alarm will be essential because during application startup, all drivers are initially set to Invalid until communications are established, and may have errors while connecting.

Alternatively, you might create an alarm to warn of driver quality falling below a value such as 0.90. The expression would be: [*Driver]\Quality Note that in the event of on-going communication failures, it can take a long time for this alarm to normalize. This alarm might be better as a trip alarm and configured with a Boolean expression (1 or 0) such as True([*Driver]\Quality < 0.9)

This expression assumes that the Alarm tag was created as the child of a driver. If the alarm cannot refer to a parent driver, substitute the full name of the driver tag for "*Driver".

Related information:

- Describes the variables that may be logged for your driver.


ABB Totalflow Driver

Use the ABB Totalflow driver tag to communicate with a variety of Totalflow devices produced by ABB. This VTScada driver relies upon a COM server developed by VTScada and that constitutes a wrapper around ABB's TCI-3.13 library. (Note that the TCI library is copyrighted by ABB).

The driver requests transactions such as DB2FCU Read Device Setup transaction or Read Registers transaction from the COM server. This server is responsible for handling the TCP communication with the ABB Totalflow Computer device to perform the transaction and then hand out the results of the transaction to the driver. The driver instantiates the COM Server and requests operations and data using its COM interfaces.

The COM server ships with and is installed by VTScada. No configuration is required. It is launched automatically when needed and terminated by the driver.

When being used by the driver, the COM server will show in Windows Task Manager, Details view as "ABBTCIWrapper.exe".

Communication Methods Supported

Totalflow RTUs are capable of different modes of communication with SCADA host systems using variants of protocol messaging. Early Totalflow RTUs, manufactured in the 1980s and 1990s, use the DB1 FCU protocol. Newer Totalflow RTUs, beginning with late model Totalflow G3 models, use the DB2 FCU, DB2 Register, and DB2 Trend protocols.

Communication protocols currently supported by the VTScada Totalflow Driver include:

Method | Comments
DB1 FCU | Not supported.
DB1 FCU + VCI | Not supported.
DB2 FCU | Supported
DB2 Register | Supported
DB2 Trend | Supported

Trend Files in ABB Totalflow Computers

Trend Files in the TotalFlow computer are historic files that are custom defined and configured by users via a client, such as ABB's PCCU software, that allows configuring an ABB Totalflow computer. You must specify what variables go in a file, the frequency of collecting the variables, as well as the frequency of writing them to the Trend file. A sequence variable is not included in a Trend File by default; if one is needed, you must configure the Trend file to contain one by specifying a trend variable called either "Seq" or "Sequence".

Settings for reading Trend files by the driver are configurable in the ABB Totalflow Driver properties: Trend tab of the properties dialog.

Since Trend readings (by time of sequence) will start from the last successfully read record, you must be careful when setting a maximum time or maximum sequence to ensure a successful reading takes place.

Troubleshooting:

  • To verify that ABBTCIWrapper installed correctly, a search of your Windows Registry for ABBTCIWrapper should find it in multiple places such as that shown in the following figure:

    Click image to expand.

  • VTScada will install ABBTCIWrapper.exe using 32 or 64 bits architecture to match your VTScada installation. (32-bit or 64-bit) If you decide to switch from one architecture to the other you must uninstall VTScada first (to also remove ABBTCIWrapper) and then install the new version.

  • The driver will spawn a single instance of the COM server for a single transaction with an ABB Totalflow device at a time. If you have multiple driver instances running in your app you might see multiple instances of ABBTCIWrapper.exe in the Task Manager.
    Each instance of the COM server will close after a transaction is finished and the results are returned to the driver.
    All instances of the COM server should close if the VTScada application stops. If the shutdown is not graceful, then some instances of ABBTCIWrapper.exe may linger in memory. These do not affect new wrapper instances but waste memory and will prevent a new installation of the COM server. Restarting the server is an effective way to clear the instances or you can stop each instance using the Task Manager. Advanced users can use the command "taskkill /F /IM ABBTCIWrapper.exe" in an elevated command prompt to stop all of the instances.

Related information:

Best Practices for Tags

Closed ABB Totalflow Driver properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

ABB Totalflow Driver properties: Device Info tab

Configure the tag port, Station ID, Security Code, Max Read Block Size, Packet Size and Device Click Time Zone.

Port

It is the COM server that performs all the communication. The TCP Port tag specified here is a place holder used for backward compatibility. It will specify the remote ABB Totalflow device's address / port and that information is passed by the driver to the COM server

The driver supports only TCP/IP port tags.

Station ID

The station ID of the device. (Before multimeter devices were created, this was referred to as the meter Id.) The station ID is 1 to 10 printable characters.

Security Code

The four-character security code assigned to the device. Allowable characters are ASCII hex 30 through hex 39 (decimal characters 0 through 9).

Maximum Read Block Size

The block size that should be used when filling packets. The block is the smallest subset of a message that is CRC protected, so the block is the smallest subset that can be requested in a retry.

Packet Size

The number of bytes that are contained in a single message from the device to the host. In the DB2 protocol, the host returns an ACK for each message (packet plus header) that is received, so the larger the packet size, the fewer number of device transmissions and host acknowledgments are required.

Device Clock Time Zone

Defaults to the server's time zone.

ABB Totalflow Driver properties: Communications tab

Configure the Timeout Limit, number of retries, whether to hold the last value in the event of a comm failure, the link time in seconds, and debug level.

Timeout Limit

The time the driver will wait for a response before setting an error or retrying.

Retries

The number of times to retry a message before declaring an error.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Link Time

Time, in seconds, to send request frames.

Debug Level

The debugging level for communication between the driver and the ABBTCI COM server. Debug output can be found in the application’s "\Data\TraceFiles\ABBTFLogs" directory.

Debugging information is saved to files named "s_Sanitized name of the driver tag-YYYY-MM-DD.LOG" for example "s_Westwells-ABBTFD2-2023-11-08.log

The ABBTCIWrapper.exe COM server logs debugging information to files named "Sanitized name of the driver tag_Tube(TubeNbr)_YYYY-MM-DD.LOG" for example:"Westwells-ABBTFD2-Tube(0)-2023-11-08.log"

YYYY-MM-DD represents the date on which the data was recorded to the file.

The application property, TotalflowAutoDebugDisableTime, specifies the length of time that logging stays in INFORMATION or VERBOSE mode before it is automatically switched to ERROR.

ABB Totalflow Driver properties: Request tab

Configure Operator credentials, enable or disablel compress response, daily records, flow header, event records, log period records, alarm log, new event records, collecting events, configure history collect method and max days. Defaults displayed.

Operator ID

Required if the device is configured to record the name of the operator with each event or to use role-based access. Leave blank otherwise.

Password

If the device is configured to use role-based access, values for both Operator ID and Password are required. Leave blank otherwise.

Compress Response

A flag that indicates if the data content in the response should be compressed. This is not available with DB2 Register requests.

Flow Header

Determines if the flow header (ranging in size from 200 to 500 bytes) should be retrieved in a historical collection.

If selected, the device returns the flow header at the start of the response so that flow header fields are used for decoding the other records in the response.

If not selected, the device returns an 8-byte header before each record type in the response.

Daily Records

Select if the Daily Records should be retrieved as part of the historical collection.

Log Period Records

Select if the Log Period records should be retrieved as part of the historical collection.

Event Records

Select if the original Event records should be retrieved as part of the historical collection. This setting is mutually exclusive of New Event Records.

Alarm Log

Select if the Alarm Log records should be retrieved as part of the historical collection.

New Event Records

Select if the new Event records should be retrieved as part of the historical collection. This setting is mutually exclusive of Event Records.

Collecting Events

Select if the device should treat this transaction as a collection process. Devices configured to operate in conformance with Canadian measurement requirements retain all events until collection is complete. Setting this flag causes the device to mark the retrieved events as reusable so that the events are overwritten, when necessary.

History Collect Method

Determines how the historical collection is retrieved. May be one of:

0 – by recent days

1 – by start and stop sequence number

2 – by start and stop time

Maximum Days

Limits the number of days of history to collect.

ABB Totalflow Driver properties: Trend tab

Configure trend collect method, directory, maximum days and maximum number of records if applicable.

Trend Collect Method

Determines how a Trend file is retrieved. May be one of:

0 – Days

1 – Sequence

2 – Timestamp

For both Days and Timestamp you must specify a decimal number of days to add to the persisted last timestamp. Every time a trend file is read, the last record read provides 2 bookmarks: last timestamp and last sequence (if sequence is applicable). The next time the trend file is to be read, the reading starts from those bookmarks. Initially, the bookmarks will be invalid or zero, and the first reading by-Days or by-Timestamp goes back from the current time to Maximum Days or the first reading by-Sequence starts from zero up to Maximum Number of Records.

Trend Directory

Sets the base folder holding the Trend file. Added to the FILE portion of the Trend datum address:

(TR:FILE:ATTRIBUTE

Maximum Days

Maximum number of days to read starting from the last timestamp read. Disabled if the Trend Collect Method is set to Sequence.

Maximum Number of Records

Maximum number of records to read starting from the latest record in the sequence. Disabled if the Trend Collect Method is set to Days or Timestamp.

Closed ABB Totalflow Driver: Widgets

The following widgets are available to display information about your tags:

ABB Totalflow Communication Messages Dialog

This Communication Messages Dialog will be drawn for the driver but will not show any data because all communications are done by the COM server, which follows a closed, proprietary protocol

ABB Totalflow Statistics Dialog


ABB Totalflow I/O Addressing

Links to address types in this document:

Totalflow Address Assist

Legacy vs. Register Addressing

Legacy Structure Addressing

Register Addressing

Trend Addressing

Accessing Legacy Data Structures

Accessing Registers

Accessing Trends

Read Current Measurement

Orifice Meter Run

Turbine Meter Run

Liquid Meter Run

Write Gas Analysis

Read History

Communication Methods Supported

Totalflow RTUs are capable of different modes of communication with SCADA host systems using variants of protocol messaging. Early Totalflow RTUs, manufactured in the 1980s and 1990s, use the DB1 FCU protocol. Newer Totalflow RTUs, beginning with late model Totalflow G3 models, use the DB2 FCU, DB2 Register, and DB2 Trend protocols.

Communication protocols currently supported by the VTScada Totalflow Driver include:

Method | Comments
DB1 FCU | Not supported.
DB1 FCU + VCI | Not supported.
DB2 FCU | Supported
DB2 Register | Supported
DB2 Trend | Supported

Totalflow Address Assist

Addresses can be more easily configured by the SCADA administrator by using the Totalflow Address Assist feature when configuring the telemetry address.

Configuration fields will vary according to the Register Type you select.

Legacy vs. Register Addressing

Totalflow RTU item addressing follows two approaches. The first is a legacy approach that can access individual data fields in "C" programming language style structures, used since the 1980s by Totalflow RTUs. Totalflow RTUs represent all types of data records as structures when using the legacy approach.

For example, a periodic flow history record has the following structure:

typedef struct
{
  TFTime  DateTime;         //Date and time
  USHORT  nSequence;        //Sequence number
  float   fpDP;             //Fixed Point Differential Pressure
  float   fpAP;             //Fixed Point Absolute Pressure
  float   fpTf;
  float   fpExtension;      //Fixed Point Extension
  float   fVolume;          //Total Volume for period (MCF)
  float   fEnergy;          //Total Energy for period
  SHORT   nFlowTime;        //Seconds flow time for period
  USHORT  nTotalLogPerTime; //Total seconds in period
  UCHAR   ucAlarms[3];      //Alarms - bit encoded
  UCHAR   ucVerCode;
  long    lArchSeq;
} ARCH_FCU_LOGPER;

Each data item in the structure has a distinct field name and a specific data type. For example, the accumulated volume for a periodic flow history record, such as fVolume , has the specific data type float.

The data field fVolume can be mapped directly to a VTScada tag such as an I/O in Analog mode, an Analog Input or Analog Status by specifying the field name and other information in the I/O address of the tag.

The second addressing approach uses a register identifier to access data items. Conceptually similar to a Modbus register address or an Emerson ROC TLP address, a register address for a Totalflow RTU provides an alias with an offset that is mapped into the specific data structures using numeric indices rather than specific data field names. Register addressing has some advantages over legacy structure addressing as registers can be queried from Totalflow RTUs in bulk for improved communication efficiency, but have the drawback of requiring a register map for the RTU, which can be dependent on the program configured in the specific RTU.

Legacy Structure Addressing

The general syntax for addressing data items in the "C" style structures within a Totalflow RTU is:

<Command Code>:<Run/Tube Number>:<Structure Field Name>

<Command Code>

Indicates to the VTScada driver which Totalflow command is to be used when reading or writing a data item in a Totalflow RTU.

<Run/Tube Number>

Indicates to the VTScada driver which integer Run/Tube number is targeted when reading or writing a data item in a Totalflow RTU.

<Structure Field Name>

Referred to as ATTRIBUTE in the address format examples that follow, this indicates to the VTScada driver which specific data field in a data structure is targeted when reading or writing a data item in a Totalflow RTU.

Sample legacy structure addresses (All DB2FCU):

AL:1:bit.19

CM:1:bit.19

DS:1:fOrificeSize { this address for example allows Read/Write }

HS:1:DAILY:fExtension

HS:1:LOGPER:fpExtension

HS:1:ALARMLOG:cMessage

HS:1:EVENT:cNewVal

HS:1:NEWEVENT:DataType

RE:1 { This is the address to write to in order to Reset Events for tube 0 }

RV:1 { This is the address to write to in order to Reset Volume for tube 0 }

DT { This is the address to writeDate Time }

Register Addressing

The RTU vendor documents array and register numbers in their respective user manuals for various RTU models. A large amount of documentation on the numerous models of Totalflow RTU units which describes in detail the operations and register addresses is readily available on ABB's public web site or through web searches.

Often the register mapping can be defined by the Totalflow RTU programmer using the PCCU software tool also provided by the vendor.

The use of register addressing requires a register map associated with the specific program in the Totalflow RTU. As the register map can vary between RTUs, consistency in programming will make configuration of the VTScada driver simpler. In contrast, legacy structure addressing does not require a register map as the structures are predefined and consistent between different models of RTU.

The general syntax for addressing data items using register style addressing within a Totalflow RTU is:

<Command Code>:<Application>.<Array>.<Index/Register Number>[/DATA TYPE]

<Command Code>

Indicates to the VTScada driver which Totalflow command is to be used when reading or writing a data item in a Totalflow RTU. For Register addressing, the <Command Code> must be set to "RG".

<Application>

An integer value which indicates a specific application area within the Totalflow RTU that will be accessed. For example, a value of 0 (zero) is typically the "System" application.

<Array>

An integer value which indicates a specific data area within an application in the Totalflow RTU that will be accessed.

<Index>

An integer value which indicates a specific data item for a data area and application in the Totalflow RTU that will be accessed.

[/DATA TYPE]

An optional string appended to the data item address. It specifies the expected data type of the register item in the Totalflow RTU. If not specified, it defaults to TF-FLOAT (#REGTYPE_FLOAT), a 32 bit floating point value.

RG addresses have the following schema with three mandatory components and two optional ones:

RG:Application.Array.Register[/Type][/Member]

Sample addresses follow. Note that the lack of a data type implies TF-FLOAT.

Simple registers:

RG:1.2.1/TF-FLOAT , RG:1.2.1 , RG:1.6.2/TF-STR

Complex registers: (For example, registers that are structures such as Hourly or Daily records.) Note that the [/Member] component should never appear without the [/Type] part

>RG:11.250.1/TF-PER/DateTimeString, RG:11.251.1/TF-DAY/temperature }
Register Address Data Type [/DATATYPE] Options | Internal Totalflow RTU Data Type | Description / Comments
TF-SWORD | #REGTYPE_INT16 | Signed 16-bit Integer
TF-SDWORD | #REGTYPE_INT32 | Signed 32-bit Integer
TF-UBYTE | #REGTYPE_BYTE | Unsigned 8-bit Integer
TF-UWORD | #REGTYPE_UINT16 | Unsigned 16-bit Integer
TF-UDWORD | #REGTYPE_UINT32 | Unsigned 32-bit Integer
TF-FLOAT | #REGTYPE_FLOAT | Floating Point 32-bit - default type used when optional address component [/DATA TYPE] is not specified.
TF-DOUBLE | #REGTYPE_DOUBLE | Floating Point 64-bit
TF-STR | #REGTYPE_STRING | Character String
TF-REG | #REGTYPE_REGISTER |
TF-SCT | #REGTYPE_STRUCT |
TF-PER | #REGTYPE_LOGPERIOD |
TF-DAY | #REGTYPE_DAILY |
TF-EVT | #REGTYPE_EVENT |
TF-NEVT | #REGTYPE_NEWEVENT |
TF-SYS | #REGTYPE_SYSTEM |

Use of the correct [/DATA TYPE] option is important for non-floating point data items. If the incorrect data type is used the read / write of the data item will result in invalid or corrupt data.

An example register address is "RG:0.8.1/TF-SWORD". Register read command, Application zero (0), array eight (8), register one (1) with a data type of TF-SWORD (16-bit integer) will read back the year number from the RTU's clock.

Trend Addressing

The general syntax for reading trend data configured within a Totalflow RTU is:

<Command Code>:<Trend File>:<Attribute>

<Command Code>

Indicates to the VTScada driver which Totalflow command is to be used when reading a data item from a Totalflow RTU. For Trend addressing, the <Command Code> must be set to "TR".

<Trend File>

Indicates to the VTScada driver which trend file is targeted when reading a data item from a Totalflow RTU.

<Attribute>

This indicates to the VTScada driver which specific data field in a data structure is targeted when reading a data item from a Totalflow RTU.

Accessing Legacy Data Structures

The "C" style data structures in a Totalflow RTU can be accessed directly based on the known field name and fixed data type of each data field. Access to the various types of structures is controlled by the Function Code specified in the I/O address.

There are several categories of Function Codes provided for mapping tag data and historical data to VTScada.

VTScada Driver Function Code Totalflow Function VTScada Driver Description
CM Read Current Measurement

Used to obtain instantaneous / real-time flow data for a meter run in the RTU including real-time analysis data. This function code would, for example, be used with Analog Input or Analog Status tags.

The Read Current Measurement command is capable of accessing the contents of the ARCH_FCU_ORIF_CURRENT structure for an Orifice Meter Run, the ARCH_FCU_LIQ_CURRENT structure for a Liquid Meter Run, the ARCH_FCU_TURB_CURRENT for a Pulse/PD/Turbine Meter Run and the associated ANALYSIS_RECORD structure for each meter run and access to the ARCH_FCU_HEADER structure for the meter run.

When a read function is used on a VTScada input tag using the "CM" command code, the driver will use the Read Current Measurement command to acquire all the instantaneous data from the RTU for the specified meter run. No write function is supported.

The Read Current Measurement command is not selective with respect to the data retrieved from the RTU. The above structures are retrieved subject to the meter run requested and the type of meter run configured in the RTU.

The Read Current Measurement command has the advantage of allowing the VTScada driver to acquire all the available instantaneous measurement data from the RTU for a meter run with one request and it is simple to configure tag I/O addresses as no register mapping is required. However, as the response to the Read Current Measurement command from the RTU includes all instantaneous data, it can be less efficient with respect to communication bandwidth consumption than using Register access (refer to next section).

AL Read Current Alarms

Used to obtain instantaneous/real-time alarm information for a meter run in the RTU. This function code would, for example, be used with IO tags in the Digital mode, Digital Input or Digital Status tags.

Current Alarm data is returned in the TAI_ALARM_POLL_INFO structure. The alarms are returned in the fcu_alarms[4] field which contains packed bits.

When a read function is used on a VTScada input tag using the "AL" command code, the driver will use the Read Current Alarms command to acquire all the instantaneous alarm bit data from the RTU for the meter run specified. No write function is supported.

Each distinct alarm is accessed by bit number for a specified meter run.

DS Read Device Setup

Used to read a meter run configuration parameter value from the RTU. This function code would be used with analog tags for read functions.

The Read Device Setup command is capable of accessing the contents of the ARCH_FCU_ORIF_SETUP, the ARCH_FCU_LIQ_SETUP and the ARCH_FCU_TURB_SETUP structures and the associated ANALYSIS_RECORD structure for each meter run and access to the ARCH_FCU_HEADER structure for the meter run.

The Read Device Setup command returns a large number of data fields for each meter type when performing a read function. When a read function is used on a VTScada input tag using the "DS" command code, the driver will use the Read Device Setup command to acquire the entire meter run configuration from the RTU for the specified meter run.

The Read Device Setup command can be useful for monitoring / viewing meter run configuration; however the Write Device Setup command requires a number of output tags to function correctly. The RTU vendor provided tool, PCCU is better suited to maintain meter run settings.

DS Write Device Setup

Used to write meter run parameter values in the RTU. This function code would be used with analog tags for write functions.

The Write Device Setup command is capable of accessing the contents of the ARCH_FCU_ORIF_SETUP, the ARCH_FCU_LIQ_SETUP and the ARCH_FCU_TURB_SETUP structures and the associated ANALYSIS_RECORD structure for each meter run.

When a write function is used on a VTScada output tag using the "DS" command code, the VTScada driver will first perform a Read Device Setup command to obtain the current settings, update the changed setting and then perform a Write Device Setup command.

The Write Device Setup command requires a number of output tags to function correctly. The RTU vendor provided tool, PCCU is better suited to maintain meter run and RTU settings.

GA Write Gas Analysis

Used to write new analysis data to a specified meter run in the RTU.

The Write Gas Analysis command is capable of accessing the contents of the ANALYSIS_RECORD structure in each meter run of the RTU. There is no equivalent read function except for the Read Current Measurement command.

When a write function is used on a VTScada output tag using the "GA" command code, the VTScada driver will first perform a Read Current Measurement command to obtain the current settings, update the changed setting in the ANALYSIS_RECORD structure and then perform a Write Gas Analysis command against the RTU for the specified meter run.

HS Read History

Used to read/upload archive records from the RTU consisting of flow data and events. History archives in the RTU are based on the contents of the ARCH_FCU_DAILY, the ARCH_FCU_LOGPER and the ARCH_FCU_EVENT structures representing daily and periodic flow records and RTU/meter event logs.

The Read History command can acquire history records based on several criteria. The VTScada Totalfow driver uses a set number of days in the past to acquire historical data for a specified meter run. Daily, Periodic and Event records are acquired whenever the Read History command is used.

Tags with the "HS" command code will trigger the Read History command. The update frequency for tags using this command code should not be frequent owning to the amount of data uploaded and the consumption of bandwidth.

The VTScada Totalflow driver maintains context of the most recent date/time of an historical record obtained from the RTU. This context information is used to only store newer data for a meter run into the VTScada historian when historical data is collected from the RTU.

DT Write Date and Time

Used to set the clock in the RTU. The Write Date and Time command writes the current clock of computer (on which the VTScada Totalflow driver is running) to the RTU. The command is not meter run specific.

No read function is available from the vendor and thus a direct read of the RTU clock is not available. However, individual clock component values can be read from the RTU using Register access.

RE Write Reset Events

Used to reset the event archives in the RTU by means of a write function.

The Write Reset Events command resets the event queue in the RTU. This command is a destructive command with respect to event data meaning that when used, event data stored in the RTU will no longer be retrievable.

When a write function is used on a VTScada output tag using the "RE" command code, the VTScada driver execute the Write Reset Events command against the RTU for the specified meter run.

RV Write Reset Volume

Used to reset accumulated volume counters. Some volume counters in Totalflow RTUs support this command and will reset; however, some counters in the RTU are never reset – this behavior is defined by the Totalflow RTU, not the VTScada Totalflow driver.

The Write Reset Volume command is a destructive command with respect to certain accumulator data meaning that when used, accumulators stored in the RTU will be reset to 0 (zero)

Accessing Registers

VTScada Driver Function Code Totalflow Function VTScada Driver Description
RG Read Registers

Used to read a specific data item in the RTU with a particular data type.

The register parameter values (Application, Array, Index) depend on the specific application configured in the RTU by the programmer using the Totalflow PCCU software tool.

When a read function is used on a VTScada input tag using the "RG" command code, the VTScada driver will perform a Read Registers command to obtain the data item. The driver will coalesce multiple tag addresses into register blocks for more efficient reading where sequential Application, Array, Index values are used.

ABB documentation for various RTU models and applications provides registers maps.

RG Write Registers

Used to write a specific data item in the RTU with a particular data type.

The register parameter values (Application, Array, Index) depend on the specific application configured in the RTU by the programmer using the Totalflow PCCU software tool.

When a write function is used on a VTScada output tag using the "RG" command code, the VTScada driver will perform a Write Registers command to set the data item.

ABB documentation for various RTU models and applications provides registers maps.

Accessing Trends

There is only one category of Function Code provided for mapping tag data and historical data to VTScada using the trend mapping approach.

VTScada Driver Function Code Totalflow Function VTScada Driver Description
TR Read Trends

Used to read a specific data item in the RTU.

The trend parameter values (Trend File, Attribute) depend on the specific trends configured in the RTU by the programmer using the Totalflow PCCU software tool.

When a read function is used on a VTScada input tag using the "TR" command code, the VTScada driver will perform a Read Trend command to obtain the data item. The driver will coalesce multiple tag addresses into trend blocks for more efficient reading where multiple values are used.

Read Current Measurement

VTScada Driver Tag I/O Address Format VTScada Driver Address Description
CM:<#>:<ATTRIBUTE>

String, where...

CM specifies the use of the Read Current Measurement command followed by a colon ":" character;

<#> specifies a one or two digit integer Run/Tube Number in the RTU followed by a colon ":" character;

<ATTRIBUTE> is a multi-character string that specifies the Totalflow "C" style data structure field name.

There are variations between each data structure returned by the Read Current Measurement command, but many field names are common amongst the different meter run types. For example, the data field fLVPVolume maintains the instantaneous accumulated volume on a meter run. The data field is common to all three meter types (Orifice, Turbine, Liquid) supported by Totalflow RTUs.

A VTScada tag address specified as " CM:1:fLVPVolume " would return the current accumulated volume for meter run #1 in a Totalflow RTU, regardless of the meter type.

Array fields within the data structures are not directly accessible using the CM function code. For example, in the ARCH_FCU_ORIF_CURRENT structure, the field " fLVPAlarms[3] " (an array of 3 characters) is not accessible. Alarm data must be accessed using the AL function code.

The ANALYSIS_RECORD substructure of any meter run can be read using the CM function code or written using the GA function code.

A VTScada tag address specified as " CM:2:fEthane " would return the current analysis setting of Ethane for meter run #2 in the RTU. A tag address of " GA:2:fEthane " would be used on an output tag to write the Ethane value for meter run #2 in the RTU.

The available <ATTRIBUTE> settings for the Read Current Measurement command are based on the contents of the following structures (the definition each structure is are provided by the RTU vendor and documented in the Totalflow Archive Interface):

  • ARCH_FCU_ORIF_CURRENT - Orifice Meter Run
  • ARCH_FCU_LIQ_CURRENT - Liquid Meter Run
  • ARCH_FCU_TURB_CURRENT - Pulse/PD/Turbine Meter Run
  • ARCH_FCU_HEADER - General meter run information applicable to each meter type
  • ANALYSIS_RECORD - Nested structure included in the structure of each meter type

Each data field in the structures outlined is available to the VTScada Totalflow driver with the exception of array based fields which contain non-character packed data such as " fLVPAlarms[3] ". Arrays containing character data can be retrieved as strings.

Orifice Meter Run

ARCH_FCU_ORIF_CURRENT, ANALYSIS_RECORD – these structures are retrieved for orifice meter runs and contain the instantaneous measurement data at the moment it is read from the RTU. The data includes aspects of the orifice meter run such as numerous factors for the AGA flow rate calculation, current telemetry values for meter run inputs such as differential pressure, temperature and flowing pressure, current flow rate / accumulators and gas analysis values.

typedef struct arch_orif_current_t
{   UCHAR ucDataSetID;            // Data Structure Identifier = 81
    USHORT nRecentMeasRevision;   // CCU org routines set this to - 1 for OLD meters
    float fLVPDP;                 //Differential Pressure
    float fLVPAP;                 //Absolute Pressure
    float fLVPTf;                 //Flowing Temperature
    float fLVPVolume;             //Volume (MCF) - converted by CCU
    float fLVPExt;
    float fLVPCP;
    float fLVPY;
    float fLVPFpv;
    float fLVPFw;
    float fLVPFaux;
    ULONG fLVPIrange;
    ULONG fLVPIcounts;
    float fLVPQv;
    UCHAR fLVPAlarms[3];
    ANALYSIS_RECORD LVPAnalysis;
    float fCurAP;
    float fCurDP;
    float fCurTf;
    float fCurFlow;               // MCF per day , converted by CCU
    float fYstAccVol;             // MCF
    float fCurAccVol;             // MCF
    float fCurVoltage;            // end of common vars between 1985 and 1992
                       // calculation data structures
    float fLVPFb;                 // this block of variables is used for
    float fLVPFr;                 // meters using 1985 volume calcs
    float fLVPFpb;
    float fLVPFtb;
    float fLVPFtf;
    float fLVPFg;
    float fLVPFa;
    float fLVPFip;                // this block of variables is used for
    float fLVPEv;                 // meters using 1992 volume calcs
    float fLVPCorrOrifice;
    float fLVPCorrPipe;
    float fLVPRhob;
    float fLVPQm;
    float fLVPCd;
} ARCH_FCU_ORIF_CURRENT;

typedef struct
{   float fBTU;
    float fGravity;
    float fN2;
    float fCO2;
    float fH2S;
    float fH2O;
    float fHelium;
    float fMethane;
    float fEthane;
    float fPropane;
    float fNButane;
    float fIButane;
    float fNPentane;
    float fIPentane;
    float fNHexane;
    float fNHeptane;
    float fNOctane;
    float fNNonane;
    float fNDecane;
    float fOxygen;
    float fCO;
    float fHydrogen;
    float fArgon;
} ANALYSIS_RECORD;

Turbine Meter Run

ARCH_FCU_TURB_SETUP, ANALYSIS_RECORD – these structures are retrieved for turbine meter runs and contain the meter run configuration data. The data includes aspects of the orifice meter run such as contract/base pressure and temperature for the AGA flow rate calculation, compressibility calculation method, meter factor, contract hour and many other settings. It is recommended that the RTU vendor’s programming software be used to maintain the configuration of Totalflow RTUs. Nonetheless, certain settings can be maintained using the VTScada Totalflow driver. For example, gas analysis components.

The ANALYSIS_RECORD structure is identical for all meter run types.

typedef struct
{
  UCHAR   DataSetID;             // Data Structure Identifier = 82
  USHORT  nDeviceSetupRevision; // CCU org routines set this to -1 for OLD meters
  BOOL1   bPasswordMode;
  USHORT  nLastLoginTag;
  BOOL1   bCheckSecCode;
  UCHAR   ucPrimaryElement;
  USHORT  nPrimaryElementMask;
  UCHAR   ucVolCalcMethod;
  USHORT  nVolCalcMethodMask;
  UCHAR   ucReportUnits;
  USHORT  nReportUnitsMask;
  UCHAR   ucCalcUnits;
  USHORT  nCalcUnitsMask;
  UCHAR   ucZMethod;
  USHORT  nZMethodMask;
  UCHAR   ucDispRate;
  UCHAR   ucCdisp;
  UCHAR   ucUdisp;
  ULONG   ulVolumeLogPeriod;
  USHORT  nVolumeCalcPeriod;
  USHORT  nFlowPeriod;
  UCHAR   ucContractHour;
  float   fTBase;
  float   fPBase;
  float   fRsph;
  float   fViscosity;
  float   fFt;
  float   fFp;
  float   fBarop;
  float   fFaux;
  BOOL1   bUseFtc;
  BOOL1   bUseFpc;
  BOOL1   bUseS;
  BOOL1   bUseFaux;
  float   fAPLowLimit;
  float   fAPHiLimit;
  float   fAPLowCalibration;
  float   fAPMidLowCalibration;
  float   fAPMidCalibration;
  float   fAPMidHiCalibration;
  float   fAPHiCalibration;
  BOOL1   bUseMeasuredAP;
  float   fFixedAP;
  float   fK;
  BOOL1   bRTDInstalled;
  BOOL1   bUseMeasTemp;
  float   fFixedTf;
  float   fTempBias;
  float   fTfLowLimit;
  float   fTfHiLimit;
  float   fFlowLowLimit;
  float   fFlowHiLimit;
  float   fAcfLowLimit;
  float   fAcfHiLimit;
  BOOL1   bLCContact1;
  BOOL1   bAPLowContact1;
  BOOL1   bAPHighContact1;
  BOOL1   bACFLowContact1;
  BOOL1   bACFHighContact1;
  BOOL1   bRemSenseContact1;
  BOOL1   bVolSetpointContact1;
  float   fVolumeSetpoint;
  BOOL1   bAutoResetContact1;
  BOOL1   bStreamAttached;
  ULONG   ulStreamID;
  BOOL1   bFixedAxOnError;
  BOOL1   bFirstAnalysis;
  ANALYSIS_RECORD FixedAnalysis;
  BOOL1   bTfLowContact1;
  BOOL1   bTfHighContact1;
  BOOL1   bFlowLowContact1;
  BOOL1   bFlowHighContact1;
  BOOL1   bLCContact2;
  BOOL1   bACFLowContact2;
  BOOL1   bACFHighContact2;
  BOOL1   bAPLowContact2;
  BOOL1   bAPHighContact2;
  BOOL1   bRemSenseContact2;
  BOOL1   bVolSetpointContact2;
  float   fVolumeSetpoint2;
  BOOL1   bAutoResetContact2;
  BOOL1   bTfLowContact2;
  BOOL1   bTfHighContact2;
  BOOL1   bFlowLowContact2;
  BOOL1   bFlowHighContact2;
  BOOL1   bHVSelect;
} ARCH_FCU_TURB_SETUP;

Liquid Meter Run

ARCH_FCU_LIQ_SETUP, ANALYSIS_RECORD – these structures are retrieved for liquid meter runs and contain the meter run configuration data. The data includes aspects of the orifice meter run such as contract/base pressure and temperature for the AGA flow rate calculation, low flow cutoff, compressibility calculation method, meter factor, contract hour and many other settings. It is recommended that the RTU vendor’s programming software be used to maintain the configuration of Totalflow RTUs. Nonetheless, certain settings can be maintained using the VTScada Totalflow driver. (For example, gas analysis components.)

The ANALYSIS_RECORD structure is identical for all meter run types.

typedef struct
{
  UCHAR DataSetID;          // Data Structure Identifier = undefined
  USHORT nCurrMeasRevision; // CCU org routines set this to -1 for OLD meters
  BOOL1 bPasswordMode;
  USHORT nLastLoginTag;
  BOOL1 bCheckSecCode;
  UCHAR ucBaudRate;
  UCHAR ucParity;
  UCHAR ucStopBits;
  UCHAR ucDataBits;
  UCHAR ucPrimaryElement;
  USHORT nPrimaryElementMask;
  UCHAR ucVolCalcMethod;
  USHORT nVolCalcMethodMask;
  UCHAR ucReportUnits;
  USHORT nReportUnitsMask;
  UCHAR ucCalcUnits;
  USHORT nCalcUnitsMask;
  ULONG ulVolumeLogPeriod;
  USHORT nVolumeCalcPeriod;
  UCHAR ucContractHour;
  float fOrificeSize;
  float fPipeSize;
  float fViscosity;
  BOOL1 bMonelOrifice;
  float fZeroCutoff;
  BOOL1 bUseFb;
  BOOL1 bUseFr;
  BOOL1 bUseFg;
  BOOL1 bUseFa;
  BOOL1 bUseFaux;
  float fFaux;
  float fK0;
  float fE;
  float fVcfK0;
  float fVcfK1;
  float fVcfK2;
  float fLiqGravity;
  BOOL1 bAPPresent;
  UCHAR ucFlowUnits;
  UCHAR ucDailyUnits;
  UCHAR ucHourlyUnits;
  UCHAR ucLiquidType;
  float fDPLowLimit;
  float fDPHiLimit;
  float fDPLowCalibration;
  float fDPMidLowCalibration;
  float fDPMidCalibration;
  float fDPMidHiCalibration;
  float fDPHiCalibration;
  float fAPLowLimit;
  float fAPHiLimit;
  float fAPLowCalibration;
  float fAPMidLowCalibration;
  float fAPMidCalibration;
  float fAPMidHiCalibration;
  float fAPHiCalibration;
  float fTfLowLimit;
  float fTfHiLimit;
  BOOL1 bRTDInstalled;
  BOOL1 bUseMeasTemp;
  float fFixedTf;
  float fTempBias;
  BOOL1 bLCContact1;
  BOOL1 bDPLowContact1;
  BOOL1 bDPHighContact1;
  BOOL1 bAPLowContact1;
  BOOL1 bAPHighContact1;
  BOOL1 bRemSenseContact1;
  BOOL1 bAutoResetContact1;
  BOOL1 bVolSetpointContact1;
  float fVolumeSetpoint1;
  ANALYSIS_RECORD FixedAnalysis;
    // extension of record for new database
  float fFlowLowLimit;     // Flow Rate Low Limit
  float fFlowHighLimit;    // Flow Rate High Limit
  BOOL1 bTfLowContact1;    // Trip contact on TF low
  BOOL1 bTfHighContact1;   // Trip contact on TF high
  BOOL1 bFlowLowContact1;  // Trip contact on FlowRate low
  BOOL1 bFlowHighContact1; // Trip contact on FlowRate high
  BOOL1 bLCContact2;
  BOOL1 bDPLowContact2;
  BOOL1 bDPHighContact2;
  BOOL1 bAPLowContact2;
  BOOL1 bAPHighContact2;
  BOOL1 bRemSenseContact2;
  BOOL1 bAutoResetContact2;
  BOOL1 bVolSetpointContact2;
  float fVolumeSetpoint2;
  BOOL1 bTfLowContact2;    // Trip contact on TF low
  BOOL1 bTfHighContact2;   // Trip contact on TF high
  BOOL1 bFlowLowContact2;  // Trip contact on FlowRate low
  BOOL1 bFlowHighContact2; // Trip contact on FlowRate high
} ARCH_FCU_LIQ_SETUP;

Write Gas Analysis

This type of address should only be used on output only tags. Gas Analysis values can be read using Device Setup, Current Measurement, and Read Register addresses.

VTScada Driver Tag I/O Address Format VTScada Driver Address Description
GA:<#>:<ATTRIBUTE>

String where...

GA specifies the use of the Write Gas Analysis command followed by a colon ":" character;

<#> specifies a one or two digit integer Run/Tube Number in the RTU followed by a colon ":" character;

<ATTRIBUTE> is a multi-character string that specifies the Totalflow "C" style data structure field name.

The ANALYSIS_RECORD substructure of any meter run can be written using the GA function code. A VTScada tag address specified as " GA:2:fEthane " would write the current analysis setting of Ethane for meter run #2 in the RTU from the output tag value.

Note: a Read Current Measurement command is used to read the current settings for the meter run prior to the write function.

The available <ATTRIBUTE> settings for the Write Gas Analysis command are based on the contents of the following structures (the definition each structure is provided by the RTU vendor and documented in the Totalflow Archive Interface)

typedef struct
{ float fBTU;
  float fGravity;
  float fN2;
  float fCO2;
  float fH2S;
  float fH2O;
  float fHelium;
  float fMethane;
  float fEthane;
  float fPropane;
  float fNButane;
  float fIButane;
  float fNPentane;
  float fIPentane;
  float fNHexane;
  float fNHeptane;
  float fNOctane;
  float fNNonane;
  float fNDecane;
  float fOxygen;
  float fCO;
  float fHydrogen;
  float fArgon;
} ANALYSIS_RECORD;

Read History

VTScada Driver Tag I/O Address Format VTScada Driver Address Description
HS:<#>:<ATTRIBUTE>

String, where...

HS specifies the use of the Read History By Days command followed by a colon ":" character;

<#> specifies a one or two digit integer Run/Tube Number in the RTU followed by a colon ":" character;

<ATTRIBUTE> is a multi-character string that specifies the Totalflow "C" style data structure field name. T

here are variations between each data structure returned by the Read History command, depending on the historical record type being accessed. The records do not vary by meter run type. A few field names are common between the Daily and Periodic flow records. For example, the " fVolume " field is common to all meters for flow records.

A VTScada tag address specified as " HS:3:DAILY:fVolume " would return the most recent contract day accumulated flow on meter run #3 in a Totalflow RTU, regardless of the meter type.

Similarly, an address of " HS:2:LOGPER:fVolume " would access the Periodic Archive records for run 2 and the "Total Volume for period (MCF)". The period is dependent on the specific RTU settings.

Array fields within the data structures are not directly accessible using the HS function code.

Possible strings: DAILY, LOGPER, ALARMLOG, EVENT, NEWEVENT

The available <ATTRIBUTE> settings for the Read History command are based on the contents of the following structures (the definition each structure is are provided by the RTU vendor and documented in the Totalflow Archive Interface):

  • ARCH_FCU_DAILY - Daily flow record
  • ARCH_FCU_LOGPER - Periodic flow record (typically hourly)
  • ARCH_FCU_ALARMLOG - Alarms log record
  • ARCH_FCU_EVENT - RTU/Meter Run event record
  • ARCH_FCU_NEW_EVENT - RTU/Meter Run new event record
  • ARCH_FCU_HEADER - General meter run information applicable to each meter type

typedef struct {
  BYTE       bVerCode;
  BYTE       bDirection;
  UINT16     nSequence;
  UINT16     nDataType;
  INT16      nFormat;
  __time64_t time;
  BYTE       Value[8];
  BYTE       Limit[8];
  char       cMessage[65];
  BYTE       spare;
} ARCH_FCU_ALARMLOG;

typedef struct
{
  TFTime DateTime;        //Date and time
  USHORT nSequence;       //Sequence number;
  USHORT nLastEvtSeq;     //Last Event Sequence number
  USHORT nLPStartSeq;     //Log Period Starting Sequence;
  USHORT nLPEndSeq;       //Log Period End sequence
  UCHAR ucContractHour;   //Contract hour
  float fExtension;       //Average Extension
  float fVolume;          //Total Volume for day (MCF)
  float fEnergy;          //Total Energy for day
  ULONG ulFlowTime;       //Flow seconds for the day
  ULONG ulBackFlow;       //Back flow seconds for the day
  ULONG ulTotalDailyTime; //Log period seconds
  UCHAR ucAlarms[3];      //Alarms - bit encoded
  float fpAP;             //Average AP
  float fMinAP;           //Minimum AP
  float fMaxAP;           //Maximum AP
  float fPerctAPLow;      //Percent of day below low limit
  float fPerctAPHigh;     //Percent of day above high limit
  float fpDP;             //Average DP
  float fMinDP;           //Minimum DP
  float fMaxDP;           //Maximum DP
  float fPerctDPLow;      //Percent of day below low limit
  float fPerctDPHigh;     //Percent of day above high limit
  float fpTf;             //Average Tf
  float fMinTf;           //Minimum Tf
  float fMaxTf;           //Maximum Tf
  float fPerctTfLow;      //Percent of day below low limit
  float fPerctTfHigh;     //Percent of day above high limit
  UCHAR ucVerCode;        //Verification code
  long lArchSeq;          //Archive Sequence number
  long lArchLPStart;      //Archive Log Period Start
  long lArchLPEnd;        //Archive Log Period End
} ARCH_FCU_DAILY;

typedef struct
{
  TFTime DateTime;    //Date and time
  USHORT nSequence;   //Sequence number
  float fpDP;         //Fixed Point Differential Pressure
  float fpAP;         //Fixed Point Absolute Pressure
  float fpTf;
  float fpExtension;  //Fixed Point Extension
  float fVolume;      //Total Volume for period (MCF)
  float fEnergy;      //Total Energy for period
  SHORT nFlowTime;    //Seconds flow time for period
  USHORT nTotalLogPerTime; //Total seconds in period
  UCHAR ucAlarms[3];  //Alarms - bit encoded
  UCHAR ucVerCode;
  long lArchSeq;
} ARCH_FCU_LOGPER;

typedef struct
{
  TFTime DateTime;  // Date and time
  UCHAR ucFlags;    // flags byte (4 lsb - fcu; 4 msb - ccu)
  USHORT nSequence; // sequence number
  USHORT nCode;     // event code
  EVENT_VALUE val;  // event old/new value
  UCHAR ucVerCode;  // verification code
  long lArchSeq;
} ARCH_FCU_EVENT;

typedef struct
{
  __time32_t Time;
  BYTE Flags;
  UINT16 SeqNumber;
  UINT16 eCode;
  BYTE OldValue1[4];
  BYTE NewValue1[4];
  BYTE vCode1;
  BYTE revision;
  BYTE DataType;
  BYTE UnitGroupID;
  char OperatorName[32];
  char PointName[65];
  char OldValue2[65];
  char NewValue2[65];
  BYTE vCode2;
} ARCH_FCU_NEW_EVENT;


ABB Totalflow Error Codes

VTScada TCI COM wrapper errors:

Error code (Decimal) | Error code (Hex) | Meaning
10485761 | 0XA00001 | COMClient() failed to instantiate the TCICOM
10485762 | 0XA00002 | Failed to open a socket
10485763 | 0XA00003 | Connection attempts exceeded Max retries
10485764 | 0XA00004 | DB1_FCU and DB1_FCU_VCI are not supported
10485765 | 0XA00005 | DB2_TREND's TF_DATATYPE_TREND_CFG and TF_DOWNLOAD_TRENDDEL are not supported
10485766 | 0XA00006 | OrganizeFCUPoll failed to create an archive
10485767 | 0XA00007 | OrganizeFCUSetup failed to create an archive
10485768 | 0XA00008 | OrganizeFCUAlarms failed to create a TAI_ALARM_POLL_INFO
10485769 | 0XA00009 | OrganizeFCUCollect failed to create an archive
10485770 | 0XA0000A | OrganizeRegisterData failed to create an archive
10485771 | 0XA0000B | OrganizeTrendData failed to create an archive
10485772 | 0XA0000C | ProcessTrendDirectory failed acquire enough memory
10485773 | 0XA0000D | Post-OrganizeTrendData: unhandled data type
10485774 | 0XA0000E | Failed to build a request
10485775 | 0XA0000F | A Windows library call failed
10485776 | 0XA00010 | Fields and Values to be written should not be empty
10485777 | 0XA00011 | Field name empty or wrong
10485778 | 0XA00012 | Field value empty or does not fit the type of the structure member
10485779 | 0XA00013 | Specified type is wrong or does not match the specified register
10485780 | 0XA00014 | NumRegisterSets should be in [1-64]
10485781 | 0XA00015 | Failed to allocate the requested RegisterSets
10485782 | 0XA00016 | Failed to allocate memory
10485783 | 0XA00017 | A call to TrendRecord failed
10485784 | 0XA00018 | Socket connect failed

CPC Errors:

Error code (Decimal) | Error code (Hex) | Meaning
40966 | 0xA006 | Unable to allocate a memory buffer
40967 | 0xA007 | Received data had a Frame Check Sequence (FCS) error
40968 | 0xA008 | Received data had a CRC error
40969 | 0xA009 | Device did not respond or Receive buffer read error
40970 | 0xA00A | Data download not acknowledged
40972 | 0xA00C | Request type not supported
40974 | 0xA00E | Invalid workstation ID
40975 | 0xA00F | Transaction Ids did not match
40976 | 0xA010 | Missing previous packet
40977 | 0xA011 | Incorrect block size received
40978 | 0xA012 | Incorrect block number received
40979 | 0xA013 | Request/response out of sync
40980 | 0xA014 | Received NAK from remote device
40981 | 0xA015 | Communication failed between packets
40986 | 0xA01A | Character timeout
40988 | 0xA01C | Busy or Incorrect security code
40989 | 0xA01D | Forced timeout or Message framing error
41060 | 0xA064 | General remote NAK error
41061 | 0xA065 | Bad X-header length
41062 | 0xA066 | Bad X-header CRC
41063 | 0xA067 | Bad X-record length
41064 | 0xA068 | Bad X-record CRC
41065 | 0xA069 | Invalid header type
41066 | 0xA06A | Invalid operation
41067 | 0xA06B | Invalid method
41068 | 0xA06C | Invalid data structure
41069 | 0xA06D | Invalid transmit packet number
41070 | 0xA06E | Invalid data block number
41071 | 0xA06F | Invalid Event sequence number
41072 | 0xA070 | Invalid day sequence number
41073 | 0xA071 | Invalid log sequence number
41074 | 0xA072 | Invalid transmit packet size
41075 | 0xA073 | Insufficient buffer available
41076 | 0xA074 | Insufficient access privilege
41077 | 0xA075 | Invalid state for operation
41078 | 0xA076 | Database already locked
41079 | 0xA077 | Invalid configuration record
41080 | 0xA078 | Invalid partition record
41081 | 0xA079 | Invalid Comm setup record
41082 | 0xA07A | Invalid command record
41083 | 0xA07B | Invalid calibration record
41084 | 0xA07C | Invalid date/time record
41085 | 0xA07D | Invalid analysis
41086 | 0xA07E | Illegal register read or write
41087 | 0xA07F | Unable to wait for frame
41088 | 0xA080 | Unable to wait for Id during download
41090 | 0xA082 | No application type for remote protocol switch
41091 | 0xA083 | Invalid protocol switch type
41092 | 0xA084 | GELCOM already in use
41093 | 0xA085 | Invalid request for multi-host
41094 | 0xA086 | Attempt to read/write Gello application structure
41095 | 0xA087 | X protocol terminating
41096 | 0xA088 | X-Frame already in use
41110 | 0xA096 | Invalid application slot
41111 | 0xA097 | Invalid VCB array
41112 | 0xA098 | Invalid VCB start and/or index 152
41113 | 0xA099 | Invalid VCB start and/or index 153
41114 | 0xA09A | Event inhibit for Canadian events
41115 | 0xA09B | File not found
41116 | 0xA09C | File already exists
41117 | 0xA09D | Insufficient free space
41118 | 0xA09E | File read error
41119 | 0xA09F | File write error
41120 | 0xA0A0 | File create error
41121 | 0xA0A1 | File delete error
41122 | 0xA0A2 | File rename error
41123 | 0xA0A3 | Memory access fault
41124 | 0xA0A4 | Invalid Units file
41125 | 0xA0A5 | Invalid display file
41127 | 0xA0A7 | Invalid constants file
41128 | 0xA0A8 | Device received SYNC instead of ACK
41214 | 0xA0FE | Operator name is required
41215 | 0xA0FF | Operator authentication failed

Errors occurred in and reported by the flow computer:

Error code (Decimal) | Error code (Hex) | Meaning
-2147024809 |  | One or more arguments are not valid
-2147024882 |  | Failed to allocate necessary memory
-2147024890 |  | Handle that is not valid
-2147024891 |  | General access denied error
-2147418113 |  | Unexpected failure
-2147467259 |  | Unspecified failure
-2147467260 |  | Operation aborted
-2147467261 |  | Pointer that is not valid
-2147467262 |  | No such interface supported
-2147467263 |  | Not implemented
001 | 0x1 | Net server access error
002 | 0x2 | Modem init error
003 | 0x3 | Communications request denied
004 | 0x4 | Communications link failed
005 | 0x5 | Transmit fail
006 | 0x6 | Unable to allocate buffer
007 | 0x7 | Receive buffer FCS error
008 | 0x8 | Receive buffer CRC error
009 | 0x9 | Receive buffer read error
010 | 0xa | Receive download NACK
011 | 0xb | WR MBX error
012 | 0xc | Not supported
015 | 0xf | Error in trans Id
016 | 0x10 | Error missing previous packet
017 | 0x11 | Error block size did not match
018 | 0x12 | Error block number did not match
019 | 0x13 | Error out of sync
020 | 0x14 | Receive NACK
021 | 0x15 | Comm fail packets
026 | 0x1a | Error char timeout
027 | 0x1b | Maximum transaction timeout
028 | 0x1c | Busy or wrong SCode
029 | 0x1d | Message framing error
030 | 0x1e | Slave address mismatch
0 | 0x00 | No error
42 | 0x2A | Comm channel unavailable
43 | 0x2B | Bad write address
32768 | 0x8000 | Service transmit timeout
32769 | 0x8001 | Service receive timeout
32770 | 0x8002 | Service socket timeout
32771 | 0x8003 | XML create error
32772 | 0x8004 | XML parse error
32773 | 0x8005 | Invalid request error
32774 | 0x8006 | Invalid datum address error
32775 | 0x8007 | Command result error
32776 | 0x8008 | Unknown Totalflow CPC error
32777 | 0x8009 | Invalid license
32784 | 0x8010 | License expired
32785 | 0x8011 | Unknown license error
32787 | 0x8013 | No error report from the TCICOM

Windows errors:

Error code (Decimal) | Error code (Hex) | Meaning
-2147467260 | 0x80004004 | #E_ABORT - Operation aborted
-2147024891 | 0x80070005 | #E_ACCESSDENIED - General access denied error
-2147467259 | 0x80004005 | #E_FAIL - Unspecified error
-2147024890 | 0x80070006 | #E_HANDLE - Invalid handle
-2147024809 | 0x57 | #E_INVALIDARG - The parameter is incorrect
-2147467262 | 0x80004002 | #E_NOINTERFACE - No such interface supported
-2147467263 | 0x80004001 | #E_NOTIMPL - Not implemented
-2147024882 | 0xe | #E_OUTOFMEMORY - Not enough memory resources
-2147467261 | 0x80004003 | #E_POINTER - Invalid pointer
-2147418113 | 0x8000ffff | #E_UNEXPECTED - Catastrophic failure


Allen-Bradley Driver

Deprecated.
Existing Allen Bradley tags in legacy applications will always continue to work, but the Rockwell Driver Tag should be used for all new development.

Not counted towards your tag license limit.

The Allen-Bradley driver provides an interface to an Allen-Bradley PLC, allowing communication via one of:

  • Serial port
  • KT/SD I/O board
  • TCP/IP

Configuration options that are not relevant to the selected mode are disabled.

If using a Rockwell CompactLogix or ControlLogix PLC, use the CIP driver.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Allen Bradley drivers use the following standard ports, although variations may be found:

AB CIP | TCP | 44818
AB EIP | TCP | 2222 or 44818

Reference Notes:

Allen Bradley devices can collect data between polls. To access this data with either a VTScada Analog Status or Digital Status tag, configure the "History Address" edit field with the location in the PLC of the logged data value using the format:

DLx:y

where "x" is the queue number (between 0 and 255) and "y" is the field in the queue where the data value is being logged (between 3 and 11 because 1 is reserved for the date and 2 for the time).

Example:

The PLC is configured to log values of addresses T4:5.ACC and T4:6.ACC into fields 3 and 4 of queue 0 once every minute.

To configure an Analog Status tag to read the current value of address T4:6.ACC from the PLC every 10 minutes and to read its logged values every hour, the following needs to be set in the "I/O" tab of the Analog Status tag's configuration:

Address = T4:6.ACC,

Scan Interval = 600,

History Address = DL0:4,

History Scan Interval = 3600

This driver also has the ability to save the last value written to each output tag, and to rewrite those values, either automatically when lost communications are restored, or manually by the press of a button. Carefully review the information in the Type tab to decide whether this feature should be used in your application.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Related information:

Allen-Bradley Driver I/O Addressing - I/O address formats.

Allen Bradley Error Codes

Communication Driver Log-Enabled Variables - Log Enabled Variables.

Best Practices for Tags

Important Notes

When configuring the data-logging feature on the PLC:

  • Make sure that both date and time stamps are being logged into the relevant queues.
  • Failure to configure a queue in this manner will result in the Allen Bradley Driver tag simply ignoring all records from that particular queue. This behavior is by design because a list of logged values without time stamps is of little value.
  • Make sure that a real-time clock is present and enabled in the PLC.
  • For the same reason as above, if a real-time clock in not present in the PLC or if it is present but not enabled, the driver tag will ignore all records from all data logging queues.
  • Make sure the PLC’s real-time clock configuration (date, time, time-zone, daylight savings time) matches the workstation’s clock configuration.
  • Failure to do so will result in the Allen Bradley Driver tag setting the wrong timestamps to all logged values read from the PLC.

Allen-Bradley Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Allen-Bradley Driver properties Type tab

The Type tab for an Allen-Bradley driver tag properties folder consists of attributes used to identify the type of Allen-Bradley programmable logic controller that this driver will represent.

Allen-Bradley tag - Type tab

Allen Bradley, Type tab

PLC Type

Select the type of Allen-Bradley PLC that this Allen-Bradley driver tag will represent. This may be one of:

  • No Type Selected <default option>
  • PLC-2
  • PLC-3
  • PLC-5
  • PLC-5/250
  • SLC-500
  • MicroLogix 1100-1500

The MicroLogix driver is used in SLC-500 addressing. The TCP/IP port number to use for this driver is 44818.

It may be necessary to adjust the timeout interval on the TCP/IP tab if using MicroLogix.

If using a Rockwell CompactLogix or ControlLogix PLC, use the CIP driver.

Communication Mode

Set the mode to match the linked port.

PLC Address

This field should contain the address of the Allen-Bradley programmable logic controller. One of the following 3 formats is permitted. (Note that this address must be provided in octal.)

  • 012 (octal)
  • 034 0357 (octal with a bridge address)
  • 1.2.3.4 (IP address)

The PLC Address field and the TCP/IP Address fields are linked, and therefore are completed simultaneously. When you enter an address in the PLC Address field, the same address is automatically entered in the TCP/IP Address field on the TCP/IP tab for this tag. Conversely, when you enter an address in the TCP/IP Address field, the same address is automatically entered in the PLC Address field.

Number of Virtual Words

Use this field to specify the number of registers that the virtual PLC will create. The virtual PLC will then emulate a PLC-2 and respond to requests to read and write data.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Allen-Bradley Driver properties Serial tab

The Serial tab for the Allen-Bradley driver tag properties folder consists of attributes used to identify and establish a connection the Serial Port tag that the Allen-Bradley driver should use to transmit data to the I/O device. The Serial tab is also used to select the communication protocol and error checking to be used in transmissions of data between the I/O device and the Allen-Bradley driver.

Allen-Bradley tag - Serial tab

Allen Bradley, Serial tab

Port

Select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag. A Serial Port tag opens a serial port to enable communications between VTScada and your PLC or RTU. A TCP/IP tag is used to connect to a series of hosts, allowing you to transmit data across a network or over the Internet.

Right-click on the selected tag to open its properties folder.

Time-Out Limit

Sets the receiver time-out limit (i.e. the time in seconds or fractions of a second that this driver should wait for a reply from the PLC or RTU).

VTScada Station Address (Octal)

Specify the address (using the octal addressing format) of the VTScada system on the serial link.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

ENQ Delay

Specify the amount of time (in seconds or in fractions of a second) that this Allen-Bradley driver should wait before sending an ENQ in half duplex mode.

Note: Half duplex mode refers to the transmission of data in one direction at a time.

RTS Key Off Delay

The RTS Key Off Delay field represents the amount of time (in seconds) that this Allen Bradley driver will wait before dropping RTS at the end of a data transmission.

BCC

Click this check box to select whether the BCC error checking method will be used on communication messages.

By default, the BCC check box is not selected (i.e. CRC error checking is used on all communication messages).

Note: The CRC acronym stands for Cyclic Redundancy Check, and the BCC acronym stands for Block Check Character. Both are techniques used to detect data transmission errors. In general, CRC is a better error checking method, as it is a 16-bit error check, whereas BCC is an 8-bit error check.

Multi-Message Mode

Use only when the driver's Communication Mode is set to Serial/Modem and the DF1 Mode is set to Full Duplex.

If multiple Allen Bradley drivers are sharing the same port, then all drivers using the port must use the same configuration for this setting. Further, all of their "Communication Mode" and "DF1 Mode" settings must match as well.

This option cannot be used if other types of drivers share the same port.

See also: ABDF1IgnoreAckNak, ABDF1SerialMessages

DF1 Mode

Enables you to choose between the following data transmission modes in communications from the driver to the PLC.

  • Half Duplex: Half duplex mode refers to the transmission of data in one direction at a time. If the driver and the PLC are communicating using the half duplex mode, either the driver or the PLC may transmit data at one time. The device not communicating must wait until the device that is transmitting data is finished before it can transmit its data.
  • Full Duplex: Full duplex mode refers to the transmission of data by both parties simultaneously.
  • Radio Modem: Certain Allen Bradley PLCs use the Radio Modem Protocol (RMP) to optimize DF1 communication on radio modem links. The protocol is an enhancement of the Full Duplex Protocol and uses the same message format with all the ACK and NAK responses removed.

Allen-Bradley Driver properties SD tab

The SD tab for the Allen-Bradley driver tag properties folder consists of attributes used to identify and establish a connection to the SD I/O board, if one has been configured for this I/O device.

Allen-Bradley tag - SD tab

Allen Bradley, SD tab

Board Type

Specify the type of I/O board that has been installed. This can be one of:

  • Disabled - When selected, indicates that the I/O board for this driver is disabled.
  • S&S 5136-SD, Supplied Driver - When selected, indicates that a 5136-SD card is installed.

Device Name

The name of the device being monitored by this tag. This is a unique name that must be entered exactly as it appears in the Windows® Device Manager’s devices list.

Note: To launch the Device Manager in Windows, click Start, and then click Control Panel. Double-click System. On the Hardware tab, click Device Manager.

Time-Out Limit On SD

Set the amount of time (in seconds or in fractions of a second) that the driver will wait for a reply from the PLC's SD card.

Retries On SD

Select the number of retry attempts you wish to be made by the driver if there is no response to a message

VTScada Station Address On SD (Octal)

Specify the address of the VTScada system on the SD link. This value must be in Octal format.

The address may be set via a constant value, an expression or a numeric tag whose value is the octal address.

Allen-Bradley Driver Tag Type properties TCP/IP tab

The TCP/IP tab of the Allen-Bradley driver tag properties folder can be used to configure the address, port, and time limit to be used if communications are to be made using the TCP/IP communications protocol.

Allen-Bradley tag - TCP/IP tab

Allen Bradley, TCP tab

TCP/IP Address

The TCP/IP Address field is used to specify the port number through which this Allen-Bradley driver tag will communicate.

Note: The TCP/IP Address field and the PLC Address fields are linked, and therefore are completed simultaneously. When you enter an address in the TCP/IP Address field, the same address is automatically entered in the PLC Address field on the Type tab for this tag. Conversely, when you enter an address in the PLC Address field, the same address is automatically entered in the TCP/IP Address field.

TCP/IP Port

The TCP/IP Port Number field refers to the port number on the host address through which communications are enabled. This information should be available from your hardware specification. The default value depends on the PLC Type selected. 2222 or 44818 are typical values.

Connect Time Limit

Use the Connect Time Limit field to set the amount of time (in seconds or fractions of a second) that the driver will await responses from the PLC. Defaults to 5 seconds unless otherwise specified.

Time-Out Limit

Specifies the time to wait for the PLC to respond after connection. This is the same as the timeout on the Serial tab.

Ethernet/IP Inactivity Timeout

Applies only if the PLC Type is set to MicroLogix. The maximum network link inactivity time in seconds. If there is no communication between VTScada and the PLC for this duration, VTScada will shut down the TCP/IP socket connection to the PLC. This setting can be used to automatically terminate connections to PLC that are polled infrequently to reduce network traffic. The TCP/IP connection is automatically re-established by the driver when the PLC polling is resumed.

  • Inactivity timeout < I/O polling time will cause the session to timeout between polls
  • Inactivity timeout > I/O polling time will cause the session to remain open between polls
  • Inactivity timeout = polling time should be avoided.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Allen-Bradley Driver properties DLG tab

Certain Allen Bradley PLCs (of PLC Type "MicroLogix") can log time-stamped data into files in PLC memory.

The Allen Bradley Driver tag can read records from these files (referred to here and in the PLC documentation as queues). In order for the Allen Bradley Driver tag to make use of this feature, both the tag and the PLC must be configured properly. The DLG Read tab of the Allen Bradley Driver tag can be used to configure the tag for this feature. Refer to the PLC's manual for instructions on how to configure the PLC (noting that up to 256 queues can be created and data from different PLC memory addresses can be logged into different fields in different queues).

Allen-Bradley tag - DLG tab

Allen Bradley, DLG Read tab

Data Logging Queue

Use to select a queue (configured according to the PLC’s manual) from which the driver will be retrieving logged data.

Length of Records from Queue

Enter the length of the records in the queue selected in the Data Logging Queue drop list. This value is the length (in characters) of the records in the queue after they are converted into a string by the PLC for communication.

The valid range is from 1 to 80. The value must be calculated according to how the data logging queue was configured in the PLC itself:

  • 11 characters for the date field,
  • 9 characters for the time field,
  • 12 characters for each long integer field
  • 7 characters for each short integer field.

By default, the Allen Bradley Driver tag will assume a length of 80 chars (the maximum allowed by the PLC). While the default value will work, this may impose a penalty on the amount of communication between the driver and the PLC. Entering the exact length is therefore recommended.

Note: entering an incorrect value will most likely result in failure to read any records from a particular queue, therefore you should only change the default value if you know the exact value.

Closed Allen-Bradley Driver Tag Widgets

The following widgets are available to display information about your Allen-Bradley driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Allen-Bradley Driver I/O Addressing

VTScada supports native device address formats. For example, in a PLC5 "T4:1.ACC".

Bit-wise addressing for binary and integer formats is written by following the element with "/bit-number", except for timers which use a dot notation.

VTScada performs limited range checking on addresses and does not attempt correlate to the explicit ranges of all PLC models (i.e. some PLC’s may have limits which are more restrictive). Refer to the following list for structure member mnemonics that are supported by VTScada.

Some other structure members can be referenced via their bit number directly (for example /bb). Refer to the Allan Bradley documentation for the full structure definition.

PLC-3, PLC-5, SLC-500 and MicroLogix 1100-1500 have similar address format. PLC-2’s linear addressing scheme is listed separately. PLC-5/250 is not documented.

Input / Output Tables file - Logical address

I:xxx.wrd/bb for inputs

O:xxx.wrd/bb for outputs

xxx is the element number as follows:

The octal word number for PLC-3 (0 – 377) and PLC-5 (0 – 1999)

The decimal slot number for SLC (1 – 30) and MicroLogix (1 – 4)

.wrd is the optional word number, for SLC and MicroLogix only. Range is 0 – 255, defaults to 0 if not included

/bb is the optional bit number

Status Files - Logical address

S:xxx/bb

xxx is the word number (decimal). Range of 0 – 9999 on the PLC-3.

/bb is the optional bit number

Binary Files - Logical address

Bn:xxx/bb

n is the file number. Range 3 or (user-defined) 9 to 9999 for non-PLC-3 and 0 to 9999 on PLC-3.

xxx element number Range 0 to 1999 in the PLC-5

/bb is the optional bit number

Timer Files - Logical address

Tn:xxx.neu

n is the file number. Range 4 or (user-defined) 9 to 9999 for non-PLC-3 and 0 to 9999 on PLC-3.

xxx element number Range 0 to 1999 in the PLC-5

neu is a structure mnemonic as follows:

PRE, ACC (PLC-5 and MicroLogix)

PRE, ACC, EN, TT, DN (SLC-500)

Counter Files - Logical address

Cn:xxx.neu

n is the file number. Range 5 or (user-defined) 9 to 9999 for non-PLC-3 and 0 to 9999 on PLC-3.

xxx element number. Range 0 to 1999 in the PLC-5

neu is a structure mnemonic as follows:

PRE, ACC (PLC-5 and MicorLogix)

PRE, ACC, CU, CD, DN, OV, UN, UA (SLC-500)

Control Files - Logical address

Rn:xxx.neu

n is the file number. Range 6 or (user-defined) 9 to 9999 for non-PLC-3 and 0 to 9999 on PLC-3.

xxx element number. Range 0 to 1999 in the PLC-5

neu is a structure mnemonic.

PRE, ACC (PLC-5 and MicroLogix)

LEN, POS, EN, EU, DN, EM, ER, UL, IN, FD (SLC-500)

Integer Files - Logical address

Nn:xxx/bb

n is the file number. Range 7 or (user-defined) 9 to 9999 for non-PLC-3 and 0 to 9999 on PLC-3.

xxx element number. Range 0 to 1999 in the PLC-5

/bb is the optional bit number

Float Files - Logical address

Fn:xxx

n is the file number. Range 8 or (user-defined) 9 to 9999 for non-PLC-3 and 0 to 9999 on PLC-3.

xxx element number. Range 0 to 1999 in the PLC-5

ASCII Files - Logical address

An:xxx

n is the file number.

xxx element number. Range 0 to 1999 in the PLC-5 and 0 – 9999 in the PLC-3

String Files - Logical address

STn:xxx or Sn:xxx in the PLC-3

n is the file number.

xxx element number. Range 0 to 1999 in the PLC-5 and 0 – 9999 in the PLC-3

PID Files (PLC-5 only) - Logical address

PDn:xxx.neu/bb

n is the file number.

xxx element number Range 0 to 1999

neu is a structure mnemonic (see following table)

Bit Words: CTRL, STS (need a /bb to access specific bits)

Floats (structure mnemonics)

SP | Set Point
KP | Proportional Gain
KI | Initial Gain
KD | Derivative Gain
BIAS | Output Bias %
MAXS | Maximum Scaled Value
MINS | Minimum Scaled Value
DB | Dead Band
SO | Set Output %
MAXO | Maximum Output Limit
MINO | Minimum Output Limit
UPD | Update Time
PV | Process Variable
ERR | Error: Scaled
OUT | Output
PVH | PV Alarm High
PVL | PV Alarm Low
DVP | Deviation Alarm +
DVN | Deviation Alarm –
PVDB | PV Alarm Dead Band
DVDB | Deviation Alarm Dead Band
MAXI | Maximum Input
MINI | Minimum Input
TIE | Tieback %
Long: ADDR | Master-to-Slave Address

BCD Files (PLC-3 only) - Logical address

Dn:xxx

n is the file number

xxx element number. Range limit 0 to 9999

Data Logger Historical Reads

DLX:Y

X is the queue number

Y is the element number.

The queue number can range between 0 and 255. The element number can range between 1 and 11.

PLC 2 Linear Addressing

xxx/bb

xxx is an octal number

/bb is an optional bit octal number

PLC-5/250 - call for support

Mnemonics that are not supported:

  • .EN for a Timer Mnemonics.
    You may be able to access this directly using /15.
  • .DN syntax a Timer Mnemonics.
    You may be able to access these bits directly using /13.
  • .SWM syntax for a PID Mnemonic.
    You may be able to access this bit directly by using /4.


Allen Bradley Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
1 | 0x001 | Destination Node Out of Buffer Space
2 | 0x002 | Remote Node Does Not Acknowledge Command Message
3 | 0x003 | Duplicate Token Header Detected
4 | 0x004 | Local Port (DH or DH+) is Disconnected
6 | 0x006 | Duplicate DH Address
7 | 0x007 | Station Is Offline
8 | 0x008 | Hardware Fault
16 | 0x010 | Illegal Command or Format
32 | 0x020 | Remote Node (PLC) Has a Problem & Will Not Communicate
48 | 0x030 | Remote Node (PLC) is Missing, Disconnected, or Shut Down
64 | 0x040 | Remote Node (PLC) Could Not Complete Function - Hardware Fault
80 | 0x050 | Addressing Problem or Memory Protect Rungs
96 | 0x060 | Function Disallowed due to Command Protection Selection
112 | 0x070 | Processor is in Program Mode
128 | 0x080 | Compatibility Mode File Missing or Communication Zone Problems
144 | 0x090 | Remote Node (PLC) Cannot Buffer Command
176 | 0x0B0 | Remote Node (PLC) Problem due to Download
257 | 0x101 | Error Converting Block Address
258 | 0x102 | Incorrect Address Format in Protocol
260 | 0x104 | Symbol Not Found
261 | 0x105 | Symbol is of Improper Format
262 | 0x106 | Address Doesn't Point to Something Usable
263 | 0x107 | File is Wrong Size
264 | 0x108 | Can't Complete Request, Situation has Changed Since Start of Cmd
265 | 0x109 | File is Too Large
266 | 0x10A | Trying to Read/Write Past the End of the File
267 | 0x10B | Access Denied, Improper Privilege
268 | 0x10C | Condition Cannot be Generated - Resource Not Available
269 | 0x10D | Condition Cannot be Generated - Resource Already Available
273 | 0x111 | Illegal Data Type
274 | 0x112 | Bad Parameter
275 | 0x113 | Address Reference Exists to Deleted Data Table
512 | 0x200 | Communication Failure - Retry Limit Exceeded
513 | 0x201 | Illegal Address
514 | 0x202 | SD Card Not Available, Check if S&S Driver Installed
515 | 0x203 | Serial Port Failed to Open
516 | 0x204 | SD Card Requires Reset
517 | 0x205 | Illegal Station Address Syntax
518 | 0x206 | Unknown Error
519 | 0x207 | Unknown PLC Type
520 | 0x208 | EOT Received Before Response
521 | 0x209 | Message TNS Codes Did Not Match
531 | 0x213 | Connection Attempt Failed
544 | 0x220 | Records from PLC's DLG Queue Not as Expected
545 | 0x221 | PLC's DLG Queue Records Have No Date & Time Fields
546 | 0x222 | PLC's DLG Queue Records Have No Valid Date & Time: Clock Absent or Not Configured
547 | 0x223 | Attempt to Write to DLG Address
548 | 0x224 | Invalid DLG Address
549 | 0x225 | NAK Response from Device
550 | 0x226 | Message Received From Device With No ACK
551 | 0x227 | Timed Out Waiting For Response From Device
552 | 0x228 | Responding Station Address Does Not Match Sending Station Address
553 | 0x229 | Bad BCC or CRC Received
768 | 0x300 | Could Not Establish Socket Connection to PLC
769 | 0x301 | Could Not Connect to PLC at Port Number Specified
770 | 0x302 | Could Not Find PLC Specified
771 | 0x303 | Unknown Socket Error
772 | 0x304 | Lost Socket Connection to PLC
773 | 0x305 | Timed Out Waiting for PLC Response
774 | 0x306 | Socket Connection Not Ready
775 | 0x307 | Could Not Read Error Code from Response Message
776 | 0x308 | CIP Protocol Error
777 | 0x309 | TCP/IP Connection Message Failed


BACnet Driver

Not counted towards your tag license limit.

The BACnet driver follows the American Society of Heating, Refrigerating and Air Conditioning Engineers (ASHRAE) standard protocol document ANSI/ASHRAE Standard 135-2012 (Supersedes ANSI/ASHRAE Standard 135-2010) entitled, "BACnet - A Data Communication Protocol for Building Automation and Control Networks".

This driver supports Driver Discovery.

The driver was written using this standard as a protocol reference and supports protocol version 1.14. The protocol follows the seven-layer, Open Systems Interconnection (OSI) Basic Reference Model, in which each layer communicates with the immediately adjacent layer or layers.

It supports physical connections to devices that support the BACnet Virtual Link Layer over User Datagram Protocol/Internet Protocol, more commonly known as BVLL over UDP/IP or BACnet/IP.

The seven-layer OSI model:

Application Layer
Presentation Layer
Session Layer
Transport Layer
Network Layer
Data Link Layer
Physical Layer

Not all of these layers are required for the BACnet protocol implementation, therefore the layer diagram can be condensed as follows:

BACnet Layers |  |  |  |  |  |  | Equivalent OSI Layers
BACnet Application Layer |  |  |  |  |  |  | Application Layer
BACnet Network Layer |  |  |  |  |  |  | Network Layer
ISO 8802-2 (IEEE 802.2) Type 1 |  | MS/TP | PTP | LonTalk | BVLL | BZLL | Data Link Layer
ISO 8802-3 (IEEE 802.3) | ARCNET | EIA-485 | EIA-232 | LonTalk | UDP/IP | ZigBee | Physical Layer

The current design model of PC software and hardware prevents a reliable implementation of physical connections to other popular networks supported by the BACnet Standard, namely MS/TP. This is because the timing requirements can easily exceed the microsecond range, which may be too fast for the task-switching mechanism of modern operating systems. Moreover, systems with many drivers running in parallel can fail to achieve the minimum timing requirements for any baud rate. Using a remote port server through an IP link considerably worsens the situation, as it adds a lag between the generation of the network layer messages and the actual transmission to the media. It may also fragment packets in a way that exceeds the framing demands of the protocol.

Therefore, communications with devices not supporting BACnet/IP are only available through routing. BACnet supports a routing system alternative to the one used by higher-layer protocols (such as UDP/IP). It is based on the use of specially designed devices called BACnet routers. They are intended to interconnect two or more BACnet networks to form a BACnet internetwork. Different networks can use different data links and technologies if they are supported by both the BACnet standard and the router network being used.

To enable routing, select the option, "Use a BACnet router", on the Device tab of the driver's configuration dialog. The UDP/IP port selected in the Communications tab will be used to reach the Ethernet port of the router. This will result in the address of the port tag being displayed in the Router IP Address field, whereas the Device IP Address will become available for the user to enter the MAC address of the target device, according to the format selected in the Device Network Type drop-list. The Device Network Number field will also become available to enter the number of the network where the device is located. VTScada will add the routing information to the header of the message, so the router can relay it to the correct destination.

A typical network structure:

All numbers shown here are examples and may not work with your configuration. Refer to your device documentation rather than copying these.

While many other combinations are possible, this shows the typical scenario for a VTScada application. More information may be obtained at http://www.bacnet.org.

Because PC software and hardware evolved in a way that favors the concentration of all communications in a single IP-based link, using a BACnet router to manage low-level serial communications with compatible devices provides a much simpler and more reliable configuration. From VTScada’s perspective, all devices will be seen as BACnet/IP devices, even though routed devices will share a single UDP/IP port and address, and still rely on a typically slower media.

To use the configuration shown on the diagram, four BACnet drivers are required, configured as follows:

Numbers shown in the following tables are examples.
Refer to the hardware documentation for your device rather than copying these values.

 | BACnet/IP Device | MS/TP Device 1 | MS/TP Device 2 | MS/TP Device 3
Port | UDP Port 1 | UDP Port 2 | UDP Port 2 | UDP Port 2
Device IP/Node | (Set by Port) | 2 | 3 | 4
Network Type | - | MS/TP | MS/TP | MS/TP
Device Network # | - | 2000 | 2000 | 2000
Router IP | - | (Set by Port) | (Set by Port) | (Set by Port)
Use a BACnet router | - | Enabled | Enabled | Enabled

The two ports would be set with the following:

 | UDP Port 1 | UDP Port 2
UDP/IP Name/Address | 10.1.1.3 | 10.1.1.2
Remote Port # | 47808 (device-specific) | 47808 (device-specific)
Local Port # | 47808 | 47808

The local port numbers above are only an example. The standard BACnet port is 47808, but devices are required to support other ports as well. The MS/TP network node used by the router (1) is of no concern to this example, assuming that it doesn’t conflict with any other device located in the same network.

The BACnet router being used to connect to another network does not need to be directly connected to the destination network or support the destination protocol, as long as it has a path to another router that provides a connection. Each router in the link will receive the message and attempt to discover the best path to the requested network. This will continue until either the device is reached, or there are no remaining network hops available. Likewise, the response message (either successful or failed) will make its way back to the VTScada Station. Therefore, it is important that the Request and Segment timeouts are configured properly to allow enough time for the entire procedure.

Limitations

The driver currently supports basic I/O reading and writing of primitive types, including arrays of primitive items. More functionality is intended to be added throughout the next releases. Here is a list of current limitations and possible future enhancements:

  • Message security is not supported within the BACnet context.
  • All standard BACnet objects and their properties defined in version 1.14 are supported, although not all of them will return values that can be used by VTScada’s standard I/O tags. Some complex types, including Sequence (and therefore, sub-properties), Choice and BACnet List are not supported in this version. Arrays of primitive items can be both read and written in an item-by-item basis. Vendor-specific objects and properties are supported only if their encoding is not context-tagged.
  • While some properties may be writable per the BACnet Standard, or even some intended to be read-only could be written to on specific devices, the driver only supports writing to primitive types. As this is not enforced at the driver level, they might be configured to write, but the actual communications may fail depending on the device implementation.
  • The BACnet standard offers a few approaches to automatic network / device / object discovery, but this is currently not supported. Some properties or objects shown on the Address Assist dialog may not be present in the device being accessed.
  • The driver does not reply to queries regarding its capabilities as it does not expose the standard "Device" object.
  • Due to the limited object and property support, schedules and calendars may not be fully supported.
  • Services other than ReadProperty, ReadPropertyMultiple and WriteProperty are not supported.
Closed Related Application properties

The following property settings hold additional configuration parameters for your BACnet driver:

BACnetAddressLimit - The upper limit for BACnet object instance numbers (default = 4194303).

BACnetDefAcronyms – When set to 1 (True), the Address Assist module will generate address strings with acronyms instead of the full-name address (default = 0).

BACnetNPDUTimeout – Timeout for the receiver to wait for the reception of a full NPDU before discarding an incomplete message (default = 10 s).

BACnetDeviceInfoRetry – Retry interval when unable to get information about the capabilities of a device (default = 30 s).

BACnetPropWinSize – Default value for the parameter proposed-window-size, which determines how many message segments, up to the maximum of 127, VTScada will accept before requiring an acknowledgement (default = 127).

Closed BACnet properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

BACnet Driver properties Device tab

Device Address

The content and label of this field depends on the type of connection being used:

  • Use BACnet router disabled: the field is read-only, displaying the IP address and UDP/IP port number of the device, reflecting the configuration of the selected UDP/IP port tag.

  • Use BACnet router enabled: the field is user-editable, to enter the MAC Address of the routed device. The MAC Address is network-specific, according to the Device Network Type drop-list:

Device Network Type | Parameter name | Notes
BACnet/IP | Device IP Address | Editable
MS/TP | Device Node | Editable. Accepts values between 0 and 254
ISO 8802-3 (Ethernet) | Device Ethernet MAC Address | Editable
ARCNET | Device ARCNET ID | Editable
Point-To-Point | No device address | Not editable
LonTalk | Device MAC Address (Hexadecimal) | Editable
ZigBee | Device VMAC Address | Editable

Protocol Version and Release

Displays the ASHRAE standard protocol version that the driver follows, which is version 1.14. This value is not user-configurable.

Use a BACnet router

Select this option if the device is not physically connected to the station where VTScada is installed, but can be reached through a BACnet router. When enabled, the selected UDP/IP port tag is used to connect to the BACnet router, instead of the device itself.

Device Network Type

Enabled only when using a BACnet router. Affects the contents of the Device Address field. Used to inform the driver the type of the network the routed device is connected to as follows:

  • BACnet/IP: the device is connected to an IP network that cannot be directly accessed by the station where VTScada is installed. Device Address is used to set the IP address and UDP port number of the device. If no port is specified, the default BACnet port (47808) is used.

  • MS/TP: the device is connected to a serial Master-Slave/Token Passing network, using a EIA-485 physical layer. Device Address sets the number of the device (node) in the multi-drop serial network, between 0 and 254.

  • ISO 8802-3 (Ethernet): the device is connected to a ISO 8802-3 (“Ethernet”) LAN that does not use the IP Protocol. Device address sets the Ethernet Media Access Control (MAC) address, in the standard hexadecimal format (XX-XX-XX-XX-XX-XX).

  • ARCNET: the device is connected to a ARCNET LAN, as described in ATA 878.1. Device Address sets the ARCNET ID of the device, between 1 and 255.

  • Point-To-Point: the device is connected to a serial Point-To-Point network, through a BACnet Half-Router supporting a EIA-232 connection. Device Address is unavailable, as the destination network shall contain only a single device in this configuration.

  • LonTalk: the device is connected to a EIA/CEA-709.1 (“LonTalk”) LAN. Device Address sets the MAC Address of the device, encoded as either two hexadecimal bytes, representing a combination of the DstSubnet, DstGroup and DstNode of the device, or seven hexadecimal bytes, representing the Neuron_ID of the device. Check the BACnet Standard, clauses 6.2.2.2 and 11 for more details.

  • ZigBee: the device is connected to a wireless “ZigBee” network. Device Address sets the VMAC Address configured in the table used by the network where the device is located, encoded as an integer between 0 and 4194303. Check the BACnet Standard, annexes H.7 and O for more details.

Router IP Address

Enabled only when using a BACnet router. Displays the IP address and UDP/IP port number of the router, reflecting the configuration of the selected UDP/IP port tag.

Device Network Number

Enabled only when using a BACnet router. The network number where the VTScada Station is located. Accepts network numbers between 1 and 65534.

BACnet Driver properties Communications tab

Port

The UDP/IP port tag with the IP address and port of the device or router used to reach the device.

Note that the default UDP port used for BACnet/IP is 47808, but all BACnet devices must support, at a minimum, values in the ranges 47808 - 47823 and 49152 - 65535.

Multiple drivers using the same router to reach their peer devices must use a single shared port tag.

Response Timeout (s)

Maximum time (in seconds) that the driver will wait to receive a response to a request after the last segment of the message is transmitted, before attempting a retry. This parameter is used to set the parameter Tout, as described in the BACnet Standard, clause 5.4.

Segment Timeout

Maximum time (in seconds) that the driver will wait after sending a SegmentACK to receive an additional segment of the incoming message, or for a SegmentACK after sending the final segment of a sequence, before attempting a retry. This parameter is used to set the parameters Tseg and Twait_for_seg, as described in the BACnet Standard, clause 5.4.

Retries

The number of times to retry a message before declaring an error.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

BACnet Driver properties - Advanced tab

The parameters in this tab are usually best left at their defaults.
Used to troubleshoot connection issues, especially when limited routed networks, or older, less capable devices, are involved. Changing any of these parameters may negatively affect the performance and reliability of the driver. Advanced knowledge of the BACnet Protocol is recommended before attempting any changes.

Network Priority

The message priority to determine how messages to the device will be prioritized by routers along the path (not to be confused with property write priorities). Does not affect local connections. May be set to any of:

  • 0 – Normal Message
  • 1 – Urgent Message
  • 2 – Critical Equipment Message
  • 3 – Life Safety Message

Maximum APDU Length

The maximum number of bytes that a BACnet Application Protocol Data Unit can have before the message is divided in segments. This parameter is used to limit the size of packets going through multiple routed networks with unpredictable capacity. The actual APDU length will be the smaller between the standard for the network type chosen in the Device tab (1476 if not routed), the value chosen in this list, and the value reported by the device. Valid options are (in bytes):

  • 50
  • 128
  • 206 (fits in a LonTalk frame)
  • 480 (fits in a MS/TP, ARCNET, Point-To-Point or ZigBee frame)
  • 1024
  • 1476 (fits in an ISO 8802-3 or BACnet/IP frame)

Max Message Retransmissions (Hop Count)

The maximum times a message is retransmitted by routers when attempting to reach another network. This number is decremented every time a router receives a message and attempts to forward it to the next destination in the BACnet internetwork. It is intended to prevent messages from using network resources indefinitely when the ultimate destination is unreachable. Accepts values between 1 and 255.

Maximum Request Segments

Sets the maximum segments that a request message from the driver may have. For performance reasons, the driver will typically attempt to compose request messages that fit in a single segment and result in a single segment as response, but some data types, such as strings, may result in messages with hard to predict sizes. Some older devices may not support segmentation or may support too few segments for a response message, and it might not be possible to retrieve the information about device capabilities. If this field is set to the minimum of one segment, the driver will use a single request for each address resulting in responses containing strings.

Allow multi-property read requests

Disabling this option further limits the number of addresses that can be requested in a single message to one. It might be required when a device does not support ReadPropertyMultiple Service requests, and the driver is unable to retrieve the information about device capabilities.

Allow new requests to be sent before receiving a response

The BACnet Driver supports sending and receiving up to 256 simultaneous messages to and from a single device. Some devices with lower hardware capabilities, though, may not be able to reply to multiple messages in a timely manner, resulting in messages being discarded due to timeouts. By disabling this option, the driver will wait for either a response from the device or a timeout, before sending the next request in the queue.

Closed BACnet Driver Tag Widgets

The following widgets are available to display information about your BACnet driver tags:

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


BACnet Driver Addressing

The general format for addressing BACnet objects and properties is as follows (Brackets [ ] are used for array items. Braces { } are shown to mark optional components, but must not be used in the actual address string):

ObjectType{:}#{.Property}{[I]}{(P)}

where:

  • ObjectType is the BACnet object Default Address, Acronym, or Object Type code, according to the following table. A colon is required to separate the type code from the instance number, but this is optional when using an address or acronym. Vendor-specific objects are only supported through codes (127-1023).
  • # is the object instance number
  • Property is either the name of the property or its numeric identifier, as defined in ANSI/ASHRAE Standard 135-2012, clauses 12 and 21. If omitted, it is assumed as Present_Value (85), which usually contains the current value assigned to the object. Vendor-specific properties are only supported through identifiers (512-4194303).
  • I is the array index, required for properties encoded as such.
  • P is the write priority, used to write to commandable properties and return the correct feedback when reading from them. Values from 1 to 16 are accepted. If not specified, devices assume it as 16 (the lowest).

(Examples follow the table.)

Object Name | Default Address | Accepted Acronyms | Type Code
Analog Input | AnalogInput | AI | 0
Analog Output | AnalogOutput | AO | 1
Analog Value | AnalogValue | AV | 2
Binary Input | BinaryInput | BI | 3
Binary Output | BinaryOutput | BO | 4
Binary Value | BinaryValue | BV | 5
Calendar | Calendar | CAL | 6
Command | Command | COM, CMD | 7
Device | Device | DEV | 8
Event Enrollment | EventEnrollment | EE | 9
File | File | F | 10
Group | Group | G | 11
Loop | Loop | LP | 12
Multi-state Input | MultiStateInput | MSI, MI | 13
Multi-state Output | MultiStateOutput | MSO, MO | 14
Notification Class | NotificationClass | NC | 15
Program | Program | PROG | 16
Schedule | Schedule | SCH | 17
Averaging | Averaging | AVG | 18
Multi-state Value | MultiStateValue | MSV, MV | 19
Trend Log | TrendLog | TL | 20
Life Safety Point | LifeSafetyPoint | LSP | 21
Life Safety Zone | LifeSafetyZone | LSZ | 22
Accumulator | Accumulator | ACM | 23
Pulse Converter | PulseConverter | PC | 24
Event Log | EventLog | EL | 25
Global Group | GlobalGroup | GG | 26
Trend Log Multiple | TrendLogMultiple | TLM | 27
Load Control | LoadControl | LC | 28
Structured View | StructuredView | SV | 29
Access Door | AccessDoor | ACD | 30
Access Credential | AccessCredential | ACC | 32
Access Point | AccessPoint | ACP | 33
Access Rights | AccessRights | ACR | 34
Access User | AccessUser | ACU | 35
Access Zone | AccessZone | ACZ | 36
Credential Data Input | CredentialDataInput | CDI | 37
Network Security | NetworkSecurity | NS | 38
BitString Value | BitStringValue | BSV, BS | 39
CharacterString Value | CharacterStringValue | CSV, CS | 40
Date Pattern Value | DatePatternValue | DPV, DP | 41
Date Value | DateValue | DV | 42
DateTime Pattern Value | DateTimePatternValue | DTPV, DTP | 43
DateTime Value | DateTimeValue | DTV | 44
Integer Value | IntegerValue | IV | 45
Large Analog Value | LargeAnalogValue | LAV | 46
OctetString Value | OctetStringValue | OSV, OS | 47
Positive Integer Value | PositiveIntegerValue | UV, PIV | 48
Time Pattern Value | TimePatternValue | TPV, TP | 49
Time Value | TimeValue | TV | 50
Notification Forwarder | NotificationForwarder | NF | 51
Alert Enrollment | AlertEnrollment | AE | 52
Channel | Channel | CH | 53
Lighting Output | LightingOutput | LO | 54

For example, to read or write the value of Analog Input 1, any of the following is accepted:

AnalogInput1
AnalogInput:1
AI1
AI1.85
0:1
AnalogInput1.Present_Value
AI1.Present_Value

To retrieve the engineering units of the Accumulator object #3, both of the following can be used:

Accumulator3.Units
ACM3.Units
23:3.117

To write the present value of Analog Value 2 under priority 3:

AnalogValue3.Present_Value(3)
AV2(3)
2:2(3)

If non-null values are currently stored under higher priorities (1 or 2), reading the previous address will return the highest priority value instead. Under such circumstances, a VTScada output widget will not report success in the writing procedure, unless the Read Address of the tag is set to one of two options:

  • Adaptive Feedback (preferred method) - the tag will display the value of the selected priority (3 in the example), unless it has been relinquished, resulting in an invalid entry in the priority array. If so, it will display the highest priority instead:
AnalogValue3.Present_Value(3)

(or any of the other options shown above for the write address)

  • Direct Priority Array reference - the tag will always display the value associated with the selected priority. If it has been relinquished, no value will be shown (invalid)
 AnalogValue3.Priority_Array[3]

Address Select Dialog

The BACnet Driver provides an address selection module to help you write addresses in the correct format:

Object Type

Select the object type from this drop list. All standard BACnet object names are shown, regardless of being supported or present in the connected device.

Instance Number

Any number between 0 and the maximum object identifier (default: 4194303) can be selected, regardless of the range supported by the device.

Property

The property to read or write can be selected from this drop list. By selecting the first option in the list, the address will not specify a property, thus Present_Value will be assumed, even if the object doesn't support it. Properties supported by the selected object (per the BACnet standard) are listed on top, but any existing property can be selected. The support of specific properties, even those defined in the standard, depends on the device.

Array Index

The index of the array item being addressed, for properties encoded as such. BACnet array indexes are 1-based, with index 0 used to access the size of the array.

The driver will not prevent an array index from being specified, regardless of the type of the selected property. If it is not an array, the device will return an error when attempting to read or write it.

Write Priority

Select the priority used to access commandable properties (typically, the Present_Value property of output and value-storing objects). The BACnet prioritization system uses priority values from 1 (highest) to 16 (lowest) to arbitrate between multiple devices attempting to write to the same property.

If declared for the Read Address of a commandable property, it will override the default behavior of the prioritization system by returning the value assigned to the property in the object, if not null. Otherwise, the non-null value with the highest priority assigned to it will be returned when attempting to read the property. This setting has no effect on non-commandable properties. Items of the read-only property Priority_Array contain the values currently assigned to each priority level. If all priorities are assigned a null value, Present_Value will return the value of the property Relinquish_Default instead. If the first option (Default) is selected, no priority will be specified when attempting to write to the device, which is effectively the same as the driver's Default Write Priority parameter. Devices will ignore this setting if the property does not support write priorities.


BACnet Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
000 | 0x0 | No error
009 | 0x9 | Invalid data type
016 | 0x10 | Missing required parameter
020 | 0x14 | No space to write property
027 | 0x1b | Read access denied
031 | 0x1f | Unknown object
032 | 0x20 | Unknown property
037 | 0x25 | Value out of range
040 | 0x28 | Write access denied
042 | 0x2a | Invalid array index
047 | 0x2f | Datatype not supported
048 | 0x30 | Duplicate name
049 | 0x31 | Duplicate object id
050 | 0x32 | Property is not an array
051 | 0x33 | Abort: Buffer overflow
052 | 0x34 | Abort: Invalid APDU in this state
053 | 0x35 | Abort: Preempted by higher priority task
054 | 0x36 | Abort: Segmentation not supported
055 | 0x37 | Abort: Proprietary
056 | 0x38 | Abort: Other
059 | 0x3b | Reject: Buffer overflow
060 | 0x3c | Reject: Inconsistent parameters
061 | 0x3d | Reject: Invalid parameter data type
062 | 0x3e | Reject: Invalid tag
063 | 0x3f | Reject: Missing required parameter
064 | 0x40 | Reject: Parameter out of range
065 | 0x41 | Reject: Too many arguments
066 | 0x42 | Reject: Undefined enumeration
067 | 0x43 | Reject: Unrecognized service
068 | 0x44 | Reject: Proprietary
069 | 0x45 | Reject: Other
080 | 0x50 | Parameter out of range
123 | 0x7b | Abort: APDU too long
124 | 0x7c | Abort: Application exceeded reply time
125 | 0x7d | Abort: Out of resources
126 | 0x7e | Abort: TSM timeout
127 | 0x7f | Abort: Window size out of range
256 | 0x100 | Loss of port connection
257 | 0x101 | Header timeout error
258 | 0x102 | Data timeout error
259 | 0x103 | NPDU Timeout error
260 | 0x104 | Header CRC error
261 | 0x105 | Data CRC error
262 | 0x106 | Non-NPDU message error
263 | 0x107 | Timeout error
264 | 0x108 | Serial port error
265 | 0x109 | Invalid Write Property Error
266 | 0x10a | Invalid Read Property Error
267 | 0x10b | No valid read data
268 | 0x10c | Unsupported Frame Type
269 | 0x10d | Error in the MS/TP Network
270 | 0x10e | Unknown Data Type to write
271 | 0x10f | Invalid Destination MAC Address
272 | 0x110 | Invalid Source MAC Address
273 | 0x111 | Invalid Header Information
274 | 0x112 | Unable to get a valid Invoke ID
275 | 0x113 | Unexpected response
276 | 0x114 | Too many consecutive requests
351 | 0x15f | Unable to register with foreign BBMD


Bristol BSAP/IBP Driver

Not counted towards your tag license limit.

The Bristol driver enables communications between VTScada and Bristol RTUs using the serial BSAP protocol and Ethernet-based IBP protocol.

This driver defines the connections to each individual RTU that VTScada will communicate with. There will be one Bristol Driver tag for each unique RTU that VTScada will communicate with or pass data through. When configuring Bristol Driver tags, the individual driver tags must correctly reference their associated Network Tag and the Driver tag of the RTU acting as its network master (in serial networks) to route messages correctly. To simplify the tag configuration, the Bristol Network and Bristol Drivers can be arranged into a tree structure that mimics the physical arrangement of the RTUs in their communication infrastructure. The following section contains a number of configuration examples showing physical arrangements of RTUs and their associated VTScada Port, Network, and Driver tags.

All Bristol drivers under a Bristol Network tag utilize a single service regardless of if SharedRPC is enabled. Failover is determined by how many consecutive errors occur in the system altogether. The default Failover count is 10. The minimum failover count should be at least equal to the total number of Bristol drivers in the network or however many fails that can be permitted to occur collectively before servership switch.
To modify this setting see BristolFailoverCount

Related information:

Bristol Network Tag

Ethernet to Serial Converters - Troubleshooting.

Closed Configuration Examples

The Bristol driver tags allow communication with several distinct RTU configurations as described in the fol-lowing sections.

BSAP Serial Networks

The Bristol Driver can communicate with multi-level serial networks as shown in the following figure using the BSAP protocol option. For this network setups, create a single Bristol Network tag and a single port tag to represent the entire network and one Bristol Driver tag for each RTU.

BSAP serial network

For the example shown, the following tag tree will automatically implement the correct network and driver message routing. Note that each level of RTUs is nested below the node in the tag tree that acts as a store and forward node in the physical configuration.

Tag tree for the serial example

IBP Ethernet Networks

The Bristol Driver can communicate with Ethernet LAN/WAN connected RTU networks as shown in the following figure using the IBP protocol option. For this network setup, create a port tag and a Bristol Network tag for each RTU, along with a Bristol Driver tag for each RTU.

Ethernet LAN/WAN using IBP

For the example shown, the following tag tree will automatically implement the correct network and driver message routing. Note the difference from the previous example – each RTU connected to the Ethernet LAN will require its own port tag, its own network tag, and its own driver tag. The reason each requires its own Network tag should become clear in the next example.

Tag tree for Ethernet LAN/WAN example

Mixed Networks

The Bristol Driver can communicate with RTUs connected to "mixed" Ethernet LAN/WAN and BSAP serial networks as shown in the following figure using the IBP protocol option. For this network setup, create a port tag and a Bristol Network tag for each Ethernet connected RTU, along with a Bristol Driver tag for each RTU regardless of how it’s connected.

Mixed IBP & BSAP

For the example shown, the following tag tree will automatically implement the correct network and driver message routing. Note the difference from the previous example – each Ethernet connected RTU still has its own Network tag but all RTU connected serially to that RTU use the same network tag.

Tag Tree for Mixed Example

Closed Related Application properties

The following property settings hold additional configuration parameters for your Bristol driver:

BristolBadPollsForReactivation – sets the number of bad polls before an RTU is placed onto the reactivation list (BSAP only)

BristolTraceActive – set to record all communication messages to a trace file

BristolTraceAuditRead – set to record the read of the audit logs to a trace file

BristolTraceAlarms – set to record the read of alarms & events to a trace file

Closed Bristol Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Bristol Driver properties Communication tab

Local Address

Local address of the RTU (1 - 127).

Global Address

Global address of the RTU. This value calculated automatically by the driver based on the associated Network tag’s NRT and the position of the RTU in the network tree.

Data Read Time Limit

The time limit in seconds to get a response from an RTU. This value will get progressively longer as the network nesting level of the RTU increases and must take into account the baud rates, the polling rates, the number of RTUs on the intervening networks, etc. Refer to Bristol documentation for information on expected delay times to get responses to messages on multilevel networks.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Auto Read All RTU Signal Data

All communication between VTScada and Bristol RTUs is performed using the MSD numbers of the signals in the RTUs database. On initial startup, VTScada must communicate with the RTU to determine the MSD numbers for each signal to be read or written but by default only requests the MSD numbers for the specific signals that its interested in (i.e. the signals in the Input and Output tags). By selecting this option, the driver will automatically read all MSDs and signal names from the RTU whenever there is a request to read the needed MSD information. The data is then available for easy selection of the proper signals using the address picker tool on input and output tags for the driver. Note that this information is only read on an as needed basis – after it is read, it is stored to disk by VTScada and is still available on a system restart.

Long Names

Select when using ControlWave devices with firmware version 2.2 and higher to allow for longer tag names.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Delete Audit Log On Read

Select this flag to automatically delete the audit log entries from the RTU as they are read by the driver. By default, the log entries are not deleted and the driver keeps track of the last information read. The driver only reads the values that have been added to the audit log since the last read.

Bristol Driver properties Network tab

Bristol Network Tag

This is the Bristol Network tag that RTU is defined to be a part of. It can be defined explicitly as any Bristol Network tag configured in your tag configuration. If not defined explicitly, the driver will look up through the tag tree and use the first Bristol Network tag it finds as its network.

Master RTU Bristol Driver Tag

This is the Bristol Driver tag for the RTU that acts as the network master for this RTU. This tag is used by driver to determine its position in the network tree hierarchy and from that to calculate its global address.

The Master RTU can be defined explicitly as any Bristol Driver tag configured in your tag configuration. If not defined explicitly, the driver will look up through the tag tree and use the first Bristol Driver tag it finds as its Master RTU.

When configuring level 1 RTUs connected directly to the VTScada server with no intermediate RTUs, this tag must not be defined.

Enable Time Synch

Select this option to enable sending periodic time synchronization messages to the RTU. Note that this only applies to Level 1 RTUs – after the time is sent to these devices it is automatically propagated to all network levels beneath the RTU it is sent to.

Time Synch Frequency

The rate (in seconds) to send the time synchronization to the RTU. This value is only used if "Enable Time Synch" is selected and if the RTU is a level 1 device.

Bristol Driver properties Alarms Tab

Alarms and Events generated by the RTU can be processed and added to the VTScada alarm system using the settings on this dialog tab. All alarms & events received from the RTU and stored in the VTScada alarm manager are registered to the driver. In cases where the events have not cleared properly, the "Purge" control can be used to delete any and all alarms in the alarm manager associated with this RTU.

Handle Device Alarms

Select this option to enable the processing of alarms and sending of acknowledgments by the driver. For Ethernet-connected RTUs, the driver will send an alarm NAK message in response to any received alarms if this option is not enabled or an alarm ACK message if it is enabled.

If a Bristol device produces alarms, this option should be selected. Failure to process the alarms can interrupt normal communication with the device and prevent VTScada from reading current values and sending control outputs.

Record Device Alarms in VTScada

If alarm handling is enabled in the driver, this option allows you to then report received alarms and events from the RTU using the VTScada alarm manager.

Priority for "Events"

Sets the VTScada alarm manager priority for "Events" messages received from the RTU.

Priority for "OP Guide"

Sets the VTScada alarm manager priority for "OP Guide" messages received from the RTU.

Priority for "Non Critical"

Sets the VTScada alarm manager priority for "Non Critical" messages received from the RTU.

Priority for "Critical"

Sets the VTScada alarm manager priority for "Critical" messages received from the RTU.

Closed BSAP Driver Tag Widgets

The following widgets are available to display information about your Bristol driver tags:

Comm Indicator Widget

Bristol Communication Messages Dialog

Bristol Driver Statistics Dialog

Alarm Priority Box

Alarm Priority Icon

Bristol History Info Widget

Poll Control Widget (Bristol driver)

Poll Status Widget (Bristol driver)

Purge Alarms Widget (Bristol driver)

Send NRT and Time Widget (Bristol)


Bristol BSAP/IBP Driver Addressing

An Address Assist dialog is available when configuring I/O tags to communicate with your Bristol BSAP/IBP driver:

If you select the "Read RTU Signals" button, the driver will read all signal information from the RTU. Note that it will take time to read RTU signal information.

You must confirm that you wish to continue this operation.

The Bristol driver can access the following data types in Bristol RTUs:

  • Arrays
  • Audit logs
  • File Data
  • Remote Database (i.e. signals)

The format of the address used to access the data varies based on the data type, with some using a four-character prefix followed by a colon. The data types and their associated address prefixes are shown here:

Address Prefix | Data Type | Read | Write
ARR: | Array | Yes | Yes
AUD: | Audit Logs | Yes | No
FIL: | Archive File | Yes | No
- | Remote Database | Yes | Yes

Array Addressing

Individual array elements in the RTU can be read from and written to by VTScada tags. The format of an array address is as follows:

ARR:Ta[c,r]

Where:

ARR: - defines the address as an array read

T – the type of array to read. Allowable values are:

A – Analog array

L – Logical array

a – the number of the array

c – the column number in the array

r – the row number in the array

Example:

Use address ARR:A6[4,3] to read or write the element at column 4, row 3 of analog array #6.

Audit Log Addressing

Audit logs can be read from the RTU on an element by element basis. The format of an audit read address is as follows:

AUD:n

Where:

AUD: - defines the address as an audit read

n – the field number in the audit. Possible values are:

0. Record type

1. Name

2. New Value

3. Old Value

4. On Text

5. Off Text

Example:

Use address AUD:3 to read the old value field from the Audit Log.

Archive File Addressing

Archive files can be read from the RTU on an element by element basis. The format of an archive file read address is as follows:

FIL:f.e

Where:

FIL: - defines the address as an archive file read

f – sets the file number to read

e – defines the element (i.e. column number) of the field to read

Archive file reads are typically entered into the "History Address" field of Analog Status tags.

Example:

Use address FIL:10.4 to read the 4th field (column) of array #10.

Remote Database Addressing

Individual RTU signals can be read from and written to by VTScada tags. The format of an address for individual signals is simply their signal name.

Example:

Use address RUN1_ZB to read or write to signal RUN1_ZB.


Bristol BSAP/IBP Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0000 | 0x0 | No Error
0101 | 0x65 | Invalid or Null String Memory Address Parameter
0102 | 0x66 | No Message or Data Type Found in Tag Address
0103 | 0x67 | Invalid Message Type in Address
0104 | 0x68 | Calculated and Received CRC do not Match
0107 | 0x6b | Local Node Response Timeout
0108 | 0x6c | Unknown Serial Number Received
0109 | 0x6d | NAK Message Received, RTU Buffers Full
0110 | 0x6e | Poll Time has been Exceeded
0111 | 0x6f | Invalid Data Type Received
0112 | 0x70 | Data Read Timeout
0113 | 0x71 | Invalid Data Type Specified
0114 | 0x72 | Too Many Addresses for a Single Message
0116 | 0x74 | Name not Found or Message Buffer Byte Count Exceeded
0117 | 0x75 | Analog Value Found in Packed Logic Processing
0118 | 0x76 | No Match Found
0119 | 0x77 | ACCOL Version Number did not Match
0120 | 0x78 | Invalid Database Function Requested
0121 | 0x79 | Attempted to Write to Read Only Area
0122 | 0x7a | Invalid Identifier, Name or MSD Address
0123 | 0x7b | Security Violation
0124 | 0x7c | Attempted to Write to Manually Inhibited Signal
0125 | 0x7d | Invalid Write Attempted
0126 | 0x7e | Incomplete RDB Request
0127 | 0x7f | No Match for Indicated Signal Name
0128 | 0x80 | Data Write Timeout
0129 | 0x81 | Invalid header size
0136 | 0x88 | RBE is not defined
0137 | 0x89 | RBE Cannot Allocate Dedicated Buffers
0138 | 0x8a | RBE Cannot Queue IO Requests
0139 | 0x8b | RBE Bad Message
0140 | 0x8c | RBE Bad Function Code
0141 | 0x8d | RBE Bad Sub-Function Code
0142 | 0x8e | RBE Bad Scan Period
0143 | 0x8f | RBE Bad Stop Transmit Limit
0144 | 0x90 | RBE Bad Report Format
0145 | 0x91 | RBE Bad Parameter - Number of Entries
0146 | 0x92 | RBE Bad Parameter - Op Code
0147 | 0x93 | RBE Bad Entry in Act/DAct Request
0148 | 0x94 | RBE Bad RSN in Demand Request
0149 | 0x95 | RBE Bad RSN in Report Ack
0150 | 0x96 | RBE Post Switchover Error Detected
0151 | 0x97 | RBE Bad Port
0152 | 0x98 | RBE Manager Response Timeout
0153 | 0x99 | No Network Master Defined
0154 | 0x9a | Unknown Error Code
0155 | 0x9b | BSAP Receive Message Echo Timeout
0156 | 0x9c | BSAP Receive Message Header Timeout
0157 | 0x9d | BSAP Receive Message Address Mismatch
0158 | 0x9e | BSAP Response Message Serial Number Mismatch
0159 | 0x9f | File Read - Attempting To Read Bad File #
0160 | 0xa0 | File Read - Attempting To Read Bad File Record #
0161 | 0xa1 | Unknown Error Returned from RTU in SES
0162 | 0xa2 | BSAP Attempting to send Unknown Message Type
0163 | 0xa3 | BSAP No Acknowledge of sent Up Acknowledge
0164 | 0xa4 | Level 1 Node Is Offline, Cannot Send Message
0165 | 0xa5 | No MSD Addresses Found in RTU for RBE Names
0166 | 0xa6 | Attempting To Send NRT to Non-Level 1 Device
0168 | 0xa8 | Audit Read -EAUDIT Process Not Defined In Device
0169 | 0xa9 | Audit Read - Security Code Did Not Match
0170 | 0xaa | Audit Read - Delete of Records Not Performed
0171 | 0xab | Attempting To Read Bad File Date
0172 | 0xac | File Read - Memory Allocation Error
0173 | 0xad | File Read - Missing File Definition
0174 | 0xae | File Read - Error In File Definition
0175 | 0xaf | Bad Write Address
0176 | 0xb0 | Polling Paused
0177 | 0xb1 | IBP Data Link Not Ready
0178 | 0xb2 | Incomplete IBP Message Received
0179 | 0xb3 | Unknown Error Returned from RTU
0180 | 0xb4 | Stuck Reading Audit Log
0181 | 0xb5 | NAK Limit Reached for RTU
0182 | 0xb6 | EBSAP Group Number Did Not Match
0183 | 0xb7 | Unknown Error Returned from RTU in PES
0184 | 0xb8 | Request Format Is Incorrect
0185 | 0xb9 | Invalid File Number or Name
0186 | 0xba | Invalid Record Number or Name
0187 | 0xbb | Audit File Not Defined
0188 | 0xbc | Request Format Incorrect
0189 | 0xbd | Date Request For Non Historical Archive
0190 | 0xbe | Expanded Group Not Defined
0191 | 0xbf | Invalid Port Number (From RTU)
0192 | 0xc0 | Port Number Is Unused (From RTU)
0193 | 0xc1 | Port Error (From RTU)
0194 | 0xc2 | Security Code Not Defined In Running ACCOL Load
0195 | 0xc3 | Not All Elements Fin In Response Buffer (More To Go)
0196 | 0xc4 | Invalid Array Type
0197 | 0xc5 | Error In Request Group
0198 | 0xc6 | Not All Elements Fit In The Response And There Is An Error In A Group
0199 | 0xc7 | Invalid Array Number (Not In Load)
0200 | 0xc8 | Invalid Row Or Column
0201 | 0xc9 | Invalid Custom Interface Table
0202 | 0xca | Unsupported Function
0203 | 0xcb | Unsupported Sub-Function
0204 | 0xcc | Error In Reset Request
0205 | 0xcd | Error In Date/time Request
0206 | 0xce | Unknown PES Error Code
0207 | 0xcf | Number Of Records In response Less Than Requested
0208 | 0xd0 | Unknown PES SES Combination
0209 | 0xd1 | Level 1 Node Congestion
0210 | 0xd2 | Read Signals Timeout
0211 | 0xd3 | Timed Out Sending Message
1001 | 0x3e9 | Port Not Defined
1002 | 0x3ea | Port Failed To Connect
1003 | 0x3eb | Port Lost Connection
1004 | 0x3ec | Serial Port Settings Out of Range
1005 | 0x3ed | Serial Port Already In Use or Not Available
1006 | 0x3ee | Serial Port Access Denied
1007 | 0x3ef | Serial Port General Failure
1008 | 0x3f0 | Serial Port Invalid Parameter
1009 | 0x3f1 | Port Not Connected
1010 | 0x3f2 | Port Unknown Error


Bristol Network Tag

Not counted towards your tag license limit.

The Bristol Network tag provides a common network interface to one or more Bristol Driver tags. This tag defines the interface to the network of RTUs connected to a single port in VTScada and is configured differently for BSAP networks vs. IBP networks.

For BSAP networks, a single serial (or TCP) port in VTScada is used to communicate with one or more RTUs directly connected to that serial port (the level 1 devices) which in turn can communicate with a number of RTUs connected to their serial ports, up to 6 levels deep. For these configurations, a single VTScada Bristol Network tag is used for the entire BSAP network.

For IBP networks, each individual RTU that is connected to VTScada (each Ethernet connected RTU) will require its own unique Bristol Network tag. For a setup of 20 RTUs connected directly to an Ethernet work, you will require 20 Bristol Network tags and 20 Bristol Driver tags. If you need to communicate with RTUs connected to the serial ports of the Ethernet (IBP) connected RTUs, then you can do this through the Bristol Network tag that is used to connect to the RTU on the Ethernet (using an IBP configured tag) , and from there to the serially connected RTUs. See configuration examples provided in Bristol BSAP/IBP Driver.

Note that in the context of the VTScada Bristol Network & Bristol Driver tags, "directly connected on Ethernet" means connected to the Ethernet port on the RTU. If communicating to a serial port on an RTU using an Ethernet to serial converter, then this is a BSAP network, not an IBP network

Use in Ethernet Connected Devices

In order for VTScada to be able to set the NRT and clock of an Ethernet connected RTU, the IP address of the VTScada server must be defined as one of the RTU’s NHP servers using the Bristol "Flash Configuration" utility in the LocalView or NetView programs.

Related information:

Bristol BSAP/IBP Driver - Includes examples of network configuration.

Closed Bristol Network properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Bristol Network properties Communication tab

Port

Communications port tag that the driver will use. For BSAP (Serial) protocol, this is typically a Serial Port tag but may also be a TCP/IP Port tag or a UDP/IP Port tag if connecting to a serial RTU via an Ethernet to Serial converter.

For IPB protocol, this must always be a UDP/IP port tag with both its Remote Port Number and Local Port Number fields set to 1234.

Use in Ethernet Connected Devices: In order for VTScada to be able to set the NRT and clock of an Ethernet connected RTU, the IP address of the VTScada server must be defined as one of the RTU’s NHP servers using the Bristol "Flash Configuration" utility in the LocalView or NetView programs.

Protocol Type

Selects the type of communication that the drivers will use on this network. For direct connections to RTUs using serial, select the "Serial (BSAP)" option, for connection to RTUs via an Ethernet port on an RTU, select the "Ethernet (IBP)" option.

Note that the protocol Type selection sets the format of the data sent to and received from the RTUs on the network and does not necessarily match the VTScada port type used. To determine which protocol to use, the following guide may be helpful:

  • If communicating directly from VTScada to the Level 1 RTUs on the communication network via a serial port on the RTU, use the Serial (BSAP) protocol
  • If communicating directly from VTScada to the Level 1 RTUs on the communication network via an Ethernet to serial converter and then to a serial port on the RTU, use the Serial (BSAP) protocol even though it is being transported via Ethernet TCP/IP.
  • If communicating directly from VTScada to the Level 1 RTUs on the network via an Ethernet port on the RTU, use the Ethernet (IBP) protocol.

Local RTU Time Limit

Sets the local timeout in seconds for a directly connected RTU to respond. Note that on multi-level networks, this timeout only applies to the level 1 devices. For RTUs at different network levels, different time limits can be applied.

Retries

Set the number of times to retry a message before declaring it failed. Defaults to 1.

Disable BSAP Polling Cycle

For BSAP networks only, this option disables the background BSAP polling cycle and can be used to reduce communication link traffic in a limited number of system configurations. Select this option only if your configurations meets ALL of the following criteria:

  • Using BSAP serial protocol
  • All devices are connected as Level 1 devices (no store and forward in use)
  • All Devices support "Immediate Response" messages – this is typically only newer ControlWave hardware
  • VTScada is not polling or processing alarms from devices
  • RBE is not used

Use Congestion Control

For BSAP networks only, this option prevents sending new messages to a local BSAP node if it reports multiple NAK responses. When this situation is detected, any new messages are put in a "Wait" state and will be sent only after the node responds with a non-NAK response. If the node does not respond with a non-NAK after 2 poll cycle times for the corresponding network, the message is dropped and an error raised in the driver.

Recover Comms Using NRT

For BSAP networks only, this option selects whether VTScada will send NRT (Network Routing Table) and Time Synchronization commands to a node that it detects is not responding. This is the Bristol-recommended means to recover dead nodes but can result in unnecessary network traffic if enabled. If not enabled, a standard poll message is sent to dead nodes to recover communication.

IBP Send Delay

When using IBP protocol, the VTScada Bristol Network tag can batch up several commands into a single UDP/IP packet for transmission to the RTU. This setting defines the time that the driver will wait after receiving a single command before sending to the RTU. If one or more commands are ready to send within the time limit, they will be added to the original packet destined for the RTU. If the time expires and no more commands are ready to send, then the packet is sent to the RTU. Increasing this time reduces the number of packets sent but can slow the communication down due to extra delays.

Network Time Zone

The time zone for all RTUs connected to a network tag. This is a global setting for a given Bristol Network and is used to both set the time in the RTUs when requested, and to properly decode the time-stamped data read from the RTUs.

Diagnostics Trace Level

Used to set the level of the diagnostics sent to a trace file hat is output to the application’s Data\TraceFiles directory. When set to 0, the diagnostics file output is not written. Values of 1 through 3 set the tracing level, with 3 being the most verbose. Note that this feature can impact system performance, particularly at level 3, and should be used only when network issues need to be diagnosed.

Level 1 Poll Rate (sec)

For BSAP networks only, the rate (in seconds) at which to poll the level 1 nodes. The VTScada Bristol driver follows the rules set out in the Bristol documentation for BSAP polling, refer to these documents for selecting an appropriate poll rate.

Max NAK Msgs

Maximum number of NAK responses before a node is placed in the Wait state

Delay on NAK Retry

The delay before retrying a NAK'd message (in seconds).

Time Sync IP Port #

On Ethernet connected RTUs (IBP), this setting is the UDP/IP port number on which the RTU will request time synchronization. The port number will normally be set to the default of 1235 unless it is changed in the configuration of the RTU.

Bristol Network properties Network Levels tab

Maximum RTUs for Level #n

Bristol RTUs on BSAP networks can be configured up to 6 levels deep using the store and forward capabilities of the protocol. Use these fields to define the maximum number of RTUs for each level of the network from which the driver generates the network routing table (NRT) to send to the RTUs.

For a given level, the title will show how many RTUs can be accommodated, but the BSAP global address space is limited to 15 bits so the number of RTUs chosen per level can sometimes limit the number of RTUs on subsequent levels. In these situations, the lower levels will be set to 0 and grayed out to prevent editing their values.

In the example shown above, level 1 can have 127 RTUs (7 bits), level 2 can have up to 31 RTUs (5 bits) and level 3 can have up to 7 RTUs (3 bits) for a total of 15 bits of address space used. Because there is no more address space available, levels 4 through 6 are set to 0 and cannot be edited.

NRT Version # (1-255)

When the NRT is sent to the network by the driver, it includes a version number that is used by RTUs on the network to determine if the NRT has changed. The VTScada driver defaults this value to 1 when a network tag is created, but it’s value should be changed by incrementing it by 1 every time the maximum number of RTUs on any of the levels are changed. This will guarantee that the updated NRT generated by the driver is accepted and propagated by all RTUs on the network. If the version number is at its maximum value of 255 and the network configuration is changed, set it back to 1 and start the sequence again.

Bristol Network properties IP Addresses Tab

IP for Alarm Reporting #n

Ethernet connected RTUs report their Alarms & Events along with Report by Exception (RBE) data to a user defined set if IP addresses and this of the Network tag allows you to configure these addresses. After you define the values here, the IP addresses are sent to the RTU whenever the NRT is sent. All IP addresses must be in a.b.c.d format – i.e. names are not allowed.

In order for VTScada to be able to set the NRT and clock of an Ethernet connected RTU, the IP address of the VTScada server must be defined as one of the RTU’s NHP servers using the Bristol "Flash Configuration" utility in the LocalView or NetView programs.

Acknowledge All Alarms

Select this option to force VTScada to send an acknowledge to all received IPB alarm messages even if there is no alarm handler present (i.e. a Bristol Driver tag with the correct address) to accept and report the received alarms. This option can be useful for cleaning alarms out of a master RTU that is reporting alarms for old RTUs that may no longer exist.

Closed Bristol Network Widgets

The following widgets are available to display information about your Bristol Network tags:

Comm Indicator Widget

Bristol Network Communication Messages Dialog

Bristol Network Statistics Dialog

Alarm Priority Box

Alarm Priority Icon


CalAmp Diagnostic Driver

Not counted towards your tag license limit.

The CalAmp diagnostic driver type enables users to read statistics from any given Integra-TR, Integra-H, Viper SC or Phantom II radio.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Reference Notes:

This driver was known as the Dataradio Diagnostic driver in earlier versions of VTScada.

These tags are required only in applications where you wish to gather data about a CalAmp unit.

For example, a common arrangement might be a CalAmp unit connected to your PC, and a secondary CalAmp unit connected to an RTU or PLC at a remote location. to collect data from the RTU or PLC, your VTScada application can use an appropriate communication driver tag such as Allen-Bradley or Modicon. If you wish to gather data about either CalAmp units in such a scenario (e.g. the temperature of the CalAmp unit), your application will require a CalAmp diagnostic driver tag.

In the unusual event that you have multiple devices attempting to use the same channel at the same time across multiple ports, you might consider adding Comm Link Sequencer Tags to serialize requests.

Related information:

CalAmp Driver I/O Addressing

Comm Link Sequencer Tags - Serialize requests for the same communication channel across ports.

Best Practices for Tags

CalAmp Diagnostic Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

CalAmp Diagnostic Driver properties Type tab

The Type tab of the CalAmp diagnostic driver tag properties folder is used to select the type of CalAmp unit that this tag is to represent. The choices, as shown include:

  • Integra-TR
  • Integra-H
  • Viper SC
  • Phantom II

CalAmp Diagnostic Driver properties Serial tab

The Serial tab of the CalAmp diagnostic driver tag properties folder is used to select the port to which the CalAmp unit associated with this tag is connected.

The port on the Data Radio unit, from which VTScada collects diagnostic information, is a true RS-232 serial port. To connect to this port with VTScada, you can use one of several different hardware solutions:

  • Serial port cable connected directly.

For this case, configure and select a Serial Port tag.

  • Stand alone serial modem connected to the serial port on the radio.

VTScada has its own modem that is used to dial up the modem connected to the radio. For this option, configure and select a serial port that is using a modem.

  • Ethernet terminal server connected to the serial port on the radio.

VTScada is connected to the same network as the terminal server and can connect to it with either a TCP/IP or UDP/IP port tag

  • RJ-45 Ethernet port on the radio (Viper SC and Phantom II radios only).

Any VTScada port tag may be used, but it must match the hardware connection to the radio.

Closed CalAmp Diagnostic Driver Tag Widgets

The following widgets are available to display information about your application’s CalAmp diagnostic driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget


CalAmp Driver I/O Addressing

Data can be obtained by reading from predefined addresses. The radios generate an ASCII string containing the diagnostic information.

An analog or digital tag should be configured for each item of diagnostic information. The address structure depends on the type of radio.

  • For Integra-TR and Integra-H, the address format is <radio ID>:<parameter>.

For example, to read supply voltage on radio 3, the address is "3:VOLT".

  • For Viper SC and Phantom II radios, the address format depends on whether the radio is in ROUTER or BRIDGE mode.
    • ROUTER mode: [IP address]:<parameter>
    • BRIDGE mode: [MAC address]:<parameter>

For example, with a radio in ROUTER mode, a valid address might be: "[192.168.6.254]:VOLT".

For Viper SC radios only, the source and destination radio addresses must be specified for the RRSSI and LRSSI parameters.

For example, a valid address could be "[192.168.1.205],[192.168.2.1]:RRSSI"

Where the source radio is 192.168.1.205 and the destination radio is 192.168.1.2

The following parameters are available:

All radios:

TEMP | Internal radio temperature, measured in degrees C.
VOLT | The radio supply voltage.
FPOW | The forward power, measured in Watts.
RPOW | The reverse power, measured in Watts.

Integra-TR and Integra-H radios:

RRSSI | The remote received signal strength, measured in dBm.
LRSSI | The local received signal strength, measured in dBm.
GRX | The number of good data blocks received out of the last 15.
TRX | The total number of data blocks detected, up to a maximum o f 15.

Viper SC radios:

RRSSI | The remote received signal strength, measured in dBm.
LRSSI | The local received signal strength, measured in dBm.
PER | The packet error rate.

Phantom II radios:

BRSSI | The background received signal strength, measured in dBm.
LRSSI | The local received signal strength, measured in dBm.
PER | The packet error rate.
THIN | The packet thinning value


CalAmp Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No Error
01 | 0x1 | Invalid Address
02 | 0x2 | Communication Failure
03 | 0x3 | Misaligned Stream
04 | 0x4 | Unrecognized Stream
05 | 0x5 | Stream Parsing Failure
06 | 0x6 | Write Not Supported


Campbell Scientific Array Driver

Not counted towards your tag license limit.

Create a Campbell Scientific Array driver tag to enable communications between VTScada and Campbell Scientific data loggers such as the model CR510 and CR10X units, which are running the older, array-based operating system.

Related information:

Campbell Scientific Array I/O Addressing

Campbell Scientific Error Codes

Best Practices for Tags

Related Application properties

The following properties hold additional configuration parameters for your Campbell Scientific Array driver:

CampbellProgressWindow - When enabled, a progress window will be displayed when the Campbell devices are downloading data. This will typically be enabled (i.e. set to 1) on larger systems using dedicated servers or disabled (i.e. set to 0) on systems using a single PC to act as a combination server & user workstation.

CampbellSharedRPC - When enabled, all Campbell devices share an RPC Service. This enables all Campbell device drivers to run on the same RPC server. If any should fail, then control for the entire group shifts. drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

CampbellTestMode - If true, data for Campbell devices should be read from a file, and not from the device. Should not be enabled unless testing specific functions of the driver.

CampbellCRSendCount - Sets the number of carriage returns (Enter keys) that should be sent when connecting to the Campbell devices. Normally, this should be set to 1.

CampbellCRSendWaitTime - Sets the amount of time (in seconds) VTScada will wait after each carriage return (Enter key) sent.

CampbellCRLFWaitTime - Sets the amount of time (in seconds) VTScada will wait for the asterisk character after CRs have been sent when initializing communication with the device.

CampbellCheckSig - If true, VTScada will check the signature bytes sent after each command response to the Campbell device. This should typically be enabled unless there is an application specific reason to disable it.

CampbellSearchWindowSize - Used for tuning by VTScada when searching for timestamps in the Campbell memory bank. The larger this window size, the quicker the search will be but the longer the download will be. The default of 2000 should be used in most circumstances. Valid values range from 100-65535.

CampbellReadAllFirstTime - When set (1), causes the driver to read all logged data in the device when communication is first established rather than new data only. This will be in effect only when the driver is created and connected to the device for the first time.

CampbellReadOnStart - When set (1), forces the driver to do a read of any new data in the RTU as soon as the driver is started instead of waiting until the first time it is polled.

CampbellNoLastMatchRequired - When not set (0), the driver will attempt to obtain an exact match of values for read-alignment of last readings with new readings. Can normally be left at its default value of 1.

Campbell Scientific Array properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Campbell Scientific Array properties Settings tab

The Settings tab includes properties

Port

The port used to communicate with the data logger. The driver supports the use of directly-connected serial ports, modem-connected serial ports, TCP/IP ports and UDP/IP ports.

Response Timeout

This is the number of seconds the driver tag will wait for a response message from the device. If the driver does not receive a response within the defined length of time it will try again according to the following parameter.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Final Storage Time Code

Defines the final storage time format used when programming the data logger. Note that, if the devices is using multiple storage arrays, the driver expects all arrays to use the same format. The time code is defined as follows, where "x" is defined as "don’t care" and is normally entered as a 0:

  • xxx1 Seconds (with resolution of 0.125 sec.)
  • xx1x Hour-Minute
  • xx2x Hour-Minute, 2400 instead of 0000
  • x1xx Julian Day
  • x2xx Julian Day, previous day during first minute of new day
  • 1xxx Year

Any combination of Year, Day, Hour-Minute, and Seconds is possible (e.g., 1011: YEAR, Julian Day, Hour-Minute, Seconds).

Maximum Read Block Size

The maximum number of words that will be read from the site RTU on each transfer when retrieving logged data from a device using the "F" command. (Refer to the addressing section for more details.) Data transfers larger than this size require multiple read operations. Decreasing this value reduces the chance of communications errors by using smaller packets, but it will also increase the transmission time for large-record polls. Recommended values for this setting are 512 for direct serial and TCP/UDP connected devices and 128 or 256 for modem connected devices. If your connection is subject to system noise, you may want to use smaller settings to increase communication reliability.

Device Clock Time Zone

The time zone of the clock in the data logger. This is used to correct the time-stamped values read from the device by VTScada for storage in its historian using UTC format. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for day-light savings time (DST).

  • Uses Server Time Zone (no DST) - assumes that the device is in the same time zone as the server.
  • Device Clock In UTC - the clock in the device is set to UTC.
  • Actual Time Zone - select the actual time zone, in which the device is located.
Closed Campbell Scientific Array Driver Widgets

The following widgets are available to display information about your Campbell Scientific Array driver tags:

Campbell Driver Pointers Widget

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget


Campbell Scientific Array I/O Addressing

Analog and digital tags that are connected to a Campbell driver tag require a I/O address format specific to the device. The addresses contain two identifiers: an Array ID (AID) and an index into the array. The description of these elements is beyond the scope of this document, but can be found in the Campbell Scientific documentation.

The format is as follows:

Aaa-ii

Where

A - Denotes the address as an array read

aa - Defines the array number

ii - Defines the index number in the array

For example, if the user wishes to access AID129, element 5, the appropriate string used in the address field of any Analog or Digital tag would be "A129-5".

Related information:

Campbell Scientific Array Driver


Campbell Scientific Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
000 | 0x0 | No Error
101 | 0x65 | Timed Out Waiting For Response
102 | 0x66 | Timed Out Waiting For Echo
103 | 0x67 | Data Conversion Error
104 | 0x68 | Incomplete Message Received
105 | 0x69 | Invalid Data Logger Pointer(s)
106 | 0x6a | Received Checksum Error
107 | 0x6b | Received Signature Error (Error Checking)
108 | 0x6c | Ready For Command Not Received
109 | 0x6d | User Cancel Request
110 | 0x6e | Serial Port/Modem Not Ready
111 | 0x6f | Invalid Command Sent
112 | 0x70 | Data Not Valid Error
113 | 0x71 | Error Calculating Checksum
114 | 0x72 | Error Calculating Signature
115 | 0x73 | Invalid Error Code
116 | 0x74 | Error While Searching for Time
117 | 0x75 | Receive Buffer Overrun
118 | 0x76 | Modem Failed To Connect
119 | 0x77 | Port/Modem Not Defined
259 | 0x103 | TCP/IP Port Connect Error
260 | 0x104 | TCP/IP Port Lost Connection


Campbell Scientific PakBus Driver

Not counted towards your tag license limit.

The Campbell Scientific PakBus driver enables communications between VTScada and Campbell Scientific data loggers running the PakBus operating system such as the model CR800 and CR1000 devices.

Related information:

Best Practices for Tags

Campbell Scientific PakBus I/O Addressing

Campbell PakBus Error Codes

Related Application properties

The following property settings hold additional configuration parameters for your Campbell Scientific PakBus driver:

PakBusClockAdjustDiff - The deadband for updating the RTU’s internal clock. If the data logger returns a clock time that differs by more than this parameter, the PakBus driver will send a message to adjust the data logger’s clock. The default value is 5.

PakBusSharedRPC - When enabled indicates that all PakBus Drivers should have a shared RPC Service. This enables all PakBus Drivers to run on the same server. If any should fail, then control for the entire group shifts. The default value is 0. drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

PakBusMoreRecsExistCheck - When the PakBus Driver reads records from a data logger, it continues to request data until the data logger response contains a "No More Records" flag. This parameter determines how many additional times the PakBus Driver must receive this message before it will stop the query. The default value is 1.

PakBusInvTableDefRetries - If the PakBus Driver receives an "Invalid Table Definitions" error from a data logger the driver will immediately attempt to obtain updated table definitions from the RTU. This can be a very time-consuming process because the driver will then have to poll the data logger for its entire history. PakBusInvTableDefRetries protects against false positives in this scenario. The PakBus Driver will only discard its current table definitions if it receives a number of consecutive "Invalid Table Definitions" errors equal to this parameter. The default value is 3.

PakBusInvalidDataPortTimeOut - The time to wait (in seconds) before declaring an error if the connection was not established. The default value is 5 seconds.

Campbell Scientific PakBus properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Campbell Scientific PakBus properties Communication tab

Port

The port used to communicate with the data logger. The driver supports the use of direct connected serial ports, modem connected serial ports, TCP/IP ports, UDP/IP ports, and PakBus RF Link tags.

RF ID

The RF ID is the identifier for the attached data radio on the RF network. This parameter is only used in conjunction with a PakBus RF Link tag and is ignored for serial or TCP/UDP connections.

Security Code

The security code that the logger will use. This value must match the setting defined in the data logger.

Logger PakBus Address

The PakBus address of the data logger. Each data logger that shares a common port tag must have a unique PakBus Address.

VTScada PakBus Address

The unique PakBus address assigned to VTScada on a PakBus network. By convention this value should be greater than 4000 and must not duplicate any other address on the network. The default is 4092.

Response Timeout (sec)

Determines how long the PakBus Driver will wait for a response from a data logger before reporting a communication error.

Comm Delay

Represents an additional delay expected for communicating on an RF network. When the PakBus Driver is connected to a PakBus RF Link tag, this value is used in building the network map that is transmitted by the base station. It is not used during direct communications with a serial or TCP/UDP port.

Link Timeout (sec)

Sets how long the PakBus Driver will wait before shutting down the PakBus link layer. This value should be set based on network performance, a typical range is between 3 and 10 seconds.

Connection Retries

This parameter sets the number of times that the PakBus Driver will attempt to per-form a poll. A poll will entail multiple messages, according to the configured number of retries.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Retry Delay (sec)

How long the PakBus driver will wait before retrying a poll.

Campbell Scientific PakBus Driver - Miscellaneous tab

Logger Type

Defines the type of data logger the driver is communicating with.

Read Data at Start-Up

Select this option to force the driver to read the latest values from the data logger when starting VTScada.

Clock Sync On Connect

Select this option to automatically synch the clock in the data logger to the server’s time clock when a connection with the device is established.

Store Last Output Values

If this check box is selected the last output values sent to the PakBus device will be saved or stored. These can be used to refresh the output values in the event of a communications failure or a power interruption.

Enable Auto Rewrite

If selected this box causes the last stored output values to be rewritten to the device in the event of a communications loss or power failure.

Device Clock Time Zone

The time zone of the clock in the data logger. This is used to correct the time stamped readings read from the device by VTScada for storage in its historian in UTC format. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for day-light savings time (DST).

  • Uses Server Time Zone (no DST) - assumes that the device is in the same time zone as the server.
  • Device Clock In UTC - the clock in the device is set to UTC
  • Actual Time Zone - select the actual time zone that the device is located in
Closed Campbell Scientific PakBus Driver Widgets

The following widgets are available to display information about your Campbell Scientific PakBus driver tags:

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Campbell PakBus Driver Info Widget

Plot Data Widget

Sparklines Widget


Campbell Scientific PakBus I/O Addressing

Analog Status and Digital Status tags that are connected to a PakBus driver tag require an I/O address format specific to the device. The addresses contain two identifiers separated by a colon: the table name and the field name in the format as shown.

TABLENAME:FIELDNAME

For example, if the user wishes to access the field "Batt_Volt_Avg" in table "Maint", for storage using an analog status tag, the address entered in the "History Address" setting of the Analog Status tag would be:

Maint:Batt_Volt_Avg

An address assist dialog will be available in I/O tags if you have a valid connection to a device as configured in the driver tag.

Use the drop-down lists to select the table and field from the options available on the connected device.


Campbell PakBus Error Codes

The generated error codes are a combination of the ID of the module creating the error plus the error code. For example, an error code of 0x0608 hex, is a combination of 0x0600 (GetTableDefinition) and 0x8 (Port connection failed).

Use hex rather than decimal to separate the module ID from the error message. In all cases, error messages make up the first (right-most) two bytes and the module ID value is stored in the next two.

Module ID Values

Module Number (Decimal) | Module Number (Hex) | Module
256 | 0x0100 | Unknown
512 | 0x0200 | VTS Read
768 | 0x0300 | Send Wake Up
1024 | 0x0400 | Build Message
1280 | 0x0500 | Say Hello
1536 | 0x0600 | Get Table Definition
1792 | 0x0700 | Get Logger Data
2048 | 0x0800 | Xmit / Rcv
2304 | 0x0900 | Clock Transaction
2560 | 0x0A00 | Receiver
2816 | 0x0B00 | Say Goodbye
3072 | 0x0C00 | Link Connect Ctrl
4096 | 0x1000 | VTS Write

Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No Error
01 | 0x1 | Invalid TX Buffer
02 | 0x2 | Echo Timeout
03 | 0x3 | Response Timeout
04 | 0x4 | Lost TX Semaphore
05 | 0x5 | Message Type Mismatch
06 | 0x6 | Message TID Mismatch
07 | 0x7 | RX Signature Mismatch
08 | 0x8 | Port Connection Failed
09 | 0x9 | Lost Port Connection
10 | 0xa | Table Not Defined
11 | 0xb | Invalid 'More Records' Flag
12 | 0xc | Wrong Table Number
13 | 0xd | Table Response Code Error
14 | 0xe | Bad BMP1 Packet Size
15 | 0xf | Bad Pakbus Packet Size
16 | 0x10 | Packet Number Mismatch
17 | 0x11 | File Upload Permission Denied
18 | 0x12 | File Upload Invalid Name
19 | 0x13 | File Upload Not Accessible
20 | 0x14 | File Upload Unknown Error
21 | 0x15 | Network Description Response Code Error
22 | 0x16 | BMP1 Packet Undeliverable
23 | 0x17 | Unmapped Driver
24 | 0x18 | Table Config not Read
25 | 0x19 | Field Read Only Flag is Set
26 | 0x1a | Permission Denied
27 | 0x1b | Invalid Table or Field Name
28 | 0x1c | Data Type Conversion Not Supported
29 | 0x1d | Memory Bounds Violation
30 | 0x1e | Timed Out Waiting for Link Semaphore
31 | 0x1f | Unexpected File Fragment In Response
99 | 0x63 | Unknown Error Code


CAT M5X Driver

The CAT M5X driver enables communications between VTScada and CAT Electronic Engine Controllers (ECC) and CAT Generator Set Controllers (GSC) through a Customer Communication Module (CCM) using the M5X communication protocol.

Each CCM can support multiple ECCs or GSCs but does have a limitation of 8 broadcast lists with 8 parameters each. Each CCM will require a CCM Manager tag which carries out all communications with the CCM. For each ECC or GSC connected to a CCM a CAT

The M5X Protocol driver is configured to read and write data for the individual controller.

Related information:

Best Practices for Tags

CAT M5X CCM Manager

Closed CATM5X Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

CAT M5X Driver properties: Configuration tab

CCM Manager Tag

CCM Manager tag that is configured for the CCM the ECC or GSC is connected to.

Controller Type

The type of controller you wish to gather data from, EMCP, 3400 or 3500. The controller type determines the parameter IDs available to read and write.

ECC/GSC Module ID

The module ID depends on the type of controller you have selected. The valid range for each controller is available in the drop down list.

Controller Type | Valid Module IDs
EMCP | 88, 89, 90, 91, 92, 93, 94, 95
3400 | 33, 34, 36
3500 | 33, 34, 35, 36, 37, 38, 40, 41

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Closed CAT M5X Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


CAT 5MX Addressing

The I/O tag addressing consists of a parameter ID which is specific to the controller type chosen. A drop down list of valid parameter IDs is provided in the address assist for this driver.

I/O Reads

I/O reads can be of type broadcast or single read. Reads configured as broadcast are added to the broadcast list for the CCM and the data will be broadcast at the specified interval. Single reads are requested at the specified interval in a command / response format.

0008:PID

Not all parameter IDs are supported by all models of a controller type. If a parameter ID is added to a broadcast list that is not supported by the controller, then the complete broadcast list will stop. Please refer to CCM documentation for the description, scaling and supported parameter IDs for a controller model

I/O Writes

I/O writes can use only the parameter ID (PID) format.

CAT M5X Address Select dialog

The CAT M5X address selection tool is available to I/O tags using this driver.

If you select an Address List item that is too high a number to be a broadcast list, then the following error message is shown:


CAT M5X CCM Manager

The CAT M5X driver enables communications between VTScada and CAT Electronic Engine Controllers (ECC) and CAT Generator Set Controllers (GSC) through a Customer Communication Module (CCM) using the M5X communication protocol.

Each CCM can support multiple ECCs or GSCs but does have a limitation of 8 broadcast lists with 8 parameters each. Each CCM will require a CCM Manager tag which carries out all communications with the CCM. For each ECC or GSC connected to a CCM a CAT M5X Protocol driver is configured to read and write data for the individual controller.

Related information:

Best Practices for Tags

CAT M5X Driver

Closed CATM5X Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

CAT M5X CCM Manager properties: Configuration tab

Port

The port tag through which this manager communicates to a device, usually either a serial port tag or a TCP/IP tag.

CCM Password

The default password is blank but valid passwords can be up to 8 characters long

Time Limit

The time in seconds that the CCM has to respond to a command

CCM Check Conn Interval

The time interval in seconds that the CCM Manager will send a Heartbeat message to the CCM to verify the connection.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Closed CAT M5X CCM Manager tag Widgets

The following widgets are available to display information about your tags:

Reset Broadcast List Manager (CAT CCM5)

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


CAT M5X CCM Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x00 | No Error
1 | 0x01 | Bad Address
2 | 0x02 | No Port Tag
3 | 0x03 | No Connection
4 | 0x04 | Writing Invalid Data
5 | 0x05 | Receive Checksum Error
6 | 0x06 | Receive Time Out
7 | 0x07 | Message Terminator Missing
8 | 0x08 | Broadcast List Full
9 | 0x09 | Invalid Broadcast List Number
10 | 0x0A | Broad List Setup Failed
11 | 0x0B | Bad Checksum or Command Format
12 | 0x0C | Unknown Instruction ID Received
13 | 0x0D | Unknown Parameter ID Received
14 | 0x0E | Data Write Failed
15 | 0x0F | Broadcast Data has Stopped
16 | 0x10 | Unknown Error


CSV Data Driver

The CSV Data Driver imports values from a comma-separated file(s). Originally developed for use with the Oil & Gas Solutions layer, this driver can be configured for use with any comma-separated values file.

(The driver can only import values. It will not write to a CSV file.)

I/O Tags configured to use the CSV Data Driver use a custom addressing scheme to assist the driver in assigning these values to the proper VTScada IO tag.

Data Processing

The CSV Data Driver will periodically check a specified folder for comma-separated files. When a file is found, and I/O tags are configured to use the CSV Data Driver, values from the file will be imported into VTScada, assigned to I/O tags and stored in the VTScada Historian. All files within the folder must have the same structure or format, including how date and time values are stored. If there is variation, use a separate CSV Data Driver for each version, and store those files either in separate folders or using separate extensions.

Archiving

When a file is processed successfully, it will be moved to an archival folder under the scanned folder using the following naming format:

C:\VTScada\<your application>\<scanned directory>\Archive\Year\Month

The CSV file name will have the date and short time appended to the file name:

<original filename>-2019-06-21-11-25.csv

Fault Handling

If configuration issues are encountered with the CSV Data Driver or with the IO tag addressing, the file will be moved to a Faults folder under the scanned folder as follows:

C:\VTScada\<your application>\<scanned directory>\Faults\Year\Month

The file will be renamed by appending the current date and time to the filename and the file extension will be changed to the error number of the configuration error. For example:

<original filename>.csv

Will be renamed to:

<original filename>-2019-06-21-11-25.csv101

Related information:

Best Practices for Tags

CSV Data Driver Addressing

CSV Data Driver Errors

Closed CSV Data Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

CSV Data Driver: File/DIR properties tab

Directory to Scan

Use to select the folder where the CSV files to be imported will be placed. The default location is a folder named "CSV Files" below your application's Data folder but, you may select any folder you wish.

Archive and Fault folders are created below the one specified here.

File Spec

Only files with the specified extension are read. Defaults to *.csv (The file extension is not case-sensitive.)

CMEP MEPMD01 Standard

Select if the data in your files is structured according to the California Metering Exchange Protocol standard. Must not be selected otherwise.

Header Row in File

Select if the first row in your CSV contains column headers rather than data.

File Uses Unique Keys

Select if rows contain unique identifiers specifying which location (and therefore tag) a value belongs to. Unique keys are optional but must be used if the CSV file contains data for more than one tag..

For example, the data file may contain temperature readings, all stored in a column identified as "Temperature". Those readings may come from several sites (Site 1, Site 2, ...) which are stored in a column identified as "Site". The unique keys are therefore "Site1, Site 2, ...". Addressing within your I/O tags will ensure that each site's temperature reading is written to the correct tag.

Key Column (0-based)

Identifies which column contains the Unique Key. Columns are counted from the left of each row, starting with zero.

Parameters in One Column

This is a choice between two possible formats of CSV file.

In format 1, there is a separate column for each type of parameter value. For example all temperature values in one column and all pressure values in another. If your CSV file follows this format, select this option.

In format 2, there are two columns (in addition to those for date and the optional unique identifier), where the first identifies the parameter, ("Temperature", "Pressure") and the second holds the value for that parameter. If your CSV file follows this format, select this option.

Parm Column (0-based)

If the option, Parameters in One Column is selected, use this to identify which column contains the parameter names. Columns are counted from the left of each row, starting with zero. The column holding the matching data values is specified as part of the I/O tag's address.

File Time Zone

If the data was collected in a time zone other than where the files are being processed, use this selector to identify that time zone.

Directory Scan Rate (secs)

Specifies how often VTScada will scan for new CSV files in the identified folder. Defaults to 3600, meaning hourly.

File Process Rate (secs)

Specifies a delay between processing of files, if more than one is found during a director scan. Defaults to zero, meaning no delay.

Trigger

May be linked to any tag or expression in order to initiate a directory scan as needed.

CSV Data Driver: Date/Time Mappings tab

Both date and time can be represented in many ways. Use this to configure the CSV Data Driver to read date and time values correctly according to how they are stored. All of the CSV files being read by this driver must use the same format.

Date values are mandatory and must be included in your CSV file. Time values are optional and will default as specified in this panel if not present.

The format of dates and times is described using "percent-specifiers", which are defined as follows.

%d- | Reads a value in the date up to a "-" as an integer
%d/ | Reads a value in the date up to a "/" as an integer
%d: | Reads a value in the date up to a ":" as an integer
%s | Reads a value as a string of characters until a space, or the end of the string, is reached. Typically used to read "AM" or "PM" in a time. ** Note: This can be used the same as %d above. For example, %s- will read a string of characters up until a “-“ is encountered in the date

"d" is used for all parts of the date and time; year, month and day / hours, minutes and seconds. Other configuration options specify the order of the parts where there may be ambiguity.

Following are several optional specifiers, useful for reading the date and time fields of the CSV Data Driver. Advanced users should also note that any specifier described in the VTScada Help for the BuffRead() function can be used.

%[^-]-

Reads a string of characters until the character after the “^” is encountered.
In this example, until a “-“ is encountered in the date.

Use if months in the date are textual (i.e. Jan or January)

“-“

“/”

“:”

<space>

Possible separators between each portion of the date. Examples follow:

01-17-2019 12:00:00 PM

%d-%d-%d %d:%d:%d %s

Or

01/17/2019 12:00:00 PM

%d/%d/%d %d:%d:%d %s

Time & Date Separate Columns

Select if your CSV file contains a separate column for time data. When not selected, configuration options related to a separate time column are disabled.

Date Column (0-based)

Identifies which column contains the Date. Columns are counted from the left of each row, starting with zero. Enabled only if you have specified that date and time are contained in separate columns.

Time Column (0-based)

Identifies which column (if any) contains the Time. Columns are counted from the left of each row, starting with zero.

Date Column Format

Use percent-specifier codes as described earlier to describe how dates (and times if both are in a single column) are formatted in your CSV files. All files read by this driver must use the same format.

Year Offset

If the year value in a date is written with four digits, there is no need for an offset.

If the year value is written with two digits, this number is added to the two-digit value. CSV files that contain dates that span the year 2000 must use four-digit dates.

Year Position

Identifies which number in a date string contains the year value. Counts from the left starting at one.

Month Position

Identifies which number in a date string contains the month value. Counts from the left starting at one.

Day Position

Identifies which number in a date string contains the day value. Counts from the left starting at one.

Default Time

All values are stored as UTC time stamps with both date and time. If a time value is not provided with the record, it is stored using the value specified here.

Time Format

Use percent-specifier codes as described earlier to describe how time values are formatted in your CSV files. . The CSV Data Driver assumes the timestamp uses the 12-hour clock and AM/PM is included in the CSV file data. The time suffixes, AM and PM, are not required if the timestamps use the 24-hour clock.

The Time Format string should always be modified to match the expected format of the timestamp format used in the CSV file. For example, if the timestamp does not include seconds, (for example, 02:00 PM), the Time Format string should be modified as follows:

%d:%d %s

Enabled only if you have specified that date and time are contained in separate columns.

Closed CSV Data Driver Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

CSV Data Driver Statistics Dialog

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


CSV Data Driver Addressing

The I/O tag’s History Address must be used when reading from the CSV Data Driver. Data is imported from a comma-separated file and the time of import is not used as the data timestamp

The addressing system to use in your I/O tags relates directly to the format of your CSV file. Three formats are supported. Formats 1 & 2 are flexible, and can be adapted to nearly any purpose. Format 3 follows the California Metering Exchange Protocol standard and files must adhere to that standard.

All files to be read by one CSV Data driver must have the same format. The format is specified within the driver. (CSV Data Driver)

For formats 1 & 2, a Date column is mandatory. A time value is optional but if provided, may be included as part of the date stamp, or as a separate column.

A Unique Key column is optional in format 1 but if provided, can be used to import similar data to multiple tags. For example, if the file has a single column for Temperature and no Unique Key column, then any (and every) tag watching for temperature values from this driver will be given the value from each row. If there is a Unique Key column, then only the tag watching for a temperature value from a specific site matching the Key will be given the value from that row. (Here, "Unique Key" refers to a site or other identifier within the data, not to any VTScada tag's Unique ID value.) The Unique Key is not case-sensitive.

If a comma-separated file does not have a Unique Key column, all data in a file column will be imported to any IO tags configured to that file’s column or parameter name.

You are able to configure the format used for Time and Date within the driver tag (CSV Data Driver: Date/Time Mappings tab).

Format 1

Columns may be in any order, but it is typical to begin with either Date or Unique Key. Use the tag addressing to identify which column contains which parameter. ("Req'd" -> "Required", "Opt." -> "Optional", "Recm'd" -> "Recommended")

Each parameter type is in a separate column. (Temperature, Pressure, etc.)

DDate (Req'd), Time (Opt.), Unique Key (Opt.), Parameter 1 value, etc ...
DDate (Req'd), Time (Opt.), Unique Key (Opt.), Parameter 1 value, etc ...

Format 2

Columns may be in any order, but it is typical to begin with either Date or Unique Key. The Unique Key is recommended.

DDate (Req'd), Time (Opt.), Unique Key (Recm'd), Parm Name, Parm Value
DDate (Req'd), Time (Opt.), Unique Key (Recm'd), Parm Name, Parm Value

Format 3

Refer to the California Metering Exchange Protocol standard. An example is provided here:

MEPMD01,20080501,SENSUS,TRAL:134000,91258124,B85460925,202007311236,1,OK,W,F,1.0,,1,202007310600,R0,78

Format 1 Tag Addressing

The acceptable IO tag addressing formats can be one of the following:

UNIQUE KEY::DATA COLUMN
::DATA COLUMN
DATA COLUMN

If “::DataColumn” or “DataColumn” is used as the addressing format, ensure the CSV Data Driver is configured not to use a Unique Key in the CSV data File.

Example: Given a Unique Key of 01-31-026-19W3...

01-31-026-19W3::12

Data is being read from the 12th column (where the first column in the CSV file is 0).

Format 2 Tag Addressing

The acceptable IO tag addressing formats can be one of the following:

UNIQUE KEY::DATA COLUMN{Parameter}
::DATA COLUMN{Parameter}

Example: Given a Unique Key of 88599886...

88599886::3{Pressure}
88599886::3{Temperature}

The column in the CSV file containing the data for each parameter is column 3 (where the first column in the CSV file is 0).

Format 3 Tag Addressing (CMEP MEPMD01)

The CSV driver can follow MEPMD01 but does not implement the entire protocol. Refer to the Pacific Gas & Electric website for detailed information about the protocol.

The acceptable IO tag addressing formats can be the following:

Receiver ID::Meter ID

For Example:

94563136::2

The Receiver ID in this example is 94563136 and the Meter ID is 2.


CSV Data Driver Errors

Error code (Decimal) | Error code (Hex) | Meaning
101 | 0x65 | IO Tag Missing Unique ID
102 | 0x66 | IO Tag Address Error (check Data Column)
201 | 0xc9 | CSV File illegal format
202 | 0xca | Application tags not configured for MEPMD01 CSV file data
301 | 0x12d | Could not resolve Date
302 | 0x12e | Could not resolve Timestamp
501 | 0x1f5 | Standard must be MEPMD01


Data Flow RTU Driver

Not counted towards your tag license limit.

Data Flow RTU drivers are used to provide an interface to a Data Flow RTU. Each Data Flow RTU driver provides for up to 18 installed Data Flow modules.

Data Flow RTU driver tags do not require polling drivers because they have their own polling features.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Related information:

Best Practices for Tags

Reference Notes:

Operators who do not have configuration privileges, but do have either "tag modify" or "manual data" security privileges can toggle the active polling state on or off if this tag is drawn as a Comm Indicator on a page. When the operator right-clicks on the Comm Indicator for the driver, a context menu will open, allowing the Active status to be changed.

When data is written to a Data Flow tag, it is immediately passed to the integrated Polling Driver tag and then on to the associated communication driver tag. Following each write, all I/O addresses will be read immediately so that feedback need not wait for the next polling cycle.

The Data Flow RTU driver can be represented on a Site Map.

Alarming

When polling fails-over from the primary server to a backup, VTScada automatically generates an alarm with priority 3 (warning). You can control this using application properties as follows:

  • BackupSwitchCount. Defaults to 30. The number of consecutive communication errors that need to occur when polling Data Flow RTUs before switching to the first specified backup server.
  • PollDriverAlarmDisable. Defaults to FALSE. In spite of the name, this property will decommission the alarm rather than disable it when set to TRUE.
  • PollDriverAlarmOnDelay. Defaults to 60 seconds. Avoids nuisance alarms from transient network issues.
  • PollDriverAlarmPriority. Defaults to 3 - Warning. Legacy applications may use the property BackupAlarmPriority for the same result.

Data Flow RTU Driver properties ID tab

The Data Flow RTU Driver type includes one extra field on the ID tab: The Station number, (also known as the RTU address) and the Digipeat route.
DFS stations can digitally repeat (digipeat) information to work around obstacles that block direct signals. Refer to the

DataFlow RTU ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Station Number(, RTU Address), Digipeat Route

The address of the destination station is first, followed by the station addresses of the RTU it passes through. For example, if you want to talk to station 3 through station 5, this field would be

3, 5

The RTU address is shown in brackets because the station number and RTU address can be different. (This is not common, but it does happen.) In this case, the station number is arbitrary and the RTU address configured on the device is the one to use.

Data Flow RTU Driver properties I/O tab

The I/O tab for a Data Flow RTU driver tag provides properties that can be used to establish a connection between this tag and the physical Data Flow RTU.

DataFlow RTU I/O tab

Serial Port Name

To connect to this port with VTScada, you can use one of several different hardware solutions:

  • Serial port cable connected directly.

For this case, configure and select a Serial Port tag.

  • Stand alone serial modem connected to the serial port on the radio.

VTScada has its own modem that is used to dial up the modem connected to the unit. For this option, configure and select a serial port that is using a modem.

  • Ethernet terminal server connected to the serial port on the unit.

VTScada is connected to the same network as the terminal server and can connect to it with either a TCP/IP or UDP/IP port tag

Any type of VTScada port tag may be used, but it must match the hardware connection to the unit.

Poll Interval

Enables you to set the amount of time (in seconds or in fractions of a second) between polls of the physical Data Flow RTU.

Note: If the Active check box is not selected, the associated Data Flow RTU will not be polled, regardless of the interval assigned in the Poll Interval (Sec) field.

Active

Specify whether the designated poll interval is active or idle.

If the Active check box is selected, the associated Data Flow RTU will be polled according to the interval assigned in the Poll Interval field.

If the Active check box is not selected, the associated Data Flow RTU will not be polled, regardless of the interval assigned in the Poll Interval field.

The active status can also be toggled by the operator if the tag is drawn as a Comm Status indicator. Right-clicking on that widget will open a menu with which the operator can change the active status. When drawn as a SiteDraw, the outer ring will turn purple when the driver is not active.

No Response Time Limit

Set the amount of time (in seconds or in fractions of a second) that VTScada will wait when an attempt to poll the Data Flow RTU has been made.

If no communication is made, the system will attempt to poll the station again, according to the setting in the Retries spin box. If the system is unable to poll the Data Flow RTU, the next RTU in sequence will be polled.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Full Refresh Time

Enter a number indicating the amount of time, measured in hours that the system should wait before doing a full refresh of data values from the Data Flow RTU.

Hold Values on Error

Specify whether data should be held in the event of a communications error with the Data Flow RTU.

If the Hold Values on Error check box is selected, the last received value from the Data Flow RTU will be retained otherwise, the data will be invalidated on error.

Group Poll Supported

Select this box to specify whether the Data Flow RTU represented by this tag belongs to a poll group (if group polling is supported by the radio interface module).

Service Port Connection

If selected, The service port enables communication with the RTU via serial devices (such as Lantronix). It is an alternative to using the DataFlow RIM card radio. The DataFlow protocol is slightly different through the service port. Minor differences will be observed, such as all responses being marked as station '0' and the absence of CRCs on messages that would otherwise have them.

Echo

Used if the Service Port Connection option has been selected. Enable or disable according to whether your device transmits an echo for each transmit operation.

Read RIM Analog Values

When selected, the driver will query the Radio Interface Module (RIM) for changes in analog values. Note that this is not supported by all Radio Interface Modules. Defaults to FALSE (unselected).

Data Flow RTU Driver properties Modules tabs

The Modules tabs of the Data Flow RTU driver tag properties folder enables you to select existing (or create new) Data Flow module tags to represent the Data Flow modules installed for this RTU (see Data Flow Module Tags). You may associate up to 18 Data Flow module tags with one Data Flow RTU driver.

The modules are divided between the tabs, Modules A-F, Modules G-L and Modules M-0.

DataFlow RTU module selection

Module A, B, etc.

Use the Module fields to identify which module installed at a physical RTU by selecting a Data Flow module tags.

To associate this tag with a set of Data Flow module tags, click the drop-down field to select the appropriate Data Flow module tag for each module.

Data Flow RTU Driver properties Location tab

The Location tab is used to define the placement (latitude and longitude) of the DataFlow station. Decimal values should be used rather than degrees, minutes and seconds.

You may find it easier to set the location using the map interface than to enter the latitude and longitude values here.

Latitude and Longitude

Holds location coordinates for this tag, thereby allowing it to be represented on a Site Map page.

Custom Details Page

If a custom details page has been created for this context tag, then that page should be selected here. If there is no custom details page, then operators will see the standard Site Details page upon clicking the pin for this tag in a Site Map.

Advanced Configuration:

The default page selection dialog has a filter for "all pages" or "site pages", meaning those that take a site tag as the first parameter.

You can add either of the following two properties in the Edit Properties page of the Application Configuration dialog to restrict this filter:

LimitPageListToSitesPages

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog for all users.

LimitPageListToSitesPagesIfRealmUser

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog if the user belongs to a security group.

Custom Map Icon

If a custom map icon widget has been defined, you can select it here. That icon will then be used instead of the standard pin when this tag is represented on a Site Map page. If there is no custom map icon, then the standard pin will be used.

Site List Display

Assuming that this tag has site properties, it will be included in the list of a Sites page. What will happen when an operator clicks on this tag in that list depends on the Site List display choice, and on whether any of this tag's children are I/O tags.

  • Display as Site: A click will open the Site Details page as a pop-up.
  • Display as Folder: A click will leave focus on the Sites page, but the list will now show the child tags of this site.
  • Exclude: This tag should not be shown in the Sites page list.

Map Zoom Level

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Related information:

Site Map

Closed Data Flow System RTU Widgets

The following widgets are available to display information about your application’s DataFlow RTU tags:

Active Indicator Widget

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

Data Age Widget

DFS Station Draw

Enable Polling Checkbox Widget

Equipment / Status Color Indicator

Fast Scan Widget

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Polled Station Widget

Site Draw Widget

Site Icon Widget

Site Summary Widget

Sparklines Widget

Tag List Widget

Toggle Polling Button Widget


Data Flow RTU Addressing

Analog cards store the analog values in addresses 1 through 4. For example, A1 would read Analog One from card A, (assuming that it is an analog card).

Some cards also provide support for reading digital information stored in slots 9 - 12. For digital and pulse cards, the values are read from addresses 1 through 12.

For Radio Interface Module (RIM) cards, the addressing is:

  • R1-12 are Digitals
  • R13 to R16 are Analogs (if present)

For PCU cards, the addressing is as follows:

  • 1-44 are Digital In
  • 49-56 are Analog In
  • 58-73 are Digital Output


DataFlow Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
257 | 0x101 | Port Error
259 | 0x103 | Port Not Connected
262 | 0x106 | Timed Out Waiting For Response
263 | 0x107 | Bad Received CRC
264 | 0x108 | Incomplete Response
265 | 0x109 | Digipeat station reported com failure
267 | 0x10B | Device Address Out Of Range
268 | 0x10C | Module Address Out Of Range
269 | 0x10D | Command Type Out Of Range
270 | 0x10E | Invalid parameters
271 | 0x10F | Analog write with less than 3 values
513 | 0x201 | VTSGetAddr Error
514 | 0x202 | Illegal address within a PCU
529 | 0x211 | Unexpected Response Address
530 | 0x212 | Unexpected Response Length
531 | 0x213 | Error Parsing Response
532 | 0x214 | Unknown Read Response
533 | 0x215 | Unexpected Write Response


Delta Driver

The Delta Driver supports both PLC and VFD (variable frequency drive) devices from Delta Electronics. Users can select a product type and model from the configuration folder, then within their I/O tags use an Address Assist dialog to build addresses that are compatible with the protocol for the selected device.

The communication protocol is standard Modbus, with RTU, ASCII, and TCP supported.

Delta drivers can import tags from a DIADesigner XML file. Configure your driver then use the Import button in the Tag Browser while the driver is selected. Only XML files can be selected. You must have both Tag Add and Tag Modify privileges in order to use this feature. Up to 16,000 tags can be included in one file.

The driver can interface with the following PLC lines. AS, AH, DVP3, DVP, AX, MC, and Delta VFD. Expand the following section for a reference showing which models of PLC fall under each line.

The application must be restarted after changing the hardware type.

Closed PLC Series and Firmware Versions
PLC Series PLC Model Firmware Version
DVP

DVP-ES/EX/SS/EC/EC2/EC3

DVP-SA/SC/SX

DVP-EH/SV/EH2/EH2L

DVP-ES2/EX2/SS2/SA2/SX2/MC/SE

DVP-EH3/EH3L/SV2

V4.7 and later

V1.0 and later

DVP 3

DVP-ES3/EX3

DVP-SV3/SX3

V1.0 and later
AS

AS100 Series

AS200 Series

AS300 Series

V1.0 and later
AH

AHCPU5X0-RS2

AHCPU5X0-EN

V1.0 and later
AX

AX-308E

AX-304EL

AX-364EL

AX-300N

AX-324N

V1.0 and later
MC

AS500E

AS500C

DVP50MC

DVP15MC

V1.0 and later

Related information:

Best Practices for Tags

Closed Delta Driver properties - ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Delta Driver properties - Options tab

Use the Options tab to select the hardware type and communication mode to be used by this driver.

At present, all communication modes are related to Modbus protocols, as implemented by Delta.

The application must be restarted after changing the hardware type.

Hardware Type

Select the appropriate device type from the list.

Communication Mode

Both Modbus RTU and Modbus ASCII use a serial communication mode

Select Modbus TCP if using an Ethernet communication mode.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

PLC Address

The station address of the Delta programmable logic controller. By default, the PLC Address field is set to 1.

An expression may be used to provide the address if needed. This may be required on a network where the address varies depending on the workstation where the tag is running.

Note that, to create a valid expression for an address that contains non-numeric characters, you must enclose the address in quotation marks. e.g. "31.0.0.0" See: Modbus Plus PLC Addressing.

Squelch Noise Present

Applies when communicating over a modem. Select this box to enable the squelching of background noise. By default, the Squelch Noise Present check box is not selected.

Reverse Long Integer Byte

Select whether byte swapping should occur for long integer values. By default, the Reverse Long Integer Byte check box is not selected.

Reverse IEEE Single Byte

Select whether byte swapping should occur for IEEE single byte values. By default, the Reverse IEEE Single Byte check box is not selected.

Reverse IEEE Double Byte

Select whether byte swapping should occur for IEEE double byte values. By default, the Reverse IEEE Double Byte check box is not selected.

Delta Driver properties - Communications tab

Port

Select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag. A Serial Port tag should be used for Modbus RTU and Modbus ASCII. A TCP/IP port should be used for Modbus TCP.

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Retry Delay

The Retry Delay field enables you to specify the amount of time (in seconds or fractions of a second) that the driver will wait between attempts to repeat a transmission of data if the previous attempt(s) have failed.

By default, the Retry Delay field is set to 0 (indicating that there should be no delay between retry attempts).

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

RTS Key Off Delay

The RTS Key Off Delay field represents the amount of time (in seconds) that this Delta Driver will wait before dropping RTS at the end of a data transmission.

Squelch Time

Sets the amount of time (in seconds or in fractions of a second) to wait before clearing noise. Enabled only when Squelch Noise Present has been selected on the Options tab.

Closed Delta Driver - Widgets

The following widgets are available to display information about your Delta Driver tags:Comm Indicator Widget

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Delta Driver Communication Messages Dialog

Delta Driver Statistics Dialog

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Text Widget

Numeric Value Widget

Multi-Color Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Delta Driver Addressing

The Delta Driver supports both Delta style addressing (such as D0 or X0.0) or standard 6-digit Modbus addressing (4XXXXX). Note that this differs from the VTScada Modbus Compatible driver, which supports both 5 and 6 digit addressing.

I/O tags using the Delta Driver provide access to an Address Select dialog, which supports Delta style addressing based on the Hardware Type selected.

You can read strings from register-based addresses in PLCs such as Delta and Modbus by setting the "String stored in registers" flag of the IO tag, along with specifying the length in bytes. See: I/O Tab, String data type layout

Addressing Prefixes

P | Parameter
CR | Control Command
SR | Status Monitor Read Only
OD | Option Device Information
RI | Remote IO
SD | String Display Description
ID | Internal General Definition

Address Types

The following table outlines the types of addresses available for each Hardware type and the type of data held in the address. To access the output bit of Timers (T) and Counter (C, HC), add ".0" to denote that data type instead of the value of the Timer or Counter.

In the format column, "D" denotes "decimal. "O" denotes "octal".

PLC Series
Address Type
AS AH DVP 3 DVP
Format | Range | Format | Range | Format | Range | Format | Range
X | Bit | DD.DD | X0.0~X63.15 | DD.DD | X0.0~X1023.15 | OOO | X0~X377 | OOO | X000~X377
Word DD X0~X63 DD X0~X1023 - - - -
Y | Bit | DD.DD | Y0.0~Y63.15 | DD.DD | Y0.0~Y1023.15 | OOO | Y0~Y377 | OOO | Y000~Y377
Word DD Y0~Y63 DD Y0~Y1023 - - - -
M | Bit | DDDD | M0~M8191 | DDDD | M0~M8191 | DDDD | M0~M8191 | DDDD | M0~M8191
D | Bit | DDDDD.DD | D0~D32767.15 | DDDDD.DD | D0~D1048575.15 | N/A | N/A
Word | DDDDD | D0~D32767 | DDDDD | D0~D1048575 | DDDDD | D0~D32767 | DDDDD | D0~D11999
S | Bit | DDDD | S0~S2047 | DDDD | S0~S2047 | DDDD | S0~S2047 | DDDD | S0~S1023
T | Bit | DDD | T0.0~T511.0 | DDD | T0.0~T2047.0 | DDD | T0.0~T511.0 | DDD | T0.0~T255.0
Word | T0~T511 | T0~T2047 | T0~T511 | T0~T255
C | Bit | DDD | C0.0~C511.0 | DDD | C0.0~C2047.0 | DDD | C0.0~C511.0 | DDD | C0.0~C199.0
Word | C0~C511 | C0~C2047 | C0~C511 | C0~C199
Bit - - - - - - DDD C200.0~C255.0
DWord - - - - - - C200~C255
HC Bit DDD HC0.0~HC255.0 DDD HC0.0~HC63.0 DDD HC0.0~HC255.0 - -
DWord HC0~HC255 HC0~HC63 HC0~HC255 - -
SM Bit DDDD SM0~SM4095 DDDD SM0~SM4095 DDDD SM0~SM4095 - -
SR Word DDDD SR0~SR4095 DDDD SR0~SR4905 DDDD SR0~SR2047 - -
E Word D E0~E9 D E0~E31 D E0~E9 - -

Delta AX Series PLC addressing using Modbus

The addressing assumes that the default offsets of 0 for MW, 256 for QW, and 0 for IW are set in DIA-Designer. If the offsets are adjusted, the VTScada addresses will need to differ from the PLC addresses to account for the change. As an example, given a PLC that has a QW offset of 300 for registers, then %QW0 on the PLC would be equivalent to %QW44 due to the change in offset.

Digital addressing:

Takes the form of MXI.J, where I is an offset in Bytes, and J is the offset in bits from the Byte offset. For example, if an address of MX0.3 is provided, the Modbus coil would be 100004. If an address of MX2.2 is provided the coil value is 100019.


Delta Driver Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
256 | 0x100 | Writing Invalid Data
257 | 0x101 | Illegal Function for the Addressed Slave
258 | 0x102 | Illegal Data Address in the Information Fields for the Addressed Slave
259 | 0x103 | Illegal Data Value in the Information Fields for the Addressed Slave
260 | 0x104 | Failure in Associated Device
261 | 0x105 | Acknowledge - Processing Programming Command
262 | 0x106 | Busy - Reissue Command Later
263 | 0x107 | Negative Acknowledge - cannot perform program function
264 | 0x108 | Memory Parity Error
266 | 0x10A | Gateway Path Unavailable
267 | 0x10B | Gateway Target Device Failed to Respond
512 | 0x200 | Illegal Memory Address in Read
513 | 0x201 | Illegal Memory Address in Write
515 | 0x203 | Error Opening Port
516 | 0x204 | Timed Out Waiting for Echoed Message
517 | 0x205 | Timed Out Waiting for Response from Remote
518 | 0x206 | Received Message CRC Error
519 | 0x207 | Unknown Error
520 | 0x208 | Attempting to Write Invalid Data to PLC
521 | 0x209 | Attempting to Send Invalid Read Msg to PLC
528 | 0x210 | No Path Available for Message
529 | 0x211 | Command Mismatch
530 | 0x212 | Response from Wrong Station
531 | 0x213 | Communication Channel Not Available
532 | 0x214 | Send/Receive Out of Sync
533 | 0x215 | Response from wrong data logger
534 | 0x216 | Corrupt or illegal MODBUS/TCP header
535 | 0x217 | Illegal value in response
536 | 0x218 | Purge of data log records failed
537 | 0x219 | Session Open Illegal Command
538 | 0x21A | Session Open Illegal Version
546 | 0x222 | Unknown Modbus Exception Code Returned
551 | 0x227 | Bad Transport Mode
768 | 0x300 | No Error
769 | 0x301 | Port Not Defined
770 | 0x302 | Port Failed To Connect
771 | 0x303 | Port Lost Connection
772 | 0x304 | Serial Port Settings Out of Range
773 | 0x305 | Serial Port Already In Use or Not Available
774 | 0x306 | Serial Port Access Denied
775 | 0x307 | Serial Port General Failure
776 | 0x308 | Serial Port Invalid Parameter
777 | 0x309 | Port Not Connected
784 | 0x310 | Port Unknown Error
29697 | 0x7401 | Command in packet is undefined
29698 | 0x7402 | Packet is longer than the maximum length
29699 | 0x7403 | Packet is shorter than the minimum length
29700 | 0x7404 | Packet is not correctly formed
29701 | 0x7405 | The byte length is incorrect
29702 | 0x7406 | Checksum error
29703 | 0x7407 | Non-ASCII characters are included


DNP3 Driver

Not counted towards your tag license limit.

This tag is a DNP3 Master, which implements all the objects defined in DNP subset level 3, except for the "Frozen Counter" type. The driver does not generate "Freeze" requests, or class enable/disable messages. The driver supports a number of other objects as listed in a following topic.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

DNP3 drivers will commonly connect to TCP on port # 20000, although variations may be found.

Reference Notes:

DNP3 Drivers may be configured to accept in-bound connections from an RTU via a configured IP Network Listener tag. In DNP3 terms this is a 'dual-endpoint' where the IP network listener allows this to be a 'listening endpoint'.

This driver has the ability to save the last value written to each output tag, and to rewrite those values, either automatically when lost communications are restored, or manually by the press of a button. Carefully review the information in the Options tab to decide whether this feature should be used in your application.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

As of VTScada version 12.1.39, drivers that do not have a suffix will use event-based polling. Refer to notes in DNP3DefaultNoScan and DNP3 I/O Addressing

Related information:

DNP3 I/O Addressing

DNP3 Error Codes

IP Network Listener Tags

Best Practices for Tags

DNP3 Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

DNP3 Driver properties Communications tab

Contains driver communication parameters. If the configured port is using a modem for communications to a DNP3 outstation, this tag may be configured to accept incoming phone calls.

Note:

  • The DNP3 broadcast addresses of 0xFFFD to 0xFFFF (65533 to 65535) are not supported in VTScada.
  • Address 0xFFFC (65532) is reserved for the "Self-Address". This address is not supported in VTScada.
  • Addresses 0xFFF0 to 0xFFFB (65520 to 65531) are DNP3 reserved addresses, which should not be used and therefore are not supported in VTScada.
  • Removing these addresses from the pool gives the allowable range in VTScada of 0x0000 to 0xFFEF (0 to 65519).

Communications tab found in the properties of the DNP3 Driver from the tag browser

Port

Enables you to select the Serial Port tag, TCP/IP tag or UDP/IP Port tag that you wish to be associated with this driver tag. A Serial Port tag opens a serial port to enable communications between VTScada and your PLC or RTU. A TCP/IP or UDP/IP tag enables you to connect to a series of hosts, allowing you to transmit data across a network or over the Internet. A port must be configured regardless of whether an IP Network Listener is also configured.

The Port field can be cleared using the X button that appears to its right.

Enable Modem Dial-In

Should be configured only if you expect the RTU to dial in using the VTScada Modem Manager. Do not use this option if an IP Network Listener is configured.

IP Network Listener Group

Configure only if this driver is to accept in-bound TCP or UDP communications. Select an existing IP Network Listener tag using the drop-down list. While a TCP connection is open, new connections will be rejected by the DNP3 driver.

If an IP Network Listener is configured, the Port tag must be a TCP/IP configured in client socket mode, or a UDP/IP tag.

IP Allow

Optional. Misconfiguration of this field is a common source of problems.

Used in connection with an IP Network Listener tag. General IP address filtering should be set on the IP Network Listener, as this will be more efficient. The list of allowed IP addresses in the driver is intended to prevent misconfigured devices from interfering with other devices.

Both filters (that in the Network Listener and this one) can be configured at the same time. The filter in the IP Network Listener will be applied when the device first connects and the local filter will be applied after a specific driver instance has been identified.

Time Out Limit

Sets the time in seconds or fractions of a second that this driver should wait for a reply from the remote unit.

RTS Key Off Delay

Sets the amount of time (in seconds) that this driver will wait before dropping RTS at the end of a data transmission.

Message Fail Time

The time interval for which VTScada will delay a failed message to allow other messages on the same port to be transmitted. This enables better performance when multiple RTUs share the same port and a message or messages to one RTU are timing out, thus slowing down communications to all RTUs. Usually set to 0 when there is only one driver using the port.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Redundant Multiplexer Connection

This setting is incompatible with the DriverMUX's Parallel or Alternating modes.

Used only in the case that two DNP3 drivers will be subordinate to a Driver Multiplexer. If selected, this setting will prevent activity if the driver is a DriverMUX inactive subordinate.

When in this mode (option selected, current driver is the inactive subordinate driver) the DNP3 Driver will almost completely shut down except for periodic checking of its communications link.

DNP3 Driver properties Data Link tab

Data Link tab found in the properties of the DNP3 Driver tag from the tag browser.

Master Address (VTScada)

The station address for VTScada. This is the "from" address in messages from VTScada to the RTU, and the "to" address in messages from the RTU to VTScada. The range is 0 to 65519 ()xFFEF).

Station Address

The station address for the RTU. The valid range for this parameter is 0 to 65519.
If a broadcast address will be used, the station address is set automatically to 65533 (self-address).

Broadcast Address

The DNP3 driver supports 3 special outstation broadcast addresses that will allow an RTU that receives them to process the message. The 3 addresses are:

  • 0xFFFD (65533) specifies that the outstation should not require confirmation for the broadcast received flag.
  • 0xFFFE (65534) specifies that the outstation should require confirmation for the broadcast received flag.
  • 0xFFFF (65535) specifies that the outstation may optionally require confirmation for the broadcast received flag.

Note that the use a broadcast address for a driver is of practical use only if the communications medium for that driver is also broadcast. For example, UDP to a broadcast address or Serial\TCP to a radio.

The only DNP3 objects that may be used by a driver employing a broadcast address are the Control Relay Output Block (CROB, g12v1) to set digital outputs and the Analog Output (g41v1-4) to set analog outputs.

As no replies are sent by outstations to the broadcast address, an instance of the driver using a broadcast address will never receive data.

An outstation that receives a broadcast message will indicate the fact in the Internal Indications value of a response, specifically the IINBroadcast flag. This is a publicly-accessible variable in each (non-broadcast) DNP3 driver instance that tracks the appropriate value in Outstation responses. Note that this value may be set for only a short period of time. Outstations may also generate events corresponding to the outputs set by broadcast, which will be reflected in I/O tags as per all other outputs.

DNP3 Driver properties Options tab

Use the properties within this tab to fine-tune the driver behavior, adjusting it for your particular hardware.

Options tab found in the DNP3 driver tag properties from the tag browser.

Poll Options - Disable Class x Reads

Disable Class 1, 2 and 3 Reads. Any of these three DNP3 data classes may be disabled independently. A class marked as disabled will not be read, even if the outstation indicates that class data is available.

Check RTU Interval

The interval (in seconds) at which VTScada should check for class 1, 2 and 3 event data in the RTU. This function performs two tasks: checks that the outstation is still functioning and checks to see if the outstation has an event pending, which may be read. The outstation's configuration will determine which data changes are reported by events.

If your RTU is configured to spontaneously send values as they change (unsolicited data) you may choose to set the Check RTU Interval value to a relatively large value, thus minimizing bandwidth while still ensuring that values have been sent.

The interval is the time since the last check. For example, if set to 3600 at 12:00, the RTU will be checked and the next interval is now scheduled for 1:00. But, if any event causes a new check to happen at 12:45, the next interval will be 1:45.

Enable Periodic Integrity Poll & Integrity Poll Interval

This option may not be required.

When selected, VTScada will send a request for all values every Integrity Poll Interval seconds, even though these values may not have changed.

An Integrity Poll will read all enabled Class 1, 2, and 3 events (changes) then all Class 0 (current) values. Note that Class 0 values may not include all data types - this depends entirely on the configuration of the DNP3 device.

Regardless of whether the Enable Periodic Integrity Poll option is set, there are three situations when an integrity poll will always occur:

When the driver becomes the I/O server. When an RTU signals that is has re-started. When an RTU signals that event buffers have overflowed.

History File Read Interval

Refer to WITS History Reads. Sets the interval in seconds for History Reads. This overrides any interval set in the tags that are configured with a DNP3 WITS history address. The default value is 600s. Note that only history files using the WITS format are supported.

Unsolicited Data Options - Enable Unsolicited Data

The Enable Unsolicited Data option must be selected for VTScada to listen for unsolicited event messages (exceptions) from the RTU.

Disable Class x Responses

These options are available only when the Enable Unsolicited Data option has been set. Disable Class x Response to prevent the RTU from spontaneously sending event messages for that class. This affects only unsolicited messages from the RTU.

Reconnect Action

Choose what action to take when a connection to an RTU is re-established. The default action is "None" because the connection is usually re-established by VTScada making a Read request. No additional action is required in this case.

In rare circumstances an RTU may make the connection, then send no data. The Poll For Events option exists so that you can direct the DNP3 driver to send a request for changed data when this occurs.

In older (pre-10.0.12) versions of the driver, a reconnect would always cause an integrity poll to be done. The Integrity Poll option exists for legacy application support.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

DNP3 Driver properties Advanced tab

By default, the outstation requests time synchronization by setting the IIN1.4 "Time Synchronization Required" flag. The DNP3 driver responds by sending a time sync message to the outstation.

Time Sync - Ignore Outstation Initiated Time Sync Request

If enabled, the DNP3 driver will not respond to a time synchronization request from the outstation. (Defaults to FALSE)

Enable Periodic Master Initiated Time Sync

If enabled, the DNP3 driver will send the time synchronization message to the outstation after a period of time set in Master Initiated Time Sync Interval.

Master Initiated Time Sync Interval

If Enable Periodic Master Initiated Time Sync is enabled, this field indicates the time period in seconds. (Default 3600 seconds)

Data Link Confirm

If set, every low level data link message will be confirmed by an acknowledgment. This option is generally used in an environment where there are unreliable communications due to the extra non-data traffic sent.

Timestamps are in Local Time

Controls how the driver will send and interpret received timestamps from the RTU. If selected, then timestamps are in local time. If FALSE, then timestamps are in UTC. For most applications, UTC is the proper way to work with timestamps. The local option exists for compatibility with legacy applications.

The default for the parameter is controlled by the application property, DNP3LocalTimestampsDefault. Applications upgraded from versions before VTS 10 will default to '1', but new applications will default to '0' (UTC).

You are advised to leave this option unselected in order to avoid issues related to daylight savings time transitions.

Closed DNP3 Driver Tag Widgets

The following widgets are available to display information about your application’s DNP3 driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


DNP3: TCP versus UDP

Many sites choose to use UDP rather than TCP for DNP3 connections, especially on cellular networks where it is important to reduce data usage and associated costs. These savings come at the cost of less efficient handling of packet-loss, slower notice of connection failure and increased application complexity. Trihedral does not recommend either protocol over the other, but offers the following information to help you choose which to use.

TCP has a direct overhead over UDP of 12 octets per packet sent. There are also TCP connection setup packets (SYN, SYN + ACK, ACK, 68, 68 & 64 octets respectively), each time a connection is made and TCP ACK messages to be sent, although these are often conveyed along with data, hence no overhead.

For a common DNP3 master message (for example, a class 0123 request with 27 octets), a TCP packet will contain 81 octets and a UDP packet will contain 69 octets giving a TCP overhead of 12/69 = 17.4%. For a common DNP3 maximum size response, a TCP packet will contain 346 octets and a UDP packet 334, a TCP overhead of 12/346 = 3.45%. As a DNP3 response often consists of multiple response packets, the average overhead will tend to be a little lower than 17% in the master to outstation direction, and a little more than 3.5% in the outstation to master direction.

The overhead figures show that UDP (as long as retransmissions are ignored) will use less octets on the link, but a dropped UDP packet is likely to cause a bigger retransmission (all application fragments will be resent) and hence more octets than with TCP (a small ACK will be sent requesting only the missing segment).

A system configured to use TCP in "disconnected mode", where the master closes the connection shortly after the outstation check poll and the outstation connects to the master when it has events to send, is the most efficient use of TCP, and requires an IP network listener tag for each local port in use. Only one IP Network listener is definitely required as all drivers could use the same port, with the DNP3 drivers configured for the IP Network listener group and the outstations configured to either connect to the last master IP, or have the master IP's statically configured along with the remote port to be used. The outstation also has to have the local port configured for incoming connections.

For UDP, the outstations still require configuration, either to connect to the last master IP, or have the master IP's statically configured, along with the local and remote port to be used.

In summary there is a little extra configuration at the master side for TCP, and nothing at the outstation, although TCP does require each outstation using a particular port to have a distinct DNP3 address (0 - 65519 are available).

With TCP, the protocol guarantees in-order packet delivery to the application, requesting retransmissions if necessary for missing packets. Failures of the connection are reported to the application which can take prompt recovery action (e.g. opening a new connection).

With UDP, there are no guarantees, as the application has to perform the TCP in-order reassembly functionality along with retransmission requests, and there are no indications to the application of issues in the transit to the remote apart from a lack of response. For VTScada drivers, the recovery will occur after the driver timeout limit for responses occurs.

TCP has built-in congestion control, handled by all components on the route, UDP has none, and when under capacity pressure, routers are more likely to drop or delay UDP packets as it's assumed applications running atop of UDP don't mind.

In summary, for DNP3 the tradeoff is a small increase in octets transmitted for TCP, but with better behavior with packet loss and more immediate notice of connection failure and a reduced application complexity. With the current DNP3 driver, UDP packet loss (or out-of-order packets) causes the whole DNP3 message to be retransmitted.


DNP3 I/O Addressing

DNP3 implementations vary widely between different equipment manufacturers. Before configuration of an application using the VTScada DNP3 driver, be sure to review the specific DNP3 implementation of your devices.

With release 12.1.39 of VTScada, the driver behavior has changed in the following ways for new applications. This behavior is controlled by the new property, DNP3DefaultNoScan. New applications have this property set to 1, whereas existing applications will have it undefined, which is the same as 0.

Addresses without a suffix

Polling will be event-based, unless the object itself does not support events, such as Time and Date, File Transfer.
New data is returned by Class polling or unsolicited messages whenever the value in the device changes beyond the constraints of deadband and debounce settings..

Addresses with :DR

Will use the standard VTScada interval-based polling, returning the current value of the point.

Addresses with :NS

Treated the same as addresses with no suffix.

For existing applications, addresses without a suffix will always use standard polling. To use event-based polling, :NS is required.

Addresses that do not support events will return an error if a suffix is added. Standard polling will always be used.

Within VTScada, DNP I/O addresses for all points except File Identifiers (object 70) are formatted in the following manner:

Obj/Var/Index[:NS | :LATCH | :PULSE]

Where:

  • Obj is the DNP object to use. A table of supported object types can be found later in this topic.
  • Var is the DNP variation of the object
  • Index is the points index. For the Restart flag in the Internal Indications (object 80, var 1) use an index of 7.
  • :NS is used to stop direct polls of the I/O address. DNP3 events and Class 0 Integrity polls will update the tag value regardless of the presence or absence of the :NS suffix. Note that DNP3 works most efficiently without direct polls.
  • :LATCH is used to indicate the output type is a latched control.
  • :PULSE is used to indicate the output type is a pulsed control. Use only with I/O tags with the data type set to Analog.

VTScada provides the DNP 3.0 Address Select dialog (Address Assist / Address Select) to help you build these addresses. In any tag that uses a DNP3 driver, the I/O panel of the configuration dialog will provide a button beside the Address field:

Click this to open the Address Select dialog.

To use this dialog, start by selecting the Group designation of the I/O device.
Available groups include:

  • Binary Input
  • Binary Output Status
  • Counter
  • Frozen Counter
  • Analog Input
  • Analog Output Status
  • Time and Date
  • Internal Indications
  • Octet String

If the Direct Poll option is not selected, then (for the appropriate groups) the suffix :NS will be added to the address and no variations may be applied.

Click the Direct Poll option to allow scanning and to enable the Variation selector, the content of which will vary according to the selected Group.

Binary Output:

Devices may use one of three control models:

  • Activation Model. A single signal. The output is activated for the duration of the on-time regardless of the code being sent.
  • Complementary Latch Model. A single output signal that is held at the commanded state.
  • Complementary Two-Output. Two outputs named close and trip. One or other output is set active momentarily for a commanded on-time and off-time.

The VTScada output address suffixes, :Latch, :Pulse, or no suffix indicating a Trip/Close control, relate to these models as follows:

For the following, the term "on-time" refers to the duration of the signal, not the value or control code sent in the signal.
By the DNP3 specification, timings are suggestions. The device may use the supplied timing, may limit the supplied timing to its own configured limits, or may substitute timing with its own configured values.
The suffix :LATCH should not be confused with the Complementary Latch Model of control.
To send an exact value of zero (0) or one (1), a Digital Control or Digital Output tag is recommended. To send any other value, use an Analog Control or Analog Output tag.

Trip/Close control (Analog types only. No suffix added to the address)

Use only with Analog Control or Analog Output tags. Values greater than zero send a close request (control code 0x41) and values equal to or less than zero send a trip request (control code 0x81).

The absolute value being written is the duration of the on-time, measured in milliseconds. Note that a value of zero, written by the tag, sends a trip request with an on-time of one millisecond. Scaling values must be set to allow the range of value that is being written, otherwise they will clamp the value.

  • Activation Model: The output is set to active for the duration of the on-time.
  • Complementary Latch Model: The output is set to active for a close (value > 0) or set to inactive for a trip (value <= 0).
  • Complementary Two-Output Model: Either the close output is set to active if a close (value > 0) is sent, or the trip output is set active for a trip (value <= 0), for the duration of the on-time.

Examples:

1 - sends a close request with an on-time of 1 millisecond.

0 - sends a trip request with an on-time of 1 millisecond.

1000 - sends a close request with an on-time of 1 second.

-1000 - sends a trip request with an on-time of 1 second.

:LATCH suffix

The DNP3 standard does support sending an on-time and off-time for the latch on|off codes, but this driver does not when the :LATCH suffix is in use. It always sets the times to 0, so is likely to be useful only with a complementary latch module output.

A Digital Control or Digital Output tag is recommended.

A value greater than zero (1) sends a latch-on request (control code 0x03).

A value less than or equal to zero (0) sends a latch-off request (control code 0x04).

  • Activation Model: The output is set to active.
  • Complementary Latch Model: The output is set active for a latch-on and inactive for a latch-off.
  • Complementary Two-Output Model: The output is set active for a latch-on and inactive for a latch-off.

Examples:

1 - sends a latch-on request.

0 - sends a latch-off request.

:PULSE suffix

Use only with Analog Control or Analog Output tags. The value to write should be a single value as shown in the examples, or else it must include both the pulse-on duration and the pulse-off duration in milliseconds, separated by a period. It is up to the RTU to hold the pulse for the specified durations - VTScada simply sends the information in one write. For example, to send an 8-second pulse control command to CROB #23, create an Analog Control tag with address 12/1/23:PULSE and use it to write a value of 8000 to the device.

Neither of the complementary models are supported.

Both an on-time and an off-time can be specified in milliseconds as follows. Given a numeric value, "nnn.fff"

  • The absolute value of the digits preceding the decimal point (nnn) specifies the on-time in milliseconds.
  • The absolute value of the digits following the decimal point (fff) specifies the off-time in milliseconds.

Positive values greater than zero (> 0) send a pulse-on request (control code 0.01).

Negative values (<= 0) send a pulse-off request (control code 0x02).

  • Activation Model: The output is set active for the duration of the on-time.
  • Complementary Latch Model: A "NOT-SUPPORTED" status will be returned.
  • Complementary Two-Output Model: A "NOT-SUPPORTED" status will be returned.

Examples:

The following are values to write to an Analog Control tag:

1 - sends a pulse-on request with an on-time of 1 millisecond and an off-time of 0.

0 - sends a pulse-off request with an on-time of 0 milliseconds and an off-time of 0. This may cause an error as there should normally be some value for the on-time.

-1 - sends a pulse-off request with an on-time of 1 milliseconds and an off-time of 0.

5000.999 - sends a pulse-on request with an on-time of 5 seconds and an off-time of 0.999 seconds.

-4000.003 - sends a pulse-off request with an on-time of 4 seconds and an off-time of 3 milliseconds.

Select Before Operate (:SBO)

To set a point to use SBO rather than direct operate, append the suffix ":SBO" to the I/O address. The SBO suffix can be used in combination with the other output attribute suffixes, ":PULSE" or ":LATCH".

This suffix is available as an option in the DNP3 address assist dialog when building a binary output command.

Reads

Address examples for reading values:

To read a digital input with status (obj 1, var 2) at address 4321 use

1/1/4321.

To read a 32 bit delta counter without status (obj 20, var 7) at address 876 use

20/7/876

WITS History Reads

A History Read address takes the form G/V/INDEX:HW:FILENAME, where:

  • G is the DNP3 "group", the supported groups are 1 (Binary Input), 10 (Binary Output status), 20 (Counter), 30 (Analog Input), and 40 (Analog Output Status).
  • V is the DNP3 variation, for History Reads this should be 0 (all variations).
  • INDEX is the point index.
  • The ":H" suffix indicates a History Read.
  • W is the history type, currently only WITS is supported so the type is "W".
  • ":FILENAME" is the name of the history file to read. At time of writing, only the WITS global all points log file is supported. This has a filename of "WITSLOG\D_A_GB__X_X" which is the default.

An example of an actual WITS History Read address is:

 "30/0/1:HW:WITSLOG\D_A_GB__X_X".

Outstation Directory Reads

Outstation directories may be read using an I/O address as follows:

70/5/DirectoryPath,READDIR

Where:

  • DirectoryPath is the path to the directory to be read. This will vary by outstation.

The normal use for this will be from script via a Read command.

Example:

ReadObj = Variable("DriverName")\DriverRead("70/5//data,READDIR", 1, &Result)

ReadObj will go invalid on completion.

Result will be set to an 2D array of directory entries, one row for each entry where the columns are as follows:

[0] | Entry name | Either file name or a sub-directory name
[1] | Entry Type | 1 for a file, 0 for a sub-directory
[2] | Entry size | File length for a file, number of entries for a sub-directory
[3] | Timestamp | UTC
[4] | Permissions* | The permissions for the entry

* DNP3 File permissions are a set of 9 bits, indicating read, write and execute permissions for the user, group and world. Normally written in octal, the value 0777 is "all permissions for all classifications". The exact meaning of the bits is outstation-dependent.

DNP3 File Reads

Files may be read from the outstation using an I/O address as follows:

70/5/PathToFile

Where:

  • PathToFile includes the path for the file. This will include forward slashes for directories. The exact path will depend on the outstation - see example.

Example:

ReadObj = Variable("DriverName")\Driver\Read("70/5//data/newdata.txt", 1, &Result)

The result will be available as a buffer when the ReadObj goes Invalid.

DNP3 File Writes

Files may be written to the outstation using an I/O address as follows:

70/5/PathToFile[,Timestamp[,Permissions[,Append]]]

Where:

  • PathToFile includes the path for the file. This will include forward slashes for directories. The exact path will depend on the outstation - see example.
  • The optional parameter, Timestamp, is the timestamp for the file on the outstation in seconds since 1/1/1970, UTC. The default is the current time of the I/O server (in UTC).
  • The optional Permissions* are the permissions for the file. The default is 0777.
  • Append is a flag indicating the behavior of the write if the indicated file already exists on the outstation. If TRUE, the file will be appended to. If FALSE, the file will be overwritten by the new data. The default is false (no append)

The normal use for this will be from script via a Write command.

Example:

WriteObj = Variable("DriverName")\Driver\Write("70/5//data/newdata.txt", 1, &FileStrm, Invalid, "SomeText", &Result)

Result will become valid after the file write has completed - TRUE for success, FALSE for failure. In addition, WriteObj will become invalid on completion.

FileStrm, the data to be written to the outstation file, can be a stream or a buffer. In the example given, the file to be written to is "/data/newdata.txt". The paths used will depend on the outstation.

DNP3 File Deletions

Files may be deleted from the outstation using an I/O address as follows:

70/5/PathToFile,DELETE

Where: PathToFile includes the path for the file to be deleted.

The normal use for this will be from script via a Write command.

Example:

WriteObj = Variable( "DriverName")\Driver\Write( "70/5//data/newdata.txt,DELETE", 1, &FileStrm, Invalid, "SomeText", &Result)

Note that some valid data must be provided as the data parameter (FileStrm) but it's contents are ignored.

DNP3 object types supported

Please refer also to the Implementation Table of the document, DNP3DeviceProfileApril2016.xslt, included with your VTScada program.

Object Description | Object Type | Object Variation | Read | Write
Single bit binary input all variations | 1 | 0 | Ö |
Single bit binary input | 1 | 1 | Ö |
Single bit binary input with status | 1 | 2 | Ö |
Single bit binary input event all variations | 2 | 0 | Ö |
Single bit binary input event without time | 2 | 1 | Ö |
Single bit binary input event with time | 2 | 2 | Ö |
Single bit binary input event with relative time | 2 | 3 | Ö |
Single bit binary output all variations | 10 | 0 | Ö |
Single bit binary output status | 10 | 2 | Ö |
Control relay output block | 12 | 1 |  | Ö
Binary counter all variations | 20 | 0 | Ö |
32 bit binary counter | 20 | 1 | Ö |
16 bit binary counter | 20 | 2 | Ö |
32 bit delta counter | 20 | 3 | Ö |
16 bit delta counter | 20 | 4 | Ö |
32 bit binary counter without status | 20 | 5 | Ö |
16 bit binary counter without status | 20 | 6 | Ö |
32 bit delta counter without status | 20 | 7 | Ö |
16 bit delta counter without status | 20 | 8 | Ö |
Frozen binary counter all variations | 21 | 0 | Ö |
Frozen 32 bit binary counter with status | 21 | 1 | Ö |
Frozen 16 bit binary counter with status | 21 | 2 | Ö |
Frozen 32 bit delta counter with status | 21 | 3 | Ö |
Frozen 16 bit delta counter with status | 21 | 4 | Ö |
Frozen 32 bit binary counter with time | 21 | 5 | Ö |
Frozen 16 bit binary counter with time | 21 | 6 | Ö |
Frozen 32 bit delta counter with time | 21 | 7 | Ö |
Frozen 16 bit delta counter with time | 21 | 8 | Ö |
Frozen 32 bit binary counter no status | 21 | 9 | Ö |
Frozen 16 bit binary counter no status | 21 | 10 | Ö |
Frozen 32 bit delta counter no status | 21 | 11 | Ö |
Frozen 16 bit delta counter no status | 21 | 12 | Ö |
Binary counter event all variations | 22 | 0 | Ö |
32 bit binary counter event without time | 22 | 1 | Ö |
16 bit binary counter event without time | 22 | 2 | Ö |
32 bit delta counter event without time | 22 | 3 | Ö |
16 bit delta counter event without time | 22 | 4 | Ö |
32 bit binary counter event with time | 22 | 5 | Ö |
16 bit binary counter event with time | 22 | 6 | Ö |
32 bit delta counter event with time | 22 | 7 | Ö |
16 bit delta counter event with time | 22 | 8 | Ö |
Frozen binary counter event all variations | 23 | 0 | Ö |
Frozen 32 bit binary counter event without time | 23 | 1 | Ö |
Frozen 16 bit binary counter event without time | 23 | 2 | Ö |
Frozen 32 bit delta counter event without time | 23 | 3 | Ö |
Frozen 16 bit delta counter event without time | 23 | 4 | Ö |
Frozen 32 bit binary counter event with time | 23 | 5 | Ö |
Frozen 16 bit binary counter event with time | 23 | 6 | Ö |
Frozen 32 bit delta counter event with time | 23 | 7 | Ö |
Frozen 16 bit delta counter event with time | 23 | 8 | Ö |
Analog input all variations | 30 | 0 | Ö |
32 bit Analog input | 30 | 1 | Ö |
16 bit Analog input | 30 | 2 | Ö |
32 bit Analog input without status | 30 | 3 | Ö |
16 bit Analog input without status | 30 | 4 | Ö |
Float Analog input without status | 30 | 5 | Ö |
Double Analog input without status | 30 | 6 | Ö |
Analog input event all variations | 32 | 0 | Ö |
32 bit Analog input event without time | 32 | 1 | Ö |
16 bit Analog input event without time | 32 | 2 | Ö |
32 bit Analog input event with time | 32 | 3 | Ö |
16 bit Analog input event with time | 32 | 4 | Ö |
Float Analog input event without time | 32 | 5 | Ö |
Double Analog input event without time | 32 | 6 | Ö |
Float Analog input event with time | 32 | 7 | Ö |
Double Analog input event with time | 32 | 8 | Ö |
Analog output all variations | 40 | 0 | Ö |
32 bit Analog output status | 40 | 1 | Ö |
16 bit Analog output status | 40 | 2 | Ö |
Float Analog output status | 40 | 3 | Ö |
Double Analog output status | 40 | 4 | Ö |
32 bit Analog output | 41 | 1 |  | Ö
16 bit Analog output | 41 | 2 |  | Ö
Float Analog output | 41 | 3 |  | Ö
Double Analog output | 41 | 4 |  | Ö
Time and Date | 50 | 1 | Ö | Ö
Common Time Object | 51 | 1 | Ö |
Common Time Object - unsynchronized | 51 | 2 | Ö |
Time delay coarse | 52 | 1 | Ö |
Time delay fine | 52 | 2 | Ö |
Class 0 Event data | 60 | 1 | Ö |
Class 1 Event data | 60 | 2 | Ö |
Class 2 Event data | 60 | 3 | Ö |
Class 3 Event data | 60 | 4 | Ö |
File Identifier (older systems) | 70 | 1 | Ö | Ö
File Identifier (preferred object for newer systems) | 70 | 5 | Ö | Ö
Internal Indications object | 80 | 1 |  | Ö
Octet String | 110 | *(1) | Ö | Ö
Octet Change Object | 111 | *(2) | Ö |

*(1) The variation in the I/O address is used to set the length of the string. If the string is shorter than the variation, it is right-aligned and padded with spaces to fit the variation.

The DNP3 driver allows the use of an additional suffix, ":SL" that overrides the variation with the length of the supplied string, thus allowing callers to pass in arbitrary strings and not have to modify the variation element of the I/O address. The ":SL" suffix is only valid for Octet string writes. Octet strings are limited to 0..255 bytes. Anything attempted outside this range will cause the driver to report an error.

*(2)Event\change objects would not normally be configured as I/O addresses. They are listed to indicate that processing support is provided them. Upon receiving an event\change object, the value of the corresponding static object will be updated. For example, if 110/255/6 is configured and an event is received for 111/13/6, then the tag reading the first address will be updated with the value from the event\change as they share the same index.

Static\event object pairs that obey this rule include:

  • g1 Binary Input and g2 Binary Input change
  • g10 Binary Output and g11 Binary Output change
  • g20 Counter and g22 Counter change
  • g21 Frozen Counter and g23 Frozen Counter change
  • g30 Analog Input and g32 Analog Input change
  • g40 Analog Output and g42 Analog Output change
  • g110 Octet Strings and g111 Octet String change

Data values returned for the objects that may be read:

Object Description | Return Value
Single bit binary input | 0 or 1.
Single bit binary input with status | If status is OK, 0 or 1, else invalid.
Single bit binary input event without time | If status is OK, 0 or 1, else invalid. Refer to the note following this table.
Single bit binary input event with time | If status is OK, 0 or 1, else invalid. Refer to the note following this table.
Single bit binary output status | If status is OK, 0 or 1, else invalid.
32 bit binary counter | If status is OK, 32 bit unsigned integer, else invalid.
16 bit binary counter | If status is OK, 16 bit unsigned integer, else invalid.
32 bit delta counter | If status is OK, 32 bit unsigned integer, else invalid.
16 bit delta counter | If status is OK, 16 bit unsigned integer, else invalid.
32 bit binary counter without status | 32 bit unsigned integer.
16 bit binary counter without status | 16 bit unsigned integer.
32 bit delta counter without status | 32 bit unsigned integer.
16 bit delta counter without status | 16 bit unsigned integer.
32 bit binary counter event without time | If status is OK, 32 bit unsigned integer, else invalid. Refer to the note following this table.
16 bit binary counter event without time | If status is OK, 16 bit unsigned integer, else invalid. Refer to the note following this table.
32 bit delta counter event without time | If status is OK, 32 bit unsigned integer, else invalid. Refer to the note following this table.
16 bit delta counter event without time | If status is OK, 16 bit unsigned integer, else invalid. Refer to the note following this table.
32 bit binary counter event with time | If status is OK, 32 bit unsigned integer, else invalid. Refer to the note following this table.
16 bit binary counter event with time | If status is OK, 16 bit unsigned integer, else invalid. Refer to the note following this table.
32 bit delta counter event with time | If status is OK, 32 bit unsigned integer, else invalid. Refer to the note following this table.
16 bit delta counter event with time | If status is OK, 16 bit unsigned integer, else invalid. Refer to the note following this table.
32 bit Analog input | If status is OK, 32 bit signed integer, else invalid.
16 bit Analog input | If status is OK, 16 bit signed integer, else invalid.
32 bit Analog input without status | 32 bit signed integer.
16 bit Analog input without status | 16 bit signed integer.
32 bit Analog input event with time | If status is OK, 32 bit signed integer, else invalid. Refer to the note following this table.
16 bit Analog input event with time | If status is OK, 16 bit signed integer, else invalid. Refer to the note following this table.
32 bit Analog input event without time | If status is OK, 32 bit signed integer, else invalid. Refer to the note following this table.
16 bit Analog input event without time | If status is OK, 16 bit signed integer, else invalid. Refer to the note following this table.
32 bit Analog output status | If status is OK, 32 bit signed integer, else invalid.
16 bit Analog output status | If status is OK, 16 bit signed integer, else invalid.
Time and Date | The current date and time in the outstation as a floating-point number representing the number of milliseconds since Jan 1 1970.
File Identifier | A buffer containing the records requested, or an individual value of the specified type from the specified offset in a specified record.
Octet String | A buffer containing the string.

Note: For events, the return value is an array of five elements:

Index | Element
0 | The address of the point in the form Object/Variation/Address.
1 | Value, after correction for any status flags. If the status is on-line, not restart and not communication lost, the value will be as reported in the event, otherwise the value will be invalid.
2 | The timestamp of the event.
3 | The actual value before correction for status flags
4 | The status flags.

For those events that return a time, the time will be as recorded in the device. For those events that do not return a time, the time will be the local time when the driver received the message.

Time values are returned as a double, representing the time as the number of milliseconds since midnight, on 1/1/1970.

The data values that may be supplied for output objects:

Object Description | Data Value
Control relay output block | 32 bit signed integer. If > 0, then action will be a latch on, close or raise. The time for the raise will be the value supplied in units of milliseconds. If =< 0, then action will be a latch off, open or lower. The time for the lower will be the absolute value supplied in units of milliseconds. The Latch flag, if TRUE, will cause the output to be a latch type.
32 bit Analog output | 32 bit signed integer.
16 bit Analog output | 16 bit signed integer.
Float Analog output | IEEE Single Precision Floating (4 bytes)
Double Analog output | IEEE Double Precision Floating (8 bytes)
Time and Date | The data value is ignored. The current date and time of the VTScada system will be sent to the outstation.
File Identifier | A buffer containing the records to be written.
Internal Indications | 16 bit unsigned integer. Note that only certain values are allowed and will be detailed in the remote device's profile.

Note to VTScada programmers who are using the DNP3 driver in their code:

The following flags are available in the VTScada layer of the driver and will be updated by every response from the remote station:

Flag | Meaning
IINTimeSync | TRUE when Time sync is required by the Outstation.
IINLocalDO | TRUE when some DO's in the Outstation are in local control.
IINTrouble | TRUE when an abnormal condition exists in the Outstation.
IINRestart | TRUE when an Outstation restart has occurred.
IINEventOverflow | TRUE when Outstation event buffers have overflowed.
IINConfigCorrupt | TRUE when Outstation configuration is corrupt.


DNP3 Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
257 | 0x101 | Serial Port Parameter(s) Out of Range
258 | 0x102 | Serial Port Not Active
259 | 0x103 | TCP/IP Port Failed to Connect
260 | 0x104 | TCP/IP Port Disconnected
261 | 0x105 | Serial Port Already in Use
262 | 0x106 | Communication Channel Not Available
287 | 0x11F | Serial Port General Failure
343 | 0x157 | Serial Port Invalid Parameter
512 | 0x200 | Data Link - Invalid Command
513 | 0x201 | Data Link - Timed Out Waiting for Echo
514 | 0x202 | Data Link - No Reply
515 | 0x203 | Data Link - No Acknowledge
516 | 0x204 | Data Link Reset - No Acknowledge
768 | 0x300 | Station address out of range
769 | 0x301 | Object type or variation out of range
770 | 0x302 | Object variation out of range
771 | 0x303 | Point address out of range
772 | 0x304 | Data type out of range
773 | 0x305 | Invalid parameters
774 | 0x306 | RTU - Function code not implemented
775 | 0x307 | RTU - Requested objects unknown
776 | 0x308 | RTU - Request parameters out of range
777 | 0x309 | RTU - Event buffers overflow
778 | 0x30A | RTU - Requested operation pending
779 | 0x30B | RTU - Configuration corrupt
780 | 0x30C | Start record out of range
781 | 0x30D | End record out of range
782 | 0x30E | Invalid file operation
783 | 0x30F | Missing File name
784 | 0x310 | File does not exist
785 | 0x311 | Out of file space
786 | 0x312 | File access denied
787 | 0x313 | File in use
788 | 0x314 | Too many files are currently open
789 | 0x315 | File handle not valid
790 | 0x316 | Device lost comms with file location
791 | 0x317 | Handle closed due to inactivity
792 | 0x318 | Fatal file processing error occurred
793 | 0x319 | File block sequence incorrect
794 | 0x31A | Timeout waiting for delayed response
795 | 0x31B | Received file not of expected size
796 | 0x31C | File size exceeds limits
797 | 0x31D | RTU - Device specific problem
798 | 0x31E | Driver currently disabled
799 | 0x31F | Control operation rejected
800 | 0x320 | Select operation rejected
801 | 0x321 | Bad address suffix


Driver Multiplexer

Not counted towards your tag license limit.

Driver multiplexer (DriverMUX) tags allow you to set up redundant or alternate lines of communication between I/O tags and equipment.

This refers specifically to communication between the I/O tag and equipment, not between the driver and equipment.

Certain drivers, notably the CIP, will generate their own communication traffic in order to do health checks or update addressing. Because the DriverMUX does not stand between the driver and the PLC, it has no control over this automatically generated traffic.
Health checks are not performed when the DriverMUX is in Alternating mode.

Configuration Considerations for Driver Multiplexer

It is recommended that all communications go through the DriverMUX tag(s) and not through the subordinate drivers. See DriverMUX I/O Addressing for more details.

Driver Multiplexer cannot be used with devices that are limited to a single connection. Trying to make multiple connections to a device's serial port using an IP-to-Serial adapter will not work.

The Driver Multiplexer will not work if you have enabled SharedRPC mode for your communications driver. This mode prevents the DriverMUX from detecting that one driver has failed.

If the subordinate drivers feature the Hold setting in their Communications configuration (for example, DNP3 drivers), both subordinates must have this setting configured the same way. Either both enabled or both disabled. A difference in configuration may result in outdated data appearing after a failover.

Common uses for Driver Multiplexer

  • Establishing a fail-over communications route in the event that one driver is lost.

In its basic configuration, the DriverMUX tag will direct all communications to the primary driver. In the event that the connection to the primary driver is lost, communication will switch to the secondary driver.

  • Upgrading to new communications equipment/drivers with zero downtime.

In this scenario, you would install the new equipment and drivers while the existing system remains in place. The new drivers would be connected to the DriverMUX tag instead of directly to your I/O devices. When you are ready to test the new system, you can direct the DriverMUX to switch to the new, secondary system. If there are problems, then communication will immediately and automatically switch back to the primary system with no loss of data.

  • Load sharing between two lines of communication.

The DriverMUX tag can be directed to use both communication drivers in either an alternating or an as-ready basis. While one driver is busy with a large packet, the other can continue to send messages.

If a DriverMUX tag has a Polling Driver for one of its subordinate drivers, then it must have a Polling Driver as both subordinates.
A DriverMUX tag may be subordinate to a Polling Driver.

Recommendations for subordinate drivers with

To log an event for each switch between the primary and secondary communication path, create an alarm that monitors the state of the expression, [DriverMUX Tag Name]\CurrentSubDriver. "CurrentSubDriver" is a property of this tag, identifying the subordinate driver in use.

To log an event for failure of either communication path, create an alarm for each driver. Refer to the topic Communication Driver Alarms for details.

Related information:

DriverMUX I/O Addressing

Communication Driver Alarms

Best Practices for Tags

Closed DriverMUX properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Closed DriverMUX properties Subordinate Drivers tab

Select the two drivers that the multiplexer will communicate with. Either of these may be another DriverMUX tag, with its own primary and secondary device drivers.

DriverMUX subordinate drivers tab

If the Primary I/O Device is a Polling Driver, then the Secondary must be a Polling Driver as well.

Primary I/O Device.

One of two device drivers that the DriverMUX tag can switch between. Depending on the purpose you intend use the DriverMUX tag for, this will normally be the device that will be used for the majority of I/O communications.

Secondary I/O Device.

The other of the two device drivers that the DriverMUX tag can switch between. This could be any of a backup route of communication, a new system that you are switching to or even another DriverMUX tag, allowing you to configure three or more redundant lines of communication.

Closed DriverMUX properties Modes tab

Define the operation (and thereby the purpose) of the DriverMUX tag. For each of the three modes, you can select an option from a menu of choices, or you can use a tag or expression to provide external control over the mode.

If defining a tag or expression to control a mode, note that numbering starts from 0, with the top mode in each list being the 0 mode. For example, a tag or expression controlling the Selection Mode would need to set the values 0, 1 or 2 for Automatic, Exclusive Primary and Exclusive Secondary, in that order. If the controlling tag or expression goes to invalid, then the last known good value will be used.

DriverMUX modes tab

Selection Mode

Automatic

Enables the DriverMUX to switch between the primary and secondary drivers, using rules defined in the other modes. (May be a constant, expression or tag that evaluates to 0.)

Exclusively Primary

Only the driver defined as primary is used for polling. Data may still be pushed in from the secondary, or arrive as a result of a driver health check, in which case you have the option to ignore data from the inactive subordinate. (Refer to the Settings tab.)
(May be a constant, expression or tag that evaluates to 1.)

Exclusively Secondary

Used when only the driver defined as secondary is to be used. Data may still be pushed in from the primary, or arrive as a result of a driver health check. (May be a constant, expression or tag that evaluates to 2.)

Sequence Mode

Primary Preferred

The primary driver is used for all communication unless it fails, at which point communication is handled by the secondary driver. When the primary driver comes back online, communication is transferred back to it. (May be a constant, expression or tag that evaluates to 0.)

Sticky Mode

Similar to Primary Preferred except that communication continues to be handled by whichever driver is in use until that driver fails. Upon failure of the active driver, communication switches to the alternate, where it remains regardless of whether communication is restored to the driver previously in use. (May be a constant, expression or tag that evaluates to 1.)

Parallel mode

Both drivers are used for communication on an as-ready basis. If one driver is busy with a larger communication packet, the other driver will be used for all packets until the first is ready for another packet. (May be a constant, expression or tag that evaluates to 2.)

Alternating mode

Both drivers are used in a strictly alternating basis. If the next driver in turn is still busy with its last communication packet, further communications will be queued until that driver is ready for another packet. (May be a constant, expression or tag that evaluates to 3.)

Secondary Preferred

In this mode, the secondary driver is used for all communication unless it fails, at which point communication is handled by the primary driver. When the secondary driver comes back online, communication is transferred back to it. (May be a constant, expression or tag that evaluates to 4.)

Failover Mode

Failover mode is of use in a multi-server application where backup servers are configured to handle communications in the event that a primary server fails.

Switch Drivers First

In the event that communication is lost with the driver in use, switch to the alternate driver. (May be a constant, expression or tag that evaluates to 0.)

Switch Servers First

In the event that communication is lost with the driver in use, attempt to switch to a backup server to re-establish communication with that driver before switching to the alternate driver. (May be a constant, expression or tag that evaluates to 1.)

Write Mode

By default, the driver multiplexer writes to only the active driver. If the drivers are connected to different hardware devices, then it is possible that one device might not be synchronized with regards to registers that are used as set points or other controls. This could cause unpredictable results in the case of a hardware fail over.

You have the option of forcing the DriverMUX to write to both devices.

Single Device.

The DriverMUX tag writes to the active driver only

Both Devices.

The DriverMUX tag sends all write requests to both the primary and secondary drivers.

Closed DriverMUX properties Settings tab

In the event of a communication failure, the DriverMUX tag will poll the failed driver at a decreasing frequency, watching for communication to be restored. This is done to allow communication to be re-established as quickly as possible in the event of a momentary outage, but to also reduce network load devoted to polling in the event of a longer outage.

DriverMUX settings tab

Minimum Test Rate (seconds)

The initial frequency at which checks are made to determine a failed driver's state.

Maximum Test Rate (seconds)

The longest period to wait between checks of a failed driver.

Backoff Rate (multiplier)

The time between tests is multiplied by this rate to obtain a progressively slowing frequency between tests until the Max Test time is reached.

Health Check Rate (seconds)

When the mode is set to Primary Preferred and the primary driver is in use, the secondary driver is tested at this rate to ensure its availability.

Health checks are not performed when the DriverMUX is in Alternating mode.

If using a DriverMUX with a Polling Driver, take note that the health check will run independently of the polling order and rate. The heath check is completely unaware that the Polling Driver exists.

Alternate Failure Triggers

It is possible for a driver to report that it is still working, even though no data is being transferred. An example is a radio link: All devices may be in perfect working order, but if the antenna is obscured, no data will be transferred. You can use the Alternate Failure Trigger to monitor some indicator other than the driver itself to determine when the DriverMUX should switch drivers.

A separate alternate trigger is provided for each driver. Use a tag or an expression that will evaluate to TRUE (1) to determine when a failure condition can be considered to have happened. An additional field, "Trigger Delay" is used to set the length of time that the alternate trigger must be true before the DriverMUX will switch drivers. For example, if monitoring for no data being received, it is necessary to wait several seconds to distinguish between a loss of communications and a pause between messages.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device. Auto-Rewrite must be set on the subordinate drivers that are to participate in automatic re-writing.
  • Manually by way of a button press. Store Last Outputs must also be must also be set on both of the subordinate drivers. See, Rewrite Outputs Widget for details.

Changing this value from selected to unselected will cause all stored values to be erased immediately.

Ignore Data from Inactive Subordinate

Select this option to discard any data that is being received by the driver that is not the active one. The default behavior when the box is unselected and the DriverMUX is in "Automatic" mode, is to pass all unsolicited data from both drivers to input tags.

Closed DriverMUX Tag Widgets

The following widgets are available to display information about your application’s DriverMUX tags. Note that, when the DriverMUX tag is in alternating mode, communication statistics shows only a count of switches.

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Show Statistics Button Widget

DriverSelect Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


DriverMUX I/O Addressing

The address used by an I/O tag may or may not need to change when the DriverMUX tag switches between drivers. It is recommended that all communications go through the DriverMUX tag(s) and not through the subordinate drivers at all. The issue is that the DriverMUX will attempt to control all of the polling through the subordinates, which can conflict with the setup of direct-to-driver I/O tags.

If either or both of the subordinate drivers provide an Address Selection dialog, that will be available to the I/O tags connected to the Driver Multiplexer. You have a choice of using the same address for both primary and secondary drivers or configuring separate addresses.

DriverMUX Address Select dialog

The following three scenarios are provided to help you plan how to use your driver multiplexer.

Scenario 1: Two lines of communication are set up between a PLC in the field and VTScada: one uses radio and the other uses a modem.

In this case, tag addressing is simple: The address is defined by the PLC device and does not change with the communication driver.

DriverMux addressing example 1

Scenario 2: Connecting to different RTUs.

For this scenario, the tag addressing used by the primary driver will be different from that used by the secondary. By way of example, perhaps one used Allen Bradley equipment and the other uses Modicon.

In this case, an I/O Tag will have to reference its intended data location by two completely different addresses. The address parameter of the I/O tag must therefore contain both addresses where each address is given inside curly braces and are given in the order of the Primary and Secondary subordinate drivers.

Ex. {Primary Address}{Secondary Address}

If (and only if) the DriverMUX is in Parallel or Alternating mode, you can make use of this address format to force an I/O tag to read from only one of the two drivers. Include both sets of braces, but leave the address blank for the driver that you do not want to read from.

Ex. {}{Secondary Address} will force an I/O tag to read only from Secondary Address on Driver B.

DriverMux addressing example 2

Scenario 3: A subordinate driver is also a DriverMUX tag, and each driver requires a different address for the I/O devices.

In this scenario, the addresses in each I/O tag will be nested in curly braces where the left to right order matches the primary to secondary configuration of the DriverMUX configuration:

The subordinate DriverMUX should never be configured as the preferred driverFor the following two scenarios, the primary driver is to the left and the secondary to the right. For this scenario, MUX1 should be set to secondary preferred mode. This will result in the precedence C, A, B. For this scenario, MUX1 should be set to primary preferred mode. This will result in the precedence A, B, C.The reason for this recommendation can be seen by examining the first scenario. Suppose that MUX1 is set to primary preferred mode with MUX2 as the primary (not recommended). If A fails, then MUX2 will switch to B. If B fails then MUX1 will switch to C. The difficulty arises when B is restored. MUX2 will continue to report an error mode because it is using its secondary, therefore MUX1 will continue to use C. Thus fail-over would work as intended A -> B -> C, but restoration would be C -> A, skipping B. 1.

Ex. {Primary Address}{{Secondary Address}{Tertiary Address}}

DriverMux addressing example 3

Once again, If the need arises to get a value from a specific driver (for example, the battery level of "C") you can ensure the DriverMUX tags do not poll this value from the other drivers by providing empty braces. To get the value only from "B" using the tag layout in scenario 2, the address can be set to something like {}{BatteryAddress}.

For scenario 3, it would be a little more complex: {}{{BatteryAddress}{}} for "B". {BatteryAddress}{{}{}} for "A".


Driver Redirect Tag

Used to help organize tags that use a common driver.

When an I/O tag is created, its driver parameter defaults to "*Driver", meaning that it will look up the tag tree to the nearest driver. The Driver Redirect tag looks like a driver tag to those underneath it in the tree, but will actually point those tags towards the real driver which is specified in its I/O Device parameter.

This is not uncommon in applications based on the Oil and Gas layer where, for example, the Daily, Hourly and Process tags that are found underneath each meter run tag are actually driver redirect tags that point the I/O tags below them to the various communication drivers used by the flow computer. With this configuration, one need only define one set of drivers, even if a flow computer has multiple meter runs.

Related information:

Best Practices for Tags

Closed Driver Redirect properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Driver Redirect properties Driver tab

I/O Device

Select the driver to which this tag will redirect.

Closed Driver Redirect Tag Widgets

The following widgets are available to display information about your tags:

Alarm List

Alarm Priority Box

Alarm Priority Icon

Draw HDV Widget

Site Alarm List

Site Details Widget

Site Icon Widget

Site Summary Widget

Tag List Widget


Enron Modbus Driver

Not counted towards your tag license limit.

Protocol Introduction

Enron Modbus is a variation on the standard Modbus protocol that allows for the transmission of stored historical data and alarm / event logs. The standard read / write Modbus function codes, 01, 03, 05, 06, are supported and used to read or write real-time values. The only major difference between accessing real-time values in regular Modbus versus Enron Modbus is the register addressing. See the addressing section for details.

Many devices that communicate via Enron Modbus also maintain an internal historical log with periodic, hourly or daily records. Additionally, they usually have a separate log, which contains alarm and event data specific to the flow calculations that the device is monitoring. The Enron driver allows both of these logs to be read and then transferred to the VTScada historian.

This driver supports multiple TCP/IP port connections between a single instance of the driver and the RTU.

As of release 12.1.31, this driver supports Omni Flow Computers. For details specific to that device, refer to the description of the Custom History Log Format within this document and relevant notes in the topic, Enron Modbus I/O Addressing.

For advanced VTScada developers: You can create an expression to obtain the timestamp of the last logged value using an Enron Modbus specific function: [<path-to-driver>]\GetLastTimestamp(History Address), where "History Address" is the numeric value of the address being monitored, typically starting at 701.

Related information:

Enron Modbus I/O Addressing

Enron Modbus Error Codes

Best Practices for Tags

Related application properties:

The following property settings hold additional configuration parameters for your Enron Modbus driver:

EnronBoolMaxBlockSize - Maximum number of standard Boolean values requested in a single read.

EnronShortMaxBlockSize - Maximum number of standard short integer values requested in a single read.

EnronLongMaxBlockSize - Maximum number of standard long integer/floating point values requested in a single read.

EnronMaxHistoryBlockSize - Maximum number of historical values requested in a single history log read.

EnronPropogateOnlyOnDataChange - If set, don't bother processing incoming data if it hasn't changed since the last read. Note that this setting does not apply to history reads or event log reads (which are always processed).

EnronSharedRPC - Set to use the same RPC service for all instances of the Enron Modbus driver. drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

EnronContinuousHistoryRead - When set, a single history poll cycle will continue reading from the device until all new history has been read.

EnronHistoryReadStartUpDelay - Seconds to wait for Enron history tags to initialize before timing out with a communications error.

Closed Enron Modbus Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Enron Modbus Driver properties Options

Comm Channel

Choose the format of the outgoing messages. Serial RTU sends the messages as they are and includes a CRC Closed Cyclic Redundancy Check at the end. Open Modbus TCP prefaces the messages with a TCP header. Note that the comm channel setting can be changed independently of the port tag. For example, some devices use the Serial RTU protocol sent out over a TCP/IP port.

Enable Multi-Write Function

Although standard Modbus multi-write function codes are not defined as part of the Enron Modbus standard, some devices can make use of them. If this is true of your device, this box may be selected.

Squelch Noise Present

Applies when communicating over a radio modem. Select this box to enable squelching of background noise.

Squelch Time

The number of seconds to wait before clearing noise when the Squelch Noise Present option has been selected.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Device Clock Time Zone

The time zone of the clock in the Enron Modbus device. This is used to correct the time-stamped values read from the device by VTScada for storage in its historian using UTC format. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for daylight savings time (DST).

  • Uses Server Time Zone (no DST) - assumes that the device is in the same time zone as the server.
  • Device Clock In UTC - the clock in the device is set to UTC
  • Actual Time Zone - select the time zone where the device is located.

Observe DST

Select if the RTU clock adjusts itself for Daylight Savings Time. Note that this does not necessarily mean that the RTU is in daylight savings time when this is being set. That is determined by the Windows operating system based on the selected time zone.

Enron Modbus Driver Configuration - Communications

Port

The port tag through which this driver communicates to a device, usually either a serial port tag or a TCP/IP tag.

Time-Out Limit

The length of time, in seconds, that the driver should wait for a reply from the device.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

RTS Key Off Delay

Used for serial communications, this field represents the length of time in seconds that the device will wait before dropping RTS at the end of a data transmission.

Station Address Mode

Use to limit the range of allowed addresses. Select according to your hardware:

Standard Address ... 1 - 247 according to Modbus Protocol

Lufkin ELAM Address ... 1 - 2295

TeleBUS Extended Address ... 1 - 65534

Station Address

The Modbus address of the Enron Modbus device.

Retry Delay

The length of time, in seconds, that the driver will wait between retry attempts if there is no reply to the initial message.

Enron Modbus Driver Configuration - Protocol

Operator Change / Alarm Event Log...

Base Date

When operator-change or alarm-event-log, time-stamped data is returned from the device, the year is provided as a two-digit number. That number is then added to this base date to produce the actual date used for the timestamp. for example, if the number returned was "34" and the base date is "1980" then the year will be recorded as 2014. This information should be available in your device's documentation.

Date Returned Before Time

Usually operator-change or alarm-event-log time-stamps from the device are returned with the time being sent before the date. If the reverse is true for your device then this box should be selected.

History Log...

Base Date

When history log time stamped data is returned from the device, the year is provided as a two-digit number. That number is then added to this base date to produce the actual date used for the timestamp (e.g. if the number returned was "34" and the base date is "1980" then the year will be re-corded as 2014. This information should be available in your device's documentation.

Date Returned Before Time

Usually, history-log time-stamps from the device are returned with the time being sent before the date. If the reverse is true for your device then this box should be selected.

Enron Modbus Driver Configuration - History

The Enron Modbus protocol allows for the retrieval of historical data records stored in the device. Each record holds the value of several variables for a specific timestamp, ordered by an incrementing index value. The following table is a representation of a theoretical hourly history log.

Index | Date | Time | Temperature | Pressure | Flow
1 | 08/08/2014 | 08:00:00 | 21.3 | 87.2 | 48.4
2 | 08/08/2014 | 09:00:00 | 22.4 | 86.9 | 49.4
3 | 08/08/2014 | 10:00:00 | 25.1 | 87.3 | 48.7
... | ... | ... | ... | ... | ...
1024 | 27/06/2014 | 19:00:00 | 18.9 | 87.4 | 44.0

Every hour, a new record is created inside the device. After the final history register has been filled (in this case index 1024) the next record goes back to index 1 and overwrites the record stored there.

The History tab is used to define and to track the characteristics and status of the device's history log. The "table columns" that are to be logged should be defined here. Up to 30 log tables may be defined.

History Address Number

Select which of the 30 separate history addresses to configure.

Log Address

The register address in the device where the history log is stored. For the first flow run, this is usually either 701 (for hourly history) or 702 (for daily history).

Default values of 701 through 710 are provided for History Address Numbers 1 through 10.

History Log Index Address

Some devices track the position of the index of the next record to be written. The address where this index position is stored should be entered here. This field is only used if the Enron driver's Read History Index from a Separate Address box is selected.

Total Number of Log Indices

The total number of records stored in the history log. After the driver has read this many indices it will start back at the first index.

Log Indices Begin at 0

Select this box if the first index of your device is 0 instead of 1.

Read History Log Index from a Separate Address

Historical data is read from a table in the device, which is ordered by an index value. By default the Enron Modbus driver will read all indices sequentially until arriving at the end of the new data (according to the datum's timestamp), however some devices track the most recent index value internally in a separate register. If this is the case with your device then this box should be selected. Note that the actual index register is set as part of the Enron History tag.

Use a 6-Byte Time/Date Format

The Enron Modbus protocol it returns the time and date from history logs as a pair of 4-byte floats. Some RTUs will instead return those as six 1-byte integers (MM/DD/YY followed by HH/MM/SS).

6-Byte Format Returns Day First

Enabled only when the preceding option is selected. Returns a 6-byte date format as DD/MM/YY instead of MM/DD/YY.

Custom History Log Format

This is an optional JSON file that you can use to specify the format of data in the history log for the case when it is not a series of 32-bit floating point numbers.

Example:

{
  "721": {
    "NumItems": 16,
    "Length" : 99,
    "FormatInfo":[
      {"DataType" : "STRING8", "Offset"   : 6},
      {"DataType" : "STRING8", "Offset"   : 14},
      {"DataType" : "STRING8", "Offset"   : 22},
      {"DataType" : "STRING8", "Offset"   : 30},
      {"DataType" : "BYTE",    "Offset"   : 38},
      {"DataType" : "STRING8", "Offset"   : 39},
      {"DataType" : "UINT32",  "Offset"   : 47},
      {"DataType" : "UINT32",  "Offset"   : 51},
      {"DataType" : "UINT32",  "Offset"   : 55},
      {"DataType" : "FLOAT",   "Offset"   : 59},
      {"DataType" : "FLOAT",   "Offset"   : 67},
      {"DataType" : "FLOAT",   "Offset"   : 71},
      {"DataType" : "FLOAT",   "Offset"   : 75},
      {"DataType" : "FLOAT",   "Offset"   : 91},
      {"DataType" : "UINT16",  "Offset"   : 95},
      {"DataType" : "STRING8", "Offset"   : 97}
    ]
  }
}

NumItems is the number of log items to be read

Length is the number of bytes needed to read all the data in FormatInfo

FormatInfo is an array of items consisting of a DataType and Offset value. The Offset is how many bytes into the data the value starts, and the data type is the type of data to read.

Supported values of data type are: FLOAT, BYTE, SINT16, SINT32, UINT16, UINT32, and STRING##, where ## is the length of the string in bytes.

If an improperly formatted file is detected, an error is displayed. Note the Import button, for use when adding a JSON.

Closed Enron Modbus Driver Tag Widgets

The following widgets are available to display information about your Enron Modbus driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Next Poll Index Widget

Numeric Value Widget

Plot Data Widget

Reset Polling History Widget

Rewrite Outputs Widget

Sparklines Widget


Enron Modbus I/O Addressing

Standard Values

For standard reads and writes, the address can be entered directly into the address field. Unlike with the standard Modbus driver there is no need to indicate the data type (e.g. /FLOAT) because each data type has its own predefined address range.

Register Numbers | Type | Table Name
1001-1999 | Read-Write | Boolean variables
3001-3999 | Read-Write | 16 bit Short integer variables
5001-5999 | Read-Write | 32 bit Long integer variables
7001-7999* | Read-Write | 32 bit Floating point variables

*Many devices allow floating point addresses above 7999.

History Logs

Note: The history logs can only be read in conjunction with an Enron History Log tag. See the Enron History Log Tag section for details on both the tag and the history storage methodology.

Analog Status tags, which store history information, should use the address structure:

HL:x:y

where x is the address of the history log (usually 701 or 702) and y is the variable's position in the returned history record (beginning with 0).

Alarm/Event Logs

An Enron Modbus device has a single log where both alarm and event information is stored. It should be noted that the alarms logged here are internal to the device and to the device's flow calculations, and as such are not necessarily related to alarms in VTScada.

Along with the timestamp, four pieces of information are returned as part of each event/alarm. Each of these pieces of information should be captured in its own analog status tag with the address:

EL:x:y

where x is the address of the alarm log (usually 32) and y is a value between 0-3 based on the chart following.

Address Index | Description | Comments
0 | Bitmap | Group of flags describing the event/alarm (see following)
1 | Register | Register that was changed/that triggered the alarm
2 | Data1 | Previous value (event) or current value (alarm)
3 | Data2 | Current value (event) or not used (alarm)

The Bitmap is a group of flags whose meanings change based on whether the record is an event or an alarm. Of particular importance is bit 9, which is always a 1 for an event and a 0 for an alarm.

Bit Number | Alarm Map | Operator Event Map
0 | unassigned | Fixed Value
1 | unassigned | Zero Scale
2 | unassigned | Full Scale
3 | unassigned | Operator Entry Work Value
4 | unassigned | Boolean Fixed Bit
5 | unassigned | Fixed/Variable Flag
6 | unassigned | Table Entry Change
7 | unassigned | System Command Change
8 | unassigned | unassigned
9 | Operator Change Event Bit (Always 0) | Operator Change Event Bit (Always 1)
10 | Lo-Lo Limit | Lo-Lo Limit
11 | Lo Limit | Lo Limit
12 | Hi Limit | Hi Limit
13 | Hi-Hi Limit | Hi-Hi Limit
14 | Rate of Change Limit | Rate of Change Limit
15 | Set/Reset Alarm (1 = set, 0 = reset) | unassigned

The diagram following details the tag setup. Contrasting this with the diagram of the historical log, you can see that no intermediary tag is necessary between the driver and the status tags. However, you may still choose to add a context tag to group the four analog status tags together.

Omni Flow Computers

The prefix of S8: can be used to denote that an address will return an 8 character string. For example, S8:4001 will interpret the data from address 4001 as an 8 character string.

You can read bit values from registers and history log entries by using a / or \ followed by the bit number to read.
Note that bit writes for non-boolean registers are NOT supported.


Enron Modbus Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
256 | 0x100 | Writing Invalid Data
257 | 0x101 | Illegal Function for the Addressed Slave
258 | 0x102 | Illegal Data Address in the Information Fields for the Addressed Slave
259 | 0x103 | Illegal Data Value in the Information Fields for the Addressed Slave
260 | 0x104 | Failure in Associated Device
261 | 0x105 | Acknowledge - Processing Programming Command
262 | 0x106 | Busy - Reissue Command Later
263 | 0x107 | Negative Acknowledge - cannot perform program function
264 | 0x108 | Memory Parity Error
266 | 0x10A | Gateway Path Unavailable
267 | 0x10B | Gateway Target Device Failed to Respond
512 | 0x200 | Illegal Memory Address In Read
513 | 0x201 | Illegal Memory Address In Write
515 | 0x203 | Error Opening Port
516 | 0x204 | Timed Out Waiting For Echoed Message
517 | 0x205 | Timed Out Waiting For Response From Remote
518 | 0x206 | Received Message CRC Error
531 | 0x213 | Communication Channel Not Available
534 | 0x216 | Corrupt or Illegal MODBUS/TCP header
537 | 0x219 | History Table Not Defined in Driver
544 | 0x220 | Error Sending Alarm/Event Log Acknowledge
545 | 0x221 | Incorrectly Sized History Data Returned
546 | 0x222 | Unknown Modbus Exception Code Returned
547 | 0x223 | Multi-Write Not Supported on this Device - See Driver Settings
548 | 0x224 | Read History Index Set but Address Not Defined
549 | 0x225 | History Index From Device Out of Range
550 | 0x226 | Error Reading History Index From Device
551 | 0x227 | Bad Transport Mode
552 | 0x228 | Bad Timestamp with History Log Data
768 | 0x300 | No Error
769 | 0x301 | Port Not Defined
770 | 0x302 | Port Failed To Connect
771 | 0x303 | Port Lost Connection
772 | 0x304 | Serial Port Settings Out of Range
773 | 0x305 | Serial Port Already In Use or Not Available
774 | 0x306 | Serial Port Access Denied
775 | 0x307 | Serial Port General Failure
776 | 0x308 | Serial Port Invalid Parameter
777 | 0x309 | Port Not Connected
784 | 0x310 | Port Unknown Error


Fisher ROC Driver

Not counted towards your tag license limit.

The Fisher ROC driver is used to communicate with devices that support the ROC protocol.

The ROC driver cannot share a port with the 12.1 version of the Modbus driver or Enron Modbus driver.

Related information:

Fisher ROC I/O Addressing

Fisher ROC Error Codes

Best Practices for Tags

Related Application Properties

ROCReadOnStartup - If true (1), the ROC driver will read all values when the system starts. Defaults to false (0).

ROCDriverSharedRPC - When true (1) indicates that the same RPC. drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

ROCMaxPointReadDataSize - Defaults to 239. The maximum number of values requested in a single point read. (opcode 167)

ROCMaxParmReadDataSize - Defaults to 239. The maximum number of values requested in a single parm read. (opcode 180)

ROCIgnoreFatalErrOnParmRead - Defaults to 0. If TRUE (1), allows the driver to attempt to continue after encountering a fatal error.

ROCDriverFailoverCount - Defaults to 1. Number of communication failures before switching to backup.

ROCNewSiteDailyHisSeconds - Defaults to 604800. Sets the default history length for daily point read history in seconds

ROCNewSiteHourlyHisSeconds - Defaults to 172800. Sets the default history length for hourly point read history in seconds

ROCIgnoreFatalErrOnHistRead - Defaults to 0. Allows the driver to attempt to continue after encountering a fatal error reading history

Closed Fisher ROC Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

ROC Driver properties Settings tab

The following properties are configured in the Settings tab:

Device Type

From the drop list, select the ROC device type being configured. Options include:

  • ROC300 ROCPAC
  • FloBoss 407
  • ROC300 FlashPAC
  • ROC800
  • FloBoss 103
  • FloBoss 107
  • ROC800L
  • FloBoss 107 - Alternate ROCNOC
  • FloBoss 107 - Surface Control Manager
  • FloBoss 103 - Surface Control Manager

Station ID

"Station" refers to the ROC device.

The ID is the identifier used by each ROC device so that it knows which messages it is meant to respond to.

Station Group

The Group is used to further distinguish one device from another, especially in cases where there are more than 255 ROC devices on the network. For example, a message addressed to ID 100 in Group 2 will not be answered by ID 100 of Group 3.

Host ID and Host Group

"Host" refers to the VTScada application.

The VTScada driver is given an ID and a Group so that the response messages from the RTU can be delivered properly.

Device Clock Time Zone

The time zone of the clock in the device. This is used to correct the time-stamped data, read from the device by VTScada, for storage using UTC format. \

Regardless of the time zone selected with this option, the driver assumes that the device does not adjust its clock for daylight savings time (DST). Take care to ensure that this is the case for your system.

  • Uses Server Time Zone (no DST) - assumes that the device is in the same time zone as the server.
  • Device Clock In UTC - the clock in the device is set to UTC. Strongly recommended.
  • Actual Time Zone - select the actual time zone that the device is located in

Custom Point Definition File

If configuring for custom point types, select the .CSV file holding the definition for those types. This file must have the same format as the file C:\VTScada\VTS\ROCPointDefinitions.CSV, which is found in every installation of VTScada. Refer to: ROC Address Storage.

ROC Driver properties Communications tab

Port

The port tag through which this driver communicates with a device. This is normally a serial port tag or a TCP/IP tag.

Time-Out Limit

The length of time, in seconds, that the driver should wait for a reply from the device.

Transmit Delay (sec)

Will delay the sending of messages. ROC field devices using RF links can hold the carrier on for a short period of time after sending a response message back to the host, resulting in missed messages. Use this to force a delay, giving the field device a chance to close the carrier. The delay defaults to 0 seconds

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

Flag indicating that the last values written to the device should be maintained. If true, the driver will maintain the last values written for each address, allowing these value to either be re-written manually or automatically.

Automatic Rewrites

Flag indicating the driver should automatically rewrite the last value written to each address upon successful establishment of communications after a driver error occurred.

Closed Fisher ROC Driver Tag Widgets

The following widgets are available to display information about your Fisher ROC driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

ROC Driver History Info Button

ROC History Polling Timestamp Reset

Sparklines Widget


Fisher ROC I/O Addressing

The Fisher ROC driver has an address assist module accessible from all standard I/O tags that are linked to a Fisher ROC driver. The address assist module is activated by clicking on the ROC button drawn on the I/O tab of all standard VTScada I/O tags.

Options within the Address Assist are revealed progressively, in response to your selections. Begin with Access Type as shown:

First step of the ROC Address Assist dialog.

Although the Address assist module exists to help users properly select complex Fisher ROC addressing, certain circumstances may dictate that addresses be entered manually. The following table lists the access types available to I/O tags connected to the Fisher ROC Communications driver:

Access Type | Function
Point Access (*) | Used to read individual parameters. Reads are coalesced based on point type and logic number.
Parm Access (*) | Used to read individual parameters. Read coalescing is not ordered in any particular fashion.
Point History | Report by Exception.
Configurable Opcode Table | Used to read minute, daily, hourly, and statistical historical values form the device.
Alarm Log | Used to read the alarm log from the device.
Event Log | Used to read the event log from the device.

(*) Refer to following descriptions and also to the section, "Efficient Data Collection", within this topic.

Point Access Address Format

Point access addresses are formatted as follows:

POINT:Type:Logical:Parameter

Where Type is the Point type, Logical is the logical number and parameter is the parameter number. As an example, to read AGA flow specific gravity for meter 1, the following address would be used:

POINT:7:0:5

Parm Access Address Format

Parm access addresses are formatted in the same manner as point access addresses.

PARM:Type:Logical:Parameter

Point History Address Format

The point history accessor is used to retrieve the following types of historical data:

  • Minute
  • Hourly
  • Daily
  • Statistical

Formatting will depend on your selection of the type of data and upon whether your device uses standard ROC addressing (in which case Ram Area must be selected) or ROC Plus (in which case the History Segment must be selected.) Examples are provided:

Standard ROC address for the daily history type, ram area 0 and history point 1:

POINTHIST:DAILY:0:1

Standard ROC address for the hourly history type, ram area 1 and history point 1.

POINTHIST:HOURLY:1:1

ROC Plus address for the minute history type, history segment #0 and history point 1.

POINTHIST:MINUTE:0:1

Statistical History addresses are formatted as follows:

POINTHIST:MINMAX:HistoryPointNumber:StatisticType

History point number specifies the history point number whose minute data is to be accessed. Statistic Type is used to specify the type of statistic to retrieve. The statistic values are as follows:

Statistic Type Address Value | Statistic
0 | Current Value
1 | Minimum Contract Hour Value
2 | Maximum Contract Hour Value
3 | Minimum Value Yesterday
4 | Maximum Value Yesterday
5 | Last Hour Value

Configurable Opcode Table Address Format

Configurable opcode table addresses are formatted as follows:

CNFOPTABLE:TableNumber:TableElement

TableNumber is used to specify the table number to access, and table element specifies the element number within the table to access.

Alarm Log Address Format

Alarm Log addresses are formatted as follows:

ALARMLOG:AlarmFieldNum

Where AlarmFieldNum specifies the alarm record field as shown in the following table:

Alarm Address Field Number | Statistic
0 | Alarm Type
1 | Alarm Code
2 | Alarm tag
3 | Alarm Value

Event Log Address Format

Event Log addresses are formatted as follows:

EVENTLOG:EventFieldNum

Where EventFieldNum specifies the alarm record field as indicated in the following table:

Event Address Field Number | Statistic
0 | Point Type
1 | Parameter Number
2 | Timestamp
3 | Point Number
4 | Operator ID
5 | Old Value
6 | New Value
7 | FST Number
8 | Event Text
9 | Event Value
10 | Event Timestamp
11 | Calibration Type
12 | Calibration Info 1
13 | Calibration Info 2

ROC Address Storage

ROC addresses are stored as a series of CSV files, stored in the C:\VTScada\VTS folder. You may view these files for reference, but you cannot edit them because they are a part of the VTScada layer. The files are:

  • ROCDeviceTypes.CSV – a list of all of the various ROC devices supported by VTScada and their accompanying TypeID. This TypeID will be important if you are configuring custom addresses.
  • ROCPointTypes.CSV – all list of all of the possible point types (the "T" from the address’ "TLP"). The description on the left is used in the ROC address assist, but only the PointType number matters when configuring custom addresses.
  • ROCPointDefinitions.CSV – a list of every address that can be read from every ROC device type.

You can add custom ROC point definitions by selecting your own CSV file that contains those definitions. The file may be stored anywhere on your computer but when imported, a copy of that file will be added to the application and placed in C:\VTScada\YourAppName\CustomROCPoints\. If you want to edit the file after it has been imported, you’ll need either to directly edit the copy in CustomROCPoints or you’ll need to edit your original file and then re-import it from the ROC tag’s configuration folder.

The contents of this file are appended to the standard ROCPointDefinitions.CSV file, which is still read. If a parameter is defined in both the new file and the standard one, the new definition is used for that parameter.

The new CSV file must have the same format as the standard ROCPointDefinitions.CSV and therefore must contain the following fields:

  • Device Type – the TypeID as referenced in the ROCDeviceTypes.CSV file, this defines the ROC Device Type that will use this definition (e.g. FloBoss 107, ROC800, etc.). If you want your new definition to be used by more than one device type then you will need to include it multiple times, each with a different number in the Device Type field.
  • Point Type – The PointType, as referenced in the ROCPointTypes.CSV file. This will define the T in the TLP. Most often, users who are editing this file will be redefining all of the parameters for a given point type.
  • Parameter Number – The P in the TLP, this is where you specify which individual parameter you are defining. Note that while these parameters do not need to be listed in any particular order, you shouldn’t leave any "holes" in your block of parameters. In other words, if you want to read parameter 7 and parameter 10 you should also include definitions for parameters 8 and 9.
  • Bit Number – Only applicable to binary (or BIN) types, this is the bit number within the overall byte that you are defining. Look at 7:0:14 in the standard file for an example.
  • Data Type – Tells the ROC driver how to interpret the data coming from the RTU. Options include:
    • BIN – a binary word
    • INTx – a signed integer, where x is the number of bits in the response (8, 16, 32)
    • UINTx – an unsigned integer, where x is the number of bits in the response (8, 16, 32)
    • FL – 4-byte floating point
    • DBL – 8-byte double floating point
    • TLP – a 3-byte TLP address
    • AC – ASCII text
    • TIME – 4-byte timestamp
  • Data Length – The number of bytes expected in the response. This is closely tied to the data type, but may vary for some types like AC.
  • Access – either "R/W" (can read or write) or "R/O" (can only read, writes are disabled)

It is not necessary to restart the application after loading a custom point definition file, but this file is not monitored for changes while the application runs. If you edit the file, you must restart the application before the changed point definition will be used.

Efficient Data Collection

When accessing current parameter values, various strategies can be used to increase communications efficiency based on the TLP distribution of the I/O tags being accessed. the following three accessor types will be further explained in order for users to properly select the accessor strategy to meet the particular Tag address distribution of the application.

Point Access

Will coalesce reads based on a combination of Point type and logical number. This accessor method should be used when the values of many tags, or groups of tags, being accessed have a TLP with identical point type and logical number. As an example, when accessing the following set of TLPs using the Point Access accessor:

(5:0:1, 5:0:2, 5:0:5, 5:0:6, 5:0:7, 5:0:8, 5:0:9, 5:0:10, 5:0:11, 5:0:12, 5:0:13, 5:0:14, 5:0:15, 5:1:5, 5:1:6, 5:1:7, 5:1:8, 5:1:11, 6:0:4, 6:0:5, 6:0:6, 6:0:7)

The parameters will be accessed using three separate reads.

  1. Begin at 5:0:1 for 15 parameters
  2. Begin at 5:1:5 for 7 parameters
  3. Begin at 6:0:4 for 4 parameters

Parm Access

Will coalesce as many reads into a single message as possible. The number of parameters that can be coalesced into a single message is limited by the maximum ROC protocol message size. Given the example above:

(5:0:1, 5:0:2, 5:0:5, 5:0:6, 5:0:7, 5:0:8, 5:0:9, 5:0:10, 5:0:11, 5:0:12, 5:0:13, 5:0:14, 5:0:15, 5:1:5, 5:1:6, 5:1:7, 5:1:8, 5:1:11, 6:0:4, 6:0:5, 6:0:6, 6:0:7)

The driver will coalesce the reads into a single request. the efficiency of this accessor is lost in the fact that the TLP of each parameter being accessed must be included in the request, thus require more bandwidth in the request than simply specifying the starting TLP and the number of parameters to read. This accessor is efficient when accessing parameters which do not share common Types and logical numbers, and when the configurable opcode table has not been implemented in the device.

Configurable Opcode Table

This can be useful when the feature has been implemented in the device configuration. ROC devices allow often accessed TLPs to be assigned to particular indexes with the configurable opcode table. All values within the table can be accessed using a single read. The protocol specifies the starting index and the number of values to retrieve.

Historical Data Retrieval

Status of historical data, including alarms, events, and process data collected from the HMI is not maintained within the ROC devices. This means that the ROC device does not keep track of which data has been retrieved, and will readily allow the HMI to access all logged data within the device. To prevent duplicate readings within VTScada, the driver will retain the timestamp of the last data record, for each data type, and only retrieve records whose timestamps are newer than the previously retrieved record. On the initial connection to a device, the driver will have no retained timestamp and retrieve all available data.

Related information:

Fisher ROC Driver


Fisher ROC Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
1 | 0x001 | Timed Out Waiting For Response
2 | 0x002 | Rx CRC Error
32 | 0x020 | Rx Opcode Mismatch
33 | 0x021 | Rx Point Type Mismatch
34 | 0x022 | Rx Point Num Mismatch
35 | 0x023 | Rx Number Data Mismatch
36 | 0x024 | Rx Start Mismatch
37 | 0x025 | Rx RAM Type Mismatch
38 | 0x026 | Rx History Point Mismatch
39 | 0x027 | Rx Table Number Mismatch
40 | 0x028 | TLP Mismatch in Rx Message
41 | 0x029 | Unknown Rx Error
42 | 0x02A | Communication channel not available
43 | 0x02B | Writes to This Address Not Supported
44 | 0x02C | Invalid Write Message
80 | 0x050 | Timed Out Waiting For Response Header
81 | 0x051 | Timed Out Waiting For Response Body
82 | 0x052 | Port Not Ready
83 | 0x053 | Unexpected Operation
201 | 0x0C9 | ROC Error Code 1: Invalid Opcode Request
202 | 0x0CA | ROC Error Code 2: Invalid Parameter Number
203 | 0x0CB | ROC Error Code 3: Invalid Logical Number / Point Number
204 | 0x0CC | ROC Error Code 4: Invalid Point Type
205 | 0x0CD | ROC Error Code 5: Received Too Many Data Bytes
206 | 0x0CE | ROC Error Code 6: Received Too Few Data Bytes
207 | 0x0CF | ROC Error Code 7: Did Not Receive 1 Data Byte
208 | 0x0D0 | ROC Error Code 8: Did Not Receive 2 Data Bytes
209 | 0x0D1 | ROC Error Code 9: Did Not Receive 3 Data Bytes
210 | 0x0D2 | ROC Error Code 10: Did Not Receive 4 Data Bytes
211 | 0x0D3 | ROC Error Code 11: Did Not Receive 5 Data Bytes
212 | 0x0D4 | ROC Error Code 12: Did Not Receive 16 Data Bytes
213 | 0x0D5 | ROC Error Code 13: Outside Valid Address Range
214 | 0x0D6 | ROC Error Code 14: Invalid History Request
215 | 0x0D7 | ROC Error Code 15: Invalid FST Request
216 | 0x0D8 | ROC Error Code 16: Invalid Event Entry
217 | 0x0D9 | ROC Error Code 17: Requested Too Many Alarms
218 | 0x0DA | ROC Error Code 18: Requested Too Many Events
219 | 0x0DB | ROC Error Code 19: Write to Read Only parameter
220 | 0x0DC | ROC Error Code 20: Security Error
221 | 0x0DD | ROC Error Code 21: Invalid Security Sign in
222 | 0x0DE | ROC Error Code 22: Invalid Store and Forward Path
223 | 0x0DF | ROC Error Code 23: Flash Programming Error
224 | 0x0E0 | ROC Error Code 24: History Configuration in Progress
225 | 0x0E1 | ROC Error Code 25: Invalid Parameter Range
229 | 0x0E5 | ROC Error Code 29: Invalid 1 Day History Index Request
230 | 0x0E6 | ROC Error Code 30: Invalid History Point
231 | 0x0E7 | ROC Error Code 31: Invalid Min/Max Request
232 | 0x0E8 | ROC Error Code 32: Invalid TLP
233 | 0x0E9 | ROC Error Code 33: Invalid Time
234 | 0x0EA | ROC Error Code 34: Illegal Modbus Range
250 | 0x0FA | ROC Error Code 50: General Error
251 | 0x0FB | ROC Error Code 51: Invalid State for Write
252 | 0x0FC | ROC Error Code 52: Invalid Configurable Opcode Request
261 | 0x105 | ROC Error Code 61: HART Passthrough Comm Scanner or Passthrough Disabled on this Channel
262 | 0x106 | ROC Error Code 62: HART Passthrough not Licensed
263 | 0x107 | ROC Error Code 63: Requested Security Level Too High
500 | 0x1F4 | Received too many data bytes
501 | 0x1F5 | Number of data bytes > 0
502 | 0x1F6 | Less than 6, or more than 8 data bytes received
503 | 0x1F7 | Industry Canada audit log full
504 | 0x1F8 | One of the following: Incorrect number of data bytes received- Not a valid configurable Opcode point- Starting table location greater than 43- Number of table locations greater than 44
505 | 0x1F9 | One of the following: Starting table location plus the number of table locations greater than 44- The length of data is greater than 234 bytes
506 | 0x1FA | Error in configuration. One of the parameter definitions is no longer valid.
507 | 0x1FB | One of the following: Starting table location plus the number of table locations greater than 44- Expecting more data than was received
508 | 0x1FC | Too little data
509 | 0x1FD | Too Much Data
510 | 0x1FE | Security error
512 | 0x200 | Requested security level too high
513 | 0x201 | Number of data bytes not equal to 16
514 | 0x202 | Number of data bytes less than 12
515 | 0x203 | Number of data bytes not equal to 30
516 | 0x204 | One of the following: Number of data bytes > 2- Invalid Point Number for requested module- Invalid RAM area number
517 | 0x205 | One of the following: Number of data bytes > 22- Requested more than 20 tags- Invalid RAM area number
518 | 0x206 | Invalid Point Number for requested RAM area
519 | 0x207 | One of the following: Number of data bytes not equal to 3- Starting alarm pointer > 239
520 | 0x208 | One of the following: Number of data bytes > 2- Invalid Point Number for requested RAM area- Invalid RAM area number
521 | 0x209 | One of the following: The history Point Number requested exceeds the number of points defined for that history RAM area- The data portion of the message received did not consist solely of 3 bytes- The history point is not defined for periodic, hourly archival
522 | 0x20A | One of the following: Not a valid day specified, the day specified must be between 1 and 31, inclusive- Not a valid month specified, the month specified must be between 1 and 12, inclusive
523 | 0x20B | Specified day and/or month requested does not match the day and/or month in the time stamp associated with the first history value for the day
524 | 0x20C | The Point Number exceeds the number of possible history points for that RAM area
525 | 0x20D | One of the following: The number of data values requested exceeds the number of data values defined for the history RAM area- The data portion of the message received did not consist solely of 5 bytes- The module number exceeds or is equal to the maximum number of modules supported by the ROC
526 | 0x20E | One of the following: The Point Number exceeds the number in the requested module- The requested Point Number has an invalid archival type
527 | 0x20F | Industry Canada audit log retrieval error
528 | 0x210 | Industry Canada clear audit log error
529 | 0x211 | One of the following: Number of data bytes is not equal to 3- Display number > 1
530 | 0x212 | One of the following: Display number > 1- Number lines requested > 3- Starting row > 20- Starting row + number of rows > 21
531 | 0x213 | Number of data bytes incorrect
532 | 0x214 | One of the following: Number of data bytes < 4- Set/Send byte < 4- Invalid Point Number for RAM area
533 | 0x215 | Number of data bytes not equal to 7 for "Set Operation"
534 | 0x216 | Number of data bytes not equal to 4 for "Set Operation"
535 | 0x217 | Received 4 or fewer data bytes, or invalid Point Type
536 | 0x218 | More than 250 data bytes in response
537 | 0x219 | Serial Port Invalid Parameter
538 | 0x21A | One of the following: Did not receive 4 data bytes- Invalid Point Type
539 | 0x21B | Point does not exist
540 | 0x21C | Invalid range of parameters asked for
541 | 0x21D | Too many data bytes to send (more than 240)
542 | 0x21E | One of the following: Number of data bytes not equal to 2- Number requested > 32- Invalid starting Point Number- Too many points requested for requested starting Point Number
543 | 0x21F | One of the following: Number of data bytes not equal to 4- Invalid Point Type
544 | 0x220 | Invalid Point or Type
545 | 0x221 | Received less than 4 data bytes
546 | 0x222 | Point type out of range (1 - 24 are valid)
548 | 0x224 | Number of data bytes not equal to 2
549 | 0x225 | Invalid Opcode requested
550 | 0x226 | Not enough data bytes received
551 | 0x227 | Error in one of the parameters
767 | 0x2FF | Not in security user list


GE Series 90 Driver

Not counted towards your tag license limit.

Use this driver to communicate with GE series 90 PLCs / RTUs. Two modes of communication are supported: TCP/IP using the Service Request Transport Protocol (SRTP) or serial using the Series 90 Protocol Express (SNP-X) protocol.

Limitations

When addressing the memory in the PLC / RTU the bit reads must be byte-aligned. For example, if address %T0014 is being read, a tag would need to be created that would start the read at the byte boundary, %T0009. Also GE addressing starts at one, not zero.

GE Series 90 drivers will commonly connect to TCP on port # 18245, although variations may be found.

Related information:

GE Series 90 Addressing

GE Series 90 - Serial Error Codes

GE Series 90 - TCP Error Codes

Best Practices for Tags

Closed GE Series 90 Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

GE Series 90 Driver properties Config tab

Set the communication properties of the driver with the following fields:

Communications Channel

Sets the type of communication the driver will use to communicate with the PLC and can be set to TCP/IP (SRTP) or Serial (SNP-X).

PLC SNP Address/PLC or TCP/IP Address

If TCP/IP communications are being used, this will be the IP address of the PLC. If Serial communications are being used this will be the station SNP-X ID.

Timeout Limit

The maximum time to wait (in seconds) for a response from the remote device before retrying or generating an error.

Port

Select the external serial port for use with the SNP-X protocol. Note that the Port may need to be a Serial Port tag if the PLC does not support "Break-Free Operation". In it's original format, SNP-X protocol relies on the use of serial break commands that cannot be handled by TCP/IP or UDP/IP port connections to Ethernet to serial devices. Some of these devices may support the serial break function, but only if used with their supplied serial port redirector drivers and configured as a serial port in VTScada. Check the device hardware / software specifications to confirm if the break function is supported.

If the PLC supports "Break-Free Operation" and it is enabled, then a TCP/IP Port tag or UDP/IP Port may be used when communicating to the PLC using an Ethernet to serial converter.

A port tag does not need to be defined when using the STRP protocol as the driver uses an internal TCP/IP port

TCP/IP Port #

The TCP port number used by the internal TCP/IP port for the SRTP protocol.

TCP/IP Connect Time Limit

The time limit for a successful TCP/IP connection before an error is generated.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

GE Series 90 Driver properties Virtual PLC tab

The Virtual PLC tab is for setting up the driver to act like a "virtual" PLC. Specify how many memory addresses of each type to allocate to this virtual PLC.

Virtual PLC "R" Words

The number of type "R" words to allocate for the virtual PLC.

Virtual PLC "AI" Words

The number of type "AI" words to allocate for the virtual PLC.

Virtual PLC "AQ" Words

The number of type "AQ" words to allocate for the virtual PLC.

Virtual PLC "I" Bits

The number of type "I" bits to allocate for the virtual PLC.

Virtual PLC "M" Bits

The number of type "M" bits to allocate for the virtual PLC.

Virtual PLC "T" Bits

The number of type "T" bits to allocate for the virtual PLC.

Virtual PLC "Q" Bits

The number of type "Q" bits to allocate for the virtual PLC.

Closed GE Series 90 Driver Tag Widgets

The following widgets are available to display information about your Enron Modbus driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


GE Series 90 Addressing

The input / output tags addressed under the GE Series 90 Driver use the addressing system in the following table. An assist dialog is provided to help you create these addresses.

Preface the address with the register or bit type to be used. The limits on any actual addresses will depend on the configuration of the system and type of CPU used.

Address Format | Data Type
%I# | Discrete Inputs
%Q# | Discrete Outputs
%M# | Discrete Internals
%T# | Discrete Temporaries
%AI# | Analog Input
%AQ# | Analog Output
%G | Global Bits
%GY | Global Bytes%GY is addressed by Byte number and is 1 based. To read the first byte, the address would be %GY1 and would read the G bits 1-8. To read the sixth byte the address would be %GY6 and would read G bits 41-48. To go from bytes to start bit: start bit = (byte*8) – 7. To go from start bit to byte: byte = (start bit + 7)/8. This should always result in a whole number. Byte addressing is always on the byte boundary. 1
%R# | Registers
%W# | Words
%S# | Status Bits
%SA# | Status Bits
%SB# | Status Bits
%SC# | Status Bits

In this table, # represents the register or bit number, starting at one. Note that addresses configured as outputs can also be read by input tags.


GE Series 90 - Serial Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | Invalid X-Request Code
01 | 0x1 | Privilege Level Insufficient
02 | 0x2 | Invalid Memory Type
03 | 0x3 | Invalid Address or Range
04 | 0x4 | Invalid Data Length
05 | 0x5 | Data Buffer Length Mismatch
06 | 0x6 | Queue Full in Slave
07 | 0x7 | Response Size Too Large
08 | 0x8 | CMM Module Error
09 | 0x9 | Illegal Broadcast
10 | 0xa | Invalid Message Type
11 | 0xb | Invalid Next Message Type or Length
12 | 0xc | Invalid Message Type in X-Buffer
13 | 0xd | Invalid Next Message Type in X-Buffer
14 | 0xe | Serial Output Timeout
15 | 0xf | SNP-X Request Aborted
16 | 0x10 | Exceeded X-Buffer Message Size
17 | 0x11 | PLC-CPU No Response
18 | 0x12 | PLC Backplane Comm Error
19 | 0x13 | Parity Error in X-Attach Message
20 | 0x14 | Framing or Overrun Error in X-Attach Message
21 | 0x15 | BCC Error in X-Attach Message
22 | 0x16 | Invalid Message Type Expecting X-Attach
23 | 0x17 | Invalid Next Message Type in X-Attach
24 | 0x18 | Invalid Request Code in X-Attach
25 | 0x19 | Parity Error in X-Request Message
26 | 0x1a | Framing or Overrun Error in X-Request Message
27 | 0x1b | BCC Error in X-Request Message
28 | 0x1c | Parity Error in X-Buffer Message
29 | 0x1d | Framing or Overrun Error in X-Buffer Message
30 | 0x1e | BCC Error in X-Buffer Message
31 | 0x1f | Expected X-Buffer Message Not Received
32 | 0x20 | Unknown PLC Error
33 | 0x21 | Unable to find connection address
40 | 0x28 | Exceeded Maximum Data Size
41 | 0x29 | Port Parameter(s) Out Of Range
42 | 0x2a | Serial Port Already In Use
43 | 0x2b | Timed Out Waiting For Echo
44 | 0x2c | NAK Received From Remote
45 | 0x2d | Unknown Response From Remote
46 | 0x2e | Timed Out Waiting For Response
47 | 0x2f | Bad Received BCC
48 | 0x30 | Unmatched Message IDs
49 | 0x31 | Unmatched Command/Response
50 | 0x32 | Unknown Error
51 | 0x33 | Device Address Out Of Range
52 | 0x34 | Memory Address Out Of Range
53 | 0x35 | Data Type Out Of Range
54 | 0x36 | Invalid parameters
55 | 0x37 | Unknown Error Code
56 | 0x38 | No Errors
60 | 0x3c | Serial Port Parameter Out Of Range
64 | 0x40 | Serial Port Access Denied
65 | 0x41 | Serial Port General Failure


GE Series 90 - TCP Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
000 | 0x0 | No Errors
001 | 0x1 | Socket Manager - Could Not Connect
002 | 0x2 | Socket Manager - Socket Connection Lost
003 | 0x3 | Socket Manager - Socket Connection Not Valid
004 | 0x4 | Socket Manager - Timeout Error
005 | 0x5 | SndRcv - Timeout Waiting For Response
006 | 0x6 | Read - Invalid Device Address
007 | 0x7 | Read - Memory Offset Out Of Range
008 | 0x8 | Read - Data Type Out Of Range
009 | 0x9 | Read - Invalid Parameter
010 | 0xa | XmitRcv - Socket Not Ready
011 | 0xb | XmitRcv - Socket Not Valid
012 | 0xc | SndRcv - No ACK Received
013 | 0xd | Write - Invalid Device Address
014 | 0xe | Write - Memory Offset Out Of Range
015 | 0xf | Write - Data Type Out Of Range
016 | 0x10 | Write - Invalid Parameter
017 | 0x11 | Write - Exceeded Maximum Number Of Write Values
018 | 0x12 | Virtual PLC Timeout Error
019 | 0x13 | Virtual PLC Read Address Error
020 | 0x14 | Virtual PLC Write Address Error
021 | 0x15 | Virtual PLC Read Overflow Error
022 | 0x16 | Virtual PLC Write Overflow Error
023 | 0x17 | Virtual PLC Receive Timeout Error
024 | 0x18 | Unexpected PDU Response Received
025 | 0x19 | Invalid Error Code
026 | 0x1a | Socket Manager - Connect ACK Not Received
027 | 0x1b | Socket Manager - Session ACK Not Received
028 | 0x1c | SndRcv - Timeout Due to Consecutive Sequence Number Mismatches
099 | 0x63 | Unknown Error Code
100 | 0x64 | PLC Unknown Error #%0
101 | 0x65 | PLC Error #1 - Other Error
102 | 0x66 | PLC Error #2 - PLC Inaccessible
103 | 0x67 | PLC Error #3 - Invalid Service Mapping
104 | 0x68 | PLC Error #4 - Unexpected Version
105 | 0x69 | PLC Error #5 - Unrecognized Protocol Data Unit (PDU)
106 | 0x6a | PLC Error #6 - Data Not Allowed
107 | 0x6b | PLC Error #7 - Resources Exceeded
108 | 0x6c | PLC Error #8 - Protocol Data Unit (PDU) CM State Clash
109 | 0x6d | PLC Error #9 - Request Refused
110 | 0x6e | PLC Error #10 - Unsupported Protocol Data Unit (PDU)
111 | 0x6f | PLC Error #11 - Lost Transaction
142 | 0x8e | PLC Error #42 - The Backplane Driver could not access the PLC CPU
143 | 0x8f | PLC Error #43 - Invalid binding on the message sent to the Backplane Driver
144 | 0x90 | PLC Error #44 - Message could not be sent because the mailbox was not open
145 | 0x91 | PLC Error #45 - Max # of transfers to the destination are already active
146 | 0x92 | PLC Error #46 - Max # of transfers of this type are already active
147 | 0x93 | PLC Error #47 - Cannot obtain a Dual-Port RAM buffer
148 | 0x94 | PLC Error #48 - Cannot obtain resources (other than Dual-Port RAM buffer)
149 | 0x95 | PLC Error #49 - Connection ID or Block Transfer ID is not valid
150 | 0x96 | PLC Error #50 - Timed out waiting for response from PLC CPU
151 | 0x97 | PLC Error #51 - The PLC CPU aborted the request
152 | 0x98 | PLC Error #52 - An invalid message type was specified
153 | 0x99 | PLC Error #53 - The specified task is not registered
154 | 0x9a | PLC Error #54 - The specified mailbox offset is invalid
155 | 0x9b | PLC Error #55 - Argument "msg_rsp" may not be NULL
156 | 0x9c | PLC Error #56 - Argument "unsol_rsp" may not be NULL
157 | 0x9d | PLC Error #57 - Parameter pointer is unexpectedly NULL
158 | 0x9e | PLC Error #58 - Maximum byte length exceeded for a single transfer
159 | 0x9f | PLC Error #59 - Bad sequence number in request
160 | 0xa0 | PLC Error #60 - Invalid command in request
161 | 0xa1 | PLC Error #61 - Actual response length size unexpected
162 | 0xa2 | PLC Error #62 - Service Request Processor in PLC CPU is unavailable
163 | 0xa3 | PLC Error #63 - No text buffer available


Honeywell Mercury Driver

Not counted towards your tag license limit.

This driver can communicate with the following versions of Honeywell Mercury flow computer devices:

  • ECAT
  • Mini-AT (firmware versions newer than 6.81)
  • Mini-Max (firmware versions newer than 2.60)
  • ERX
  • EC350
  • ERX350

The following Honeywell Mercury protocol features are supported:

  • Reading item data.
  • Reading of live data items.
  • Write data to an item.
  • Retrieving logged data records (including extracting events from audit trigger/alarm field).
  • Reading of event log records (when supported by device).
  • Reading of alarm log records (when supported by device).
  • Support for incoming calls initiated by a site.

Unlike a standard driver, all reads and writes are done together after establishing a session with the RTU. Standard read triggers in IO tags are disabled. If a write is called, the value to be written is saved within the driver and then written out during the next calling session. A triggering mechanism is required to perform the calls. We recommend using a Polling Driver Tag for that purpose.

What is read by the driver during each call is determined by the addresses configured in I/O tags using this driver.

Related application properties

The following property settings hold additional configuration parameters for your Honeywell Mercury driver:

MercuryDriverAlarmXXXPriority, where XXX is the item number (only a certain subset of item numbers are alarms).

MercuryDriverEventXPriority, where X is the event code, ranging between 0 and 22.

MercuryDriverTAPriority_XXXX, where XXXX is a particular Trigger Type.

Troubleshooting

  • The driver appears to be configured correctly but has not triggered a single read since the application started.

    Has a Polling Driver tag been configured? The driver must initiate sessions to receive data. We recommend that you configure a Polling Driver tag to manage the polling interval and trigger sessions.

  • Why can't I use a Trigger tag to trigger sessions?

    If you only have one Honeywell Mercury driver, you could use a Trigger tag tied to its Trigger parameter. However a Polling Driver tag is suitable for single and multiple configurations.

Related information:

Best Practices for Tags

Closed Honeywell Mercury Driver properties, ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Honeywell Mercury Driver, Configuration properties tab

Device Type

Commands work differently based on the device. Select from any of:

  • Mini-AT
  • Mini-Max
  • ECAT
  • EC 350
  • ERX
  • ERX 350

Date Format

Three options are allowed:

  • MMDDYY
  • DDMMYY
  • YYMMDD

Site ID #1, Site ID #2

Used by the discriminator to determine the driver to which inbound calls are sent.

Access Code

Defaults to 33333

Enable VTScada Alarm Logging

Select if alarms read from the device should be recorded in the VTScada alarm history.

Honeywell Mercury Driver, Communications properties tab

Port

Must be a serial port, to which a modem or cellular modem is attached.

Call Trigger

A tag or expression. A call is placed when this value changes from zero to any non-zero value.

Timeout

Specify the time in seconds, after which a call is aborted if there is no response. Defaults to 2 seconds.

Device Clock Time Zone

VTScada stores all values using UTC time zone. To store time-stamped data correctly, you must specify the timezone of the RTU.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Closed Honeywell Mercury Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Honeywell Mercury Show Stats

Equipment / Status Color Indicator

Indicator Light Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Rewrite Outputs Widget

Sparklines Widget


Honeywell Mercury Driver Addressing

An Address Select dialog is provided to help you build I/O addresses for use with your Honeywell Mercury driver.

Address

Display field only. Build the address using the Address Types selection and providing a matching Item Number

Device Type

Display field only. Shows the Device Type configuration of the Honeywell Mercury driver tag.

Addressing will be the same regardless of device type however, this module will determine the proper function code based on the device type and version.

Address Types

Select the type of value for which you are building an address (Item, Live, Audit, Event, Alarm, ...)

Item Number

Visible only when an Address Type has been selected. Enter the appropriate value for the address you need. The resulting address will be displayed in the first field. Numbers will be checked to ensure that they are within range.


Honeywell Mercury Driver Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0 | No Error
1 | 0x1 | Response Timed Out
2 | 0x2 | Response CRC Error
3 | 0x3 | Response Too Long
4 | 0x4 | Lost Session
5 | 0x5 | Response Incorrect
6 | 0x6 | Response Invalid or Unknown
100 | 0x64 | No Error
101 | 0x65 | Message Format Error
120 | 0x78 | Sign-On Error
122 | 0x7a | Framing Format Error
123 | 0x7b | Check-Word Error
127 | 0x7f | Access Code Error
128 | 0x80 | Invalid Command
129 | 0x81 | Invalid Item Number
130 | 0x82 | ENQ Error
131 | 0x83 | Retry Limit
132 | 0x84 | Access Disabled
133 | 0x85 | No Audit-Trail Records
134 | 0x86 | Event Log Full
135 | 0x87 | Invalid AGA8 Condition
136 | 0x88 | No Event Log Records
137 | 0x89 | No Alarm Log Records
138 | 0x8a | Invalid Data
139 | 0x8b | Invalid Change Attempt
140 | 0x8c | Insufficient Power
141 | 0x8d | REI Read Error
142 | 0x8e | REI Write Error


IEC 60870-5-104 Driver

Not counted towards your tag license limit.

IEC 60870-5 refers to a collection of standards produced by the International Electrotechnical Commission, or IEC, to provide an open standard for the transmission of SCADA telemetry control and information. IEC 60870-5-104 provides for communications over networks using the TCP/IP protocol suite.

Related information:

IEC 60870-5-104 Addressing

IEC Error Codes

Best Practices for Tags

Related application properties

The following property settings hold additional configuration parameters for your IEC 60870-5-104 driver:

IECFailoverCount – Count of errors before a soft failover to a redundant server is attempted. Defaults to 10.

IECPropagateOnlyOnDataChange - If set, driver will not process incoming data if it hasn't changed since the last read. Note that this setting does not apply to history reads or event log reads (which are always processed). Defaults to 1.

Closed IEC 60870-5-104 Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

IEC 60870-5-104 Driver properties Communications

Port

The VTScada port tag that will be used by the driver. Note that the IEC-60870 5-104 driver uses port #2404

Device Timezone

The time zone of the clock in the IEC-60870-5-104 device. This is used to correct the time-stamped readings read from the device by VTScada for storage in its historian in UTC format.

  • Uses Server Time Zone (no DST) – assumes that the device is in the same time zone as the server. Take care to ensure that the server does not use daylight savings time.
  • Device Clock In UTC – the clock in the device is set to UTC. Strongly recommended.
  • Actual Time Zone – select the actual time zone, in which the device is located.

Enable Time Synchronization

Controls whether a time synchronization message is sent to the device on establishing a communications session. If selected, time synchronization is enabled. By default, no time synchronization is performed.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Number of Outstanding ASDUs (K)

Specifies the number of Application Service Data Units (ASDUs) that can be received before sending an acknowledgment. The value, K, is defaulted to 3.

Response Timeout (T1) (seconds)

Time to wait for a response before reporting an error. T1 has a default of 5 seconds.

ACK Response Timeout (T2) (seconds)

Time to wait before sending an ACK (S Type Message) in the absence of any other communications. T2 has a default of 5 seconds.

IP Network Listener Group

Configure only if this driver is to accept in-bound TCP or UDP communications. Select an existing IP Network Listener tag using the drop-down list. If the IP Network Listener is configured, this driver must use the VRTU, configured on the VRTU tab.

IP Allow

Optional. Misconfiguration of this field is a common source of problems.

Used in connection with an IP Network Listener tag. General IP address filtering should be set on the IP Network Listener, as this will be more efficient. The list of allowed IP addresses in the driver is intended to prevent misconfigured devices from interfering with other devices.

Both filters (that in the Network Listener and this one) can be configured at the same time. The filter in the IP Network Listener will be applied when the device first connects and the local filter will be applied after a specific driver instance has been identified.

IEC 60870-5-104 Driver Configuration - Protocol

ASDU Address Size

Specifies the size of the Application Service Data Unit in the protocol in number of bytes. This can either be 1 or 2, where the default is 2.

IO Address Size

Specifies the size of the Information Object Address (IOA) in the protocol in number of bytes. This can either be 1 or 2, where the default is 2.

Origin Address

Specifies whether the Origin Address should be included in the protocol messages. Enabled by default.

GI Poll Rate

Specifies the rate in seconds at which a general interrogation will be requested.
Note that if the Device is connected and a session is established, a general interrogation is not necessary and will not be performed.

Select Execute Command

If selected, a command will send a Select message before an Execute message.
Otherwise, only an execute message will be sent.

Select Execute Setpoint

If selected, a Setpoint will send a Select message before an Execute message.
If not true, only an execute message will be sent.

Disconnect After GI Poll

Specifies whether the connection should be closed after a general interrogation (GI)poll.

Poll for Global ASDU

When VTScada (as a master) connects to other IEC devices, it makes an interrogation inquiry to ask the device to send all of it's configured values. If the Poll from Global ASDU is selected, that request is broadcast to all connected devices, therefore VTScada will get data for all of the devices on the network, regardless of whether that data is needed.

If this option is not selected (default), VTScada will make individual requests to each ASDU configured within VTScada only.

Counter Freeze

Specifies whether a counter should be frozen while it is being read.

Counter Reset

Specifies if a counter should be reset after it has been read.

Counter Poll

Specifies whether a counter should be polled.

IEC 60870-5-104 Driver Configuration - Virtual IO

Enable Virtual RTU

Specifies whether this instance of the IEC Driver will operate in a Slave Configuration. If selected, the Virtual RTU functions are enabled and the driver will respond to IEC 60870-5-104-104 master requests.

Select / Execute Timeout (s)

Duration in seconds of a Select or Execute command.

Command Action Termination

Specifies whether an ACT-TERM message is sent following an ACT-CONF message.

Short Pulse Duration (s)

The duration in seconds of a Short Pulse for a command operations.

Long Pulse Duration (s)

The duration in seconds of a Long Pulse for a command operations.

IEC 60870-5-104 Driver Configuration - Virtual IO Config

ASDU Address

The Application Service Data Unit (ASDU) address of the data item. This is an integer between 1 and 65534.

IO Address

The Information Object Address (IOA) of the data item.

ASDU Type

Specify the Application Service Data Unit type of the data item.

New / Edit / Delete

Dialogs for working with entries in this table. Note that the Delete tool will not prompt for confirmation.

Closed IEC 60870-5-104 Driver Tag Widgets

The following widgets are available to display information about your IEC 60870-5-104 driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

IEC 60870-5-104 Communication Messages Dialog

IEC 60870-5-104 Driver Statistics Dialog

GI Poll Button

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Reset Polling History Widget

Rewrite Outputs Widget

Sparklines Widget


IEC 60870-5-104 Addressing

When connected to an IEC 60870-5-104 driver, I/O tags will provide an address assist button.

The dialog varies depending on whether you are creating an address for reads or for writes. Scroll for the relevant version.

IEC Address Assist I/O Reads

IEC 60870-5-104 addresses will have the following format:

ASDUAddr.ASDUType:InfoObjAddr[/:QOC]

Where...

Field | Description
ASDUAddr | Application Service Data Unit Address. An integer value
ADUType | Application Service Data Type (see following tables)
InfoObjAddr | Information Object Address (IOA). An integer value.
QOC | The Quality of Command (optional)

The following Address Assist dialog is provided to help you build these addresses. There are three versions of this dialog depending on whether you are creating a Read Address, Write Address or VRTU Address (Slave).

Read Address selection dialog

Device ASDU Address

The Application Service Data Unit Address, an integer value.

Info Object Address

The Information Object Address (IOA) of the data item an integer value

ASDU Address Data Bytes

Shows the ASDU Address as it is represented by the protocol.

Info Object Address Data Bytes

Shows the IOA Address as it is represented by the protocol.

Read Type

Select from the list of available Read Types:

ASDU Read Type | Type Identification | Type Identifier
SINGLEPOINT | 2, 30 | M_SP_TA, M_SP_TB
SINGLEPOINTNOTIME | 1, 20 | M_SP_NA, M_PS_NA,
DOUBLEPOINT | 4, 17, 31, 38 | M_DP_TA, M_EP_TA, M_DP_TB, M_EP_TD
DOUBLEPOINTNOTIME | 3 | M_DP_NA
STEPPOSITION | 6, 32 | M_ST_TA, M_ST_TB
STEPPOSITIONNOTIME | 5 | M_ST_NA
BITSTRING | 8, 33 | M_BO_TA, M_BO_TB
BITSTRINGNOTIME | 7 | M_BO_NA
NORMALIZED | 10, 21, 34 | M_ME_TA, M_ME_ND, M_ME_TD
NORMALIZEDNOTIME | 9 | M_ME_NA
SCALED | 12, 35 | M_ME_TB, M_ME_TE
SCALEDNOTIME | 11 | M_ME_NB
FLOAT | 14, 36 | M_ME_TC, M_ME_TF
FLOATNOTIME | 13 | M_ME_NC
INTEGRATED | 16, 37 | M_IT_TA, M_IT_TB
INTEGRATEDNOTIME | 15 | M_IT_NA

Reverse Byte Order (ABB)

Swaps the byte order of the ASDU Address Data Bytes and Info Object Address Data Bytes fields, used by ABB PLC.

Qualifier Information

Use to add optional Qualifier Information to the address.

Bit Number

The bit number if reading a single bit from a word.

Device Tags

A list of tags that have been retrieved by a General Interrogation poll from the target device. Selecting one of these tags will update the other fields with the correct information for the selected Tag. Note that a valid connection to the device must be established before any tags will appear in this list and a ASDU Address must be specified.

New Address

Displays the constructed address.

Example I/O Reads:

To read a Float Value from ASDU 1 at Information Object Address 11, the address would be:

1:Float:11

To read a Single Point Digital Value from ASDU 2 at Information Object Address 201, the address would be:

2:SinglePoint:201

IEC Address Assist I/O Writes

The following Address Assist dialog is provided to help you build the addresses used to write to equipment:

Write Address selection dialog

Device ASDU Address

Enter the Device ASDU address.

Write Type

Select one of the following write types:

ASDU Read Type | Type Identification | Type Identifier
SINGLECOMMAND | 58 | C_SC_TA
DOUBLECOMMAND | 59 | C_DC_TA
REGSTEPCOMMAND | 60 | C_RC_TA
NORMALISEDCOMMAND | 61 | C_SE_TA
SCALEDCOMMAND | 62 | C_SE_TB
FLOATCOMMAND | 63 | C_SE_TC
BITSTRINGCOMMAND | 64 | C_BO_TA

Info Object Address

Specify the Information Object Address (IOA) of the data item an integer value.

Qualifier Information (Displayed only when a Write Type is selected)

Either a data-entry field, or a selection of the following, depending on the Write Type.

  • No Additional Information
  • Short Pulse Duration
  • Long Pulse Duration
  • Persistent Output

New Address

Displays the constructed address.

Example I/O Writes:

To set a Digital Value in ASDU 1 at Information Object Address 100 with a short duration, the address would be:

1:SingleCommand:100:1

To write a Float Setpoint in ASDU 5 at Information Object Address 10, the address would be:

5:SetpointFloat:10

Slave Type

Slave mode (Virtual RTU selected on the driver)

Configuration properties match those already described for Read and Write addresses.


IEC Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
257 | 0x101 | Serial Port Parameter(s) Out Of Range
258 | 0x102 | Serial Port Not Active
259 | 0x103 | TCP/IP Port Failed to Connect
260 | 0x104 | TCP/IP Port Disconnected
261 | 0x105 | Serial Port inactivity timeout
511 | 0x1FF | Communication channel not available
512 | 0x200 | Data Link - Invalid Command
513 | 0x201 | Data Link - Timed Out Waiting For Echo
514 | 0x202 | Data Link - No Reply
515 | 0x203 | Data Link - No Acknowledge
516 | 0x204 | Data Link Reset - No Acknowledge
517 | 0x205 | Tag Address not configured in the device
518 | 0x206 | Failed to synchronize time
768 | 0x300 | ASDU Address Error
769 | 0x301 | ASDU Type Address Error
770 | 0x302 | Information Object Address Error
771 | 0x303 | QOC Address Error
772 | 0x304 | ASDU Type Out of Range
773 | 0x305 | ASDU Address Out Of Range
774 | 0x306 | Info Object Address Out Of Range
776 | 0x308 | Data unavailable
777 | 0x309 | Unknown ASDU Type
778 | 0x30A | Unknown cause of transmission
779 | 0x30B | Unknown common address of ASDU
780 | 0x30C | Unknown information object address
781 | 0x30D | Incorrect response to select command
782 | 0x30E | Incorrect response to execute command
783 | 0x30F | Incorrect response - no CON received
784 | 0x310 | Incorrect response to GI Poll
785 | 0x311 | Invalid Header Byte
786 | 0x312 | Timeout Waiting for Length
787 | 0x313 | Invalid Message Length
788 | 0x314 | Timeout waiting for APCI


JSON/XML Driver

Not counted towards your tag license limit.

Given a fixed URL Closed Uniform Resource Locator. The address of a web page., the driver will read the JSON Closed JavaScript Object Notation or XML data at that address and turn it into a nested VTScada dictionary with arrays.

Data may be read by attached I/O tags such as Analog Status, Digital Status or String I/O as appropriate. The address will depend on the structure of the JSON or XML file, therefore an Address Assist dialog is provided. All I/O tags linked to this driver will gain an address assist button automatically. The contents of the resulting dialog will be populated from the file. If the file cannot be read for any reason, then no addresses will be available.

Supports responses compressed via deflate or gzip methods.

The JSON/XML driver works in one direction only: it reads data into VTScada. It does not write data out to external URLs.

Multiple JSON/XML drivers connecting to the same domain will do so sequentially by default. This may cause unnecessary wait times. Configure your application so that your JSON/XML drivers connect to a specific domain in parallel for more efficient simultaneous data transfer. See Connect JSON/XML Drivers in Parallel for more information.

Error codes

JSON/XML drivers connect to web servers. Therefore, most errors that you might see will be a standard HTTP code. 401 (unauthorized access attempt) and 404 (page not found), are common. Other possible error codes include:

  • -1: Connection timed out
  • -2: Response timed out
  • -3: Invalid (non-HTTP) response
  • -4: Incomplete response
  • -5: Unsupported transfer-encoding
  • -6: Missing parameters

Related information:

Best Practices for Tags

Closed JSON/XML Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

JSON/XML Driver properties Settings tab

JSON/XML Driver properties Settings tab

The Settings tab includes the following properties:

URL

This is the address of the file containing either JSON or XML-formatted data to be read by the driver.

Use the selector below the address to specify which of the two supported data types will be found at this URL. If the URL does not specify a port number, then it will default to 80 for unsecured connections and 443 for secured connections.

Username and Password

If required by the remote system, provide the Username and Password required to access the file. Note that the password will displayed as "***" characters and will be stored in an encrypted form.

Polling Interval

Set the frequency in seconds for fresh reads of the URL. This defaults to 60 seconds.

Processor

The name of a JSON/XML processor. Standard (the default processor) supports live values being read from the site, but does not provide support for timestamped historical data, forecast data, or dynamic data where the payload structure can change. For these cases, you can write your own processor that will handle complex data structures. See: Write a JSON/XML Processor

Connection Time Limit (s)

Sets the time in seconds that the driver will wait for a response before it gives up and retries or sets an error if all retries have been attempted.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Max Request Rate (per second)

The maximum number of requests to send per second to the host. The default is an unlimited rate.

A limited rate is necessary for situations where a host may reject a client if it has received more than X requests per second from that client.

Typically, all driver instances that use the same host would be configured with the same Max Request Rate, but this is not required. Each driver will enforce only its own specified rate limit.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

External Trigger

Optionally, specify a tag or expression that will cause a fresh read of the URL to be performed.

JSON/XML Driver properties Extra HTTP Headers tab

Some APIs may require extra information such as tokens, form data, etc. Use this tab to specify name=value pairs to be added to the header. Values may be specified here, or supplied from expressions or tags.

Closed JSON/XML Driver tag Widgets

The following widgets are available to display information about your application’s JSON/XML Driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Show Statistics Button Widget

Data Age Widget

Equipment / Status Color Indicator

JSON/XML Statistics Dialog

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget


JSON/XML Driver Address Assist

Inline DTD and schemas represent an inherent security risk and are not supported by the JSON/XML driver. If you attempt to read such a file, the message, "error: DTD is prohibited" will be returned. No value will be read into the attached I/O.

Elements within a JSON or XML file are addressed using a dot-separated format. For example, given the following XML file:

<?xml version="1.0" encoding="UTF-8" ?>
<xmldoc>
  Root value
  <tests>
    <subnode>val 1</subnode>
    <subnode>val 2</subnode>
  </tests>
</xmldoc>

An address assist dialog will appear as follows:

JSON / XML Address Assist

The address of the first subnode will be:

.xmldoc.tests.subnode[0]

And, the value returned will be "val 1". A String I/O tag is recommended for text values.


Koyo DirectNET Driver

Not counted towards your tag license limit.

The Koyo driver started out as a Texas Instrument (TI) driver. Koyo purchased the technology, therefore new PLCs using this protocol bear the Koyo name. This driver works with the 200 / 300 and 400 series of PLCs.

The current Koyo addressing formats work only for the DL series of PLCs.

Related information:

Koyo Driver Addressing

Koyo Error Codes

Best Practices for Tags

Related Application Properties

KoyoSharedRPC - Koyo shared RPC. If set, all Koyo PLCs will share the same RPC name, "KoyoDriverService". Defaults to false (0). drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

KoyoFailoverCount - Number of communication failures before switching to backup. Defaults to 1.

Closed Koyo Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Koyo Driver properties Configuration tab

The Configuration tab includes the following properties:

Port

This is the name of the port tag that will be used to communicate with the PLC and can be a serial port tag, a TCP/IP port tag or a UDP/IP port tag. Note that TCP/IP and UDP/IP can only be used in combination with a terminal server to convert the TCP/IP or UDP/IP to the serial communications needed to interface with the PLC at the far end. There are Koyo PLCs available that communicate directly on TCP/IP but they use a protocol that is not supported by this driver.

PLC Type

Sets the Koyo / TI PLC type with which you are communicating. Valid types selected from the drop list are: 205, 315, 315S, 320, 320S, 325, 325S, 330, 330S or 405.

Time-Out Limit

Sets the time in seconds that the driver will wait for a response before it gives up and retries or sets an error if all retries have been attempted.

VTScada Address

Sets the address of the VTScada server that is communicating with the Koyo PLC. The valid range is 0 to 80.

Station Address

Sets the address of the PLC station with which the device will communicate. The valid range is 0 to 80.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Closed Koyo Driver tag Widgets

The following widgets are available to display information about your application’s Koyo Driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

Koyo Driver Communication Messages Dialog

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget


Koyo Driver Addressing

The current Koyo addressing formats work only for the DL series of PLCs.

The input / output tags addressed under the Koyo driver use the addressing system shown here. The simple format of prefacing the address with the register or bit type to be used is utilized. The limits on any actual addresses will depend on the configuration of the system and type of CPU used. Note that bits can be extracted for word addresses by adding a "/" separator followed by the bit number. For example:

R100/0 will read bit zero of the 8 bit data register R100.

Address Type | Data Type
X | Discrete Inputs
Y | Discrete Outputs
R | 8 Bit Data Registers
CT | Counter Status Bits
T | Timer Status Bits
CTR or CNT | Counter Accumulated Values
TMR | Timer Accumulated Values
SEQ | Sequencers
SR | Shift Registers
ST or S | Stages
V | Variable Memory
GX | Global Inputs
SP | Special Relays
SC | Scratchpad
D | Diagnostics

Some typical addresses would use the address types listed above followed by the register or bit number. Such as:

X10, Y20, TMR100 or V4010


Koyo Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
000 | 0x0 | No Error
001 | 0x1 | Timed Out Waiting For Response To Enq
002 | 0x2 | Bad Response To Inquire
003 | 0x3 | Timed Out Waiting For Header ACK
004 | 0x4 | NAK Response To Header
005 | 0x5 | Unknown Response To Header Error
006 | 0x6 | Timed Out Waiting For Write Data Block ACK
007 | 0x7 | Bad Response To Write Block
008 | 0x8 | Timed Out Waiting For Read Block
009 | 0x9 | Timed Out Waiting For EOT Marker
012 | 0xc | Invalid Address
013 | 0xd | Address Error
014 | 0xe | Read Module Timeout
015 | 0xf | Write Module Timeout
016 | 0x10 | Retry Limit Exceeded
017 | 0x11 | Serial Port Error
018 | 0x12 | Invalid PLC
020 | 0x14 | Unknown Error Code


MDS Diagnostic Driver

Not counted towards your tag license limit.

The MDS diagnostic driver tags enable users to read statistics from any given MDS radio.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Reference Notes:

MDS diagnostic driver tags are required only in applications where you wish to gather data about an MDS radio. For example, a common arrangement might be an MDS radio connected to your PC, and a secondary MDS radio connected to an RTU or PLC at a remote location. To collect data from the RTU or PLC, your VTScada application could use an appropriate communication driver tag (e.g. Allen-Bradley or Modicon), however, if you wish to gather data about either MDS radios in such a scenario (e.g. the temperature of an MDS radio), your application will require an MDS diagnostic driver tag.

The MDS Diagnostic Driver was written for use with the x710 radios. These radios have a DLINK (Diagnostic Link) feature that can be enabled or disabled to allow diagnostic data (RSSI, radio temperature, supply voltage, etc.) to be transmitted to the master radio and read at its serial port (using our MDS Diagnostic Driver or software from MDS). This data is added by the radios to the regular packets transmitted when polling a remote PLC or RTU.

The SD line of radios is backwards-compatible with the x710 and can also use the DLINK feature if operated in x710 mode.

The Orbit series is Ethernet based using SNMP and Netconf to obtain performance information that can be monitored using GE MDS PulseNET. From the Orbit Technical manual, section 3.8.18 details the Simple Network Monitoring Protocol (SNMP) setup. It supports V1, V2 and V3 with traps. VTScada has a native SNMP Driver which should be used to support monitoring of system and network interface status of this radio series.

Related information:

MDS Diagnostic Driver I/O Addressing

MDS Error Codes

Best Practices for Tags

Closed MDS Diagnostic Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

MDS Diagnostic Driver properties Serial tab

The Serial tab of the MDS diagnostic driver tag properties folder is used to indicate the serial port to which the MDS radio associated with this tag is connected.

MDS Diagnostic driver serial tab

Port

The Port field enables you to select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag.

In order to connect to MDS radio port with VTScada, you can use one of several different hardware solutions:

  • Serial port cable connected directly.

For this case, configure and select a Serial Port tag.

  • Stand alone serial modem connected to the serial port on the radio.

VTScada has its own modem that is used to dial up the modem connected to the radio. For this option, configure and select a serial port that is using a modem.

  • Ethernet terminal server connected to the serial port on the radio.

VTScada is connected to the same network as the terminal server and can connect to it with either a TCP/IP or UDP/IP port tag

Any type of VTScada port tag may be used, but it must match the hardware connection to the radio.

Time-Out Limit

Set the time in seconds or fractions of a second that this driver should wait for a reply from the remote unit.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Actively Retrieve Values

Indicates that messages should be sent out in active mode, rather than passive mode.

If the Actively Retrieve Values check box is selected, messages will be sent out in active mode (i.e. a request for data from the MDS radio will be immediately sent).

If the Actively Retrieve Values check box is not selected (default), the data will be sent out in passive mode (i.e. a request for data from the MDS radio will be held until another request for data from the associated RTU or PLC is made).

Closed MDS Diagnostic Driver Tag Widgets

The following widgets are available to display information about your application’s MDS diagnostic driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget


MDS Diagnostic Driver I/O Addressing

MDS radio diagnostic data can be obtained by reading from predefined addresses. Supported models are: TransNET, x790, x710, and SD series radios.

An analog or digital tag should be configured for each item of diagnostic information of interest. Note that not all radio models support all diagnostic data. Please refer to the manufacturer’s manuals to find the available diagnostic data for individual models and the proper radio configuration to enable diagnostics.

The following predefined addresses are available for analog tags:

RSSI.VAL | Received signal strength, in dBm. Analog tags with this address should use the following scaling:
Unscaled Min 136
Unscaled Max 206
Scaled Min -120
Scaled Max -50
SNR.VAL | Signal to noise radio, in dBm.
TEMP.VAL | Internal radio temperature, in degrees C.
VOLT.VAL | Primary supply voltage in mV.
CUR.VAL | Primary supply current in mA.
SVOLT.VAL | Secondary power supply #1 voltage, in mV.
SVOLT2.VAL | Secondary power supply #2 voltage, in mV.
SVOLT3.VAL | Secondary power supply #3 voltage, in mV.
TXFPOW.VAL | Transmit forward power, in dBm.
TXRPOW.VAL | Transmit reverse power, in dBm.
LNACUR.VAL | Low Noise Amplifier current, in mA.

The following predefined addresses are available for digital tags
(0 = OK, 1 = BAD):

RSSI.ERR | RSSI status
SNR.ERR | SNR status
TEMP.ERR | Temperature status
CUR.ERR | Primary supply current status
SVOLT.ERR | Secondary power supply #1 voltage status
SVOLT2.ERR | Secondary power supply #2 voltage status
SVOLT3.ERR | Secondary power supply #3 voltage status
TXFPOW.ERR | Transmit forward power status
TXRPOW.ERR | Transmit reverse power status
LNACUR.ERR | Low Noise Amplifier current status

The address structure is <radio unit #>:<address>.

For example, to read supply voltage on radio 3258, the address is "3258:VOLT.VAL".


MDS Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No Error
01 | 0x1 | Invalid Address
02 | 0x2 | Communication Failure
03 | 0x3 | Unrecognized Message Type
04 | 0x4 | Message Parsing Failure
06 | 0x6 | Retry Limit Exceeded
07 | 0x7 | Diagnostic Mode Error
08 | 0x8 | Radio Type Error
09 | 0x9 | Write Not Supported
10 | 0xa | Unrecognized Register Access
11 | 0xb | Invalid Get Request
12 | 0xc | Invalid Put Request
13 | 0xd | Unavailable Get Request
14 | 0xe | Unavailable Put Request
15 | 0xf | Failed Get Request
16 | 0x10 | Failed Put Request


Mitsubishi Driver

Provides support for the Mitsubishi iQ-R and Q series of PLC's.

Communication uses theMELSEC protocol, which is a Mitsubishi-specific protocol that can be used to speak to their various models of PLCs. It consists of various frame types based on the PLC and communication type (Ethernet or serial), and supports two different encodings: Binary and ASCII. Binary is the more efficient encoding, but ASCII can be more readable to some packet monitoring tools.

Support is provided for the following frame and format type combinations:

PLC Series | CPU Type | Frame Type | Format Type | Communication Mode
iQR | n/a | 3E | n/a | Binary ASCII
 |  | 4E | n/a | Binary ASCII
 |  | 2C | Format 1 Format 2 Format 4 | n/a
 |  | 3C | Format 1 Format 2 Format 4 | n/a
 |  | 4C | Format 1 Format 2 Format 4 Format 5 | n/a
Q | Basic Model QCPU Universal Model QCPU High Performance Model QCPU | 3E | n/a | Binary ASCII
 |  | 4E | n/a | Binary ASCII
 |  | 2C | Format 1 Format 2 Format 4 | n/a
 |  | 3C | Format 1 Format 2 Format 4 | n/a
 |  | 4C | Format 1 Format 2 Format 4 Format 5 | n/a
FX3U | n/a | 1E | n/a | Binary ASCII

Format Type 3 is not currently supported.

The driver supports batch read and writes for device data using device-level commands.

Related information:

Best Practices for Tags

Closed Mitsubishi Driver tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Mitsubishi Driver tag properties: Options tab

Refer to the table at the beginning of this topic for supported combinations of PLC Series, Frame Type and Format Type.

PLC Series

Select from the iQR, Q and FX3U series of PLC.

CPU Type

Enabled only for the Q series of PLC. Select between the following:

  • Basic Model QCPU
  • Universal Model QCPU
  • High Performance Model QCPU

Frame Type

Choose between 3E or 4E, 2C, 3C or 4C as appropriate for your device. 1E is only available for FX3U series.

Format Type

Only supported for serial frames. Available format types (from 1 through 5) vary depending on the selection of Frame Type.

Format type 3 is not currently supported.

Communication Mode

Only supported for ethernet frames. Choose between Binary or ASCII as appropriate for your device. Binary is the more data-efficient option if a choice is available.

Check Sum

Only supported for serial frames. Choose whether the driver should examine the check sum code.

Station Number

Only supported for serial frames. Specify the station to be connected from an external device.

This Station Number

Only supported for serial frames. Specify this when more than one external device (m stations) and more than one C24s (n stations) are connected with the multidrop connection. Specify the fixed value (00H) for any cases other than multidrop connection in the form, m:n.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Mitsubishi Driver tag properties: Communications tab

Port

The port tag through which this driver communicates to a device, usually either a serial port tag or a TCP/IP tag.

Timeout Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Retry Delay

Sets the length of time (in seconds or fractions of a second) that the driver will wait between attempts to repeat a transmission of data if the previous attempt(s) have failed.

By default, the Retry Delay field is set to 0 (indicating that there should be no delay between retry attempts).

RTS Key Off Delay

The length of time (in seconds) that this device will wait before dropping RTS at the end of a data transmission.

PLC Monitoring Timer

Measured in multiples of 0.25 seconds. This is the time to wait for the PLC to process messages. Set to 0 for "indefinite".

Closed Mitsubishi Driver Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Mitsubishi Driver Communication Messages Dialog

Mitsubishi Driver Statistics Dialog

Comm Indicator Widget

Comm Line Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Mitsubishi Addressing

The Mitsubishi driver supports the MELSEC Device style of addressing for retrieving data from the PLC Device registers. Support for serial frames 2C, 3C, and 4C, formats 1, 2, 4 and 5 (only 4C can support format 5) has been added for both the Q series and iQR series PLCs. Support for the 3E and 4E frames has been added for the Q series PLC.

Examples of valid addressing include D0 to read the D device at index 0 in the D register table, or M100 to read the data from index 100 in the Device table. Note that the devices are 0 based.

(For example, D0 or M0).

An Address Select dialog is available within your I/O tags when configured to use a Mitsubishi driver. There are two forms:

Form 1: Address Select in Device mode

Form 2: Address Select in Label mode

Device Mode Options - iQR Series

Address

Displays the address resulting from configuration of the following options.

Device

Available device prefixes.

Note that the range available to each is configured within the PLC. Many prefixes are limited to specific data types.

Data Type Prefix | Data Type | Range
D | Data register | 0-5923327
W Link register

0-5923327

TN | Timer value | 0-5265151
CN | Counter value | 0-5265151
STN | Retentive timer value | 0-5265151
LCN | Long counter value | 0-2787391
TS | Timer contact | 0-5265151
TC | Timer coil | 0-5265151
X

Input

0-12287
Y | Output | 0-12287
M | Internal relay | 0-94773247
B | Link relay | 0-5923327
L | Latch relay | 0-32767
F | Annunciator | 0-32767
V | Edge relay | 0-32767
CS | Counter contact | 0-5265151
CC | Counter coil | 0-5265151
STS | Retentive timer contact | 0-5265151
STC | Retentive timer coil | 0-5265151
LCS | Long counter contact | 0-2787391
LCN | Long counter coil | 0-2787391

Register

The index number of the device you wish to read/write.

Size

The data size of the chosen device type.

Bit Number

Used to read a specific bit from a device that contains more than 1 bit and will add the VTScada separator code to the address.

Label Mode Options

The Melsec Label addressing scheme for iQR series PLCs is supported. Use this to define labels, arrays, and structures in the PLC and to use the label names as the address in tags reading from the PLC.

Supported data types include bit, signed word, unsigned word, signed double word, unsigned double word, float, and double precision float. Multidimensional arrays are supported, but no limitation is placed on the index bounds in VTScada. The use of indices greater than those defined in the PLC may work, but is not recommended.

The address used internally by VTScada for Melsec label addressing follows the form of the address from the PLC with the defined data type appended, following a colon. The data type used in the VTScada address must match that defined in the PLC for the given label. (Data Suffixes for Tag I/O Addressing)

Examples:

MyArray[1,2,3]:bit
MyLabel.StructureMember1:UDWord
Label1:Double

Address

Displays the address resulting from configuration of the following options.

Label

Enter the label to be used.

Data Type

Select from the drop-down list of supported data types. The colon separating the data type from the label is added automatic

Support for Q-Series PLCs and Serial Frames

This driver provides support for three CPU types of the Q series PLC, as well as for serial format frames.

Basic CPU

Device
Code 		Device Data type Range
SM | Specific Relay | bit | 0-1023

SD

Specific Register word 0-1023

X

Input bit 0-2047

Y

Output bit 0-2047

M

Internal Relay bit 0-8191

L

Latching Relay bit 0-2027
F | Alarm | bit | 0-1023

V

Variant Relay bit 0-1023

B

Link Relay bit 0-2047

D

Data Register word 0-11135

W

Link Register word 0-2047

TS

Timer Contact bit 0-511

TC

Timer Coil bit 0-511

TN

Timer Present Value word 0-511

SS

Retentive Counter Contact bit 0-511

SC

Retentive Counter Coil bit 0-511

SN

Retentive Counter Present Value word 0-511
CS | Counter Contact | bit | 0-511
CC | Counter Coil | bit | 0-511
CN | Counter Present Value | word | 0-511
SB | Link Specific Relay | bit | 0-1023
SW | Link Specific Register | word | 0-1023
S | Step Relay | bit | 0-2027
DX | Direct Access Input | bit | 0-2047
DY | Direct Access Output | bit | 0-2047
Z | Variant Register | word | 0-9
R | File Register - Block Toggle Method | word | 0-32767
ZR | File Register - Linked Access Method | word | 0-65535

High performance CPU

Device
Code 		Device Data type Range
SM | Specific Relay | bit | 0-2047

SD

Specific Register word 0-2047

X

Input bit 0-8191

Y

Output bit 0-8191

M

Internal Relay bit 0-8191

L

Latching Relay bit 0-8191
F | Alarm | bit | 0-2047

V

Variant Relay bit 0-2047

B

Link Relay bit 0-8191

D

Data Register word 0-12287

W

Link Register word 0-8191

TS

Timer Contact bit 0-2047

TC

Timer Coil bit 0-2047

TN

Timer Present Value word 0-2047

SS

Retentive Counter Contact bit 0-2047

SC

Retentive Counter Coil bit 0-2047

SN

Retentive Counter Present Value word 0-2047
CS | Counter Contact | bit | 0-1023
CC | Counter Coil | bit | 0-1023
CN | Counter Present Value | word | 0-1023
SB | Link Specific Relay | bit | 0-2047
SW | Link Specific Register | word | 0-2047
S | Step Relay | bit | 0-8191
DX | Direct Access Input | bit | 0-8191
DY | Direct Access Output | bit | 0-8191
Z | Variant Register | word | 0-15
R | File Register - Block Toggle Method | word | 0-32767
ZR | File Register - Linked Access Method | word | 0-1042431

Universal CPU

Device
Code 		Device Data type Range
SM | Specific Relay | bit | 0-2047

SD

Specific Register word 0-2047

X

Input bit 0-8191

Y

Output bit 0-8191

M

Internal Relay bit 0-8191

L

Latching Relay bit 0-8191
F | Alarm | bit | 0-2047

V

Variant Relay bit 0-2047

B

Link Relay bit 0-8191

D

Data Register word 0-12287

W

Link Register word 0-8191

TS

Timer Contact bit 0-2047

TC

Timer Coil bit 0-2047

TN

Timer Present Value word 0-2047

SS

Retentive Counter Contact bit 0-2047

SC

Retentive Counter Coil bit 0-2047

SN

Retentive Counter Present Value word 0-2047
CS | Counter Contact | bit | 0-1023
CC | Counter Coil | bit | 0-1023
CN | Counter Present Value | word | 0-1023
SB | Link Specific Relay | bit | 0-2047
SW | Link Specific Register | word | 0-2047
S | Step Relay | bit | 0-8191
DX | Direct Access Input | bit | 0-8191
DY | Direct Access Output | bit | 0-8191
Z | Variant Register | word | 0-15
R | File Register - Block Toggle Method | word | 0-32767
ZR | File Register - Linked Access Method | word | 0-1042431

Support for FX3U-Series PLCs and 1E Frame

Device
Code 		Device Data type Range
D | Data Register | word | 0-8511
R | Extension Register | word | 0-32767
TN | Time Current Value | word | 0-511
TS | Timer Contact | bit | 0-511
CN | Counter Current Value | word | 0-199
dword | 200-255
CS | Counter Contact | bit | 0-255
X | Input | bit | 0-255
Y | Output | bit | 0-255
M | Auxiliary Relay | bit | 0-7679
8000-8511
S | State | bit | 0-4095


Mitsubishi Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0000 | No Error
2 | 0x0002 | The device range destination of devices to be read/written from/to is incorrect
80 | 0x0050 | Codes for the command/response type of a subheader are not within the specifications
81 | 0x0051 | The start address specified by a connected device has been set outside the range from 0 to 6143
82 | 0x0052 | The requested data range goes outside of the allowable range
84 | 0x0054 | ASCII message cannot be converted to proper binary command
85 | 0x0055 | Attempted to write while program is being editted and SLMP is disabled
86 | 0x0056 | Incorrect device specified
87 | 0x0057 | A device address is out of range
88 | 0x0058 | The start device address is out of range
89 | 0x0059 | An extension file register cannot be specified
96 | 0x0060 | The CPU exceeded the monitoring timer to respond
512 | 0x0200 | Timed Out Waiting for Response from Remote
513 | 0x0201 | Timed Out Waiting for Echoed Message
514 | 0x0202 | Illegal Device Address
515 | 0x0203 | Unexpected Device Response
516 | 0x0204 | Frame Error
517 | 0x0205 | CheckSum Mismatch
768 | 0x0300 | No Error
769 | 0x0301 | Port Not Defined
770 | 0x0302 | Port Failed To Connect
771 | 0x0303 | Port Lost Connection
772 | 0x0304 | Serial Port Settings Out of Range
773 | 0x0305 | Serial Port Already In Use or Not Available
774 | 0x0306 | Serial Port Access Denied
775 | 0x0307 | Serial Port General Failure
776 | 0x0308 | Serial Port Invalid Parameter
777 | 0x0309 | Port Not Connected
784 | 0x0310 | Port Unknown Error
16385 | 0x4001 | Unsupported request
16386 | 0x4002 | Unsupported request
16388 | 0x4004 | The CPU module is starting up.
16389 | 0x4005 | The amount of data handled according to a specified request is out of range
16390 | 0x4006 | Initial communication has failed
16392 | 0x4008 | The CPU module is BUSY
16395 | 0x400B | A set value of data handled according to a specified request is invalid
16400 | 0x4010 | The request cannot be executed because the CPU module is running
16403 | 0x4013 | The request cannot be executed because the CPU module is not in the STOP state
16432 | 0x4030 | The specified device is not supported
16433 | 0x4031 | The specified device number is out of range
16435 | 0x4033 | Writing cannot be done because the specified device is for system use
16512 | 0x4080 | Request data error
16576 | 0x40C0 | The specified label name does not exist
28992 | 0x7140 | Request Data Error
28994 | 0x7142 | Unsupported Register Name
28995 | 0x7143 | Start Register Address Out of the Range
29009 | 0x7151 | PLC Number Above the Range
29011 | 0x7153 | Length of Frame Out of Receive Range
29028 | 0x7164 | Request Content Error
29039 | 0x716F | Unsuppoted Register
29040 | 0x7170 | Request Points Out of Range
29041 | 0x7171 | Unsupported Register Name
32320 | 0x7E40 | Unsupported Command or Subcommand
32321 | 0x7E41 | Out of Points Range When Random Read/Write
32322 | 0x7E42 | Request Points Out Of Command Range
32323 | 0x7E43 | Unsuppoted Register
32324 | 0x7E44 | Timeout When Receive Response
32327 | 0x7E47 | Receive Another Response Before Specified Response
32333 | 0x7E4D | Change Mode When Data Send or Receive
32335 | 0x7E4F | Request Number of Register Error
32351 | 0x7E5F | IO index Error of Request Target Module
32353 | 0x7E61 | Interval Unit Setting Out of Range
32367 | 0x7E6F | Modem's Connection Destination Mismatch
32451 | 0x7EC3 | Resend Request When During Process
32452 | 0x7EC4 | Send Data's Length Exceeds the Setting of Transceiver Buffer
32513 | 0x7F01 | Receive Another Response Before Finish Last Response Processing
32544 | 0x7F20 | Conversion Error From ASCII to Binary
32545 | 0x7F21 | Receive Header Error
32546 | 0x7F22 | Unsupported Command or Register
32547 | 0x7F23 | No Data After Header
32548 | 0x7F24 | CheckSum Mismatch
32549 | 0x7F25 | Receive Data's Length Exceeds the Settings of Transceiver Buffer
32615 | 0x7F67 | Receive Another Response Before Finish Last Response Processing
32616 | 0x7F68 | Frame Error
32617 | 0x7F69 | Parity Check Error
32618 | 0x7F6A | Full Transceiver Buffer Error
32753 | 0x7FF1 | Set Value Error
32754 | 0x7FF2 | Unsuppoted Command
49233 | 0xC051 | The number of read/write points from/to the device is out of range (word)
49234 | 0xC052 | The number of read/write points from/to the device is out of range (bit)
49240 | 0xC058 | The request data length after ASCII-to-binary conversion does not match the size of the character area
49242 | 0xC05A | The Ethernet-equipped module cannot read/write data from/to the device specified
49243 | 0xC05B | The Ethernet-equipped module cannot read/write data from/to the device specified
49249 | 0xC061 | The specified message length does not match actual length


Modbus Compatible Device Driver

Not counted towards your tag license limit.

The Modbus Compatible Device driver provides an interface to a Modicon PLC.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Modbus drivers will commonly connect to TCP on port # 502, although variations may be found.

This driver supports multiple TCP/IP port connections between a single instance of the driver and the RTU.

Closed Reference Notes:

Any of the following communication channels may be used:

  • Serial RTU
  • Serial ASCII
  • SA-85 I/O card for ModBus Plus communications
  • Embedded TCP/IP
  • Open Modbus TCP

This driver has the ability to save the last value written to each output tag, and to rewrite those values, either automatically when lost communications are restored, or manually by the press of a button. Carefully review the information in the Options tab to decide whether this feature should be used in your application. If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

The number of bytes in a Modbus message is limited by the setting: ModiconVTSMaxBlock. By default, this is 125.

When this driver is used in combination with a TCP/IP tag, the standard TCP port is 502.

"Type specified" means addresses such as the HC1 and IR2 format. This does not apply to addresses written as numbers only. (For example, 40001 is always the first address in the 40000 block, and is equivalent to HR1 when ModiconTypedAddr1Offset is 0, or HR0 when ModiconTypedAddr1Offset is 1) If you change the property ModiconTypedAddr1Offset, it will be changed for all Modbus-compatible drivers in the application. If you need some drivers to be zero-based and others to be one based, you can achieve this by creating a parent Context tag for each driver, adding a property named ModiconTypedAddr1Offset to that Context tag. The child driver tag will take the value in the parent Context tag instead of the global property value. (See: Context tag properties, Settings tab)

Modbus Compatible Device Properties

Properties folder tab | Property | Value
Options tab | Comm Channel | Serial RTU
Communications tab | PLC Address | 1
Communications tab | Time-Out Limit | 0.5 (Make it shorter if Scan Interval is going to be very short)
Communications tab | Port | COM2 (name of Serial Port tag)
Communications tab | Retry Delay | 0
Communications tab | Hold | deselected
Communications tab | Retries | 2
Communications tab | RTS Key Off Delay | 0

Related information:

Best Practices for Tags

Modbus Compatible Device I/O Addressing

Modbus Error Codes

Modbus Plus PLC Addressing

SCADAPack History Read

History Data for a TBox RTU

Koyo Address Translation

ModiconVTSMaxBlock

Closed Modbus Compatible Device: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Modbus Compatible Device: Options tab

The Options tab of the Modbus Compatible Device tag properties folder can be used to set byte swapping for long integer, IEEE single or IEEE double bytes. If this driver is communicating over a modem, then the Options tab is also used to indicate that squelch noise should be suppressed, if present.

Modicon driver tag - options tab

Comm Channel

Select the communication channel and protocol to use for this Modbus Compatible Device driver. This will be one of:

  • Serial RTU Select to use the RTU mode of the Modbus serial communications standard.
  • Serial ASCII Select to use the ASCII mode of the Modbus serial communications standard.
  • SA-85 (MB+) Select to use the Modbus Plus communications protocol via a Modicon SA-85 card.
  • Embedded TCP/IP Select to use the Embedded TCP/IP protocol.
  • Open Modbus TCP Select to use the Modicon Open Modbus/TCP specification to receive Modbus protocol over Ethernet TCP/IP.

Squelch Noise Present

Applies when communicating over a modem. Select this box to enable the squelching of background noise. By default, the Squelch Noise Present check box is not selected.

Reverse Long Integer Byte

Select whether byte swapping should occur for long integer values. By default, the Reverse Long Integer Byte check box is not selected.

Reverse IEEE Single Byte

Select whether byte swapping should occur for IEEE single byte values. By default, the Reverse IEEE Single Byte check box is not selected.

Reverse IEEE Double Byte

Select whether byte swapping should occur for IEEE double byte values. By default, the Reverse IEEE Double Byte check box is not selected.

Force Multi Element Write OpCodes

This setting enables writing to individual addresses on hardware that requires data to be written using multi-element OpCodes (15 and 16). It will only be writing to individual addresses and not multiple simultaneous addresses. This setting is only intended to force compatibility with certain hardware.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Maximum Coalesce Gap

Use only if the Modbus compatible device does not support reads from addresses that are not explicitly declared in the device. VTScada will attempt to coalesce reads from a range of addresses, which may lead to an error with these devices.

If left blank, there is no effect on driver coalescing.

Set to zero to allow for devices that cannot read from addresses that are not explicitly declared.

Set to a number greater than zero to fine-tune read coalescing. The gap is measured in units of two-byte words. Warning: when using low maximum coalesce gap values, it is important to avoid unnecessary gaps in VTScada tag addresses.

if this value is set, driver response time may be slowed due to the increased number of read blocks.

See also: VTSMaxBlock

Modbus Compatible Device: Communications tab

The Communications tab for the Modbus Compatible Device Driver tag properties folder consists of attributes used to identify and establish a connection to the hardware.

Port

Enables you to select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag. A Serial Port tag opens a serial port to enable communications between VTScada and your PLC or RTU. A TCP/IP tag enables you to connect to a series of hosts, allowing you to transmit data across a network or over the Internet.

The Port field can be cleared using the X button that appears to its right.

IP Network Listener Group

Configure only if this driver is to accept in-bound TCP or UDP communications. Select an existing IP Network Listener tag using the drop-down list.

If the IP Network Listener is configured, this driver must use Open Modbus TCP, configured on the Options tab.

IP Allow

Optional. Misconfiguration of this field is a common source of problems.

Used in connection with an IP Network Listener tag. General IP address filtering should be set on the IP Network Listener, as this will be more efficient. The list of allowed IP addresses in the driver is intended to prevent misconfigured devices from interfering with other devices.

Both filters (that in the Network Listener and this one) can be configured at the same time. The filter in the IP Network Listener will be applied when the device first connects and the local filter will be applied after a specific driver instance has been identified.

Station Address Mode

Use to limit the range of allowed addresses. Select according to your hardware. (The Lufkin and TeleBUS options are sometimes used by Oil & Gas applications and seldom elsewhere.)

Standard Address ... 1 - 247 according to Modbus Protocol. Extended addressing ranges cannot be entered directly.
An expression can be used for this parameter in order to bypass the limit if your device uses a modified Modbus protocol. Proceed with caution.

Lufkin ELAM Address ... 1 - 2295

TeleBUS Extended Address ... 1 - 65534

If the driver is running as a virtual server, the addressing is limited to the standard range, 1 - 247.

PLC Address

The station address of the Modicon programmable logic controller. By default, the PLC Address field is set to 1.

An expression may be used to provide the address if needed. This may be required on a network where the address varies depending on the workstation where the tag is running.

Note that, to create a valid expression for an address that contains non-numeric characters, you must enclose the address in quotation marks. e.g. "31.0.0.0" See: Modbus Plus PLC Addressing.

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Retry Delay

The Retry Delay field enables you to specify the amount of time (in seconds or fractions of a second) that the driver will wait between attempts to repeat a transmission of data if the previous attempt(s) have failed.

By default, the Retry Delay field is set to 0 (indicating that there should be no delay between retry attempts).

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

RTS Key Off Delay

The RTS Key Off Delay field represents the amount of time (in seconds) that this Modbus Compatible Device will wait before dropping RTS at the end of a data transmission.

Squelch Time

Sets the amount of time (in seconds or in fractions of a second) to wait before clearing noise. Enabled only when Squelch Noise Present has been selected on the Options tab.

Modbus Compatible Device properties Modbus Plus tab

The Modbus Plus tab of the Modbus Compatible Device tag properties folder is used when an SA-85 I/O card for Modbus Plus communications has been configured.

Modicon driver tag - Modbus Plus tab

SA-85 Adapter Number

The SA-85 Adapter Number section enables you to specify the number of the adapter if you have installed an SA-85 network adapter card for Modbus Plus communications networks. You can specify adapter 0, adapter 1, or none by selecting the associated radio button. The default setting for the SA-85 Adapter Number section is None.

SA-85 Polling Rate

Set the rate in seconds or fractions of a second at which you wish the SA-85 network adapter card to be polled. The default SA-85 Polling Rate setting is 0.025.

Retries

Select the number of attempts that will be made by this driver if there is no reply to a message. An error will be declared after this number has been reached.

Time Out (x500mS)

Specify the message response time limit that the driver will wait for a reply from the PLC. This time limit may be set from 1 to 20 increments. The default setting for the spin box is 2 (i.e. two 500 millisecond increments, or 1 second).

Maximum Paths Open

Set the maximum number of Modbus Plus sessions that can be opened simultaneously by the installed SA-85 network adapter. The Maximum Paths Open spin box may be set from 1 to 8. The default setting for the Maximum Paths Open spin box is 8.

Modbus Compatible Device: Virtual I/O tab

These properties are used to configure a virtual PLC in the memory of your PC. If using virtual addresses, and if your server is connected to the Internet, you may wish to enhance security by adding an IP Network Listener tag. See: IP Network Listener Tags

Modicon driver tag - Virtural I/O tab

Holding Coils 0xxxx (0-999)

Enter the number of 00000-series holding coils to be assigned to the virtual PLC.

Input Coils 1xxxx (0-9999)

Enter the number of 10000-series input coils to be assigned to the virtual PLC.

Input Registers 3xxxx (0-9999)

Enter the number of 30000-series input registers to be assigned to the virtual PLC.

Holding Registers 4xxxx (0-9999)

Enter the number of 40000-series holding registers to be assigned to the virtual PLC.

Closed Modbus Compatible Device Widgets

The following widgets are available to display information about your application’s Modbus Compatible Device Driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Modbus Compatible Device I/O Addressing

The allowable range of addresses is dependent upon the device with which you are communicating. For example, a PLC may only have 500 holding registers, and thus it can only address either 40001 through 40501, OR 400001 through 400501 (whichever you prefer), even though the protocol allows for addresses much higher than this.

The following table identifies the value ranges for Modicon outputs, inputs, input registers, and holding registers.

I/O Type | Type Specified | 5 digit address | 6 digit address
Holding Coil | HC1 - HC65536 | 00001 - 09999 | 000001 - 065535
Input Coil | IC1 - IC65536 | 10001 - 19999 | 100001 - 165535
Input Registers | IR1 - IR65536 | 30001 - 39999 | 300001 - 365535
Holding Registers | HR1 - HR65536 | 40001 - 49999 | 400001 - 465535
Data Logger | DL1:1 - DL16:8 |  |
Holding Registers Long(1) | HL1 - HL65536 |  |
Input Registers Long(1) | IL1 - IL65536 |  |

(1)The Modbus protocol does not include 32-bit addresses, but some devices use these anyway. VTScada supports 32-bit Modbus addresses by way of the text prefixes HL for Holding Long and IL for Input Long. The default data type for 32-bit addresses is SDWord.

when using numeric addressing, the leading digit is significant as it determines the I/O type. Any 4 digit numeric address will be used as a Holding Coil address.

Some applications may be configured using the text prefix addresses that are 0-based, i.e. the first holding coil was at HC0. To permit these applications to work correctly, an application property flag (ModiconTypedAddr1Offset) is used to set the base for text specified addresses.

"Type specified" means addresses such as the HC1 and IR2 format. This does not apply to addresses written as numbers only. (For example, 40001 is always the first address in the 40000 block, and is equivalent to HR1 when ModiconTypedAddr1Offset is 0, or HR0 when ModiconTypedAddr1Offset is 1) If you change the property ModiconTypedAddr1Offset, it will be changed for all Modbus-compatible drivers in the application. If you need some drivers to be zero-based and others to be one based, you can achieve this by creating a parent Context tag for each driver, adding a property named ModiconTypedAddr1Offset to that Context tag. The child driver tag will take the value in the parent Context tag instead of the global property value. (See: Context tag properties, Settings tab)

Bit Addressing

An individual bit in a register (either an Input Register or a Holding Register) may be read or written (for Holding Registers) by appending the address with "/x" where x has a value from 0 to 15 and indicates which bit is to be used. For writes, a read\modify\write cycle is used on the register as the Modicon protocol does not have a bit operation function.

If you are working with long integers, append the text "/sdword" after the bit number. For example: "40050/1/sdword".

Float Addressing

If required, you can use floating point addressing with VTScada. The process will require an adjustment to the way the address is provided to reach the correct register.

Modicon registers are 16 bits wide. In order to get a float address you will need to read 2 sequential registers to get 32 bits. To do this, you will need to know the lowest register address of the pair. Note that this may be odd or even and differs by device.

The address will be formed by entering the lowest address of the pair with the suffix of /FLOAT. e.g. IR9/FLOAT will read the register pair at IR9 and 10, and return the combined value as a float.

Note that driver options determine how the 4 bytes in the combined register pair are ordered to form the float as this will differ by device.

You can read strings from register-based addresses in PLCs such as Delta and Modbus by setting the "String stored in registers" flag of the IO tag, along with specifying the length in bytes. See: I/O Tab, String data type layout

Related information:

Data Suffixes for Tag I/O Addressing - A list of all available data type suffixes that can be used for tag I/O addresses.


SCADAPack History Read

The VTScada Modbus supports the reading of data from data loggers created by Control Microsystems RTU's that have been configured to store data using DLOG functions.

For example, you may have a Control Microsystems driver which is saving data once per minute using DLOG functions. To configure VTScada to read the data once per hour, you can use the SCADAPack History Read as described in the following notes.

Configuring the Control MicroSystems RTU

the following provides minimal information required to use Control Microsystems devices with VTScada. For more information on the RTU's, please refer to the TelePACE Ladder Logic manual

A necessary first step is to program the RTU driver to use the DLOG functions. The DLOG functions can log 8 fields from any of 16 loggers.

For each set of 8 fields, VTScada requires one to be configured as a "Date and Time" field. It does not matter which field is used for this purpose or even whether more than one is configured as "Data and Time". VTScada will simply use the first one found in numerical order.

For the other fields, VTScada supports any of the data types that Control MicroSystems uses.

Configuring VTScada

To retrieve data from history, you must use either the Analog Status tag or the Digital Status tag. These two tags can read both current data and historical data.

Using Analog Status tags

The format for the history address must be in the format "DLx:y" where x is the number of the logger and y is the field within that logger.

Thus, to read from field 3 of logger 1 the address would look like "DL1:3".

The history scan interval is measured in seconds and can be any integer value you wish. For example, to read every hour you would enter 3600.

Analog Status tag history fields

While it would be unusual, you are also able to enter an address for direct analog input, reading at a different interval frequency.

Tag Value:

If an address has been defined (standard address - not history address), the value coming from this address will always be used to set the tag value, regardless of whether a history address is also defined.

If only a history address has been defined, and if the value read from the data logger has a newer timestamp than the tag's current timestamp, then the value read from history will be used as the tag's value.

Varying History Scan Intervals

Should you attempt to set different history scan intervals for the different fields within one logger, VTScada will force all the tags associated with that logger to read at the same time. This time will be the smallest of the varying history scan intervals.

Scaling

A useful technique for maximizing the data being stored by the RTU is to not scale it at the logger level, leaving it as a two byte integer. Scaling will be done in VTScada after reading from the logger, using the tag's scaling properties.

The tag performs a destructive read. After the data has been read and saved, a log purge will be performed.

Using Digital Status tags

Digital Status tags are configured the same way as Analog Status tags except for the format used in the history address field. For Digital Status tags this takes the form: DLx:y/b where the /b indicates the bit number within the address. Thus, bit 0 of field 3 of logger 1 would be addressed as DL1:3/0.

By using individual bits, each field in the logger can store as many as 32 digital values, thus maximizing storage in the RTU.

You must select the Read History box in the I/O tab to see where to put the address.

Note that the appearance of the Digital Status tag's I/O tab will change when the Read History box is selected as shown:

Digital Status tag history fields


History Data for a TBox RTU

TBox RTUs, manufactured by CSE Semaphore, can store periodic time-stamped process data internally using internal tables. Because the standard Modbus does not have facilities for transferring time-stamped data, the TBox implements a set of custom Modbus functions to accomplish the transfer. To enable these tables to be read into VTScada tags, enhancements have been made to the standard VTScada Modbus driver specifically to access the TBox sample tables.

3 forms of history data tables are available: Sample Table, Digital Chronology and Analog Chronology.

  • Sample Tables are read with a History Address of "STx", where x is the table number to read, starting at 1.
  • Digital Chronologies are read with a History Address of "DCxxxx", where xxxx is the address of the digital.
  • Analog Chronologies are read with a History Address of "ACxxxx", where xxxx is the address of the analog.

The driver will read all the available history data in a compressed mode, and will then poll at the History Scan interval for new data, reading any that is available.

The total number of simultaneous sample table or chronology reads on a TBox RTU is ten. Because Ethernet-connected RTUs can be accessed by multiple masters, VTScada reads only one sample table or chronology at a time even if multiple tables are read at the same rate. Using this scheme, if multiple tables need to be read at the same time they are automatically read in sequence.

Sample Table Read Status widget

This widget can be drawn on any page to provide operators with a way to monitor the sample (i.e. history) tables in the RTU. The grid will be populated with address and the data start time for each table. For each table, a button is added to the Force column; click to force a complete re-read of the table.

Configuration options in the widget's properties dialog are limited to changing the button label and disabling the context menu and tooltips.


Koyo Address Translation

VTScada supports the Koyo address format by internally translating to standard Modbus addresses. You do not need to perform any translation between the two formats.

A Koyo address will consist of an address key (one or two letters) followed by an octal value. For example, a Koyo address might look like "SP612".

Koyo Address Keys
X
SP
Y
C
T
CT
S
V
GY
GX

Attempting to provided an invalid octal value in the Koyo format will result in an error condition. Further information about the relation between Koyo's format and standard Modbus addresses can be found in the Koyo documentation.

Standard data type suffixes are supported

Reads that cross boundaries such as Y/C will fail under the default driver settings. If you experience this problem, set the Modbus Compatible driver's Maximum Coalesce Gap to 3, thereby separating the reads.

Koyo Click: These use six digit addressing. If attempting to use an address in the 10000 range, you may need to add a leading zero.
For example, if trying to reach holding coil address 16001, VTScada will interpret this as input coil 16001. You must enter the address as 016001 in order to read the correct address.


Modbus Plus PLC Addressing

When communicating using Modbus Plus, request packets may have to be routed across various BP85 Bridge Plus devices to reach the intended PLC. The routing information is stored as part of the PLC address.

Modbus Plus addressing example

Because VTScada workstations that are located on different subnets will have to be routed through intervening BP85 Bridge Plus devices, it is therefore necessary that the PLC address of the Modbus Compatible Device tag to be resolved based on the workstation the tag is running on.

The expression to use for the PLC address of PLC (x) in the above example might be as follows:

ToUpper(RPCManager\WkStnName) == "SERVER_B" ? "20.10" : "10"

This code says that, if the address is being resolved from server B, then use "20.10" otherwise use "10". The following illustration shows how this would look in your tag configuration panel.

Modbus Plus addressing expression


Modbus Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
1 | 0x001 | Illegal Buffer Length
3 | 0x003 | Invalid Command
5 | 0x005 | Timeout
6 | 0x006 | Receive Buffer Too Small
8 | 0x008 | Invalid Local Session Number in NCB LSN
9 | 0x009 | Out of Resources
10 | 0x00A | Session Closed
11 | 0x00B | Command Cancelled
13 | 0x00D | Duplicate Local Name
14 | 0x00E | Local Name Table is Full
15 | 0x00F | Close Command was Issued But Sessions Still Active
17 | 0x011 | Local Session Table is Full
18 | 0x012 | Routing Failure, Remote Node Not Responding
19 | 0x013 | Invalid Name - Bad Value in NCB NUM
20 | 0x014 | Name Not Found
21 | 0x015 | Invalid Name - No Entry in Local Name Table
22 | 0x016 | Name Already Exists on Network
23 | 0x017 | Name was Deleted
24 | 0x018 | Session Abnormally Terminated
25 | 0x019 | Name Conflict - Two Nodes Using the Same Name Detected
33 | 0x021 | Adapter Busy - Command Cannot Execute
34 | 0x022 | Too Many Commands Queued
35 | 0x023 | Invalid Values for NCB LANA NUM - Must be 0 or 1
36 | 0x024 | Command Completed Before Cancel Issued
38 | 0x026 | Invalid Cancel Command - Target NCB Cannot be Found
78 | 0x04E | Hardware Error Code
255 | 0x0FF | Still Processing Command
256 | 0x100 | Writing Invalid Data
257 | 0x101 | Illegal Function for the Addressed Slave
258 | 0x102 | Illegal Data Address in the Information Fields for the Addressed Slave
259 | 0x103 | Illegal Data Value in the Information Fields for the Addressed Slave
260 | 0x104 | Failure in Associated Device
261 | 0x105 | Acknowledge - Processing Programming Command
262 | 0x106 | Busy - Reissue Command Later
263 | 0x107 | Negative Acknowledge - cannot perform program function
264 | 0x108 | Memory Parity Error
266 | 0x10A | Gateway Path Unavailable
267 | 0x10B | Gateway Target Device Failed to Respond
512 | 0x200 | Illegal Memory Address in Read
513 | 0x201 | Illegal Memory Address in Write
514 | 0x202 | Error Loading NETLIB.DLL
515 | 0x203 | Error Opening Serial Port
516 | 0x204 | Timed Out Waiting for Echoed Message
517 | 0x205 | Timed Out Waiting for Response from Remote
518 | 0x206 | Received Message CRC Error
519 | 0x207 | Unknown Error
520 | 0x208 | Attempting to Write Invalid Data to PLC
521 | 0x209 | Attempting to Send Invalid Read Msg to PLC
528 | 0x210 | No Path Available for Message
529 | 0x211 | Command Mismatch
530 | 0x212 | Response from Wrong Station
531 | 0x213 | Communication Channel Not Available
532 | 0x214 | Send/Receive Out of Sync
533 | 0x215 | Response from wrong data logger
534 | 0x216 | Corrupt or illegal MODBUS/TCP header
535 | 0x217 | Illegal value in response
536 | 0x218 | Purge of data log records failed
537 | 0x219 | Session Open Illegal Command
538 | 0x21A | Session Open Illegal Version
546 | 0x222 | Unknown Modbus Exception Code Returned
551 | 0x227 | Bad Transport Mode
768 | 0x300 | No Error
769 | 0x301 | Port Not Defined
770 | 0x302 | Port Failed To Connect
771 | 0x303 | Port Lost Connection
772 | 0x304 | Serial Port Settings Out of Range
773 | 0x305 | Serial Port Already In Use or Not Available
774 | 0x306 | Serial Port Access Denied
775 | 0x307 | Serial Port General Failure
776 | 0x308 | Serial Port Invalid Parameter
777 | 0x309 | Port Not Connected
784 | 0x310 | Port Unknown Error


Motorola ACE Driver

Not counted towards your tag license limit.

The Motorola ACE driver should be used for all Motorola ACE / Moscad RTUs in your system.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Reference Notes:

Requires a Motorola IP Gateway tag, and the Motorola table configuration file, MDLC_TYP.CFG, which lists the possible RTU table configurations.

This driver relies on the parent IP Gateway device to report whether a site is up or not. That device must be properly configured via the Motorola STS software. Please refer to the STS Advanced Features PDF, which should be installed with STS.

The configuration file describes only the configuration for communication. It does not configure the RTU. This file should be modified to match the configuration of the RTU.

When viewed in the Tag Browser, the RTU ID value configured in this driver will be shown as the address.

Related information:

Motorola ACE Driver I/O Addressing

Motorola IP Gateway

Best Practices for Tags

Closed Motorola IP Gateway: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Motorola ACE Driver properties Settings tab

The settings tab is used to define the communication parameters to your Motorola ACE RTU. The IP Gateway device will handle retries and timeouts. No field exists in this driver to allow a retry specification. Time limit values are provided only as a fall-back in the case that the IP Gateway does not handle the time limit.

Motorola IP Gateway

The name of a configured Motorola IP Gateway. The first such parent found will be used automatically.

RTU ID

The identifier of the MDLC network that the RTU device was configured with.

RTU Type

Should match the RTU type, as specified in the API configuration file. This name will be found immediately after the keyword, "Type" and just before the table definitions.

RTU Status Interval

The period between RTU status polls.

Burst Refresh Interval

The burst refresh poll interval. Used to cause a read poll to occur at a regular interval while the driver is using burst mode and polling would otherwise be disabled.

Read Time Limit

The IP Gateway device configuration provides the time-outs to be used. The value in this field is only to provide a fail-safe in the event that the usual time-out limit fails to work for read operations.

Write Time Limit

The IP Gateway device configuration provides the time-outs to be used. The value in this field is only to provide a fail-safe in the event that the usual time-out limit fails to work for write operations

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Closed Motorola ACE Tag Widgets

The following widgets are available to display information about your application’s Motorola ACE driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget


Motorola ACE Driver Addressing

Viewing: Reference > Tag Reference > Communication Driver Tags > Motorola ACE Driver > Motorola ACE Driver Addressing

Reference:

Data Suffixes for Tag I/O Addressing

Communication Driver Log-Enabled Variables

Motorola ACE Driver I/O Addressing

Motorola ACE features will be available only if your VTScada license includes this option.

Addressing uses the following form, where T, R and C are zero-based integers, and B is the letter B.

[B]T:R:C

Where...

  • The letter B is optional, as indicated by the square brackets. (Do not type the brackets in an address.) If present, this indicates that the driver should wait for unsolicited data to be pushed out from the RTU, rather than the driver polling the RTU.
  • T is the table number to use in the MDLC_TYP.CFG file.
  • R is the row number to use in the MDLC_TYP.CFG file.
  • C is the column number to use in the MDLC_TYP.CFG file.

The trace message for the Motorola RTU driver is <Type>, <Address>, <Data>. This is not part of a standard communication protocol.

<Type>

Burst, Polled, or blank (for writes) depending on how the data is received.

<Address>

[B]T:R:C as described in the preceding notes.

<Data>

May be either a string representation of a value, a one-dimensional array or a two-dimensional array.

Examples:

0:1:2

Designates Table 0, Row 1, Column 2 in polling mode, because the B is not present.

B3:2:1

Designates Table 3, Row 2, Column1 in Burst mode.

Burst mode may only be used if the RTU was programmed to communicate this way. Simply adding the B to the address will not cause the RTU to push updates.

Burst mode applies only to data reads. After an initial poll the driver will wait for the RTU to report a change. The burst option is ignored for data writes. A burst refresh interval is provided to periodically perform an explicit poll of the RTU.


Motorola - Sample MDLC_Type.CFG file

Motorola ACE features will be available only if your VTScada license includes this option.

The following is an example of a Motorola MDLC_Type.CFG file. It cannot be used without modifications unique to the configuration of your RTU.

When modifying the configuration file, you need only setup the tables that are in use for your RTU. The number following the name of the configuration is the number of tables defined below it. Data types available for use are as follows (note that these are named differently than in the device programming software): Bit, Val, Long and Float.

; File Type & Version
;--------------------------
FILE_TYPE         RTU_TYPE
VERSION             1.0

; The number of RTU types defined within this file:

Number_of_Types 2

; Definition of RTU Types
;--------------------------
;   Type name   Number of tables

Type  ExampleConfig2	9

; Table_no N_cols Col_0 Col_1 Col_2 Col_3 Col_4 Col_5 Col_6 Col_7

Table  0   1  Val
Table  1   3  Bit    Long  Long
Table  2   1  Float
Table  3   3  Bit    Long  Long
Table  4   1  Val
Table  5   2  Bit    val
Table  6   1  Val
Table  7   6  Bit    Bit   Val    Float  Bit   Bit
Table  8   6  Float  Float Float  Val      Val   Bit

Type  ExampleConfig2         2

; Table_no N_cols Col_0 Col_1 Col_2 Col_3 Col_4 Col_5 Col_6 Col_7

Table  1   3  Bit    Long  Long
Table  3   1  Val


Motorola ACE Error Codes

See also: Motorola IP Gateway Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
768 | 0x300 | Not connected to IP Gateway
769 | 0x301 | RTU Link Not Ready
770 | 0x302 | RTU Communications Link Lost
771 | 0x303 | Attempted to Write Multiple Values
772 | 0x304 | Bad Address
773 | 0x305 | Bad Write Address


MQTT Client Driver

MQTT stands for Message Queuing Telemetry Transport

The MQTT Client Driver can transfer information to and from an MQTT broker, either on your local intranet or on the Internet. You may then log, view, alarm and report on values from devices connected to that host, in your VTScada system.

Never share a TCP/IP Port tag with multiple MQTT Client Drivers. Each driver must use its own port tag.

Do not use a Polling Driver with an MQTT driver. It is not possible to issue a poll for data because the MQTT driver works strictly on the basis of report by exception.

Redundant broker setup using DriverMUX

If a device is configured to use two redundant brokers, VTScada can accommodate this with the Driver Multiplexer tag and two MQTT drivers. The Driver Multiplexer should be configured with the following setup:

  • Selection Mode -> Automatic
  • Sequence Mode -> Parallel
  • Failover Mode -> Switch Server First
  • Write Mode -> Both Devices
  • Ignore Data From Inactive Subordinate -> deselected

If configuring for redundant broker setup AND using Sparkplug B with the Automatic Tag Creation option enabled:

If the MQTT driver sees that it is a subordinate of a Driver Multiplexer, the automatic tag creation feature will place tags under the Driver Multiplexer instead of placing them under the MQTT driver. This ensures that the redundant broker, configured using a second MQTT tag and port, will use the same I/O tags.

If the MQTT driver was created and its child tags generated before being attached to a Driver Multiplexer, then when the MQTT driver is made a subordinate under a Driver Multiplexer a fresh set of the tags would be created under the Driver Multiplexer. The original tags are not moved and there is no link between history collected by the old tags and history collected by the new.

To avoid this situation, ensure that automatic tag creation is not selected / enabled in the MQTT driver until it has been linked as a subordinate driver to your Driver Multiplexer tag.

To repair this situation if it was not avoided, do the following:

  1. Deselect the automatic tag creation option in the MQTT driver.
  2. Delete the I/O tags that were generated below the Driver Multiplexer tag.
  3. Select all the I/O tags that are children of the MQTT driver.
  4. Cut.
  5. Paste those tags as children of the Driver Multiplexer tag.
  6. Re-enable the automatic tag creation option in the MQTT driver.

If nested Driver Multiplexers are used such that more than two redundant brokers are supported, automatic tag creation will place the tags under the topmost Driver Multiplexer.

History Addresses and Sparkplug B

If all of the following are true:

You are using the MQTT driver to read from a Sparkplug B device.

You are configuring I/O addresses yourself rather than letting the driver read them automatically.

The device sends messages that contain arrays of historical data.

Then...

Configure the History Address parameter of your I/O and Calculations tags to append the characters, $$History$$

If an array of data is sent to the Read address of an input tag (including legacy Status tags as well as the I/O and Calculations tag) then only the first value is read and the rest discarded. You must use the History address in order for the tag to process the full array.

Note also that the Read address and the History address must not be identical.

Example:

Read Address : spBv1.0/PT/DDATA/PTGateway/ET_EFB107_H_002++ACC00

History Address: spBv1.0/PT/DDATA/PTGateway/ET_EFB107_H_002++ACC00$$History$$

Determine whether a remote Sparkplug B device is online

If the broker tag's value (MQTT Driver instance) is 0 and any known good IO tag's value is equivalent to Invalid with Hold not enabled on the driver, then the field device for that IO tag is considered to be disconnected. The IO tag value would only be invalid if either a) no valid value for that tag was received after VTScada was started, OR b) following the receipt of a DEATH certificate, after which all IO tags associated with that device would be invalidated.

If the broker tag value is !=0, then the connection to the broker is disconnected.

Related information:

MQTT Client Addressing

MQTT Client Error Codes

MQTT Communication Messages Dialog

MQTT Client Driver Statistics Dialog

Write a Custom MQTT Decoder

Best Practices for Tags

Closed MQTT Client Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

MQTT Client Driver properties Connection tab

Set the communication properties of the driver with the following fields:

Port

Select the TCP/IP Port tag that holds the address information for the MQTT data source.
MQTT data is available only over TCP/IP connections.

When configuring your TCP/IP tag, note that port 1883 is reserved with IANA for use with MQTT. Port 8883 is registered with IANA for use with MQTT over a secured connection. Your data source may use a different port.

This port must not be shared with any other clients.

MQTT Client ID

Every MQTT client must have a unique identifier. This is generated for you using the following four components to guarantee uniqueness on the broker as well as across VTScada applications and within the same application across multiple machines

  • Either of a configuration property called "MQTTClientIDPrefix" if set (useful for branding) or the string "VTScada"
  • The application's GUID (guaranteed unique identifier)
  • The workstation's unique identifier
  • This tag's name

The Client ID may be edited, but do so with caution and only when a broker requires a specific ClientID to allow a connection to be established. Typically, this value must be machine-specific, but that will not be the case after editing.
If a custom value has been set, the edit button is grayed out. To return to the default of a VTScada-specified Client ID, unique to the current machine, delete the parameter and apply the change.

Sparkplug B SCADA Host ID

This field is generated automatically and is common to all instances of the MQTT Client Driver in an application. The SCADA Host ID should be entered into the EoN Closed Sparkplug Edge Node configuration of the remote device, if supported by that device.

This parameter is editable, but do not change unless necessary. If it is edited in a redundant broker configuration, then all drivers that are part of the redundancy must use the same value for the parameter.

Namespace Parameter

Allows the Sparkplug B subscription to be limited to a specific namespace instead of the root spBv1.0/#. This may be required by some brokers, or it can be used to limit what data is requested by the driver. The subscription becomes spBv1.0/namespace/#.

Keep Alive

Specifies the number of seconds, after which the connection will close if no new data is received.

Ensure that the Disconnect Delay in your TCP/IP Port tag is greater than the Keep Alive time set here.

QoS

QoS stands for Quality of Service and specifies an agreement between the sender and receiver of a message. Zero is the lowest quality and should be used for reliable connections and where you do not mind if the occasional message is lost. Use QoS 1 when you need to be sure that every message is sent and you have a system in place to handle duplicate messages. QoS 2 is the most reliable but (due to its nature) the slowest option, ensuring that every message is delivered exactly once.

Protocol

Select from JSON, XML, Sparkplug B, Pass Through, or Custom.

It is possible to configure the driver with one protocol, but then have an IO tag use a different protocol by specifying another Decoder in its address. Be aware that you cannot do Sparkplug communications unless the driver protocol is set to Sparkplug. You can use other protocols when in Sparkplug mode by specifying a Decoder in the address.

Timeout

Sets the length of time allowed for message processing before the attempt will timeout.

Must be between 0 and 90% of the Keep Alive time. While zero is allowed by the dialog, it is not advised.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

Hold

Select whether this driver should hold the last message received from the broker in the event of a communications failure.

Automatic Tag Creation Sparkplug B protocol only.

When selected, a hierarchy of Context and I/O tags will be created automatically under the driver tag whenever a BIRTH certificate is received.

After the tags are created, they can be modified as needed but should not be moved unless Automatic Tag Creation is disabled. Otherwise, new copies of the tags will be created in their place.

If using a Driver Multiplexer, refer to notes at the beginning of this topic for redundant broker setup. Ensure that automatic tag creation is OFF until you have finished driver configuration of both the MQTT driver and the Driver Multiplexer.

MQTT Client Driver properties Credentials tab

Use this tab to provide the user name and password if those are required to sign into the MQTT broker. (Not all brokers will require these.)

Username

The name required to sign in to the MQTT broker

Password

The password matching that user name. Passwords are never shown and are not stored in plain text. That said, security depends on ensuring that your link to the MQTT broker uses only a secure connection (TLS).

Hash Password with MD5

Select this option if the MQTT broker saves passwords using that algorithm. The password will be hashed before being sent to the broker.

MQTT Client Driver properties Last Will tab

This provides a mechanism for the broker to notify interested clients that the VTScada client has disconnected. For example, if you set the Last Will Message to "VTScada MQTT Client 1 has disconnected" and the Last Will Topic to be "VTScada/Client/1", then if your application disconnects from the broker for any reason, the broker will send all clients that have subscribed to the topic "VTScada/Client/1" a message saying " VTScada MQTT Client 1 has disconnected "

Last Will Topic

The topic should be specific to the device, although this is not mandatory. One way to do this is to include the device name as part of the topic.

Last Will Message

The information to be sent to the topic in the event of a disconnection. "Offline" is typical.

Last Will QoS

Specify the quality of service with which the Last Will should be sent. (See notes in the description of the Connection tab.)

Last Will Retain

Use a retained message to update the status of a device on a topic. New clients will see the last retained message.

Closed MQTT Client Driver Tag Widgets

The following widgets are available to display information about your MQTT Client driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget


Using the MQTT Driver With Sparkplug B

VTScada will generate a Sparkplug B SCADA Host ID automatically. This ID value is common to all instances of the MQTT Client Driver in an application. The SCADA Host ID should be entered into the EoN configuration of the remote device, if supported by that device.

There are various ways that VTScada can receive information from a remote device using the Sparkplug B protocol:

  1. Hardware sending a BIRTH message after receiving the "ONLINE" State message from VTScada as described in the protocol.
  2. Hardware sending a BIRTH upon connecting to a broker in which VTScada is already communicating, as per the protocol.
  3. VTScada sending Node Control / Rebirth commands upon receipt of a DATA message for which it has no BIRTH information.
  4. If a device is online but has no current data to send, then to get a BIRTH message set up a digital IO tag with a Write Address as follows:
spBv1.0/GroupID/NCMD/EoNID++Node Control/Rebirth

Where GroupID and EoNID are unique strings for each piece of hardware publishing to the MQTT Broker. Sending a value of 1 (one) will tell the device to send VTScada a BIRTH message if it supports the Node Control / Rebirth feature, as published in the protocol documentation, but marked as optional.

Support for the Node Control / Rebirth command is listed in the protocol specification as optional, so there may be pieces of hardware for which options 3 and 4 will not work.

DataSet as a data type is not currently supported in the Sparkplug B implementation. As an alternative, publish the metric multiple times in the same message in order to fill the history in a way that can be used in VTScada.

When in Sparkplug B mode, you can Import Tags from PLCs rather than create and configure them one at a time. Refer to MQTT Client Addressing.

History Addresses and Sparkplug B

If all of the following are true:

You are using the MQTT driver to read from a Sparkplug B device.

You are configuring I/O addresses yourself rather than letting the driver read them automatically.

The device sends messages that contain arrays of historical data.

Then...

Configure the History Address parameter of your I/O and Calculations tags to append the characters, $$History$$

If an array of data is sent to the Read address of an input tag (including legacy Status tags as well as the I/O and Calculations tag) then only the first value is read and the rest discarded. You must use the History address in order for the tag to process the full array.

Note also that the Read address and the History address must not be identical.

Example:

Read Address : spBv1.0/PT/DDATA/PTGateway/ET_EFB107_H_002++ACC00

History Address: spBv1.0/PT/DDATA/PTGateway/ET_EFB107_H_002++ACC00$$History$$


MQTT Client Addressing

An address assist dialog is provided but it may not be possible to query your broker for the published topics. You may need to obtain the topic names and structure from your MQTT broker.

MQTT Address Assist dialog - manual mode

  • For protocols other than Sparkplug, enter the Topic (required) and the Metric (optional unless in Sparkplug protocol).
  • If your driver is configured for Custom protocol, enter the name of the custom encoder/decoder module (required).
  • The MQTT addressing scheme allows the use of simple array indexing with the built-in JSON in order to read JSON array payloads.
    It will also allow custom decoders to return either structures or arrays of structures.
  • If the pass-through decoder is used, do not use any indexing trail
  • An XML reading address with top-level array indexing will cause an addressing error, because decoded XML always starts with the root and cannot start with an array. With XML an indexing trail can never start with a top level array indexing, therefore an indexing trail in the form, [0].A.B will fail because it starts with a top level array indexing.

Indexing Trails

(aka "metric". Specifies the address of nested or array data)

You will get a "Tag Address" error in the following situations:

  • You use the built-in pass-through decoder with any indexing trail.
  • You use the built-in XML decoder with an indexing trail that starts with array indexing such as [2][0].temperature

It is possible to have an indexing trail that begins with array indexing if the data returned from the decoder is an array of structures instead of just a structure. As examples:

  • A custom decoder could return a VTScada structure or an array of VTScada structures.
  • The built-in JSON decoder can also return a structure or an array of structures.
  • The built-in XML decoder can return only a structure.
  • The built-in pass-through decoder cannot return either. It returns the MQTT payload as a stream.

MQTT Address Assist dialog - Sparkplug B mode

When in Sparkplug B mode, you can Import Tags from PLCs rather than create and configure them one at a time.

  • When the driver is in Sparkplug B mode, Topic, Metric and Custom Decoder will not be shown. Instead, the dialog will display a tree of addresses. This information is obtained from the BIRTH certificate.
    If needed, the address assist can be made to switch back to the generic address entry mode using the "Manual" button, at the bottom left of the dialog when in Sparkplug B mode. (And, back to tree mode using the "Tree" button.)

Reading Data

The general form of an address is

TopicName+Decoder+Metric

Note that it is optional to specify an encoder or decoder, therefore the most common form of an address is

TopicName++Metric

Where

  • Plus signs (+) are separators between the three components as shown.
    VTScada does not support the use of wildcards.
  • TopicName is required and is a unique name describing the information. Examples include:
building/floor-1/sensors/temperature

The temperature sensor on the first floor.

building/+/sensors/temperature

Temperature sensors on all floors.

building/floor-1/sensors/#

All sensors on the first floor.

  • Decoder (/ Encoder) Tells VTScada how the information is stored so that it can be interpreted correctly. In practice, most data will be encoded as either JSON or XML. In most cases you need only specify the decoder if you are deviating from the protocol you specified in the driver.
    The following decoders are provided. It is also possible for experienced VTScada programmers to write their own. (Write a Custom MQTT Decoder)
    An Encoder / Decoder is always required for Custom and must not be specified for PassThrough. Other requirements may exist for various encoders.

JSONDec

The default decoder. If left blank, this will be used.

XMLDec

An XML decoder.

MQTTPassThruParser

Data stored in the topic is passed through without parsing.

SPBDec

Sparkplug B decoder

SPBEnc

Sparkplug B encoder

If the driver is configured to use the Sparkplug B protocol, there is no need to specify these strings in the address.

  • Metric (formerly "Indexing Trail") Specifies the address of nested or array data.

For example, given data stored in the topic, Building/Floor1/sensors using JSON as follows, where the desired information (highlighted in green) is the first element of the array in "K1_1_3":

{"V1":51.5,
 "K1":{"K1_1":{"K1_1_1":53,
               "K1_1_2":"v1_2_794",
               "K1_1_3":[13.713,26.138,39.804]
              }
      },
 "K2":11.11,
 "Timestamp":1555622869.8499205
}

The address is:

Building/floor1/sensors++K1.K1_1.K1_1_3[0].

Note that in this example, the decoder is not specified (++), meaning that the default JSONDec decoder is to be used.

For Sparkplug B, the "DataSet" data type is not supported.

The keys used within a Metric's properties array to extract extra tag information are as follows:

Units - SparkplugBEngUnitsProperty

RangeMin - SparkplugBRangeMinProperty

RangeMax - SparkplugBRangeMaxProperty

No action is required if your SparkplugB device publishes units, and ranges under the following names : engUnit, engHigh, engLow. If your device publishes units under a different name (for example, "MotorUnits") then you must change the matching SparkplugB property as shown in the following example:

SparkplugBRangeMinProperty = MotorUnits

The following is an example of a Python script implementing an MQTT device that references those variables:

#
metric.properties.keys.extend(["engUnit"])
propertyValue = metric.properties.values.add()
propertyValue.type = ParameterDataType.String
propertyValue.string_value = "Deg Celcius"
#
metric.properties.keys.extend(["engHigh"])
propertyValue = metric.properties.values.add()
propertyValue.type = ParameterDataType.Float
propertyValue.float_value = 50.0
#
metric.properties.keys.extend(["engLow"])
propertyValue = metric.properties.values.add()
propertyValue.type = ParameterDataType.Float
propertyValue.float_value = 10.0

In each block you can see the reference to engunit, enghigh and englow. Those MQTT properties get translated to the SparkPlugB properties in VTScada. If your MQTT device uses different variable names, you can change them in the VTScada properties.

VTScada then takes those three variables and when the MQTT tags are automatically built, it uses them to populate the engineering units and the Display Range Min and Max of the IO tag.

Writing data

Write addresses follow a similar scheme as the Read addresses with the following changes:

  • The only encoders supported by default are the JSONEncoder (JSONEnc) and the MQTTPassThruParser. The default is the JSON encoder.
  • Custom encoders are supported and if used are passed in the tag value as parameter 1. The TrailingIndex, if used, is specified as parameter 2. The encoder must be a subroutine that returns the full payload for the message (very similar to the custom decoders).
  • Write addresses contain 2 additional optional components in their delimiters - the QoS of the message, and if the message should be retained. e.g. MyTopic+MyEncoder+TrailingIndex+QoS+Retain. The QoS will default to that of the driver if not specified, and the retain will default to FALSE if not specified.

Read example, using the HiveMQ® public broker:


MQTT Client Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0 | No Error
1 | 0x1 | Connection Refused: Unacceptable protocol version
10 | 0xa | Timeout waiting for SUBACK
11 | 0xb | Timeout waiting for UNSUBACK
12 | 0xc | Timeout waiting for PINGRESP
13 | 0xd | Malformed Remaining Length
14 | 0xe | Problem with the underlying communication port
15 | 0xf | Address could not be parsed
16 | 0x10 | Malformed received MQTT packet
17 | 0x11 | Subscription failure
18 | 0x12 | Payload decoding failure
19 | 0x13 | Failed to compile a Decoder
2 | 0x2 | Connection Refused: Identifier rejected
20 | 0x14 | The received MQTT packet type is not supported on this client
21 | 0x15 | Timeout waiting for PUBACK
22 | 0x16 | Timeout waiting for PUBREC
23 | 0x17 | Timeout waiting for PUBCOMP
3 | 0x3 | Connection Refused: Server Unavailable
4 | 0x4 | Connection Refused: Bad username or password
5 | 0x5 | Connection Refused: Authorization error
6 | 0x6 | Connection lost or bad
7 | 0x7 | Timeout waiting for Length bytes
8 | 0x8 | Timeout waiting for Payload
9 | 0x9 | Timeout waiting for CONNACK


NMEA 0183 Driver

Not counted towards your tag license limit.

The National Marine Electronics Association (NMEA) is a non-profit association of manufacturers, distributors, dealers, educational institutions, and others interested in peripheral marine electronics occupations. The NMEA 0183 standard defines an electrical interface and data protocol for communications between marine instrumentation.

The protocol consists of ASCII sentences and data fields within the sentences.

Related Application Properties

NMEADriverSharedRPC - Set to TRUE (1) to share one RPC service. Defaults to FALSE (0). drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

Closed NMEA 0183 Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

NMEA 0183 Driver properties Configuration tab

The Configuration tab includes the following properties:

Serial or TCP/IP Port

Select the Serial or TCP/IP tag that will provide the address and port to be used when communicating with the PLC.

Time-Out Limit

The time that the driver will wait for a response before setting an error or retrying.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Use LRC on Writes

Select this option if a longitudinal redundancy check (LRC) will be performed on driver writes.

Closed NMEA Driver Widgets

The following widgets are available to display information about your application’s NMEA Driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


NMEA 0183 Driver Addressing

VTScada I/O tag addressing for the NMEA 0183 driver uses the following format:

SSSSS:n

Where "SSSSS" is the sentence ID and "n" is the field number, starting at 0.

This format returns a single value (field) from the sentence.

You may also use the format:

SSSSS

Where "SSSSS" is the sentence ID.

This format returns the complete list of fields from the sentence in CSV format.


OCPP Driver

OCPP stands for Open Charge Point Protocol. It is often used by Electric Vehicle (EV) charging infrastructure using version 1.6J

The driver's server list MUST contain the machine with which the charger will initiate the connection. As a general rule, be sure that the charger can initiate a connection with any workstation in the server list for the driver.

Related information:

OCPP Users Tag

Best Practices for Tags

Closed OCPP Driver tag properties - ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

OCPP Driver tag properties - Options tab

Configure a password, a heartbeat period, link a user list or enable the following: Auto rewrite, store last output values, hold, write debug logs to disc or view raw IdTag.

Password

The password supplied by the charger on connection. Dots will be shown in place of the actual characters.

Use of a password is strongly recommended. If not specified, any device will be able to connect via the URL.

OCPP Users

Provide an OCPP Users tag which has been configured with a list of authorized users.

If not specified, anyone will be able to use the charger.

Heartbeat Rate

The time between heartbeat messages from the end device. Defaults to 10 seconds.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Write Debug Logs to Disk

Select only when attempting to diagnose a problem.

The log file will be written to the Data folder of your application.

View Raw IdTag

Log a charging transaction's IdTag if no OCPP Users tag is linked to the driver. The IdTag can be logged by linking a string IO tag with a Read Address of 'N:Name' where 'N' is the connector number (1,2,3... etc). If an OCPP Users tag is linked to the driver, the state of the checkbox bears no consequence; The option would be functionally disabled.

View Raw IDTag is disabled by default as it is considered to be a less secure configuration. Enabling View Raw IdTag will prevent encryption and should be enabled with caution.

OCPP Driver tag properties - Communications tab

Path Portion of URL

Appended to the Full Connection URL. Refer to notes for that property.

Charge Point ID

The ID that the charger will use to identify itself along with the password on connection.

Full Connection URL

This field is for display only. The intent is to provide a starting point for the URL that you will configure in your charging device in order to connect.

Copy this and edit as required for your situation. The format is typically:

MACHINENAME/RealmName/AppGUID/Websocket/Path portion here/ChargerID

  • MachineName initializes to the name of the workstation where this tag is being configured. Use the name or canonical address of the primary server to which the charger will connect.
  • RealmName is the name of the VTScada Internet Server realm that you configured for the EV to connect to.
  • "WebSocket" is a keyword and should not be changed.
  • Path portion is any additional information that may be required so that the HTTP Server can route the request to the driver.
  • ChargerID is used to identify the charger as one that is authorized to connect.

Timeout Limit (s)

Specifies the length of time to wait before giving up on a connection attempt. Defaults to 5 seconds.

Closed OCPP Driver Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


OCPP Driver Addressing

The default protocol metrics are supported in the address assist. Manufacturer-specific items can also be added by entering them manually in the configuration dialog.

Meter values are read by specifying the connector number (where 0 specifies the unit as a whole, with individual connectors starting at 1), and then the measurand Closed A quantity, object, or property intended to be measured. For example, 1:Voltage.

The following is a list of measurands that the protocol supports. Note that not all may be supported by any specific device. "Name" and "TransactionId" will be cleared when a transaction is ended.

The keyword, "Import" specifies a value going to the electric vehicle. The keyword, "Export" specifies a value coming from the electric vehicle.

ChargeBoxSerialNumber

ChargePointModel

ChargePointSerialNumber

ChargePointVendor

Current.Export

Current.Import

Current.Offered

Energy.Active.Export.Register

Energy.Active.Import.Register

Energy.Reactive.Export.Register

Energy.Reactive.Import.Register

Energy.Active.Export.Interval

Energy.Active.Import.Interval

Energy.Reactive.Export.Interval

Energy.Reactive.Import.Interval

FirmwareVersion

Frequency

Iccid

Imsi

MeterSerialNumber

MeterType

Name

Power.Active.Export

Power.Active.Import

Power.Factor

Power.Offered

Power.Reactive.Export

Power.Reactive.Import

RPM

SoC

Temperature

TransactionId

VendorId

VendorErrorCode

Voltage

Additional information that can be read about connectors:

Status

ErrorCode

Info

Unit level information (connector 0):

Model

Vendor

VendorId

VendorErrorCode

Status

ErrorCode

Info

Configuration information can be read (and written if supported by the device) via an addressing scheme of Configuration:Metric

Supported Write Functions:

Configuration

The address should specify the metric to which you wish to write configuration information.

ChangeAvailability

1 –> Available

0 –> Unavailable.

The address to use is ChangeAvailability:Conn# where the value sent corresponds to the desired state of the connector.

RemoteStartTransaction

The address is RemoteStartTransaction:Conn# and the value is the Friendly Name of the user stored in the linked OCPP Users tag.

RemoteStopTransaction

The address is RemoteStopTransaction:Conn# This write triggers when the tag value is set to 1.

TriggerMessage

The address is TriggerMessage:MessageName:ExtraInfo where MessageName is the type of OCPP message to be sent from the charger and the ExtraInfo is an optional connector number if applicable to the message being sent.

Related information:

OCPP Driver


OCPP Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0000 | No Error
1 | 0x0001 | Not Implemented
2 | 0x0002 | Not Supported
3 | 0x0003 | Internal Error
4 | 0x0004 | Protocol Error
5 | 0x0005 | Security Error
6 | 0x0006 | Improper Action Syntax
7 | 0x0007 | Improper Action Value
8 | 0x0008 | Too Many Occurences In An Action
9 | 0x0009 | Action Field Type Mismatch
10 | 0x000A | Generic Error
11 | 0x000B | Malformed Packet Received
12 | 0x000C | Simultaneous CALLs received
13 | 0x000D | Request Timed Out
14 | 0x000E | Request Rejected
15 | 0x000F | Request Requires Reboot To Take Effect
16 | 0x0010 | Not Connected
4097 | 0x1001 | Address Not Valid
4098 | 0x1002 | Address Not Writeable
4099 | 0x1003 | Address Not Readable


OCPP Users Tag

This tag is required by an OCPP Driver. If present, only those users specified in this tag may use the driver. If not specified, any user can use the OCPP driver.

Attempting to create a duplicate ID value will result in an error message.

Related information:

OCPP Driver

Best Practices for Tags

Closed OCPP Users tag properties - ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

OCPP Users tag properties - User Info tab

Name

A human-friendly name for each user.

ID

A unique identifier for each user. This value is encrypted and will never be shown.


Omron FINS Driver

Not counted towards your tag license limit.

"FINS" stands for Factory Interface Network Service, which is a protocol for sending messages between controllers on Omron FA networks. The VTScada FINS driver takes care of selecting which of the available protocols to use and which PLC unit, node and network to communicate with.

As described in the FINS command reference, the driver can work with three different types of network: Host Link, SYSMAC NET (TCP/IP) and SYSMAC LINK.

There are differences in communications depending on the type of network in which the FINS commands are used. These differences are listed in the following table:

Item | SYSMAC NET | SYSMAC LINK | Host Link
Code (a) | Binary or ASCII | Binary Only | ASCII Only
Maximum Data Length (b) | Binary: 1990 bytes | 542 bytes | 542 bytes
Baud Rate | 2 Mbps | 2 Mbps | 1200, 2400, 4800, 9600 or 19200 bps
Maximum # of Nodes | 126 (c) | 62 Nodes | RS-232: 1 Node RS-422: 32 Nodes
Destination Nodes | PCs, IBM PC / AT Compatible or CPU Bus Units | PCs, IBM PC / AT Compatible or CPU Bus Units | PCs Only

Notes:

  1. All nodes within any one network must be set to the same code. Networks connected via gateways may use different codes. The code is automatically converted as necessary in inter-network communications.
  2. This is the maximum length from command code through text for internet communications. Slightly longer communications are possible in local connections. Refer to the operation manuals for individual systems for details.
  3. Not including a Line Server.

The PLC system may be configured on multiple networks, connected via a gateway (either a computer with two network link units or support boards, or a unit specially designed to work as a gateway). Using FINS commands, a given network node can communicate with other nodes on three network levels:

  1. Nodes on the local network.
  2. Nodes on networks connected directly via one gateway.
  3. Nodes on networks separated by one other network (i.e. networks connected via two gateways). Note that a connection between a network and a host computer via a Host Link is not counted as an additional gateway for this purpose.

Related information:

Omron FINS I/O Addressing

Omron FINS Error Codes

Best Practices for Tags

Related Application Properties

The following property settings hold additional configuration parameters for your Omron FINS driver:

OmronFINSServerFailTimeOut - Omron FINS server fail timeout. Defaults to 30 seconds.

OmronFINSDriverSemTimeOut - Omron FINS driver semaphore timeout. Defaults to 10 seconds.

OmronFINSSharedRPC - TRUE if all Omron FINS drivers share the same RPC service. Defaults to zero. drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect. whereby the RPC service will be the Name of the driver tag. If true the RPC service will be "OmronFINSServer".

Closed Omron FINS Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Omron FINS Driver properties Protocol tab

Connection Type

Choose which of the three available network types is being used by the system: Host Link, SYSMAC Link, or TCP/IP (i.e. SYSMAC Net Link).

CPU Type

The selection of CV Series CPU vs. CS/CJ Series CPU enables the driver to adjust for differences between these two types of Omron units.

Communications Port

Available only for Host Link and TCP/IP net-work types. In most cases, a COM port is used by Host Link while a TCP/IP port is required by the TCP/IP network type.

Host Link Unit #

Available only when a Host Link network is configured.

Store Last Output Value

If selected, the last output values sent to the Omron FINS device will be saved or stored. Use this option if you want to refresh the output values in the event of a communications failure or a power interruption.

Enable Auto Rewrite

If selected this box causes the last stored output values to be rewritten to the device in the event of a communications loss or power failure.

Omron FINS Driver properties Configuration tab

Base

Available only when the SYSMAC Link network protocol has been selected on the Protocol tab. Specifies the base address of the network support board in the workstation.

Destination Network

In a multi-network environment, use this option to specify by number, the network with which to communication. Set 0 for HostLink. The value is configured in the PLC for SYSMAC Link or SYSMAC NET, using the CX-Integrator.

Destination Node

Specify by number, which node on the network contains the PLCs with which you wish to communicate.

Destination Unit

Specify, by number, the PLC unit on the selected node with which you wish to communicate. The CPU is unit 0 while other rack-mounted cards are the unit number + 10.

Source Network

If you have a multi-network environment, specify by number, the network with which the workstation is connected. Set as for PLC network.

Source Unit

Specify by number, which node on the network contains the workstation.

Time Limit

Responses must be received within the specified time limit, otherwise a communications error will be assumed to have occurred.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

PLC Time Sync

When selected, the workstation time is written to the PLC every hour.

Closed Omron FINS Driver Tag Widgets

The following widgets are available to display information about your Omron FINS driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Omron FINS I/O Addressing

The addressing system for I/O tags consists of a memory area prefix followed by an address number. In the following table, the "#" sign should be replaced by the address number.

Address | Memory Area
IR# | Input / Output Area
WR# | Work Area
HR# | Holding Bit Area
AR# | Auxiliary Bit Area
TI# | Timer Completion Flag Area
CO# | Counter Completion Flag Area
PT# | Timer PV Area
PC# | Counter PV Area
DM# | Data Memory Area
EM# | Current Extended Memory Area

Related information:

Omron FINS Driver


Omron FINS Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No Error
01 | 0x1 | Invalid Memory Address Parameter
02 | 0x2 | Invalid or Illegal Command Param
03 | 0x3 | Response SID did not match
04 | 0x4 | NSB did not respond to send req
05 | 0x5 | Timed Out - No Response
06 | 0x6 | Timed Out Waiting For Response
07 | 0x7 | Bad Received CRC
08 | 0x8 | Unmatched Message IDs
09 | 0x9 | Unmatched Command/Response
10 | 0xa | Unknown Error
11 | 0xb | Network Address Out Of Range
12 | 0xc | Node Address Out Of Range
13 | 0xd | Unit Address Out Of Range
14 | 0xe | Invalid Address Parameter
15 | 0xf | Timed Out waiting for echo
16 | 0x10 | Bad Received FCS
17 | 0x11 | Response from different Host Link Unit
18 | 0x12 | No Valid Response Code
19 | 0x13 | No FINS Response Packet
20 | 0x14 | Unknown Error Code
21 | 0x15 | Local Node not part of Network
22 | 0x16 | Token Timeout, Node # too High
23 | 0x17 | Number of Transmit Retries Exceeded
24 | 0x18 | Max # of Frames Exceeded
25 | 0x19 | Node # Setting Error
26 | 0x1a | Node # Duplication Error
27 | 0x1b | Dest Node not part of Network
28 | 0x1c | No Node with Node # Specified
29 | 0x1d | Third Node not part of Network
30 | 0x1e | Busy Error, Dest Node Busy
31 | 0x1f | Response Timeout, Noise or Watchdog
32 | 0x20 | Error in Comm Controller
33 | 0x21 | PLC Error in Dest Node
35 | 0x23 | Undefined Command Used
36 | 0x24 | Cannot Process Command
37 | 0x25 | Routing Error
38 | 0x26 | Command is too Long
39 | 0x27 | Command is too Short
40 | 0x28 | Specified Data Items != Actual
41 | 0x29 | Incorrect Command Format
42 | 0x2a | Incorrect Header
43 | 0x2b | Memory Area Code Error
44 | 0x2c | Access Size Specified is Wrong
45 | 0x2d | First Address is Inaccessible
46 | 0x2e | Address Range Exceeded
47 | 0x2f | Unknown Error Code
48 | 0x30 | Non-existent Program # Specified
49 | 0x31 | Unknown Error Code
50 | 0x32 | Unknown Error Code
51 | 0x33 | Data Size in Command is Wrong
52 | 0x34 | Unknown Error Code
53 | 0x35 | Response Block too Long
54 | 0x36 | Incorrect Parameter Code
55 | 0x37 | Program Area Protected
56 | 0x38 | Registered Table Error
57 | 0x39 | Area Read-Only or Write Protected
59 | 0x3b | Mode is Wrong
60 | 0x3c | Mode is Wrong (Running)
61 | 0x3d | PLC is in Program Mode
62 | 0x3e | PLC is in Debug Mode
63 | 0x3f | PLC is in Monitor Mode
64 | 0x40 | PLC is in Run Mode
65 | 0x41 | Specified Node is not Control Node
66 | 0x42 | Specified Memory does not Exist
67 | 0x43 | No Clock Exists
68 | 0x44 | Data Link Table Error
69 | 0x45 | Unit Error
70 | 0x46 | Command Error
71 | 0x47 | Destination Address Setting Error
72 | 0x48 | No Routing Tables
73 | 0x49 | Routing Table Error
74 | 0x4a | Too Many Relays
75 | 0x4b | The Header is not FINS
76 | 0x4c | The Data Length is too Long
77 | 0x4d | The Command is not Supported
80 | 0x50 | Timed Out waiting for Port Semaphore
94 | 0x5e | All Connections are in Use
95 | 0x5f | The Specified Node is Already Connected
96 | 0x60 | Attempt to Access Protected Node from Unspecified IP
97 | 0x61 | The Client FINS Node Address is OOR
98 | 0x62 | Same FINS Node Address is being used by Client and Server
99 | 0x63 | No Node Addresses are Available to Allocate


Omron Host Link Driver

Not counted towards your tag license limit.

The Omron Host Link driver provides an interface to an Omron PLC via a serial port.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Closed Reference Notes:

The Omron driver requires that the PLC be in Monitor mode in order for writes to work.

This driver has the ability to save the last value written to each output tag, and to rewrite those values, either automatically when lost communications are restored, or manually by the press of a button. Carefully review the information in the Serial tab to decide whether this feature should be used in your application. If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Related information:

Omron I/O Addressing

Omron Error Codes

Best Practices for Tags

Closed Omron Host Link Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Omron Host Link Driver properties Serial tab

The Serial tab for the Omron Host Link driver tag properties folder consists of attributes used to identify and establish a connection the Serial Port tag that the Omron Host Link driver should use to transmit data to the I/O device. The Serial tab is also used to select the communication protocol to be used in transmissions of data between the I/O device and the driver.

Omron driver serial tab

Port

Enables you to select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag. A Serial Port tag opens a serial port to enable communications between VTScada and your PLC or RTU. A TCP/IP tag enables you to connect to a series of hosts, allowing you to transmit data across a network or over the Internet.

The Port field can be cleared using the X button that appears to its right.

Time-Out Limit

Sets the receiver time-out limit (i.e. the time in seconds or fractions of a second that this driver should wait for a reply from the PLC or RTU).

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Point To Point

Select whether the Point To Point protocol to be used by the Omron Host Link driver in communications with the PLC.

If selected, the driver will use point-to-point protocol (PPP) to communicate with the PLC.

If the Point To Point check box is not selected, the driver will use multi-drop protocol.

By default, the Point To Point check box is not selected.

Station

Enter the PLC station address in this field.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Closed Omron Host Link Driver Tag Widgets

The following widgets are available to display information about your application’s Omron Host Link driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Omron I/O Addressing

The addressing for Omron C-Series PLCs in VTScada is made up of two parts, the memory area and the address. The address string is made up of a two-letter memory designator and an unsigned integer value as outlined in the following table. Although the Host Link protocol does not support bit reads or writes, VTScada does support bit addressing when writing or reading the word registers. Caution should be exercised when writing bits because all bits in the affected register will be written.

The addressing for Omron Host Link driver bits supports the period ( . ) separator, as well as the backslash character ( / ), enabling the use of the standard addressing format utilized by Omron.

The bit address is an optional part of the address string. A complete address for an Omron C-Series PLC would be in the following format:

MMdddd[/BN]

Where MM is taken from the first column in the following table, dddd is the register number, and BN is the optional bit number.

The following table shows the addressing values for Omron C-Series PLCs.

Prefix | Description | Channel Digits | Channel | Bit
AR | Auxiliary Relay | 2 | Yes | Yes
TC | Timer/Counter | 3 | Present Value | Status (don't add digits)
T | Timer | 3 | Present Value | Status (don't add digits)
C | Counter | 3 | Present Value | Status (don't add digits)
DM | Data Memory | 4 | Yes | No
HR | Holding Relay | 2 | Yes | Yes
IR | Internal Relay | 3 | Yes | Yes
LR | Link Relay | 2 | Yes | Yes
SR | Special Relay | 3 | Yes | Yes
TR | Temporary Relay | 0 | No | Yes
EM | Extended Memory | 4 | Yes | No

Examples of Omron Addressing:

DM120
HR98/2
AR120/15

The data types of the Omron registers are set by appending one of the following strings to the end of the address string:

"/UWORD"
"/UDWORD"
"/SWORD"
"/SDWORD"
"/BCD4"

The default data type is unsigned word integer.

For a list of all available data type suffixes that can be used for tag I/O addresses, please refer to Data Type Suffixes for Tag I/O Addresses.


Omron Error Codes

Error codes other than the following may be PLC-specific. Consult the documentation for your device.

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0 | No Error
1 | 0x1 | Not executable in RUN mode
16 | 0x10 | Parity Error
17 | 0x11 | Framing Error
18 | 0x12 | Overrun
19 | 0x13 | FCS Error (checksum)
20 | 0x14 | Format error (parameter length error)
21 | 0x15 | Entry number data error
22 | 0x16 | Instruction not found
24 | 0x18 | Frame length error
25 | 0x19 | Not executable
2 | 0x2 | Not executable in MONITOR mode
32 | 0x20 | I/O table generation impossible
3 | 0x3 | Not executable with PROM mounted
4 | 0x4 | Address over (data overflow)
128 | 0x80 | Incomplete response to WRITE
129 | 0x81 | Bad serial port parameters
130 | 0x82 | Serial port already used
131 | 0x83 | FCS Error (checksum)
132 | 0x84 | No response from PLC (timed out)
133 | 0x85 | Wrong PLC station address responded
134 | 0x86 | TYPE parameter out-of-range
135 | 0x87 | Garbled/Incomplete message
160 | 0xA0 | Aborted due to parity error in transmit data
161 | 0xA1 | Aborted due to framing error in transmit data
162 | 0xA2 | Aborted due to overrun in transmit data
164 | 0xA4 | Aborted due to format error in transmit data
165 | 0xA5 | Aborted due to entry number data error in transmit data
168 | 0xA8 | Aborted due to frame length error in transmit data
11 | 0xB | Not executable in PROGRAM mode
176 | 0xB0 | Not executable because the program area is not 16K
191 | 0xBF | Connection Attempt Failed
12 | 0xC | Not executable with PROM mounted
13 | 0xD | Not executable in LOCAL mode


OPC Classic Client Driver

Not counted towards your tag license limit.

By adding OPC Classic Client Driver tags to your application, you can communicate with OPC servers on your network, whether those are other VTScada applications, control equipment or other programs. The VTScada driver supports OPC DA 3.0

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Reference Notes:

The OPC interface allows for two-way communication, thus you can add both input and output tag types that exchange information with the OPC server through the OPC Classic Client drivers you configure.

Related information:

OPC Classic Client Driver I/O Addressing

OPC Classic Client Error Codes

OPC Classic Server Setup

OPC Classic Configuration - Technical information about the OPC Server configuration in VTScada.

Best Practices for Tags

Closed The ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

OPC Classic Client Driver properties OPC tab

The OPC tab for the OPC Classic Client driver tag properties folder consists of attributes used to identify and establish a connection to the control device to be associated with this driver. The OPC tab for an OPC Classic Client driver is also used to identify the remote server node that the driver should use to transmit data.

OPC driver tag, OPC tab

OPC Server

The Server Prog ID field enables you to specify the program identifier (ProgID) for the OPC server to which you wish to connect. This will be a string of the form Manufacturer.OPC.ServerType.

Examples of a Server Prog ID are: Trihedral.VTSOPC.DA or Matrikon.OPC.Modbus.

The OPC Server vendor generally supplies the Server Prog ID. Refer to your OPC Server manufacturer's documentation for the correct details.

Remote Server Node

Use this field to specify the name of the workstation that is acting as the OPC server. The Remote Server Node field can be left blank in the event that the local workstation is the OPC server.

Analog Deadband (% of full scale)

Set a percentage by which analog values must change before a change in value is reported. If the percentage is 0, the updates will be event driven, occurring on each value change.

Hold

In the event of an interruption in communication, this option will cause the last good value to be held. You should use this option with caution because, unless there is another means to alert you to interruptions in communication, it will appear that a valid value is still being received.

Data Update Rate Controls

By default, data updates from OPC servers are sent to OPC clients only on change of value or quality, with the maximum rate at which the servers send the values to the clients set to a default of 1 second. This is the default time defined in the OPC standard. The following two settings allow the VTScada OPC Classic Client driver to change this default behavior to meet application specific requirements.

Force Asynchronous Refresh

This option allows for an override to the default "send only on change" behavior and when selected will cause the VTScada OPC Classic Client to poll the OPC server for values at a fixed rate as defined in the individual I/O tag’s "Scan Interval" setting.

The default "send on change" behavior will still function when this option is selected. For example, if the I/O tag "Scan Interval" is set to 10 seconds, the server can still send values every second, but the setting will only act to force a refresh from the server every 10 seconds in addition to the update on change.

In some cases, use of this option this may cause excessive load on the OPC Server host as it services all of the data update requests, and should be used only when there is an application-specific need for time based updates versus the OPC standard of update on change.

Use Tag Scan Interval

If this option is selected, the VTScada OPC Classic Client driver will request that the server send the values to the client at a maximum update rate defined by the individual I/O tags’ "Scan Interval" instead of the default 1 second rate.

This feature affects only the rate at which the OPC Server updates tags in the VTScada OPC Classic Client. The rate at which the OPC Server queries field devices depends on the server implementation and cannot be controlled from within VTScada.

If using this option, the client (VTScada) is updated with the current value at the end of each scan interval. If the value at the field device changes several times within that period, then even if those changes are read by the OPC Server, they are not sent to the client.

Accept Data Marked as

Values received by the OPC Classic Client tag are set to INVALID unless the attributes of the value are specifically set to GOOD (>= 0xC0). Use these options to accept values with other attributes as marked.

Closed OPC Classic Client Driver Tag Widgets

The following widgets are available to display information about your application’s OPC Classic Client Driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget


OPC Classic Client Driver I/O Addressing

The VTScada OPC Address Select tool (Address Assist / Address Select) will help you build addresses for your I/O tags.

OPC address browser buttons

Clicking the OPC button opens the OPC Address Select tool. (Example shows a client connected to the Trihedral OPC Server - your display will vary depending on the server that your OPC Classic Client is using. )

OPC Address Browser

Using the Address Select tool, you can quickly navigate through the nodes to the OPC item that you wish to use.

For the VTScada OPC Server, there is no leaf for the "Value" of a tag. The tag node itself has the value attached.

The following is a basic example (not using the OPC Address Select tool) of using an OPC Classic Client driver tag to read data from an Omron C200H PLC via an OPC Server (in this example, an INGEAR Omron OPC Server version 2.25.0.1).

There is no standard for OPC driver addressing. The following example covers only one possible configuration. For your application, the definitive guide to OPC addressing will always be the documentation for the OPC Server in use.

On the OPC Server (using the user interface provided by the manufacturer of the OPC Server):

  1. Create a device named Omron.
  2. Create a group named MyGroup.
  3. Create two items, Tag1 and Tag2.
  4. Configure the tags with the correct addressing information for connecting to the Omron PLC.

VTScada OPC Classic Client Driver tag properties:

OPC Classic Client Driver Tag Properties Folder tab | Property | Value
OPC tab | Server Prog ID | CimQuest.IGOMOPC.1

VTScada Input Tag Properties (Analog Input or Digital Input)

Enter the address Omron.Group.Tag1 in the Address field for the VTScada input tag that will read data from the Tag1 item on the OPC Server.

Enter the address Omron.Group.Tag2 in the Address field for the VTScada input tag that will read data from the Tag2 item on the OPC Server.

Note that the addresses entered for the above VTScada input tags are based on the syntax:

DeviceName.GroupName.ItemName

For a list of all available data type suffixes that can be used for tag I/O addresses, please refer to Data Type Suffixes for Tag I/O Addresses.


OPC Classic Client Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No Error
01 | 0x1 | Failed to load OPC Automation DLL
02 | 0x2 | Connection request to OPC Server failed
03 | 0x3 | OPCGroups Object not retrieved
04 | 0x4 | Failed to add I/O Group to OPC Server
05 | 0x5 | OPC Server Status is Unavailable
06 | 0x6 | OPC Server is not in Running State
07 | 0x7 | OPC Thread heartbeat fail
08 | 0x8 | Unknown Error
20 | 0x14 | The Value of the Handle is Invalid
23 | 0x17 | The Server Cannot Convert the Data
24 | 0x18 | Requested Operation is not Allowed on Public Groups
25 | 0x19 | The Items access Rights do not Allow the Operation
26 | 0x1a | The Address does not Exist
27 | 0x1b | Syntax Error in Address
28 | 0x1c | The Filter String was not Valid
29 | 0x1d | The Items Access Path is Unknown
30 | 0x1e | The Value was Out of Range
31 | 0x1f | Duplicate Name not Allowed
32 | 0x20 | Server does not Support Requested Data Rate
33 | 0x21 | Attempted Write to Clamped Output
34 | 0x22 | Operation Failed because the Object is In Use
35 | 0x23 | Server Invalid Configuration File Format
36 | 0x24 | Requested Object was not Found


OPC Classic Server Setup

Not counted towards your tag license limit.

Use of the OPC Classic Server tag is restricted to VTScada installations that include this feature as part of the license key. You can confirm whether this feature is enabled by opening the About VTScada dialog from the VTScada Application Manager.

Reference Notes:

Server Name: Trihedral.VTSOPC.DA

The VTScada OPC Server supports the OPC DA (Data Access) Standard version 3.0.

The OPC Classic Server tag is used to turn your application into an OPC Server. Minimal VTScada configuration is required on your part to do this.

OPC security is handled by Windows via user and group security permissions set using the Microsoft Component Services dialog and the COM Security tag of the My Computer dialog. Please refer to Securing an OPC Server for more information on OPC security.

Only one OPC server may be defined per application. Attempting to define a second server in the same application will result in an error dialog stating "An application can have at most one OPC Classic Server tag".

Note: Use of the same name space for more than one application is strongly discouraged as it will cause significant problems.

There are no widgets for this tag. When the OPC Classic Server tag has been created, the application’s OPC-supporting tags become available on the VTScada OPC server.

Related information:

OPC Server Error Codes

OPC Classic Client Driver

OPC Classic Configuration - Technical information about the OPC Server configuration in VTScada.

Best Practices for Tags

Closed OPC Classic Server properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

OPC Server Setup properties Settings tab

An OPC Server has two configurable properties in addition to its ID information:

  • The name space for this application on the Trihedral OPC Server. This is a required field.
  • The Disallow Writes check box is there as a security feature. If selected, clients can query data from the server, but cannot write to it.

As a convenience, the server’s Prog ID will also be shown in this screen.

You may find it easiest to reuse the application's name for the server namespace. You should not use the same name space for two applications.


OPC UA Client Driver

Not counted towards your tag license limit.

UA stands for "Unified Architecture". The OPC UA Client driver interfaces to an OPC UA server running on either the local or another computer.

OPC UA is an alternative communication protocol to OPC CLASSIC, which used DCOM for communication between a client and a server. VTScada still supports the existing OPC CLASSIC driver.

Unlike OPC CLASSIC, OPC UA, does not rely on third-party "OPC-tunnellers" to act as proxies between the client and server. An OPC UA server may run on a remote computer or be embedded in a smart device and can run on a variety of operating systems. Because there are a limited number of OPC UA products, a tunneller can be used to connect OPC UA clients to an OPC CLASSIC server.

Do not proceed with OPC UA Client Driver configuration until you have read the related information in the topic, OPC UA Support & Security

If both client and server are using OPC UA, the only additional configuration necessary is to ensure that firewalls allow the correct ports to be opened and that trust is established between the server and client. The port(s) in use are defined by the OPC UA server.

The "None" security policy permits communication without encryption or message signing (no confidentiality or integrity). This should only be selected for testing or when the connection is otherwise protected by external means, such as a VPN between the VTScada system and the OPC UA server.
Where encryption or cryptographic signing of communication is desired (recommended), a trusted certificate is required at both the OPC UA server and the VTScada OPC UA Client driver to verify identity.

Unlike many other drivers, the OPC UA Client does not use a Port tag to communicate with its device (OPC UA server). Due to the nature of the binary protocol, the OPC UA Client has port handling built-in.

If VTScada and the UA server are out of time synchronization by more than 5 minutes, the connection will not be made. The driver will return a 520 error, indicating a large time differential.

The OPC UA Client Driver Statistics Dialog widget provides an "Endpoints" button, which when pressed, will display the list of OPC UA Server Endpoint information that is retrieved by the driver and held internally. This information may be helpful when trying to diagnose connection issues or user authentication problems.

Importing tags from an OPC UA device

Not all OPCUA nodes are considered to be tags, so not all can be imported. The Tag Browser's Import tool will place properties of tags inside the I/O tag where possible instead of bringing them in as separate IO tags.

If the latter functionality is desired, the user will have to create their own independent I/O tags for this purpose.

Related information:

OPC UA Support & Security

OPC UA Addressing - I/O address formats.

Communication Driver Log-Enabled Variables - Log Enabled Variables.

Best Practices for Tags

Closed Related Application properties

OPCUAClientDriverFailoverCount

OPCUAClientSharedRPC

Closed OPC UA Client Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

OPC UA Client Driver properties Connection tab

Use this tab to supply the address of the server.

Endpoint URL

The address of a server using the OPC UA binary encoding is known as an Endpoint URL and is expressed as:

opc.tcp://server:port/path

(see: Server Addressing in the topic, OPC UA Addressing)

Connection Security

Select the type of transport security to be used between the VTScada OPC UA Client driver and the OPC UA server.

Enforce Secure Connection

Always connect using the most secure endpoint available (excludes None).

Prefer Secure Connection

Connect using the most secure endpoint available but allow fallback to None as a last resort.

Use Unsecure Connection

Strictly connect using the "None" security policy. If unavailable, the connection will fail.

The "None" security policy permits communication without encryption or message signing (no confidentiality or integrity). This should only be selected for testing or when the connection is otherwise protected by external means, such as a VPN between the VTScada system and the OPC UA server.
Where encryption or cryptographic signing of communication is desired (recommended), a trusted certificate is required at both the OPC UA server and the VTScada OPC UA Client driver to verify identity.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

OPC UA Client Driver properties Authentication tab

Refer to OPC UA Support & Security for more detail on required security configuration.

Fields within this tab are enabled according to your selection of authentication method:

Anonymous

When authentication is set to Anonymous, no other fields are enabled.

Anonymous Authentication option for OPC UA

Username

Username and Password fields are enabled.

Username and Password Authetication option for OPC UA Client

Certificate

'Select a certificate...' drop-down and 'Manage Certificates' button are enabled.

Certificate Authetication option for OPC UA Client

The 'Select a certificate...' droplist displays a list of available certificates in the current user's Personal Windows certificate store. Selecting the 'Manage Certificates' button will load the Certificate Management UI, where the user may add, update, delete or renew certificates.

If the certificate selected is set to expire in less than 30 days, the expiry date text in the 'Valid To' field will be orange in color and red if it has expired.

Certificates created through the Certificate Management UI will also have an automatically created URL and DNS entry. The URL is derived from the application GUID, making it unique to your instance of VTScada. The DNS entry contains the host name of the workstation on which you are creating this certificate (not the fully qualified domain name (FQDN)). These are used visibly in the certificate's Subject Alternative Names (SAN).

OPC UA Client Driver properties Client Certificate tab

Refer to OPC UA Support & Security for more detail on required security configuration.

Contains a 'Select a certificate...' drop-down, fields for basic information of the selected certificate and a 'Manage Certificates' button.

Use this to choose the certificate that the OPC UA Client will supply to the server for transport security. It displays only valid certificates of the appropriate extended key usage type (that is, suitable for client authentication) that are in the current user’s Trihedral OPC UA Client certificate store. That certificate store is created by the OPC UA Driver for this purpose.

Client certificate selected appearance

OPC UA Client Driver properties Server Certificate tab

Refer to OPC UA Support & Security for more detail on required security configuration.

Server Certificate tab of OPC UA Property Dialog

This tab holds a pair of certificate grids showing trusted and untrusted server-supplied transport security certificates, if any (See: Certificate Management UI). The certificates displayed are those in the current user’s Trihedral OPC UA Trusted and Trihedral OPC UA Untrusted certificate stores.

The server provides its certificate during establishment of a connection with the client. The OPC UA Client will only allow the connection to be established if the certificate is trusted (See Certificate Error Messages for issues that may arise).

If the server’s certificate is derived from a trusted certificate authority (in other words, there is a complete chain of trust from the server’s certificate through any intermediate certificates to the trusted certificate authority’s certificate), the certificate will be automatically trusted and not placed in either of these stores.

If the server certificate is not trusted by virtue of such a chain of trust and is not in the Trihedral OPC UA Trusted certificate store, it is automatically placed in the Trihedral OPC UA Untrusted store and appears in this tab’s Untrusted Certificates grid. From there you can elect to trust that certificate, using the Add Trust button. This will remove the certificate from the Untrusted Certificates and place it in the Trusted Certificates grid (and corresponding store).

If the OPC UA Client trusts the server’s transport certificate, via either of the above two methods, then the OPC UA Client will allow a connection to the server to be established.

OPC UA Client Driver properties Diagnostics tab

On startup, the OPC UA Client reads certain status and other information from the server. This tab displays the most recent information and provides a button to allow the data to be refreshed. The data is only available when there is a good connection to the server.

There is also a check box that allows an unsecured, unencrypted transport connection to be made to the server (if the server permits such a connection) for debugging purposes. The state of the check box always reverts to unchecked when the driver is reloaded (typically on restart of the application). After selecting or deselecting the check box, use the Restart Driver button to cause the OPC UA Client to disconnect and reconnect to the server, thereby switching between secure and unsecured communication.

Closed OPC UA Client Driver Widgets

The following widgets are available to display information about your application’s OPC UA Client Driver tags:

Comm Indicator Widget

Comm Line Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

OPC UA Client Driver Statistics Dialog

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


OPC UA Addressing

Server Addressing

The address of a server using the OPC UA binary encoding is known as an Endpoint URL and is expressed as:

opc.tcp://server:port/path

where:

  • "opc.tcp://" The protocol specifier for OPC UA binary protocol.
  • server The name of the server.
  • :port The TCP port number to use on the server. (Note the colon.) :4840 is the IANA registered port number for OPC UA, but this may not be used by your device.
  • /path Optional path on the server. May not be needed in all circumstances.

For example:

opc.tcp://opctest.trihedral.com:46233/Office/Monitoring

Node Addressing

I/O tags provide an address that identifies the data item it reads data from (or writes data to). In OPC UA, addresses are textual and their content is defined by the server. There is a standard set of addresses defined by the OPC Foundation that are numeric in nature but beyond that, the server implementation is free to structure addresses within defined rules. The address space is divided into namespaces and within the namespaces, Node IDs. Nodes are interlinked with other nodes and are often represented as a tree structure. This is also the way VTScada represents the nodes through the OPC UA client driver address assist.

A Node ID comprises a namespace (an integer, that can be omitted if using namespace 0) and an identifier that can be an integer, a string, a guid, or an opaque set of bytes. This two elements are identified in the I/O address string by the items "ns" and "id" respectively.

When the Node ID is encoded to be transmitted, a choice must be made on how to encode it. An integer can be transmitted in several shorter forms depending on the size of the number, and string, GUID and opaque elements are encoded as is normal in OPC UA for those data types. The encoded data has a field indicating the identifier type, the values for which are 0 (integer), 1 (string), 2 (GUID) and 3 (opaque bytes).

As this encoding must be persisted in the I/O address, the type is specified by the introducer "nt" (for NodeID Type). This was added to VTScada in version 12.0.24 Any existing I/O address strings without the "nt" element will work as they did before, automatically inferring the type, but any new addresses received via OPC UA address assist will have the "nt" element. If adding addresses manually, the appropriate "nt" element should be specified. If it is not, the old inference rules will be applied. This will most notably affect node identifiers that are numeric but should be encoded as strings.

VTScada always formats node addresses as follows:
(Square brackets indicate optional parts. They are not part of the address. Replace XXX with the relevant value.)

[ns=XXX;]id=XXX;nt=XXX[;at=XXX][;ty=XXX]

where:

ns Namespace identifier
Optional. Defaults to numeric zero. The server node addresses are divided into namespaces, with namespace 0 being the set of OPC Foundation-defined, reserved node addresses.
id Node identifier
Mandatory. The identifier is a text string that can represent an integer, a string, a GUID or an opaque set of bytes. It is assigned by the server to this node.
nt

Node ID Type

Mandatory. Defines the type of the NodeID (Identifier type, not data type.) The value of this parameter is numeric, as defined by part 3 of the OPC Foundation's OPC UA specification, section 8.2.3, table 23

at

Attribute
Optional. The attribute specifies which of the (usually many) attributes the address refers to. An attribute is a numeric value between 1 and 27 defined by the OPC Foundation. (See part 6 of the OPC Foundation’s OPC UA specification, Annex A).

VTScada’s address assist helpfully translates these to the same text names as provided in that reference. For example, Value is attribute number 13.

ty

Type
Optional for reads, mandatory for writes. Specifies the type of the attribute supplied to VTScada from the server. This assists with the correct encoding of the data value when writing a VTScada value to the server. Most of the time VTScada can decode data based on information returned with the data value from the server without this hint.

The type values are defined in part 6 of the OPC Foundation’s OPC UA specification, section 5.1.2.

For example:

ns=2;id=West_WTP_Ambient_Temp;at=13;ty=11

identifies the Value attribute (attribute 13) of the server node "West_WTP_Ambient_Temp" in namespace 2. The Value has a type of 11, which is an IEEE double precision (64-bit) floating point value.

OPC UA Address Assist

The OPC UA Client provides address assist for any I/O tags using this driver.

As with other drivers, address assist is activated via the button next to the address field of the I/O tab on an I/O tag configuration folder. For the OPC UA Client, the button is labeled "OPC UA".

Address assist is only available on the computer that is the current server for the driver as communication with the server is necessary in order to obtain OPC UA address space information. The address assist button will be disabled if this is not the case.

Clicking the address assist button opens a separate window divided into a tree view, on the left, and an attribute view on the right.

The tree view displays the hierarchical arrangement of the "nodes" configured on the OPC UA server.

The OPC UA nodes displayed in the tree view are restricted to objects, variables and views. Any node in the tree that has child nodes of these types is represented as an expandable folder to allow navigation to the children.

An OPC UA node contains various attributes that describe the item. Those nodes that possess a Value attribute may be assigned to an I/O tag. The I/O tag’s value will be the node’s Value. For input tags, the I/O tag’s value will be updated using the OPC UA Subscription service. For output tags, the OPC UA server’s value will be updated using the Write method of the Attribute service.

VTScada does not currently support assigning node attributes other than Value to I/O tags via the address assist dialog. If you need to select a different attribute, you must enter the address of the attribute manually.

Tags with blue dots denote variables that are properties (see following image). These are always leaf nodes; they can never have any variables under them. These can be thought of as meta-data about the parent node, not meant to change often. Refer to the definitions provided in the OPC UA Online Reference.

When opening the address assist for an I/O tag that already has an address within the OPC UA server’s address space, the tree will be automatically expanded to the node with that address. This is only possible if the OPC UA server supports reverse browsing, i.e. identifying "parent" links from a node. In the case where this is not supported by the server, the tree will not be automatically expanded.

The format of node addresses supported by the VTScada OPC UA Client is described in Node Addressing.


OPC UA Client Error Codes

If diagnosing error code 270 - No valid endpoint, use the Endpoints tool that is available in the OPC UA Client Driver Statistics Dialog widget.

Error code (Decimal) | Error code (Hex) | Meaning
-10051 |  | Port unreachable
-10053 |  | Connection aborted
-10054 |  | Connection reset
-10060 |  | Connection timeout
-10061 |  | Connection refused
-10065 |  | Host unreachable
0 | 0x0000 | No error
259 | 0x0103 | Failed to connect to server
260 | 0x0104 | Connection to server lost
261 | 0x0105 | Bad message received
262 | 0x0106 | Missing client certificate
263 | 0x0107 | Missing server certificate or thumbprint
264 | 0x0108 | Bad security policy reflection
265 | 0x0109 | Incorrect security token ID
266 | 0x010A | Decryption failure
267 | 0x010B | Message signature mismatch
268 | 0x010C | Incorrect request ID or sequence number
269 | 0x010D | Bad Server URI
270 | 0x010E | No valid endpoint
512 | 0x0200 | Server Certificate is untrusted
513 | 0x0201 | Server Certificate is unreadable
514 | 0x0202 | Server Certificate subject mismatch
515 | 0x0203 | Server Certificate missing required EKU
516 | 0x0204 | Server Certificate bad validity
517 | 0x0205 | Incorrect Certificate supplied by server
518 | 0x0206 | Server failed to correctly sign data
519 | 0x0207 | Incorrect endpoints supplied by server
520 | 0x0208 | Server time offset is too large
32768 | 0x8000 | Unspecific Error
32769 | 0x8001 | An unexpected error occurred
32770 | 0x8002 | An internal error occurred as a result of a programming or configuration error
32771 | 0x8003 | Not enough memory to complete the operation
32775 | 0x8007 | Decoding halted because of invalid data in the stream
32776 | 0x8008 | The message encoding/decoding limits imposed by the stack have been exceeded
32778 | 0x800A | The operation timed out
32782 | 0x800E | The server has stopped and cannot process any requests
32784 | 0x8010 | The request could not be processed because it specified too many operations
32787 | 0x8013 | An error occurred verifying security
32800 | 0x8020 | The User Identity Token is not valid
32801 | 0x8021 | The server rejected the User Identity Token
32803 | 0x8023 | The timestamp is outside the range allowed by the server
32805 | 0x8025 | The Session ID is not valid
32806 | 0x8026 | The session was closed by the client
32808 | 0x8028 | The subscription ID is not valid
32820 | 0x8034 | The node id refers to a node that does not exist in the server address space
32847 | 0x804F | The server URI is not a valid URI
32853 | 0x8055 | The security policy does not meet the requirements set by the server
32889 | 0x8079 | There is no subscription available for this session
32902 | 0x8086 | The secure channel has been closed
32904 | 0x8088 | The sequence number is not valid


Opto 22 Mux Driver

The Opto 22 Mux Driver is designed to communicate with Opto22™ B1, B2, B4 and B5 brain boards. Communications to the brain boards can be via an RS485 serial link for B1 and B2 brain boards or the Pamux™ bus using an ISA bus adapter card for B4 and B5 brain boards

Addressing

The addresses available for your I/O tags are configured within this driver tag. An address selection is available, but rather than being a dialog to be opened, it is a drop-down list within the I/O tag, showing all available addresses as configured within the driver.

Related information:

Best Practices for Tags

Opto22 Driver Errors

Closed Opto 22 Mux properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Opto 22 Mux properties, Serial tab

Brain Board Address

The brain board address.

Board Type

Choices as shown.

Channel

Choices as indicated.

Port

Select the serial port tag used to access the physical Opto 22 device.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Opto 22 Mux properties, PA Mux tab

AC28 Base Port Address

AC28 adapter card base address. Only required for Pamux protocol

Reset Line Port Address

Port address for Pamux reset port. Only required for Pamux protocol.

Reset Active High

If set the brain board reset is active high. Only required for Pamux protocol.

Opto 22 Mux properties, Channels 0 - 15 tab

This tab allows for the configuration of the individual channels of the Opto 22 device, 0 through 15.

Channel x:

This is configuration of the individual channels of the Opto 22 device. Options include:

  • None = No module present
  • DO = Digital Output
  • DI = Digital Input
  • AI = Analog Input
  • AO = Analog Output
  • ICTD = ICTD Probe AD4 Module
  • RTD 10 = 10 Ohm RTD AD14T Module
  • RTD 100 = 100 Ohm RTD AD10T Module
  • TC-J = Type J Thermocouple AD5/AD5T Module
  • TC-K = Type K Thermocouple AD8/AD8T Module
  • TC-R = Type R Thermocouple AD17T Module
  • TC-S = Type S Thermocouple AD17T Module
  • TC-T = Type T Thermocouple AD18T Module
  • TC-E = Type E Thermocouple AD19T Module

Opto 22 Mux properties, Channels 16 - 31 tab

This tab allows for the configuration of the individual channels of the Opto 22 device, 16 through 31.

Refer to the description of the previous tab for details.

Closed Opto 22 Mux Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Next Poll Index Widget

Numeric Value Widget

Plot Data Widget

Reset Polling History Widget

Rewrite Outputs Widget

Sparklines Widget


Opto22 Driver Errors

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0 | No Error
1 | 0x1 | Board Received Undefined Command
2 | 0x2 | Board Received Checksum Error
3 | 0x3 | Board Input Buffer Overrun
4 | 0x4 | Board Received Non-Printable ASCII Char
5 | 0x5 | Board Received Data Field Error
6 | 0x6 | Board Watchdog Timeout
7 | 0x7 | Board Received Specified Limits Invalid
101 | 0x65 | Timed Out Waiting For Response
102 | 0x66 | Timed Out Waiting For Echo
103 | 0x67 | Received Unknown Response
104 | 0x68 | Incomplete Message Received
105 | 0x69 | Timed Out Waiting For Error Response
106 | 0x6a | Recieved Checksum Error
107 | 0x6b | Power Up Error Received


Polling Driver Tags

Not counted towards your tag license limit.

Polling driver tags are designed for use in telemetry applications where communication links may be costly, either in terms of time or money.

Reference Notes:

The Polling driver tag provides the following features:

  • The ability to poll multiple stations or I/O devices in a pre-determined order and at a fixed time interval.
  • The ability to switch to fast-polling mode of selected sites on demand. See Fast Scan Widget.
  • Provides a simple grouping of I/O tags on a single display.
  • Navigate to a station page using F11 or F12.

Polling driver tags are not required for Data Flow RTU driver tags because those have a polling feature built-in.

Polling drivers should be configured to stand between a communications driver tag and the I/O tags. Their function is to control the order and the frequency of data transfer between the I/O tags and the remote equipment via the communication driver tag.

All input tags associated with a Polling driver will use the scan interval configured for the Polling driver rather than their configured scan rate.

When data is written from an output tag, it is immediately passed to the Polling driver tag and then on to the associated communication driver tag. Following each write, all I/O addresses will be read immediately so that feedback need not wait for the next polling cycle.

Each polling driver should be attached to a unique driver. These may share a common port.
Because Poll Drivers use the same RPC service as their communication driver, it is important to ensure that all communication drivers within the same Polling Group are using the same server list.

Alarming

When polling fails-over from the primary server to a backup, VTScada automatically generates an alarm with priority 3 (warning). You may control this using three application properties as follows:

  • PollDriverAlarmPriority. Defaults to 3 - Warning.
  • PollDriverAlarmDisable. Defaults to FALSE. In spite of the name, this property will decommission the alarm rather than disable it when set to TRUE.
  • PollDriverAlarmOnDelay. Defaults to 60 seconds. Avoids nuisance alarms from transient network issues.

A common need is to create an alarm that will be triggered, not on the first failure, but only after x consecutive polling cycles have failed. This can be done using an expression in an Alarm tag, created as a child of the Polling driver. You will need to know the following:

  • [*Driver]\LastTime will return the time stamp of the parent Polling driver's last successful poll.
  • Time stamps are measured in seconds since January 1, 1970. (Standard computer time stamp.)
  • Today()*86400 will give you the number of seconds from January 1, 1970 to midnight last night.
  • Now(60) will give you the number of seconds from midnight to the most recent minute, updating once a minute at the minute mark.

Combining that information, you can create the following expression to find the time since the last successful poll, updating on each poll and on the minute mark:

Today()*86400 + Now(60) - [*Driver]\LastTime

If your polling rate is two minutes (120 seconds) and you want an alarm after five unsuccessful polls (5 * 120 = 600), then your alarm expression becomes:

Today()*86400 + Now(60) - [*Driver]\LastTime >= 600

Learn more about expressions here: Expressions

Station Page Navigation

Pressing either F11 or F12 will open the Station Number dialog:

Related information:

Polling Groups and Scan Intervals

Closed Polling Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Polling Driver properties I/O tab

The I/O tab for the Polling Driver tag consists of properties used to identify the communication driver tag to be associated with this polling driver, and to establish the poll group, the I/O device's sequence in the poll, and the interval at which the equipment associated with the communication driver tag should be polled for data.

Polling driver configuration

I/O Device

The I/O Device field enables you to specify the communication driver tag for which this polling driver will set the scan rate.

The I/O Device field can be used to associate this tag with a new or existing communication driver tag using the tag browser button. The button opens the Tag Browser, which displays only the existing communication driver tags for your application, and enables you to create a new communication driver tag using its New button.

Poll Group Name

Optional. If you have several Polling Drivers with similar configurations and especially if those drivers use the same port (possibly a radio) you may create an association between them by creating and assigning the same group name to all. There are several use-cases for this, as described in Polling Groups and Scan Intervals.

Poll Sequence Number

Relevant only if you have used the same Poll Group Name for several Polling Drivers, and if those drivers are configured with the same Scan Interval and Delay After Scan.

Because the interval and delay are the same, all drivers are placed on the group's "to-be-polled" list at the same time. The Poll Sequence Number specifies this driver's place in the sequence for the identified group. See: Polling Groups and Scan Intervals

Scan Interval

Measured in seconds. When the scan interval is reached, the driver is placed back on the "to-be-polled" list. For example: If, as a result of slow communications, it takes 10 seconds to poll a station, a driver with a one-second scan interval can scan only once every 10 seconds. But, thanks to its one-second scan interval, it is placed back on the list immediately after each interval passes, and will be next in line for the following round of scans.

If the Scan Interval is set to 0, the I/O device is scanned for data as fast as is possible, defaulting to 1 second. Note that Polling drivers were designed for use with radio communication, therefore the fastest possible scan interval is one second. Faster intervals do not make sense for the intended purpose. If you require scan intervals measured in fractions of a second, configure those directly within your I/O tags and do not use a Polling driver to control timing.

See: Polling Groups and Scan Intervals

Scan Interval Offset

Measured in seconds. Sets a delay after the Scan Interval that must pass before the driver is added back to the "to-be-polled" list. For example, if the Scan Interval is 10 and the delay is 2 (both measured in seconds) then the driver will be added back into the to-be-polled list at the 2, 12, 22, 32... marks, assuming that it takes less than 10 seconds to complete the poll. (10 second interval plus 2, not 12 second intervals of 12, 24, 36...)

See: Polling Groups and Scan Intervals

External Poll Trigger

May be linked to any tag or expression that transitions from a 0 or invalid state to a 1-state to trigger a poll. A Trigger Tag should be used here, if you want to schedule polling to occur on a given schedule or in response to an operator’s command. Note that an external poll signal will not cause a poll to occur if polling is disabled, or if fast scan mode is enabled.

Disable Polling

Use to disable or re-enable the polling cycle for this poll driver. This does not mean that reads or writes are disabled because only the polling cycle is affected. A Toggle Polling Button widget can be drawn in your application to allow operators to change this value at need.

Closed Polling Driver properties Display tab

The Display tab is used to define the placement (latitude and longitude) of the Polling Driver station. Decimal values should be used rather than degrees, minutes and seconds.

You may find it easier to set the location using the map interface than to enter the latitude and longitude values here. See: Site Map.

Latitude and Longitude

Holds location coordinates for this tag, thereby allowing it to be represented on a Site Map page.

Custom Details Page

If a custom details page has been created for this context tag, then that page should be selected here. If there is no custom details page, then operators will see the standard Site Details page upon clicking the pin for this tag in a Site Map.

Advanced Configuration:

The default page selection dialog has a filter for "all pages" or "site pages", meaning those that take a site tag as the first parameter.

You can add either of the following two properties in the Edit Properties page of the Application Configuration dialog to restrict this filter:

LimitPageListToSitesPages

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog for all users.

LimitPageListToSitesPagesIfRealmUser

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog if the user belongs to a security group.

Custom Map Icon

If a custom map icon widget has been defined, you can select it here. That icon will then be used instead of the standard pin when this tag is represented on a Site Map page. If there is no custom map icon, then the standard pin will be used.

Site List Display

Assuming that this tag has site properties, it will be included in the list of a Sites page. What will happen when an operator clicks on this tag in that list depends on the Site List display choice, and on whether any of this tag's children are I/O tags.

  • Display as Site: A click will open the Site Details page as a pop-up.
  • Display as Folder: A click will leave focus on the Sites page, but the list will now show the child tags of this site.
  • Exclude: This tag should not be shown in the Sites page list.

Map Zoom Level

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Closed Polling Driver Tag Widgets

Polling driver tags enable users to establish groups of PLCs or RTUs that will be polled together. The widgets for a Polling Driver tag enable users to display pertinent data about the RTU or PLC with which they are associated.

The following widgets are available to Polling Driver tags:

Active Indicator Widget

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

Data Age Widget

Draw HDV Widget

Enable Polling Checkbox Widget

Equipment / Status Color Indicator

Fast Scan Widget

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Data Age Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Polled Station Widget

Site Draw Widget

Site Alarm List

Sparklines Widget

Tag List Widget

Toggle Polling Button Widget


Polling Groups and Scan Intervals

Polling Groups and Scan Intervals are separate concepts. In some configurations, there can be a logical relationship between them, but membership in a Polling Group has no effect on the driver's Scan Interval or Delay After Scan. These are separate things.

Background

Polling Driver Tags were created when the most common link between the VTScada workstation and the remote device was through a serial port. In that configuration, it was typical to create a Polling Group for each serial communication link. This continues to be true for the case of stations connected via a radio link. While the Scan Interval is typically configured to be the same for every driver in the group, there are situations where it might vary, as described later in this topic under Scan Intervals.

There are three use cases for Polling Groups:

Use Case #1

The main purpose of the Polling Driver is to try to poll all the IO in a remote RTU closely in time rather than letting the driver poll individual blocks of data from any remote station based upon the oldest data (the default behavior). This is helpful when there is a slow polling update to get to all of the data, as is typical in radio telemetry systems where it can take several minutes to poll all of the remote stations. If various parts of the data from a station were each polled a few minutes apart, it can create unexpected results, such as the pump showing as running but the motor's amperage being 0. The scan interval of each driver should be configured to be the same in this case.

Use Case #2

The second major reason for the Poll Driver is to force the sequence of polling through a set of RTUs. This is seldom necessary for any reason other than the reassurance of seeing stations being polled in an expected order. Scan intervals and delays must be the same for all drivers in the group.

Note that delays due to the time it takes to scan can affect the order, with variations increasing over time.

Use Case #3

A third feature of the Polling Driver is that it will immediately force a poll of all the inputs at a station whenever something is written to a station. This lets the operator see the effect of a control action immediately rather than waiting for the next poll cycle.

Scan Intervals and Delays

Each Polling Driver specifies its own poll (scan) interval. When the specified time since the last poll is reached, that driver goes on the "to-be-polled" list. In most cases, drivers with the same scan interval all go on the list at the same time and they all get polled in order according to their sequence number in a group.

If the scan interval is longer than the time it takes to poll the last group, then that station will wait until its next scan interval is reached. Others with shorter scan intervals may continue to poll in the meantime.

(In the following example, the 10 seconds required to poll a station is unusually long. The number was chosen for the sake of clarity in the sample rather than to approximate actual hardware.)

For example, suppose that you have a system that requires 10 seconds to poll each station, and you have 4 stations, each set with a 1-second scan interval. Each station would go back on the list 1 second after it is polled but must wait for the remaining stations to be polled, so all stations would be polled once every 4 x 10 = 40 seconds. (Example continues...)

Suppose further that one station is more important than the others. You might back off the timing on the other 3 by setting their poll interval to 60 seconds. The result is the high-priority station (still set to poll at 1 second) would poll every 10 seconds (the time required by the hardware), while all of them would poll every minute. This is not ideal, because at the minute mark, the high priority station would have to wait 3 x 10 = 30 seconds longer to get its data. The scan delay parameter can help here. For the three lower priority stations, the delays might be set to 0, 20 and 40 respectively. What this will do is poll the high priority station consistently every 20 seconds, and each of the others once per minute (at 0 second mark the first low priority station would go on the poll list with the high priority station, next at the 20 second mark the next low priority station would go on the list, and so on).

High and Low Priority Groups

Another use case for the poll groups would be to put high priority stations in one group and low priority stations in another. The stations in each group could be set up with different polling intervals, with the high priority ones set to a very short interval, say 1 second, even though the com channel may not support that low of a polling rate.

The low priority stations would have a poll interval set significantly higher than the time it takes to poll all of the high priority stations. As in the previous example, the low priority stations might have a 60 second interval. The benefit of this method is that it avoids any need to calculate and maintain scanning delays. All could be set to 0 and the same result as the previous example would be achieved.


Rockwell Driver Tag

Not counted towards your tag license limit.

As of VTScada version 12.1, this tag replaces the legacy CIP/ENIP Driver (Control and Information Protocol) and combines support for multiple Rockwell devices into one driver.

The Rockwell driver type provides an interface between VTScada and Rockwell PLCs that use the CIP, CSP Socket or Serial communication protocols. This includes: CompactLogix, ControlLogix, Micro 800 series, PLC-5, SLC-500 and MicroLogix 1100-1500 PLCs.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

The Rockwell driver is able to query the PLC's Tag configuration on the CompactLogix series of PLCs. Therefore, those configurations will support the Import function to create tags in your application automatically. Before attempting the import, ensure that:

  • You are connected to the correct Rockwell device.
  • Your application is not pending a restart.
  • Your account has the Tag Modify privilege.

Instructions and error descriptions are provided in the documentation under Import Tags from PLCs. Note that only ControlLogix modes support PLC tag upload.

The Rockwell driver may have trouble doing a 'large' PLC upload in a certain configuration. In this case, a 'large' PLC tag upload is defined as one that takes longer than the 'CIP Connection Timeout' parameter.

Some tags displayed in the Address Assist dialog may return a "Path Destination Unknown" error, depending on the PLC's ExternalAccess attribute.

Related information:

Best Practices for Tags

PLC Alarm Tag

CIPForwardCloseAdvance - Default: .5 Used to compensate for network latency to avoid the situation of Forward Close commands reaching the destination after the connection has already been closed in the PLC.

CIPTransTimeOutCount - Defines the number of transaction timeouts for a CIP driver before the connection is dropped.

CIPMaxNumberofSessions - Deprecated.

RockwellDriverDHRIOChannels - Default: 2. Number of DH+ channels that can be addressed in a 1756-DHRIO card.

RockwellDriverMaxCPInstance -Default: 1. The maximum Connection Point instance number to use.

RockwellPollB4BuildComplete - Default: 0. Set to 1 to poll before all reads are built.

RockwellReadsBeforeAddressError - Default: 2. The number of reads before setting an address error. Set to zero to disable the Address Error dialog in the Symbolic addressing mode.

RockwellWriteMode - Default 0. Set to 1 for Fragmented (0x53) or 2 for Tag (0x4D).

RockwellMaxUploadIdle - Default 15. The maximum idle time in seconds for the tag upload procedure during tag importing.

RockwellDriverMaxInboundPacketSize - Sets the maximum inbound packet size for your Rockwell drivers.

RockwellDriverMaxOutboundPacketSize - Sets the maximum outbound packet size for your Rockwell drivers.

RockwellDriverMaxStringLength - Sets the maximum string length for your Rockwell drivers.

Closed Rockwell Driver properties - ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Rockwell Driver properties - Configuration tab

The Rockwell driver may have trouble doing a 'large' PLC upload in a certain configuration. In this case, a 'large' PLC tag upload is defined as one that takes longer than the 'CIP Connection Timeout' parameter.

PLC Mode

Choices include:

  • CompactLogix/ControlLogix (Logical Addressing - Default)
  • CompactLogix/ControlLogix (Instance Symbolic Addressing)
  • CompactLogix/ControlLogix (Symbolic Addressing)

For CompactLogix and ControlLogix PLCs, there are three choices. The Logical Addressing mode is the most efficient and fastest read method but requires an upload of the PLC tag information. This mode also requires the building of 'Readblocks' within the PLC each time there is a new CIP connection to the device.

The Instance Symbolic Addressing mode is the second-most efficient read method and also requires an upload of the PLC tag information. However, this mode does not require the building of 'Readblocks' so it will be quicker to recover from a CIP Connection loss.

The Symbolic Addressing mode is the least efficient read method but does not require an upload of PLC tag information nor the building of 'Readblocks'. This mode is best used on smaller PLCs with slower communication links or slow period polling requirements (i.e. > 15-30 minutes).

  • Micro820/850 (Symbolic Addressing)

For Micro 800 series PLCs, Symbolic Addressing is the only read method available. (There is no PLC tag upload, nor the building of Readblocks).

The Address Select tool is always available when configuring your I/O tags when using the Logical Addressing or the Instance Symbolic Modes. In the Symbolic mode, the Address Select is available but 'optional', so the PLC tag Read must be triggered from Address Select dialog as it is not automatically uploaded in this mode. The Address Select is not available in the Micro 800 series PLCs.

  • PCCC over CIP

Select to connect to older Allen Bradley PLCs that support the PCCC protocol (Data File addressing encoded in CIP messages), such as PLC-5 (Enhanced controllers only), SLC-5/05 and MicroLogix 1100-1500, selected through the PLC Type control, in the PCCC/DF1 tab.
Recommended only when the target PLC supports EtherNet/IP connections directly (MicroLogix). While this mode also allows the routing through DHRIO cards, the Routed DH+ mode is more efficient and compatible with a broader range of controllers.

  • Legacy Serial/CSP Socket

This mode is similar to the PCCC Mode in that it also supports Data File addressing-compatible PLCs (PLC-5, SLC-500 series and MicroLogix 1100-1500), but instead using Serial or CSP Sockets over TCP/IP. All protocol settings for this mode are set in the PCCC/DF1 tab. PLC-2, PLC-3 and PLC5-250 are not supported by the Rockwell driver. Use the Allen Bradley Driver with those controllers.

  • DH+ routed through Logix PLC/DHRIO card

Used to reach PLCs connected to the DH+ channels of a 1756-DHRIO Interface Module, typically from a ControlLogix chassis. Like PCCC and Legacy modes, it is intended to communicate with older controllers, namely PLC-5 and SLC-500 series (Data File addressing), by encapsulating DF1 messages in CIP packets sent through CIP connections to the DHRIO card. Therefore, Port Segment Path must be targeted at the DHRIO card itself, rather than the PLC (do not add the segment containing the DH+ channel and station address to the Port Segment Path). The DH+ channel (A or B) is selected on the CIP Connection Target drop-list, whereas the PLC Type and Address are configured in the PCCC/DF1 tab.

You may achieve improved response time when using the Rockwell's Symbolic Addressing modes from the driver by increasing the system overhead time slice setting within the PLC from 20% to 70% via the Logix 5000 or Studio 5000 software.
Use this information with caution, taking your unique situation into account. It may be less relevant for newer systems.

Port Segment Path [Port #, Link Address][Port,Addr]…

The Port Segment Path format is [Port ID, Link Address], and describes the path or route to access the data.

The Port ID is a number that describes the port by which the message will exit the communications card that received it.

  • Port ID 0 is reserved.
  • Port ID 1 is the backplane from a communications card
  • Port ID 2 and 3 are the communication port of the communications cards.

For example port 2 on a DHRIO type card is DH+ channel A, while port 3 is channel B (PCCC mode only).

The Link Address is the destination address of the message for this pair of the port segment path. You may provide an IP address for Ethernet network, slot number for a backplane, (decimal) node number for DH+ and ControlNet networks and station address for DF1 networks. Note that node numbers in Routed DH+ mode must be set in the PCCC/DF1 tab, rather than in the Port Segment Path.

For example when accessing the CPU with a built-in Ethernet port, the Port ID would be 1 for the backplane and the link address would be the slot number of the CPU. If the CPU is in slot number 0 the Port Segment Path parameter should be set to [1,0].

In newer CIP devices such as the 1756-L83E processor, use an empty path rather than [1,0].

Further examples:

[1,5]
The message destination is slot number 5 of the backplane.

[1,5][2,18]
The message will be directed to slot number 5 on the backplane and then out port 2 of the communications card to node or station address 18, depending on the type of network

[1,5][2,10.158.2.20][1,0]
The message will be directed to slot number 5 on the backplane, then out port 2 of the Ethernet card to IP address 10.158.2.20 and then to slot number 0 of that backplane.

You must be familiar with the hardware to which you are connecting to correctly establish the Port Segment Path. The newer ControlLogix L80 series of PLCs can use a blank or a [] Port Segment path for connections directly to the processor.

CIP Connection Target

(Was: Path uses a Connection point) Select between Message Router, no Connection Point or Message Router, Connection Point 1

For native CIP modes (including PCCC in "Connected Mode"), this determines whether the connection target is the Message Router itself, or one of its 'connection points' (currently, the only option is instance #1). Defaults to "Message Router, Connection Point 1". The connection point is not needed when you are routing ‘through’ one device to another device, or when you are connecting to a ControlLogix L80 series processor via a separate IP card.

For Routed DH+ mode, it is used to select the DH+ Channel of the DHRIO card (A or B). Defaults to "DH+ Interface, Channel A".

If seeing the error, "789 (0x315) – FO: Invalid segment in connection path", set the connection target to "Message Router, no Connection Point.

Check for PLC Changes (s)

The Rockwell driver reads the entire PLC tag configuration into memory as dictated by the PLC Mode setting above. For the modes that require the PLC tag information, this parameter controls how often the PLC is checked to see if that tag configuration has changed from the last time it was uploaded. If a change is detected, the PLC tag configuration is reloaded.

In the Symbol addressing mode, where the PLC tag upload is optional, this parameter controls how that uploaded data (for use in the Address Assist dialog) is valid.

This parameter is ignored for the Micro 800 series and Data File addressing modes (PLC tag upload is not supported).

The full read of the PLC tags configuration can take time and will interrupt the driver's read process. This check time can be extended from the default of 30 seconds if:

  • You are confident that the PLC tag configuration is not changing.
  • You don't mind manually initiating the PLC tag upload when need to pick-up a new tag name/address from the PLC (if you have set this extremely large). This avoids the disruption that a PLC tag upload may cause.

Use unconnected messages on the PLC tag upload

Newer versions of Rockwell firmware support the use of unconnected messages when doing the PLC tag upload. This can significantly decrease the time it takes to do that upload.

You should perform a manual PLC tag upload (triggered from an Address Assist dialog) and watch via the Show Stats dialog, to see if this setting is faster for your configuration. Defaults to not using connected messages.

When PCCC over CIP is selected, this parameter becomes 'Use unconnected messages on all PCCC communication'. Enable 'unconnected messages' if the target PLC does not support CIP connections. The Rockwell driver will generate a "Service not supported" error if so.

Maximum Number of CIP Connections

Rockwell's implementation of the CIP protocol supports multiple CIP messages ‘in flight’ by opening multiple CIP Connections on a single EtherNet/IP Connection / TCPIP Socket. If you have enough PLC resources, communication bandwidth and host machine CPU capacity, then multiple CIP Connections will increase your system performance.

This parameter should be tuned for your specific configuration:

Increase the number of connections until all connections are not being used. The number of CIP Connections in use is shown in the driver's Show Stats dialog.

Decrease the number connections if either of the following occurs, usually on startup (as shown in the Show Stats dialog):

  • CIP Connections start to fail to open with an insufficient Memory Buffer error
  • CIP Connections start to fail with a timeout error

Up to 128 simultaneous CIP connections are supported, but 5 to 10 typically provide the best performance.

Default: 1 connection.

Rockwell Driver properties - Communications tab

Port

Select the TCP/IP tag that will provide the IP address and port to be used when communicating with the PLC. Rockwell's default TCP/IP port number is 44818.

If using the Legacy mode, you may need a Serial or UDP port. Either can be used, but this means that it is also possible to use the traditional (the first 4 Rockwell Driver modes) CIP communication modes over a serial link instead of TCP/IP. This is not recommended because serial links would be too slow for CIP communication and should only be used in exceptional cases.

The Rockwell driver supports a shared serial port, which is needed for radio or modem-based communication. It is best configured with a Serial Port tag as the parent and Rockwell drivers as child tags of that port.

Shared port tags might be required in two situations:

  • In Legacy Serial mode, a shared port is needed for radio or modem-based communication. It is best configured with a Serial Port tag as the parent and Rockwell drivers as child tags of that port.
  • When accessing multiple PLCs through the same Ethernet interface card, (a common scenario in the Routed DH+ mode), it is possible to use either a single TCP/IP Port tag for all drivers, or one TCP/IP Port tag for each driver or group of drivers. Each Port tag will make exactly one TCP connection to the Ethernet card, therefore the Port tag's Maximum connections setting shall be left at the default setting of 1. Using multiple TCP/IP Port tags may improve the performance when communicating with tens of PLCs with such setting, but care should be taken not to exceed the maximum number of simultaneous TCP connections supported by the card.

Operation Timeout

Use to specify the time (in seconds) after which the driver will abort a communication attempt and declare a timeout error. The default value for Operation Timeout property is 10 (seconds). The Operation timeout x Retries should be less than the CIP Connection Timeout.

CIP Connection Timeout

The CIP Connection timeout is the time a CIP Messaging Connection remains open without any communication activity with the PLC. On hardwired or direct communication networks, which usually have faster tag poll times, the CIP Connection Timeout should be set higher than the poll rate so that the CIP Connections do not close between polls. This avoids the overhead of the Logical Address mode's PLC Readblock build, caused by the termination of a CIP Connection.

On bandwidth-limited networks (typically cellular or radio based), which usually have slower tag poll times, the CIP Connection Timeout should be lower than the poll rate so that the CIP Connection closes after the poll completes. In this mode of operation, the driver should be run in the Symbolic Addressing mode to avoid the overhead of the Logical Address mode's Readblock build.

In order to determine which mode of operation is best for your configuration, you should perform a detailed analysis of the factors such as:

  • The overhead of the Logical Address mode ReadBlock build and PLC tag upload (when required) transactions.
  • The smaller polling packet sizes in the Logical Addressing mode than in the Symbolic Addressing mode.
  • The cost of 'tcp/ip keep alive' packets for a communication link not being used.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Rockwell Driver properties - PCCC/DF1 tab

Configuration in the PCCC/DF1 tab is required to support the Data File addressing-compatible modes (PCCC over CIP, Legacy Serial/CSP Socket and Routed DH+).

PLC Type

Select the type of the target Allen-Bradley PLC. This may be one of:

  • PLC-5
  • SLC-500
  • MicroLogix 1100-1500

VTScada Station Address (Octal)

Legacy Serial mode only. Specify the address (using the octal addressing format) of the VTScada system on the serial link.

PLC Address (Octal)

Legacy Serial and Routed DH+ modes only. This field should contain the octal address of the Allen-Bradley programmable logic controller.

DF1 Mode

Choose between the following data transmission modes in communications from the driver to the PLC.

  • Full Duplex (Serial) is the same as the AB Driver's Serial 'Communication mode' and DF1 Mode of Full Duplex.
    Full duplex mode refers to the transmission of data by both parties simultaneously.
  • Half Duplex (Serial) is the same as the AB Driver's Serial 'Communication mode' and DF1 Mode of Half Duplex.
    Half duplex mode refers to the transmission of data in one direction at a time. If the driver and the PLC are communicating using the half duplex mode, either the driver or the PLC may transmit data at one time. The device not communicating must wait until the device that is transmitting data is finished before it can transmit its data.
  • Radio Modem (Serial) is the same as the AB Driver's Serial 'Communication mode' and DF1 Mode of Radio Modem.
    Certain Allen Bradley PLCs use the Radio Modem Protocol (RMP) to optimize DF1 communication on radio modem links. The protocol is an enhancement of the Full Duplex Protocol and uses the same message format with all the ACK and NAK responses removed.
  • Multi-message Full Duplex (Serial) is the same as the AB Driver's Serial 'Communication mode' and the Multi-message mode checked.
    If multiple Allen Bradley drivers are sharing the same port, then all drivers using the port must use the same configuration for this setting. Further, all of their "Communication Mode" and "DF1 Mode" settings must match as well. This option cannot be used if other types of drivers share the same port.
  • CSP Socket (TCP/IP) is the same as the AB Driver's TCP/IP Communication mode.
    This is supported only by the PLC5 and SLC-500 PLCs, The MicroLogic TCP/IP uses the PCCC Mode of the Rockwell driver for its TCP/IP based communication.

BCC

Select whether the BCC error checking method will be used on communication messages. If not selected (the default) then CRC error checking is used on all communication messages.

The CRC acronym stands for Cyclic Redundancy Check, and the BCC acronym stands for Block Check Character. Both are techniques used to detect data transmission errors. In general, CRC is a better error checking method, as it is a 16-bit error check, whereas BCC is an 8-bit error check.

ENQ Delay

Specify the amount of time (in seconds or in fractions of a second) that this driver should wait before sending an ENQ when the DF1 mode is set to half duplex.

(Half duplex mode refers to the transmission of data in one direction at a time.)

Data Logging Queue

Use to select a queue (configured according to the PLC’s manual) from which the driver will be retrieving logged data.

Length of Records from Queue

Enter the length of the records in the queue selected in the Data Logging Queue drop list. This value is the length (in characters) of the records in the queue after they are converted into a string by the PLC for communication.

The valid range is from 1 to 80. The value must be calculated according to how the data logging queue was configured in the PLC itself:

  • 11 characters for the date field,
  • 9 characters for the time field,
  • 12 characters for each long integer field
  • 7 characters for each short integer field.

By default, the driver will assume a length of 80 chars (the maximum allowed by the PLC). While the default value will work, this may impose a penalty on the amount of communication between the driver and the PLC. Entering the exact length is therefore recommended.

Note: entering an incorrect value will most likely result in failure to read any records from a particular queue, therefore you should only change the default value if you know the exact value.

Closed Rockwell Driver Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Rockwell Control Widget

Rockwell Statistics Widget

Rockwell Information Widget

Comm Indicator Widget

Comm Line Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 7 Segment Widget

LCD 5x7 Matrix Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget

Rockwell Driver Statistics Dialog


Rockwell Driver I/O Addressing

The VTScada Address Select tool (Address Assist / Address Select) can help you build addresses for your I/O tags for most Rockwell devices that support the upload of PLC tag information. The upload of the PLC tag information can be triggered from within the Address Assist tool if required.

Note that if you have modified the address in a way that is not recognized by the driver, the address assist will not find that reference.

When the Rockwell driver is in the PCCC or the legacy mode, Allen Bradley I/O addressing for PLC-5, SLC-500 and Micrologix 1100-1500 applies. Refer to Allen-Bradley Driver I/O Addressing

In all cases, it is worthwhile to refer to the manufacturer's documentation for the final word on address formats.

Address Structure:

Address | Description | I/O String
Tag_Name | Reads the tag matching the provided name | Tag_Name
Tag_Name[n] | Reads element n from array Tag_Name | Tag_Name(n)
Tag_Name[n,m] or Tag_Name[n][m], etc. | Reads element m from 2D Array Tag_Name | Tag_Name(n)m
Tag_Name.Attribute | Reads Attribute from structure Tag_Name | Tag_Name Attribute
Tag_Name[n].Attribute | Reads Attribute from structure in Array Tag_Name, Element n | Tag_Name(n) Attribute

Examples:

Address | Description
Setpoint | Read the value of the tag Setpoint.
Analog_Data[4] | Read the value of element 4 of the Analog Data Array.
Timers[6].PRE | Read the value of the Preset Attribute of the 6th timer in the Timers Array.
Inputs[5,9] | Read the 9th Element of the Inputs 2 dimensional array.

Rockwell Driver tag data type qualifiers:

Both write and Boolean array read addresses traditionally require a data type qualifier when using the Symbolic addressing modes. The Logical and Instance Symbolic addressing modes do not require data type qualifiers.

In the Symbolic Addressing modes, if the driver reads a tag address before it is written, the data type is retained from that read so the data type qualifier is not required on the write address (i.e. read before you write).

For Symbolic mode Boolean array reads, if an address generates a 'Path not found' error on its first attempt, the address is retired as Boolean array read instead. A true Boolean array address will then read. If not, an address error dialog is generated.

The above logic will probably negate the need for data type qualifiers in most situations. However, if required, the supported data type qualifiers are:

|BOOL

|SINT

|INT

|DINT

|BYTE

|WORD

|DWORD

|REAL

|SMALLSTR

|BOOLARR

|LREAL

|LINT

|LWORD

|DATE

|TIME

|UDINT

|ULINT

|USINT

|UINT

If you are using the Address Assist dialog, you can select the Use Address Qualifier box and the correct data type qualifier will be appended to the selected address. Also, the data type of a particular tag entry is shown by hovering over the item in the displayed tag tree.

Bit Addressing

You can specify a bit number on integer and double integer addresses. If you choose to use this format, the .bit # is stripped off the end of the address so the address assist dialog can find it.

To read bit number four of an element in a double-int array, add a .4 after the address. For example, DINT_Array[n].4 where [n] specifies the number of the element in the array.

Note that you cannot use this format for Boolean array elements. Everything after the closing bracket of the array element number will be ignored.

The use of this format of bit addressing will reduce PLC communications if you are reading many individual bits out of the same address (either integer or double). This because VTScada will do a single read of the addressed item (with the bit number stripped off) and all tags will be updated as per the tag's corresponding bit number.

The Use External Bit Number check box allows for address with an explicit bit number to be converted to the External Bit Number format.

Program tag addressing:

VTScada I/O tags can also access local tags defined in a PLC module (program) via the following address format:

Program:ProgramName.tagname

Where, "Program:" is a keyword, "ProgramName" is the name of the program in the PLC and "tagname" is the PLC tag name.

Rockwell documentation states that only controller (global) tags should be accessed directly. That said, VTScada does not enforce this rule, but the PLC may still return a Path Destination Unknown error when attempting to access a program tag, even if it is listed in the Address Select dialog. If that happens, the only way to access the tag is by copying it to a user tag in the global scope.
Micro800 PLCs generally do not offer direct access to program tags.

Structure Referencing:

The Rockwell driver can read entire structures, and the Address Assist dialog will allow structures to be selected as a valid VTScada tag address. However, none of the standard VTScada tags will extract data from within those structures. Therefore, be sure to reference the actual element of the structure you require when configuring VTScada tags.

Rockwell Address Select dialog

The Rockwell address assist tool is available when VTScada is able to query the device.

Type Filter (Root only)

Limits the tags shown to:

  • All
  • Bool (Boolean)
  • SINT (small integer)
  • INT (integer)
  • DINT (double integer)
  • REAL (floating point)
  • DWORD (double word)
  • LINT (long integer)
  • STRUCTURE
  • ARRAY

Name Filter

Any user-specified filter to limit the display. Wildcards (*) are accepted.

Read PLC Tags

Reads the available tags from the PLC and displays the address of all that pass the two filters, into the selection area.

Selection Area (unlabeled)

After reading tags from the PLC, all that pass the two filters are displayed here for you to select from.

User Address Qualifier

Allows for the correct data type qualifier to be appended to the selected address (see Rockwell driver I/O addresses)

Use External Bit Number

Allows for address with an explicit bit number to be converted to the External Bit Number format. (see Rockwell driver I/O addresses)


Rockwell Error Codes

Some tags displayed in the Address Assist dialog may return a "Path Destination Unknown" error, if the tag's ExternalAccess attribute is not set in the PLC.

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0000 | Success
1 | 0x0001 | Connection failure
2 | 0x0002 | Resource unavailable
3 | 0x0003 | Invalid parameter value
4 | 0x0004 | Path segment error
5 | 0x0005 | Path destination unknown
6 | 0x0006 | Partial transfer
7 | 0x0007 | Connection ID is not valid
8 | 0x0008 | Service not supported
9 | 0x0009 | Invalid attribute value
10 | 0x000A | Attribute list error
11 | 0x000B | Already in requested mode/state
12 | 0x000C | Object state conflict
13 | 0x000D | Object already exists
14 | 0x000E | Attribute not settable
15 | 0x000F | Privilege violation
16 | 0x0010 | Device state conflict
17 | 0x0011 | Reply data too large
18 | 0x0012 | Fragmentation of a primitive value
19 | 0x0013 | Not enough data
20 | 0x0014 | Attribute not supported
21 | 0x0015 | Too Much Data
22 | 0x0016 | Object does not exist
23 | 0x0017 | Service fragmentation sequence not in progress
24 | 0x0018 | No stored attribute data
25 | 0x0019 | Store operation failure
26 | 0x001A | Routing failure: request packet too large
27 | 0x001B | Routing failure: response packet too large
28 | 0x001C | Missing attribute list entry data
29 | 0x001D | Invalid attribute value list
30 | 0x001E | Embedded service error
31 | 0x001F | Vendor specific error
32 | 0x0020 | Invalid parameter
33 | 0x0021 | Write-once value or medium already written
34 | 0x0022 | Invalid reply received
37 | 0x0025 | Key failure in path
38 | 0x0026 | Path size invalid
39 | 0x0027 | Unexpected attribute in list
40 | 0x0028 | Invalid Member ID
41 | 0x0029 | Member not settable
42 | 0x002A | Group 2 only server general failure
43 | 0x002B | Unknown Modbus error
44 | 0x002C | Attribute not gettable
208 - 255 | 0x00D0 - 0x00FF | Unknown object-specific error
256 | 0x0100 | FO: Connection in use or duplicate Forward Open
259 | 0x0103 | FO: Transport class and trigger combination not supported
262 | 0x0106 | FO: Ownership conflict
263 | 0x0107 | FO: Target connection not found
264 | 0x0108 | FO: Invalid network connection parameter
265 | 0x0109 | FO: Invalid connection size
272 | 0x0110 | FO: Target for connection not configured
273 | 0x0111 | FO: RPI not supported
274 | 0x0112 | FO: RPI value(s) not acceptable
275 | 0x0113 | FO: Out of connections
276 | 0x0114 | FO: Vendor ID or product code mismatch
277 | 0x0115 | FO: Device type mismatch
278 | 0x0116 | FO: Revision mismatch
279 | 0x0117 | FO: Invalid produced or consumed application path
280 | 0x0118 | FO: Invalid or inconsistent configuration application path
281 | 0x0119 | FO: Non-listen only connection not opened
282 | 0x011A | FO: Target object out of connections
283 | 0x011B | FO: RPI is smaller than the production inhibit time
284 | 0x011C | FO: Transport class not supported
285 | 0x011D | FO: Production trigger not supported
286 | 0x011E | FO: Direction not supported
287 | 0x011F | FO: Invalid O->T Fixed/Variable
288 | 0x0120 | FO: Invalid T->O Fixed/Variable
289 | 0x0121 | FO: Invalid O->T Priority
290 | 0x0122 | FO: Invalid T->O Priority
291 | 0x0123 | FO: Invalid O->T connection type
292 | 0x0124 | FO: Invalid T->O connection type
293 | 0x0125 | FO: Invalid O->T redundant owner
294 | 0x0126 | FO: Invalid configuration size
295 | 0x0127 | FO: Invalid O->T size
296 | 0x0128 | FO: Invalid T->O size
297 | 0x0129 | FO: Invalid configuration application path
298 | 0x012A | FO: Invalid consuming application path
299 | 0x012B | FO: Invalid producing application path
300 | 0x012C | FO: Configuration symbol does not exist
301 | 0x012D | FO: Consuming symbol does not exist
302 | 0x012E | FO: Producing symbol does not exist
303 | 0x012F | FO: Inconsistent application path combination
304 | 0x0130 | FO: Inconsistent consume data format
305 | 0x0131 | FO: Inconsistent produce data format
306 | 0x0132 | FO: NULL ForwardOpen not supported
515 | 0x0203 | FO: Connection timed out
516 | 0x0204 | Unconnected request timed out
517 | 0x0205 | Parameter error in unconnected request
518 | 0x0206 | Message too large for UnconnectedSend
519 | 0x0207 | FO: Unconnected acknowledged without reply
520 | 0x0208 | This service requires a connection
769 | 0x0301 | FO: No buffer memory available
770 | 0x0302 | FO: Network bandwidth not available for data
771 | 0x0303 | FO: No consumed connection ID filter available
772 | 0x0304 | FO: Not configured to send scheduled priority data
773 | 0x0305 | FO: Schedule signature mismatch
774 | 0x0306 | FO: Schedule signature validation not possible
785 | 0x0311 | FO: Port not available
786 | 0x0312 | FO: Link address not valid
789 | 0x0315 | FO: Invalid segment in connection path
790 | 0x0316 | FO: ForwardClose connection path mismatch
791 | 0x0317 | FO: Scheduling not specified
792 | 0x0318 | FO: Link address to self invalid
793 | 0x0319 | FO: Secondary resources unavailable
794 | 0x031A | FO: Rack connection already established
795 | 0x031B | FO: Module connection already established
796 | 0x031C | FO: Miscellaneous
797 | 0x031D | FO: Redundant connection mismatch
798 | 0x031E | FO: No more user configurable link consumer resources available in the producing module
799 | 0x031F | FO: No more user configurable link consumer resources configured in the producing module
2048 | 0x0800 | FO: Network link offline
2049 | 0x0801 | FO: Incompatible Multicast RPI
2050 | 0x0802 | FO: Invalid Safety Connection Size
2051 | 0x0803 | FO: Invalid Safety Connection Format
2052 | 0x0804 | FO: Invalid Time Correction Connection Parameters
2053 | 0x0805 | FO: Invalid Ping Interval EPI Multiplier
2054 | 0x0806 | FO: Time Coordination Msg Min Multiplier
2055 | 0x0807 | FO: Network Time Expectation Multiplier
2056 | 0x0808 | FO: Timeout Multiplier
2057 | 0x0809 | FO: Invalid Max Consumer Number
2058 | 0x080A | FO: Invalid CPCRC
2059 | 0x080B | FO: Time Correction Connection ID Invalid
2060 | 0x080C | FO: SCID Mismatch
2061 | 0x080D | FO: TUNID not set
2062 | 0x080E | FO: TUNID Mismatch
2063 | 0x080F | FO: Configuration operation not allowed
2064 | 0x0810 | FO: No target application data available
2065 | 0x0811 | FO: No originator application data available
2066 | 0x0812 | FO: Node address has changed since the network was scheduled
2067 | 0x0813 | FO: Not configured for off-subnet multicast
2068 | 0x0814 | FO: Invalid produce/consume data format
3840 | 0x0F00 | Port Not Defined
3841 | 0x0F01 | Port Failed To Connect
3842 | 0x0F02 | Port Lost Connection
3843 | 0x0F03 | Serial Port Settings Out of Range
3844 | 0x0F04 | Serial Port Already In Use or Not Available
3845 | 0x0F05 | Serial Port Access Denied
3846 | 0x0F06 | Serial Port General Failure
3847 | 0x0F07 | Serial Port Invalid Parameter
3848 | 0x0F08 | Port Not Connected
3849 | 0x0F09 | Port Unknown Error
3890 | 0x0F32 | The Current Operation has Timed Out
3891 | 0x0F33 | Invalid EtherNet/IP Encapsulation Session
3892 | 0x0F34 | Forward Open Command Failed
3893 | 0x0F35 | Lost CIP Connection
3894 | 0x0F36 | CIP Connection Timeout
3895 | 0x0F37 | No More CIP connections Allowed
3896 | 0x0F38 | Invalid Command Buffer
3897 | 0x0F39 | Receiver Out of Sync
3898 | 0x0F3A | Command Response Mismatch
3899 | 0x0F3B | Invalid data response
3900 | 0x0F3C | Unknown data type
Error code (Decimal) | Error code (Hex) | Meaning
4097 | 0x1001 | Invalid Error Code
4099 | 0x1003 | PLC Tag Upload process interrupted
4100 | 0x1004 | Invalid address
4112 | 0x1010 | EOT Received Before Response
4113 | 0x1011 | Message TNS Codes Did Not Match
4114 | 0x1012 | NAK Response from Device
4115 | 0x1013 | Message Received From Device With No ACK
4116 | 0x1014 | Responding Station Address Does Not Match Sending Station Address
4117 | 0x1015 | Bad BCC or CRC Received
4353 | 0x1101 | Destination Node Out of Buffer Space
4354 | 0x1102 | Remote Node Does Not Acknowledge Command Message
4355 | 0x1103 | Duplicate Token Header Detected
4356 | 0x1104 | Local Port (DH or DH+) is Disconnected
4358 | 0x1106 | Duplicate DH Address
4359 | 0x1107 | Station Is Offline
4360 | 0x1108 | Hardware Fault
4368 | 0x1110 | Illegal Command or Format
4384 | 0x1120 | Remote Node (PLC) Has a Problem & Will Not Communicate
4400 | 0x1130 | Remote Node (PLC) is Missing, Disconnected, or Shut Down
4416 | 0x1140 | Remote Node (PLC) Could Not Complete Function - Hardware Fault
4432 | 0x1150 | Addressing Problem or Memory Protect Rungs
4448 | 0x1160 | Function Disallowed due to Command Protection Selection
4464 | 0x1170 | Processor is in Program Mode
4480 | 0x1180 | Compatibility Mode File Missing or Communication Zone Problems
4496 | 0x1190 | Remote Node (PLC) Cannot Buffer Command
4528 | 0x11B0 | Remote Node (PLC) Problem due to Download
4609 | 0x1201 | Error Converting Block Address
4610 | 0x1202 | Incorrect Address Format in Protocol
4612 | 0x1204 | Symbol Not Found
4613 | 0x1205 | Symbol is of Improper Format
4614 | 0x1206 | Address Doesn't Point to Something Usable
4615 | 0x1207 | File is Wrong Size
4616 | 0x1208 | Can't Complete Request, Situation has Changed Since Start of Cmd
4617 | 0x1209 | File is Too Large
4618 | 0x120A | Trying to Read/Write Past the End of the File
4619 | 0x120B | Access Denied, Improper Privilege
4620 | 0x120C | Condition Cannot be Generated - Resource Not Available
4621 | 0x120D | Condition Cannot be Generated - Resource Already Available
4625 | 0x1211 | Illegal Data Type
4626 | 0x1212 | Bad Parameter
4627 | 0x1213 | Address Reference Exists to Deleted Data Table
5127 | 0x1407 | Could Not Read Error Code from Response Message
8192 | 0x2000 | General Error: Tag access
8452 | 0x2104 | General Error: Offset is beyond end of the requested tag
8453 | 0x2105 | General Error: Access beyond end of the requested tag
8455 | 0x2107 | General Error: Data type used in request does not match the data type of the target tag


ScanCom Driver Tag

The ScanCom protocol is a derivation of the ADEPT protocol. It is used primarily to communicate with Barton Scanner devices.

The protocol is designed with 7-layers, for serial communication.

  • ScanCom-7 Application
    (VTScada in this case. Holds commands and responses)
  • ScanCom-6 Presentation
    (ADEPT 4.0 only, contains measuring units – Imperial / Metric)
  • ScanCom-5 Session
    (Similar to ScanCom-7 Application but applies to login / logout. A message can contain ScanCom-7 plus 6, or ScanCom-5 but not both)
  • ScanCom-4 Transport
    (Used to break up large messages into multiple packets)
  • ScanCom-3 Network
    (Not implemented)
  • ScanCom-2 Data Link Control
    (Packet sequencing, CRC. Derived from another protocol called HDLC)
  • ScanCom-1 Physical
    (Serial Port)

In VTScada, layers 5-7 are treated as a single-layer and layers 1 and 3 are ignored. The maximum packet size across layers 2 through 7 is 256 bytes.

Layers 3-7 use little-endian byte ordering but layer 2 uses big-endian byte ordering.

Related information:

Best Practices for Tags

Closed ScanCom Driver properties - ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

ScanCom Driver properties - Communications tab

Port

The ScanCom driver uses a serial protocol. If a serial port is not available on your server, use a Serial-to-Ethernet device with a TCP/IP port.

Timeout

The length of time (in seconds) that the driver should wait for a reply from the device. Defaults to 10 seconds.

Retry Delay

The Retry Delay field enables you to specify the amount of time (in seconds or fractions of a second) that the driver will wait between attempts to repeat a transmission of data if the previous attempt(s) have failed.

By default, the Retry Delay field is set to 0 (indicating that there should be no delay between retry attempts).

RTS Key Off Delay

The RTS Key Off Delay field represents the amount of time (in seconds) that this ScanCom driver will wait before dropping RTS at the end of a data transmission.

ADEPTv3 Logout Delay

Applies only when the ADEPT version is set to v3.4. Sets the delay (in seconds) the session will remain idle before automatically sending a logout message and ending the session.

(ADEPT v4.0 will always log you out automatically after a session ends and does not use this parameter.)

RR Reply Delay (ms)

The delay to wait after receiving a Receiver Ready acknowledgment before sending a Receiver Ready reply to the Scannner.

RNR Reply Delay (s)

The delay to wait after receiving a Receiver Not Ready acknowledgment before sending a Receiver Ready reply to the Scanner.

Max RR Replies (Waiting for ACK) and

Max RR Replies (Waiting for Response)

After sending a request to a device, several Receiver Ready messages may be exchanged while awaiting acknowledgment that the request was received (Waiting for ACK). Defaults to 1.

Similarly, several more may be exchanged while waiting for the reply (Waiting for Response). Defaults to 3.

These limits prevent an infinite number of such messages being exchanged. If the limits are exceeded error code 0x100C will be generated. If this error is generated frequently the Max RR Replies parameters should likely be increased.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

ADEPT Version

Specify 3.4 or 4.0 according to your device.

ScanCom Driver properties - Addresses tab

VTScada Application Address

The ADEPT-7 application address for VTScada. Defaults to 4352.

Scanner Application Address

The ADEPT-7 application address for the scanner. Defaults to 1100.

VTScada Device ID

The address at the ADEPT-4 Transport Layer for VTScada. Defaults to 1.

Scanner Device ID

The address at the ADEPT-4 Transport Layer for the scanner. Defaults to 1100.

VTScada Physical Address

The address at the ADEPT-4 Data Link Layer for VTScada. No default

Scanner Physical Address

The address at the ADEPT-4 Data Link Layer for the scanner. No default

ScanCom Driver properties - Session tab

Session Name

Effectively, an encrypted version of the user name

Password

A password for the connection. The text will not be displayed. The password is stored in an encrypted form.

RTU Node Name

Upon a successful login request the Scanner will reply with its name as a text string. This field lets us ensure we are connected to the right Scanner.

Device Clock Time Zone

The default is to use the server's time zone. Select an alternative time zone if appropriate.

Max Queue Records to Return

The maximum number of queue records to be returned in a GETN response. A value of "0" means "no limit", or "send them all".

Units

Choose between US and SI.

Comms Trace: Packet Building and Parsing,

Comms Trace: Transmit and Receive,

Comms Trace: Session Manager,

These three parameters control what (if any) trace information should be logged. Look for the file in the folder Data\Trace Files of your application. The filename will take the form, <Name of Driver Tag>-YYYY-MM-DD.LOG For example: DemoScanCom-2023-06-08.LOG

Ignore RTU-Generated Errors

The Scanner provides return codes in its replies. By default the ScanCom Driver counts any non-zero return codes as driver errors, ending any operation in progress. This can be problematic in certain circumstances, such as if the Scanner returns an error code as part of a login transaction. For these occasions, the Ignore RTU-Generated Errors parameter allows us to disregard the Scanner return codes in order to connect to the device for diagnostic or corrective purposes. Note that the Scanner return codes provide important information, and this setting should not be enabled for extended periods of time.

Closed ScanCom Driver Widgets

The following widgets are available to display information about your ScanCom Driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

ScanCom Driver Communication Messages Dialog

ScanCom Driver Statistics Dialog

Equipment / Status Color Indicator

Indicator Light Widget

Multi-Color Widget

Multi-Text Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


ScanCom Driver I/O Addressing

An Address Select dialog is provided to help you build valid I/O addresses for the data you want to monitor.

The fields, New Address and Previous Address are not user-editable. These display the addresses built using selection tools within this dialog.

Item / Structure / Queue

Item addresses are for reading current values. VTScada will group the reads by common data types. (DOUBLEs in one read, ULONG in another, etc.)

Structure addresses will send back all the data members of that structure in a reply. This is used only for "frozen" reads, where the RTU takes a snapshot of the structure's contents for subsequent retrieval. This might be used for information such as flow calculations where you want to be sure none of the data members are partway through a calculation. Structures should not be used when reading only one data point. Use only when there is value in reading "frozen" data.

Queue addresses are used for accessing history data. (Daily, hourly, or from a data log.) Daily and Hourly Queue records have a predefined format, while Data Log Queues are linked to data logger accessories, which could (presumably) access any item's read address.

Item Address Format

Item addresses take the general format:

Datatype|ItemIdentifier:Key

Supported data types include BYTE, SHORT, CHAR, SINGLE, LONG, DOUBLE, TIMESTAMP, most with unsigned versions (UBYTE, etc.) CHAR data types should be followed by the fixed-length of the item to read, i.e. CHAR16 or CHAR24.

The item identifier is a long word (eight character hexadecimal code). Refer to the ScanCom documentation for lists of item identifiers.

Key usage varies according to the value being accessed. For example, when querying hardware the key is the hardware slot. When querying Flow Run Data Manager data, the key is the flow run number.

The Address Select dialog organizes Items into groups, each of which has sub-groups. For example, groups include "System", "Peripheral", and "Accessory". Within the "Peripheral" group, you will find a subgroup of various types of device. ( 1=MVX Peripheral Device, 2=Daniel’s Ultrasonic Peripheral Device, etc.)

Addresses in the selection dialog are not filtered for the type of I/O tag you are configuring. All data types are shown regardless of whether you are creating an analog or digital I/O tag. Select with care.

Structure Address Format

Structure addresses take the general form:

SStructIdentifier:Key|ItemIdentifier:Key

The "S" identifies this as a structure address. The vertical bar (pipe symbol) separates the structure identifier from the item identifier. For any given group in the address selection dialog, StructIdentifier will be the same for every object within that group. Only ItemIdentifier changes as you finish the address selection.

Queue Address Format

Queue addresses should be used only for the History Address of an I/O tag, not for the Read Address.

Queue addresses take the general form:

QQueueIdentifier:Key|ItemIdentifier:Key

This is the same as the Structure address format, except with a leading Q instead of an S.

Note that with queue type, Data Log, QueueIdentifier may have a key that differs from ItemIdentifier.


ScanCom Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0000 | No Error
4097 | 0x1001 | XmitRcv: Bad Parameters
4098 | 0x1002 | XmitRcv: Function Code Mismatch
4099 | 0x1003 | XmitRcv: Transaction Count Mismatch
4100 | 0x1004 | XmitRcv: Transport Sequence Mismatch
4101 | 0x1005 | XmitRcv: Frame Reject
4102 | 0x1006 | XmitRcv: Scanner Disconnected
4103 | 0x1007 | XmitRcv: Unsupported HDLC Code
4104 | 0x1008 | XmitRcv: Response Timeout
4105 | 0x1009 | XmitRcv: Echo Timeout
4106 | 0x100A | XmitRcv: DLC Sequence Mismatch
4107 | 0x100B | XmitRcv: Transport Missing Initial Frame of Multi-Frame Message
4108 | 0x100C | XmitRcv: RTU is communicating but not answering request
4353 | 0x1101 | BuildPacket: Bad Parameters
4609 | 0x1201 | BuildApplicationLayer: Bad Parameters
5121 | 0x1401 | BuildTransportLayer: Bad Parameters
5377 | 0x1501 | BuildPresentationLayer: Bad Parameters
5633 | 0x1601 | BuildDLCLayer: Bad Parameters
5889 | 0x1701 | ParsePacket: Bad Parameters
6145 | 0x1801 | ParseApplicationLayer: Bad Parameters
6401 | 0x1901 | ParseTransportLayer: Bad Parameters
6657 | 0x1A01 | ParsePresentationLayer: Bad Parameters
6658 | 0x1A02 | ParsePresentationLayer: Unknown Device Word
6659 | 0x1A03 | ParsePresentationLayer: Missing Header
6913 | 0x1B01 | ParseDLCLayer: Bad Parameters
6914 | 0x1B02 | ParseDLCLayer: Bad CRC Check
6915 | 0x1B03 | ParseDLCLayer: Unknown ADLC Type
8193 | 0x2001 | BuildGETI: Bad Parameters
8449 | 0x2101 | BuildGETN: Bad Parameters
8705 | 0x2201 | BuildLOGI: Bad Parameters
8961 | 0x2301 | BuildPUTI: Bad Parameters
9217 | 0x2401 | BuildScanComAddr: Bad Parameters
9729 | 0x2601 | BuildVTSAddr: Bad Parameters
16385 | 0x4001 | ParseGETF: Bad Parameters
16386 | 0x4002 | ParseGETF: Unexpected Attribute Mask
16387 | 0x4003 | ParseGETF: Unknown DataID in Structure
16641 | 0x4101 | ParseGETI: Bad Parameters
16642 | 0x4102 | ParseGETI: Unexpected Attribute Mask
16897 | 0x4201 | ParseGETN: Bad Parameters
17153 | 0x4301 | ParseLOGI: Bad Parameters
17409 | 0x4401 | ParsePUTI: Bad Parameters
17410 | 0x4402 | ParsePUTI: Unexpected Attribute Mask
17665 | 0x4501 | ParseSHOQ: Bad Parameters
18177 | 0x4701 | VTSGetAddr: Illegal Address
18178 | 0x4702 | VTSGetAddr: Data Type Not Supported
18179 | 0x4703 | VTSGetAddr: Indeterminate Prefix
18180 | 0x4704 | VTSGetAddr: Prefix Mismatch
18689 | 0x4901 | VTSWrite: Partial Failure of Multiple-Tag Write
20481 | 0x5001 | SessionManager: Bad Node Name
32800 | 0x8020 | SCANNER: DLC Message type error
32801 | 0x8021 | SCANNER: DLC Message length error
32848 | 0x8050 | SCANNER: No session active
32849 | 0x8051 | SCANNER: Unit busy (User active with another A4 Device)
32850 | 0x8052 | SCANNER: Login rejected
32851 | 0x8053 | SCANNER: Set Access rejected
32852 | 0x8054 | SCANNER: Read access denied
32853 | 0x8055 | SCANNER: Write access denied
32854 | 0x8056 | SCANNER: Password change rejected
32855 | 0x8057 | SCANNER: Write access denied: change log full
32856 | 0x8058 | SCANNER: Write access denied: another user active
32857 | 0x8059 | SCANNER: Access denied: superboot mode active
32858 | 0x805A | SCANNER: Emergency login: key is in return string
32859 | 0x805B | SCANNER: Write access denied: cfg lock switch on
32860 | 0x805C | SCANNER: Session is already logged in
32861 | 0x805D | SCANNER: Maximum number of sessions reached
32862 | 0x805E | SCANNER: Session in use (trusted access rejected)
32882 | 0x8072 | SCANNER: Function not found
32883 | 0x8073 | SCANNER: Function not supported
32895 | 0x807F | SCANNER: Application busy
32928 | 0x80A0 | SCANNER: Structure ID not defined
32929 | 0x80A1 | SCANNER: Owner ID or key not found
32930 | 0x80A2 | SCANNER: No such structure occurrence
32943 | 0x80AF | SCANNER: Specified attributes not supported
32960 | 0x80C0 | SCANNER: Invalid structure definition
32975 | 0x80CF | SCANNER: Structure was redefined
32993 | 0x80E1 | SCANNER: Structure does not support PUTS
32994 | 0x80E2 | SCANNER: Supplied data does not fit structure
32995 | 0x80E3 | SCANNER: Supplied attributes not updateable
32996 | 0x80E4 | SCANNER: PUTS failed due to potential change log full
33024 | 0x8100 | SCANNER: Invalid time/date in FREE
33025 | 0x8101 | SCANNER: Structure is not frozen
33026 | 0x8102 | SCANNER: Delayed snapshots not supported
33027 | 0x8103 | SCANNER: Snapshot buffer overflow
33038 | 0x810E | SCANNER: Some attributes not snapshotted
33039 | 0x810F | SCANNER: Previous snapshot overwritten
33040 | 0x8110 | SCANNER: No such snapshot in GETF call
33055 | 0x811F | SCANNER: Some attributes not included
33056 | 0x8120 | SCANNER: No items exist
33057 | 0x8121 | SCANNER: Identifier attribute required
33058 | 0x8122 | SCANNER: Too many elements in item list
33059 | 0x8123 | SCANNER: Bad data value given in PUT
33060 | 0x8124 | SCANNER: Units are not specified correctly.
33061 | 0x8125 | SCANNER: Input value default used (live values only)
33062 | 0x8126 | SCANNER: Value out of range low (live values only)
33063 | 0x8127 | SCANNER: Value out of range high (live values only)
33064 | 0x8128 | SCANNER: Value out of range cut-off (live DP values only)
33069 | 0x812D | SCANNER: DataID not found
33070 | 0x812E | SCANNER: DataID exists but is not in use
33071 | 0x812F | SCANNER: DataID is valid but is not supported
33104 | 0x8150 | SCANNER: Unknown queueID specified
33105 | 0x8151 | SCANNER: Bad queue key specified
33106 | 0x8152 | SCANNER: No such queue occurrence
33107 | 0x8153 | SCANNER: Incorrect mode use in GETN
33108 | 0x8154 | SCANNER: Incorrect start/end time use in GETN
33117 | 0x815D | SCANNER: No new queue records found
33118 | 0x815E | SCANNER: Queue record not found
33119 | 0x815F | SCANNER: No record count supplied in response
33136 | 0x8170 | SCANNER: Non-specific creation error
33137 | 0x8171 | SCANNER: Out of memory
33138 | 0x8172 | SCANNER: Out of RAM memory
33139 | 0x8173 | SCANNER: Out of non-volatile (NVRAM) memory
33152 | 0x8180 | SCANNER: Hardware communication error
33168 | 0x8190 | SCANNER: All Flowrun values associated with a Station are not readable
33169 | 0x8191 | SCANNER: All Flowrun values associated with a Station are not writeable


Siemens S7 Driver

Not counted towards your tag license limit.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

Siemens S7 drivers will commonly connect to TCP on port # 102, although variations may be found.

For S7-300 and S7-400, the CPU will normally be at slot 2, but for the S7-1200 PLC system the CPU will always be at slot 1, which is different from the default setting.

Reference Notes:

Communication with the PLC is via ISO over TCP.

This driver has the ability to save the last value written to each output tag, and to rewrite those values, either automatically when lost communications are restored, or manually by the press of a button. Carefully review the information in the Options tab to decide whether this feature should be used in your application. If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

When this driver is used in combination with a TCP/IP tag, the standard TCP port is 102.

Required PLC Settings

For both of the following tasks, use the PLC manufacturer’s programming software, not VTScada.

  • If using the newer S7 1200 PLCs (possibly others as well), you must select the "Permit access with PUT/GET communication from remote partner" option in the PLC CPU properties.
  • When addressing tags using data blocks, you must deselect the "Optimized block access" option on the data blocks and program blocks in order to determine the byte offset of the individual variables in the blocks.

Related information:

Siemens S7 Driver I/O Addressing

Siemens Error Codes

Best Practices for Tags

Closed Siemens S7 Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Siemens S7 Driver properties Options tab

The Options tab for the Siemens S7 driver tag properties folder consists of attributes used to identify and establish a connection to the control device to be associated with this driver.

Siemens tag options tab

PLC Type

Address parsing differs for the S7-200 device. For all other S7 devices, choose the option, "other".

Priority

Two priority levels are available: OP Mode (low priority) and PG Mode (high priority). Note that there may be a limit on the number of PG mode connections which are available.

Rack and Slot

Specify the CPU position. These can be determined from the hardware configuration. Note that these fields do not apply to the S7-200 CPU.

CP Type

If you are connecting to a Siemens PLC through a communications processor, select it here, otherwise select None.

Options include: CP-243, CP-343 and CP-443.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Siemens S7 Driver properties Serial tab

The Serial tab for the Siemens S7 driver tag properties folder consists of attributes used to identify and establish a connection to the control device to be associated with this driver.

Siemens tag serial tag

Port

Since the only protocol available is ISO over TCP, you should configure and select a TCP Port.

Time-Out Limit and Retries

A half second time out limit with one retry is recommended as a reasonable value for a Siemens PLC.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Protocol Timeout

Timeout period, after which a lack of protocol traffic is considered an error. Default: 30 seconds.

Initial Max Packet Length

Maximum PG/OP packet length used for initial communication with the PLC. This value will not be used after length negotiation with the PLC is complete. Default: 240.

Max. Outstanding Requests

Defines the maximum number of PG/OP packets that may be outstanding. Default: 1 outstanding request.

Max Items Per Request

Defines the maximum number of item addresses to include in a request. Default: 18 items.

Max Requests per Semaphore

Defines the maximum number of requests that can be sent in one semaphore acquisition. Default: 100 requests.

Max Time per Semaphore

Defines the maximum amount of time to hold the semaphore. Default: 1 second.

Closed Siemens S7 Driver Tag Widgets

The following widgets are available to display information about your application’s Siemens S7 driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Siemens S7 Driver I/O Addressing

The syntax of the S7 memory addresses and the legal ranges for each of the supported PLCs are as follows:

The syntax for memory addresses takes one of 3 forms:

  • [Area][Byte Address].[Bit Index]
  • [Area][Data Size: B, W or D][Starting Byte Address]
  • [Data Block Number DBx].DB[Data Size: B, W, X, or D][Starting Byte Address]

Memory Area | Area Prefix | Notes
Input | E (or I) |
Output | A (or Q) |
Memory | M |
Special Memory | S | S7-200 ONLY
Variable Storage | V | S7-200 ONLY
Timer | T |
Counter | Z (or C) |
Data Blocks | DBx DBy |
Peripheral Input | PE (or PI) |
Peripheral Output | PA (or PQ) |
Analog Input | AE (or AI) | S7-200 ONLY
Analog Output | AA (or AQ) | S7-200 ONLY
Local | L |
Flags | F | Not supported in S7-200

Notes and Examples:

Float values are the most common specifier used. To correctly address a float value you must include the correct area prefix, data size(unsigned double word) and starting byte number for the variable within the block.
For example: If the memory area is "Memory", the starting byte address is 30, to read a float value the address would be

MD30/FLOAT

Where
M = Memory (Area prefix for Memory Area)
D = Data Size(ie. unsigned double word as required for a float value)
30 = Byte Address
/FLOAT = specifies a float value

The "PLC Type" selection on the Options tab is used only to determine what types of addresses the driver allows us to request, remembering that the driver really only differentiates between S7 200 & all other S7 types.

Typically, most information is read from and written to data blocks (type DB). These are the individual memory areas in the PLC that represent variables of the individual function block instances in the PLC program, along with the global data for the program.

Addresses of DB type values in the PLC will follow the format of the PLC program with which VTScada is communicating. Note that the addressing format for accessing both global data blocks and instance data blocks is the same with only the data block number and location within that block changing.

To access a variable within a data block, you must know a minimum of three things about it:

  • The data block number.
  • The data type of the variable within the data block.
  • The starting byte number within the data block for the variable you want to access.

Putting these three elements together, the format of a data block address becomes:

DBx.DByz

Where:

  • x is the data block number
  • y is the data type and may be one of the following four values:
    • X – bit
    • B – unsigned byte
    • W – unsigned word (2 bytes)
    • D – unsigned double word (4 bytes)
  • z is the starting byte number for the variable within the block. The starting byte number can be determined using the manufacturers supplied PLC programming software to examine the contents of the data blocks.

For example, if you have a data block #440 with a integer value that starts at the first byte of the block, you would address this variable as:

DB440.DBW0

Where DB is the area prefix, 440 is the byte address, W indicates an unsigned word and 0 is the starting byte address.

For a double word starting at byte 23 in the same block, you would use:

DB440.DBD23

Where D indicates unsigned double word and 23 is the starting byte address.

Alternatively, if you have a floating point value located at byte 45 of data block #10, you can address this as:

DB10.DBD45/FLOAT

Note that in this case VTScada will initially read the data as a double word (DBD45) and then convert it to a float using the /FLOAT qualifier.

This same methodology can also be used to change the unsigned short and long integers read from the PLC into signed using the qualifiers /SWORD and /SDWORD respectively. For example, to read a signed short integer from block #5 starting at byte #21, use address:

DB5.DBW21/SWORD

When reading bit data types, an additional address component to specify the bit number must also be added to the address in the form:

DBx.DBXz.b

Where b defines the bit number to read from byte z.

For example, to read bit 5 from byte 41 of data block 109, use address:

DB109.DBX41.5

This formula applies to all memory areas. The following are also valid addresses:

Z440.DBW0

M10.DBD45/FLOAT

S5.DBW21/SWORD


Siemens Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
5 | 0x005 | Address Out Of Range
10 | 0x00A | Data Item Not Available
133 | 0x085 | PG/OP Response Exceeds Maximum Length
256 | 0x100 | Invalid Address
257 | 0x101 | Communications Port Error
258 | 0x102 | Invalid Response from PLC
259 | 0x103 | Invalid Read Request
260 | 0x104 | Invalid Write Request
261 | 0x105 | Communications Protocol Error
262 | 0x106 | Connection Timed Out
263 | 0x107 | Connection Unexpectedly Lost
33028 | 0x8104 | Function Not Supported - Check PLC Settings


SNMP Driver

Not counted towards your tag license limit.

The SNMP driver can be used to communicate with any device that uses the Simple Network Management Protocol (versions 1, 2c or 3).

Look for SNMP configuration in the Other Tab of the Edit Properties Page. There, the SNMP version must be set to v3 for all options to be displayed.

Driver Errors: To learn more about the cause of an error condition, refer to the Driver Summary Report and the Driver Error Report, both of which are available in the Reports page. The Show Stats button will also provide current and last error messages: Show Statistics Button Widget

SNMP data types influence your selection of I/O tag:

SNMP supports 12 data types. These are passed directly to the I/O tag, where further processing may be required.

  • SNMP data types: Integer32, Unsigned32, Gauge32, Counter32, Counter64 and TimeTicks can be used with numeric tag types.
  • SNMP data types: Integer(Enumerated), Octet String, Object Identifier, IpAddress, Opaque and Bits should be read in with a String I/O tag, with additional processing done using a Calculation tag as required.

SNMP drivers will commonly connect to UDP on port number 161 or 162, although variations may be found.

VTScada supports only ASCII-encoded MIB files.

Reference Notes:

I/O tags that are configured to use an SNMP driver will have an address selection feature. A button labeled "..." will be added beside the Address field of the I/O tab. Clicking this will open an SNMP Address Select window (Address Assist / Address Select), from which you can choose the correct Object Identifier (OID) address.

The SNMP driver requires more configuration than other drivers. You will need to obtain the MIB library for your device from the manufacturer and you will need to tell VTScada where to find this information. See SNMP Addressing for details and configuration steps. (If the user knows the OID there is no need for a MIB.)

SNMP v3 Security

Legacy applications built prior to the release of VTScada version 12.1 used application properties to configure the authentication and privacy settings. For backward compatibility, you may continue to use these properties, but for new development you are advised to use the configuration properties available in each SNMP driver tag. Both are describe here.

Those not familiar with SNMP v3 security configuration should read SNMP v3 Security Notes before continuing.

For legacy applications relying on properties:

When using version 3, authentication may be done using either HMAC-SHA-96 or the MD5 protocol. Encryption uses either DES or 128-bit AES(1). Choice of protocol is done using the following application properties, found in Settings.Dynamic:

    SNMPv3DefaultUserAuthProtocol (Set "0" for MD5 and "1" for SHA-1)

    SNMPv3DefaultUserPrivProtocol (Set "0" for DES and 1 for AES128)

(1) If circumstances require that multiple users or security levels be configured, then multiple SNMP drivers can be instantiated. In legacy applications, although one could specify a v3 username in every driver, all drivers share the same pass phrases and authentication / security protocols as specified in the application configuration properties

The following security levels are supported: NoAuthNoPriv, AuthNoPriv, and AuthPriv. There can be only one level per driver instance. When SNMP version 3 is selected, the contents of the Agent tab of the configuration folder change to allow selection of the security level and parameters for the User name and Context Name. The following custom privileges are used to store the configuration: SNMPv3DefaultUserAuthKey, SNMPv3DefaultUserAuthProtocol, SNMPv3DefaultUserPrivKey, SNMPv3DefaultUserPrivProtocol.

For new application development:

New applications should not rely on the parameters just described. Instead, configure each SNMP driver to specify up to three sets of SNMP v3 credentials as required. Security levels can be set to None, Authentication Only, or Authentication and Encryption.

Authentication requires a password and a choice of MD5 or SHA-1 for the protocol.

Encryption requires a privacy password and a choice of DES, AES-128, 3DES or AES-256 for the protocol. Note that DES and AES-128 are both older protocols and may not provide reliable security.

SNMPDriverLegacyV3Notifications. In legacy applications, notifications carrying different usernames were accepted if they had the same credentials. For example, if you had specified three users: User1, User2, User3, then all these users would have the same credentials (the legacy credentials) and were all represented by a default username in the USM data base. Traps carrying any of the three user names were accepted. But, because every SNMP driver now has its own sets of separate credentials, the legacy behavior does not apply unless this property is set.

SNMPDriverOctetStringMaxSize. Specifies the expected maximum size in bytes of OCTETSTRING data to be read by any SNMP driver in the application. This will allow multiple IO tags to be coalesced in a single GET request. If this property is left invalid then no OCTETSTRING GET requests will be coalesced.

Cautions:

  • Using the same user name but different passwords for both GET_SET and TRAP in the same SNMP driver, or different SNMP drivers that connect to the same remote agent, may conflict and lead to unpredictable behavior.
  • INFORMs credentials set in any driver might conflict with VTScada’s SNMPAgent GET and SET credentials and lead to unpredictable behavior.
  • INFORMs credentials set in a SNMP Agent Destination tag may conflict with GET / SET / TRAPs credentials specified in one or multiple SNMP drivers
  • If using an SNMP driver with a Driver Multiplexer, note that traps do not count towards driver communication status or RecommendAlternate behavior. The SNMP driver must have one or more polling tags attached to ensure proper behavior.
  • If your system has multiple servers, you may find it helpful to increase the value of SNMPFailoverCount, or set NoSoftDriverFailure. In some situations it is possible that when switching servers, a number of errors can occur that is sufficient to trigger Recommend Alternate.

Related information:

SNMP I/O Addressing

SNMP Error Codes

SNMP Agent Configuration

SNMP Agent Destination Tag

Many application properties relate to the SNMP driver. Refer to Communication Driver Properties

Best Practices for Tags

Closed SNMP Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

SNMP Driver properties, Communications tab

Use the Communications tab to select the port through which this driver will communicate as well as options for handling communication errors. In addition to the port parameters, this tab provides a location for you to specify the name of the SNMP group to which this driver instance will belong.

SNMP tag - communications tab

Port

Use the tag browser button to select the TCP/IP or UDP port tag to which the remote equipment is attached. The X button can use used to clear the current selection.

Maximum PDU Length (Bytes)

Use to specify the maximum length, as measured in bytes, of the Protocol Data Unit. This value is based on the smallest MTU Closed Maximum Transmission Unit along the path to the equipment and need only be changed from the default if a different value is required by the equipment with which you will be communicating.

SNMP Group

The name of a VTScada RPC service to which this driver instance will belong. Alternate RPC services need only be created if your application uses multiple servers on separate sub-nets. In most applications you should leave the default value for this field.

Time-Out Limit

In the event that a connection cannot be made, sets the number of seconds until another attempt will be made.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

SNMP Driver properties, Agent tab

Provides configuration options related to the SNMP device with which this driver will communicate.

Format for SNMP 1 and 2c.

Format for SNMP 3

SNMP Version

Select the simple network messaging protocol version that the agent is using. Supported versions include 1, 2c and 3. Defaults to 1. Selecting version 3 will cause the available configuration parameters to change as shown

(v1 & v2c) Read Community String

Used for authentication of the device. The default value of "public" should have been changed on the device in the interest of improved security.

(v1 & v2c) Read/Write Community String

Similar to the Read Community String, this value is used to authenticate an SNMP device that will be used to both read and write information. Like the former, this value should be changed on the device from the default of "public".

(v3) Username

The name required for authentication.

(v3) Context Name

A context is a collection of information accessible by an SNMP entity. A SNMP Engine may contain one or more contexts, where the default context has an empty name. Information is not constrained to a single SNMP Engine ID or context. The same information can be available via different means. A context is used to define information subsets. For example, an SNMP Engine exposed to this driver might contain multiple components, each of which implements MIB items that may have conflicting OID info. The concept of a context was introduced to avoid this ambiguity. For simple devices the default context is sufficient.

(v3) Authentication Password

The user name, authentication and privacy protocols and passwords are created and set in the equipment and provided to the user. The authentication allows the equipment to verify that it is, in fact, the privileged user who is Getting or Setting SNMP data via the SNMP driver. Privacy protocols and credentials allow encryption of the data exchanged between the driver and equipment.

(v3) Authentication Protocol

Authentication protocol to use. Choose between MD5 and SHA-1

(v3) Privacy Password

Privacy password associated with the given user name.

(v3) Privacy Protocol

Privacy protocol to use. Choose between DES, AES-128, 3DES or AES-256 (Blumenthal)

SNMP Driver properties, Traps tab

In general, it is recommended that the Allow Traps option be disabled unless explicitly required.

Used to specify the port on which the driver will listen for unsolicited (Trap) messages. The intended purpose of Traps in SNMP is to notify the network management service so that it can investigate as required. They are not intended to set data because doing so represents a weak point in security (although, many devices use Traps to do exactly that). Traps typically contain messages such as a timestamp and an event OID such as a device restart.

The port number defaults to 162. Should not match the local or the remote port number.

You may set the port number to zero (0) to prevent the SNMP driver from accessing the port. This may be useful in the case that the driver should not open a port or receive traps.

SNMP tag - traps tab

The following notes are for SNMP version 3 only:

Additional configuration options, within the Trap Data block will be enabled when SNMP v3 is in use.

When filtering for a specific SNMP user, check that the minimum security level is set as required. Note that the user/security-level/context setup on the Agent tab is for commands (Get/Set/GetBulk) and has no effect on traps.

Security levels available when SNMP v3 is in use include:

  • Accept traps with no security
  • Only accept authenticated traps.
  • Only accept authenticated and encrypted traps.

SNMP Driver properties, Informs tab

The authentication password field is enabled only when the security level is set to at least Authentication Only. The Privacy Password field is enabled only when the security level is set to Authentication and Encryption.

For authentication and privacy of Gets, Set and Traps, credentials are defined and created on the equipment side and then provided to VTScada. For Informs, the authentication and privacy credentials are created in VTScada and then provided to the equipment side.

Security levels are set within the Agent tab.

Closed SNMP Driver Tag Widgets

The following widgets are available to display information about your application’s SNMP driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget

Related information:

SNMP I/O Addressing

SNMPGetBulkDistributor Tag


SNMP v3 Security Notes

Starting from SNMPv3, an instance of a software implementation of SNMP has come to be known as an SNMP entity, where an SNMP entity consists of a single SNMP engine and one or more associated applications.

Applications may be any or all of the following:

  • Command Responder (a.k.a. Agent and is usually the host of one or more management information base)
  • Command Generator (a.k.a. Manager)
  • Notification Originator
  • Notification Receiver.

Look for SNMP configuration in the Other Tab of the Edit Properties Page. There, the SNMP version must be set to v3 for all options to be displayed.

The engine is responsible for dispatching requests and responses as well as authorizing and encrypting / decrypting those messages. SNMPv3 requires that an application be able to identify the remote SNMP engine of the remote SNMP entity uniquely, in order to retrieve or manipulate objects maintained on that entity.

The SNMP Engine ID (stored as "snmpEngineID") is a unique identifier of an engine and also of an entity. An SNMP context is a collection of management information accessible by an SNMP entity. An item of management information may exist in more than one context and an SNMP entity potentially has access to many contexts. A context is identified by the EngineID value of the entity hosting the management information (contextEngineID) and a context name that identifies the specific context (contextName).

The User-based Security Model (USM) is the most widely used security model in SNMPv3. A USM SNMP packet reserves two fields for the identification of SNMP entities. One field identifies the authoritative entity. The second field identifies the entity hosting the context to which the data belongs. Since EngineID is well defined as an entity unique identifier, it is used by USM. The USM entity's identification fields are further explained here:

  • authoritativeEngineID
    The rules for designating the authoritative engine are as follows: if the SNMP message requires a response (get, getnext, getbulk, set, or inform), the receiver of these messages is authoritative. If the message does not require a response (trap or report), the sender of the message is authoritative. Generally, an SNMP agent is authoritative, and a manager is nonauthoritative. A nonauthoritative engine must discover the snmpEngineId of the authoritative engine with which it communicates. USM describes a mechanism for authoritative EngineID discovery in RFC3414.
  • contextEngineID:
    This is the EngineID of the entity that hosts the context to which the data belongs. For simplicity and for most practical purposes authoritativeEngineID and contextEngineID are the same.

VTScada has a single SNMP engine in every application and the corresponding EngineID is unique for every application + workstation combination. This engine serves the single SNMP Agent as well as all the SNMP driver tags running in the application. VTScada’s SNMP engine supports and services the USM authoritative engineID discovery mechanism.


SNMP I/O Addressing

SNMP addresses are built using a hierarchy of OID Closed Object IDentifier. A part of the SNMP driver addressing system. values. The VTScada SNMP Address Select tool (Address Assist / Address Select) will help you build addresses for your I/O tags.

As part of the Address Select tool, you can tell VTScada where to find the MIB Closed Management Information Base. A hierarchy of the information available to an SNMP device, organized by numbered Object Identifiers (OIDs). file, supplied by the manufacturer for your device. If you know the OID there is no need for a MIB.

It is possible to create a VTScada SNMP Agent service, to serve tag values over SNMP. But note that table addressing and reading tables is complex. As one example, the OID for a table entry contains the content of the entry and is not fixed. Therefore, for VTScada I/O the user must obtain the table entry using a third party SNMP software program, obtain the full OID, and then use it in VTScada IO address. While GetBulk and GetNext are useful in walking a table, VTScada I/Os do not use these functions (although they are implemented in the driver). The user must write a script to call these functions and pass their values to I/O tags.

SNMP data types influence your selection of I/O tag data type:

SNMP supports 12 data types. These are passed directly to the I/O tag, where further processing may be required.

  • SNMP data types: Integer32, Unsigned32, Gauge32, Counter32, Counter64 and TimeTicks can be used with numeric tag types.
  • SNMP data types: Integer(Enumerated), Octet String, Object Identifier, IpAddress, Opaque and Bits should be read in with a string data type, with additional processing done using a Calculation tag as required.

SNMP Agent Configuration is described in the VTScada Programmer's Guide

SNMP Address Configuration

There are two parts to address configuration. The first is to obtain the required .MIB file(s) and import them into your application. The second is to build the address using the built-in SNMP Address Select dialog (shown later in this topic).

Importing a .MIB

  1. Obtain a .MIB file from your equipment manufacturer.
  2. Save this file to a folder on your VTScada server computer.

All .MIB files that will be used by an application will be stored a folder named "MIB" within your application directory. You can create this folder yourself and copy the files to it. If using the Import MIB button, VTScada will create the folder and copy the selected files to it. This is generally the easiest and most reliable method.

  3. Import the file into the application's version control system.

There are two ways to do this:

  1. Copy the file to your application and then click on the application's Import File Changes button in the VAM.

Or:

  1. Create and configure an SNMP driver tag in your application.
  2. Select that driver in an I/O tag.
    The address field of the I/O tag will now have a ... button which you can use to open an Address Select tool.
  3. In the Address Select tool, you will find an Import MIB button.
  4. Click the Import MIB button.
  5. Select the file.

If the .MIB file depends on other .MIB or .MY files, you will get an error message in the Address Select tool. Hovering over the error will open a tool-tip window that displays the name of the missing file. Locate and copy this file to the MIB folder, then use the Import File Changes button in the VAM.

Building an address.

The following instructions assume that you are configuring an I/O tag that uses an SNMP driver and have reached the stage of building the address.

SNMP addressing - MIB button

An Address Select button can be found beside the address field when an SNMP driver has been selected as the I/O Device.

SNMP address selection

The Disable Polling option will turn off regular polls for this OID. Use this when you want to receive data from traps only. Adding the :NS (no scan) suffix after the SNMP OID will cause the same result.

The result will be similar to that shown here:

SNMP address string


SNMP Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No Error
01 | 0x1 | Response message too large
02 | 0x2 | Bad OID
03 | 0x3 | Bad value
04 | 0x4 | Read only
05 | 0x5 | General error
06 | 0x6 | No access
07 | 0x7 | Wrong type
08 | 0x8 | Wrong length
09 | 0x9 | Wrong encoding
10 | 0xa | Value can't be assigned
11 | 0xb | Can't create variable
12 | 0xc | Inconsistent value
13 | 0xd | Resources unavailable
14 | 0xe | No variables updated
15 | 0xf | Undo failed
16 | 0x10 | Authorization error
17 | 0x11 | Not writeable
18 | 0x12 | Inconsistent name
19 | 0x13 | Max retries exceeded
20 | 0x14 | OID or Syntax not in local MIB
21 | 0x15 | Port not connected
22 | 0x16 | Port incompatible
23 | 0x17 | Port invalid
24 | 0x18 | No such instance at this OID
25 | 0x19 | No such object at this OID
26 | 0x1a | Unknown SNMP version
27 | 0x1b | Unknown SNMP security model
28 | 0x1c | Invalid security flags
29 | 0x1d | Cannot parse incoming SNMP packet
30 | 0x1e | Cannot encode outgoing SNMP packet
31 | 0x1f | Unsupported security level
32 | 0x20 | Message not in time window
33 | 0x21 | Unknown username
34 | 0x22 | Unknown EngineID
35 | 0x23 | Authentication failed
36 | 0x24 | Decryption failed
37 | 0x25 | Encryption failed
38 | 0x26 | Response message parameters don't match request message parameters
39 | 0x27 | Unexpected PDU type
40 | 0x28 | RequestID in response does not match request
41 | 0x29 | Unexpected internal error in SNMPDriver
42 | 0x2a | No handler was available to process PDU
43 | 0x2b | Error adding user credentials


SNMPGetBulkDistributor Tag

Called a SGBD tag for short, this tag coordinates GetBulk commands for an SNMP driver tag.

Overview

An SNMPGetBulkDistributor tag is linked to an SNMP driver tag or an SNMP-related Driver Multiplexer tag. You can specify the starting point and the length of the sequence, and the polling frequency for the GetBulk commands within the SGBD tag Connection tab.

The SNMPGetBulkDistributor tag will prompt the SNMP driver tag to issue the GetBulk command at the specified polling frequency.

SNMP itself does not have a WriteBulk. GetBulk is meant to read in a bulk from any SNMP device, whether it is read-write or read-only. Also it can read objects (in our case I/Os that are read-write or read-only)

About GetBulk commands

A GetBulk command requests the values from a number of sequential OID Closed Object IDentifier. A part of the SNMP driver addressing system.s returned in a single datagram.

As an example, if the SGBD tag is configured like so:

  • GetBulk Starting OID = 1.3.1.4.1.2021.8.1.101
  • GetBulk Max-Repetitions = 10
  • Scan Interval = 10

then the SNMP driver will request the values stored in the 10 OIDs after 1.3.1.4.1.2021.8.1.101 in the order that they are listed in the MIB. The SGBD tag will prompt the SNMP driver tag to repeat this command every 10 seconds.

GetBulk commands permit you to send small command packets compared to multiple or coalesced GET commands. It is a compact command with the potential to reduce overhead. However, they're only practical in MIBs that have sequential OIDs to poll, with a relatively predictable response size within your maximum PDU length. Datagrams that exceed the capacity of your network are dumped.

The SGBD tag is not a driver. It should never be used as a subordinate for a Driver Multiplexer tag, a Polling Driver, or for a Transaction Logger tag.

Closed SNMPGetBulkDistributor tag ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Closed SNMPGetBulkDistributor tag Connection tab

caption

I/O Device

Link to an SNMP driver tag or an SNMP-related Driver Multiplexer tag.

GetBulkStarting OID

When linked to a configured SNMP driver with linked I/O Device tags, an address selector will be enabled and an ellipsis button will appear to the right of this field.

Specify the starting OID of your GetBulk sequence.

GetBulk Max-Repetitions

Excluding the starting OID, the number of subsequent OIDs to include in the request.

Scan Interval

The polling frequency, measured in seconds. A fresh GetBulk command is initiated after the interval has elapsed. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored.

Related information:

SNMP Agent Configuration

SNMP Driver

SNMP I/O Addressing

SNMPAgentMaxRepetitionsCap


SNMP Agent Destination Tag

This tag is used to specify destination SNMP entities for the traps and informs outgoing from VTScada SNMP agent. If the application property "SNMPAgentPublish" is set, then every IO tag (or legacy io) that has the publish flag set, will be published via SNMP trap/inform to all the destinations in the destination tags.

A VTScada SNMP Agent operating in v2c can use either this tag or the legacy application properties, SNMPAgentTagNotifyMode,SNMPAgentTrapCommunity, SNMPAgentTrapHost, SNMPAgentTrapPort.

For communication in SNMP v3, an SNMP Agent Destination tag must be used to send traps or informs.

Related information:

Best Practices for Tags

Closed SNMP Agent Destination properties, ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

SNMP Agent Destination properties, Communications tab

This tab identifies the remote SNMP entity to which the outgoing SNMP notifications (TRAPS or INFORMS) are destined.

Address

Name or IP address of the remote system

Port

Port number for the remote system

SNMP Agent Destination properties, Credentials tab

Varies according to whether the SNMP version is set to v2c or v3.

SNMP Version

Select either v2c or v3. This choice affects the remaining properties.

Mode

Chose between Traps and Informs.

(v2c) Trap Community String

The SNMP trap community string to be used.

(v3) Security Level

Choose between None, Authentication Only, or Authentication and Encryption.

(v3) Username

Username for the SNMP credentials

(v3) Authentication Password

Security level must be set to at least Authentication.

Provide the authentication password. This is encrypted before being stored and will never be displayed as readable text. After the cursor leaves this configuration field, changes can be made only be clearing the field and entering a new value.

(v3) Authentication Protocol

Security level must be set to at least Authentication.

Specifies the authentication protocol in use for the given username. May be either MD5 or SHA-1

(v3) Privacy Password

Security level must be set to at Authentication and Encryption.

Encrypted privacy password. This will never be displayed as readable text. After the cursor leaves this configuration field, changes can be made only be clearing the field and entering a new value.

(v3) Privacy Protocol

Security level must be set to at Authentication and Encryption.

Specifies the privacy protocol in use for the given username. May be any of DES, AES-128, 3DES or AES-256.

Closed SNMP Agent Destination Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Equipment / Status Color Indicator

Indicator Light Widget

LCD 7 Segment Widget

Numeric Value Widget


SQL Data Query Driver

Not counted towards your tag license limit.

The SQL Data Query driver provides a means for a VTScada application to capture data from an ODBC-compliant database and to place that data into the application's Analog Status, Digital Status, Analog Input, or Digital Input tags. The driver allows time-stamped historical data in the database, or current values, or both to be read into VTScada tags and sent to the VTScada historian.

To use the driver, do the following steps in order:

  1. If you plan to use an ODBC data source name for the connection, create this using the Microsoft ODBC administration tools. Choose the 32-bit or 64-bit ODBC administrator as appropriate for the data source. VTScada can connect to either.
  2. Create and configure one or more SQL Data Query Driver tags.
    At least one tag will be required for each ODBC source used. Additional tags may be required if more than one SQL Query template is required.
  3. Create the I/O tags that will receive data from the driver tags.
    Use String I/O tags if retrieving text values.
    If using Analog Status tags, ensure that you set the scaling parameters appropriately. In most cases, the Unscaled Data Process Max and the Scaled Data Process Max values should be identical so as to avoid scaling the retrieved value.
  4. Draw the SQL Data Query Driver tag using the built-in drawing widgets.
    The Show Stats button and a Communication Indicator widget are both recommended.

Error Handling

Connections to database servers via ODBC can provide a wide range of errors that are related to the type of database, the ODBC driver used, and the type of fault encountered. For some of these errors, the best course of action is to disconnect from the database and then reconnect to it to clear the fault. Because the cases where this needs to be done can vary widely and may be influenced by your server or network configuration, VTScada provides a means to instruct the SQL Data Query Driver tag to perform a disconnect and reconnect upon receiving specific error codes from the database.

To configure this feature, you must first determine what error codes require that the database be disconnected (this may take some trial and error) and then enumerate these error codes using a set of system settings that define both the database type and the error codes. In practice, these settings will take the following general format:

SSSODBCDisconnectErrorN = EEE

Where:

SSS defines the server type and can be one of the following. (Note that this must match the server type you selected when configuring the tag)

  • MS-SQL-Server
  • MS-Access
  • Oracle
  • MySQL
  • SyBASE
  • PolyHedra

N defines the error index, which must start with a value of 1 and increase in steps of 1 for each different error code. ODBCDisconnectError must always match this test for all settings

EEE defines the error code returned by the ODBC driver for the database

These codes can be configured using the advanced option Edit Properties dialog or by manually editing the Settings.Dynamic file, followed by an import.

Example #1:

If a connection to an MS SQL-Server database returns error codes 234, 895, and 4589 when it needs to be disconnected & re-connected, create the following three application settings:

MS-SQL-ServerODBCDisconnectError1 = 234
MS-SQL-ServerODBCDisconnectError2 = 895
MS-SQL-ServerODBCDisconnectError3 = 4589

Example #2:

If a connection to a MySQL database returns error codes 1111,222, 666, and 4321 when it needs to be disconnected & re-connected, create the following four application settings:

  • MySQLODBCDisconnectError1 = 1111
  • MySQLODBCDisconnectError2 = 222
  • MySQLODBCDisconnectError3 = 666
  • MySQLODBCDisconnectError4 = 4321

Related information:

SQL Data Query I/O Addressing

SQL Driver Error Codes

Best Practices for Tags

Closed Related Application properties

The following property settings hold additional configuration parameters for your SQL Data Query driver:

SQLDataQueryDriverDefaultDBType - The default database type is 2 (Oracle).

SQLDataQueryDriverDefaultTableName - The default table name is "RealAnalog".

SQLDataQueryDriverMaxTagsPerQuery - Limit on the number of tags per query. Defaults to 25.

Closed SQL Data Query Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

SQL Data Query properties Database Settings tab

The Database Settings tab holds the properties required to connect to the database that you will query.

Database DSN

The Data Source Name (DSN) is configured using the Microsoft ODBC Administrator tool. It is used in place of a connection string to access a database via an ODBC-compliant driver.

Database Type

In addition to the usual types supported by VTScada: Oracle, MySQL, and MS-SQL Server, you can select from Access, PolyHedra or SyBase.

Username and Password

Provide the credentials that are required to connect to your database program.

While the password is not displayed on this configuration screen, it is stored using plain text and will be visible if the tag database is exported.

While not a common configuration, you can set the SQL Data Query Driver's password to an expression. If you are using an optimized expression, you should use a Settings.Startup property because an optimized expression does not react to dynamic changes. (You will need to restart the application for the expression to react to the change.) If you use an unoptimized expression, note that those do react to dynamic changes, and will update if you change a Settings.Dynamic property that is referenced in the expression.

SQL Data Query properties Query Settings tab

Single Value SQL Query Template

Use this if either of the following is true:

  • The data will be queried in a format of one query per address (input tag) or
  • Only one tag address is supplied (attached) to the driver.

Templates are the SQL selection queries that you want to execute. The table name and where-clause values to query are written as replaceable parameters, with values coming from the I/O tags using this driver. For more information, refer to the section, "Creating Queries for the SQL Data Driver", found within this topic.

Multi Value SQL Query Template

The tag query template to use if multiple tag addresses will be returned by a single query.

Use Multi Value Query Template

Force the use of the "Multi Value SQL Query Template" if more than one tag is attached.

Use Single Quotes on Addresses

Select this box to apply single quotation marks to all tag addresses / where-clause parameters, when they are inserted into a query.

Select this option if querying based on text values. Deselect this option if querying based on numeric values.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Query Result Timestamp Time Zone

Using these radio buttons you can display the timestamp within your results using either the local time zone or UTC. Note that the VTScada Historian stores all data using UTC, but this might not be the case for the database that you are querying.

Time-Out Limit

Time limit in seconds for queries to the database server. Queries that exceed this time will be declared as a communication failure and data for associated tags may be invalidated, depending on the state of the "Hold" setting.

Creating Queries for the SQL Data Driver

The SQL Data Query Driver relies on user-defined query templates in combination with parameters supplied by the address fields of the associated tags to create configurable queries that extract data as needed. Use this to create generic query template to be created at the driver level that are then modified by the contents of the attached input tag address fields through the use of replaceable tokens. This enables the driver tag to read a database table containing data for multiple tags with a single query definition.

A user defined query template can contain the following tokens:

  • ^A - ID value token
  • ^T - Table name token

Several examples following show how these can be used in conjunction with the tag addresses to create queries to extract database table values into VTScada tags. Note that query templates may contain modifiers as appropriate for the database being queried, such as "LIMIT" (MySQL, Oracle), "TOP" (Access, MS-SQL), "ORDER BY", etc.

Required Query Result Format

All queries returned from the database must be structured in a multi-field format following one or the other of the formats described following:

  • Option 1 - ID and Value

The data will be returned as two columns with the first field containing a text string or numeric value that matches the ID portion of the address field of the tag for which it is destined. The second column will contain the data value for the tags that match the address ID in the first field. For example, if an Analog Status tag is created with its address set to "ABCDE", a query resulting in the following returned data set would assign a value of 36.7 to the raw value of the tag:

Field 1 - ID | Field 2 - Value
ABCDE | 36.7
AAAAA | 56.8
GHGHG | 99999

If two other tags are created with their addresses set to "AAAAA" and "GHGHGH", their raw values would be set to 56.9 and 99999 respectively by the same query result. In this example, the timestamp of the Analog Status tags would be set to the current time as a result of the query result as there are no timestamps in the data set returned from the database.

  • Option 2 - ID, Value, and Timestamp

An optional third timestamp field may also be returned from the database and if present will be automatically detected by the driver and used as the timestamp for the tags. For the above example, if the table to be queried was instead formatted as shown here:

Field 1 - ID | Field 2 -Tag Value | Field 3 - Timestamp
ABCDE | 36.7 | 2014-06-02 12:34:56
AAAAA | 56.8 | 2013-06-02 13:44:16
GHGHG | 99999 | 2012-06-02 14:54:06

Then the Analog Status tags with addresses "ABCDE", "AAAAA", and "GHGHGH" would be assigned values 36.7, 56.8, 99999, and timestamps "2014-06-02 12:34:56", '2013-06-02 13:44:16", & "2012-06-02 14:54:06" respectively.

Using Query Templates

The driver tag's query templates function by allowing the user to create a generic query that will have some of its content replaced by data extracted from the address fields of the associated I/O tags through the use of the ID token ^A or the table token ^T. The examples following show several ways in which data can be read from a database using the query templates in conjunction with the tokens.

Example #1 - Single Tag Value from a Table

This example reads a single value from a specific table.

Given a query template configured as:

SELECT TagName, TagValue FROM DataLogTable WHERE TagName = '^A'

And, an Analog Status tag with its address set to AIT0045,

Then the resulting query would be:

SELECT TagName, TagValue FROM DataLogTable WHERE TagName = 'AIT0045'

The result is a two-field response where the first field is a match for the address field of the attached Analog Status tag.

An additional setting of the driver that makes building queries of this type easier is the "Use Single Quotes on Addresses". If selected, then the tag addresses are automatically delimited by the single quotation marks so the query template can be changed to:

SELECT TagName, TagValue FROM DataLogTable WHERE TagName = ^A

And, the resulting query will be the same. This option should be used only when querying based on text values, not numbers.

Example #2 - Multiple Tag Values from a Table Using Multiple Queries

If multiple tags need to be extracted from a single table, then the template shown in example #1 will function by executing one query for each connected tag. For example, if three tags are connected to the driver with addresses, AIT0045, PT0679, and FIT0098, then three queries are generated by the driver:

SELECT TagName, TagValue FROM DataLogTable WHERE TagName = 'AIT0045'

SELECT TagName, TagValue FROM DataLogTable WHERE TagName = 'PT0679'

SELECT TagName, TagValue FROM DataLogTable WHERE TagName = 'FIT0098'

This example is contingent on the following settings being made in the driver:

  • The template is entered in the "Single Value SQL Query Template" setting
  • "Use Multi Value Query Template" is NOT selected

Note that the setting "Use Multi Value Query Template" enables the user to select which template to use. If not selected, the "Single Value SQL Query Template" is always used. If selected, the "Single Value SQL Query Template" is used only if there is 1 tag attached to the driver, while the "Multi Value SQL Query Template" is used if there are multiple tags attached to the driver.

Example #3 - Multiple Tag Values from a Table Using a Single Query

As noted above in Example #2, a query template can be used to query data for multiple tags in a single query, provided that the query result correctly correlates the tag addresses in the first field with the data in the second field. If, for the above example, the "Use Multi Value Query Template" setting is selected, then the following template entered in the Multi Value SQL Query Template field:

SELECT TagName, TagValue FROM DataLogTable WHERE TagName In (^A)

would result in a query structured as:

SELECT TagName, TagValue FROM DataLogTable WHERE TagName In ('AIT0045','PT0679','FIT0098')

The dataset returned from this query would contain multiple records and the driver will assign the data to the appropriate tags based on the contents of the TagName field returned as the ID.

Example #4 - Using Table Name in the Address

If each tag requires data to be extracted from a different table, then a table name may be added to a tag's address and from there used to populate the table name field of a query automatically. Using this template:

SELECT TagName, TagValue FROM ^T WHERE TagName = '^A'

Where used with tags having the following addresses:

AIT0098/DataHourly

PT1111/DataDaily

FIT0108/DataMonthly

Then, the resulting queries would be in the form:

SELECT TagName, TagValue FROM DataHourly WHERE TagName = 'AIT0098'

SELECT TagName, TagValue FROM DataDaily WHERE TagName = 'PT1111'

SELECT TagName, TagValue FROM DataWeekly WHERE TagName = 'FIT0108'

Note that this example assumes that all three tables contain the columns, 'TagName' and 'TagValue'.

Example #5 - ID Does Not Exist In Database

In some instances, there may be a need to extract data from a database table where no unique ID exists to identify the data other than the field names in the table. For example, if a database contains a table named "LastReadings" that contains only 1 record with the following fields:

ReadingTime
Temperature
Pressure
FlowRate

If you wish to extract the most recent of these three readings into three individual tags, then the following query template could be used:

SELECT '^A', ^A, ReadingTime FROM LastReadings

By setting the tag addresses to "Temperature", "Pressure", and "Flow", the following queries will be created:

SELECT 'Temperature', Temperature, ReadingTime FROM LastReadings

SELECT 'Pressure', Pressure, ReadingTime FROM LastReadings

SELECT 'FlowRate', FlowRate, ReadingTime FROM LastReadings

Note the use of the ID in two places in the list of fields to select. By placing the first of these inside of single quotation marks, the query result will return this field value as a text string, which will then meet the driver requirements to have the first field match the ID portion of the address set by the tag. The second field returned will contain the corresponding data required for the tag from the named field itself.

Example #6 - Multiple columns of readings per row

In many databases, there will be many values per row in a table. For example, consider the following table named FieldReadings which has temperature, pressure and flow, all identified by ID:

ID | Temperature | Pressure | Flow
1001 | 50.6 | 100.4 | 20.5
1002 | 53.7 | 120.3 | 15.5

One approach is to define three separate driver tags, with the following query templates:

SELECT ID, Temperature FROM FieldReadings WHERE ID IN (^A)

SELECT ID, Pressure FROM FieldReadings WHERE ID IN (^A)

SELECT ID, Flow FROM FieldReadings WHERE ID IN (^A)

This benefits from driver read coalescing, in that the driver can efficiently retrieve data for multiple tags with a minimum of calls to the database. However, this comes at the cost of more complex tag configuration, where I/O tags must be configured to point to different drivers that all reference the same table.

Another approach is to override the use of the ^T table placeholder to instead refer to the column from which to retrieve the data.

The query template for the single instance of the driver tag would look like the following:

SELECT ID, ^T FROM FieldReadings WHERE ID IN (^A)

The tag addressing would look as follows:

1001/Temperature

1001/Pressure

1001/Flow

This has the benefit of reducing the number of driver tags to one and reducing configuration complexity across the system. However, due to the addressing scheme used, the driver can not take advantage of read coalescing, which will result in a database query for each tag value requested. This approach would be of use in a smaller system with a limited amount of tags that wish to query a fast database platform at spaced intervals. This approach may not be suited for large-scale systems querying data at high rates.

Closed SQL Data Query Driver Widgets

The following widgets are available to display information about your SQL Data Query driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Related information:

SQL Data Query I/O Addressing


SQL Data Query I/O Addressing

Input tags using the SQL query driver should use the following format in their address fields:

HIST:ID/Table

Where:

HIST: - An optional prefix on the address to force the driver to configure the data returned from the database in a format that is compatible with the "History Address" settings for the analog status and digital status tags. This format is typically used when retrieving logged historical records from a database into the VTScada historian.

ID - Denotes a text string or numeric value that will uniquely identify the tag to which it is associated. This is used to match data returned from the database with the tag.

/Table - The optional table name.

Examples of valid addresses:

Address | Description
AIT09876 | Simple text ID (In the driver configuration, select 'Single quotes should be specified on addresses')
9087 | Simple numeric ID
PIT9087.PV/DataLog | ID "PIT9087.PV" including a table named "DataLog".
HIST:PIT9087.PV/DataLog | ID "PIT9087.PV" including a table named "DataLog" used in history retrieval mode
HIST:9087 | ID "9087" used in history retrieval mode

Related information:

SQL Data Query Driver

SQL Data Query properties Query Settings tab


SQL Driver Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
101 | 0x65 | No valid SQL queries found
102 | 0x66 | Wrong Number of Columns in Response
103 | 0x67 | No Valid SQL Query Responses
104 | 0x68 | Tag Not Found in Query Response
105 | 0x69 | NULL Value Returned in Response
106 | 0x6a | NULL Timestamp Returned in Response


Tesco Driver

Not counted towards your tag license limit.

Tesco Driver Tags are available only if your VTScada license includes this option. Contact your Trihedral representative to purchase the required license.

The Tesco Data Express Plus driver implements Tesco’s Data Express Plus protocol, which is used to communicate with their L3000e RTU.

The following message types are fully implemented:

  • Multiple Register (Write)
  • Scalar Dump (Read)
  • Binary Dump (Read)
  • Special Command (Write)
  • Operational Status (Read)
  • Serial Number/Version (Read)

The following message types are not implemented:

  • Clock
  • Communication Failure Notification
  • Data Transfer
  • Archive Directory
  • Archive Transfer

Diagnostics

Detailed diagnostic logs can be created, which contain more information than those available in the Trace Viewer. If a NAK message is received, the textual information within it will be added to the diagnostic log.

Diagnostics are logged in 2 ways:

  • In memory based on the TescoDriverDiagnosticLogRecentSize setting. (Logging is disabled unless set to a non-zero value.)
    The most recent log messages are stored within each driver and can be retrieved by sending a memory dump file to Trihedral for analysis. This should typically be left on.
  • In log files (Application Trace Directory\Tesco Driver) if TescoDriverDiagnosticLogEnable is 1.
    Each driver's log files will be stored in one folder as simple text files. The logs are divided into multiple files based on the value of TescoDriverDiagnosticLogDuration. Files older than TescoDriverDiagnosticLogAge are deleted to ensure the diagnostics will not fill the available disk space. This should typically be left off when not troubleshooting a specific issue.

Related Application Properties

TescoDriverDiagnosticLogAge

TescoDriverDiagnosticLogDuration

TescoDriverDiagnosticLogEnable

TescoDriverDiagnosticLogRecentSize

TescoDriverDisableCommStats

TescoFailoverCount

TescoPortErrorDelay

TescoSharedRPC

Closed Tesco Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Tesco Driver properties Settings tab

The Settings tab includes the following properties:

Port

Select the Serial or TCP/IP tag that will provide the address and port to be used when communicating with the RTU.

Scada Network ID

The network ID of VTScada. This will be used as the source network for outgoing messages, and must be the destination network for incoming message

Scada Network Address

The node address of VTScada. This will be used as the source node address for outgoing messages, and must be the destination address for incoming message.

RTU Network ID

The network ID of the RTU. This will be used as the destination network for outgoing messages, and must be the source network for incoming message.

RTU Network Address

The node address of the RTU. This will be used as the destination node address for outgoing messages, and must be the source address for incoming message.

Any incoming messages that are not addressed to the correct Network ID / Node Address (Scada) and from the correct Network ID / Node Address (RTU) will be discarded.

Time-Out Limit

The length of time, in seconds, that the driver should wait for a reply from the devic

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

If this driver is being used in conjunction with a Driver Multiplexer, then configure the Driver Multiplexer to store the last values, not the drivers connected to the Multiplexer. In this case, only the Multiplexer should be configured to re-write automatically.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Closed Tesco Driver Widgets

The following widgets are available to display information about your application’s Tesco Driver tags:

Comm Indicator Widget

Comm Line Widget

Tesco Driver Communication Messages Dialog

Tesco Driver Statistics Dialog

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Tesco Driver Addressing

VTScada provides an Address Select (Address Assist / Address Select) dialog to help you build I/O addresses that work with your Tesco Driver. The dialog will sense whether you are creating an analog or digital tag and adjust the available address choices accordingly.

Configuring an analog tag to use a Tesco address.

Tesco addresses take the form, type-code followed by an index number. For example: AI0 for Analog Input type, index 0.

The Address Assist will display an error message if the address is not valid. It will also reduce the list of types and other fields as appropriate based on the I/O tag type being configured, and whether a read, a write, or a read/write operation is being performed. If the desired address cannot be configured in the address assist it’s likely the wrong tag type is being used – or the tag is not being configured properly.

The contents of the Special Command and Operational Status droplists are intended to assist the user in selecting the actual Index or BitNumber respectively. The entries can be expanded beyond those initially included by adding the following phrase identifier keys.

  • TescoOperationalStatusBit[BitNumber]Label
  • TescoSpecialCommand[Index]Label

Where BitNumber can be 0-7 and Index can be 0-255.


Tesco Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
101 | 0x65 | No Response
102 | 0x66 | Unexpected Message Type
103 | 0x67 | Bad Checksum
201 | 0xc9 | Write Rejected
202 | 0xca | Scalar Dump Rejected
203 | 0xcb | Binary Dump Rejected
204 | 0xcc | Special Command Rejected
301 | 0x12d | Address Error - Invalid address type
302 | 0x12e | Address Error - Invalid index
303 | 0x12f | Address Error - Index out of range
304 | 0x130 | Address Error - Invalid element
305 | 0x131 | Address Error - Bad element
306 | 0x132 | Address Error - Invalid bit number
307 | 0x133 | Address Error - Bit number out of range
308 | 0x134 | Address Error - Unknown timer/counter value data type
309 | 0x135 | Address Error - Unexpected address element
310 | 0x136 | Address Error - Invalid operation for this type
311 | 0x137 | Address Error - Timer/Counter value write missing a valid data type


TI505 Device Driver

Not counted towards your tag license limit.

Use this driver to communicate with devices in the Simatic TI505 family.

Note that the driver is designed for use only with TCP/IP connections.

Do not attempt to write bit-packed analogs. The protocol doesn't allow for the setting of a single bit in the PLC register. Attempting to do so will clear the other bits.

This driver supports multiple TCP/IP port connections between a single instance of the driver and the RTU.

Related Application Properties

TI505PropagateOnlyOnDataChange

TI505FailoverCount

TI505SharedRPC

Closed TI505 Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

TI505 Driver properties TCP/IP tab

The following properties are configured in the TCP/IP tab:

Port

Select the TCP/IP tag through which this device will communicate. Note that only TCP/IP ports will work. The TI505 device driver cannot be used with Serial ports.

Response Timeout (seconds)

The number of seconds to wait for a response before raising an error.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Store Last Output Values

Flag indicating that the last values written to the device should be maintained. If true, the driver will maintain the last values written for each address, allowing these value to either be re-written manually or automatically.

Automatic Rewrites

Flag indicating the driver should automatically rewrite the last value written to each address upon successful establishment of communications after a driver error occurred.

Closed TI505 Driver Tag Widgets

The following widgets are available to display information about your TI505 driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


TI505 Driver Addressing

VTScada provides an Address Select dialog (Address Assist / Address Select) to help you build I/O addresses that work with your TI505 Device driver.

Configuring an analog tag to use a TI505 address.

TI505 addresses take the form, MemoryClass followed by an Address number. For example, WX100 for Word Input at address 100.

Memory Class

Available memory classes include:

Memory Class Name | Memory Class
V Memory | V
Memory | K
Discrete Input Packed | X
Discrete Output Packed | Y
Control Register Packed | C
Word Input | WX
Word Output | WY
Timer/Counter Preset | TCP
Timer/Counter Current | TCC
Drum Step Preset | DSP
Drum Step Current | DSC
Drum Count Preset | DCP
System Status Word | STW
Drum Current Word | DCC

PID Loop Variables

Support is provided for the following:

  • LKC. (dot variable)
  • LPV. (dot variable)
  • LSP. (dot variable)
  • LMN. (dot variable)
  • LERR. (dot variable)
  • LMX. (dot variable)
  • LPV
  • LMN
  • LSP
  • LERR

Bit Number

A bit number can be enabled for reading inputs, but do not use for writing.

Note that the maker of the TI505 device uses a very different bit numbering convention for its hardware than the VTScada standard:

  • 16-bit data is numbered 1..16 instead of 0..15.
    Bit 1 is the most-significant bit, and Bit 16 is the least significant bit

  • 32-bit data is numbered 1..32.
    Bit 1 is the most-significant bit of the most-significant byte.

To accommodate this, I/O addresses for the TI505 accept both bit conventions:

  • Traditional VTScada bit numbers are preceded by the '/' character.
    Example: V200/0
  • SIEMENS bit numbers are preceded by the "." character.
    Example: V200.16

The Address Assist module has been modified to account for this. The "Enable Bit Number" option is now a radio button control that offers three options:

  • Disable Bit Number
  • VTScada Bit Number
  • SIEMENS Bit Number


TI505 Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x0000 | No Error
50 | 0x0032 | Timeout No Response from PLC
53 | 0x0035 | BCC error in Read Reply message
56 | 0x0038 | Bad Word Count in Read Reply message
57 | 0x0039 | Read Data Length too long
58 | 0x003A | Invalid Char in Read Reply message
59 | 0x003B | Incorrect Response Type in Read Reply message
61 | 0x003D | BCC error in Write Reply message
64 | 0x0040 | Bad Word Count in Write Reply message
65 | 0x0041 | Write Data Length too long
66 | 0x0042 | Invalid Char in Write Reply message
80 | 0x0050 | Bad VTS Address
110 | 0x006E | PLC: NITP Protocol Error
115 | 0x0073 | PLC: Bad or Missing Delimiter
116 | 0x0074 | PLC: Bad Block Check
117 | 0x0075 | PLC: Invalid Type
118 | 0x0076 | PLC: Invalid Character
119 | 0x0077 | PLC: Odd Number of characters
120 | 0x0078 | PLC: Invalid Device Code
128 | 0x0080 | PLC: Invalid error character
129 | 0x0081 | PLC: No words to write
130 | 0x0082 | PLC: Invalid Word count
131 | 0x0083 | PLC: Memory Address == 0
132 | 0x0084 | PLC: Write Unsuccessful
133 | 0x0085 | PLC: Invalid Command Code
143 | 0x008F | PLC: Invalid number of words
144 | 0x0090 | PLC: Unsupported Address class
145 | 0x0091 | PLC: Request too large
147 | 0x0093 | PLC: CAMP Max Resp Size Exceeded
172 | 0x00AC | PLC: Memory Read Error
173 | 0x00AD | PLC: Memory Write Error
199 | 0x00C7 | PLC: Message Queue Full


Toyopuc Driver

The Toyopuc driver provide support for all PLCs in the PC3 and PC10 lines.

Related information:

Best Practices for Tags

Toyopuc Driver Addressing

ToyopucDriverVTSMaxBlock

Closed Toyopuc Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Toyopuc Driver Options tab

PLC Series

Select one of PC3 or PC10 as appropriate.

Store Last Output Values

When selected, the driver will maintain a record of the last value written to each output address. This may be useful in at least two situations:

  • For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
  • When failed hardware is replaced by a new device and you would like to start that device with the values last written to the old one.

If the last output values are stored, they may be re-written by either of two methods:

  • Automatically, when communication is restored to the device.
  • Manually by way of a button press. See, Rewrite Outputs Widget for details.

Changing this value from selected to deselected will cause all stored values to be erased immediately.

Enable Auto Rewrite

If selected, the Store Last Output Values option will also be activated. This option causes the driver to rewrite the last value written to each output, in the event that communications are lost and then restored.

Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in driver communications.

Toyopuc Driver Communications tab

Configure the port, timeout limit, retries, whether or not to hold, retry delay, program number (PC3 PLC series only), Link number and Exchange number.

Port

Select the TCP/IP or UDP/IP port in use by your PLC. VTScada does not support FL-net.

Timeout Limit

Responses must be received within the specified time limit, otherwise a communications error will be assumed to have occurred.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

(For the above note, only the UDP configuration applies. The Toyopuc driver does not support communication via a serial port.)

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Retry Delay

The Retry Delay field enables you to specify the amount of time (in seconds or fractions of a second) that the driver will wait between attempts to repeat a transmission of data if the previous attempt(s) have failed.

By default, the Retry Delay field is set to 0 (indicating that there should be no delay between retry attempts).

Command Relay

Access data on RTUs that cannot connect directly to VTScada by relaying the information through 1 to 3 intermediary RTUs. Each level of relaying is comprised of three addresses as follows:

Program Number

The program number used at the destination hop. Ranging from 0 to 15. This only takes effect when PC3 is selected as PLC series, Defaults to 0.

Link Number

The source address. Ranging from 1 to 8.

Exchange Number

The destination address. Ranging from 1 to 254.

The fields for the second and third level of relaying will become editable once the preceding level has both fields filled out. Ensure each address is a discrete number within range and click anywhere outside the fields to process the change.

Closed Toyopuc Driver - Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Toyopuc Driver Communication Messages Dialog

Toyopuc Driver Statistics Dialog

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Toyopuc Driver Addressing

Addresses for the Toyopuc PLC driver take the form of PX-RRYYY\B

This can be specified using an Address Assist dialog, as shown:

Where:

  • PX- is an optional specification of program number for several register ranges (values between 1 and 3).

  • R represents the register type (either 1 or 2 characters).

  • YYY the register number in hexadecimal (to allow mapping from outputs from the PLC programming software).

  • \B is an optional bit-specifier to read a specific bit from a word based address.
    (Note: specific bit writing of word based addresses is NOT supported currently).

The following registers can be prefixed with a Program Number between 1 and 3

K, V, T, C, L, X, Y, M, S, N, R, D, B

The following registers are read as unsigned word by default and use the word addressing scheme

S, N, R, D, B, ES, EN, H, U, EB

The following register types are read as bits by default and use the bit addressing scheme

K, V, T, C, L, X, Y, M, EK, EV, ET, EC, EL, EX, EY, EM, GX, GY, GM

The maximum value for a register is based on the following defined data types:

"K" = 0x2FF

"V" = 0x0FF

"T" = 0x1FF

"C" = 0x1FF

"L" = 0x7FF

"X" = 0x7FF

"Y" = 0x7FF

"M" = 0x7FF

"S" = 0x3FF

"N" = 0x1FF

"R" = 0x7FF

"D" = 0x2FFF

"B" = 0x1FFF

"EK" = 0x0FFF

"EV" = 0x0FFF

"ET" = 0x07FF

"EC" = 0x07FF

"EL" = 0x1FFF

"EX" = 0x07FF

"EY" = 0x07FF

"EM" = 0x1FFF

"ES" = 0x07FF

"EN" = 0x07FF

"H" = 0x07FF

"U" = 0x7FFF

"GX" = 0xFFFF

"GY" = 0xFFFF

"GM" = 0xFFFF

"EB" = 0x1FFFF


Toyopuc Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
0 | 0x000 | No Error
17 | 0x011 | Inability to process data because of faulty CPU Module Hardware
32 | 0x020 | Fixed Data (ENQ) within relay command is not 05.
33 | 0x021 | Faulty transfer number
35 | 0x023 | Erroneous command code
36 | 0x024 | Erroneous subcommand code
37 | 0x025 | Erroneous command-format byte
38 | 0x026 | Erroneous function call operand number
49 | 0x031 | Write of function call prohibited by sequence operation
50 | 0x032 | A command that is defeated during a stop continuity is activated during a stop continuity
51 | 0x033 | Attempting to execute a debug function despite non debug mode
52 | 0x034 | Access prohibited due to configruation
53 | 0x035 | Non-executable due to configuration
54 | 0x036 | Non-executable due to other device configuration
57 | 0x039 | Attempting to start scanning without any reset afterwrting I/O point number parameters
60 | 0x03C | During a fatal failure a command has issued that is not executable during a fatal failure
61 | 0x03D | Non-executable due to competing process with a different-factor command is executed
62 | 0x03E | Non-executable command due to reset existence
63 | 0x03F | Non-exectuable command due to stop duration
64 | 0x040 | Address of a reading/writing command or address + data number of a command is out of range
65 | 0x041 | Word/byte number is out of range
66 | 0x042 | Non-designated data is sent
67 | 0x043 | Erroneous function-call operand
82 | 0x052 | Though any timer or counter is employed a command for reading.writing the set/recent values is issued.
102 | 0x066 | No reply is sent from link module with the link exchange number specified by a relay command
112 | 0x070 | Non-executable module with the link exchange number specified by a relay command
114 | 0x072 | No reply is sent from link module with the link exchange number specified by a relay command
115 | 0x073 | Multiple relay commands were issued to the same link module
512 | 0x200 | Timed Out Waiting for Response from Remote
513 | 0x201 | Timed Out Waiting for Echoed Message
514 | 0x202 | Unexpected Device Response
515 | 0x203 | Mismatch Response Command Code
516 | 0x204 | Relay Command: Exchange Number Mismatch
517 | 0x205 | Relay Command: Wrong Number of Hops
768 | 0x300 | No Error
769 | 0x301 | Port Not Defined
770 | 0x302 | Port Failed To Connect
771 | 0x303 | Port Lost Connection
772 | 0x304 | Serial Port Settings Out of Range
773 | 0x305 | Serial Port Already In Use or Not Available
774 | 0x306 | Serial Port Access Denied
775 | 0x307 | Serial Port General Failure
776 | 0x308 | Serial Port Invalid Parameter
777 | 0x309 | Port Not Connected
784 | 0x310 | Port Unknown Error


Veeder Root Driver

Not counted towards your tag license limit.

Use the Veeder Root driver tag to communicate with Veeder Root TLS-300 and TLS-350 UST Monitoring

Systems devices. At present, this driver supports only the i201 function code.

Related information:

Veeder Root Tag Addressing

Veeder Root Error Codes

Best Practices for Tags

Related Application Properties

VRDPLCConnAttLimit

VDRSharedRPC. drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

Closed Veeder Root Driver properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

Veeder Root Driver properties: Settings tab

Use the parameters in this tab to define how the driver connects to the device.

Settings tab of the Veeder Root driver

Port

Select the Serial tag that will provide the address and port to be used when communicating with the RTU.

Time-Out Limit

The length of time, in seconds, that the driver should wait for a reply from the device.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Security Code

If the device is protected by a security code, you must provide that value here before you will be able to change configuration.

Closed Veeder Root Driver Tag Widgets

The following widgets are available to display information about your application’s CalAmp diagnostic driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Comm Messages Button Widget

Show Statistics Button Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Rewrite Outputs Widget

Sparklines Widget


Veeder Root Tag Addressing

Veeder Root addresses take the form FunctionCode-TankNumber-Property. (example: i201-0-Volume for tank zero, total volume.) At present, only the i201 function code is supported, with properties as follows. Tank numbers can range from 0 to 16.

i201, in Tank Reports

Height

ProductCode

StatusBits

TCVolume

Temperature

Ullage

Volume

Water

WaterVolume


Veeder Root Error Codes

Error code (Decimal) | Error code (Hex) | Meaning
00 | 0x0 | No error
11 | 0xb | Not Used
12 | 0xc | Lost the port semaphore
13 | 0xd | Time out waiting for SOH char
14 | 0xe | Function code not found in VDRDict
15 | 0xf | Time out waiting for ETX
16 | 0x10 | Bad checksum calculation
17 | 0x11 | Function Code not supported
18 | 0x12 | Tank number not in valid range
19 | 0x13 | Variable not supported
20 | 0x14 | Tank number received does not match tank number sent
21 | 0x15 | Function code received does not match function code sent
22 | 0x16 | System does not understand command
23 | 0x17 | Writes Not Supported (Yet)


Workstation Status Tag

Not counted towards your tag license limit.

Workstation status driver tags can be associated with one or more I/O tags to access data that the driver obtains from the Windows Management Instrumentation (an API in the Windows operating system that enables devices and systems in a network to be managed and controlled).

In order to access information about the workstation being monitored by a workstation status driver tag, follow these steps:

  1. Create a workstation status driver tag. Set the Workstation Name drop-down list to the name of the workstation you wish to monitor. (You can create one workstation status driver tag for each workstation you wish to monitor.)
  2. Create one Analog Input tag for each piece of data you wish to obtain from the workstation being monitored. (You can create multiple Analog Input tags and associate them with a single workstation status driver tag.)
  3. Use the I/O Device field for each Analog Input tag to associate the analog input with the workstation status driver tag.
  4. Set the Address field of each Analog Input tag to one of the available strings.

See: Workstation Status Driver I/O Addressing

Workstation status driver tags have been configured in such a way that they do not conform to the same server/backup server fail over process like other VTScada drivers. In essence, the PC being monitored by a workstation status driver tag is its own server. If the PC being monitored drops off the network, the workstation status driver tag will be unable to report data about it to the application and will therefore have a value of INVALID. A value of 0 (zero) for the Workstation Status tag means that the PC is running and there are no errors.

Using the Expression() address of Workstation Tags.

The Expression() address of a Workstation driver provides a method to call a script-only function or expression from within an otherwise steady-state expression.
This feature can be a handy way to integrate a script-only function into an expression by referring to the value of the I/O tag holding the Expression() address.
This should not be used for triggers that require perfect accuracy. The function you call may require measurable execution time.
See: Workstation Status Driver I/O Addressing

About monitoring RPC performance

Local RPC queue length

The current length of the local FIFO Closed First In, First Out that processes all RPCs. Generally, a heavily loaded system is likely to have a large queue but the queue can still be large and the system functioning normally if the queue is being drained in an acceptable time. High queue length and low queue delay indicates a very busy system that is managing to keep up with RPC production but has very little spare capacity.
Address field value: RPCQLength

Local RPC queue delay time

The time it currently takes an RPC from being created to being processed. This represents the delay incurred between queuing an RPC and it being processed. This value increases as the system becomes more heavily loaded and is directly related to the time it takes VTScada to react to a value change from a device. The value is in seconds.
Address field value: RPCQDelay

Remote machine RPC transmission delay

The last delay between queuing an RPC for transmission and the RPC being transmitted. This is an approximation only due to the way that RPC inter-machine transmission queues are handled, but large values here indicate an overloaded network link to the remote machine. This could be due to excessive RPCs to the remote or a poorly performing network connection. The value is in seconds.
Address field value: RPCRemoteQDelay:{machine} - e.g. RPCRemoteDelay:ScadaBackup.

Related information:

Workstation Status Driver I/O Addressing

Monitor Servers, Disk Space, and Memory

Alarm on Low Disk Space

Best Practices for Tags

Closed Workstation Status Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Workstation Status Driver properties Workstation tab

This tab is used to specify the workstation for which the tag should report data.

Workstation Name

The Workstation Name drop-down list enables you to select the name of the workstation that you wish to monitor (you may alternatively enter a Net BIOS name in this field). The Workstation Name field defaults to the local machine name when new workstation status driver tags are initially created.

Please refer to Workstation Status Driver Tag Addressing for instructions on the correct configuration of a workstation status tag and its associated Analog Input tags.

Troubleshooting

Values do not appear for anything other than battery checks

It is likely that the Windows performance counter needs to be reset on this machine. Test by opening a command prompt with administrative privileges and typing PERFMON. If this opens with an error message, close the performance monitor and type LODCTR /R

Note that the /R must be in uppercase. If you did not open the command prompt with administrative privileges, this command will fail with error 5.

Restart the workstation.

Values don't update when running VTScada as a Service

If running as a service under a regular user account, then to access Workstation Status Driver values e.g. CPU, the account must be a member of the local "Performance Monitor Users" group.

Closed Workstation Status Driver Tag Widgets

The following widgets are available to display information about your application’s workstation status driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Numeric Value Widget

Multi-Color Widget

Multi-Text Widget

Plot Data Widget


Workstation Status Driver I/O Addressing

A workstation status driver tag monitors attributes of a named workstation. Use associated I/O tags to retrieve and display data about the workstation.

Updated values will be returned at the scan interval of the I/O tag.

In order to access information about the workstation being monitored by a workstation status driver tag, follow these steps:

  1. Create a workstation status driver tag. Set the Workstation Name drop-down list to the name of the workstation you wish to monitor. (You can create one workstation status driver tag for each workstation you wish to monitor.)
  2. Create one Analog Input tag for each piece of data you wish to obtain from the workstation being monitored. (You can create multiple Analog Input tags and associate them with a single workstation status driver tag.)
  3. Use the I/O Device field for each Analog Input tag to associate the analog input with the workstation status driver tag.
  4. Set the Address field of each Analog Input tag to one of the available strings.

VTScada provides the Workstation Address Select dialog ( Address Assist / Address Select) to help you build these addresses. In any tag that uses a Workstation Status driver, the I/O panel of the configuration dialog will provide a button beside the Address field:

I/O Address field with tool to open the Address Select dialog

Click this to open the Address Select dialog.

Available options include CPU, Battery, Memory, Disk, RPC monitoring and Other options including custom expressions

Workstation Address Select.
The "Expression" field is available only when "Other >> Custom expression" is selected.

Troubleshooting

Values do not appear for anything other than battery checks

It is likely that the Windows performance counter needs to be reset on this machine. Test by opening a command prompt with administrative privileges and typing PERFMON. If this opens with an error message, close the performance monitor and type LODCTR /R

Note that the /R must be in uppercase. If you did not open the command prompt with administrative privileges, this command will fail with error 5.

Restart the workstation.

Values don't update when running VTScada as a Service

If running as a service under a regular user account, then to access Workstation Status Driver values e.g. CPU, the account must be a member of the local "Performance Monitor Users" group.

If you intend to measure the amount of memory being used by VTScada, the PrivateBytes metric offers a reasonable approximation of this, being the sum of the amount of physical memory allocated, including paged data.
The VirtualMemory metric is the least accurate measure of actual memory in use since it refers to reserved space rather than used space.

Options | Address Field Value | Information Returned from Workstation
Performance
Processing Load | Expression:ProcessingLoad() | Returns the current VTScada processing load in percentage
CPU
Average CPU | AverageCPU | Running average of total system CPU
System CPU SystemCPU

System CPU - all processes

100% means that all logical processors are being used to their fullest. (In versions of VTScada prior to 12.1, VTSCPU was capped at 1 divided by the number of logical processors.)

VTScada CPU usage VTSCPU

CPU used by VTScada only.

100% means that all logical processors are being used to their fullest. (In versions of VTScada prior to 12.1, VTSCPU was capped at 1 divided by the number of logical processors.)

Battery
Battery level | BatteryLevel | The percentage of the battery level remaining
Battery lifetime | BatteryLifetime | An estimation of the remaining battery life, in seconds
Power status PowerStatus 0 == on battery
1 == on A/C
2 == on back-up power
Battery state - High | BatteryState:High | 1 if the battery's power state is high
Battery state - Low | BatteryState:Low | 1 if the battery's power state is low
Battery state - Critical | BatteryState:Critical | 1 if the battery's power state is critical
Battery state - Charging | BatteryState:Charging | 1 if the battery is charging
Battery state - No Battery | BatteryState:NoBattery | 1 if no battery is found
Memory
VTScada total memory | PrivateBytes | The total memory actually in use by the process, both physically and in the page file. Does not include shared memory such as that in shared DLLs.
OS used memory | SystemUsedMemoryBytes | Amount of committed memory currently being used by system in bytes.
OS used memory % | SystemUsedMemoryPercentage | Amount of committed memory currently being used by system in percentage.
OS total memory | SystemTotalMemoryBytes | Total committed memory available on system in bytes.
OS available memory | SystemAvailableMemoryBytes | Amount of unused RAM on the system
OS unused RAM | SystemAvailablePhysicalMemoryBytes | Amount of RAM that is available for use by applications and processes
VTScada Memory as per VTScada | Expression:Memory() | Calls the Memory function, returning the current amount of memory acquired for VTScada from the operating system heap on the named workstation.
VTScada memory as per OS Memory VTScada memory use in bytes, as seen by Windows. Does not decrease as memory is released.
In general, both Expression:Memory() and PrivateBytes will provide more useful measurements.
VTScada paged memory PageFileBytes

The total number of bytes that have been committed to the process, whether in physical memory or not. May include memory in shared DLLs.

This value provides the best reflection of how much memory VTScada needs while running your application.

VTScada virtual memory VirtualMemory

Virtual memory (hard drive space used as memory) allocated to VTScada, but not necessarily in use. Does not decrease as memory is released. Measured in bytes.

This does not provide an accurate view of memory that is actually in use. Page file size is allocated in blocks on an "in case needed" basis. The size of those blocks will be larger on a 64-bit system than on a 32-bit system.

Disk
Free disk space on drive FreeDiskSpace

Free disk spaces (bytes) for a logical disk that is addressable with a drive letter. (*)

You must append the letter for the drive to be monitored to FreeDiskSpace (e.g. FreeDiskSpaceC for drive C, or FreeDiskSpaceD for drive D.

Total bytes per second | IOBPS | Rate at which the process is reading and writing bytes in I/O operations. This property counts all I/O activity generated by the process to include file, network, and device I/Os.
RPC metrics
Local RPC queue length RPCLocalQLength The current length of the local FIFO that processes all RPCs.
High queue length and low Local RPC queue delay time(see RPCLocalQTime) indicates a very busy system that is managing to keep up with RPC production but has very little spare capacity.
Local RPC queue delay time | RPCLocalQTime | The time it currently takes an RPC from being created to being processed. The value is in seconds.
Remote machine RPC transmission delay | RPCRemoteQDelay:{machine} | e.g. RPCRemoteDelay:ScadaBackup. The last delay between queuing an RPC for transmission and the RPC being transmitted. The value is in seconds.
Other
Custom expression | Expression:AnyScriptFunction() | Call any script-only function or expression. This will fail if you attempt to use a steady-state only function. For example, Expression:Now(1) % 100 will fail but Expression:Seconds() % 100 will work.
VTScada GDI objects | GDIObjects | GDI objects used by VTS
VTScada handles | Handles | Handles in use by VTS
VTScada threads | Threads | Threads being used by VTS

For Remote machine RPC transmission delay you must supply the name of the remote machine. When this option is selected, The Expression changes to Remote Machine and becomes enabled.
You must supply the name of the remote machine. The name will appear in the Address Field.


Input Tags

Input tags are used to read data from an I/O device, such as a programmable logic controller (PLC), remote terminal unit (RTU), or an I/O board. These tags permit the handling of either digital (discrete), or analog (continuous floating point) values.

All input tags require a driver tag, which will provide the communication protocol required for the device. In general, it is best to configure a driver tag first, then add input tags later as children of that driver.

The following input tags are included with VTScada:

I/O and Calculations Tag
Analog Input Tags | Analog Status Tags
Digital Input Tags | Digital Status Tags
Data Flow Pulse Input Tags | Pump Status Tags
String I/O Tags | Camera Tag

Related information:

Communication Driver Tags - Driver tag reference

The Tag Browser - Using the Tag Browser to create and edit tags.

Optimize Your Configuration - Avoid problems when logging data

Deadbands for Reading and Logging - Avoid problems with system noise.


Camera Tag

Before displaying a camera’s image feed on a page, you must create a connection to the camera. As with all I/O, this is the job of a tag.

Create a Camera tag for each camera that you intend to monitor. Each must be accessible on your network using a URL (uniform resource locator). Note that the video feed must be provided as a motion JPEG.

Limits:

Camera limits and VTScada to camera connection sharing are done on a per-VTScada server / thick client basis. If two thick clients connect to a camera, they make separate connections and enforce limits separately. Any limit on a thin client refers to the case when a VTScada Internet Server's local user-interface (the thick client) and one or more thin clients connected to that server, are viewing the same camera feed.

  • Where a specific camera is being viewed multiple times simultaneously (for example, on a thick client and one or more thin clients) there is no limit. VTScada makes a single connection to the camera.

  • There is a default limit of 15 connections to a single host (or more specifically a scheme + host + port combination). This limit would apply where the camera streams come from a single source, such as a Network Video Recorder. Exceeding the Camera Tag default connection limit may slow VTScada.

  • Where the streams are from unique sources, such as individual camera IP addresses or host names, no limits are applied to the number of unique streams retrieved by VTScada.

Overriding the Camera Tag Connection Limit

The maximum number that can be set is 50 as the HTTP client also has a maximum 50 connection limit. The maximum connection limit cannot be exceeded. When exceeding the default limit of 15 connections, run test values to ensure that system performance is not impacted.

CameraTagConnectionLimit

Related information:

Best Practices for Tags

Closed Camera tag properties - ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Camera tag properties - Communications tab

URL

The address where the camera can be found. This must start with "http://" or "https://". Note that the feed must be provided as a motion JPEG.

Username and Password

If your camera is secured, provide the username and password as assigned. Configure these only if required by your system.

Camera Tag Widgets

The following widgets are available to display information about your tags:

Camera Viewer Widget

Camera Tag API

This function is for advanced users only.

The function GetLiveMJPEG is an API that provides access to the motion JPEG data in real-time. As the camera tag receives each frame, the data is converted to text and stored within the function variable. The text stored within the variable is continuously refreshed with each subsequent frame.

If the URL or credentials in the camera tag are irretrievable or if the camera is down the reference value will be invalid.


I/O and Calculations Tag

Counted towards your tag limit if configured to read or write.

Does not count towards your tag limit if configured to calculate without an output address.

This replaces many legacy tags, including: Analog Input, Analog Output, Digital Input, Digital Output, Analog Status, Analog Control, Digital Status, Digital Control, Pump Status, String I/O, Calculation and Function. While those tags will always be supported, you are advised to use the I/O and Calculations tag in their place for all new development work.

The replaced tags are available only in the "All Tag Types" and the "Legacy I/O and Calculations" groups of the Tag Browser.

Within this topic:

ID Tab

I/O Tab Version 1. Analog, Discrete and String

I/O Tab Version 1. Digital

I/O Tab Version 2. 2-bit Digital

Calculations Tab

Quality Tab

Scaling Tab

Logging Tab

Alarms Tab, Basic View

Alarms Tab, Advanced View

Display Tab

Widget List

Read / Write

If both a read address and a write address are defined and valid, then the read address is used only for feedback and is the only value shown as the value of the tag. If the value at the read address differs from the value written, the tag's Mismatch variable is set to TRUE, as reflected in widgets linked to this tag. The value at the read address is NOT sent to the write address on change.

If there is a write address and no read address, then the value of the tag will reflect the last value that was written. This is true for all data types. Use care however: this does not provide the same information as you would get from having a read address. Without feedback, you know only what the SCADA system attempted to send, not what the state is at the equipment.

If an I/O tag is configured as a Calculation and an output address is provided, each new value calculated will be written to that address. The value will be forced to the data type of the tag. If the data type is numeric, but the expression returns text, nothing will be written. If the data type is discrete, but the expression returns a floating point result, only the integer portion will be written.

The presence of Read, Write and History addresses are indicated in the Tag Browser by bracketed labels after the type. The order of the labels matches the order of the address. For example, in the following figure, the High Alarm has both a read address (40021) and a write address (40019).

The address of a calculation mode is shown as [Calc] or [Calc/Out]. Memory tags, which have no addresses, are shown as [Mem]

Related Information:

Deadbands for Reading and Logging - Avoid problems with system noise.

Memory Tags

If an I/O and Calculation tag does not have a configured address (read, write or history) then it does not count against your tag license. This configuration can be valuable as a "memory tag", which holds a value that is provided by an operator via a widget. The data type can be Analog, Discrete, Digital, or String.

Because memory tags do not write to an address in hardware, it is possible to set their value to Invalid. This can be controlled with the option, "Allow value to be cleared", which is visible in the I/O tab only when no address has been configured. This option also affects certain widgets such as the Droplist Widget, which will show "No Data" (value: Invalid) only if the memory tag can have its value cleared.

2-bit Digital, and all Calculation options of the I/O tag do not count as Memory Tags.

Operators can set the value of a memory tag using any of the standard control widgets. It is also possible to set the values of multiple memory tags in a single operation by using Multi-Write Tags

Memory tag values will persist across application restarts. You can configure a default (initial) value for a memory tag using the input field "Default Memory Value" on the I/O tab, but only if "Allow value to be cleared" is not selected.

Only I/O tags that have an address (read or write) count against your tag license. Memory tags have no address and therefore do not count.

Group Membership

The Historical Data Viewer, Reports Page, and other tools that list tags allow you to sort and filter by "group", where a group may be "analogs", "digitals", "loggers", etc.

Any given I/O and Calculations tag's group membership depends on how you configured it. The rules are:

  • Inputs group: The tag has a valid Read or History address, or it is a 2-bit Digital.
  • Outputs group: The tag has a valid write address, (2-bit digitals are never in the Outputs group.)
  • Loggers group: All I/O and Calculation tags.
  • Analogs and Numeric groups: This includes all Analog, Discrete, and their calculation modes.
  • Analytics group: This includes all calculation modes.
  • Digitals and Numeric groups: This includes all Digital and 2-bit Digital IO tags and their calculation modes.
  • Strings group: String and String Calculation mode IO tags

I/O and Calculations tag properties: ID tab

Closed Name, Area, Description

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Data Type

While the I/O and Calculations tag replaces many types, you must specify how each one is to be used. The data type selection controls the tag's behavior and the configuration options.

Configuration options vary according to the data type that you choose in the ID tab of the properties dialog. In the following notes, you may need to look up or down within a section to find the version that matches the mode you are configuring.

Data Type | Details | Select when you need to...
Analog | Analog (Doubles and floating point) | Read or write values that scale such as temperature or volume. If a deadband is not applied on the logging tab, a default deadband of 0.25% of the scaled range is applied. This value is stored in the application property DefaultAnalogDeadbandFractionOfFullScale
Discrete | Analog (Integers) | Read or write a set of known values, which may scale.
Digital | Digital (Binary values, 0 or 1) | Read or write a value of 1 or 0 from a single address.
2-Bit Digital | Digital (Binary values 00 to 11 (0 to 3)) | Read a value of 1 or 0 from two address, making this a 4-state digital. Cannot write values to either address.
String | Note (Text) | Read or write a text value. Output padding is handled by widgets rather than the I/O tag.

Within reason, you can change the data type after creating a tag. If after configuring for one data type, you select another, configuration options that do not apply to the new type are saved but not used. For example, you might initially define the tag as Analog and set scaling parameters. If you change the data type to Digital, the scaling tab is hidden and the scaling parameters are not used, but the values you set will be retained.

Calculation

For any data type, there is a Calculation option. This counts as a separate but matching mode for each listed in the drop-down. (So, Analog -> Analog Calculation)

Use this when you intend to create an expression that will be set the tag's value (or select another tag that this one should mirror). When creating a calculation, the choice of data type affects the values that can be returned by the expression and the set of widgets that can be used to display that value.

  • Calculation results can be written to an output address, in which case the tag will count towards your tag license.
  • Calculations that do not write to an output address do not count towards your license.
  • Any I/O tag with the Calculation mode set does not count as a memory tag. (Memory Tags)
  • Calculations do not retain their value across restarts. Use a legacy Analog Status (Analog Status Tags) or Digital Status (Digital Status Tags) if that feature is required.
  • In applications that run on multiple workstations, calculations are performed locally on each workstation unless the synchronize option (Sync) is selected. Either mode may be appropriate depending on the purpose of the calculation.
Mode Select when you need to...

Analog Calculation

Calculate a numeric value.

Does not read from hardware but may use the value of other tags that do.

Can write to hardware.

Discrete Calculation

Calculate a value from a set of known values.

Does not read from hardware but may use the value of other tags that do.

Can write to hardware.

Digital Calculation

Calculate a digital value.

Does not read from hardware but may use the value of other tags that do.

Can write to hardware (1, 0, or pulse)

2-Bit Digital Calculation

Calculate a 2-Bit digital value. (0 to 3)

Does not read from hardware but may use the value of other tags that do.

Can write to hardware (single address).

String Calculation

Calculate a text value.

Does not read from hardware but may use the value of other tags that do.

Can write to hardware.

Some changes of I/O type may harm other work. For example, assume that you have a tag configured as an Analog and drawn using a gauge. If you change the type to String, the gauge will be broken since it cannot display a text value. Note the mode for each data type as given in the preceding table. Changes from one to another data type are likely to cause problems.

Data logged for one data type may not be appropriate for another. Nothing will be lost, but a report for a digital such as "Pump run time" cannot show data logged while the tag was of type String.

HDV plots may need to be reconfigured. If the tag was plotted as a digital, it will not automatically switch to analog.

Work to avoid any need to change the data type of your I/O tags.

Equipment Type

Provides a way to categorize tags that is similar to the Area property but more powerful.

When used with Discrete or Digital I/O types, you can create style for your equipment type that assigns a label and color for each possible value of your tag. This may be especially useful when combined with I/O Multi-Text or the Droplist Widget.

One default type is provided: "Pump". This is used in the Reports page as a filter for the Pump Activity and Pump Discrepancy reports. You can filter based on equipment type in any tag list. Advanced users can create reports or other tools that use Equipment Type as a filter.

You are free to create as many equipment types as you need, and you may do so from within either an I/O tag on the ID tab or a Style Settings tag on the Equipment tab. The instructions are the same in both cases:

  1. Place the cursor in the Equipment Type field.
    (It does not matter whether the field is blank or shows an existing type.)
  2. Type the name of your new equipment type.
  3. Press the [tab] or [Enter] key on the keyboard.
  4. Click the Apply button.
    The new type is saved.
    If the field had shown an existing type before you started, it is not changed.

Equipment type names can be removed the same way that Area properties are removed: First ensure that the name is not in use within any tag, then restart the application.

The Equipment Type of an I/O and Calculations tag is a powerful feature when used with care. Do not assign Equipment Types casually, without a clear plan for how you intend to use this feature.

I/O and Calculations tag properties: I/O tab

The layout for Analog and Discrete modes is described first.
Scroll down for the String and Digital modes.

Link to a driver, configure addresses and scan interval, deadband, privileges, link and enable or disable publishing

I/O tab for Analog and Discrete modes

I/O Device (Required)

Select the communication driver tag that data will be read from or written to.

By default, the tag will look for a parent tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver's properties dialog.

Read Address (Optional.)

Provide the address within the I/O device from which this tag is to read data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

If a Write Address is provided the Read Address is used only as feedback and will set the value of the tag regardless of the value written. If the value in the Read Address does not match the value written then the tag's Mismatch flag is set to true and will be reflected in linked widgets, either as a blink or a mismatch color, according to the widget.

Address Assist: (...)

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the Address Assist dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your Communication Driver Tags for more information.

Scan Interval (Read scan interval. Applies only if a Read Address is provided.)

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Deadband (On data reading, for Analog values only)

If defined, the value on the device must change by more than this amount before the tag will register it as a new value. A deadband can greatly improve application efficiency by filtering out noise and eliminating unnecessary work to process that noise as if it were useful data.

The deadband is an absolute value, not a percentage, and is specified in terms of the tag's display values if set or the scaled engineering units otherwise. (Refer to notes for the Scaling tab.) If a deadband value is not provided, one will be calculated automatically based on several factors including the logging deadband and the application property, DefaultDriverDeadbandFractionOfFullScale.

See also: Deadbands for Reading and Logging

History Address (Optional. Use only with devices that support this feature.)

If set, then the Read address field becomes optional. This field provides a means of reading values as recorded by a data logger.

If both the read address and the history address are provided, then the read address will be polled for data at the set interval, but the values read from the history address will override the values logged from the read address.

If the identical address is provided for both read and history, then only the read address is used. History values will not be recorded.

The form for the history address will depend on the RTU. Please refer to the addressing reference chapter for your driver.

Typically, history data arrives as an array. If sent to the Read address of an input tag, only the first element is read and the rest discarded. History data must be sent to the History address in order to be fully recorded.

Note that it is not possible to enter a parameter expression directly in the History Address field. As an alternative, you may enter compound address in the Address field using a parameter expression. For example, if Addr, HistAddr and HistoryRate are all properties of a parent tag, the following expression in the Address field will create a compound address with all three components:

concat(.\Addr , "):(" , .\HistAddr , "):(" , .\HistoryRate )

The characters "):(" separate each component of the address. Do not add a leading or trailing parenthesis around the entire expression.

Further information on reading history information can be found in the topic SCADAPack History Read

For numeric values (not String), a deadband is applied automatically to the values read on the History Address. The calculation uses the application property, DefaultAnalogDeadbandFractionOfFullScale.

CalculatedHistDeadband = PickValid(Threshold, (HighScaleValue - LowScaleValue) * \DefaultAnalogDeadbandFractionOfFullScale, 0);

Scan Interval (History scan interval. Applies only if a History Address is provided.)

Sets the time between polls of the history data logger. If a History address has been set, but this field is left blank, then it will default to the value set in the Scan Rate field. The recommended value for this field is 60 seconds. Lesser values may cause communications to slow down.

Write Address (Optional. Do not configure for tags that are input-only.)

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Privilege (Applies only if a Write Address is provided)

Limit the ability to write using this tag to only those operators who have been granted the selected custom privilege. See: Restrict Access to Output Tags

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Allow value to be cleared

Enabled only for memory tags (I/O tags with no read or write address). When selected, widgets such as the Droplist Widget can show No Data (value: Invalid) as a option.

Default Memory Value

Can be used to set a default value when this tag is configured as a Memory tag (Memory Tags). This option cannot be used when Allow value to be cleared is selected.

I/O Tab, String data type layout

Variation for Strings, showing options for output padding and storage in registers

Pad with spaces

Enabled only after a Write Address has been entered. If selected, you will have the option of specifying a minimum length for output strings. Values shorter than this will be padded with spaces according to the selected Justify option.

String stored in registers

Select this option if reading a string from a series of numeric registers in PLCs such as Modbus or Delta, where the characters are encoded in the register values. This option requires the length of the string to be set so the tag can know how many registers to read or write.

Minimum Length

Enabled only after "Pad with spaces" or "String stored in registers" is selected.

  • When used for Pad with spaces, this sets the minimum length for output strings.
  • When used for String stored in registers, this sets the size of the string in bytes to ensure the proper number of registers are read to read the string.

Justify

Controls whether spaces are added to the left, the right or both sides of output text in order to achieve the required minimum length.

Reading Strings

If reading string data, note that not all PLCs will store characters in the same in order in registers. Further, registers may vary in size from one PLC type to another.

If the string read from your registers has characters that are not in the order you expected, use the BuffOrder() function in an expression to swap the order of the characters so that they do match what is expected. Do this by creating one I/O and Calculations tag to read the value, then create a second with an expression to read the value in the first and apply the BuffOrder function. The second I/O and Calculations tag will not count against your license because it does not use a read or write address.

Better practice is to program the PLC to send an integer code that can be mapped to a phrase in VTScada. The result can be used in a multilingual application and can reduce the amount of data transmitted.

Example: A BuffOrder call for a word-sized register with the character order swapped:

BuffOrder([<SourceTag>], 0, 1, 2, N)

...where the value N should be the half the length of the buffer.

I/O Tab, Digital layout

I/O tab for the Digital data type

Variations in this mode are as follows:

  • No Deadband values
  • Addition of the Invert Input and Invert Output
  • Addition of a pulsed output option

Pulse Duration

The pulse duration can be no less than 0 and no greater than 86400 (one day)

When set to a positive, non-zero number, the tag will a specified signal (1 or 0) to the Write Address, then retain that value for the number of seconds specified by the duration. At the end of that time, the opposite value is sent to the write address and the tag's value returns to its normal state.

For example, if a linked button widget is configured to write a 1, this tag will write the value 1 when the button is pressed and will hold the value 1 for the specified duration. At the end of the duration, a 0 is written and the tag's value returns to 0. Writing a zero using a second button linked to the same tag has no effect, except in the case that a pulse is in progress, in which case it will cancel the pulse.

If Invert Output is selected, then this tag's base state is 1 and it can be used to write a 0 (zero).

Triggering a pulse repeatedly will reset the timer with each press of the button. This allows a long pulse to be sent, but the pulse following the last button press will be no longer than the set duration.

Invert Input

If the Invert Input check box is selected, the value of the tag being used as the data source is reversed (i.e. a 1 becomes a 0 or a 0 becomes a 1).

Invert Output

If selected, the value being written is reversed (i.e. a 1 becomes a 0 or a 0 becomes a 1).

If the read address is the same as the write address, or the read address is blank and the history address is the same as the write address, then the Invert Output field will be disabled and the value will be set to the same value as Invert Input, preventing a mismatch.

I/O and Calculations tag properties: ID tab version 2

Used for: 2-bit Digital

2-bit Digitals can only read. Do not use for tags that must write. There is no option to read from a History address with a 2-bit Digital.

The reported value is the data at the Bit 0 address plus two times the data at the Bit 1. If the Bit 0 Address field does not contain a valid address, this tag will not read.

I/O tab, only for 2-bit Digitals

I/O Device (Required.)

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Bit 0 Address (Required.)

The Bit 0 Address property is the address of the low order bit for this tag in the I/O device.

Bit 1 Address (Required.)

The Bit 1 Address property is the address of the high order bit for the digital input in the I/O device.

Address Assist

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your driver for more information.

Scan Interval (Required.)

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

I/O and Calculations tag: Calculation tab

Used for: All Calculation modes

There are three versions of this tab, depending on the data type of the tag. Select the one you are interested in from the following drop-downs.

It is important that the calculation expression match the data type. For example, a digital calculation expression should have a value of 0 or 1. Proper behavior cannot be guaranteed unless the result matches the tag's data type. For example, a text expression for a discrete data type will resolve to an Invalid.

If the Sync Calculation option is not selected, Calculations are performed locally on each machine running the application and are not synchronized between machines.

To protect your system, changes in numeric calculations are subject to the built-in deadband, DefaultCalculationDeadbandFractionOfFullScale

Closed Analog and Discrete version of the Calculation tab:

Closed Digital and Two-bit Digital version of the Calculation tab:

Note that Value is a binary choice when set to Constant. Select Expression to open the usual expression field and editor button.

Closed String version of the Calculation tab:

Calculation

Holds the expression that this tag should calculate. (Expressions) While you can specify a constant or select another tag to mirror it's value, in most cases you will select the Expression option, then click on the [image] button in order to open the expression editor.

In calculation mode, the I/O tag does not retain its value across application restarts. If this is required, use the legacy Analog Control Tags.

Sync Calculation

The default is for calculations to be done on each local machine. If Sync Calculation is selected, the calculation is performed only on the current server and the value broadcast to other machines. "Current server" means the server for the parent driver tag, if there is one. If no valid driver is specified for the I/O tag, calculations are not synchronized.

I/O Device (Optional)

Select the communication driver tag that data will be read from or written to.

By default, the tag will look for a parent tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver's properties dialog.

Address (Optional)

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Deadband (Numeric and Discrete Calculation only. Optional.)

Changes in value smaller than this are not written by the tag.

Expected Range - Min and Max (Numeric and Discrete Calculation only. Optional.)

Used to provide default minimum and maximum values to certain widgets. (The Numeric Calculation type does not have a scaling tab, where these values would otherwise be set.)

By definition, an expected range should not overlap an alarm setpoint. If you do configure an overlap, do not expect both to show in any widget.

Pulse Duration (Digital Calculation only. Optional)

When set to a positive, non-zero number, the tag will send a specified signal (1 or 0) to the Write Address, then retain that value for the number of seconds specified by the duration. At the end of that time, the opposite value is sent to the write address and the tag's value returns to its normal state.

An important distinction from the Digital data type is that the calculation tag’s value does not return to its original state once the pulse its done (just the written value). To reset the pulse for a digital calculation, the expression’s value must go to 0 and then back to 1. This means that triggering a pulse repeatedly does not create a single long pulse, as in the normal digital case.

Invert Output (Digital Calculation only. Optional)

If selected, the a calculated state of the tag of 1 write as 0.

Privilege (Applies only if a Write Address is provided)

Limit the ability to write using this tag to only those operators who have been granted the selected custom privilege. See: Restrict Access to Output Tags

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

I/O and Calculations tag: Scaling tab

Used for: Analog and Discrete

Only the first four fields affect the value.

I/O scaling illustrated

VTScada assumes a linear relationship between the values as shown. The scaled and unscaled process values you provide set the slope of the line, allowing any value on one axis to be mapped to the other.

The values do not limit what the tag can read, but the Scaled Process Min and Max values do limit what the tag can write.

Min and Max Unscaled Process Data (Required.)

Use these to tell VTScada the range of raw values to expect from or write to hardware.

Min and Max Scaled Process Data (Required.)

These values must match the Unscaled Min and Max values. VTScada uses them to convert between the engineering units shown in the SCADA system and the raw values read from or written to the hardware. By default, the "Limit outputs to within Scaled min/max" option is selected. If you deselect this option, the output range limit is disabled. This allows any value, including negative integers, to be sent to the tag. However, scaling is still applied to the new output value, regardless of the value sent to the tag.

Display Range Min and Max (Optional.)

These two fields have no effect on the value of the tag.

Set the Min and Max Display Range values to define the default scale range for the HDV trend view and certain widgets, such as the various meters. Use these when values are expected to stay within a portion of the full scale range and it is therefore helpful to adjust the displayed range as needed.

If left blank, the Scaled Process Data Min and Max values will be used as the Display Range values.

Expected Range Min and Max (Optional.)

These two fields have no effect on the value of the tag.

Used to provide default minimum and maximum values to certain high performance graphics widgets. If left blank, the expected range feature of those widgets is not drawn. Both must be provided.

The expected range is shown in pale blue.
The color is controlled by the assigned Style Settings tag.

I/O and Calculations tag: Quality tab

Used for: All types

Quality tab for all types.

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

If the tag is configured with an output address, and (in the case where this tag is protected by a user-defined security privilege) if the person configuring the Manual Data value has required privilege, then the manual data value will be written to the defined output address.

In the case where the I/O tag was configured as a Calculation, the manual data value will override any expression value .

Quality Based on

The Quality Based On field can be tied to a driver tag, a tag that monitors driver communication errors, a register in the PLC or RTU, or any other indication of system health. The tag you are configuring will use that value to set an internal variable named QualityIssue. You may test this value in an expression: [TagName]\QualityIssue.

QualityIssue will be a 0 or 1 where "Good Quality" is defined as a value of "0 or Invalid" and "Bad Quality" is defined as any valid, non-zero value. This is consistent with driver communication error values.

Widgets that use the System Style tag will display bad quality using the color set on the Exceptions tab.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

I/O and Calculations tag: Logging tab

Used for: All types

Logging tab for all types

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Enable Logging

If values should be logged only while certain conditions are true, you can tie the Enable Logging option to any tag or expression that will change from zero (logging disabled) to 1 (logging enabled). Do so by right-clicking on the Enable Logging check box and creating a parameter expression. The "Optimize..." option in the expression should be deselected. For detailed instructions (and important warnings) see: Automated Tag Configuration.

Minimum Log Interval

Here, "Interval" refers to time measured in seconds. If set to a valid number greater than zero, and if the tag has a valid value, that value will be recorded to the history every interval, regardless of whether it has changed from the last write.

In most cases, this should be left blank, allowing values to be written on change larger than the specified deadband.

As of release 12.1.42, logging of I/O tags has changed as follows: Values will be logged on interval OR on change but not both. If both are needed, create a second (free) I/O tag using an expression that watches the value of the first tag. Log the first on interval and the second on change. Attempting to do both on the same tag introduces a small but important risk of values being recorded out of sequence if the remote device is sending timestamped data and its clock is not synchronized with the server.

Deadband (Analog, Discrete, and matching calculation modes only)

Every change in value will be written to the Historian. You are advised to set a deadband so that you do not fill the log with small changes that amount to system noise. (See: Deadbands for Reading and Logging)

When using the Analog data type, a default deadband of 0.25% of the display range if set and the scaled range otherwise. This value is stored in the application property DefaultAnalogDeadbandFractionOfFullScale

I/O and Calculations tag: Alarms tab (Basic analog type)

Used for: Analog, Discrete, and matching calculation modes

The basic version of this tab allows quick configuration of up to four alarms, two high-level and two low-level. Unlike the legacy Analog Status tag, you do not need to enable the alarm in addition to selecting a priority.

Do not configure an alarm for tags that write but do not read.

Basic mode of the Alarms tab for analog values. The Discrete mode includes the option of a State Alarm.

Priority

Use the drop-down tool to select the priority for each alarm that will be triggered by this tag. The available priorities are:

  • None
  • 0 - Event
  • 1 - Critical Alarm
  • 2 - High Alarm
  • 3 - Warning Alarm
  • 4 - Notice Alarm

If you have defined your own Alarm Priority Tags, those will also be available for selection.

Setpoint

Sample setpoints are provided, based on the default scale values of the tag. You must change these to the setpoints at which an alarm should be triggered. To link the setpoint to another tag or an expression, use the Advanced version of this tab.

Delay

To avoid nuisance alarms due to transient spikes in value, set a delay in seconds. The tag's value must reach or pass the setpoint for this length of time before an alarm occurs. To set a deadband on the value, use the Advanced version of this tab.

State (Discrete)

The state for which the alarm will occur.

I/O and Calculations tag: Alarms tab (Advanced type)

Content varies. Used for: Analog, Discrete, Digital, 2-bit Digital, and matching calculation modes

For all the following descriptions, assume that for each data type, the matching calculation mode also applies. For example, what applies to Analog also applies to Analog Calculation.

For Analog and Discrete, after switching to the advanced tab and making a configuration change, there is no option to switch back to the basic tab. If you use the advanced mode to do any alarm configuration, the basic option will no longer be available. If you close the properties dialog without doing advanced alarm configuration, then the basic tab will still be available the next time you open the dialog.

The following figure is a composite of all possible parameters.
No single version of the advanced Alarms tab includes all the parameters shown here.

A composite of all alarm parameters.
>> No single version includes all the parameters shown here <<.

Alarm (Analog, Discrete)

Select any of the four built-in alarms that are available for Analog and five for Discrete I/O types.

A Discrete I/O tag can be configured with high or low alarms like an Analog, or with a state alarm like a Digital.

Alarm (Digital, 2-bit Digital)

The only available choice is "State", meaning that alarms are triggered by a change to a defined state value.

String I/O types do not have built-in alarms.

Priority (All types)

Use the drop-down tool to select the priority for the selected alarm. This will also enable the alarm.

Delay (All types)

To avoid nuisance alarms due to transient spikes in value, set a delay in seconds. The tag's value must reach or pass the setpoint for this length of time before an alarm occurs.

Setpoint (Analog and Discrete)

The value at which the alarm will occur. An expression or tag can be used to create a variable setpoint for Analog or Discrete data types.

State (Digital and Discrete)

The state for which the alarm will occur. For Digitals, the triggering state may be [0] OFF, [1] ON, or [Upon Change].

For Discrete tags, it may be any value or Upon Change.

State (2-bit Digital)

The state for which the alarm will occur.
Options include [0] OFF, [1] ON, [2], [3] or [Upon Change]

Trip Alarm (Digital, 2-bit Digital, Discrete)

Select if this alarm is to be a trip alarm. When triggered, a trip alarm is not affected by the changing status of the equipment.

For comparison, a "level alarm" has an active state (the level is at or beyond the trip point) and a normal state (the level has returned to normal operating conditions.) A trip alarm simply trips and does not monitor whether the cause returns to normal operating conditions.

After being tripped, all visible and audible notifications will continue until an operator acknowledges the alarm.

Append State to Alarm Description (Digital, 2-bit Digital, Discrete)

When selected, the description found in the Alarm List will be appended with the state of the tag. This status will update for Alarm, Normal and Trip events.

Deadband (Analog and Discrete)

Does not change the setpoint. Use this to avoid nuisance alarms that activate and normalize due to a value that fluctuates into and out of the alarm condition as defined by the type and setpoint. The level must drop (or high alarms) or rise (for low alarms) by this much past the setpoint before the alarm condition is considered to have normalized.

Alarm Rearm Time (All types)

Measured in seconds. If a valid, non-zero value is given then if the alarm has been acknowledged, but remains active for the time shown in this field, the alarm will return to the unacknowledged state. Audible and visible warnings configured for this alarm’s priority level, will again be displayed.

Does not apply if Trip is selected. (Digital types only)

Alarm Disable (All types)

Select to flag the alarm as disabled without changing other configuration. Disabling of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine maintenance is being performed on the equipment represented by this tag, or when you are aware that another interruption in communications will occur for a period of time. In such situations, the alarm can be disabled until the maintenance is complete and communications are reestablished.

Many sites like to tie this property to Digital tag so that many alarms can be disabled at the same time for maintenance. That option is not available with the built-in alarms, but you could use Alarm Tag instead.

Disable or Enable Alarms Disable or Enable Alarms

Suppress

Create an expression or select a tag that will suppress the alarm when TRUE and unsuppress it when FALSE.

Suppress Alarms

In an I/O tag, there is only one Suppress parameter, and all configured alarms are suppressed or enabled with it. If you need to suppress some alarms that are triggered by an I/O tag but not others, consider using Alarm tags rather than built-in alarms.

Popup (All types)

The application property AlarmPopupsEnable must be set to 1 (Alarms Tab of the Edit Properties Page). If set, a pop-up dialog will be displayed whenever the respective alarm is triggered. This feature should be used sparingly.

Sound (All types)

The Sound field can be set to blank, 0, 1, or to the name of a .WAV sound file to be played.

  • If 0, no sound will be played when this alarm is triggered.
  • If blank or 1, an alarm sound whose properties are configured on the associated Alarm Priority tag will be played.
  • If the name of a .WAV sound file, it will override any alarm sound configured for the associated Alarm Priority tag. If the specified sound file is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

The .WAV file must be stored in the application folder and must be added to the application by using the Import File Changes Tool

Alarm Database

This tag will be auto linked to the closest ancestor or else sibling Alarm Database tag and the hierarchy. If none found, it will use the System Alarm Database.

Use this parameter to link the tag to an alternate Alarm Database of your choice.

Monitor the Alarm Status

Every tag has public variables that advanced developers can use in expressions or when working in the Idea Studio. Those properties are described here for the sake of providing full information.

Of particular note are the following variables that can be used to monitor the alarm status of an I/O tag.

HighAlarmActive | HighHighAlarmActive
HighAlarmUnacked | HighHighAlarmUnacked
LowAlarmActive | LowLowAlarmActive
LowAlarmUnacked | LowLowAlarmUnacked
AlarmActive (state alarms) | AlarmUnacked

Further information about how to refer to tag properties with expressions can be found in the topic, Automated Tag Configuration.

I/O and Calculations tag: Display tab

Layout and content varies by type

Display properties for analog data types including calculations.
Other data types will have fewer properties.

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Display Order

Common to all type selections. Used to specify the placement of this tag when viewed in a Site Details Page.

Digits After Decimal

Analog and Numeric Calculation. Limits the number of digits displayed after the decimal point wherever this tag is displayed, including the Historical Data Viewer. May be overridden in certain widgets. (See: Deadbands for Reading and Logging)

Engineering Units ((Analog, Discrete, and matching calculation modes)

Provide the units of measure that the scaled value represents. This text will be used by widgets that include engineering units as part of the display. Possible values for this field include "rpm", "degrees C", "%", etc.

You can add a degree symbol to the engineering units by holding down the Alt-key while typing 0176 on the numeric keypad. Release the Alt-key before typing the C or F.

Plot Line

Options in this section control how this tag's pen is shown in the Historical Data Viewer (HDV) and widgets that support I/O tag features such as Sparklines.

Use System Pens

If selected (default) no pen configuration from this tag is made available to the HDV. Widgets that can take display characteristics from the linked I/O tag will have that option disabled.
Deselecting this option does not force the HDV or linked widgets to use display settings from this tag.
Default values are assigned for the following:

Line Style

Analog, Discrete, Digital, 2-bit Digital, Numeric Calculation. Default appearance of the line when plotted in any version of the Historical Data Viewer. Defaults to a continuous line. May be overridden in any plot. Options include a variety of dash and dot combinations.

Line Width

Analog, Discrete, Digital, 2-bit Digital, Numeric Calculation. Default width of the line when plotted in any version of the Historical Data Viewer. Defaults to a single pixel. May be overridden in any plot, up to 9 pixels.

Color

Select the color to use when representing this tag in the HDV.

Display as Step Plot

Intended for Discrete data types. The lines drawn between data points will not be sloped. Changes in values will be practically vertical and plateaus will be horizontal. Like steps.

I/O and Calculations tag Widgets

All widgets that could be used for a numeric, digital or string value are available, but some may not be appropriate for a given configuration. It is up to you to select widgets that will work with a given I/O and Calculations tag. See: Widget Reference

Analog Bar & Indicator Widget

HP Radial Gauge

History Stats Value Widget

Sparklines Widget

Spider Graph Widget

I/O Multi-Text - Display predefined labels for matching discrete values

Toggle Button Widget

Toggle Switch Widget

Illuminated Toggle Switch Widget


Comparison of Analog Input Versus Analog Status Types

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

Analog Status and Analog Input tags are used for similar purposes. Both are used to monitor analog values and, with only one exception, the same widgets are available to each. Either could be used for the same PLC I/O address and when drawn on the screen, there is nothing to indicate which tag has been used.

A similar relationship exists between Digital Input and Digital Status tags.

A common question then is, "which type should I use?". The following comparison of features should help you choose. Any tag attribute not listed in the following table is the same for both.

Analog Input | Analog Status
No built-in logger | Logger built in, logging on change
No deadband option | Deadband option - used to set a minimum change required before logging a new value.
No built-in alarm | High and low alarms built-in.
Does not support history reads | Supports history reads when used with drivers that have this feature.
Not drawn on VTScada Station Pages | Drawn on VTScada Station Pages
Does not include the "Draw" widget | Includes the "Draw" widget
Can be linked to an "Owner" tag. | Does not have the "Owner" option.

The feature comparison shows that Analog Status tags have several advantages. There are more built-in features, reducing the need to use extra tags to provide logging and alarms. Analog Status tags also support history reads and are displayed on Station Pages. If you plan to use any of these features, then an Analog Status tag is probably your best choice.

Why then might you ever use an Analog Input tag? First, the dedicated Logging or Alarm tags that you add to an analog input will have more features and therefore more control than the built in logging and alarms of the Analog Status. Secondly, if you do not need the extra features of the Analog Status tag, the smaller Analog Input is a more efficient choice. Finally, for applications that have been coded to make use of tag aggregation, the Owner option of the Analog Input is an essential feature.

When you do add Analog Status tags to your application, there is one extremely important configuration option to remember: You should always set a value for the deadband. The automatic logging feature of these tags will add a new record each time the value changes, regardless of how small that change is. To avoid filling the log file with system noise, you should set the deadband to a small value, thus causing the tag to ignore any change less than this amount. For example, on a input that changes from 0 to 100, you might set the deadband between 0.1 and 1.

Related information:

Analog Input tag reference. Analog Input Tags

Analog Status tag reference. Analog Status Tags


Pulse Input Tags

Viewing: Reference > Tag Reference > Input Tags > Pulse Input Tags

Data Flow Pulse Input Tags

Counted towards your tag license limit.

Data Flow Pulse Input tags accept incoming analog data from a pulse input device (such as a rain gauge, transducer, or a gas, water, or electric meter).

The Pulse Input Tag was designed to work with the Data Flow driver and will not permit the selection of any other driver type.

Typically, the value sent is the number of tips of a rain collection device since the last poll. Use the scaling parameters of this tag to assign the relation between each tip of the device and the amount of rain measured.

After each poll, the driver will re-set to zero. Note: the driver provides no support for storing the last value sent. If a communication error prevents a value from being sent on any given poll interval, that value is lost.

Values from the Data Flow Pulse Input can be displayed using the Totalizer widget, which includes a configuration option to reset the value back to zero every N hours. There is also a report - The Rainfall Report - designed for use with the Data Flow Pulse Input tag.

It is not uncommon to want to trigger an alarm when the rainfall rate exceeds a certain amount. For that purpose, you should use a History Statistics tag's Totalizer option as the trigger for the alarm. The Data Period parameters of the History Statistics tag should be set short enough to give a frequent-enough update but remain in the Update Interval long enough so as not to overload the system. For every Update Interval, the history of the tag must to be accessed from disk. Suggested starting values are to use the latest 1 hour with an update rate of 5 minutes. An alarm can be attached to the History Statistics tag to check if the total rainfall per hour (assuming that the "Latest" parameter is set to 1 hour) exceeds a limit.

Related information:

Best Practices for Tags

Closed Pulse Input tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Data Flow Pulse Input properties I/O tab

The I/O tab holds the properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU), or to the polling driver responsible for determining the order and rate at which data polls will occur.

I/O Device

A Data Flow Driver is required for this tag to function as a pulse input.
If a different type of driver is chosen, this tag will approximate the behavior of an Analog Input. It works as a pulse input only when linked to a Data Flow driver.

Address

Provide the address within the I/O device from which this tag is to read data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

If a Write Address is provided the Read Address is used only as feedback and will set the value of the tag regardless of the value written. If the value in the Read Address does not match the value written then the tag's Mismatch flag is set to true and will be reflected in linked widgets, either as a blink or a mismatch color, according to the widget.

Address Assist: (...)

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the Address Assist dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your Communication Driver Tags for more information.

Scan Interval

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Engineering Units

Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

Data Flow Pulse Input properties Scaling tab

The Scaling tab requires a scaled value that will be counted per incoming pulse.

Data Flow Pulse Input properties Quality tab

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

This tab also contains the Quality Based On field, for use when this tag is to be a contributor to a custom-built container tag. Please see the topic Merit tab and Quality tab, for details.

Data Flow Pulse Input properties Display tab

The Order tab for a Pump Status tag enables you to specify the placement of this tag when viewed in an associated station dialog.

Data Flow Pulse Input properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Closed Data Flow Pulse Input Tag Widgets

The following widgets are available to display information about your application’s Data Flow Pulse Input tags:

Alarm Priority Box

Alarm Priority Icon

Draw Widget

Totalizer Widget


Output Tags

Output tags are used to write data to an I/O device, such as a programmable logic controller (PLC), remote terminal unit (RTU), or an I/O board. These tags permit the handling of either digital (discrete), or analog (continuous floating point) values.

Output tags will not write INVALID data. (INVALID is a specific VTScada data type, roughly meaning, "no valid value available"). Also, except for the MultiWrite tag, no output type will write an unchanged value twice unless directed by the driver performing a "re-write outputs" operation.

Record Operator-Entered Values

While the output tags are designed to write to a device, they can also be used to record purely operator-entered values. For example, an operator may be asked to read a value from a device that is not connected to the automation system and record that value in a place where it can be included in the SCADA system's reports.

To record operator-entered values:

  1. Create an Analog Control tag.
    The name and description should match the information that is to be recorded.
    Do not configure an I/O device or address.
    Ensure that the scaled minimum and maximum values allow the full range of expected numeric values. (The Operator Notes page exists to record text.)
  2. Add a Logger tag to the Analog Control.
    Select the option, Log on Change as well as Time.
    Set the Log Range Interval to a very large value (for example, 3153600000 == 100 years). This ensures that a value will be written to the Historian only upon operator entry.
  3. Draw the Analog Control tag on a page as a Numeric Entry widget, having a relevant label. Operators should note that it is necessary to press enter, or tab away from the data entry field before the value will be saved.

Each time the operator enters a new value, it will be written to the Historian, and may be used in trend graphs and reports. Note that a click on any widget linked to an output tag does not open the trend window.

The following output tags are included with VTScada:

I/O and Calculations Tag
Analog Control Tags | Analog Output Tags
Deadband Control Tags | Digital Control Tags
Digital Output Tags | Multi-Write Tags
Selector Switch Tags | Trigger Tag
String I/O Tags |

Related information:

Communication Driver Tags - Driver tag reference

The Tag Browser - Using the Tag Browser to create and edit tags.

Deadbands for Reading and Logging - Avoid problems with system noise.


I/O and Calculation Tags

Counted towards your tag limit if configured to read or write.

Does not count towards your tag limit if configured to calculate without an output address.

This replaces many legacy tags, including: Analog Input, Analog Output, Digital Input, Digital Output, Analog Status, Analog Control, Digital Status, Digital Control, Pump Status, String I/O, Calculation and Function. While those tags will always be supported, you are advised to use the I/O and Calculations tag in their place for all new development work.

The replaced tags are available only in the "All Tag Types" and the "Legacy I/O and Calculations" groups of the Tag Browser.

Within this topic:

ID Tab

I/O Tab Version 1. Analog, Discrete and String

I/O Tab Version 1. Digital

I/O Tab Version 2. 2-bit Digital

Calculations Tab

Quality Tab

Scaling Tab

Logging Tab

Alarms Tab, Basic View

Alarms Tab, Advanced View

Display Tab

Widget List

Read / Write

If both a read address and a write address are defined and valid, then the read address is used only for feedback and is the only value shown as the value of the tag. If the value at the read address differs from the value written, the tag's Mismatch variable is set to TRUE, as reflected in widgets linked to this tag. The value at the read address is NOT sent to the write address on change.

If there is a write address and no read address, then the value of the tag will reflect the last value that was written. This is true for all data types. Use care however: this does not provide the same information as you would get from having a read address. Without feedback, you know only what the SCADA system attempted to send, not what the state is at the equipment.

If an I/O tag is configured as a Calculation and an output address is provided, each new value calculated will be written to that address. The value will be forced to the data type of the tag. If the data type is numeric, but the expression returns text, nothing will be written. If the data type is discrete, but the expression returns a floating point result, only the integer portion will be written.

The presence of Read, Write and History addresses are indicated in the Tag Browser by bracketed labels after the type. The order of the labels matches the order of the address. For example, in the following figure, the High Alarm has both a read address (40021) and a write address (40019).

The address of a calculation mode is shown as [Calc] or [Calc/Out]. Memory tags, which have no addresses, are shown as [Mem]

Related Information:

Deadbands for Reading and Logging - Avoid problems with system noise.

Memory Tags

If an I/O and Calculation tag does not have a configured address (read, write or history) then it does not count against your tag license. This configuration can be valuable as a "memory tag", which holds a value that is provided by an operator via a widget. The data type can be Analog, Discrete, Digital, or String.

Because memory tags do not write to an address in hardware, it is possible to set their value to Invalid. This can be controlled with the option, "Allow value to be cleared", which is visible in the I/O tab only when no address has been configured. This option also affects certain widgets such as the Droplist Widget, which will show "No Data" (value: Invalid) only if the memory tag can have its value cleared.

2-bit Digital, and all Calculation options of the I/O tag do not count as Memory Tags.

Operators can set the value of a memory tag using any of the standard control widgets. It is also possible to set the values of multiple memory tags in a single operation by using Multi-Write Tags

Memory tag values will persist across application restarts. You can configure a default (initial) value for a memory tag using the input field "Default Memory Value" on the I/O tab, but only if "Allow value to be cleared" is not selected.

Only I/O tags that have an address (read or write) count against your tag license. Memory tags have no address and therefore do not count.

Group Membership

The Historical Data Viewer, Reports Page, and other tools that list tags allow you to sort and filter by "group", where a group may be "analogs", "digitals", "loggers", etc.

Any given I/O and Calculations tag's group membership depends on how you configured it. The rules are:

  • Inputs group: The tag has a valid Read or History address, or it is a 2-bit Digital.
  • Outputs group: The tag has a valid write address, (2-bit digitals are never in the Outputs group.)
  • Loggers group: All I/O and Calculation tags.
  • Analogs and Numeric groups: This includes all Analog, Discrete, and their calculation modes.
  • Analytics group: This includes all calculation modes.
  • Digitals and Numeric groups: This includes all Digital and 2-bit Digital IO tags and their calculation modes.
  • Strings group: String and String Calculation mode IO tags

I/O and Calculations tag properties: ID tab

Closed Name, Area, Description

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Data Type

While the I/O and Calculations tag replaces many types, you must specify how each one is to be used. The data type selection controls the tag's behavior and the configuration options.

Configuration options vary according to the data type that you choose in the ID tab of the properties dialog. In the following notes, you may need to look up or down within a section to find the version that matches the mode you are configuring.

Data Type | Details | Select when you need to...
Analog | Analog (Doubles and floating point) | Read or write values that scale such as temperature or volume. If a deadband is not applied on the logging tab, a default deadband of 0.25% of the scaled range is applied. This value is stored in the application property DefaultAnalogDeadbandFractionOfFullScale
Discrete | Analog (Integers) | Read or write a set of known values, which may scale.
Digital | Digital (Binary values, 0 or 1) | Read or write a value of 1 or 0 from a single address.
2-Bit Digital | Digital (Binary values 00 to 11 (0 to 3)) | Read a value of 1 or 0 from two address, making this a 4-state digital. Cannot write values to either address.
String | Note (Text) | Read or write a text value. Output padding is handled by widgets rather than the I/O tag.

Within reason, you can change the data type after creating a tag. If after configuring for one data type, you select another, configuration options that do not apply to the new type are saved but not used. For example, you might initially define the tag as Analog and set scaling parameters. If you change the data type to Digital, the scaling tab is hidden and the scaling parameters are not used, but the values you set will be retained.

Calculation

For any data type, there is a Calculation option. This counts as a separate but matching mode for each listed in the drop-down. (So, Analog -> Analog Calculation)

Use this when you intend to create an expression that will be set the tag's value (or select another tag that this one should mirror). When creating a calculation, the choice of data type affects the values that can be returned by the expression and the set of widgets that can be used to display that value.

  • Calculation results can be written to an output address, in which case the tag will count towards your tag license.
  • Calculations that do not write to an output address do not count towards your license.
  • Any I/O tag with the Calculation mode set does not count as a memory tag. (Memory Tags)
  • Calculations do not retain their value across restarts. Use a legacy Analog Status (Analog Status Tags) or Digital Status (Digital Status Tags) if that feature is required.
  • In applications that run on multiple workstations, calculations are performed locally on each workstation unless the synchronize option (Sync) is selected. Either mode may be appropriate depending on the purpose of the calculation.
Mode Select when you need to...

Analog Calculation

Calculate a numeric value.

Does not read from hardware but may use the value of other tags that do.

Can write to hardware.

Discrete Calculation

Calculate a value from a set of known values.

Does not read from hardware but may use the value of other tags that do.

Can write to hardware.

Digital Calculation

Calculate a digital value.

Does not read from hardware but may use the value of other tags that do.

Can write to hardware (1, 0, or pulse)

2-Bit Digital Calculation

Calculate a 2-Bit digital value. (0 to 3)

Does not read from hardware but may use the value of other tags that do.

Can write to hardware (single address).

String Calculation

Calculate a text value.

Does not read from hardware but may use the value of other tags that do.

Can write to hardware.

Some changes of I/O type may harm other work. For example, assume that you have a tag configured as an Analog and drawn using a gauge. If you change the type to String, the gauge will be broken since it cannot display a text value. Note the mode for each data type as given in the preceding table. Changes from one to another data type are likely to cause problems.

Data logged for one data type may not be appropriate for another. Nothing will be lost, but a report for a digital such as "Pump run time" cannot show data logged while the tag was of type String.

HDV plots may need to be reconfigured. If the tag was plotted as a digital, it will not automatically switch to analog.

Work to avoid any need to change the data type of your I/O tags.

Equipment Type

Provides a way to categorize tags that is similar to the Area property but more powerful.

When used with Discrete or Digital I/O types, you can create style for your equipment type that assigns a label and color for each possible value of your tag. This may be especially useful when combined with I/O Multi-Text or the Droplist Widget.

One default type is provided: "Pump". This is used in the Reports page as a filter for the Pump Activity and Pump Discrepancy reports. You can filter based on equipment type in any tag list. Advanced users can create reports or other tools that use Equipment Type as a filter.

You are free to create as many equipment types as you need, and you may do so from within either an I/O tag on the ID tab or a Style Settings tag on the Equipment tab. The instructions are the same in both cases:

  1. Place the cursor in the Equipment Type field.
    (It does not matter whether the field is blank or shows an existing type.)
  2. Type the name of your new equipment type.
  3. Press the [tab] or [Enter] key on the keyboard.
  4. Click the Apply button.
    The new type is saved.
    If the field had shown an existing type before you started, it is not changed.

Equipment type names can be removed the same way that Area properties are removed: First ensure that the name is not in use within any tag, then restart the application.

The Equipment Type of an I/O and Calculations tag is a powerful feature when used with care. Do not assign Equipment Types casually, without a clear plan for how you intend to use this feature.

I/O and Calculations tag properties: I/O tab

The layout for Analog and Discrete modes is described first.
Scroll down for the String and Digital modes.

Link to a driver, configure addresses and scan interval, deadband, privileges, link and enable or disable publishing

I/O tab for Analog and Discrete modes

I/O Device (Required)

Select the communication driver tag that data will be read from or written to.

By default, the tag will look for a parent tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver's properties dialog.

Read Address (Optional.)

Provide the address within the I/O device from which this tag is to read data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

If a Write Address is provided the Read Address is used only as feedback and will set the value of the tag regardless of the value written. If the value in the Read Address does not match the value written then the tag's Mismatch flag is set to true and will be reflected in linked widgets, either as a blink or a mismatch color, according to the widget.

Address Assist: (...)

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the Address Assist dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your Communication Driver Tags for more information.

Scan Interval (Read scan interval. Applies only if a Read Address is provided.)

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Deadband (On data reading, for Analog values only)

If defined, the value on the device must change by more than this amount before the tag will register it as a new value. A deadband can greatly improve application efficiency by filtering out noise and eliminating unnecessary work to process that noise as if it were useful data.

The deadband is an absolute value, not a percentage, and is specified in terms of the tag's display values if set or the scaled engineering units otherwise. (Refer to notes for the Scaling tab.) If a deadband value is not provided, one will be calculated automatically based on several factors including the logging deadband and the application property, DefaultDriverDeadbandFractionOfFullScale.

See also: Deadbands for Reading and Logging

History Address (Optional. Use only with devices that support this feature.)

If set, then the Read address field becomes optional. This field provides a means of reading values as recorded by a data logger.

If both the read address and the history address are provided, then the read address will be polled for data at the set interval, but the values read from the history address will override the values logged from the read address.

If the identical address is provided for both read and history, then only the read address is used. History values will not be recorded.

The form for the history address will depend on the RTU. Please refer to the addressing reference chapter for your driver.

Typically, history data arrives as an array. If sent to the Read address of an input tag, only the first element is read and the rest discarded. History data must be sent to the History address in order to be fully recorded.

Note that it is not possible to enter a parameter expression directly in the History Address field. As an alternative, you may enter compound address in the Address field using a parameter expression. For example, if Addr, HistAddr and HistoryRate are all properties of a parent tag, the following expression in the Address field will create a compound address with all three components:

concat(.\Addr , "):(" , .\HistAddr , "):(" , .\HistoryRate )

The characters "):(" separate each component of the address. Do not add a leading or trailing parenthesis around the entire expression.

Further information on reading history information can be found in the topic SCADAPack History Read

For numeric values (not String), a deadband is applied automatically to the values read on the History Address. The calculation uses the application property, DefaultAnalogDeadbandFractionOfFullScale.

CalculatedHistDeadband = PickValid(Threshold, (HighScaleValue - LowScaleValue) * \DefaultAnalogDeadbandFractionOfFullScale, 0);

Scan Interval (History scan interval. Applies only if a History Address is provided.)

Sets the time between polls of the history data logger. If a History address has been set, but this field is left blank, then it will default to the value set in the Scan Rate field. The recommended value for this field is 60 seconds. Lesser values may cause communications to slow down.

Write Address (Optional. Do not configure for tags that are input-only.)

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Privilege (Applies only if a Write Address is provided)

Limit the ability to write using this tag to only those operators who have been granted the selected custom privilege. See: Restrict Access to Output Tags

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Allow value to be cleared

Enabled only for memory tags (I/O tags with no read or write address). When selected, widgets such as the Droplist Widget can show No Data (value: Invalid) as a option.

Default Memory Value

Can be used to set a default value when this tag is configured as a Memory tag (Memory Tags). This option cannot be used when Allow value to be cleared is selected.

I/O Tab, String data type layout

Variation for Strings, showing options for output padding and storage in registers

Pad with spaces

Enabled only after a Write Address has been entered. If selected, you will have the option of specifying a minimum length for output strings. Values shorter than this will be padded with spaces according to the selected Justify option.

String stored in registers

Select this option if reading a string from a series of numeric registers in PLCs such as Modbus or Delta, where the characters are encoded in the register values. This option requires the length of the string to be set so the tag can know how many registers to read or write.

Minimum Length

Enabled only after "Pad with spaces" or "String stored in registers" is selected.

  • When used for Pad with spaces, this sets the minimum length for output strings.
  • When used for String stored in registers, this sets the size of the string in bytes to ensure the proper number of registers are read to read the string.

Justify

Controls whether spaces are added to the left, the right or both sides of output text in order to achieve the required minimum length.

Reading Strings

If reading string data, note that not all PLCs will store characters in the same in order in registers. Further, registers may vary in size from one PLC type to another.

If the string read from your registers has characters that are not in the order you expected, use the BuffOrder() function in an expression to swap the order of the characters so that they do match what is expected. Do this by creating one I/O and Calculations tag to read the value, then create a second with an expression to read the value in the first and apply the BuffOrder function. The second I/O and Calculations tag will not count against your license because it does not use a read or write address.

Better practice is to program the PLC to send an integer code that can be mapped to a phrase in VTScada. The result can be used in a multilingual application and can reduce the amount of data transmitted.

Example: A BuffOrder call for a word-sized register with the character order swapped:

BuffOrder([<SourceTag>], 0, 1, 2, N)

...where the value N should be the half the length of the buffer.

I/O Tab, Digital layout

I/O tab for the Digital data type

Variations in this mode are as follows:

  • No Deadband values
  • Addition of the Invert Input and Invert Output
  • Addition of a pulsed output option

Pulse Duration

The pulse duration can be no less than 0 and no greater than 86400 (one day)

When set to a positive, non-zero number, the tag will a specified signal (1 or 0) to the Write Address, then retain that value for the number of seconds specified by the duration. At the end of that time, the opposite value is sent to the write address and the tag's value returns to its normal state.

For example, if a linked button widget is configured to write a 1, this tag will write the value 1 when the button is pressed and will hold the value 1 for the specified duration. At the end of the duration, a 0 is written and the tag's value returns to 0. Writing a zero using a second button linked to the same tag has no effect, except in the case that a pulse is in progress, in which case it will cancel the pulse.

If Invert Output is selected, then this tag's base state is 1 and it can be used to write a 0 (zero).

Triggering a pulse repeatedly will reset the timer with each press of the button. This allows a long pulse to be sent, but the pulse following the last button press will be no longer than the set duration.

Invert Input

If the Invert Input check box is selected, the value of the tag being used as the data source is reversed (i.e. a 1 becomes a 0 or a 0 becomes a 1).

Invert Output

If selected, the value being written is reversed (i.e. a 1 becomes a 0 or a 0 becomes a 1).

If the read address is the same as the write address, or the read address is blank and the history address is the same as the write address, then the Invert Output field will be disabled and the value will be set to the same value as Invert Input, preventing a mismatch.

I/O and Calculations tag properties: ID tab version 2

Used for: 2-bit Digital

2-bit Digitals can only read. Do not use for tags that must write. There is no option to read from a History address with a 2-bit Digital.

The reported value is the data at the Bit 0 address plus two times the data at the Bit 1. If the Bit 0 Address field does not contain a valid address, this tag will not read.

I/O tab, only for 2-bit Digitals

I/O Device (Required.)

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Bit 0 Address (Required.)

The Bit 0 Address property is the address of the low order bit for this tag in the I/O device.

Bit 1 Address (Required.)

The Bit 1 Address property is the address of the high order bit for the digital input in the I/O device.

Address Assist

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your driver for more information.

Scan Interval (Required.)

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

I/O and Calculations tag: Calculation tab

Used for: All Calculation modes

There are three versions of this tab, depending on the data type of the tag. Select the one you are interested in from the following drop-downs.

It is important that the calculation expression match the data type. For example, a digital calculation expression should have a value of 0 or 1. Proper behavior cannot be guaranteed unless the result matches the tag's data type. For example, a text expression for a discrete data type will resolve to an Invalid.

If the Sync Calculation option is not selected, Calculations are performed locally on each machine running the application and are not synchronized between machines.

To protect your system, changes in numeric calculations are subject to the built-in deadband, DefaultCalculationDeadbandFractionOfFullScale

Closed Analog and Discrete version of the Calculation tab:

Closed Digital and Two-bit Digital version of the Calculation tab:

Note that Value is a binary choice when set to Constant. Select Expression to open the usual expression field and editor button.

Closed String version of the Calculation tab:

Calculation

Holds the expression that this tag should calculate. (Expressions) While you can specify a constant or select another tag to mirror it's value, in most cases you will select the Expression option, then click on the [image] button in order to open the expression editor.

In calculation mode, the I/O tag does not retain its value across application restarts. If this is required, use the legacy Analog Control Tags.

Sync Calculation

The default is for calculations to be done on each local machine. If Sync Calculation is selected, the calculation is performed only on the current server and the value broadcast to other machines. "Current server" means the server for the parent driver tag, if there is one. If no valid driver is specified for the I/O tag, calculations are not synchronized.

I/O Device (Optional)

Select the communication driver tag that data will be read from or written to.

By default, the tag will look for a parent tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver's properties dialog.

Address (Optional)

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Deadband (Numeric and Discrete Calculation only. Optional.)

Changes in value smaller than this are not written by the tag.

Expected Range - Min and Max (Numeric and Discrete Calculation only. Optional.)

Used to provide default minimum and maximum values to certain widgets. (The Numeric Calculation type does not have a scaling tab, where these values would otherwise be set.)

By definition, an expected range should not overlap an alarm setpoint. If you do configure an overlap, do not expect both to show in any widget.

Pulse Duration (Digital Calculation only. Optional)

When set to a positive, non-zero number, the tag will send a specified signal (1 or 0) to the Write Address, then retain that value for the number of seconds specified by the duration. At the end of that time, the opposite value is sent to the write address and the tag's value returns to its normal state.

An important distinction from the Digital data type is that the calculation tag’s value does not return to its original state once the pulse its done (just the written value). To reset the pulse for a digital calculation, the expression’s value must go to 0 and then back to 1. This means that triggering a pulse repeatedly does not create a single long pulse, as in the normal digital case.

Invert Output (Digital Calculation only. Optional)

If selected, the a calculated state of the tag of 1 write as 0.

Privilege (Applies only if a Write Address is provided)

Limit the ability to write using this tag to only those operators who have been granted the selected custom privilege. See: Restrict Access to Output Tags

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

I/O and Calculations tag: Scaling tab

Used for: Analog and Discrete

Only the first four fields affect the value.

I/O scaling illustrated

VTScada assumes a linear relationship between the values as shown. The scaled and unscaled process values you provide set the slope of the line, allowing any value on one axis to be mapped to the other.

The values do not limit what the tag can read, but the Scaled Process Min and Max values do limit what the tag can write.

Min and Max Unscaled Process Data (Required.)

Use these to tell VTScada the range of raw values to expect from or write to hardware.

Min and Max Scaled Process Data (Required.)

These values must match the Unscaled Min and Max values. VTScada uses them to convert between the engineering units shown in the SCADA system and the raw values read from or written to the hardware. By default, the "Limit outputs to within Scaled min/max" option is selected. If you deselect this option, the output range limit is disabled. This allows any value, including negative integers, to be sent to the tag. However, scaling is still applied to the new output value, regardless of the value sent to the tag.

Display Range Min and Max (Optional.)

These two fields have no effect on the value of the tag.

Set the Min and Max Display Range values to define the default scale range for the HDV trend view and certain widgets, such as the various meters. Use these when values are expected to stay within a portion of the full scale range and it is therefore helpful to adjust the displayed range as needed.

If left blank, the Scaled Process Data Min and Max values will be used as the Display Range values.

Expected Range Min and Max (Optional.)

These two fields have no effect on the value of the tag.

Used to provide default minimum and maximum values to certain high performance graphics widgets. If left blank, the expected range feature of those widgets is not drawn. Both must be provided.

The expected range is shown in pale blue.
The color is controlled by the assigned Style Settings tag.

I/O and Calculations tag: Quality tab

Used for: All types

Quality tab for all types.

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

If the tag is configured with an output address, and (in the case where this tag is protected by a user-defined security privilege) if the person configuring the Manual Data value has required privilege, then the manual data value will be written to the defined output address.

In the case where the I/O tag was configured as a Calculation, the manual data value will override any expression value .

Quality Based on

The Quality Based On field can be tied to a driver tag, a tag that monitors driver communication errors, a register in the PLC or RTU, or any other indication of system health. The tag you are configuring will use that value to set an internal variable named QualityIssue. You may test this value in an expression: [TagName]\QualityIssue.

QualityIssue will be a 0 or 1 where "Good Quality" is defined as a value of "0 or Invalid" and "Bad Quality" is defined as any valid, non-zero value. This is consistent with driver communication error values.

Widgets that use the System Style tag will display bad quality using the color set on the Exceptions tab.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

I/O and Calculations tag: Logging tab

Used for: All types

Logging tab for all types

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Enable Logging

If values should be logged only while certain conditions are true, you can tie the Enable Logging option to any tag or expression that will change from zero (logging disabled) to 1 (logging enabled). Do so by right-clicking on the Enable Logging check box and creating a parameter expression. The "Optimize..." option in the expression should be deselected. For detailed instructions (and important warnings) see: Automated Tag Configuration.

Minimum Log Interval

Here, "Interval" refers to time measured in seconds. If set to a valid number greater than zero, and if the tag has a valid value, that value will be recorded to the history every interval, regardless of whether it has changed from the last write.

In most cases, this should be left blank, allowing values to be written on change larger than the specified deadband.

As of release 12.1.42, logging of I/O tags has changed as follows: Values will be logged on interval OR on change but not both. If both are needed, create a second (free) I/O tag using an expression that watches the value of the first tag. Log the first on interval and the second on change. Attempting to do both on the same tag introduces a small but important risk of values being recorded out of sequence if the remote device is sending timestamped data and its clock is not synchronized with the server.

Deadband (Analog, Discrete, and matching calculation modes only)

Every change in value will be written to the Historian. You are advised to set a deadband so that you do not fill the log with small changes that amount to system noise. (See: Deadbands for Reading and Logging)

When using the Analog data type, a default deadband of 0.25% of the display range if set and the scaled range otherwise. This value is stored in the application property DefaultAnalogDeadbandFractionOfFullScale

I/O and Calculations tag: Alarms tab (Basic analog type)

Used for: Analog, Discrete, and matching calculation modes

The basic version of this tab allows quick configuration of up to four alarms, two high-level and two low-level. Unlike the legacy Analog Status tag, you do not need to enable the alarm in addition to selecting a priority.

Do not configure an alarm for tags that write but do not read.

Basic mode of the Alarms tab for analog values. The Discrete mode includes the option of a State Alarm.

Priority

Use the drop-down tool to select the priority for each alarm that will be triggered by this tag. The available priorities are:

  • None
  • 0 - Event
  • 1 - Critical Alarm
  • 2 - High Alarm
  • 3 - Warning Alarm
  • 4 - Notice Alarm

If you have defined your own Alarm Priority Tags, those will also be available for selection.

Setpoint

Sample setpoints are provided, based on the default scale values of the tag. You must change these to the setpoints at which an alarm should be triggered. To link the setpoint to another tag or an expression, use the Advanced version of this tab.

Delay

To avoid nuisance alarms due to transient spikes in value, set a delay in seconds. The tag's value must reach or pass the setpoint for this length of time before an alarm occurs. To set a deadband on the value, use the Advanced version of this tab.

State (Discrete)

The state for which the alarm will occur.

I/O and Calculations tag: Alarms tab (Advanced type)

Content varies. Used for: Analog, Discrete, Digital, 2-bit Digital, and matching calculation modes

For all the following descriptions, assume that for each data type, the matching calculation mode also applies. For example, what applies to Analog also applies to Analog Calculation.

For Analog and Discrete, after switching to the advanced tab and making a configuration change, there is no option to switch back to the basic tab. If you use the advanced mode to do any alarm configuration, the basic option will no longer be available. If you close the properties dialog without doing advanced alarm configuration, then the basic tab will still be available the next time you open the dialog.

The following figure is a composite of all possible parameters.
No single version of the advanced Alarms tab includes all the parameters shown here.

A composite of all alarm parameters.
>> No single version includes all the parameters shown here <<.

Alarm (Analog, Discrete)

Select any of the four built-in alarms that are available for Analog and five for Discrete I/O types.

A Discrete I/O tag can be configured with high or low alarms like an Analog, or with a state alarm like a Digital.

Alarm (Digital, 2-bit Digital)

The only available choice is "State", meaning that alarms are triggered by a change to a defined state value.

String I/O types do not have built-in alarms.

Priority (All types)

Use the drop-down tool to select the priority for the selected alarm. This will also enable the alarm.

Delay (All types)

To avoid nuisance alarms due to transient spikes in value, set a delay in seconds. The tag's value must reach or pass the setpoint for this length of time before an alarm occurs.

Setpoint (Analog and Discrete)

The value at which the alarm will occur. An expression or tag can be used to create a variable setpoint for Analog or Discrete data types.

State (Digital and Discrete)

The state for which the alarm will occur. For Digitals, the triggering state may be [0] OFF, [1] ON, or [Upon Change].

For Discrete tags, it may be any value or Upon Change.

State (2-bit Digital)

The state for which the alarm will occur.
Options include [0] OFF, [1] ON, [2], [3] or [Upon Change]

Trip Alarm (Digital, 2-bit Digital, Discrete)

Select if this alarm is to be a trip alarm. When triggered, a trip alarm is not affected by the changing status of the equipment.

For comparison, a "level alarm" has an active state (the level is at or beyond the trip point) and a normal state (the level has returned to normal operating conditions.) A trip alarm simply trips and does not monitor whether the cause returns to normal operating conditions.

After being tripped, all visible and audible notifications will continue until an operator acknowledges the alarm.

Append State to Alarm Description (Digital, 2-bit Digital, Discrete)

When selected, the description found in the Alarm List will be appended with the state of the tag. This status will update for Alarm, Normal and Trip events.

Deadband (Analog and Discrete)

Does not change the setpoint. Use this to avoid nuisance alarms that activate and normalize due to a value that fluctuates into and out of the alarm condition as defined by the type and setpoint. The level must drop (or high alarms) or rise (for low alarms) by this much past the setpoint before the alarm condition is considered to have normalized.

Alarm Rearm Time (All types)

Measured in seconds. If a valid, non-zero value is given then if the alarm has been acknowledged, but remains active for the time shown in this field, the alarm will return to the unacknowledged state. Audible and visible warnings configured for this alarm’s priority level, will again be displayed.

Does not apply if Trip is selected. (Digital types only)

Alarm Disable (All types)

Select to flag the alarm as disabled without changing other configuration. Disabling of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine maintenance is being performed on the equipment represented by this tag, or when you are aware that another interruption in communications will occur for a period of time. In such situations, the alarm can be disabled until the maintenance is complete and communications are reestablished.

Many sites like to tie this property to Digital tag so that many alarms can be disabled at the same time for maintenance. That option is not available with the built-in alarms, but you could use Alarm Tag instead.

Disable or Enable Alarms Disable or Enable Alarms

Suppress

Create an expression or select a tag that will suppress the alarm when TRUE and unsuppress it when FALSE.

Suppress Alarms

In an I/O tag, there is only one Suppress parameter, and all configured alarms are suppressed or enabled with it. If you need to suppress some alarms that are triggered by an I/O tag but not others, consider using Alarm tags rather than built-in alarms.

Popup (All types)

The application property AlarmPopupsEnable must be set to 1 (Alarms Tab of the Edit Properties Page). If set, a pop-up dialog will be displayed whenever the respective alarm is triggered. This feature should be used sparingly.

Sound (All types)

The Sound field can be set to blank, 0, 1, or to the name of a .WAV sound file to be played.

  • If 0, no sound will be played when this alarm is triggered.
  • If blank or 1, an alarm sound whose properties are configured on the associated Alarm Priority tag will be played.
  • If the name of a .WAV sound file, it will override any alarm sound configured for the associated Alarm Priority tag. If the specified sound file is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

The .WAV file must be stored in the application folder and must be added to the application by using the Import File Changes Tool

Alarm Database

This tag will be auto linked to the closest ancestor or else sibling Alarm Database tag and the hierarchy. If none found, it will use the System Alarm Database.

Use this parameter to link the tag to an alternate Alarm Database of your choice.

Monitor the Alarm Status

Every tag has public variables that advanced developers can use in expressions or when working in the Idea Studio. Those properties are described here for the sake of providing full information.

Of particular note are the following variables that can be used to monitor the alarm status of an I/O tag.

HighAlarmActive | HighHighAlarmActive
HighAlarmUnacked | HighHighAlarmUnacked
LowAlarmActive | LowLowAlarmActive
LowAlarmUnacked | LowLowAlarmUnacked
AlarmActive (state alarms) | AlarmUnacked

Further information about how to refer to tag properties with expressions can be found in the topic, Automated Tag Configuration.

I/O and Calculations tag: Display tab

Layout and content varies by type

Display properties for analog data types including calculations.
Other data types will have fewer properties.

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Display Order

Common to all type selections. Used to specify the placement of this tag when viewed in a Site Details Page.

Digits After Decimal

Analog and Numeric Calculation. Limits the number of digits displayed after the decimal point wherever this tag is displayed, including the Historical Data Viewer. May be overridden in certain widgets. (See: Deadbands for Reading and Logging)

Engineering Units ((Analog, Discrete, and matching calculation modes)

Provide the units of measure that the scaled value represents. This text will be used by widgets that include engineering units as part of the display. Possible values for this field include "rpm", "degrees C", "%", etc.

You can add a degree symbol to the engineering units by holding down the Alt-key while typing 0176 on the numeric keypad. Release the Alt-key before typing the C or F.

Plot Line

Options in this section control how this tag's pen is shown in the Historical Data Viewer (HDV) and widgets that support I/O tag features such as Sparklines.

Use System Pens

If selected (default) no pen configuration from this tag is made available to the HDV. Widgets that can take display characteristics from the linked I/O tag will have that option disabled.
Deselecting this option does not force the HDV or linked widgets to use display settings from this tag.
Default values are assigned for the following:

Line Style

Analog, Discrete, Digital, 2-bit Digital, Numeric Calculation. Default appearance of the line when plotted in any version of the Historical Data Viewer. Defaults to a continuous line. May be overridden in any plot. Options include a variety of dash and dot combinations.

Line Width

Analog, Discrete, Digital, 2-bit Digital, Numeric Calculation. Default width of the line when plotted in any version of the Historical Data Viewer. Defaults to a single pixel. May be overridden in any plot, up to 9 pixels.

Color

Select the color to use when representing this tag in the HDV.

Display as Step Plot

Intended for Discrete data types. The lines drawn between data points will not be sloped. Changes in values will be practically vertical and plateaus will be horizontal. Like steps.

I/O and Calculations tag Widgets

All widgets that could be used for a numeric, digital or string value are available, but some may not be appropriate for a given configuration. It is up to you to select widgets that will work with a given I/O and Calculations tag. See: Widget Reference

Analog Bar & Indicator Widget

HP Radial Gauge

History Stats Value Widget

Sparklines Widget

Spider Graph Widget

I/O Multi-Text - Display predefined labels for matching discrete values

Toggle Button Widget

Toggle Switch Widget

Illuminated Toggle Switch Widget


Multi-Write Tags

Not counted towards your tag license limit.

The MultiWrite tag will write predefined values to a list of selected tags upon triggering. This can be used to place a plant into a state of operation or to quickly shut a plant down in one step.

Trihedral technical support frequently receives requests for help with scripting when people want to send a control signal in response to a trigger. The response is almost always to use a Multi-Write tag in place of a script.

Reference Notes:

Up to 100 output and memory tags can be controlled by a single MultiWrite tag, with a defined value set to be written to each. The trigger for the write may be any of a manual button press, a tag that changes state from false to true, or an expression that evaluates to true.

Each value to be written will be checked to ensure that it is valid before it is written. Invalid writes will be ignored. All valid values will be written, regardless of whether they have changed since the last write.

Should 100 tags not be enough, it is possible for one MultiWrite tag to trigger another upon finishing its write sequence.

An event will be recorded in the event history whenever a MultiWrite is triggered.

If triggering a Digital Control or Digital Output with a pulse duration, use care that you do not attempt to send a pulsed zero.

Set Value Buttons and Multi-Write tags.

This tag will work with the Set Value Button Widget but support is limited:

  • Value to Write must be set to 1 in the widget for use with a Multi-Write tag. No other value will work.
  • Multi-write tags cannot act as feedback tags. To use Select Before Operate in the Set Value, a separate I/O tag must be configured as the feedback tag and used as the linked tag in the Execute / Cancel buttons.

Related information:

Best Practices for Tags

Closed MultiWrite properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

MultiWrite properties Write List tab

The Write List displays the output or memory tags that will be written to, and controls what value will be written to each. The outputs will be written in the order in which they are displayed.

You can add or edit any tag in the list by clicking on a row. You must select a tag before configuring the value to be written to it.

The Tag and Value input fields will be activated when a row is selected, except that rows must be filled in sequence from #1. You cannot add a tag to row three before row two has been completed.

The grid displays the name and description of each tag selected to be written to. The Value column shows what will be written to each tag when the MultiWrite is triggered. The value may be any of a constant, an expression or another tag’s value. In the case where another tag’s value is to be written, that tag’s name will be display in the Value column.

Note that, the display may show a tag's Unique ID rather than its name when the tag is not selected. The description will always be shown for every tag, to help avoid confusion.

To add a tag to the list, select the next available row, then click on the Tag Browser button. Select or create an output tag. After you have specified the tag to write to, you can provide a value to write using the Value field.

To remove a tag from the list, select its row, then click on the X button in the lower-right corner of the window.

The arrow buttons below the grid may be used to move a selected row up or down in the list, thus controlling the order in which output tags are written to.

MultiWrite properties Activation tab

The Activation tab provides a way for MultiWrite tags to be controlled automatically.

Activation Trigger

Any tag or expression that will change from a false (0) to a true (1 or any non-zero number) can be used to trigger the write.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Log an event on automatic multi-write

Selected by default. You can choose to not log events when multi-writes occur in response to the activation trigger. Choose this if you have a multi-write operation that triggers frequently.

An operator pressing the Multi-Write Button or Hotbox will always cause in a new event to be logged.

Closed MultiWrite Tag Widgets

MultiWrite tags write defined values to a group of PLC or RTU addresses, as defined by the associated tags. The widgets for these tags enable users to trigger the writing of this data.

Multi-Write Button Widget

Multi-Write Hotbox Widget


Selector Switch Tags

Counted towards your tag license limit.

Selector Switch tags provide the means to create multi-position switches that can be used to create on-off toggles, mode selectors, or Hand-Off-Auto (H-O-A) switches.

Reference Notes:

For each switch position, a predefined value will be written to a specific address. Each position can write to the same address, or each could write to a unique address. Using the same address is typical for toggle switches. Using unique addresses is typical for Hand-Off-Auto (HOA) switches. If a unique address is used for each switch position, it is customary to configure the switch to write a zero to the address for each position not currently selected.

Selector Switches can be used as digital controls, but they differ in structure from I/O tags that do digital control. Use care when choosing which type to use for any situation.

Feedback

A Selector Switch can accept two types of feedback:

  • Equipment feedback indicates the current status or state of the equipment. When configuring the Selector, you can specify what the expected value will be for each switch position.
  • Switch Position feedback updates the selected position of the Selector Switch. This value must match the numeric switch position (0, 1, or 2). A new value arriving via the position feedback does not cause the Selector Switch tag to do a fresh write.

In both cases, feedback must be provided by a tag or an expression.

The two types of feedback do two different things and either (or both) should be used as needed. Switch position feedback must be used if something other than VTScada can change the position or mode of that item.

Mismatch Conditions

The selector switch is designed to alert the operator to a mismatch condition by providing visual feedback through its native widgets.

There are two possible causes for a mismatch condition:

  • Position mismatch The switch position as requested by the operator does not match the actual position as reported by the switch position feedback value. This can occur when there is a lag in response time from the equipment.
  • Value mismatch The equipment feedback does not match the expected value for the requested or current position. This type of mismatch can also be used to trigger an alarm. The alarm must be enabled and the mismatch must exist for a set length of time before an alarm will become active.

The native widgets for the selector switch will use the following conventions to notify the operator of a mismatch or an alarm condition:

  • Alarm indicators take precedence. While an alarm indicator is active, no other mismatch indicator will be displayed.
  • Alarms are normally indicated with red, and (if possible) will be shown on the requested or current position of the switch.
  • Alarm indicators are displayed until the alarm condition is cleared, regardless of whether the alarm has been acknowledged.
  • When a position mismatch occurs and no alarm state is active, then (if possible) the requested position will be indicated by the widget - often by blinking.
  • When a value mismatch occurs and the alarm is either disabled or has not yet triggered, an indication like a position mismatch will be displayed, if possible.

Related information:

Best Practices for Tags

Closed Selector Switch properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Selector Switch properties I/O tab

The I/O Tab includes properties used to identify and establish a connection to the communication driver tags being used to exchange data with your physical I/O device (e.g. PLC or RTU). This is done by identifying the communication driver tag that is linked with the physical I/O device.

In addition, the I/O tab also provides a means of selecting tags or expressions that are to provide feedback for the state of the equipment or external control over the switch position.

Feedback versus Switch Position Feedback

Feedback is a value that you read from the controller by configuring a tag to monitor an address on the controller. By monitoring a feedback value, you can ensure that the correct value was written after changing the switch position, and that the controller and the SCADA system agree on the current switch position.

Referring to the labels from the configuration panel (see following image):

Feedback

The Feedback field is used to ensure that the correct value was written to the remote device. This is similar to the feedback field of a Digital Control tag. When configuring the switch positions and the value to write for each position, you will also configure the value that will be expected via the feedback for each position of the switch.

If the value of the selected feedback tag or expression does not match the expected value for the current position, then this will trigger an alarm, assuming that the alarm option of the selector has been enabled.

Switch Position Feedback

Switch Position Feedback is used to ensure that the selector in the SCADA system remains synchronized with the controller. The tag or expression used for this field must be able to have values matching the possible positions of the selector. (0 and 1 for a two-position selector, 0, 1 and 2 for a three-position selector).

If the tag or expression providing position feedback changes to a new value, this Selector Switch will update to match. Note that this does not cause the tag to do a fresh write to the equipment.

If an operator changes the position of this Selector Switch within the application, but the switch position feedback indicates that the physical position has not changed, the widget will blink to show a mismatch.

I/O configuration for a Selector Switch

I/O Device

Select the communication driver tag to which data will be written.

By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver's properties dialog.

Feedback (equipment feedback)

[Optional] Select the tag or expression that has been configured to provide feedback indicating whether the control action of this switch has been successful. "Success" means that the state of the equipment matches what is expected (as configured on the Positions tab) for each possible switch position. A mismatch in values here will trigger an alarm, if one is configured on the Alarm Setup tab.

Switch Position Feedback

[Optional] Select the tag or expression that has been configured to provide an indication of the current position of the equipment. (0, 1 or 2 according to switch positions) The selector switch will change positions to follow this feedback value. If the selector switch is changed, but the feedback value does not follow, the widget will blink, but this will not by itself cause an alarm. See Feedback (equipment feedback).

Value When Off

Available only when the Use Single Output Address option has been deselected. The value provided here will be written to the addresses of the unselected switch positions after the current position's value has been written.

Use Single Output Address

This check box provides an option to use a single output address for all switch positions, or to allow a separate address for each position.

In the case where each position of the switch writes to a different output address, you can deselect the "Use Single Output Address" box and provide a value that will be written to each address not matching the current switch position. Note: Addresses are specified on the next tab, Positions.

Values will be written in a "make before break" order. In other words, the value for a new switch position will always be written before the value-when-off is written to the addresses matching the unselected switch positions

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Selector Switch properties Positions tab

In the Positions tab you can configure the expected feedback values, the values to write and the address(es) corresponding to each of the possible switch positions. (Whether a single or multiple output addresses are used, depends on the check box in the I/O panel.)

Select Position to Configure

Select each of the available switch positions to configure the output and expected values for that position. The label over each parameter will change to show which position is being configured. The list is controlled by the parameter, Number of Positions.

Number of Positions

May be either "2" or "3". Limits the number of configurable positions in the switch. Always select "2" for a toggle switch. (This differs from earlier versions where it was common practice to create toggle switches by configuring positions "0" and "2," leaving position "1" blank.)

Expected Value (Position x)

Specify the value that is expected to be returned in the feedback field of the I/O panel, to indicate that the tag's switching operation caused a successful change in the system. This value can be a constant, an expression, or it may come from a tag.

Output Value (Position x)

This field is where you to specify the constant, expression or tag value that will be written to the output address when the corresponding position is selected. If a tag or expression is used here, then changing output values will trigger a write to the device as long as the position has not changed.

Label (Position x)

If the switch requires operator confirmation (configured when drawing the switch as a toggle) then this label will appear as part of the confirmation prompt for the matching switch position.

Address

The I/O address to write the output value to when position x is selected.

If the Use Single Address option was checked in the I/O panel, then this field will be labeled simply "Address" since the same address is used for all positions. Otherwise, the label will be "Address (Position x)" to indicate which switch position you are providing the address for.

Selector Switch properties Alarm Setup tab

Specify the parameters of the alarm that will be triggered when the equipment feedback for the tag does not match expected value.

Because physical equipment can sometimes take a few moments to respond, a delay can be specified to prevent the alarm from being triggered while waiting for the expected feedback value.

By design, this alarm cannot be configured as a trip alarm.

Invalid data, whether on the I/O Device or a feedback tag, will neither cause nor clear an alarm condition.

Alarm Priority

Select the priority level of this alarm. All other controls are disabled while the priority level is set to "None".

On Delay

Specify a delay in seconds to wait when the feedback value from the PLC does not match the expected value for the requested switch position before triggering an alarm.

Sound

[optional] Enter the name of a .wav file in your application directory to use that as the alarm sound.

Alarm Disable

Deselect to enable alarms on this switch. May be linked to a tag or expression for suppression by design.

Pop-up Enable

Available only when alarm pop-ups are enabled in the application properties (see: AlarmPopupsEnable)

Selector Switch properties Merit tab

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Selector Switch properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed Selector Switch Tag Widgets

Selector switch tags allow you to add multi-position widgets such as Toggle buttons, mode selectors and Hand-Off-Auto switches to your applications.

The following widgets are available to Selector Switch tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Checkbox Switch Widget | Color Blink Widget
Color Box Widget | Color Fill Widget
Color Line Widget | Compass 1 Widget
Compass 2 Widget | LCD 5x7 Matrix Widget
Draw Text Widget | Droplist Widget
Equipment / Status Color Indicator | Horizontal Button Widget
Image Change Widget | Indicator Light Widget
LCD Bar Widget |
LCD 7 Segment Widget | Left Bar Widget
Meter 1 Widget | Meter 2 Widget
Meter 3 Widget | Momentary Button Widget
Multi-Color Widget | Multi-Text Widget
Numeric Entry Widget | Numeric Value Widget
Plot Data Widget | Right Bar Widget
Selector Switch Widget | Set Analog Value Widget
Legacy Set Value Button Widget | Legacy Set Value Hotbox Widget
Slider Widget | Text Change Widget
Top Bar Widget | Toggle Switch Widget
Two Color Bar Widget | Vertical Buttons Widget
Sparklines Widget |


Trigger Tags

Viewing: Reference > Tag Reference > Output Tags > Trigger Tags

Trigger Tag

Not counted towards your tag license limit.

Trigger tags can be used to activate a process at a set time and date. They may be configured to repeat at regular intervals, or they can be configured to trigger based on an expression or another tag’s value. By drawing the Trigger tag on a page, you can also provide a way for operators to manually trigger an event.

As well as defining a schedule or event that will set the trigger to 1 (On), you can should also define a schedule for when it will be reset to 0 in preparation for the next trigger event. This may be configured as a delay measured in seconds after the On trigger event, it may be set to a regular schedule or it may be tied to an expression or tag value.

The trigger depends on the underlying Windows operating system and your server's system clock. It should not be relied upon for precise to-the-second starts or stops.

There is only once source of information to determine the Trigger tag's value, and that is the server's system clock. The value of the trigger tag on any client workstation follows the value on the server in real-time. Regardless of the location of client workstations, any given trigger will occur only once, on the server, in the server's time zone, accounting for DST.

In a multi-server configuration, the trigger tag will follow the NetworkValues service to determine which workstation is the server and therefore which time to trigger on. If no server list has been provided for the NetworkValues service, the default server list is used.

The time of the latest ON-state is saved. On a restart, the time for the next OFF-state is checked. The tag will start in the appropriate state depending on whether the trigger-off following the last ON is in the past (therefore start in the OFF state) or future (therefore ON). In short, the tag will work as it should while the application is running, even if a trigger event is missed due to downtime.

An "Enable" parameter is provide to allow you to control whether the Trigger tag is activated or not. If the tag is drawn on a page, this can be toggled by right-clicking on the widget. Disabling a Trigger tag will also force its value to be 0 (OFF).

In VTS applications created prior to version 10, the scheduling option of both the On Condition and Off Condition could be disabled by setting the "Every" field to 0. This has been replaced by an "Enable" check box, but applications created in earlier versions will continue to work without modification.

Related information:

Best Practices for Tags

Confirmation Prompts for Output Tags - Control options for confirmation prompt text.

Closed Trigger tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Trigger tag properties: On Conditions tab

This tab is used to set the condition that will switch the tag’s value to 1. The tag may be switched to an ON state based on a schedule or based on an expression (which may include a tag).

Both options may be configured, resulting in a tag that will be triggered both on a regular schedule and also in response to an event.

Note the field labeled "Enable". When not selected, this means that no schedule is in effect. All other time-related fields will be disabled.

Note also the Starting Time. This serves as both an initial trigger time and the base date for repeating trigger events. For example, to trigger a report to be created at midnight on the first day of each month, you would set the following values:

  • "Enable" field selected.
  • "Starting Time" set to 12:00 a.m. on the first day of this month.

(Setting the first day of next month would achieve the same result, but putting the base date of repeating events in the past ensures that you do not miss the first iteration.)

  • "Every" value set to 1.
  • "Months" option selected.
  • "Same Day as Starting Day" selected. ("Same Day" refers to date in the month, not day of the week)

You must also configure the Off Conditions tab to set the schedule or condition that will reset the tag’s value to 0. After the trigger has occurred and the tag’s value set to 1, it remains at a value of 1. If you need a 0 to non-zero transition to trigger an event, you must reset the value to Off (0) before the next desired On-time.

Enable

Must be selected in order for the trigger to activate based on a time and date schedule.

Starting Time

Sets the base date and time for the schedule configuration options. Subsequent configuration options will be counted from this start time. If set to the future, no trigger will occur until that date. The time that is displayed in this field is in the time zone of the workstation that you are using to access the application.

Every [N] Seconds / Minutes / Hours / Days

The field beside "Every" controls the frequency of the following units.

For example, if the Every value is set to 1 and the Hours check box is selected, then beginning with the time configured in the Start Time, the trigger will be set to true every hour.

If the Every value is set to 7 and the Days check box is selected, then beginning with the configured Start Time date, the trigger will be set to true every week at the time given in Start Time.

Day check boxes

Allow you to control which days the Trigger tag will operate on. For example, you may choose to disable the trigger’s action on weekends by deselecting Saturday and Sunday.

These check boxes will not be enabled when the Months option is selected.

Months

Selecting the Months option is similar to configuring to Trigger tag to switch on every N Hours. If this option is chosen, then further refinements include "On The" or "Same Day as Starting Day".

For example, you may wish to configure the trigger to run "on the 1st Wednesday" or "on the 2nd Monday" of the month. Alternatively, of you have selected "Same Day as Starting Day" then the trigger will run on the given numeric day of the month, at the selected time.

When the Months option is selected, the Day check boxes will not be enabled.

Expression

Select a tag, or enter an expression that will be used to activate the Trigger tag. The On condition will be set when the selected tag or expression’s value becomes non-zero.

Trigger tag properties: Off Conditions tab

This tab is used to set the condition that will switch the tag’s value to 0, resetting the Trigger tag for the next scheduled event. The tag may be switched to an OFF state based on a delay in seconds after switching ON, a schedule, or based on an expression (which may include a tag).

A combination of options may be configured, resulting in a trigger that will reset either based on time, or in response to an event.

Note the field labeled "Every". When set to 0 this means that no schedule is in effect. All other time-related fields will be disabled.

Delay

When set to a value greater than 0, the Trigger tag’s value will be set to 0 (OFF) this many seconds after being triggered by the On Condition.

Enable

Must be selected in order for the trigger to de-activate based on a time and date schedule.

Starting Time

Used to set the base date and time for the reset (Off-condition) schedule. The other configuration options on this tab will be counted from the given Starting Time. The time that is displayed in this field is in the time zone of the workstation that you are using to access the application.

Every [N] Seconds / Minutes / Hours / Days

The field beside "Every" controls the frequency of the following units.

For example, if the Every value is set to 1 and the Hours check box is selected, then beginning with the time configured in the Start Time, the trigger will be reset to 0 every hour.

If the Every value is set to 7 and the Days check box is selected, then beginning on the configured Start Time date, the tag will be reset to 0 every week.

Day check boxes

Allow you to control which days the reset schedule will operate on. For example, you may choose to not reset the tag to 0 on weekends by deselecting Saturday and Sunday.

These check boxes will not be enabled when the Months option is selected.

Months

Configures the tag to reset to 0 every month. If this option is chosen, then further refinements include "On The" or "Same Day as Starting Day".

For example, you may wish to configure the trigger to reset "on the 1st Wednesday" or "on the 2nd Monday" of the month. If you have selected "Same Day as Starting Day" then the trigger will be reset on the given numeric day of the month, at the selected time.

When the Months option is selected, the Day check boxes will not be enabled.

Expression

Select a tag, or enter an expression that will be used to reset the Trigger tag’s value to 0. The Trigger tag’s value will be set to 0 when the value of the selected tag or expression becomes non-zero.

Trigger tag properties: Options tab

A trigger tag may be drawn as a button on a page, thus allowing operators to trigger the associated action at unscheduled times, if required. By adding a custom privilege, you can restrict access, allowing only authorized users to use the button.

Select the Disable option to deactivate the Trigger tag. Disabling a Trigger tag forces its value to 0.

Related information:

Protect Pages and Output Tags - Create your own privileges for protection.

Trigger tag properties: Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed Trigger Tag Widgets

The following widgets are available to Trigger tags:

Alarm Priority Box

Alarm Priority Icon

Animated Image Widget

Color Blink Widget

Color Box Widget

Color Line Widget

Equipment / Status Color Indicator

Image Change Widget

Indicator Light Widget

Momentary Button Widget

Plot Data Widget

Legacy Set Value Button Widget

Legacy Set Value Hotbox Widget

Text Change Widget

Of these widgets, only the Legacy Set Value Button, Legacy Set Value Hotbox Widget, and Momentary Button Widget methods enable users to output values to the associated tag. The remaining widgets display the value of the tag.


Confirmation Prompts for Output Tags

Many of the widgets for output tags include an option to require the operator to confirm that they intended to write a value. For analog tags, the confirmation text will include the new value. For example, "Are you sure you want to set the value to 1500?".

For I/O and Calculation tags configured as Digitals, the text for the prompt comes from the digital mode of the associated Style Settings tag. You can have a variety of messages for a variety of digital tags by configuring equipment types. For example "Open" for valves, "Start" for motors, "On" for switches. This is also true for I/O tags configured as discrete.

For some digital tags, the message displayed will be more or less meaningful depending on how you configure the tag. For example, the Digital Control tag includes the fields "On Text" and "Off Text". Selector Switches provide a label for each position. If you provide a descriptive word for the control action matching each output state ("On", "Open", "Start"), then that word will appear in the confirmation prompt. For tags that do not have this option, and for those with the option that you leave unconfigured, a generic message will be displayed.


Publisher Tags

Publisher tags used in publisher/subscriber communications. Publisher tags are typically used in conjunction with a server or broker such as OPC, MQTT or a device like a Data Diode.

Related information:

Data Diode Client Tag

Data Diode Publisher Tag

OPC Classic Server Setup

PublisherListTag

Sparkplug Edge Node

Sparkplug Edge Device


Data Diode Publisher Tag

The data diode publisher tag is paired with the Data Diode Client Tag to establish communication across a Data Diode device. It is located on the Data Diode Publisher side, within the secured network. The Data Diode Publisher tag must have an IP Address and a port number from which the Data Diode will receive and publish data. At least one Historian tag must be linked to the Data Diode Publisher tag.

The historian tags and I/O tags must be the same on both applications and have the same Unique IDs. The easiest way to do this is to create the publishing application first and copy it to reconfigure as the client application.

You must link the Historian tag(s) to the Publisher tag and Client tag by inserting custom properties in the Application Configuration.

First, find the Unique IDs of the Historian tag and either the full name or UniqueID of the Data Diode Publisher/Client tag. You can find this by locating them in the tag browser and hovering over them with your cursor. Write these down.

Next go to the Application Configuration > Edit Properties in Advanced Mode and Insert a new property.

The property name will be (The unique ID of the Historian tag)"DDPublisherID" or "DDClientID" and it's value will be (The full name or unique ID of the Data Diode Publisher/Client tag).

ex. To link a Historian tag with a unique ID of "123ztg-y\y" to a Data Diode Publisher tag with a full name of Station 1\DDP_01 you must insert 123ztg-y\yDDPublisherID = Station 1\DDP_01

To link a Historian tag with a unique ID of "4561#3_yg" to a Data Diode Client tag with a unique ID of "8_6ynG-0" you must insert 4561#3_ygDDClientID = 8_6ynG-0

If you have more than one Historian tag, repeat the process for all tags you wish to publish to Data Diode. The client-side Historian tags must have identical Unique IDs to the publisher-side Historian tags.

The global unique ID of the default system historian found in every VTScada application is "SystemHistorian"

If the server fails on the client app, there is no way for the publishing app to detect it. It will continue transmitting data until the publishing application stops or an operator intervenes. Once the server issues on the client side is resolved, you can back-track by using the Start from Date/Time button to start retransmitting from the last date captured before the failure.

Your Data Diode configuration may resemble the above diagram. The publishing tags and widgets belong in a secured network. The data is transmitted out, to a client tag on the receiving application. There is no means to transmit data into the secured network, effectively isolating it.

A Data Diode configuration requires two VTScada applications, one app on the secured network (publishing side), and one on an external network (client side).

Closed Data Diode Publisher Properties ID Tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Data Diode Publisher Properties Settings Tab

Link the port tag, set the security privilege or opt to reset the published state.

The settings tab of the Data Diode Publisher Properties.

TCP/IP Name/Address

The TCP/IP Name/Address field provides a space for you to identify the name or IP address of the server to which to connect (for example, MyRTU.com, or 198.255.32.1).

TCP/IP Port Number

The TCP/IP Port Number field refers to the port number on the host address through which communications are enabled. This information should be available from your hardware specification.

Privilege

Select a custom security privilege from this drop down to limit the access to this view to only those operators who have been granted the matching security privilege.

Reset Published State

The publishing application keeps track of data transmitted to Data Diode by using counters, state files and by utilizing a queue complete with headers and trailer checksums. In this way, VTScada can publish from where it left off if the transmission is stopped and started. To reset the published state and begin transmitting from the earliest recorded data in the historian, click Reset Published State to clear the slate.

If you select reset published state the data used as a placeholder will be deleted. You cannot undo it and you cannot speed up the process using Start from Date/Time. This widget relies on data that will be erased by resetting the published state. You will have to let the bulk sync process complete.

Data Diode Error Codes

Error Code | Description
-1 | Port configuration incomplete
0 | No Error
1 | Port Not Defined
2 | Port Failed To Connect
3 | Port Lost Connection
9 | Port Not Connected
Closed Data Diode Publisher tag widgets

Data Diode Start Button Widget

Data Diode Start From Date/Time Button

Data Diode Stop Button Widget

Data Diode Publisher Statistics Dialog

Related information:

Data Diode Support

Data Diode Client Tag

TCP/IP Port Tags


Data Diode Client Tag

The data diode client tag is paired with Data Diode Publisher Tag to establish communication across a Data Diode device. This tag is configured on the Data Diode client side, outside of the secured network. The Data Diode Client tag must have a port number receiving data from Data Diode. At least one historian tag must be linked to the Data Diode Client tag.

Your Data Diode configuration may resemble the above diagram. The publishing tags and widgets belong in a secured network. The data is transmitted out, to a client tag on the receiving application. There is no means to transmit data into the secured network, effectively isolating it.

A Data Diode configuration requires two VTScada applications, one app on the secured network (publishing side), and one on an external network (client side).

The historian tags and I/O tags must be the same on both applications and have the same Unique IDs. The easiest way to do this is to create the publishing application first and clone it to reconfigure as the client application. Cloning is the only way to copy over the same assets with the same Unique IDs on an application outside of the secured network.

You must link the Historian tag(s) to the Publisher tag and Client tag by inserting custom properties in the Application Configuration.

First, find the Unique IDs of the Historian tag and either the full name or UniqueID of the Data Diode Publisher/Client tag. You can find this by locating them in the tag browser and hovering over them with your cursor. Write these down.

Next go to the Application Configuration > Edit Properties in Advanced Mode and Insert a new property.

The property name will be (The unique ID of the Historian tag)"DDPublisherID" or "DDClientID" and it's value will be (The full name or unique ID of the Data Diode Publisher/Client tag).

ex. To link a Historian tag with a unique ID of "123ztg-y\y" to a Data Diode Publisher tag with a full name of Station 1\DDP_01 you must insert 123ztg-y\yDDPublisherID = Station 1\DDP_01

To link a Historian tag with a unique ID of "4561#3_yg" to a Data Diode Client tag with a unique ID of "8_6ynG-0" you must insert 4561#3_ygDDClientID = 8_6ynG-0

If you have more than one Historian tag, repeat the process for all tags you wish to publish to Data Diode. The client-side Historian tags must have identical Unique IDs to the publisher-side Historian tags.

The global unique ID of the default system historian found in every VTScada application is "SystemHistorian"

After configuring the client application (historian and I/O tags are ready), you must refresh the historian storage location. There are two ways to do this. The easiest way is to set a new historian storage location. Alternatively, you can find the "History" folder and delete it. It will be located under VTScada > YourApplicationName > Data. When you begin receiving historian data, VTScada will create a fresh History folder.

There can only be one client server. The server list of the Data Diode Client tag must only contain one machine. If the client server fails, the client application would not be able to receive data. Data Diode can only send data to a specific IP address. It cannot automatically failover to a backup machine.

To switch to a new machine, you must reconfigure the server list to only have the new machine in it and update the IP and port number in the Data Diode. If the server has failed, the publisher will continue to transmit data. There is no way to signal to the publishing application directly that an error has occurred on the client application. Once the issue has been resolved, use Start from Date/Time on the publishing application to re-transmit data that was not replicated in the client application during the down-time.

Closed Data Diode Client Properties ID Tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Data Diode Client Tag Properties Settings Tab

Link the port tag, set the security privilege or opt to reset the published state.

The settings tab of the Data Diode Client Properties.

TCP/IP Port Number

The TCP/IP Port Number field refers to the port number on the host address through which communications are enabled. The port number configured in the client tag can be any port that isn't used by other services. You must set up the Data Diode device with the same destination port. Refer to your hardware specification for more information.

The Data Diode Client Tag will act as a listener. That is why only a port number is required and not a TCP/IP Address. We strongly recommend your IT department set firewall rules for the port used by the Data Diode Client tag to ensure it only accepts connections from the Data Diode device.

Data Diode Error Codes

Error Code | Description
-1 | Port configuration incomplete
0 | No Error
1 | Port Not Defined
2 | Port Failed To Connect
3 | Port Lost Connection
9 | Port Not Connected
Closed Data Diode Client tag widgets

Sync Status Indicator Widget

Comm Indicator Widget

Historian Status Widget

Data Diode Client Statistics Dialog

Related information:

Data Diode Support

Data Diode Publisher Tag

TCP/IP Port Tags


PublisherListTag

Not counted towards your tag license limit.

Publish data to more than one publisher. The Publisher List tag will forward register, unregister, and publish calls to up to 8 different publishers. In the I/O or Calculation tab of the IO tag, use the Publisher tag selector to link to the Publisher List tag and configure the Publisher List tag with all applicable Publishers.

In this example, 3 IO and Calc tags plus one analog status tag are linked to the publisher list tag. The publisher list tag is configured to publish to 5 different publisher tags

This is just one unlikely example of a possible configuration for the Publisher List tag

It is possible to link publisher lists to other publisher lists, however circular references will be prevented from being created. You may configure duplicate references, but this could result in more publish calls to a given publisher than necessary.

Published data passes through the Publisher List tag but requested data does not. Publishers will not function any differently when part of a publisher list. They can still receive and request data in all the same ways.

Related information:

Best Practices for Tags

Closed Publisher List tag properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Publisher List tag Publisher List tab

Use the tag selectors to link as few as one or as many as eight publisher tags. To the right of each field is an [ x ], a relative path button and a tag browser button.

To select a publisher tag, click the tag browser button. This will open the tag browser with a filtered applied and only showing Publisher type tags.

If you navigate to the root level and enable Show Children you will see all of the eligible tags in the application at once.

The [ x ] button will clear the field. The relative path button gives you a choice of how to specify the link. See Relative Paths - Tag Relationships for more information.


Sparkplug Edge Device

The Edge Device tag is always the child of an Edge Node tag. It is the muster point for a logical group of devices such as all devices registered on a single PLC. It is intended to model an Edge Device like a PLC or industrial controller in a Sparkplug B environment.

Closed Sparkplug Edge Device properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Sparkplug Edge Device properties Connection tab

Link the edge device to an edge node and establish or edit the device ID.

Sparkplug Edge Node

The Sparkplug Edge Node tag through which the Sparkplug Edge Device tag will communicate. This will automatically link to the parent Sparkplug Edge Node tag or you can select a specific Sparkplug Edge Node tag.

Sparkplug Edge Device ID

The topics namespace for Sparkplug B has the following format: namespace/group_id/message_type/edge_node_id/[device_id]. Sparkplug Edge Device ID is the device_id in this format. Auto-generated unless specified. By default, this ID will include any parent tags and the tag name with the slash (\) substituted with two underscores (__) to keep the ID unique. For example, Edge Device tag "EoD1" appearing under a Sparkplug Edge Node tag "EoN1" which is under a context tag "Weather Station" will auto-generate the Sparkplug Edge Device ID "Weather Station__EoN1__EoD1". Topic names are case-sensitive.

Allow Incoming Write Commands

Enables the Edge Device tag to receive, process, and execute DCMD write commands. There is a buffer size determined by the Write Command Buffer Size in the Buffering tab.

Sparkplug Edge Device properties Buffering tab

Specify parameters for queueing and sending data from Edge Devices to Edge Nodes.

You can specify parameters related to queuing values from different I/O metrics linked to the Sparkplug Edge Device for DDATA publishing. The Sparkplug Edge Node has a queue for each of its devices dedicated to buffering incoming DDATA messages. The DDATA queue is encoded into a DDATA message and handed to the Sparkplug Edge Node to be buffered and published either when the maximum queue length has been reached or when a configured length of time has passed.

Max metrics count per DDATA

The maximum length of the DDATA queue. A buffering algorithm goes through all the I/O metrics attached to the Edge Device in a round-robin fashion and picks the oldest value from the metrics queue to buffer in the DDATA queue.

It is a best practice to configure the max metrics count per DDATA to equal the number of metrics attached to the device as long as the size of the resulting DDATA message is not too large to fit in an MQTT payload and if it does not put a heavy load on the network.

Max wait time for DDATA queue before publishing

A maximum amount of time, in seconds, to wait before the DDATA queue is encoded into a DDATA message and handed to the Edge Node to be buffered and published.
The Edge Device will hand the DDATA packet to the Edge Node when either the maximum wait time or maximum queue length has been reached.

Max measurements queue length per tag

Values produced by an IO tag are inserted into a queue for that tag. The queuing algorithm goes through the tags values queues in a round-robin fashion until it fills the DDATA queue of the device. If a new value is produced by the IO tag but the tag's queue is full, the oldest value in the queue is dropped and the new value is queued.

Max DDATA queue length

This is the maximum number of payloads for the same Edge Device buffered in the Edge Node.
The Edge Device will hand the DDATA packet to the Edge Node when either the maximum wait time or maximum queue length has been reached.

Write Command Buffer Size

Defines the maximum number of write commands that each attached tag can buffer simultaneously. This setting applies to all tags attached to the same Edge of Device (EoD) tag. The minimum buffer size is 2.

Closed Sparkplug Edge Device Widgets

Site Summary Widget

Site Details Widget

Site Alarm List

Tag List Widget

Site Icon Widget

Alarm List

Alarm Priority Box

Alarm Priority Icon

Draw HDV Widget

Add Lock Button Widget

Locks List Widget

Lock Level Icon Widget

Lock Level Box Widget

Request Token Button Widget

Release Token Button

Token Level Icon

Token Level Box

Control Token Box

Tokens List

Tokens and Token Requests List

Related information:


Sparkplug Edge Node

The Edge Node tag does all the work to prepare data for an MQTT server. It collects data from sensors or Edge Devices, formats it using the Sparkplug B naming and formatting protocol and publishes it to the MQTT server.

Edge Node tag RPC Service

For server configuration, the Edge Node has an RPC Service. As with other RPC Manager Services, a server list can be specified for the Edge of Node tag as opposed to the default server list. The first server listed will be the primary; Only the primary will handle the writes/reads and dissemination of information to the redundant servers. The RPCServerName of the Edge Node is automatically produced as soon as a name is applied to the Edge of Node tag. It will resemble the name of the tag (ex. If the tag is called Well1EON1 and is a child of context tag Well1 the RPCServerName may be Well1\Well1EON1)

As with other redundant server configurations, should the primary server fail, the next server on the list will become the new primary.

Closed Sparkplug Edge Node properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Sparkplug Edge Node properties Connection tab

Establish or edit the Edge Node ID, Group ID, MQTT Client ID. Specify Keep Alive time, reconnect attempts, max DDATA publish count and timeout limit. Toggle on tracing for troubleshooting or start publishing.

The topics namespace for Sparkplug B has the following format:
namespace/group_id/message_type/edge_node_id/[device_id]
Edge Node ID and Group ID are identified in this properties dialog. Note that topic names are case-sensitive.

Sparkplug Edge Node ID

Auto-generated unless specified. By default, this ID will include any parent tags and the tag name with the slash (\) substituted with two underscores (__) to keep the ID unique. For example, Edge Node tag "EoN1" appearing under context tag "Weather Station" will auto-generate the Sparkplug Edge Node ID "Weather Station__EoN1".

Group ID

Auto-generated unless specified. Part of the topics namespace for Sparkplug B.

MQTT Client ID

Auto-generated unless specified. This value is only used by the MQTT broker when establishing a connection. It may be useful to know this value if you are troubleshooting.

Sparkplug B SCADA Host ID

Optional. If you name a Sparkplug B SCADA Host ID then this Sparkplug Edge Node tag will only publish if the specified host is online.

Keep Alive (s)

The length of time to maintain an open connection between ping requests.

Reconnect Attempts

The number of times the Edge Node will try to connect to a server before it gives up and moves to the next specified server.

Maximum Active DDATA Publish Count

The maximum number of MQTT publish messages carrying DDATA Closed 2-Factor Authentication. that are in flight at any point in time. This limits the number of Publish modules taking up memory and CPU resources and is useful when the application is publishing DDATA at very high rates. It does limit the publishing rate but could keep the app responsive and give other modules the chance to execute. A buffering algorithm goes through the devices in a round-robin fashion and queues a single DDATA for a device if one is available.

It is a best practice for the Maximum Active DDATA Publish Count to equal the number of devices attached to the node. This way, all devices get a chance to publish. In a system with a high publishing rate, the larger this number the bigger the risk of overloading the stack and network.

Timeout Limit (s)

The period of time in seconds before we give up on an MQTT message.

Write Command Buffer Size

Defines the maximum number of write commands that each attached tag can buffer simultaneously. This setting applies to all tags attached to the same Edge of Node (EoN) tag. The minimum buffer size is 2.

Allow Incoming Write Commands

Enables the Edge Node tag to receive, process, and execute NCMD write commands.

Start Tracing

This should only be enabled when necessary for debugging, detailed analysis and identifying bottlenecks. Tracing is a logging tool designed to track and record operational data within the publisher.

Start Publishing

You must enable this to publish. Disabled by default so the full architecture, all Edge Device tags and I/O and Calculations device tags, can be configured before you start publishing. Every time this tag is enabled it publishes NBIRTH Closed Birth certificate for Sparkplug Edge Nodes and every time it is disabled it will publish NDEATH Closed Death certificate for Sparkplug Edge Nodes.

Sparkplug Edge Node properties Server tab

Select number of servers for redundancy or performance. Configure credentials and link a communications tag.

Number of Servers

Specify up to five servers. These servers are typically for redundancy. It is possible to configure a node command to change servers if the current server is performing too slowly.

Server

Click on the server you want to specify by default.

Configuration - Username

If your MQTT broker requires a username, specify it here.

Configuration - Password

If your MQTT broker requires a password, specify it here.

Configuration - Hash Password with MD5

You may enable this option to hash the MQTT broker password with MD5.

Configuration - Port

Specify the TCP/IP port tag you have configured for your MQTT communications.

Related information:

Closed Sparkplug Edge Node Widgets

Site Summary Widget

Site Details Widget

Site Alarm List

Tag List Widget

Site Icon Widget

Alarm List

Alarm Priority Box

Alarm Priority Icon

Draw HDV Widget

Add Lock Button Widget

Locks List Widget

Lock Level Icon Widget

Lock Level Box Widget

Request Token Button Widget

Release Token Button

Token Level Icon

Token Level Box

Control Token Box

Tokens List

Tokens and Token Requests List


Alarm System Tags

This group of tags includes all tags related to alarms that can be used in every VTScada installation.

Tags which are used by the optional Alarm Notification System can be found in the following group, Alarm Notification System Tags.

Related information:

Alarm Tag. Create and configure an alarm, to be triggered by another tag.

Alarm Priority Tags. Control the notification parameters for each priority of alarm. Create customized notifications.

Alarm Status Tags. Monitor for any alarms matching a configured profile.


Alarm Tags

Viewing: Reference > Tag Reference > Alarm System Tags > Alarm Tags

Concepts:

Create Alarms

Alarm Database Tags

Alarm Priority Tags

Alarm Tag

Not counted towards your tag license limit.

Alarm tags are used to establish rules for when an alarm should be triggered, and what behavior should occur. An Alarm tag monitors the value of another tag and triggers an alarm when that tag’s value reaches or passes a given set point.

The Setpoint property can be a user-defined number or it can be supplied by another tag’s value. The two values are compared using an operation such as greater than, equal to, or less than. If the result of this comparison is determined to be true, then the Alarm tag will be triggered.

The value of the Alarm tag itself becomes 1 while the alarm is on the active list. Otherwise, the value of the Alarm tag is 0. Note that trip alarms and event alarms never appear on the active list and therefore will always have a value of zero.

The urgency of the alarm (from Event to Critical) is defined by the Alarm Priority tag selected in the Alarm tag’s properties.

Alarms can be configured such that, if they are acknowledged by an operator, but remain active for a set length of time (that is, the triggering condition for the alarm remains in effect), the alarm will go back to an unacknowledged condition, thereby re-activating any audible and visible warning indicators that are attached to that alarm.

Note that shelving or unshelving an alarm is an operational action, not a configuration change.

Alarms should be matched to alarm databases when the application is created. If an alarm is switched from one database to another, you will lose access to the portion of the alarm's history that was recorded using the first database.
The selection of which alarm database to use is based on each tag's position in the tag hierarchy. Alarms are matched to the closest AlarmDatabase tag ancestor in the hierarchy, defaulting to the built-in System Alarm DB if no other database ancestor is found.
An alternate AlarmDatabase can be configured within the Alarm tag.

Trip Alarms Versus Level Alarms

Alarm tags can be configured as either "Trip" or "Level".

A level alarm will show up in the Active List as long as the underlying trigger condition remains true. The underlying condition must be cleared before the alarm is removed from the list of Active alarms.

The opposite of "Active" is not "Inactive". The opposite is "Normalized".

Trip alarms do not have an Active or Inactive status. After being triggered, the trip alarm is simply in an alarm condition, waiting for operator acknowledgment. A trip alarm will not be displayed in the list of Active alarms. They are primarily used in situations where the momentary existence of an alarm condition should "trip" the alarm, after which the state of the trigger is irrelevant.

Level alarm example

An alarm is set to be triggered when the pressure within a tank rises above X. This happens and the alarm is now both current and active. But before the operator acknowledges the alarm, they fix the problem by relieving pressure so that it falls below the setpoint (plus deadband if one is in use). The alarm has now normalized and is no longer shown in the list of Active alarms, but it remains Current and must still be acknowledged.

With a level alarm, you know from the triggering tag's value whether there is still an active (dangerous) situation.

Trip alarm example

An alarm is set to be triggered when a door is opened and the security code is not entered. But following this event, you cannot tell from the state of the door, whether the burglar is on the inside or the outside. A burglary could be as actively in progress with the door open as closed. This is a use-case for a trip alarm. The alarm has been tripped and is current. Checking the "Active" list for the state of the door is a waste of time and therefore trip alarms are not shown in the list of active alarms.

Use a trip alarm when the triggering tag's value does not tell you whether there is still an active (dangerous) situation.

The important point is that both types of alarms are equally alarms. The fact that trip alarms are not shown in the "Active" list does not mean that they have somehow been deactivated.

Closed Alarm properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Alarm properties Trigger tab

The Trigger tab for the Alarm tag properties folder consists of the attributes used to identify the conditions that the Alarm tag will evaluate to determine whether an alarm should be triggered.

The Triggered By field is used to select the tag that is being monitored by this Alarm tag. The Setpoint property displays a value (or a tag) that will be compared to the value of the tag being monitored (as identified in the Triggered By tab). The Function property selects the operation that is to be performed to compare the monitored tag's value with the Setpoint value.

Triggered By

Select the tag whose value will be monitored and compared to the value of this Alarm tag's Setpoint value to determine if this alarm should be triggered.

The Triggered By field can be used to associate this Alarm tag with a new or existing numeric tag using the tag browser button to its right. The Triggered By field can be cleared of its current value using the X button to its right.

Right-clicking the name of the I/O tag that has been selected in the Triggered By field opens the tag properties folder for the selected communication driver tag.

While the link can be made using either the Expression or the Tag option, this alarm will not show up in a trend plot of the triggering tag if the link is made using an expression. If you specify the Triggered By tag directly then the alarm line will be shown. (Assumes that the pen in the HDV is configured to show alarms.)

Function

The Function drop-down list enables you to select one of 11 operators to use to compare the value of the Triggered By tag with the Setpoint value configured for the Setpoint field to determine if there is an alarm state.

Mode

Three modes are available:

Standard

The alarm watches the value of the Triggered-by tag or expression. This is how alarms have always worked prior to version 12.1.

Unconfirmed Write

Also referred to as "Failure to Operate". Set the Function to "Equal to" and the Setpoint to 1. Use only as a Trip alarm and always set an On Delay. Will not work if Triggered-by is set to an expression, or with any tag type other than I/O and Calculations. Does not work with memory tags or calculated outputs.

The alarm will trip if the triggered-by tag writes a value and, after a delay, its feedback value does not match the written value. This assumes that you have configured a feedback value for the triggered-by tag.

Unexpected Change of Value

Also referred to as "Unexpected Change of State". Set the Function to "Equal to" and the Setpoint to 1. Use only as a Trip alarm. Will not work if Triggered-by is set to an expression, or with any tag type other than I/O and Calculations Input tag.

The alarm will trip if the triggered-by tag receives a feedback value that is different from the last value that it wrote out. The intent is to trip an alarm if the value in the PLC is changed by a method other than the triggered-by tag. This alarm is expected to be set to Trip.

Setpoint

You must provide a setpoint to configure an alarm. The alarm will trip or activate when the triggering value matches the setpoint, according to the rule set by the selected function.

The valid value for the Setpoint field can be provided via any of a constant, an expression, or a tag. Please see Constant, Expression or Tag for help selecting which to use.

Deadband

The Deadband field specifies how far the triggering value must return into the safe zone before the alarm is no longer considered active. Deadband values are used in systems where analog values fluctuate often, sometimes providing a false data reading.

On Delay

Use the On Delay field to specify a length of time (in seconds or in fractions of a second) that the system will wait before triggering this alarm. This enables you to disregard transient spikes in value as the tag must remain in an alarm state for the amount of time specified in the Delay field before an alarm will be indicated.

Off Delay

Similar to the On Delay, the Off Delay field can be used to specify a length of time (in seconds or in fractions of a second) that the system will wait before the alarm will return to the normal state. (The triggering condition is no longer true).

This enables you to disregard transient spikes in value that may occur after an alarm has been activated. The Off Delay does not apply to trip alarms, which do not have an active state.

Alarm properties Actions tab

The Actions tab for the Alarm tag properties folder enables you to select an Alarm Priority tag whose of properties will be used to indicate the category of alarm to be triggered by this Alarm tag (see Alarm Priorities). Other properties available on the Actions tab allow you to disable the alarm in the event that alarm conditions could be triggered due to routine equipment maintenance or another interruption in communications of which you are aware. The sound to be used for the alarm siren for this alarm can also be indicated here.

Disable Alarm

Use this check box to disable or enable this Alarm tag. Disabling an alarm is a configuration action and usually done within the properties dialog.

If an Alarm tag is drawn on a page, users who have the Alarm Disable privilege but not the Tag Modify privilege will be able to disable that alarm using the right-click menu.

Users familiar with VTScada from before version 12.1.28 may expect to see an option to set an expression or tag for disabling an alarm. For that, use Suppress.

Suppress

Create an expression or select a tag that will suppress the alarm when TRUE and unsuppress it when FALSE.

Suppress Alarms

Alarm Rearm Time

Applies only if Alarm Rearm Enable is selected for this alarm. If the alarm has been acknowledged, but remains active for the time shown in this field, the alarm will return to the unacknowledged state. Audible and visible warnings configured for this alarm’s priority level will again be displayed. The Alarm Rearm Time is measured in seconds, and defaults to 3600 (1 hour). The value in this field must be greater than 0.

Alarm Rearm Enable

Controls whether this alarm will revert back to an unacknowledged state if it remains active for the length of time set in Alarm Rearm Time, after having been acknowledged by the operator.

Trip

Choose whether this alarm is a trip alarm or a level alarm, as described in the introduction to this tag.

Priority

Set the priority of this alarm by selecting an Alarm Priority tag. The built-in Alarm Priority tags have numbers from 0 to 4 with the following meanings:

  • None.
  • 0 (event) - the alarm will not occur, but its value may still be used as a set point by other tags.
  • 1 (critical) - the highest priority alarm.
  • 2 (high) - a regular priority alarm.
  • 3 (warning) - warning.
  • 4 (notice) - a notice or informational event. Logged in the event history, but otherwise silent.

You may also create your own Alarm Priority tags.

Sound

Identify what audible warning will be played when this alarm is triggered. The Sound field can be set to a 0, a 1, or to the name of a .WAV sound file to be played.

If the Sound field is set to 0, no sound will be played when this alarm is triggered.

If the Sound field is set to 1, the sound configured in the associated Alarm Priority tag will be played.

If the Sound field identifies the name of a .WAV sound file, it will override any alarm sound configured for the associated Alarm Priority tag. When specifying a sound file, you must enter its name and extension (e.g. MySound.wav). The specified sound file must be a .WAV file, and must be stored in the application directory. If the specified sound file is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Alarm Database

This tag will be auto linked to the closest ancestor or else sibling Alarm Database tag and the hierarchy. If none found, it will use the System Alarm Database.

Use this parameter to link the tag to an alternate Alarm Database of your choice.

Pop-up Enable

If the configuration variable AlarmPopupsEnable is set to 1, then selecting this option will result in a pop-up dialog being displayed whenever the alarm is triggered. The variable can be set using a check box within the Application Configuration dialog, Alarms tab.

The pop-up will display the names of all active alarms for which the Pop-up option has been selected. As alarms are acknowledged, they will be removed from the pop-up. Should all the alarms be acknowledged while the pop-up is displayed, it will close. You may close the pop-up at any time by selecting the Close button. The pop-up will not be displayed again until a fresh alarm event occurs.

Alarm properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed Alarm Tag Widgets

An alarm tag has a value of zero or one, depending on whether the alarm is on the active list (one for active). The alarm tag may therefore be drawn as if it were a digital status. Note that trip alarms are never in an active state and therefore will always have a value of zero.

The following widgets are available to Alarm tags:

Alarm Priority Box

Alarm Priority Icon

Animated Image Widget

Color Blink Widget

Color Box Widget

Color Line Widget

Equipment / Status Color Indicator

Image Change Widget

Indicator Light Widget

Text Change Widget


Alarm Database Tags

Not counted towards your tag license limit.

The Alarm Database tag type is used to link alarms and events to Historian tags. They are also used to preselect the columns that will be shown when viewing the alarms from a particular database in the Alarm Page.

Every VTScada installation comes with two Alarm Database tags: System Alarm DB and System Event DB. The term "System Event" refers to the VTScada event-level actions that will be recorded using the System Event DB tag. This includes operator actions such as signing in and changing output tag settings. It also includes events such as report generation using a Report tag.

Alarms are associated with their closest Alarm Database ancestor in your tag hierarchy. Any alarm that does not have a specific Alarm Database tag as an ancestor will be associated with the System Alarm DB. This includes user-defined alarms that are given priority 0 - Event. Only VTScada events are logged with the System Event DB tag.

If configuring an I/O and Calculations tag (advanced alarm mode) or an Alarm tag, you are free to select any Alarm Database for that tag's alarms.

Version 12.0.18 introduced a change in alarm database behavior: In earlier versions, all operational events related to tags were stored in the System Event DB. From 12.0.18 onward, operational events related to tags are stored in the parent alarm database, if one exists. Otherwise, they continue to be stored in System Event DB. For those using custom Alarm Database tags, this simplifies filtering.

Alarm Database tags are treated as containers, similar to the Context type and include all options for site display configuration.

Depending on the size and complexity of your application, there can be benefits from creating extra Alarm Databases. Do so if any of the following apply but avoid creating extra databases if they are not needed.

  • Security across realms.
    Realm filtering can be applied so that an operator can be restricted to see only the alarms from a single alarm database (or set of databases). All other databases could be hidden from this operator.
    Note that it is not a requirement that you create multiple alarm databases to use realm filtering.
  • Management of alarms.
    If operators in different roles or locations are required to look after a certain subset of alarms, those alarms could be kept in a separate database so that no filtering is required in the alarm list beyond the selection of which database's alarms to show.
  • Efficiency.
    It can be slow to filter alarm history if there are millions of alarm records in a database. If the alarms are distributed between multiple databases then each will be smaller, thus making it faster to filter alarm history.
  • Management of large, widely distributed systems.
    If two or more plants are part of the same application, and those plants are separated by a slow network link, then you can improve local performance by setting up an Historian-AlarmDatabase pair for each plant, where each plant will be use local server(s) for its primary server.
    (We do not recommend creating additional Historians except in large or widely-distributed systems.)

Switching Databases

There is no restriction on moving an alarm from one database to another, but in rare circumstances the alarm may be temporarily orphaned on the old database. This could result in duplicate alarms on the alarm page and may result in an alarm activation not being logged in the new db. The orphaned alarms will be purged automatically within a few minutes of application start, as controlled by the property, AlarmDatabasePurgeDelay. See: Orphaned Alarms

To move an alarm to a new database, move the tag to become a child of the new Alarm Database tag or change its configuration to link to the new database. A decommission event will be registered for the old database, and a commission event will be registered for the new.

Every Alarm Database tag will have its own child Notebook tag, which will be created automatically. All notes created for an alarm are stored in the notebook associated with the matching alarm database.

Related information:

Realm Filtering, Global Tag & Area Filtering

Alarm Database Groups

Historian and Logger Configuration

Best Practices for Tags

Sites & Maps

Closed Alarm Database properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Alarm Database properties Settings tab

Use the Column Format selector to choose how alarms in this database should be displayed on the Alarm Page. Your options are as follows:

Column Format | Displayed columns
Alarms | Time - Priority - State - Event - Area - Name - Description - Value - Setpoint - Units - Operator - Notes
Events | Time - Area - Name - Description - Workstation - Device - Operator - Notes
Legacy 1 | Event - Priority - Time - Area - Name - Description - Operator
Legacy 2 | Time - Name - Description
Legacy 3 | Time - Ack - State - Event - Priority - Area - Name - Description - Operator
Legacy 4 | Time - State - Event - Priority - Area - Name - Description - Operator
Legacy 5 | Ack - State - Event - Priority - Area - Name - Description - Operator
Legacy 6 | Time - Event - Priority - Area - Name - Description - Operator
Legacy 7 | Time - Name - Description - Ack
Locks | Relevant only to the Alarm List Widget / Locks List Widget. Displays currently active Control Locks and provides a means for authorized operators to release those locks. Described in Locks List Widget
Popups | Priority - Ack - Name - Description

As an advanced configuration option, you can create your own column formats by writing XML templates. See: Customize Columns in Alarm Displays

Alarm Database properties Historian tab

Historian

Do not use the same Historian for both alarm history and tag data.

An Historian tag must be selected in order for this alarm database to save alarm history. Historian configuration and advanced logging options are described in the discussion of the Historian Tags. By default, the System Alarm Historian is selected.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible.

Alarm Database properties Site Display tab

There are two ways to prevent a site's location pin from being shown on a map: Leave the Latitude and Longitude values empty, or deselect the Show option for the map icon. If the site has latitude and longitude values, but the icon is not displayed, then the indicator beacon will pulse while the cursor is held over the site's coordinates on the map, even though the pin is not displayed.

Latitude and Longitude

Holds location coordinates for this tag, thereby allowing it to be represented on a Site Map page if the map icon is shown.

Custom Details Page

If a custom details page has been created for this context tag, then that page should be selected here. If there is no custom details page, then operators will see the standard Site Details page upon clicking the pin for this tag in a Site Map.

Map Icon

You might choose to define a location for this site, but not display it on a map.

If a custom map icon widget has been defined, you can select it here. That icon will then be used instead of the standard icon when this tag is represented on a Site Map page. If there is no custom map icon, then the standard widget will be used. A custom map icon is any tag-widget that can be linked to this tag type.

Site List Display

This tag will be included in the list of a Sites page. What will happen when an operator clicks on this tag in that list depends on the Site List display choice, and on whether any of this tag's children are I/O tags. Note that the following applies only to the list section of the Sites page, not to the map.

  • Display as Site: A click will open the Site Details page as a pop-up.
  • Display as Folder: A click will leave focus on the Sites page, but the list will now show the child tags of this site.
  • Exclude from Site List: This tag should not be shown in the list section of the Sites page.
  • Only Display Child Tags: This tag is used to group other sites. Those sites should be displayed, but this one should not be displayed. Operators will not need to navigate through this site to reach the child sites.
  • Automatic: If this tag contains child sites, folder display will be used. Otherwise, site display will be used.

Map Zoom Level

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Closed Alarm DatabaseTag Widgets

The following widgets are available to display information about your application’s CalAmp diagnostic driver tags:

Alarm List

Alarm Priority Box

Alarm Priority Icon

Draw HDV Widget

Site Alarm List

Site Details Widget

Site Icon Widget

Site Summary Widget

Tag List Widget


Alarm Priority Tags

Not counted towards your tag license limit.

The Alarm Priority tag type is used to specify different alarm indicators such as the frequency of the alarm tones, the tone cycle, the priority number, and the symbol and highlight color used to represent alarms of this priority. All alarms are associated with an Alarm Priority tag so that when the Alarm tag is triggered, the sound and color indicators configured for the Alarm Priority tag with which the alarm is associated will be activated.

Every standard VTScada application includes five Alarm Priority tags , as described in the following table:

Tone Cycles: 0 means no tone and positive values set the number of repetitions. All priorities can have two tones, each of which can be configured for frequency (pitch) and duration.

All alarm priority tags are part of area, "System". The default duration for all tones is 0.5 seconds.

Priority 0 is defined as an "event" rather than "alarm". These are logged, but will never trigger any notification, will never be "active", and cannot be acknowledged.

Name | Descriptor | Priority # | Color | Symbol | Tone 1 Freq | Tone 2 Freq | Tone Cycles
AlarmPriority0 | Event | 0 | White | none | 0 Hz | 0 Hz | 0
AlarmPriority1 | Critical | 1 | Red |  | 2000 Hz | 1000 Hz | unlimited
AlarmPriority2 | High | 2 | Orange |  | 1800 Hz | 1000 Hz | unlimited
AlarmPriority3 | Warning | 3 | Yellow |  | 1600 Hz | 1000 Hz | unlimited
AlarmPriority4 | Notice | 4 | Cyan |  | 1400 Hz | 1000 Hz | 0

Related information:

Best Practices for Tags

Spoken Alarms on the Server or Workstation

Closed Alarm Priority properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Alarm Priority properties - Display tab

The Display tab for the Alarm Priority tag properties folder sets the priority number of the alarm and holds the properties used to help operators visually identify the priority of alarms associated with this tag.

Priority

The Priority field sets the priority of this alarm as a number from 0 to 4, where:

  • 0 indicates an event rather than an alarm. Events are recorded in the history, but require no operator response.
  • 1 indicates the highest priority alarm, usually described as "critical".
  • 2 indicates a regular priority alarm, usually described as "high".
    Only priority 1 and priority 2 alarms will be sent to the alarm notification system for dial-out, email or SMS text notifications.
  • 3 indicates a warning.
  • 4 indicates a notice or informational event

You may set the Priority property to values higher than 4 for user-defined alarm priorities.

Priority Descriptor

Use this field to enter a short text description that will be used to identify the priority of those alarms associated with this Alarm Priority tag. This description will appear when filtering drop-down lists, and in the alarm list, wherever alarm priority is referenced.

Color

When clicked, the Priority Color button opens the Select Color dialog from which you can select the color you wish to be used to highlight alarms of this priority in the alarm list (thereby helping operators to identify the priority of the alarm visually.

Icon

Select any of the preset icons, or choose a custom icon. This will be used in alarm lists, and by the Alarm Priority Icon and Alarm Priority Box widgets to help operators identify the priority of alarms.

If you decide to use a custom icon, the Select button will open the VTScada graphics library. Select any existing image, or import a new graphic for use.

Icon Label

Sets the text to display within the icon. By default, this will match the priority number.

Icon Label Offsets - X and Y

Use these to adjust the location of the label within (or outside) the icon. An offset may be required for custom icon images to ensure that the label is clearly visible. Offsets are measured in pixels.

Alarm Priority properties - Sounds tab

Use this tab to control the sound that will signal alarms with this priority. You can define a tonal sound, enable speech, use any .WAV format file from disk, or set a combination. These settings do not apply to the voice calls made by the VTScada Alarm Notification system.

Sound Cycles

Specifies the number of times that the tonal or .WAV file alarm notifications will repeat. The default is -1, signifying unlimited repetitions until the alarm is silenced or acknowledged.

Speech - Enable Alarm Speech

Before enabling speech for this priority tag, you must open the Application Configuration dialog, select the Alarms tab of the Edit Properties page and there select, "Speak alarms instead of playing sounds".

A check box to enable or disable spoken alarms. Refer to Spoken Alarms on the Server or Workstation for the instructions to make this feature work on your system.

Speech cycles

Sets the number of times that the message will be repeated.

Tone Frequency in Hz and Tone Period

The VTScada alarm sound consists of two high-pitched tones, alternating within a specific time period.

For all Alarm Priority tags, the default frequency for the second tone is 1000Hz. The frequency of the first tone varies from one Alarm Priority tag to the next so that each priority will have a distinct sound. Adjust tone and frequency as desired to create a distinctive sound.

.WAV File Name

The .WAV File Name field enables you to specify the name and extension of a .WAV sound file to be used in place of the typical alarm tones to signal to operators that an alarm has been triggered. A variety of sound files are included with VTScada.

If a .WAV file is specified, the Sound Cycles field controls the number of times the .WAV file is to be played after an alarm has been triggered.

When specifying a sound file, you must enter its full name and extension (e.g. MyAlarmSound.WAV) . VTScada searches for the specified .WAV file in your application directory if no path is provided. If the .WAV file is not found, the alarm will revert back to using the tones as specified in the Tone 1 Frequency in Hz and Tone 2 Frequency in Hz fields.

Alarm Priority properties - Settings tab

Deselect the option within this tab to exclude alarms of this priority from an "Ack All" command.

For the case where alarm acknowledgment should be allowed only under controlled circumstances, advanced VTScada programmers can create a hook module that enables the Ack button on a cell-by-cell basis within an alarm list. Refer to the Alarm Manger Service section under Scripting in this documentation.


Alarm Status Tags

Not counted towards your tag license limit.

This tag looks for active or unacknowledged alarms matching a given set of characteristics. It can be used to build a trigger for an output or another alarm. For example, you might use it to trigger a warning system when any alarm with a given priority in a given area is active.

The value of the Alarm Status tag will be either 1 or 0 depending on whether any matching alarms have been triggered.

If this tag is a child of an Alarm Database, it will look only for alarms in that database. Otherwise, it will look for all alarms in all Alarm Databases. Use with care if you have a large number of alarms in your system.

Related information:

Best Practices for Tags

Closed Alarm Status properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Alarm Status properties Alarm tab

The alarm tab is used to define which alarms will be counted an instance of the Alarm Status tag. Use the fields to select the characteristics that must be found in an alarm to be included in the count.

Low Alarm Priority

Select the lower end of the range of alarm priorities to be filtered for. Any alarm with a priority between the Low Alarm Priority and the High Alarm Priority, and matching the remaining conditions will be included in the filter. The minimum priority cannot be set above the maximum priority.

To filter for alarms of only a given priority, set both the Low Alarm Priority and the High Alarm Priority to that value.

High Alarm Priority

Select the upper end of the range of alarm priorities to be filtered for. Any alarm with a priority between the Low Alarm Priority and the High Alarm Priority, and matching the remaining conditions will be included in the filter. The maximum priority cannot be set below the minimum priority.

To filter for alarms of only a given priority, set both the Low Alarm Priority and the High Alarm Priority to that value.

Area Filter

Select the area that the alarm must be configured within to be included in the filter. Areas shown in the list include all system alarm areas as well as developer-created areas.

Name Filter

Use this field to restrict the list of filtered alarms to only those matching a given name. The * wildcard may be used to permit selection on a set of similar names. For example, "East*" will match "East Pump Alarm", "East Tank Alarm", etc.

Alarm List

Options include "Active", "Unacknowledged" and "Current". Only one option may be chosen. Restricts the filter to only those matching a particular list type.

Alarm Status properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed Alarm Status Tag Widget

The following widget is available to display information about your application’s Alarm Status tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Blink Widget | Color Box Widget
Color Fill Widget | Color Line Widget
Compass 1 Widget | Compass 2 Widget
LCD 5x7 Matrix Widget | Draw Text Widget
Droplist Widget | Equipment / Status Color Indicator
Image Change Widget | Indicator Light Widget
LCD Bar Widget | LCD 7 Segment Widget
Left Bar Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Glass Gauge Widget | Classic Gauge Widget
Retro Gauge Widget | Cockpit Gauge Widget
Aqua Gauge Widget | Army Gauge Widget
Backlit Gauge Widget | Nautical Gauge Widget
Quarter Arc Gauge Widget | Linear Gauge Widget
Antique Gauge Widget | LCD Ring Widget
LCD Arc Widget | LCD Meter Widget
Momentary Button Widget | Multi-Color Widget
Multi-Text Widget | Numeric Entry Widget
Numeric Value Widget | Plot Data Widget
Right Bar Widget | Rotary Control Widget (Knob)
Set Analog Value Widget | Legacy Set Value Button Widget
Legacy Set Value Hotbox Widget | Slider Widget
Text Change Widget | Top Bar Widget
Two Color Bar Widget | Sparklines Widget


PLC Alarm Tag

Counted towards your tag license limit.

This tag is designed to read alarm status and configuration from the PLC (where supported by your PLC and device driver protocol) for display in the SCADA system.

Use PLC Alarm tags where alarm logic is configured in the PLC rather than within VTScada. Alarm status and configuration is determined from the state of the PLC. The value of the PLC Alarm tag will be 1 when the alarm it monitors on the PLC is active and 0 otherwise, reflecting the state of the PLC.

By design, if communication with the PLC is lost after an alarm is reported, the PLC Alarm tag will continue to indicate the alarm until communication is reestablished and the alarm is cleared on the PLC. When using the PLC Alarm tag, the PLC is the alarm master, not VTScada.

If using this tag with a Control/CompactLogix or Micro800 PLC device (Rockwell devices), the alarm block name must be provided as a parameter to this tag, as well as the alarm type (Analog High, Digital, etc.). Using this information, the PLC Alarm tag will build all the necessary addresses. This note does not apply to other devices.

For customers using the legacy Oil & Gas Solutions layer, see: Deprecated PLC Alarm (OGS)

About Alarm Statuses

The status-related alarm controls issued from VTScada are to acknowledge, shelve or unshelve alarms. Limited support is also provided to enable or disable the alarm status (see following notes.) These status values are written to the PLC and read back into VTScada, where the current status of the PLC will be shown. The full set of PLC alarm status information, and how each status is handled by VTScada follows:

  • Active / Normal:
    This is a read-only status for VTScada. The value from the PLC tells the PLC Alarm tag whether it is in alarm or not, having value of 1 or 0 respectively.
  • Acked / Unacked:
    VTScada will read this status, but is able to write only an Ack to the PLC. VTScada cannot write an Unack status.
  • Shelved / UnShelved:
    VTScada will read this status and can also shelve or unshelve alarms within the PLC.
    Both the PLC and VTScada support their own shelving time. In a Rockwell PLC, there is a single shelving time for a single alarm block, which is required to allow shelving at all. This shelving time would apply to a single digital alarm, or the set of all 6 analog alarms in a given block. If a shelving time is configured in VTScada for a given alarm, the alarm will be unshelved at the Internal PLC time, or the VTScada shelving time, depending on which happens first. This allows different alarms in the same block to be shelved for different amounts of time in VTScada only.
  • Suppressed / Unsuppressed:
    Not supported by the PLC Alarm tag.

Auto unshelve causes the alarm to become unshelved.
Manual unshelve may cause some PLCs to unack alarms.

Alarm Configuration

Some users may want to issue configuration controls to the PLC via VTScada rather than use third-party software to do their PLC alarm configuration. The PLC alarm tag is able to configure Setpoint or Condition (for analog or digital alarms, respectively), Priority, Deadband, Delay and Disabled status. The PLC alarm tag has a custom widget for reading these configuration values as a reference, and outputting user-defined values to the correct address in the PLC.

To achieve this, the custom widget can be opened from the properties folder of the PLC Alarm tag. Control actions can be issued from the properties folder or from a page using the widget.

Rate of Change Alarms

VTScada will display positive values for both positive and negative rate of change values and setpoint on the alarm page. That is to say, if a tag’s value is rapidly decreasing, the positive ROC is not used, and the negative ROC will have a positive setpoint and positive value, with the implication that the rate of change being negative comes from the alarm type, rather than its value

Custom Alarm Values

VTScada conventionally interprets 1 as an active alarm and 0 as a normal status. Some PLCs work with opposite logic, 1 is a normal status and 0 is an active alarm. Using the Invert settings in the PLC Alarm tag will flip these values to make VTScada work compatibly with these devices. Some devices expect completely different values such as a discrete value (for example, 74) or a text value (for example, "Acknowledge"). You can create a custom property to write a custom value to the PLC.

PLCAlarm_Acknowledge_WriteValue property can be defined in two ways:

  1. A PLCAlarm_Acknowledge_WriteValue applicable to all PLC Alarm tags, it can be created in the Edit Properties Dialog of the Application Configuration.
  2. If you have multiple PLC Alarm tags requiring different custom Ack values, a PLCAlarm_Acknowledge_WriteValue can be defined in aContext Tags. Its custom Ack value is used by all its child PLC Alarm tags.

Custom Alarm Values are restricted to PLC Alarm tags with an Acked address. For any PLC Alarm tags that use custom Ack values, the Invert checkbox next to the Ack Address field has no effect.

Related information:

Best Practices for Tags

Closed PLC Alarm properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

PLC Alarm properties I/O tab

Configure I/O Device, PLC Type, Alarm Type, PLC Alarm Block Name, Custom Security Privileges, Scan Interval and Questional Data settings.

I/O configuration of a PLC Alarm tag

The I/O Tab includes properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU), or to the polling driver responsible for determining the order and rate at which data polls will occur.

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

PLC Type

Choose between "Control/CompactLogix or Micro800 PLC" (addresses are pre-configured) or "Custom PLC" (addresses must be provided).

Alarm Type

A selection of Digital, Analog High, Analog Low, etc.
Required when configuring a Rockwell driver. For custom PLCs this is used as a label to distinguish between alarm types on the alarm page and to determine the behavior of the tag based on whether it is an analog or digital alarm.

PLC Alarm Block Name

If a PLC alarm block name is given, it will preface the address parameters. If there is no alarm block name given, the addresses are complete.

For Rockwell drivers, this is the folder in the PLC that holds all the addresses of the alarm block registers. This is an address in the form, MyProgram:MyAnalogAlarm, under which the relevant alarms will be located. (For example, MyProgram:MyAnalogAlarm.HiHiEnable)

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the configuration of the PLC to only those operators who have been granted the matching security privilege. This applies only to the configuration of the Setpoint, Priority, Deadband, Delay, Disable, and Alarm Condition.

Scan Interval

Provide the frequency, measured in seconds, that the device should be scanned for new data. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

PLC Alarm Properties Addresses tab

Set Status, Ack, Disabling, Shelving, and configuration addresses. Address selector available for Control/CompactLogix or Micro800 PLCs.

Address configuration for custom PLC alarms

For Control/CompactLogix or Micro800 PLC, these show the pre-configured addresses based on the alarm type. (Addresses cannot be modified.)

For a Custom PLC, use this to input the PLC alarm’s function addresses. An address assist is provided as a convenience. Only the Active address is required for the PLC alarm tag to work, but each address provides additional functionality and information.

Many values are also invertible. If the "Invert" checkbox next to any address is checked, then VTScada inverts the value read from that address or inverts then writes the value to that address. This allows correct communication with PLCs that use values opposite to those that VTScada expects. For example, VTScada expects a value of 1 from a PLC as an active alarm, but some PLCs use a value of 0 for their active alarm. By reading the PLC's 0 as a 1, VTScada correctly registers the alarm. If a custom property is being used to specify a custom value, the Invert checkbox will have no effect.

Active address (Read, Invertible):

Used to read the digital status of the PLC alarm, 1 if it is in alarm, 0 if it is not.

Value address (Read):

Used to read the value in the PLC, used to determine its active status internally.

Acked address (Read, Invertible):

Used to read the acked status of the alarm. 1 is acknowledged, 0 is not.

Ack address (Write, Invertible):

Used to set the alarm to be acknowledged.

Disabled address (Read, Invertible):

Used to read the disabled status of the alarm. 1 is disabled, 0 is not.

Disable address (Write, Invertible):

Used to set the alarm to be disabled.

Enable address (Write, Invertible):

Used to set the alarm to be enabled.

Shelved address (Read, Invertible):

Used to read the shelved status of the alarm. 1 is shelved, 0 is not.

Shelve address (Write, Invertible):

Used to set the alarm to be Shelved.

Unshelve address (Write, Invertible):

Used to set the alarm to be Unshelved.

Setpoint address (Read/Write):

Used to set the alarm’s setpoint (Analogs only). Also read for display.

Priority address (Read/Write):

Used to set the alarm’s priority. Also read for display.

Deadband address (Read/Write):

Used to set the alarm’s deadband. Also read for display.

Delay address (Read/Write):

Used to set the alarm’s delay. Also read for display.

Condition address (Read/Write, Invertible):

Used to set the alarm’s condition (digitals only). Also read for display.

Not all addresses need be configured for a given PLC alarm. If there are not separate Acked/Ack bits in a given PLC, it is only required to configure one of them with the single read/write acknowledging bit. Similarly, for Disabling and Shelving, a single read/write address can be configured rather than using all 3 addresses, depending on the PLC in use. The table below shows the read/write behavior for various address configurations, using Disabled/Disable/Enable as an example. The same logic applies to the shelving/unshelving addresses.

Available Addresses Read disabled status from
(Address : Value) 		For disabling write to
(Address : Value) 		For enabling write to
(Address : Value)
Disabled
Disabled : 1 Disabled : 1 Disabled : 0
Disable
Disable : 1 Disable : 1 Disable : 0
Enable
Enable : 0 Enable : 0 Enable : 1
Disabled Disable
Disabled : 1 Disable : 1 Disable : 0
Disabled Enable
Disabled : 1 Enable : 0 Enable : 1
Disable Enable
N/A N/A N/A
Disabled Disable Enable
Disabled : 1 Disable : 1 Enable : 1

PLC Alarm properties Alarm Setup tab

Alarm Setup configuration of a PLC Alarm tag

Priority

For Control/CompactLogix or Micro800 alarms, there are two parts to priority mapping: The selection of the VTScada Alarm Priority, and the selection of the corresponding alarm severity value in the PLC.

In the case of a Custom PLC there are two methods by which to set the VTScada alarm priority, depending on the existence of a priority address. If a priority address is given, we read the priority of the alarm from the PLC through the priority map. If no priority address is given, the PLC does not govern the alarm priority, and we must assign a priority to the alarm internally. This is done through a priority selection droplist.

PLC Delay Units

The internal units of a custom PLC may be in seconds or milliseconds, while the delay of the PLC alarm tag is written and displayed in seconds. This configuration allows proper configuration (and therefore display in VTScada) of the delay from the PLC.

Configure PLC Alarm

Opens the following dialog...

PLC Alarm properties Configuration dialog

Properties you configure in this dialog are read from and written to the PLC.

Controls on this tab write to the PLC immediately upon change.

I/O configuration of a PLC Alarm tag

Setpoint

The setpoint for an analog alarm.

Priority

Use Priority drop-down tool to select the priority of the alarm that will be triggered for this tag. The available priorities are:

None 0 - Event 1 - Critical Alarm 2 - High Alarm 3 - Warning Alarm 4 - Notice Alarm

Deadband (Not relevant to digital alarms)

The Deadband field specifies how far the triggering value must return into the safe (normal) zone before the alarm is no longer considered active. Deadband values are used in systems where analog values fluctuate often, sometimes providing a false data reading.

Delay

There is a conversion that must occur between VTScada and the PLC. The delay in the PLC is measured in microseconds, while the standard VTScada delay is in seconds. PLC Delay Units applies a factor to the incoming/outgoing delay.

Disable

Use the Disable Alarm checkbox field to disable or enable this Alarm tag. Unchecked = 0 (not disabled) and checked = 1 (disabled). This feature is typically used in situations such as when routine maintenance is being performed. In such a situation, an alarm can be disabled until the maintenance is complete and communications are reestablished, thus avoiding false alarms.

Alarm Condition - Digital Setpoint

This setting is only used when the Alarm Type is set to Digital Alarm. Check Digital Setpoint to set the alarm condition value at the Condition Address provided in the Address tab. If no address is provided, the default value is 1.

Please note that the Invert setting applies here. If no address is provided and Invert is checked the default value becomes 0.

PLC Alarm properties Display tab

(Digital alarm version shown)

Associated Tag

If an I/O tag is reading a specific value from the PLC while the PLC alarm block is alarming on that value, it makes sense for the name of the alarm in VTScada to match the name of the I/O tag, rather than the name of the PLC alarm tag. Therefore, the alarm record will contain the name of the associated value I/O tag, which is obtained by setting the Associated Tag parameter of each PLC Alarm tag to be the tag from which the source value is read. The alarm record will show the description, units, and area of the associated tag, allowing the PLC Alarm tag to behave like a built-in alarm of an I/O tag.

Typically, this is done by making the PLC Alarm tag a child of the associated I/O tag.

Use Associated Tag's Info

Deselect if you have an associated tag, but do not want to use information from that tag for display purposes.

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Popup

If the configuration variable AlarmPopupsEnable is set to 1, then selecting this option will result in a pop-up dialog being displayed whenever the alarm is triggered. The variable can be set using a check box within the Application Configuration dialog, Alarms tab.

The pop-up will display the names of all active alarms for which the Pop-up option has been selected. As alarms are acknowledged, they will be removed from the pop-up. Should all the alarms be acknowledged while the pop-up is displayed, it will close. You may close the pop-up at any time by selecting the Close button. The pop-up will not be displayed again until a fresh alarm event occurs.

Append state to alarm description (Digital alarm only)

When selected, VTScada will append the text used for the state of the tag, as taken from the Off Text and On Text fields in the associated tag’s I/O tab, to the alarm message.

Engineering Units (Analog alarms only)

Enter the units that should be displayed with the alarm.

Related information:

PLCAlarmCfgDeadbandDigits

PLCAlarmCfgDelayDigits

PLCAlarmCfgSetpointDigits

PLC Alarm Control Widget


Alarm Notification System Tags

The VTScada Alarm Notification System contacts designated operators by phone, pager, or email when alarms have gone unacknowledged for a user-defined period of time. This is an optional component of your VTScada license.

Tags used by the Alarm Notification System include:

Related information:

Modem Tags. Used to configure the modem through which voice calls will be made.

Roster Tags. Used to designate who will be contacted for alarms in a given area, and the method of contact for each user.

SMS Appliance Tags. Used to configure the SMS device through which text messages will be sent and received.


Modem Tags

Viewing: Reference > Tag Reference > Alarm Notification System Tags > Modem Tags

Concepts:

Alarm Notification System - Alerts by Phone, Email or Text

Roster Selection Hierarchy

Tasks:

Email Setup for Alarms and Reports

Reference:

Roster Tags

SMS Appliance Tags

Call Progress and Error Codes

Modem Tags

Not counted towards your tag license limit.

Modem tags enable outgoing and incoming calls by providing a link between your VTScada application and a modem configured on your system. This is not the same as configuring a Serial Port that uses a modem for communication.

If configuring a modem for use with the Alarm Notification System, ensure that it is a true voice modem. Refer to instructions within Install a Voice Modem.

The workstation name configured in the Modem tag must be no longer than 15 characters.

Your choice of Area property for a Modem tag will affect how it works. When used with the Alarm Notification System, the area property of a Modem tag must be left blank.

If your application uses one modem for I/O communication and another for the Alarm Notification System, then you should set the area property of the data modem to match the area property of the port. You must also add the application property, "UseSerialAreaInModemCall", and set it to 1. This will force all data calls to use the modem having an area that matches that of the attached serial port.

If running multiple applications (for example, hosted systems) then you cannot share modems, SMS devices, or Twilio accounts between applications. You must have independent modems or Twilio accounts for each application.

You can monitor the call status by using a Modem Indicator widget to display the modem tag's value. This will be a numeric value, with meanings according to the following table.

Value | Modem Error
0 | Modem idle
1 | Modem calling
2 | Modem answering
3 | General failure (other than listed here).
4 | Server is unavailable
5 | Workstation that owns the modem is unavailable.
6 | Cannot use serial port due to an external condition. The modem will poll occasionally for revised status. The polling time is set by MMUnAvailRetry, and defaults to 60 seconds.
7 | Manually disabled - will not clear automatically.

Related information:

Best Practices for Tags

Closed Modem properties ID tab

The Area property for a voice Modem tag must be left blank.

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Modem properties Settings tab

All fields are in this tab are mandatory.

The Settings tab of the Modem tag properties folder contains properties that allow you to configure the network and security settings for the Modem tag. A message is provided to the right of the workstation name, provides extra information about the station's availability, as follows:

If the Workstation field is left blank, the modem tag is for a so-called, local modem, and the text "Local" will be displayed in the workstation message field. This configuration is not recommended - it is much better to specify the workstation name even if VTScada is running only on a single workstation where the modem also resides. (The term "Local Modem" does not mean simply that the modem is on the same machine.) The "Index" parameter (the modem name) for the modem tag is ignored if this modem tag is for a local modem. Local modems are specified by a configuration setting in the <workstation>.Startup file for each workstation as follows:

<Modem tag name>Device = <Modem friendly name>

For example:

Modem1Device = MultiTech Systems MT9234ZPX-UPCI [Trihedral]

If this setting is not provided, the modem manager will select a modem from the list of modems not already associated with a modem tag. (Results may be unexpected.)

Local modems are typically used only if PPP is being used by VTScada, or in a system with custom software designed to use local modems. Under typical operating conditions, Trihedral recommends that local modems NOT be used.

The text, "Available" or "Unavailable" in the workstation message field refers to the workstation's availability. It is displayed even if no modem has been selected.

Workstation Name

Specify the name of the computer to which the modem is connected. (You must provide the computer name and not an IP address.) If you do not specify a workstation in the Workstation Name field, VTScada will use a local modem on a machine that is running that tag within the application, selecting the first modem that is available.

After the workstation name has been specified, the Line Name and Name Or Index On Workstation drop-down lists will automatically update to display the names of the Serial Port tags and modems available on this workstation.

The workstation name configured in the Modem tag must be no longer than 15 characters.

Line Name

Select or create a name. The same line name must be used by modems sharing the same physical phone line, even if they are on different workstations. Names must be different from those used by modems on other physical phone lines.

Name Or Index On Workstation

The Name Or Index On Workstation drop-down list enables you to select a modem on the workstation specified in the Workstation Name field, provided that the workstation is available. If the specified workstation is not available, you may enter the name of the modem you wish to use, or can enter a number or text value as follows:

If this value is numeric, it is the index into the list of modems shown in the Modems Properties dialog box in the Windows Control Panel, starting from 1.

If the value of Index is a text string, it is the name of the modem exactly as it appears in the Modems Properties dialog that is accessed using the Windows Control Panel.

Because the index of available modems can change over time, it is recommended that you refer to the modem by name rather than by its index in the Modem Properties dialog box.

Ring Count

Select the number of rings you wish to occur before the selected modem answers an incoming call.

If the value of Ring Count is 0, the modem will not answer any calls.

Regardless of this setting, the modem will not be answered if the application property, AnswerCalls is set to 0. Information on this and other configuration variables pertaining to the Modem Manager can be found Application Properties for the Modem Manager.)

Security Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

In this case, "operation" refers to the ability to disable or enable the tag via the context menu. It does not affect whether the modem will operate while a user without the privilege is signed in.

Modem properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Modem properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Closed Modem Tag Widgets

The following widgets are available to display information about your application’s Modem tags:

Alarm Priority Box

Alarm Priority Icon

Animated Image Widget

LCD 5x7 Matrix Widget

Equipment / Status Color Indicator

Image Change Widget

Indicator Light Widget

LCD 7 Segment Widget

Modem Indicator Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget

Text Change Widget

VTScada also includes a Modem Tools folder within the Widgets palette, which contains modem diagnostics tools that may be added to a page.


Roster Tags

Viewing: Reference > Tag Reference > Alarm Notification System Tags > Roster Tags

Concepts:

Alarm Notification System - Alerts by Phone, Email or Text

Roster Selection Hierarchy

Tasks:

Email Setup for Alarms and Reports

Reference:

Roster Control Using Properties

Modem Tags

SMS Appliance Tags

Roster Tags

Not counted towards your tag license limit.

It is not necessary for users to have the Tag Modification privilege to update modem contacts. Grant the Edit Roster Contacts privilege to users who need to update the contact list, but who should not otherwise be able to modify tags.
Legacy applications used the Manual Data or Tag Parameter View privilege. Accounts with those privileges will be granted the Edit Roster Contacts privilege on upgrade. The older privileges will no longer serve to modify the roster.

Roster tags are designed to work with the Alarm Notification system. Using a Roster tag, you may configure contact information for up to 39 operators. When a Roster tag has been enabled, the notification system will contact the operators in order in the event that an alarm has been triggered and has gone unacknowledged for a user-defined period of time. The notification system will continue to contact the operators on the active Roster tag until the alarm has been acknowledged.

Roster tags do not work alone. You also need a way for notifications to be sent (Modem tag, SMS Appliance tag, email server, Twilio account, VOIP system, or pager system) and configuration of the Alarm Notification System properties .

Area Property and Roster Tags

The Area field, selected during configuration, is especially important for Roster tags. The Area field is used by VTScada to link the Roster to alarms with the same area. If more than one Roster shares the an area, only one can be active at a time. The active Roster Tag in an area is always the one most recently activated - all other Roster tags with the same area property are automatically deactivated when one is activated. (See: Roster Selection Hierarchy)

In general, Roster tags should use the area, Default, unless you intend to send different sets of alarms to different operators.

If a Roster is a child of a custom AlarmDatabase, it will notify for alarms only from that database rather than all. Alarms with a matching Area property but under other AlarmDatabases will not be sent out by this Roster.
You may switch to the legacy behavior where all AlarmDatabases are searched, but this will be slower if you have a large number of AlarmDatabase tags. See: LimitRosterToParentDB

Default Call-Out Off Roster

One Roster Tag, the Default Call-Out Off Roster, is configured in every VTScada system. No names should be added to this roster. Its purpose is to provide a means of telling VTScada to not notify anyone. Because only one roster in an area can be active at a time, if the roster that is active has no names attached, no one will be notified.

Whether existing alarms are sent to a roster as it becomes active depends on the configuration of the rosters.

Alarms are not transferred: Given two rosters, the first having no contacts (since operators are assumed to be on-site) and the second having a list of contacts for when operators are not on-site. As the second roster becomes active, existing alarms are not sent to it.

Alarms are transferred: Given two rosters, each of which has a list of contacts. As the second roster becomes active, existing alarms that were being called out to the now-inactive roster will switch to the currently active roster.

If your system includes more than one modem, and those modems are attached to servers located in regions with different area codes, then you must use the A canonical phone address is a text string with the following structure: + CountryCode SPACE [(AreaCode) SPACE] SubscriberNumber | Subaddress ^ Name CRLF … 1 for each phone number and you must configure the server's location within the Windows™ Phone and Modem Settings dialog.

"9" - Internal vs external phone lines

In the event that you must configure a Roster tag to include the prefix "9" from some workstations, but not others, you should use the Modem Settings dialog in the Windows Control Panel.

On a computer that requires the 9:

  1. Open the Control Panel.
  2. Open the Phone and Modem Options dialog.
  3. Select the Dialing Rules tab.
  4. Click, Edit.
  5. Ensure that the area code is set.
  6. In the appropriate boxes, enter the number "9".
  7. Click Apply and close.
  8. In the Roster configuration, ensure that you use canonical phone numbers.

Phone number formatting matters. You must use a format that is acceptable for whichever service provider or device you have opted to use. You are generally safe using the E.164 standard of canonical phone numbers Closed Microsoft Azure Active Directory app registration, an OAuth 2.0 provider., however, you are advised to check your device manual or check with your service provider to confirm their formatting rules.

Related information:

Best Practices for Tags

Roster Control Using Properties

Script a Custom View of a Roster (For advanced developers only.)

Closed Roster properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Roster properties Contacts

The Contacts tab for a Roster tag is used to create the list of people who will be notified, and to define how to reach each of them. The available methods include voice (a phone call) email, pager, text message, or text as a compact email via your cellular provider.

Use the [+] Add Contact button to create a new contact row.

The Contact List

Add both contacts and delay/repeat rules using the plus buttons at the lower left of the Contacts panel.

Each is added as a row in the list. The list can hold up to 39 contacts, each with its own delay or repeat rule. If there is no explicit delay rule between contacts, then there is no delay.

Blank contact rows are not saved and VTScada will perform basic error-checking of email address formatting. In general though, it is up to you to ensure that you have complete and accurate information for how to contact each operator. Use care when defining your roster.

Change the order of contacts and rules in the list by selecting a row then using the up or down arrows below the list. Delay/repeat rules apply to all preceding contacts, as marked by an arrow. Delay/repeat rules cannot be consecutive - every rule must be preceded by one or more contacts.

Use options within the Settings tab to choose whether to repeat the entire roster or stop after an attempt has been made to reach each active contact.

Each contact row contains the following columns:

Method

A drop-down selection of Voice, Pager, Email, Text message, or Compact email. You may need to click in the Method field to reveal the selection tool. Only contact methods that are configured can be used.

Name

Any name that you wish to provide to identify the contact. If the same operator can be contacted in different ways then you might include that information in the Name field.

Phone Number / Email addresses

Voice lines: Enter the contact’s phone number, using only the digits. If your phone systems requires a 9 to access an outside line, you will need to configure your modem options using the Windows™ control panel.

If your system includes more than one modem, and those modems are attached to servers located in regions with different area codes, then you must use the Canonical Address Format for each phone number and you must configure the server's location within the Windows™ Phone and Modem Settings dialog.

Pagers: The Phone Number field requires the paging company’s T.A.P. Modem Number (TAP = Telocator Alphanumeric Protocol). This number enables access to the alphanumeric paging network, enabling VTScada to send a message to the pager phone/PIN. The correct number for the Phone Number field can be obtained from your paging company’s technical support team.

Email addresses: If the selected contact mode is email, this field will be used for email addresses rather than phone numbers. You may enter several addresses, using a semi-colon between each.

Email Aliases

You may add a list of email aliases, from which acknowledgments will be accepted. This is useful when an operator has forwarded one or more email accounts to another that is used more often. Use a colon character to separate the list of email addresses to which the alarm will be sent from the list of email addresses that are acceptable aliases for those accounts. There is no need to add an alias address if the operator will reply from one of the addresses to which the notification is sent.

  • A semicolon ; between addresses: Send a notification to each
  • A colon : between addresses: Notify the first and accept a response from the following.

Example 1 - A simple configuration.

JoeOperator@CountyUtility.com

Example 2 - Configured with multiple addresses for one operator. A notification is sent to both addresses. Joe can acknowledge from either.

JoeOperator@CountyUtility.com;JoeOperator@GigaMail.com

Example 3 - Joe has forwarded his CountyUtility account to his GigaMail account. Notification is sent to his CountyUtility account, but Joe reads and acknowledges the alarm using his GigaMail account.

JoeOperator@CountyUtility.com:JoeOperator@GigaMail.com

While there is no limit on the number of email addresses you may have, the combined total number of characters may not exceed 255.

For those using Realm Filtering: Each contact user name in the roster that belongs to a realm must include the full realm qualifier. For example: WestRealm:Robert

Pager PIN

This field is used only with the pager communication method. A PIN is a required part of the pager contact information.

Username

The contact's account name as defined in the VTScada security system. Operators will not be able to acknowledge alarms via text or email unless this is provided. Leave blank for any operator who should be notified of an alarm but is not expected (or allowed) to acknowledge it by email or text.

Time Zone

If one or more of the contacts are located in a time zone other than that of the alarm server, they may find it inconvenient or confusing to translate the time stated in the alarm notification to their local time. If the contact's time zone is provided, using this drop-down list, then they will receive a message that has been adjusted to their location for them.

The list uses the names built into the Microsoft Windows' Multilingual User Interface Pack.

Enabled

A simple check box controlling whether the contact is enabled. Delays and repetition rules do not apply to disabled contacts; those contacts are simply not notified.

A parameter expression can be added to any contact's Enabled field, allowing you to enable / disable a contact based on any expression that returns a 1 (enabled) or 0 (disabled). (See: Automated Tag Configuration) Expressions must be added to contacts individually. There is no way to apply one expression to several contacts, other than to copy / paste.

Delete

Click the X at the right of each row to delete that row.

Roster Tag Message Dialogs

If an operator’s contact mode has been set to email and a badly formatted email address has been entered, then the following warning dialog will be displayed:

Click on the Close button and correct the email address before proceeding. The Roster tag will not permit you to save a badly formatted email address.

Roster properties Settings tab

Activation Trigger:

For any given area (including "Default") one roster, and only one roster, is always active. Activating a roster automatically deactivates all other rosters that share the same area.

You can draw a roster as a Make Active button to allow user control but many sites prefer to automate the process of switching rosters by using a Trigger Tag. Note that if using a Trigger tag, in addition to setting the On time, you should also set an Off time 30 seconds later. This will not deactivate the Roster, but will allow the next On time trigger to occur.

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application.

Global Setting Overrides

Settings in this section are typically set globally using the Alarms Tab of the Edit Properties Page but can be overridden for each roster.

Repeat at end of list

When Use Default is selected, repetitions of the list are controlled by the property EnableRosterListRepeat. You can choose to override that property on a roster-by-roster basis. You can also use the Enable selection to control whether this roster will repeat.

The behavior that is in effect is shown at the bottom of the contact list:

Delay before repeating roster

Applies only when you have chosen to repeat the entire roster. This is the delay in seconds before starting a repetition. (RosterListDelay)

Rather than repeat the entire roster indefinitely, you can use a Delay/Repeat rule within the contact list to set a defined number of repetitions.

Delay before notifying on priority 1 alarms

Overrides theCallOutDelay1 setting for this roster.

Delay before notifying on priority 2 alarms

Overrides the CallOutDelay2 setting for this roster.

Delay between contact notifications

Overrides the RosterDelay setting for this roster.

In legacy versions of VTScada, this controlled the delay between contact notifications. It is now used only as a default when defining delay rules in the notification list. If there is no explicit delay between entries in the contact list, then there is no delay between attempts to contact those operators.

Closed Roster Tag Widgets

The following widgets are available to display information about your application’s Roster tags:

Color Box Widget

Equipment / Status Color Indicator

Image Change Widget

Indicator Light Widget

Make Active Widget

Roster Alarm Test Widget

Text Change Widget


SMS Appliance Tags

Viewing: Reference > Tag Reference > Alarm Notification System Tags > SMS Appliance Tags

Concepts:

Alarm Notification System - Alerts by Phone, Email or Text

Roster Selection Hierarchy

Tasks:

Email Setup for Alarms and Reports

Reference:

Roster Tags

Modem Tags

SMS Appliance Tags

Not counted towards your tag license limit.

While VTScada will always attempt to send the text message, there is no guarantee that your the cellular provider will deliver all messages. Use the SMS option of alarm notification with caution.

The SMS Appliance tag works in conjunction with the Alarm Notification System option to allow alarm notifications to be sent as text messages to a mobile cellular device, and to allow alarm acknowledgment via SMS.

SMS messages are sent and received using an "SMS appliance", which is a cell phone (or "cell modem") tethered to a VTScada workstation via RS-232, Bluetooth, or USB. Any such "cell modem" should conform to ETSI TS 100 585, which is a part of the GSM standard applying to the AT command set for sending and receiving text messages. Devices that use the CDMA standard are not supported.

The SMS Appliance tag handles communications through the SMS appliance. The tag registers with the SMS Manager service as an SMS agent.

Because SMS appliances are usually installed as "modems" under MS Windows™, the configuration of the SMS Appliance tag enables the specification of this modem and the workstation to which the modem is attached. You may also set a security privilege, and if necessary, can mark the modem as disabled.

If running multiple applications (for example, hosted systems) then you cannot share modems, SMS devices, or Twilio accounts between applications. You must have independent modems or Twilio accounts for each application.

The SMS Manager takes care of forwarding message requests to any registered SMS agents in a round-robin sequence. It also provides a publisher for received SMS text messages. Code that subscribes to received messages will get notification of all received text messages. Subscribers are responsible for any filtering of received text messages.

The SMS Appliance tag will re-initialize the appliance once per minute to verify that it is still attached and functioning. Any error will result in a complete reset, which is repeated at a regular interval until the tag is disabled or a functioning device is available.

The SMS Appliance tag will queue messages to send so long as it is operating normally. Received messages are published immediately. If these should be queued, it is the responsibility of the subscriber to do so.

The value of the SMS Appliance tag can be used to monitor the device status, according to the following table. (These values are reflected in the SMS Indicator widget.)

Value | Meaning
0 | Initializing
1 | Connected to cell modem
2 | Sending an SMS Message
3 | Receiving an SMS message
4 | Checking the connection to the cell modem
5 | Disabled
6 | Workstation with modem is not available
7 | Modem unavailable

Error Messages
Most error messages associated with SMS come from the network and are not defined in VTScada. For more information about any error message you might see, including those in the alarm history, use an Internet search engine.
CME Closed Cellular Mobile Equipment errors passed through from the device are equipment-related while CMS Closed Cellular Mobile Switch errors are network-related.

Related information:

Best Practices for Tags

Closed SMS Appliance properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

SMS Appliance properties Settings tab

The Settings tab is used to identify the SMS appliance (SMS "modem") that will be used to send and receive messages.

Workstation Name

The name of the computer running the VTScada application, to which the SMS appliance is attached. (You must provide the computer name and not an IP address.) Workstation names must be no longer than 15 characters. Do not leave blank.

Name or Index on Workstation

The named workstation will be checked for devices. If more than one is found, you may select between them using this drop-down list. Names are preferred over index values, because the latter may change.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

In this case, "operation" refers to the ability to disable or enable the tag via the context menu. It does not affect whether SMS messages are sent while a user without the privilege is signed in.

Disable

Select this box to disable the device without removing it or deleting its configuration.

SMS Appliance properties Advanced tab

The fields in the Advanced tab are optional. These need not be set for most configurations and should be used only by developers who are familiar with the configuration of SMS devices.

In rare instances, a device might not use a standard configuration of 9600 baud, etc. Serial port configuration fields are provided for use when working with such a device.

PIN for SIM Card

If required, this will value will be assigned to you by your cellular provider. The password is preconfigured in most SIM cards.

SMS Gateway Number

If required, this number will be provided by your cellular provider. This number is preconfigured in most SIM cards.

Modem Initialization String

You may provide an initialization string, as specified in the user manual for your cell modem. This will be sent to the cell modem at the beginning of each initialization cycle.

In most cases, you do not need to provide this string to the tag.

Baud Rate

Change this field only if your device does not autobaud to 9600.

Data Bits, Stop Bits and Parity

If your device does not autobaud to 9600, you might also need to configure these other serial communication parameters.

Port Number

Use to specify the serial port if that information is not available via the installed drivers. A value set here will override any other port information.

SMS Appliance properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed SMS Appliance Tag Widgets

SMS Appliance Tags have a numeric value indicating their current state. The following widgets may be used to display this information:

Alarm Priority Box

Alarm Priority Icon

Animated Image Widget

Color Box Widget

Image Change Widget

LCD 5x7 Matrix Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 7 Segment Widget

SMS Indicator Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Text Change Widget


Data Logging and Reporting Tags

Viewing: Reference > Tag Reference > Data Logging and Reporting Tags

Logging and Reporting Tags

Data logging tags are used to record the values of input and output tags to disk so that they can then be used in the Historical Data Viewer and reports. Reporting tags are used to specify groups of tags upon which to generate timely reports. Notebook tags enable users to add notes on the new Historical Data Viewer page.

The relationship between Historian tags and Logger tags is that Logger tags define when data is to be stored, while Historian tags define where the data is to be stored. Each tag for which data is to be stored must have a unique Logger tag. A single Historian tag is often enough for an application.

Related information:

Historian Tags. Looks after writing data to storage.

Logger Tags. Links tags that do not have built-in logging to Historians. Enables configuration of logging frequency.

Optimize Your Configuration - Avoid problems when logging data

Notebook Tags. Used to add notes on the Historical Data Viewer page.

Report Tags. Generate a preconfigured report at the push of a button, or on a defined schedule.

SQL Logger Group Tags. Provides support for SQL Logger tags, by holding the connection information for the data store.

SQL Logger Tags. Writes data from a selected tag to the database configured in an SQL Logger Group tag.

Transaction Logger Tags. Used to record a collection of historical values as a single transaction.


Historian Tag

Viewing: Reference > Tag Reference > Data Logging and Reporting Tags > Historian Tag

Concepts:

Historian - API and Queries

Tasks:

Optimize Your Configuration

Historian and Logger Configuration

Historian Tags

Not counted towards your tag license limit.

The Historian Tag is used to write data that is to be logged to storage. (The Logger tag controls only how often the Historian tag writes.)

Every VTScada application will have a default instance of an Historian tag named "SystemHistorian" for tag I/O values and one named SystemAlarmHistorian, used by Alarm databases. In many cases, these will be the only Historian tags that you use in an application. The information will be written to a VTScada proprietary database format unless otherwise configured.

Do not use the same Historian to record both process values (tag I/O data) and alarm information.

The Historian tag's configuration panels provide access to only some of the available options. With a combination of Historian tags and related application properties, you can also configure the following:

  • Save data to a proprietary database such as Oracle, Microsoft SQL Server, MySQL. PostgreSQL , or SQLite instead of the VTScada database.
  • Ensure that a redundant backup exists by writing to separate storage locations on two or more servers.
  • Configure load sharing between servers.

The status of the Historian's connection to its data store can be viewed using the Historian Status Widget widget.

Related information:

Best Practices for Tags

Optimize Your Configuration - Avoid problems when logging data

Log and Report - Advanced options.

Alarm Data Logging - Details related to the alarm system.

Closed Historian properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Historian properties Datastore tab

Choose how and where data will be stored. Use only letters and numbers for the Storage Name.

Historian datastore options

Represent system downtime as missing data

Do not select this option in Historians used by Alarm Databases.

If selected, then system downtime will be represented as a gap in the data. If not selected, then the last recorded value will be taken as if it were in effect for the duration of the time that VTScada was not logging.

Options for system downtime

Enable Client Data Storage

Intended only for Alarm Historians. Do not enable client data storage otherwise unless you have a clear understanding of the costs and benefits. On a system with many clients, this feature can add a significant load to network communications.

This feature is intended for use only with Alarm Historians, allowing isolated clients to modify the alarm system database and obtain alarm data from local storage. When enabled, Client Data Storage increases availability of the alarm system, especially in the event of a client becoming isolated from the network. Alarm historians tend to be relatively small (averaging one or fewer alarm or events per minute) when compared to the SystemHistorian, which may be logging thousands of records per second. It is entirely possible to use alarm Historians without this feature, but those clients will not be able to generate alarms and events when isolated from a server. They will also have to obtain alarm history from the server, which may require significant data transfer.

You are strongly advised to avoid using this feature with Historians that are logging I/O data.
If you insist upon doing so, ensure that drivers are configured with the Hold option set, to prevent isolated clients from logging invalids and thereby causing HDV gaps.

When enabled on any Historian tag, that tag will synchronize and store its history files on all VTScada hosts, regardless of their presence in the server list. This generates extra synchronization and update traffic between all hosts and should only be used in the recommended circumstances such as alarm Historians, to allow alarm data to be available locally on all hosts.

Related information:

Historian Data Storage

Diagnostic Tracing

When enabled, diagnostic information such as error messages will be recorded to a file within the application's Data\TraceFiles folder structure. This option is enabled by default and should remain enabled in most circumstances.

Storage Name

Advanced Use Only. Enables a user-specified name to be used, rather than the tag's Unique ID. This provides control over the folder name that will be used in the data store.

If configuring an ODBC-based database, the use of this field is recommended, as the tag's Unique ID may not remain unique after being modified to a form that can be used by the ODBC driver.

Storage Type

Advanced Use Only. May be either "ODBC" or "ODBCSingleTable" if configuring an ODBC-based database. Defaults to the native VTScada storage system if blank and therefore need not be set unless using ODBC.

  • If set to ODBC, each tag's data will be stored in a table named for that tag's unique identifier.
  • If set to ODBCSingleTable, there will be one table per schema (analogs, digitals, drivers...) holding the data for all tags that match that schema.

If using an Oracle database as a target for historian data, the database must have a "tablespace" named "Users", which is not present in a new Oracle DB. This is used as the default tablespace for the user created by a historian tag, and is where all the historian tables are stored.
All tables are created with the "owner" (or schema) named after the tag name. So, given a historian tag of "SystemHistorian", then all tables are created with the owner SYSTEMHISTORIAN and have a name such as "SYSTEMHISTORIAN.FRIENDLYTAGNAMELOOKUP".

Storage Location

Advanced Use Only. If using the VTScada data store, you may use this field to specify the path to a storage location other than the default. (C:\VTScada\AppName\Data)

When using paths outside of VTScada install folder, ensure that VTScada will have read/write access to the new location. VTScada has no control over file permissions outside its installation folder.

If using an ODBC-based database, this should be set to either the configured DSN (Data Source Name) of the database as follows:

DSN=MyDSNName

Or, you may use a connection string, in the form:

Driver=ServerBrand;Server=ServerName;Database=DBName;Uid=user;Pwd=pwd

For compatible database types, refer to Historian Data Storage

While it is possible to set the storage type and location using application properties, you are advised to use the tag configuration fields described here instead.

Related information:

Historian Data Storage - More about storage options. How to configure logging to both the VTScada data store and a third-party database.

Query a 3rd-Party DBMS - Table structure

Historian properties Storage Limiting Settings tab

Historians used by Alarm Databases should not use storage limiting.

Choose whether to limit the data saved. If the data is to be limited, you can also choose whether to limit it by date, or by a maximum number of records.

Storage limiting tab

By default, no limit is set on the amount of data to be stored.

If you choose to delete data older than a given number of days, you will have the option of setting how many days that will be. The default is 365.

Default settings for storage limiting

If you have chosen to delete data, the only guarantee is that records stored since the parameter modification and newer than the limit are kept. Records that are newer than the limit BUT older than the parameter modification may be deleted.
Older records will be swept eventually and it is seldom worthwhile to focus on the value of the Sweep Interval.

The sweep interval sets the size of data blocks. It can be no less than one hour and no greater than 356 days. The default comes from the application property HistorianDataAgeSweepIntervalDivisor. (A more technical explanation is provided with the description of that property.)

Sweeping is done based on when data was recorded, which may differ from the data timestamp, especially in the case of manually entered data.
Data blocks are removed sometime soon after all recorded timestamps within a block are older than the set retention date. Changes to the sweep interval or the related Interval Divisor property do not cause existing blocks to be broken into smaller chunks and might not cause current data to be stored in a new block.

Older values will be swept eventually, and it is pointless to focus on the value of the sweep interval. Storage Limiting is about the amount of data to retain.

Historian storage limiting options

Estimate Days Left Before Your Hard Drive is Full

The following example is for advanced developers who are comfortable with scripting expressions.

It is possible to configure tags to provide a broad estimate of the time remaining before your hard drive fills up. You can do this by measuring the remaining space, measuring the rate at which space is being used and performing a calculation. The more consistent hard drive use is, the more accurate the estimate will be.

The scenario: You want to monitor hard drive C:\. Your application uses up space at a relatively steady rate and you'd like to know how many days of storage are left.

Four tags will be used:

  • Workstation Status tag
    • I/O & Calculations (Analog)
    • Rate of Change tag
    • I/O & Calculations (Analog Calculation) tag

Create a Workstation Status tag to detect remaining hard drive space.

Create an analog I/O tag as a child of a Workstation Status tag. Set the Read Address to "FreeDiskSpace" and select your drive (In our example, the read address displays "FreeDiskSpaceC".)

Find the Rate of Change over a day.

Create a Rate Of Change tag. Link it to the tag from the previous step. To get the rate of change over a day, set the period to 86400 (the number of seconds in a day) and set the refresh interval to 3600 (to refresh the value hourly).

Use an Expression in a Calculation tag to find days left.

Create an analog calculation I/O Calculation tag using an IO & Calculation tag. Use an expression like the following, where these refer to the two tags you just created...

[FreeDiskSpaceC] / [RateOfChange]

which should tell you approximately how many days you would get if the remaining space continued to decrease at the same rate each day.

Replace [Bracketed] terms with tag names. If your tags are not closely related, you may need to scope and specify \value in your expression.

Adapt to Your Application

If you have multiple historian servers you will need to configure multiple Workstation Status tags and pick the smallest remaining disk size to calculate the estimated days remaining.

In the provided scenario, the rate of change is on a per-day basis and it is updated once per hour.

Increasing the frequency may give your Rate of Change tag more data points but it will also impact your application performance.

If your application sees irregular spikes in hard disk space consumption, this will negatively impact the accuracy of your estimate. To smooth out spikes in the estimate, increase your sample size. (Collect the rate of change over a longer span and adjust your calculation expression to estimate days)

You won't see an estimate until a day has passed and under the assumption that there has been a change in hard disk space during this time.

Widgets:

Historian Status Widget - Displays information for all Historians, rather than being linked to a specific instance as widgets are.


Logger Tags

Not counted towards your tag license limit.

Logger tags are used to control when data is to be logged. They are required only for tags such as the Analog Input and Digital Input, which do not have logging built-in.

The Logger tag must be linked to an Historian tag, which will perform the actual recording of the data. The Logger's only job is to define when the value from the source tag is to be recorded.

Note that many tags have built-in logging through a connection to the Historian. As a general rule, the built-in logging is preferred when available. If you attempt to attach a logger to a tag that has its own historian connection, a warning will be displayed to discourage you from proceeding.

Logger tags themselves have no values and cannot be drawn on a page

Related information:

Best Practices for Tags

Optimize Your Configuration - Avoid problems when logging data

Closed Logger properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Logger properties Conditions tab

The Conditions tab for the Logger tag properties folder consists of the attributes used to identify the tag whose value should be recorded and the logging mode to use when logging the tag's data. The logging mode can be a time period or for whenever the monitored tag's value changes.

Log Data From

Select the tag whose values will be passed to an Historian by this Logger tag.

The Log Data From field can be used to associate this tag with a new or existing tag using the … button. The … button opens the Tag Browser, which displays only the existing tags for your application, and enables you to create a new tag using its New button. (Information on using the Tag Browser can be found in "Tag Browser").

The Log Data From field can be cleared using the X button to its right.

Right-clicking the name of the tag that has been selected in the Log Data From field opens the tag properties folder for the selected tag.

Log On Change As Well As Time

If the Log On Change As Well As Time check box is selected, data will be logged when the value of the tag being monitored changes as well as every defined interval as defined in the Log Rate tab. Note that this feature does not apply a deadband to filter out miniscule changes.

Enable

Enable or disable the logging of tag data by this logger using a constant value (either a 0, or a 1), an expression, or the value of a second tag.

If the Constant check box beneath the Enable field is selected:

  • Enter a 1 to enable the logging of the data for the tag being monitored.
  • Enter a 0 to disable the logging of the data for the tag being monitored.

Any expression or tag that returns either a 0 or 1 (or non-zero) can also be used. Please see Constant, Expression or Tag for help selecting which option to use.

Logger properties Log Rate tab

The Log Rate tab of the Logger tag properties folder is used to identify the rate at which the data is recorded for the monitored tag. Intervals start at midnight. An interval of 86400 (seconds in a day) would write a value once at the end of each day.

Logger properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.


Notebook Tags

Not counted towards your tag license limit.

Notebook tags are used to store user-created notes. In essence, they provide a named link to an encrypted data file where operator notes are stored.

VTScada comes with two Notebook tags preconfigured: System Notes, which is the default for the Historical Data Viewer and Operator Notes, which is the default for the Operator Notes page.

You may create as many Notebook tags as required to organize your information. Every Alarm Database tag will have its own child Notebook tag, which will be created automatically. All notes created for an alarm are stored in the notebook associated with the matching alarm database.

Related information:

Best Practices for Tags

Closed Notebook properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Notebook properties SetupTab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Notebook properties Quick Notes

Use this tab to create pre-written phrases that can be added to new Operator notes with a click. Each Notebook tag will maintain its own list of Quick Notes.

These can be templates with blanks for operators to fill in, or they can be often-used phrases or keywords to be used later when searching (example: [MAINTENANCE]).

By using a template, you ensure that information is organized in a consistent form within notes and that no details are forgotten. By providing often-used phrases, you can help operators by saving them the time they would otherwise spend typing the same phrase each time it's needed.

When operators add a Quick Note to a new note that they are writing, the text is copied to their editing field. No link is maintained between the Quick Note and the final version of the note that the operator saves.

Add a Quick Note by clicking the Add button. Provide a title, which will be visible to operators when adding notes, and the text of the note.

You may add, edit or delete Quick Notes at any time. No link is maintained between a Quick Note and a saved operator note, therefore the work that you do here has no effect on saved notes.

Closed Notebook Tag Widgets

The following widgets are available for your application’s Notebook tags:

Add Note Button

Note List Widget


Report Tags

Not counted towards your tag license limit.

The Report tag provides most of the features of the Reports Page, plus two extras:

  • It will trigger automatically on the interval you specify (perhaps every morning at 8:00).
  • It adds an offset to the time periods. For example, you could set the time period to be the Last Hour but offset such that data is for the hour ending 15 minutes before the report runs.

Report tags do not allow for multiple iterations on reports.

A record is added to the events history each time a report is generated using the Report Tag. Use this to verify that automated reports were created on schedule.

The Report tag need not be drawn to function. If drawn, you can show it as a time display, showing when the report was last run. You can also draw it as a button, allowing operators to run the report at a time of their choosing, or to repeat a missed report (a configuration option of the report button widget).

Worth noting: The Report Tools Library provides a number of widgets you can place on a page to allow an operator to adjust the report, without needing to grant tag configuration privileges. See: Run-Time Configuration of Report Tags

The value of the Report tag will be 1 when writing a report and 0 otherwise. When viewed in the Tag Browser, the address of the report will be the configured report type. ("Analog Summary Report", "Hourly Snapshot Report", etc.)

When running VTScada as a Windows service, DO NOT select Excel as an output destination or option from a Report Tag. As noted in the MSDN forums, office applications assume they are being run under an interactive desktop. If Excel attempts to open a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog from a non-interactive service, the result is an invisible dialog that cannot be dismissed, stopping the thread.

Besides the technical problems, you must also consider licensing issues. Microsoft's licensing guidelines prevent Office applications from being used on a server to service client requests, unless those clients themselves have licensed copies of Office. Using server-side Automation to provide Office functionality to unlicensed workstations is not covered by Microsoft's End User License Agreement (EULA).

Before configuring an email destination for a report, you must configure VTScada so that it can access your email server. See: Email Setup for Alarms and Reports

Related information:

Best Practices for Tags

Report properties ID tab

In the default ID tab, configure a name, area, description, select a report type and opt to set a Help Search Key.

The Report tag's ID tab has an extra field: Report Type

The Report Type drop-down list should be used to select the type of report that you want to generate using this tag.

Other fields are standard for an ID tab...

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Report properties Tag tab

Use tools within this tab to select tags to include in the report. Use the Type and Area filters to limit the number shown in the "available" list. Note that, if using either of the pump-related reports, the type filter will automatically choose the Pump Status type. You may switch to the Digital Status type for these reports.

Tag selection sets must be saved as a named group before you may proceed to the remaining configuration tabs.

In an application with many tags, it can be challenging to select those tags in this dialog.
Instead, use the Report Page, where there is much more space, to select your tags and save named groups. Then, you need only use the Load Group button when configuring reports with this tag.

Load a tag group, save the current configuration as a new group, Select tag types, and areas. Use the tag selector to manually select tags to add to the report. You may sort them alphabetically or rearrange the tag order from here.

Options for tag selection. Sets must be saved as a group.

Load Group

The Load Group button enables you to load a set of tags that has previously been saved. A loaded tag group can then be used to generate a new report based on your application's requirements. Step-by-step instructions can be found in Saving and Loading Tag Groups for Reports: Steps to Run a Report

Save Group

The Save Group button enables you to save the tags that have been configured for this report as a group that can later be reused for report generation. Step-by-step instructions can be found in Saving and Loading Tag Groups for Reports: Steps to Run a Report

Types

Use this drop-down list to select the type of tags you wish to include in this report.

The Types drop-down list is set automatically according to the setting of the Report Type drop-down list on the Report tag's ID tab. You will rarely need to change it.

Areas

The Areas drop-down list enables you to filter the tags to be included in this report by their Area property.

Tags Available

The Tags Available list displays the names and descriptions of those tags that are available for inclusion in the reports to be generated by this tag. The < button enables you to move a selected tag (or tags) between the Tags Available list and the Tags In Report list. The << button enables you to move all tags in the Tags Available list to the Tags In Report list.

Tags In Report

The Tags In Report list displays the names and descriptions of those tags you have selected to be included in this report. The > button enables you to move a selected tag (or tags) between the Tags In Report list and the Tags Available list. The >> button enables you to move all tags in the Tags In Report list to the Tags Available list.

Report properties Period tab

Use the Period tab of the Report Tag properties folder to select a preset time period or configure a custom time period for the report to be generated by this tag. Note that the Report Button widget (Report Button Widget) provides an option for an operator to re-run the last scheduled report in the event that a system interruption prevented that report from being generated.

Last versus Previous:

The terms "Last" and "Previous" mean different things in the context of a report. "Last" refers to a time period ending at present (or at a defined end time if defining a custom period). "Previous" refers to the most recent full period where weeks end on Sunday night, days end at one second before midnight, and hours end one second before the top of the hour.

For example, suppose that the current time is 3:25 p.m. on a Tuesday. "Last 24 hours before trigger time" refers to the period from 3:25 p.m. Monday until 3:25 p.m. Tuesday.

"Previous calendar day" refers to the period from 12:00 a.m. Monday until 11:59 p.m. Monday.

"Current" refers to the time frames such as "so far today" or "so far this week".

Preset the tag period, select a period type, report duration, end time or offset. Options will be enable/disabled or pre-filled depending on the Preset selection.

Presets

The Presets drop-down list can be used to select a preconfigured period of time for the data to be included in this report.

If Custom is selected, further options will be available.

Period Type

The selection is enabled for Custom presets and offers a choice between Previous Time Period, Duration and End Time and Raw Duration and Start Time.

Previous Time Period:

Select a time period (Days, Weeks, etc.) from the drop down list and enter a number in the field provided. "Previous" refers to the most recent time period, ending at a standard boundary such as the midnight, etc.

Duration and End Time:

Sets the length of time that should be included in the report, ending at a set length of time prior to the trigger event.

Raw Duration and Start Time:

Enables you to set report period parameters with a parameter expression. Switching Presets will auto generate values in the Report Duration and Report End Time fields.

Report properties Trigger tab

Select a trigger that will generate the report. A variety of timing options are available, or you can link to any tag that will change in value from zero to non-zero as the trigger. (For example, an Alarm tag or a Trigger tag.)

You may also leave the selection as "No Trigger" and draw this tag as a button that operators can press to generate reports on demand.

The trigger tab in the report tag properties sets conditions to automatically generate a report

Schedule an automated report run

Trigger

The Trigger radio buttons enable you to select an event that will prompt the generation of this report. This can be one of:

No Trigger Hourly at. (repeats every X hours, beginning at the specified time)

If X is 3, a specified time of 12:00, 3:00, 6:00 or 9:00 would all produce exactly the same result. You do not need to provide the earliest interval in the day.

If the system is offline when a report interval is due, that interval will simply be missed.

Daily Trigger (at a user-defined time) Weekly Trigger (on a user-defined day at a user-defined time) Monthly Trigger (on a user-defined date at a user-defined time) By Tag (when the value of a specified tag changes from false to true). The Trigger Tag field is not enabled unless the By Tag radio button has been selected.

Trigger Tag

The Trigger Tag field enables you to select any tag with a numeric value whose value will be used to generate this report (when the value of the selected tag changes, the report will be generated). The Trigger Tag field only becomes enabled when the By Tag radio button is selected.

Right-clicking the name of the tag that has been selected in the Trigger Tag field opens the tag properties folder for the selected tag.

Generation Modes

The Generation Modes radio buttons enable you to select where the report is generated.

All Workstations mode (Default) reports will be generated on all workstations. Server List mode enables you to select a server list. Reports will only be generated on the primary server in the list. If Server List is selected and no list is specified, the system will use the "Default Server List" Workstation mode allows you to name a single workstation upon which a report will be generated. If no name is specified, the system will switch to All Workstations mode.

Report properties Destination tab

When running VTScada as a Windows service, DO NOT select Excel as an output destination or option from a Report Tag. As noted in the MSDN forums, office applications assume they are being run under an interactive desktop. If Excel attempts to open a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog from a non-interactive service, the result is an invisible dialog that cannot be dismissed, stopping the thread.

Besides the technical problems, you must also consider licensing issues. Microsoft's licensing guidelines prevent Office applications from being used on a server to service client requests, unless those clients themselves have licensed copies of Office. Using server-side Automation to provide Office functionality to unlicensed workstations is not covered by Microsoft's End User License Agreement (EULA).

Use the Destination tab to configure an output format and destination for the report. All options from the Reports page can be found here. Available options will change according to the selected output type.

Select an output type, choose to open report when complete, email the report or email as an attachment. Set Email settings. Choose a printer.

Email must be configured in the Alarm Properties dialog

Output Type

The Output Type drop-down list enables you to select the format to be used to display this report. This can be one of:

Default Printer: Prints the report to the printer configured for your PC under the Windows operating system. Printer: Enables you to specify the path to a printer other than the default printer configured for your PC under the Windows operating system. Text File: Generates the report as a plain, unformatted text file with the extension .TXT. This option enables the transmission of report data in the body of an email message (see, "Email Report"). Screen Display: Generates the report in a window on your screen. This format enables the use of a Microsoft Excel template file to modify the way your report appears. Please refer to "Using a Microsoft Excel Template File to Generate Reports".

A report that has had its Output Type configured as ‘Screen Display’, and for which the ‘Use Excel to Display Screen Reports’ check box has been selected will open as a regular screen display over VIC connections. The ‘Screen Display Using Microsoft Excel’ feature is not available for VIC connections at the present time.

CSV File: Generates the report as a comma-separated value file with the extension .CSV. Such files are easily imported by a variety of different database software packages. This report output option enables the transmission of report data as an attachment to an email message (see "Email Report As Attachment"). Formatted Excel XLS File: Generates the report as a formatted Microsoft Excel spreadsheet with the extension .XLS. (The report will feature a bold title and column headings.) This report output option enables the transmission of report data as an attachment to an email message "Email Report As Attachment"). Plain Excel XLS File: Generates the report as a plain, unformatted Microsoft Excel spreadsheet with the extension .XLS. (Unlike the Formatted Excel XLS File option, the report will not feature a bold title and column headings.) This report output option enables the transmission of report data as an attachment to an email message (see "Email Report as Attachment"). Access MDB File: Generates the report as a Microsoft Access database file with the extension .MDB. This report output option enables the transmission of report data as an attachment to an email message (see "Email Report As Attachment"). ODBC Data Source: Enables you to specify an existing ODBC data source associated with an existing ODBC-compatible database file into which you wish the report data to be saved.

Open Report when Complete

When selected, if the user manually generates a report, it will automatically open in the specified format when the report is ready. A user can manually generate a report using a button linked to the report tag or by using the "operate" option from the context menu of the report tag. Reports will not open automatically if they are triggered or scheduled, as these are assumed to be unattended.

Email Report & Email Report as Attachment

When selected, the Email Report check box causes the report generator to email a copy of the report data to a specified address or set of addresses within the body of the email message. The maximum possible number of characters for the address is 255.
The Email option is available with most output types, provided that you have configured an email server.

The following is an advanced option.
In a multi-server environment, you may wish to have only the current System Historian server send the email. Do so by adding a non-optimized parameter expression to the check box. The expression will be similar to \RPCManager\GetServer("SystemHistorian") allowing for variation in the name or names you are using for your historians. (See: Automated Tag Configuration.

Email Settings

After choosing to email a copy of the report, click this button to open the Email Settings dialog, where the recipients, subject, and message for the email can be configured.

Email addresses may be in the basic form, Name@Company.Com" or you may use either of the following longer forms. Multiple addresses may be entered, separated by semi-colons or commas. Do not add spaces within the angle brackets.
"Full Name" <Name@company.com>
Full Name <Name@company.com>

Destination

The destination field's label changes according to the selected report output type.

You may enter a path, printer, or ODBC data source for the report. (A path is not required for Default Printer or Screen Display output types). You may specify a path or printer using either the Browse button to navigate to the desired location, or by manually typing the path into the destination field.

Browse

Opens a dialog with which you can find and select a printer (when Printer is selected in the Output Type drop-down list) or a path to a Microsoft Excel template to be used to generate this report (when Screen Display is selected in the Output Type drop-down list). Instructions on utilizing Microsoft Excel templates to generate reports can be found in Use an Excel Macro Template.

Report properties Options tab

When running VTScada as a Windows service, DO NOT select Excel as an output destination or option from a Report Tag. As noted in the MSDN forums, office applications assume they are being run under an interactive desktop. If Excel attempts to open a modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialog from a non-interactive service, the result is an invisible dialog that cannot be dismissed, stopping the thread.

Besides the technical problems, you must also consider licensing issues. Microsoft's licensing guidelines prevent Office applications from being used on a server to service client requests, unless those clients themselves have licensed copies of Office. Using server-side Automation to provide Office functionality to unlicensed workstations is not covered by Microsoft's End User License Agreement (EULA).

This tab includes two options that are not available in the Reports page. You may choose to record an event when the report triggers, and if doing so, log that event using "Report" as the area name. This is recommended as it will give you a way to verify that automatically-generated reports did in fact run.

Use excel to display screen reports, use a separate sheets/tables, Rename sheets/tables, generate an event when a report triggers or log the event using the report area.

Final display and record-keeping options

Use Excel to display screen reports

The Use Excel to display screen reports check box can be selected if you wish Microsoft Excel to launch your report when the Screen Display report output type is selected.

If you do not select the Use Excel to display screen reports check box, then a simple window will be launched and the report data will be displayed within it.

A report that has had its Output Type configured as ‘Screen Display’, and for which the ‘Use Excel to Display Screen Reports’ check box has been selected will open as a regular screen display over VIC connections. The ‘Screen Display Using Microsoft Excel’ feature is not available for VIC connections at the present time.

Use separate sheets / tables

Multiple iterations are not available to a report tag, therefore this option has no effect.

Rename sheets / tables

Multiple iterations are not available to a report tag, therefore this option has no effect.

Generate an event

When selected, an event will be added to the application's history. Events can be viewed in the Alarm Page by selecting the History display option.

Log the event using the Report Area

The Generate an event option must also be selected. Causes the event to be associated with the system area, "Report". Otherwise, the event will be associated with the report tag's area.

Closed Report Tag Widgets

The following widgets are available to display information about your application’s Report tags:

Report Button Widget

Report Options Widget

Report Destination Widget

Report Tag List Widget

Reporting Period (Enhanced) Widget

Report Type Widget

Duration Selector

Date Time Selector


SQL Logger Group Tags

Not counted towards your tag license limit.

SQL Logging will record, in an ODBC-compatible database, the values from any tag that could normally be logged.

The SQL Logger Group tag type works in combination with the SQL Logger tag. You use the SQL Logger Group tag to define a database and the frequency of data logging for all the SQL Logger tags associated with it. The SQL Logger tag is used to select which values are to be logged to that database. You may link one or more SQL Logger tags to one SQL Logger Group, recording one or more values into a single database.

Before You Begin:

Before you can log values to a database, you will need to have 1) a database containing two tables created using the template in the VTScada examples folder, and 2) an ODBC DSN configured for your database.

  1. Setting up a database:

You can use any ODBC compatible database such as MS-Access, MS-SQL, MySQL, Oracle, etc. Instructions for how to install and configure a database program are beyond the scope of this documentation.

After you have created a database, you will need two tables within it to hold the data that VTScada will export. In the Example folder under VTScada (normally found as C:\VTScada\Examples) there are four files to help you with this task.

  • SQLLoggerAccess.mdb
  • SQLLoggerMySQL.SQL
  • SQLLoggerOracle.SQL
  • SQLLoggerSQLServer.SQL

The three files which end with the extension ".SQL", contain SQL commands to create the tables you will need in your database.

If you do not have a database and do not own a database program, you can still use this feature of VTScada by following these steps:

  1. From the examples folder of VTScada, copy the file named SQLLoggerAccess.mdb to your application folder.
  2. Rename it to match the data you plan to collect, being sure to keep the .MDB extension on the name

You are now ready to proceed.

  2. Configure an ODBC data source name (DSN)

This is created using the Windows™ Open Data Base Connectivity (ODBC) tool. A 64-bit version of this utility can be found in the Administrative Tools section the Windows™ configuration menu. A 32-bit version is available as "C:\Windows\Syswow64\odbcad32.exe". Instructions for using the Microsoft utility are beyond the scope of this topic.

This must be done on all potential servers for a networked VTScada application. The DSN must be identical on each machine.

Related information:

Best Practices for Tags

Closed SQL Logger Group properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

SQL Logger Group properties Settings tab

The Settings tab holds the properties required to connect this tag to a database.

Database DSN

As described in the introduction to this topic, you must create and configure a database before using the SQL Logger Group tag.

The DSN (Data Source Name) must already exist on your system and be pointing to the database you created for this tag.

Database Type

Tell VTScada what type of database you are writing to.

CAUTION: The Database Type selection MUST match your database. Choosing an incompatible type will result in the tag failing to write values to your database due to differences in data format.

Auto Delete Records Older Than (Days)

Limit the size of the database by automatically deleting records older than (n) days.

You may choose to set this value to 0 to turn off the auto-delete feature.

Username, Password

The Username and Password fields should match whatever is required to connect to your database. If you are using MS Access and did not configure a user name and password, then you may leave these fields blank.

Due to the method by which the password is encrypted, it is not possible configure it using a parameter expression.

Tag ID Table Name, Tag Data Table Name

The two table name fields should not be changed under ordinary circumstances. The database configuration utility supplied with VTScada created these table names for you by default. (see SQL Logger Group Tag: Before you begin)

SQL Logger Group properties Log Settings tab

Contains options to configure the timing for when data will be written to the database.

There are three choices of Log Type: Interval, Triggered and On Data Change. Note that all the tags attached to a particular SQL Logger Group through the associated SQL Logger tags will use these settings.

Log Type

  • "Interval" - Record values every (n) seconds. Use this when you want continuous monitoring of the system, setting the interval to the number of seconds you want between each data output.
  • "Triggered" - Write values only when some condition changes. The write could be triggered by a tag changing value, or you can create an expression to define precise conditions that will cause a value to be written. Note that the trigger does not need to be activated by the same tag whose value you are recording. You could potentially record the level of a holding tank every time a pump switches on or off.

When logging is to be triggered, you must also choose what the trigger will be. For testing purposes you can choose Constant, setting the value to 1 or 0. You can also write an expression that will evaluate to TRUE or FALSE (1 or 0), or you can select a tag that will have a value of 1 or 0.

Trigger On

If you have chosen Triggered as the Log Type, you also have the choice of whether the trigger happens on a Value Change, a Rising Edge (from FALSE to TRUE) or a Falling Edge (from TRUE to FALSE. This applies to Constants, Expressions and Tags.

Log Type: On Data Change

This option for log triggering passes more control over to the Logger tags attached to this Logger Group. Essentially, you are indicating that log values are to be written when the value of the tag you are monitoring changes. See the section on the SQL Logger tags for more information.

If using this log type, please read the following section: Log Invalids for an important note.

Log Invalids

You have the option of whether to record "invalids" as part of the data being written. An invalid data value is essentially a NULL.

Note that if you select On Data Change as your trigger and you have not chosen to log invalids, then if the data changes from a valid value to invalid (or vice versa), no value will be written. You must enable Log Invalids to capture these data changes.

Enable

Where triggering controls the timing of data output, Enable sets whether data is to be output at all. Where the two controls offer the same options of "Constant", "Expression" and "Tag", the difference may seem subtle, but it is fundamentally different. Enabling the logger group means that logging is switched on or off. Triggering means that (if logging is enabled) data values are written when the trigger signals them to be.

If a SQL Logger Group is disabled, then all the SQL Logger tags attached to that group are automatically disabled.

Use Coordinated Universal Time (UTC)

A switch giving you the option to record the time stamp using either local time or UTC.

SQL Logger Group properties SQL Logger tab

Each Logger Group Tag must have one or more SQL Logger tags contributing data to it before it will be useful. As noted, the SQL Logger Group Tag creates a link to a database and sets a frequency of logging - it does not actually select what data is being logged. That job is assigned to the SQL Logger tag as described in the following section.

Closed SQL Logger Group Tag Widgets

Only one widget is available to SQL Logger Group tags:

Show Stats Widget (ODBC)


SQL Logger Tags

Not counted towards your tag license limit.

The SQL Logger tag type is used to select where the data to be logged is to come from. Before using an SQL Logger tag you should create a SQL Logger Group tag as described in the preceding section. SQL Logger tags contribute values to SQL Logger Group tags.

Each record added to the database will include:

  • An index value indicating which tag's value is being recorded
  • A time stamp
  • The value of the tag being logged at that moment
  • A flag to show whether the value is 'manual data'
  • A flag to show whether the value is 'questionable data'
  • An alarm flag
  • (Characteristics available in the Table of Type Characteristics.)

Related information:

Best Practices for Tags

Closed SQL Logger properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

SQL Logger properties Log Settings tab

The Log Settings tab is where you select and control which tag's values you wish to log.

Tag to log, Variable to log

In the "Tag to log" selection area, simply choose any existing tag from your project. If that tag has multiple values which could be logged, you will have a choice in the "Variable to log" selection. In most cases, the variable will simply be "value".

Enable

Enable or disable logging of the selected value by entering a 1 for Enable and a 0 for disable. You can also toggle whether logging is enabled based on a script expression, or by selecting a tag: either the same tag you are logging the data values for, or any other. This provides you with the option of either logging continuously or logging only when a condition is met such as when an Alarm tag is activated.

SQL Logger Group

An SQL Logger Group must be selected. SQL Logger tags contribute their values to SQL Logger Group tags which then manage the actual output of the data to a database.

Deadband (Engineering Units)

If (and only if) the associated SQL Logger Group was set to trigger on data changes, it has essentially passed control to this tag to cause data writes to occur. If this is the case, then the Deadband field will be enabled and you will have the option of indicating how much the value must change by before another value will be written to the database.

Closed SQL Logger properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed SQL Logger Tag Widgets

The following widgets are available to display information about your application’s SQL Logger tags:

Animated Image Widget | Bottom Bar Widget
Color Blink Widget | Color Box Widget
Color Fill Widget | Color Line Widget
LCD 5x7 Matrix Widget | Draw Text Widget
Equipment / Status Color Indicator | Image Change Widget
Indicator Light Widget | LCD Bar Widget
LCD 7 Segment Widget | Left Bar Widget
Meter 1 Widget | Meter 2 Widget
Meter 3 Widget | Multi-Color Widget
Multi-Text Widget | Numeric Value Widget
Plot Data Widget | Right Bar Widget
Text Change Widget | Top Bar Widget
Two Color Bar Widget |


SQL View Tag

Not counted towards your tag license limit.

This is a tag intended for customers who are using VTScada's Remote Data Access and ODBC features to query the application's stored history. Use it to create views of data within your application, for use by SQL querying tools.

Without this tag, 3rd party query tools must connect to the virtual History table (or one of the time-aggregation modes of that table), which makes all information from all tags available. Typically, this is far more information than most 3rd party programs can work with. As an example of how many columns there can be in the virtual History table, consider just the data available from driver tags: each driver records seven values tracking the driver's health (quality, error, etc.). If you are querying a History_TPP table (data aggregation) then there are seven columns for every aggregation time period, for every driver.

Note also that VTScada will limit the number of columns returned in any query to 64.

VTScada stores history using only it's own proprietary format, which is not a relational database.
The SQL interface allows a limited subset of the SQL language to be used as if querying SQL tables.

Example:

In the following image, the table, LEVEL AND FLOW, as seen in a 3rd party ODBC query tool, is the result of an SQL View tag. It contains only data from tags selected for the view.

Related information:

Best Practices for Tags

Closed SQL View properties, ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

SQL View properties, View tab

Every view must have a name, which is configured on the View tab.

By default, views include only the historical values of tags selected in the Tag Filters tab. Use the Value Attributes and TPP Modes to extend the view to include selected flags that may be relevant to the data returned, or value aggregations such as averages or maximums over a defined time period.

If you are interested only in tag values and not in data aggregation over defined time periods, there is no need to select a TPP mode.

Optional attributes and calculations of an SQL View

View Name

Create a name for the view. This will be needed by your third-party viewing tool.

View names must be shorter than 55 characters. Spaces are allowed except at the beginning or end of the name. Punctuation characters are allowed except for underscore (_), colon (:), apostrophe (‘), and double quote (“).

If the View Name is cleared, after applying changes, the existing table registered by the same tag with the old view name will be unregistered (deleted).

Do not use an existing tag’s name as the view name. You will not be able to retrieve data from the matching tag.

Privilege

Select a custom security privilege from this drop down to limit the access to this view to only those operators who have been granted the matching security privilege.

Value Attributes

Value attribute related fields support only the BitwiseAND and BitwiseOR TPP mode. If value attributes are selected but neither BitwiseAND or BitwiseOR is selected, the result from a TPP query will not contain attribute columns.

Value!

A 6-bit binary with each bit representing one of the attributes (ManualData, ManualEntry,...) in the following list, in the order as shown.

It is not necessary to enable the Value! check box if you want only certain attributes. Enabling Value! will add the TagName:Value! columns to the view, where Value! is a 6-bit binary, with each bit representing an attribute. If you want only the EditedData attribute (TagName:Value!:EditedData), then select only the "EditedData" option.

ManualData

If Manual Data is set in a tag, it will be flagged to indicate that it is manual data rather than process I/O data. Select this option to include that flag in the view.

(TagName:Value!:ManualData)

ManualEntry, EditedData

Authorized users are able to add and Edit Data using the Historical Data Viewer. (Original values are always kept, and edited values are flagged as such.)

The difference between the two is that, if the timestamp associated with the new value has already been logged in the history, EditedData will be set (as the user is editing an existing value). If the new value is being added to a fresh timestamp, ManualEntry will be set.

(TagName:Value!:ManualEntry)

(TagName:Value!:EditedData)

Questionable

Values recorded while the Questionable Data flag will be marked as such. Select this option to include that flag in the view.

(TagName:Value!:Questionable)

Imported

Authorized users are able to Import Tag History. Select this option to include the flag that marks imported data as such.

(TagName:Value!:Imported)

Quality

Indicates a bad quality issue. "Good Quality" is defined as a value of "0 or Invalid" and "Bad Quality" is defined as any valid, non-zero value. Refer to the I/O and Calculations tag, topic: Quality Based on.

(TagName:Value!:Quality)

StaleData

The data has been logged again using a previous value. This happens most often if the driver has experienced a communication failure and the driver's Hold option is selected.

(TagName:Value!:StaleData)

CommFail

Indicates a failure to communicate with the device

(TagName:Value!:CommFail)

DriverCommFail

The PLC has reported a downstream communication failure.

(TagName:Value!:DriverCommFail)

DriverQuality

The PLC has reported a bad driver quality issue. Refer to the quality calculation described in Communication Driver Log-Enabled Variables

(TagName:Value!:DriverQuality)

DriverOverridden

The PLC has reported that a value has been manually overridden.

(TagName:Value!:DriverOverridden)

DriverNoData

The PLC has reported no data for an unspecified reason.

(TagName:Value!:DriverNoData)

TPP Modes

"TPP" stands for "Time Per Point". This is a time range over which data is aggregated. The length of time will be specified in the query by appending a suffix such as "_15M" to the history table. Your selection here is for the types of aggregation you want to make available to your query.

All the following are direct matches to the Modes specified in GetTagHistory.

Average

Average value over the time period.

Minimum

Minimum value over the time period.

Maximum

Maximum value over the time period.

Delta

Change in value over the TPP range.

ValueAtStart

The snapshot value at the beginning of the time period.

TimeOfMin

The time of the minimum value recorded during the period.

TimeOfMax

The time of the maximum value recorded during the period.

ZtoNZCount

The number of zero to non-zero transitions (starts) during the period.

NonZeroTime

Effectively, the running time during the period.

Total

The total of all values recorded during the period.

Interpolated

The snapshot value at the beginning of the time period. (Mode 10 is deprecated.)

RolloverTotal

The formula used is (RolloverCount * RolloverValue) + (LastValidValue - FirstValidValue).

Where, for any given time interval:

  • Rollovers are counted when a new value is smaller than the last valid value.
    (Use only for a tag that counts to a maximum and resets to zero. A tag with a fluctuating value will trigger many rollover counts.)
  • The RolloverValue is passed to the function in the parameter StaleTime.
  • LastValidValue starts with the last valid value in the previous time interval (if any), and is updated with each new valid value within the time interval.
  • FirstValidValue starts with the last valid value in the previous time interval (if any), and is updated with only the first valid value found in the current time span.

BitwiseOR

Performs a bit-wise OR of all the values stored during the time period. The result tells you which bits were set for every recorded value within that period.

BitwiseAND

Performs a bit-wise AND of all the values stored during the time period. The result tells you which bits were set for any recorded value within that period. (And conversely, which bits were not set during the time period.)

ValueAtEnd

The snapshot value at the end of the time period.

SQL View properties, Tag Filters tab

Use the Tag Selector tool within this tab to choose the tags that will be included in the view.

The Tag Selector is similar to the tool that you would use in the Historical Data Viewer to choose tags to plot. (Click the thumbnail image to expand.)

Sample tags are from a demo application.

The Tag selector can be widened as needed in order to view your tag names.

The upper list of the Tag Selector shows the tags in your application. Use filtering tools to limit which tags are shown in this list.

The lower list shows the tags that will be available in your SQL View. Move tags from the upper list to the lower, either by using the Select Tag button or by double-clicking the tag in the upper list. You may remove tags by the same method, except using the Remove button instead of Select Tag.

A powerful way to select a set of tags is to use a query. A query is simply the filter that you create using the tools at the top of this dialog. For example, setting the name filter to Station 1\* results in a query that includes only the tags within that station. Adding filters for area, type, etc. further restricts the set that will be included.

After defining the filters, use the Add Query button to save the filter set. You can save more than one query. Within a query, each filter further restricts the tag selection. When there are multiple queries, all tags that match any filter are included.

SQL View Tag Error Dialogs

Displayed when an existing name is reused. Select a new name then save again.

Displayed when an invalid character is used in the view name.

Examples: Querying for Attribute Data

The value attribute Value! and its bits column in an SQL View table of raw tag data will look like:

TagName:Value!, TagName:Value!:ManualData, TagName:Value!:EditedData.

In an SQL View table of TPP data, this might look like:

TagName:Value!:BitwiseAND, TagName:Value!:ManualData:BitwiseAND, or TagName:Value!:ManualData:BitwiseOR

The following example shows a selection that includes attribute data. Note that the attribute columns must be wrapped in double quotation marks:

SELECT Timestamp, TagName:Value, "TagName:Value!:EditedData" FROM MyView

Value attributes support only the BitwiseOR and BitwiseAND TPP mode. For example:

SELECT Timestamp, "TagName:Value!:EditedData:BitwiseOR" FROM MyView_1D

will return data as long as "EditedData" and "BitwiseOR" are enabled in the SQLView tag. The query

SELECT Timestamp, "TagName:Value!:EditedData:Average" FROM MyView_1D

will return a "TagName:Value!:EditedData:Average - Column does not exist in table: MyView" error, even if the "Average" TPP mode is enabled.


Transaction Logger Tags

Not counted towards your tag license limit.

Transaction Logger tags can be used to record a collection of historical values as a single transaction. These are useful for material-handling applications that must record transfers of custody.

When the trigger changes to a non-zero value, all of the records in the history associated with the I/O and Calculations, Analog Status, Digital Status, and String I/O tags that are immediate children of this tag, will be read and coalesced into a structure, which will be written as a single transaction record in the Historian associated with this tag. No other tag types will be included, nor will any tag that is below the level of the immediate children of the Transaction Logger. The Transaction Logger tag will not respond to a trigger event unless the child tags use the History Address field, not the address field. Transaction Logger tags do not work with report-by-exception drivers, such as MQTT, OCPP and DNP3.

The field names in this transaction snapshot will match the names of the tags being recorded, and are generated in the order of I/O and Calculations, Analog Status, Digital Status and String I/O, with the fields being alphabetically ordered within types. All field names are stored with every transaction because the child tags of the Transaction Logger may change over time.

The driver parameter of all the child tags of a Transaction Logger must be set to that Transaction Logger. Child tags that do not use this tag for their driver parameter will not be included in the transaction.

Transaction Logger tags cannot share a common Driver tag with any other tags. You must create a dedicated Driver tag for each Transaction Logger tag.

You are advised to use the History address of the input tags where possible, so that there will be a positive confirmation of the data being read via WriteHistory. This will avoid false positives on communication errors due to other users of the driver having comm errors concurrently with the transaction's polling.

Avoid using Polling Drivers that are attached to the same driver and that have polling intervals that result in continuous polling. Doing so could result in transactions failing to complete.

Error Status

The value of the Transaction Logger tag shows its current error status, according to the following table:

Tag Value | Meaning
0 | No error.
1 | Communication Error.
2 | For multiple-record devices (such as the ROC), the time stamps for consecutive records across all fields do not align.
3 | Not all fields have the same number of records returned.
4 | Driver became unavailable.

When there is an error, the I/O data corresponding to the poll attempt is written into the record, but these error records are not accessible via ODBC. In the case of the Communication Error, only one record will be written until the value becomes something other than 1. It is recommended practice to attach an alarm to each of your Transaction Logger tags.

Data Retrieval

There is a single, virtual ODBC table called TransactionLog, which presents the data for all transactions by all Transaction Logger tags. This table will be the merged columns that match the tags in the query. The table’s columns are defined by the child field tags that are present at the instant the query is made. There is a column, called TransactionLogger, that gives the associated Transaction Logger tag. Each record will have a 36-character GUID, stored in the column TransactionID.

The only method for retrieving logged transaction data is to use an SQL query. This may be done through code, calling the SQLQuery function, or through the ODBC Server. An example of an generic data retrieval query follows:

SELECT * FROM TransactionLog LIMIT 100;

Related information:

Best Practices for Tags

Closed Transaction Logger properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Transaction Logger properties I/O tab

The I/O tab for the Transaction Logger tag consists of...

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Trigger Condition

May be any tag or expression that will change from a zero to a one, signaling when to write the transaction record.

Acknowledge Output Destination

Must be a tag. In most cases, the PLC will need to know that the transaction has been read so that the PLC can update the registers for the next transaction that may be in the queue. The output provides that acknowledgment to the PLC.

Value to Write to Acknowledge

Provide the value that is to be written to the acknowledge output destination. This may depend upon the error status of the transaction tag, in which case an expression should be used to generate the appropriate value.

Force fields with different timestamps into separate transactions

When selected, data returned for each field does not have to have the same number of records. Time stamps that do not match will be placed in separate transaction records.

This option assumes that the time stamps are in order in tag history. The transactions will be written with the time stamps corresponding to the data times in chronological order. Should be selected for the TBox chronological data.

Closed Transaction Logger properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Closed Transaction Logger Tag Widgets

The following widgets are available to Transaction Logger tags:

Text Change Widget

Image Change Widget

Color Box Widget

Color Blink Widget

Animated Image Widget

Two Color Bar Widget

Plot Data Widget

Color Line Widget

Indicator Light Widget

Equipment / Status Color Indicator

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Sparklines Widget


Analytics Tags

For analyzing trends in real-time or from a pool of historical data, use a combination of VTScada tags, widgets and tools like the Historical Data Viewer (HDV).

Some tags collect real-time data. You can store raw data, apply calculations, use values in expressions or create graphic representations using tools like the HDV viewer or other widgets. For the real-time monitoring of live data, the most useful and universal tag is the I/O and Calculations tag.

Other tags in this group provide inquiry functions that you may wish to use such as Counters, Totalizers, Alarm Status counts, etc.

Statistics tags are out-of-the-box calculators. Pick the calculation you want, specify a length of time to use as a sample size and a rate at which to repeat the calculation. The resulting value will be time stamped at the start of the span to accurately represent historical trends over time.

Related information:

I/O and Calculation Tags - I/O and Calculation tags can read, write and store values. Monitor real-time values and optionally apply calculations for analytical analysis.

Counter Tags - Count the zero to non-zero transitions of a digital tag.

Totalizer Tags - Create a running total of another tag's value over time.

Rate of Change Tags - Monitor the rate at which another tag's value changes.

History Statistics Tag - Provides a statistic relative to a given time span. For any tag with a numeric value.

Digital Statistics Tags - A set tags for calculating non-zero time and zero to non-zero transitions of digital tags.

Analog Statistics Tags - A set of pre-configured History Statistics tags for any tag having a numeric value.

Calculation Tags - A legacy tag with a limited capacity to apply calculations to specified values.

Script Tags - Activate a script module, based on a set-point that monitors another tag's value.

Function Tags - An older technology for creating calculations, based on other tag values.


Counter Tags

Not counted towards your tag license limit.

Counter tags provide a means to count events such as pump starts or equipment cycles. A count is recorded each time the source changes from 0 to non-zero.

An invalid value for the source is not assumed to mean a 0 or off state. A transition from invalid to 1 will not be counted.

The Counter tag retains its value between application restarts and uses the last known valid source value when counting. For example, if the data source was 1 (i.e. running) when VTScada stopped and is 1 when VTScada restarts, it is assumed that the equipment continued to run while VTScada was offline and the counter is not incremented. Similarly, if the source was 0 (i.e. off) when VTScada stopped and is 1 when VTScada restarts, it is assumed that the equipment started at least once while VTScada was offline and the counter is incremented by 1.

Do not attempt to attach a Logger tag to a Counter tag. Counter tags have built-in logging.
Also: Note that clicking on a Counter tag drawn on a page, will not open the Historical Data Viewer window.

Related information:

Best Practices for Tags

Closed Counter properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Counter properties Settings tab

All options to configure the counting behavior of the Counter tag can be found in the settings tab.

Counter tag properties

Source

The source can be any tag or calculation whose value will change between 0 and a non-zero value. The count will be increased each time the source changes from 0 to a non-zero.
Constants are not useful here, but are a standard part of this type of selector.

Log Interval

The Counter tag will log its value at the end of each interval specified. This interval goes by the clock, not by running time. If, for example, the log interval is set to "Day" the tag's value will be logged at midnight, not at the end of 24 hours of operation. If the log interval is set to "Hour" the tag's value will be logged each hour on the hour. "Weekly" means midnight Sunday night and "Monthly" means at midnight before the first day of the month.

Reset After Log

You can select whether the counter should be reset to 0 after its value is logged.

Engineering Units

Text that states what the Counter tag is counting (e.g. Starts).

External Reset

Specify a tag or calculation to force a reset of the counter. Note that the current value of the tag will always be logged before a reset. The reset will occur when this source changes from a 0 or false value to a non-zero or true value. A change from invalid to true does not cause a reset.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Counter properties Merit tab

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Closed Counter tag properties: Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Counter properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Closed Counter Tag Widgets

The following widgets are available to display information about your application’s Counter tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Color Blink Widget
Color Box Widget | Color Fill Widget
Color Line Widget | LCD 5x7 Matrix Widget
Draw Text Widget | Equipment / Status Color Indicator
Image Change Widget | Last Logged Value Widget
LCD 7 Segment Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Numeric Value Widget | Multi-Color Widget
Multi-Text Widget | Numeric Entry Widget
Plot Data Widget | Reset Button Widget
Reset Target Widget | Set Analog Value Widget
Text Change Widget | Two Color Bar Widget
Spider Graph Widget | History Stats Value Widget


Totalizer Tags

Not counted towards your tag license limit.

The Totalizer tag provides a means of accumulating the sum of another tag's (or calculation's) value over time. To put it more precisely, the totalizer integrates a value over a time period.

The totalizer looks for its source to represent values "per second", "per minute" or "per hour". It is important to select a source time scale that matches the source values. For example, when recording total flow from a meter that is measuring flow rate per second, selecting the "per minute" source time scale is guaranteed to produce results that are incorrect.

You can also use the totalizer to record running time. For this, the source value must be a 1 when the equipment is running and a 0 when stopped. Given a source time scale of "per second" this will add 1 second, per second while the equipment is running and 0 seconds per second while stopped.

An invalid is not taken to mean that the value (or running state) of the tag is 0. If the source's value goes to invalid, it will be assumed that the last known value remains in effect and that value will continue to be used for the integration.

Values are added to the Totalizer tag at the end of each elapsed source time scale. This will not necessarily be "on the second" or "on the minute".

Do not attach a Logger tag to the Totalizer. At the end of each log interval, values are logged using the built-in connection to an Historian. You have the option of performing a reset of the Totalizer tag's value after each write to the historian.

You can cause a reset to be done at times other than the set logging interval, either by providing a reset button for the operator to use, or by configuring a tag to use an external reset. The current value is always logged before a reset is done.

If the totalizer is drawn with a Set Analog Value tag or a Numeric Entry tag, two things will happen when the operator uses either widget: the totalizer will log its current value and it will reset to whatever value is set by the widget instead of 0.

It should be noted that a plot of the Totalizer tag on the Historical Data Viewer will show a constant value from one log interval to the next, with an instant change between values at each log interval.

The current value of the Totalizer tag is saved between VTScada restarts.

Do no attempt to attach a Logger tag to a Totalizer tag. Totalizer tags have built-in logging.

Difference from the History Statistics tag, totalizer option:

The Totalizer tag calculates a time-weighted integral of the values collected. The totalizer option of the History Statistics tag provides a sum of the values within the time interval. Both have their uses.

Related information:

Best Practices for Tags

Closed Totalizer properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Totalizer properties Settings tab

Select the source tag, time scale, zero cut-off limit, log interval, engineering units for display, an external reset source, update interval in seconds and option to enable a reset after logging

Source

The source can be any tag, calculation or even a constant. Whatever value is provided here will be the value that is totaled. In most cases, this will be an analog status or Analog Input tag, but there are no restrictions on the source. You might use a digital input to collect a total of equipment running time. If, for example, you specify a constant value of 1, the totalizer will record the total time that the application is running.

Source Time Scale

While there is no limitation on what can be used for the source, a Totalizer tag will commonly be used with equipment such as a flow meter. Flow meters may provide their values in units of flow per second, flow per minute or flow per hour. Selecting the correct time scale is of critical importance to collecting an accurate total.

Log Interval

The Totalizer tag will record its current total to the historian at the end of each interval specified. This interval goes by the clock, not by running time. If, for example, the log interval is set to "Day" the tag's value will be logged at midnight, not at the end of 24 hours of operation. If the log interval is set to "Hour" the tag's value will be logged each hour on the hour. Weekly means midnight on Sunday night and Monthly means midnight starting the first day of the month.

Reset After Log

You can select whether the totalizer should be reset to 0 after its value is logged.

Zero Cut-off Limit

To allow for a source that does not output an exact 0 when there should be no value to record, you can set a zero cut-off limit. This value is taken as a range, above and below zero, within which the totalizer takes 0 to be the source's value.

Note that this is a range above and below zero, not a low value cut-off. Negative input values are possible from the source tag and are totaled as such.

Engineering Units

Text stating what the Totalizer tag is totaling (e.g. Gallons, Liters…).

External Reset

Specify a tag or calculation to force a reset of the totalizer. Note that the current value of the tag will always be logged before a reset. The reset will occur when this input changes from a 0 or false value to a non-zero value. A change from invalid to non-zero does not cause a reset.

Update Interval (Seconds)

Controls the frequency of calculations. The value cannot be set lower than 1 second.

To reduce the load on your system, set the largest update interval that still provides the information you need.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Totalizer properties Merit tab

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Totalizer properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Closed Totalizer tag properties: Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Closed Totalizer Tag Widgets

The following widgets are available to display information about your application’s Totalizer tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Color Blink Widget
Color Box Widget | Color Fill Widget
Color Line Widget | LCD 5x7 Matrix Widget
Draw Text Widget | Elapsed Time Widget
Equipment / Status Color Indicator | Image Change Widget
Indicator Light Widget | Last Logged Value Widget
LCD 7 Segment Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Multi-Color Widget | Multi-Text Widget
Numeric Entry Widget | Numeric Value Widget
Plot Data Widget | Reset Button Widget
Reset Target Widget | Set Analog Value Widget
Two Color Bar Widget | Text Change Widget
History Stats Value Widget |


Deadband Control Tags

Not counted towards your tag license limit.

Deadband control tags monitor the value of any tag with a numeric value and compare the monitored tag's value to a low set point and a high set point. If the value of the monitored tag falls below the low set point, the value of the Deadband Control tag is set to 1. If the value of the monitored tag rises above the high set point, the value of the Deadband Control tag is set to 0.

A check box enables this action to be reversed.

(Characteristics available in the Table of Type Characteristics.)

Related information:

Best Practices for Tags

Confirmation Prompts for Output Tags - Control options for confirmation prompt text.

Closed Deadband Control properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Deadband Control properties Options tab

The Options tab of a Deadband Control tag's properties folder enables you to select the tag whose value will be monitored, and to configure details such as whether the control is enabled and whether it will send a start signal when the monitored value goes above or goes below the set point.

Monitored Value

This should be either a tag, or an expression based on one or more tag values. While Constant is available as an option due to the nature of this field selector, it will not be useful as a monitored value.

The deadband control compares the Monitored Value with its low and high set points to determine its own value. If the Monitored Value is less than the value of the Low Setpoint, then the value of this Deadband Control tag will be 1. If the Monitored Value is greater than the value of the High Setpoint, the value of this Deadband Control tag will be 0.

The behavior of this Deadband Control tag can be reversed such that if the Monitored Value is greater than the value of the High Setpoint, the value of this Deadband Control tag will be 1 using the Operation radio buttons (see following notes).

Inhibit

The effect of setting the inhibit flag is to force the tag’s value to be 0, regardless of other settings.

A valid value for the Inhibit field can be provided via any of a constant, an expression, or a tag. Please see Constant, Expression or Tag for help selecting which to use.

Operation

The Operation section contains two radio buttons that enable you to set the behavior of this tag.

Start On High: If the Start On High radio button is selected, the value of this tag will be reversed from its default. When the Monitored Value is greater than the High Setpoint (see Deadband Control properties Setpoints tab), the value of this Deadband Control tag will be 1 (rather than 0, which is the default).

Start On Low: If the Start On Low radio button is selected, if the Monitored Value is less than the Low Setpoint (see Deadband Control properties Setpoints tab), the value of this Deadband Control tag will be 1.

Manual Data

The Manual Data property enables you to set a user-defined value for this tag. If the value of the Manual Data field is left Invalid, or is not a valid number, then the value for this tag is read.

If the value entered into the Manual Data field is a 0, the actual value of this tag is also overridden, as 0 is considered a valid value. Therefore, you must clear the Manual Data field entirely if you wish the actual value of this tag to be read, rather than a manually-entered value.

Questionable Data

Use this field to flag the tag’s data in the event that you suspect the values it is reporting might not be correct, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Deadband Control properties Setpoints tab

In this tab, you can configure the low and high set points that will be compared to the monitored value.

High Setpoint and Low Setpoint

The Deadband Control tag will compare the values in the Setpoint fields with the Monitored Value to determine its own value.

If the Monitored Value exceeds the value of the High Setpoint, the value of this Deadband Control tag will be 0. The result of this comparison is referred to as the stop condition.

If the Monitored Value is less than the value of the Low Setpoint, the value of this Deadband Control tag will be 1. The result of this comparison is referred to as the start condition.

The behavior of this Deadband Control tag can be reversed such that if the Monitored Value is greater than the value of the High Setpoint, the value of this Deadband Control tag will be 1.

A valid value for the High Setpoint field and the Low Setpoint field can be provided via any of a constant, an expression, or a tag. Please see Constant, Expression or Tag for help selecting which to use.

Start Delay and Stop Delay

You can enter a value (measured in seconds) in the Start Delay field to set a length of time that to wait after the start condition before setting the value of this Deadband Control tag to 1.

The Stop Delay field works in the same way: Enter the number of seconds that the tag should wait after the stop condition before setting the value of this Deadband Control tag to 0.

Deadband Control properties Owner tab

This tag can be used in an owner/contributor structure where multiple contributor tags can supply their values to an owner tag.

There is no specific "owner" tag type, rather an owner tag is typically a custom-designed tag that is created using VTScada scripting code.

Owner

Specify a tag to which this contributor should supply its data. An owner tag is one which you must design and then create, using the VTScada scripting language.

The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual data value, to questionable data, according to the configuration of the check boxes appearing beneath the Owner field. These check boxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value check box is used to set the value of this contributor tag as the nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack. Priority check box causes the owner tag to keep track of the priority of the contributor's active alarm (or records an Invalid if the contributor is not in an alarm state). Selecting the Set Active/Unack. Priority check box also causes the owner tag to record whether the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values), rather than reading data from their I/O device. When selected, the Record Use of Manual Data check box is used to increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality (Analog and Digital Input only)

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag Quality check box is used to increment the owner tag's count of the number of tags that are contributing quality data by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the Record Tag Validity check box is used to increment the owner tag's count of the number of tags that are contributing questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Closed Deadband properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Deadband Control properties Alarm tab

If you want this tag to trigger an alarm, use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Deadband Control properties Logger tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag will work with the attached Historian to record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be created as a child of the current tag.

Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Closed Deadband Control Tag Widgets

Deadband control tags monitor the value of any tag with a numeric value and compare the monitored tag's value to a low set point and a high set point. If the value of the monitored tag falls below the low set point, the value of the Deadband Control tag is set to 1. If the value of the monitored tag rises above the high set point, the value of the Deadband Control tag is set to 0. The widgets for Deadband Control tags enable the operator to set the value if it falls between the low and high set points.

The following widgets are available to Deadband Control tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Blink Widget | Color Box Widget
Color Fill Widget | LCD 5x7 Matrix Widget
Draw Text Widget |
Equipment / Status Color Indicator | Image Change Widget
Indicator Light Widget | LCD 7 Segment Widget
Left Bar Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Multi-Color Widget | Multi-Text Widget
Network Link Widget | Plot Data Widget
Right Bar Widget | Text Change Widget
Top Bar Widget | Two Color Bar Widget
Spider Graph Widget |


Network Status Tags

Not counted towards your tag license limit.

These are used to inquire about the connection status between two computers (usually a server and a workstation). A 1 is returned for a good connection, 0 for no connection and Invalid if no information can be determined.

Related information:

Best Practices for Tags

Closed Network Status properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Network Status properties Settings tab

The Settings tab for a Network Status tag is used to specify which workstations you want to monitor. You must provide the names of the machines to monitor. IP and Subnet are required only if separate connections between the computers are possible. In this case, you must tell VTScada which connection to monitor.

Machine 1 Name

Specify the name of one of the two workstations, the connection between which is to be monitored. You may enter the name of the workstation in this field, or select the name of the workstation from the drop-down list.

Machine 1 Network Adapter Name

The droplist exposes the available interfaces on the associated machine, with additional options for any interface (where you don't care) and an unknown interface (for the case where an interface is configured, but the local machine does not have access to the information to display a name).
This information may not be seen on a machine that has no direct RPC connection (or none yet established) to the target machine.

Machine 2 Name, and Network Adapter Name

These three fields match those of Machine 1. They enable you to specify the second workstation to be monitored by this tag.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Quality tab

Manual Data

The Manual Data property enables you to enter a value for this tag, rather than reading the value from the monitored workstations. In this instance, the Manual Data property may be set to 0, indicating that the workstation is not connected, or 1, indicating that the workstation is connected.

Questionable Data

Use this field to flag the tag’s data in the event that you suspect the values it is reporting might not be correct, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Network Status properties Alarm Setup tab

Use the Alarm Setup tab for a Network Status tag to configure alarm conditions for this tag.

Alarm Priority

The Alarm Priority drop-down list enables you to select the priority of the alarm for this tag, should it enter an alarm state. The available priorities are:

None (alarm not configured)
0 - Event
1 - Critical
2 - High
3 - Warning
4 - Notice

On Delay

The Delay field enables you to enter the amount of time (in seconds or fractions of a second) that the system will wait before triggering an alarm for this tag. This tag must therefore be in an alarm state for the amount of time specified in the Delay field before an alarm will be indicated.

Sound

The Sound field enables you to identify what sound will be played when this alarm is triggered. The Sound field can be set to a 0, 1, or to the name of a .WAV sound file to be played.

If the Sound field is set to 0, no sound will be played when this alarm is triggered.

If the Sound field is set to 1, an alarm sound whose properties are configured on the associated Alarm Priority tag will be played.

If the Sound field identifies the name of a .WAV sound file, it will override any alarm sound configured for the associated Alarm Priority tag. When specifying a sound file, you must enter its name and extension (e.g. MySound.wav). The specified sound file must be a .WAV file, and must be stored in the application directory. If the specified sound file is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Alarm Disable

The Alarm Disable check box enables you to disable and enable the alarm for this tag. Alarm disabling is typically used in situations where routine maintenance is being performed, or when you are aware that another interruption in communications will occur for a period of time. In such a situation, an alarm can be disabled until the maintenance is complete and communications are reestablished.
May be linked to a tag or expression for suppression by design.

Pop-up Enable

If the application property AlarmPopupsEnable is set to 1, then selecting Pop-up Enable will result in a pop-up dialog being displayed whenever the alarm is triggered. It is strongly suggested that this feature be used sparingly.

Closed Network Status properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Network Status properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Closed Network Status Tag Widgets

The following widgets are available to display information about your application’s Network Status tags:

Alarm Priority Box

Alarm Priority Icon

Station and Site Tags

Color Blink Widget

Color Box Widget

Equipment / Status Color Indicator

Image Change Widget

Indicator Light Widget

Network Link Widget

Plot Data Widget

Text Change Widget

Two Color Bar Widget


Rate of Change Tags

Not counted towards your tag license limit.

Rate of Change tags are used to display how quickly another tag’s value is changing. They can be used to watch for system problems such as leaks and blockages.

The Rate of Change tag calculates the first derivative of another tag’s value. In general terms, this is defined as the change in value divided by the change in time. For example, speed rather than position. This tag tells you how fast something is changing, not where it is. If the tag you monitor has a steadily changing value, it will have a non-zero, but constant (flat), rate of change.

The source tag's value must be logged in order for the Rate of Change tag to work properly.

The rate of change will be positive if the source is increasing in value, and negative if the source is decreasing. The tag can be configured to report the absolute rate instead, thus showing a positive number for any rate of change.

Note that in multi-server applications, the Rate of Change tag information is distributed from the server to workstations on a regular interval (default: 60 seconds) or when the value changes by a given percentage (default: 5%). These values are controlled by variables in your configuration file.

For VTScada developers who also write expressions, the following tip is especially relevant to the Rate of Change tag.

Related information:

See variables: RateOfChangeTagRPCThreshold , and RateOfChangeTagRPCInterval

Best Practices for Tags

Closed Rate of Change properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Closed Rate of Change properties Settings tab

The Settings tab is used to select which tag is to be watched and how often it is to be checked. Examples are provided at the end of this section.

Select the rate of change source tag, set the time scale, period and refresh interval.

Source

Use this option to select the tag to be monitored for changes in value.
If you would like to monitor the rate of change of some combination of tags or a calculated value, you should create a Calculation tag with the expression you need and use it as the source.

Sync Calculation

The default is for calculations to be done locally on each machine. If Sync Calculation is selected, the calculation is performed only on the ValueSyncService server machine with the source tag, if there is one, and the value broadcast to other machines.

If the Sync Calculations setting is disabled, each machine performs calculations independently; Values may temporarily differ between machines if, for example, their system clocks are not aligned. These differences are typically short-lived, lasting only for the duration of the configured period, and the values eventually converge. Please note that, in it's default configuration (Sync Calculation disabled), Rate of Change (ROC) values might vary slightly depending on the Source Value synchronization.

It is important to note that constantly syncing ROC values with other machines is a resource-heavy task. It is not suitable for fast-changing values or ROC tags with small refresh intervals. Only Sync Calculations if it is absolutely necessary.

Source Time Scale

Sets the measurement rate for the change. Available options include: per Second, per Minute and per Hour. Use when your tag is measuring a rate so that this matches the configuration of the flow meter (gallons per minute or liters per second).

If you are monitoring a level rather than a rate, with readings taken from the tag on change, then set this to "per Second" and do all your calculations in units / second.

Positive Rate

When selected, the absolute value of the rate of change will be shown. Otherwise, a decreasing value in the source tag will be displayed as a negative rate of change.

Refresh Interval and Period

  • The Refresh Interval sets how often the rate of change is calculated. This value is always measured in seconds.
  • The Period defines the length of time over which the change is to be measured. It is also measured in seconds.

The rate of change is roughly defined as the amount by which the value has changed during a given period, divided by the length of time in the period. To state it more accurately, the rate of change is the calculated derivative (dy/dx) of the plotted value.

The rate of change calculation is affected by data noise and transient spikes. The period should always be set to a value larger than the frequency of data noise. To avoid alarms due to transient noise, set a delay on the alarm. (see: Rate of Change properties Alarms tab.)

Examples

Adjust the settings according to the whether you are interested in the instantaneous rate or the rate over a longer time period. If the instantaneous rate of change is important then decrease the Period and the Refresh Interval: (at the extreme: "per Second", 1, and 1)

Example 1) You want to check every 10 minutes that over the last 6 hours the rate of change (ROC) has not dropped below -0.5ft/6hrs, (which is approximately -0.0833ft/hr or a very small -0.0000231/sec)

  • Set Source Time Scale to "per Hour" because you want to compare ROC to -0.0833ft/hr.
  • Set the Refresh Interval to 600 because you want to calculate the ROC every 10 minutes.
  • Set the Low Alarm Setpoint to -0.0833ft because this is minimum rate you want.

Example 2) You want to check every 10 minutes that over the last 1 hour the ROC has not dropped below 0.0833ft/hr (The same as the above example, but watching a smaller time span of one hour rather than six.)

  • Set Source Time Scale to per Hour because you want to compare ROC to -0.0833ft/hr.
  • Set the Period to 3600 because you want to check whether rate of change over a 1 hour period or 3600 seconds is -0.0833 or less.
  • Set the Refresh Interval to 600 because you want to calculate the ROC every 10 minutes.
  • The Low Alarm Setpoint will again be -0.0833

The second case gives more cautious results because if the ROC calculated in the last hour continues at -0.0833ft/hr, it will definitely cause the level to drop by at least 0.5 feet within the next 5 hrs.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Closed Rate of Change properties Quality tab

The Quality tab is used during the Quality portion of commissioning or testing changes to a system.

Questionable Data

Use this field to flag the tag’s data in the event that you suspect the values it is reporting might not be correct, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

Closed Rate of Change properties: Display tab

The controls in the display tab are used only in connection with the Historical Data Viewer (HDV). The Displayed Value Minimum and Maximum set the initial limits of the y-axis for this tag when it is viewed in the HDV.

These fields do not scale the data.

Engineering Units

Used by various widgets. Set this field to display the units of the rate of change.

Closed Rate of Change properties Alarms tab

You can set alarms to notify operators when the rate of change is either too slow or too fast.

High alarms are triggered when the rate matches or exceeds a set point. Depending on whether the Positive Rate option is selected on the Settings tab, the Low Alarm can be used either to warn on large negative changes, or to warn when the rate of change falls below a desired minimum.

Low and High Alarm Priority

The Low and High Alarm Priority drop-down lists are used to select the priority of the alarms that will be triggered for this tag. The default priority is None, indicating that neither alarm has been configured. The available priorities are:

  • None
  • 0 - Event
  • 1 - Critical Alarm
  • 2 - High Alarm
  • 3 - Warning Alarm
  • 4 - Notice Alarm

If you have defined your own Alarm Priority tags, those will also be available for selection.

Low and High Alarm Setpoints

Use the Low Alarm Setpoint field to enter the lowest value that this rate of change value will be permitted to attain, after which a low alarm will be triggered. Correspondingly, the High Alarm Setpoint is used to set a value at which the high alarm should be triggered.

If the Positive Rate option is selected on the Settings tab, all rates of change will be positive. In this situation, the high alarm is used to warn of excessively high rates of change (whether the changing value is rising or falling). The low alarm could be used to warn of change rates that are too slow.

If the Positive Rate option is not selected, the high alarm will warn only of excessive change rates for values that are rising. The low alarm set point should be set to a negative value to warn of excessive change rates for values that are falling.

The source for these fields may be either a constant, the result of an expression, or the value of a tag. Please see the topic: Constant, Expression or Tag for more information on selecting between these three choices.

Low and High Alarm Deadbands

If noise in the system causes a value to fluctuate above and below the set point, the alarm will repeatedly switch between active and inactive status. By using the deadband, you can dampen out these fluctuations by setting an amount by which the tag’s value must retreat back past the set point before the alarm state is considered to no longer be active.

For the low alarm, this means that the value must rise <deadband> units above the set point. For the high alarm, the value must fall by <deadband> units below the set point.

The deadband is used only for changing a current alarm’s active status. It does not affect the set point.

Low and High Alarm Delays

Noise in the value being monitored may cause transient spikes or drops in the reported rate of change. To avoid having alarms triggered by system noise, you can set a delay in seconds. The value must meet or exceed the alarm set point for the length of the delay time before an alarm will be activated.

Disable Low or High Alarm

The Disable … Alarm field is used to specify whether either the low alarm or high alarm for this tag is enabled. Disabling of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine maintenance is being performed on the equipment represented by this tag, the alarm can be disabled until the maintenance is complete and communications are re-established.

The value can be provided via any of a constant, an expression, or a tag, where 0 means "not disabled" and 1 means "disabled.
Please see the topic: Constant, Expression or Tag for help selecting which to use.

Low Alarm Pop-up Enable & High Alarm Pop-up Enable

If the configuration variable AlarmPopupsEnable is set to 1, then setting either the Low Alarm Pop-up Enable or the High Alarm Pop-up Enable, will result in a pop-up dialog being displayed whenever the respective alarm is triggered. It is strongly suggested that this feature be used sparingly.

Sound

The Sound fields can be used to set the sound that will be played when either the low alarm or the high alarm is triggered. These fields can be set to blank, 0, 1, or to the name of a .WAV sound file to be played.

If a Sound field is set to 0, no sound will be played when this alarm is triggered.

If a Sound field is set to blank or 1, an alarm sound whose properties are configured on the associated Alarm Priority tag will be played.

If a Sound field contains the name of a .WAV sound file, it will override any alarm sound configured for the associated Alarm Priority tag. When specifying a sound file, you must enter its name and extension (e.g. MySound.wav). The specified sound file must be a .WAV file, and must be stored in the application directory. If the specified sound file is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Rate of Change Error Dialogs

The period must be set to a value that is larger than the refresh interval for the Rate of Change tag to work properly. Attempting to set either value such that this is no longer the case will result in the following error dialog:

Acknowledge the dialog by clicking on the Close button, then adjust the complementary value (either a larger period or a smaller refresh interval) before continuing to set the value you were first attempting to set.

Closed Rate of Change Tag Widgets

The following widgets are available to display information about your application’s Rate of Change tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget Color Blink Widget | Color Box Widget
Color Fill Widget | Comm Line Widget
History Stats Value Widget |
LCD 5x7 Matrix Widget | Draw Text Widget
Equipment / Status Color Indicator | Image Change Widget
Indicator Light Widget | LCD 7 Segment Widget
Meter 1 Widget | Meter 2 Widget
Meter 3 Widget | Glass Gauge Widget
Classic Gauge Widget | Retro Gauge Widget
Cockpit Gauge Widget | Aqua Gauge Widget
Army Gauge Widget | Backlit Gauge Widget
Nautical Gauge Widget | Quarter Arc Gauge Widget
Linear Gauge Widget | Antique Gauge Widget
LCD Ring Widget | LCD Arc Widget
LCD Meter Widget | Multi-Color Widget
Multi-Text Widget | Numeric Value Widget
Plot Data Widget | Text Change Widget
Two Color Bar Widget | Sparklines Widget


History Statistics Tag

Not counted towards your tag license limit.

A History Statistics tag will watch a tag, gather a history within a time period and perform calculations based on the data collected. The time period is referred to as the "Data Period" in the configuration folder. Calculations are timestamped at the start of the time period specified, are updated retroactively and will not display on a plot until one full cycle of the time period has elapsed. They are, essentially, for display purposes only. They are not needed for reports and not intended to replace Totalizer tags or Counter tags.

The available calculations include:

  • Time-weighted average - average value over a specified length of time.
  • Minimum value during period
  • Maximum value during period
  • Value at start
  • Count of zero to non-zero transitions (e.g. equipment starts)
  • Non-zero time (example: total time that a pump was running during the period)
  • Totalizer, calculated as the sum of the values logged during the time period.
    Note that this calculation differs substantially from that used by Totalizer tags.
  • Change in value
    The amount a value has changed over time. (In other words, the value at the end of a period minus the value at the beginning.)
  • Change in value with rollover
    The amount a value has changed over time where the tag resets back to 0 each time it reaches a specified rollover value.

Any numeric tag may be used as the data source, so long as its value is logged.

The time period and rate are configured in the History Statistics properties Data Period tab where the period is "Latest". If you set the period to 1 hour, your first timestamp entry will appear an hour after the tag initiates and it will be timestamped with that initiation time. For example:

If the current time is 10:00 AM, and our tag is configured to show us a time-weighted average with a period of 'the latest 1 hour' at an update rate of '5 minutes'

  • We will get a flat line until 11:00AM, as data is accumulating for an hour.
  • At 11:00AM, the tag has an hour of data to work with. It calculates everything, and logs a time-weighted average timestamped 10:00AM.
  • At 11:05AM, the tag references data from 10:05AM to 11:05AM, calculates new values and logs a time-weight average timestamped 10:05AM.

As data becomes available from which to calculate values, a plotted History Statistics tag will plot retroactively.

When counting non-zero time, note that logged INVALIDS are counted as zero. If equipment goes offline (or appears to) this may cause the History Statistics tag to report a shorter run time than expected.

Getting multiple calculated values from the same device

A History Statistics tag will perform all available calculations but will only display the result of 1 selected calculation. Other calculation results can be displayed without re-doing the calculation by linking new History Statistics tags to the first. Instead of all linked History Statistics tags performing calculations, the subsequent tags will just get the result from the linked History Statistics tag.

The naming conventions and taxonomy in this sample have been simplified for illustrative purposes.

History Statistics tags work by querying the saved history of the tag they watch. This query happens on startup and at every multiple of the update rate. If you create a large number of History Statistics tags to monitor many devices, you can expect system performance to slow accordingly.

Displaying History Statistics tag values

The calculated value of the History Statistics tag can be displayed on a page using any of the Analog widgets. While a History Statistics tag can be selected for inclusion in the Historical Data Viewer (HDV), clicking on one that is drawn on a page will not cause the HDV to open. Note that if you want to save the values calculated by the History Statistics tag, you will need to select an Historian to use for the built-in connection.

Values are not logged by default, but can be by attaching an Historian. If logged, the timestamp recorded for each data period will match the start time, not the end time.

Change in value with rollover

This is for hardware that can count to a limited number, then rolls over to start a fresh count. For example, a tag that counts equipment starts, but which can only count from 0 to 15 before wrapping around to start again. This gives a value of sixteen per roll-over since there must be one more start after fifteen to have the roll-over occur. A graph of a very simple case where there is a start every second would look like the following:

(Each rollover must be followed by a fresh start, not a gradually declining value. If there are a series of declining values then, because each is less than the previous, each counts as another rollover.)

The formula used is (RolloverCount * RolloverValue) + (LastValidValue - FirstValidValue).

Where, for any given time interval:

  • Rollovers are counted when a new value is smaller than the last valid value.
  • The RolloverValue is passed to the function in the parameter StaleTime.
  • LastValidValue starts with the last valid value in the previous time interval (if any), and is updated with each new valid value within the time interval.
  • FirstValidValue starts with the last valid value in the previous time interval (if any), and is updated with only the first valid value found in the current time span.

Given this example, suppose that you want a count of starts in each thirty-second interval. In the first interval there is no previous valid value, one wrap-around and a last valid value of 12. (1*16) + (12 - 0) = 28.

This is an idealized case. Consider a more realistic case where not all values are logged. (This may be due to factors such as polling intervals, deadbands, hardware, etc.) The following graph shows the same data where the orange dots represent values obtained and logged and the gray line represents what really happened:

In the first 30 seconds there is one roll-over when the value drops from 13 to 2. The first value is 0 and the last is 11. The Historian will return 27: (1*16) + (11-0) = 27.

The Historian will return 30 for the period from 30 to 60. The first valid value (carried from the previous period) is 11. The last valid value is 9 and there are two roll-overs. (2*16) + (9-11) = 30.

Rollover Value

The maximum value at which an increasing value will reset back to 0.

Use Tag's Max Value

Select to use a maximum value from the scaling tab of the tag's configuration as the rollover value. This may vary by tag type and configuration.

If the source tag is an IO tag, the Display Range Max parameter will be used if it is set. Otherwise, the Scaled Process Data Max value will be used.

If the source is an Analog Status tag, the High Scale Value will be used if it is set. Otherwise, the Scaled Process Data Max value will be used.

Rollover Value will be ignored if the Use Tag's Max Value option is selected.

An I/O tag in Calculation mode always has an invalid ScaledMax, therefore Display Range Max must be set.

Related information:

Best Practices for Tags

Closed History Statistics properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

History Statistics properties Source Settings tab

Use this tab to select the logged tag whose value is to be used for the calculation, and the particular calculation to be performed by this instance of the History Statistics tag.

Every standard VTScada tag has only one source variable that can be used for the calculation: its value. Custom tag types may expose other variables that can be used in the calculation.

Options to select a data source

Source

Select the tag whose value (or other source variable) is to be used in the calculation. All numeric tag types are available. By default, the nearest Numeric ancestor or sibling tag will be selected. You can select another History Statistics tag here if you wish to display a different one of its 7 calculations. Selecting another History Statistics tag as the data source will disable the Data Period options for this tag instance.

Source Variable

For all standard VTScada tags, the only source variable is the tag's value. Custom tags, written specifically for your application, may make other variables available. If so, the drop-down list will be populated with the available choices.

Statistic

Select the calculation to be performed from the following list:

Average - time weighted average over the data period. Minimum value during the data period. Maximum value during the data period. Value at start of the data period. Zero to non-zero transitions during the data period. Non-zero time. Example: total time that a pump was running during the period. Totalizer - the sum of the values collected during the data period. Change in value - the amount a value has changed over time. Change in value with rollover - See notes at the beginning of this topic.

Difference from the Totalizer tag:

The Totalizer tag calculates a time-weighted integral of the values collected. The totalizer option of the History Statistics tag provides a sum of the values within the data period. Both have their uses.

Scaling Factor

The calculated value will be multiplied by the factor you specify in this field. Use for applying a scaling factor to the value, for example if correcting for raw values that are measured in terms of minutes or hours instead of seconds. Defaults to 1.

Engineering Units

Text that will indicate to operators what the value of this tag means.

Questionable Data

Use this field to flag the tag’s data in the event that you suspect the values it is reporting might not be correct, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

History Statistics properties Data Period tab

This panel is used to set the length of the calculation period, and the rate at which the calculation is updated.

If another History Statistics tag has been selected as the data source, all fields in this panel will be disabled. The source History Statistics tag will control the data period.

This does not work like, "Give me this current value, using values from the last hour and update every 5 minutes"
Think of this like, "Watch for 1 hour. Use that span to calculate the value, and give me a timestamp marking the start of the span you used."
See the introduction of this topic for an example.

History Statistics data period options

Latest

Use the text field to set a number of time units. The statistic calculation will use data from this length of time, measured to the nearest clock interval as controlled by the update rate.

Update Rate

Sets the frequency at which the statistic is recalculated. The calculation will always use data from the full length of time specified by the Latest field, ending on the clock interval specified by this update rate. For example, if the update rate is 5 minutes, the update will occur at the 5 minute mark, 10 minute mark, etc.

The update rate must not be greater than the duration of time over which the statistic is being calculated, and can be no smaller than 0.1% of that time period.

If a parameter expression is used for either of these two values, the units will always be seconds. The time unit selection tool will be disabled.

Closed History Statistics properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

History Statistics properties Historian tab

Optionally, link an Historian tag to this History Statistics tag to save a record of the summary data calculated by the History Statistics tag. Logging is done at the interval configured in the data period tab. In a multi-server application, logging is broadcast to all machines running the application.

Note that the History Statistics tag uses logged data for its calculations, thus logging the result of those calculations is redundant. Doing so may simplify later report generation, but at the cost of increased storage.

If logging is enabled by attaching an Historian, note that the timestamp of each recorded value will match the beginning of the configured time span, not the end.

The default is to have no connection to an Historian.

Closed History Statistics Tag Widgets

The following widgets are available to display information about your application’s History Statistics tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Blink Widget | Color Box Widget
Color Fill Widget | Color Line Widget
LCD 5x7 Matrix Widget | Draw Text Widget
Equipment / Status Color Indicator |
Image Change Widget | Indicator Light Widget
LCD Bar Widget | LCD 7 Segment Widget
Left Bar Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Glass Gauge Widget | Classic Gauge Widget
Retro Gauge Widget | Cockpit Gauge Widget
Aqua Gauge Widget | Army Gauge Widget
Backlit Gauge Widget | Nautical Gauge Widget
Quarter Arc Gauge Widget | Linear Gauge Widget
Antique Gauge Widget | LCD Ring Widget
LCD Arc Widget | LCD Meter Widget
Multi-Color Widget | Multi-Text Widget
Numeric Value Widget | Plot Data Widget
Right Bar Widget | Text Change Widget
Top Bar Widget | Two Color Bar Widget
 | Sparklines Widget


Digital Statistics Tags

Not counted towards your tag license limit.

Digital Statistics tags provide statistics about non-zero time and zero to non-zero transitions of any digital tag.

Digital tags include I/O & Calculations tags configured for a digital data type and tags including Digital Input, Digital Status, Pump Status, Alarm, Roster, etc.

Statistics gathered are user-configurable and include number of starts (zero to non-zero transitions) during selected time frames and total run time (non-zero time) during selected time frames.

The Digital Statistics tag works by launching a child tag for each statistic to be gathered. By default, the selected 'On Count' and 'On Time' statistics are Last Hour and Today. With these defaults, four child tags are launched:

'On' count for today (Counter Tags)

'On' count for the last hour ( History Statistics Tag)

'On' time for the last hour ( History Statistics Tag)

'On' time for the day (Totalizer Tags)

Each child tag may be included separately in a report or Historical Data Viewer plot. Historical statistics tags must wait until one full cycle of time (one hour, in this case) has passed before calculating a value. That value is time stamped to mark the beginning of the period.

Important notes about Digital Statistics tags

Please read and consider these notes carefully:

  • Select only the time frames required. A separate tag will be launched for each statistic and time frame you choose. A query happens on startup and at every multiple of the update rate. A large number of these tags will have an impact on application performance.
  • By default, the child tags are not logged. You must attach a Historian to each child tag for which you intend to save a record of the calculated statistics.
  • Do not rely on this tag for statistics of real time or starts that occurred prior to the creation of this tag. The Historian Statistics child tags will use the logged data from the monitored tag but the Totalizer and Counter tags will not.

When counting non-zero time, note that logged INVALIDS are counted as zero. If equipment goes offline (or appears to) this may cause the tag to report a shorter run time than expected.

Related information:

Best Practices for Tags

Closed Digital Statistics properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Digital Statistics properties Source tab

Used to select the source tag for which statistics are to be calculated.

Source

The Source tab is used to select which digital tag is to be monitored. Selection is limited to tags with numeric values, but only tags whose values have a clear zero to non-zero transition should be selected. Examples include Digital Input, Digital Status and Alarm tags.

Elapsed Time Meter

Your controller may be capable of recording the running time of the equipment being monitored. This is often called the Elapsed Time Meter. If your equipment supports this feature then an analog input (or analog status) tag can be created to read the value from the Elapsed Time Meter. You may then list this value beside the other statistics in your page graphics or reports.

On-Count Units

Similar to the Engineering Units field of analog tags, this value is used for display purposes only. Use it to describe what is being counted.

Exclude from Site List

Selected by default. You may choose to include this tag in the list of a Sites page as a folder. Operators may view a list of current statistics by clicking the link:

Digital Statistics properties On-Count Statistics tab

The On-Count Statistics tab is used to select the time frames for which you want to gather zero to non-zero transitions of the source tag. By default, only "Last Hour" and "Today" will be selected. Select all that you will need, remembering that a separate tag will be launched for each.

Note: Statistics for the time periods "this week" and "last week" are affected by the application property, StartOfWeek. You may use that property to set the beginning of a week to any day of your choice.

  • "Today" means since the time 00:00 this day.
  • "This Week" means since 00:00 of the first morning of the week.
  • "This Month" means since 00:00 on the morning of the first day of the month.
  • "Yesterday" means the 24 day, prior to today.
  • "Last week" means the full week prior to the current week.
  • "Last Month" means the calendar month prior to the current one.
  • "Last 24 Hours" covers the 24 hours prior to "right now".

Digital Statistics properties On-Time Statistics tab

The On-Time Statistics tab is used to select the time frames for which you want to gather the non-zero (running) time of the source tag. By default, only "Last Hour" and "Today" will be selected. Select all that you will need, remembering that a separate tag will be launched for each.

Note: Statistics for the time periods "this week" and "last week" are affected by the application property, StartOfWeek. You may use that property to set the beginning of a week to any day of your choice.

  • "Today" means since the time 00:00 this day.
  • "This Week" means since 00:00 of the first morning of the week.
  • "This Month" means since 00:00 on the morning of the first day of the month.
  • "Yesterday" means the 24 day, prior to today.
  • "Last week" means the full week prior to the current week.
  • "Last Month" means the calendar month prior to the current one.
  • "Last 24 Hours" covers the 24 hours prior to "right now".
Closed Digital Statistics Tag Widgets

The following widgets are available to display information about your application’s Digital Statistics tags:

Tag List Widget


Analog Statistics Tags

Not counted towards your tag license limit.

Configure an Analog Statistics tag with statistical information that you need from any tag having a numeric value and it will launch automatically configured child History Statistics Tag in accordance. While they can monitor digital tags, they are more commonly used to collect statistics on I/O and Calculations tags of an analog data type or legacy tags like Analog Input, and Analog Status.

Statistics are divided into three categories: minimum values, maximum values and average values. A child tag is launched for each time span selected in each category.

Each child tag may be included separately in a report or Historical Data Viewer plot.

Important notes about Analog Statistics tags:

  • Excessive use will have an impact on application performance. For every enabled statistic, an additional History Statistics tag is launched. On startup and at every multiple of the update rate, every History Statistics tag will recalculate values and system performance will slow accordingly.
  • By default, the child tags are not logged. You must attach an Historian to each child tag for which you intend to save a record of the calculated statistics If logged, the timestamp recorded for each calculated time span will match the start time, not the end time.
  • History Statistics tags work by watching the value for a specified period and then performing a calculation on that sample of data. The value is timestamped for the beginning of the time span. In this way, if these values are plotted, they will portray an accurate trend over time.
  • History Statistics tags don't plot data until one whole cycle has passed (for example, 'last hour' will take an hour before it appears on a plot, timestamped for the start of the hour.)

Related information:

Best Practices for Tags

Closed Analog Statistics properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Analog Statistics properties Source tab

Used to select the source tag for which statistics are to be calculated.

Source

The Source tab is used to select which tag is to be monitored. Any tag with a numeric value may be selected as the source.

Exclude from Site List

Selected by default. You may choose to include this tag in the list of a Sites page as a folder. Operators may view a list of current statistics by clicking the link:

Analog Statistics properties Minimum Values tab

Select the time frames, during which you wish to record the minimum value of the source tag. By default, only "Last Hour" and "Today" will be selected. Select all that you will need, remembering that a separate History Statistics tag will be launched for each.

Note: Statistics for the time periods "this week" and "last week" are affected by the application property, StartOfWeek. You may use that property to set the beginning of a week to any day of your choice.

"Today" means since the time 00:00 this day.

"This Week" means since 00:00 of the first morning of the week.

"This Month" means since 00:00 on the morning of the first day of the month.

"Yesterday" means the 24-hour day, prior to today.

"Last week" means the full week prior to the current week.

"Last Month" means the calendar month prior to the current one.

"Last 24 Hours" covers the 24 hours prior to "right now".

Analog Statistics properties Maximum Values tab

Select the time frames, during which you wish to record the maximum value of the source tag. By default, only "Last Hour" and "Today" will be selected. Select all that you will need, remembering that a separate History Statistics tag will be launched for each.

Available time frames are the same as for the Minimum Values tab.

Analog Statistics properties Average Values tab

Select the time frames, over which you wish to record the average value of the source tag. By default, only "Last Hour" and "Today" will be selected. Select all that you will need, remembering that a separate History Statistics tag will be launched for each.

Available time frames are the same as for the Minimum Values tab.

Closed Analog Statistics Tag Widgets

The following widgets are available to display information about your application’s Analog Statistics tags:

Tag List Widget


Script Tags

Not counted towards your tag license limit.

Script tags monitor the value of another tag and pass that value to a module (VTScada script code). The module performs a calculation (whatever you program it to do) and sets the script tag's value to the result.

A module is a block of VTScada scripting code - a small program. You will need to have some familiarity with the VTScada scripting language to make use of a Script tag.

The module for a script tag must have two parameters, as follows:

(
   PointObj          { object value of AI to monitor      };
   ScriptObj         { Script Object                      };
)

PointObj is the tag whose value is monitored and used by the Script tag. This matches the first field, "In Tag Scope" found in the Execute tab of the Script tag's configuration panel.

ScriptObj is used internally to link to your script tag. Whatever calculation is performed in your module must assign a value to ScriptObj\value. This enables the module to pass its calculated value back to your Script tag.

Example:

The following module will perform a first order filter on the value of a given Analog Status tag. A first order filter takes 90% of the old value and 10% of the new, thus dampening out sudden changes. It is designed to run the calculation every two seconds rather than on change, therefore if the status tag's value changes from one value to another and stays there, the script tag's value will eventually match the new value.

{============================ Filter Module ===================================}
{ This module is used to do a First order Filter of an input point             }
{   Current Value = .1 * new value + .9 * previous value                       }
{ The result is stored into the script point's value variable                  }
{==============================================================================}
(
   PointObj              { object value of Analog Status to monitor   (input)  };
   ScriptObj             { Script tag object                          (output) };
)
[ { Local variable }
  PreviousValue          { Previous Value                                      };
]
Filtering [
   { ..every two seconds... }
   If AbsTime(1, 2, 0);
   [
      { Ensure there is a valid value first time through }
      PreviousValue   = PickValid(PreviousValue, PointObj\Value);
      { Work out filtered value and assign that to the script tag }
      ScriptObj\Value = .1 * PointObj\Value + .9 * PreviousValue;
      { Save for next time }
      PreviousValue   = ScriptObj\Value;
   ]
]
{ End of Filter Module }

This module would be stored in your application folder, perhaps as FILTER.SRC.

As with all VTScada modules, it must be declared in your application's AppRoot.SRC file. The declaration links a module file to a name (variable) that VTScada can use. The declaration must be added to the PLUGINS section of AppRoot.SRC and would look similar to the following:

[ (PLUGINS)       {===== Modules added to other base system modules =====}
   Filter   module  FILTER.SRC;
]

Finally, when configuring your Script tag, you would put name of the Analog Status tag to monitor in the In Tag Scope field, and the declared variable, "Filter" in the Launched Module field.

Related information:

Best Practices for Tags

Closed Script tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Script tag properties: Execute tab

The Execute tab of the Script tag properties folder contains the properties required to identify the tag in which the script is to be executed, and the name of the script to be used.

In Tag Scope

The In Tag Scope field enables you to specify the tag whose value will be used by your script module. Use the browser button to select the tag that will provide a value to be passed to the Launched Module

Launched Module

Provide the declared name of the module this Script tag will run. (See notes in the introduction of this topic). The name to enter here must be the variable that you declared in the application's AppRoot.SRC file, for the module that will calculate a value for this Script tag.

Closed Script Tag Widgets

Script tags monitor the value of another tag and allow the execution of a script when the monitored tag's value changes. The widgets associated with Script tags enable you to display the value of the completed script.

The following widgets are available to Script tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Fill Widget | Draw Text Widget
LCD Bar Widget | LCD 5x7 Matrix Widget
Left Bar Widget | LCD 7 Segment Widget
Meter 2 Widget | Meter 1 Widget
Multi-Color Widget | Meter 3 Widget
Numeric Value Widget | Multi-Text Widget
Right Bar Widget | Plot Data Widget
Two Color Bar Widget | Top Bar Widget


Recipe and Batch Processing Tags

Tags in this category relate to the VTScada recipe and batch processing system.

Related information:

Recipe Book Tag

Recipe Parameter Tag

Recipe Proportions Tag

Recipe Trigger Tag


Recipe Book Tag

A Recipe Book holds a collection of recipes, where a recipe is a set of values (parameters) to write to a PLC. The Recipe Book provides a way to view, add, modify, delete, or write recipes (implemented using the Recipe & Batch Management Page, a user interface that you build or an API Closed Application Programming Interface. The technical details of the VTScada language.). Sets of recipes are stored in a CSV Closed Comma Separated Value. A file format used to transfer information. file.

If you are building your first recipe, start by reading Batch & Recipe Management before creating recipe-related tags and widgets.

Several Recipe Books can use the same CSV file if they want to share recipes, where each Recipe Book talks to its own PLC. Each recipe must be given a unique name. It is also possible to store different versions of the same recipe in the Recipe Book.

Import and export capabilities allow recipes to be managed externally using either Microsoft Excel® or Access®. If an external database of recipes exists, a new Recipe Book can have all of its Recipe Parameter tags automatically created by using the Import facility in the Tag Browser.

If the PLC has the concept of starting a batch using a selected recipe, the Recipe Book can start the batch after writing the recipe to the PLC, and it can watch for the PLC to indicate that the batch is complete. The Recipe Book’s value is TRUE (1) while a batch is running. Otherwise it is FALSE (0). If the tag is not configured with both a Start Address and a Done Address, the tag's value will always be FALSE.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

A Recipe Book can be triggered to write a recipe via its Start widget (best found within the Recipe & Batch Management Page), or via any Recipe Trigger tag that exists under the Recipe Book.

The Recipe Book will log information each time a recipe is written to a PLC, including the start and end time (if the PLC is capable of indicating a batch has completed), the recipe name and version, a user-entered "batch number", a note, and the user who initiated the write. Each parameter IO tag will also log the values they write to the PLC. Additionally, each event of a batch starting and stopping is recorded to the System Event Historian. These events can be viewed in the Alarms Page, History list. You can choose to disable logging to your selected Historian, but not logging to the System Event Historian.

Each new Recipe Book will be given a set of Recipe Parameter tags automatically:

  • Batch Number
  • Recipe Name
  • Recipe Version (If the Recipe Book is configured to support versioning.)

Related Tags:

Recipe Parameter Tag - Stores values for parameters of a recipe.

Recipe Proportions Tag - Can be a multiplier applied to one or more parameters (for example, to double a batch), or percentage for parameters whose quantities must add up to a certain value.

Recipe Trigger Tag - Provides a way to start a recipe batch automatically.

Related information:

Best Practices for Tags

Closed Recipe Book tag properties, ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Recipe Book tag properties, I/O tab

...

Recipe Book Tag I/O tab from the properties dialog.

I/O Device

Select the communication driver, through which recipe values will be sent to the PLC. (Communication Driver Tags)

Scan Rate

If the PLC has the concept of starting a batch using the selected recipe, the Start Address and Start Value parameters should be configured. When the RecipeBook is instructed to write its selected recipe (via UI or API), the Start Value will be written to the Start Address after the set of parameters values has been written to the PLC.

Start Address / Start Value

Controls the scan rate of all child I/O tags used by the recipe parameters.

Both the Start Address and the Stop Address are technically optional. If not provided, the batch will run once. Without a stop and start address VTScada cannot tell you when the batch starts or stops and many features will cease to function, but parameter values will still be written.

The Start Value is typically 1.

Done Address / Done Value

If the PLC can indicate that the batch is complete, the Done Address and Done Value parameters should be configured. If configured, the batch is considered to be running when the value being read from the Done Address does not match the Done Value. The batch is considered complete when the value matches the Done Value.

Be sure that the PLC will write a value to this address other than the Done Value at the start of each run.

The act of starting and of stopping each batch is recorded in both the event history and in the process I/O history for the Recipe Tag. Logging to the Historian can be switched off.

Batch Number Address

If the batch number is written to the PLC as part of each run, then you will need an I/O tag to store the value and write it to the PLC. That tag is created automatically if you provide the I/O address in this field.

Batch Number Output/Input

Configure whether VTScada is writing a batch number out to a PLC or receiving one from an external start configuration.

Batch Note Address

An address to which operator batch notes are written.

Batch Note Output/Input

Configure whether VTScada is writing a note out to a PLC or receiving one from an external start configuration.

Allow versioning of recipes

Select for recipes that have more than one version. For example there may be a recipe for a basic product that can be made in different ways depending on the ratio of various parameters.

Allow Update of Running Batch

Select if you intend to allow operators to update recipe parameter values in the PLC while a batch is running.

Batches are externally triggered

When enabled, the ability for VTScada to run a recipe will be disabled. The recipe book tag will go into reactive mode and will wait for changes to the recipe, version and step as they are read from the PLC. If a If a batch is triggered externally, VTScada will read the current parameter tag values in from the PLC and will log the start of the batch or step. On subsequent trigger events, VTScada will log the end of the previous batch or step and the beginning of the next one, pending validation of the recipe, version and step.

File Name

The file in which the recipes will be saved. By default, the name of this file will match the Recipe Book tag you are creating. You are advised to change the name if the recipe file will be used by multiple Recipe Books.

Recipe Book tag properties, Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

Logging can be disabled, but the System Event Historian will always record the time, date and current operator when each batch is started.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Closed Recipe Book tag Widgets

The following widgets are available to display information about your tags:

Recipe Batch Status Widget

Recipe Selector Widget

Recipe Version Selector

Recipe Start Widget

Recipe Update Widget

Recipe Save As Widget

Recipe Save Widget

Recipe Delete Widget

Recipe Revert Widget

Recipe Retrieve Widget

Recipe Export Widget

Recipe Note Widget

Indicator Light Widget

Image Change Widget

Text Change Widget

Color Line Widget

Equipment / Status Color Indicator

Plot Data Widget

Sparklines Widget

Animated Image Widget

Color Blink Widget

Color Box Widget


Recipe Parameter Tag

A Recipe Parameter tag is not counted towards your tag license limit, but each will be the parent of an I/O tag that may be counted if it contains a read or write address. I/O tags that are memory tags (without read or write addresses) are not counted.

If you are building your first recipe, start by reading Batch & Recipe Management before creating recipe-related tags and widgets.

A Recipe Parameter reads, writes and holds one of the values that makes up a recipe. Recipe Parameter tags must be descendents of a Recipe Book, and should be descendents of the Parameter tag within the Recipe Book structure.

Each Recipe Parameter tag has a child tag named Parameter Value. Do not edit or otherwise work directly with the Parameter Value tags.

A Recipe Book can contain multiple recipes. Each Recipe Parameter tag will hold only the value for the recipe currently selected in the Recipe & Batch Management Page. If an parameter is not used in a given recipe or recipe version, the value for that tag is zero or Invalid. Values for use with each recipe in the Recipe Book are stored in a comma-separated values (CSV) file, and loaded into the parameter tag when you select each recipe or version within the Recipe Book.

Recipe Parameter tags can be created automatically from information stored within an Access™ database file or an Excel™ spreadsheet. Look in the Recipe & Batch Management Page for the import tool.

Each Recipe Parameter tag has as a child I/O tag named Parameter Value, which may be a memory tag, or may be used to read or write the value from or to the PLC. These I/O tags are configured using expressions and (in general) should not be edited directly. You cannot change the name of an Parameter Value tag.

To change the name of a recipe parameter, change the Parameter Name property in the I/O tab or the properties dialog. The tag name is not the parameter name, although it is easier to manage parameters if they match.

The built-in Recipe & Batch Management Page will display all Recipe Parameters for a Recipe Book automatically except for the three that are created automatically: The Recipe Name, Recipe Version and Batch Number.

A Recipe Parameter tag can be drawn on any page using a control widget. This might be done if building a custom page for defining or viewing the recipes of a Recipe Book.

Every Recipe Book will contain an parameter tag named "Recipe Name". If versioning is permitted, there will also be an parameter tag named "Recipe Version".

Related information:

Best Practices for Tags

The Batch & Recipe Management Page

Closed Recipe Parameter tag properties, ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Recipe Parameter tag properties, I/O tab

Parameter Name

Holds the name used to identify the parameter in the Recipe Book's CSV file and in an Access® or Excel® file (for imports and exports). Parameter names must be unique within a Recipe Book.

Changing this parameter will automatically update the CSV file.

The Parameter Name parameter is also used as the column name in an Access or Excel table. If you want to read from or write to a file, your Parameter Names must match the column names.

Address

I/O address on the PLC for this parameter.

Data Type

Identifies the type of data required by the parameter. May be any of Analog, Discrete, Digital (1-bit), or String.

Equipment Type

If an equipment type has been defined for this parameter in the SystemStyle tag, it can be selected here. On the Recipe & Batch Management Page, users will be able to pick from a drop-down list of the labels defined in that equipment type for the value they want to configure.

Actual values for these labels are 0.25, 0.5, 0.75 ...

All equipment types for use with recipe parameters must be defined in the default SystemStyle tag. There is no option to choose an alternate style tag.

Engineering Units

Provide the units of measure that the value represents.

Digits After Decimal

Limits the number of digits shown after the decimal point wherever this tag is displayed.

Min

Minimum value that may be written.

Max

Maximum value that may be written.

Proportions Tag

Optional. Link to a Recipe Proportions Tag. Doing so allows you to set a multiplier applied at run time, or specifies that this parameter is one of several that must make up a predefined total.

Closed Recipe Parameter tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Numeric Entry Widget

String Entry Widget

Checkbox Switch Widget

Droplist Widget

Push Button Widget

Legacy Set Value Hotbox Widget

Legacy Set Value Button Widget

Rotary Control Widget (Knob)

Slider Widget

Set Analog Value Widget


Recipe Proportions Tag

An optional tag that can modify the value of one or more Recipe Parameter tags.

If you are building your first recipe, start by reading Batch & Recipe Management before creating recipe-related tags and widgets.

Different parameters can have different Recipe Proportions tags, but you cannot combine proportions. In other words, you cannot apply a multiplier to a parameter in addition to applying a portion of total.

Examples are provided following the description of this tag.

Related information:

Best Practices for Tags

Closed X properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Recipe Proportions tag, Settings tab

Proportions can be defined in either of two ways:

Parameters are multiplied at batch run time

If you need to double or triple a batch from one run to the next, create a single Recipe Proportions tag and use that in each Recipe Parameter tag.

If parameter values should not scale equally, create as many Recipe Proportions tags as required to define the multiplier for each parameter. Refer to the caution text later in this topic if the multipliers require decimal values or parameters will have decimal values after scaling.

Used in this way, you will be prompted for the multiplier value when running the batch.

Parameters must add up to [n]

Sets a total value for two or more parameters. Within the Recipe & Batch Management Page, one or more parameters can be "locked", meaning "user-set". The other parameters that use the same Recipe Proportions tag will change to equally make up the required total. To set a series of varying proportions, you might set and lock the value for the first parameter, then the second, etc. The final unlocked parameter will adjust automatically to complete the total.

Used in this way, you will not be prompted for the total amount when running the batch.

Parameter values and Recipe Proportions must be compatible with your PLC and the driver. For example, with standard Modbus, all values are integers unless your PLC can read and write /Float values. If using a standard Modbus device and not using /Float addresses, you cannot multiply a parameter value by a decimal value or write a parameter value that contains a decimal portion.

In all cases, the capabilities of your PLC are the final word on what is possible.

Closed Recipe Proportions Tag Widgets

The following widgets are available to display information about your tags:

Numeric Entry Widget

Example: Proportions Multiplier

A Recipe Proportions tag named Batch Size is created and configured as shown:

(Click to expand)

All parameters that are materials added to the recipe are configured to use this Recipe Proportions tag:

On running the batch, you are prompted for a value to use in the multiplier:

The result is a batch that is doubled in size.

Example: Portion of a Total

For one loaf of bread, the amount of flour must be 300g. But that might be made up of a combination of different types of flour. All other parameters remain the same for the recipe.

A Recipe Proportions tag named Flour Ratio is created and configured as shown:

Each parameter that specifies an amount of a flour is configured to use this Recipe Proportions tag:

To create a recipe for whole wheat bread, set the value for white flour to 200g and lock. The other flours are adjusted automatically to make up the difference:

Set the value of rye flour to 0 and lock. The amount of whole wheat flour is adjusted automatically to make up the 300g requirement:

Save the recipe as "Whole Wheat Bread - 1 Loaf".


Recipe Trigger Tag

Triggers a Recipe Book to write the specified recipe to the PLC and to record it using the specified batch number and note. This tag must be a descendent of a Recipe Book tag. The trigger may be any of the following conditions:

  • A specified recipe is complete.
  • A specified recipe is complete and an external trigger occurs, such as a timed delay or another Recipe Trigger completes
  • An external trigger occurs.

You can use this tag to run multiple recipes in sequence. For example, after Recipe A is started, a trigger tag can say “If Recipe A is complete, then start Recipe B after a 5 second delay”. The delay must be provided as an expression.

If you are building your first recipe, start by reading Batch & Recipe Management before creating recipe-related tags and widgets.

Expressions are a powerful tool for configuring tag parameters. But, their use requires some knowledge of basic programming. Refer to the Expressions chapter of the Scripting notes before attempting to use.

A Recipe Trigger tag can be used even if the PLC does not support Start or Done addresses.

No widgets are associated with this tag. It cannot be drawn on a page.

Related information:

Best Practices for Tags

Closed Recipe Trigger tag properties, ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Recipe Trigger tag properties, Activation tab

If [Recipe] [Version] is complete

An optional trigger that signals activation upon completion of a selected version of a selected recipe within the parent Recipe Tag.

Leave both as --- Any --- if the trigger depends only on an external event.

And

  • If a recipe (and optionally a version) is specified, this is an additional condition that must be met before the trigger will occur.
    Timer expressions are common, but the condition could be a watch on another tag.
  • If a recipe (and optionally a version) is not specified, the "And" condition is the trigger.
  • If set to the default, 1, then there is no additional condition. The trigger will occur when the specified recipe is complete.

As an example, this might check the value of a selected tag, where any non-zero numeric value would be taken as "TRUE".

If your goal is to add a delay to the trigger, then use an expression, such as Timeout(1, 5) Note that the expression is not executed until the specified recipe is complete. This means that the Enable parameter of the Timeout function can be left as 1 if the And condition follows recipe completion.

Then Start [Recipe] [Version]

The recipe selection is required. Add the version if there is more than one to choose from.

This is the recipe to run when the trigger is activated.

Batch Number

Optional. A specified lot number to be assigned to a given batch run.

If set as a constant, the same number will be used each time. You can use Memory Tags to provide a way for operators to set a batch number. Advanced users could use an expression or write a script module if there is an automated way to define a batch number.

If an expression is used, it will not run until it is time to start the batch.

Note

Holds a single, predefined note that will be added to each run.

Recipe Trigger tag properties, Proportions tab

Proportions Tag

A list of every Recipe Proportions Tag in the recipe book. If empty, your recipe book is not using proportions.

Value

Set the value that should be used for each proportion in the batch run triggered by this tag.


Station Tags

Viewing: Reference > Tag Reference > Station Tags

Station and Site Tags

Tags in this category create multi-I/O structures, designed for specific brands of hardware.

Related information:

MPE Duplexer Station. Define a complete MPE Duplexer station.

MPE SC Series Station. Define a complete MPE SC Series station.

MultiSmart Station. Define a complete MultiSmart station.


Grundfos Dedicated Controls

A single Grundfos Dedicated Controls tag includes all of the I/O required to monitor and operate a Grundfos CU 36X series pumping station. (https://www.grundfos.com/)

These create several child tags that do count towards you license limit, but as containers, are not themselves counted.

The controller calculates daily statistics and can provide timestamp information in the form of custom data logs and an event log. Due to the method used for calculation of statistics, local time is needed on the controller therefore the controller includes a time zone parameter.

By default, the controller is set to AutoAcknowledge mode. This is done so that when switching between operating modes (such as interlock and auto) that the operator does not need to click Cancel before reentering a mode.

The controller checks whether the station is controlled by float switches or a level sensor. If more than 2 floats are installed, then the system is float switch controlled and the setpoints tab is not needed.

If the controller requires a PIN code and an incorrect code is given, no write will occur. Direct write calls will still work, so that the pin code can be sent via the custom widget. Note that this widget is included in the automatically-built station page only if the Write Lock Enabled option is selected on the Settings tab.

Related information:

Best Practices for Tags

Grundfos Dedicated Controls Event Log

Closed Grundfos Dedicated Controls properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Grundfos Dedicated Controls tag: Settings tab

Take note of the well depth that is uploaded from the RTU. If it is significantly larger than the normal operating range, you must adjust your I/O deadbands accordingly.

Depth Units / Volume Units / Flow Units

Select the system of measurement (US or SI) for each.

The following block of settings can be uploaded from the RTU

Load From RTU

Command button, enabled only if connected to a valid RTU.

Number of Pumps

Child tags are enabled to support the defined number. Should be set manually to avoid the chance of an incorrect number due to a poor communication link.

Well Depth

Ensure that the number matches the depth units specified at the top of the dialog. The value can be verified from register 00303.

Float Switches

Child tags are enabled to support the defined number. Will be set automatically using register 00217 when read from the RTU, or you can use the control here to set the number manually.

Level Sensor

Indicates the presence of a level sensor. Will be set automatically using a presence bit, or you can override that value manually.

Pump I011X Sensors

If an IO11X is found attached to pumps, it is enabled to import additional I/O from the add-on. May be enabled manually.

Flow Calculations Supported

Will be enabled during a scan if the unit has a dedicated flow sensor. Can also be enabled manually if internal flow calculations are performed.

Pump MP204 Sensors

Will be enabled if an MP204 is detected during a scan, thereby enabling its I/O point reading. Can also be enabled manually.

Power Sensor

Will be enabled if a power sensor is detected on the RTU. Can also be enabled manually.

Pump CUE Installed

Will be enabled if a Grundfos CUE (variable speed drive) is detected on the RTU. Can also be enabled manually.

Write Lock Enabled

Check boxes, indicating the presence of each attribute on the RTU that can be enabled or disabled via an RTU scan.

Use the following settings to indicate information that you want to read. You must also enable each of these attributes on the RTU. For this set, you must check each option - none can be read from the RTU.

Mixer Present

Enable to read in mixer information, if present.

Interlock Settings

Enable to adjust interlock settings, if used.

Import GENIBus Comms

Enable to view GENIbus communications for detecting problems between the controller and the pumps.

Groups Enabled

Enable in order to edit pump group settings, if used.

Event Log

Enable in order to read the event log from the device. Required if using the Grundfos Dedicated Controls Event Log tag.

Set Real-Time Clock

Enable to allow VTScada to set the real time clock automatically based on the selected time zone.

Custom Data Log

Enable to allow reading of the custom data logs. Note that these cannot be configured from VTScada. Required if using the Grundfos Dedicated Controls Custom Data Log tag.

Read Real-Time-Clock

Enable to display the current time of the real-time clock on the RTU.

Alarm Simulation

Enable to use the alarm simulation tool in the controller. This will be added to the Station tab of the automatically-generated station page.

Pump Current Sensor

Enable if a current sensor is installed on the pump that is not part of an IO11X add-on.

CIM Settings

Enable to view and edit the CIM card settings (Communication Interface Module). Needed only for configuration.

Pump Water in Oil Sensor

Enable if an oil-in-water sensor is on the pump that is not part of an IO11X or MP204 module.

Pump PID Setpoints

Enable to allow modification of the pump PID setpoints.

Import Grundfos Version Information

Enable to display Grundfos-specific information on the inputs tab.

Foam Draining Enabled

Select in order to gain access to the setpoint value if the foam-draining feature of the controller is enabled.

Control Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Device Clock Time Zone

The default is to use the server's time zone, without adjusting for daylight savings time. Instead, you may choose to use the device clock in UTC, or any standard time zone.

Grundfos Dedicated Controls tag: Communications tab

Port

Select the TCP/IP or Serial Port tag that is to be used for communication with the equipment. The ancestor port is selected automatically if this tag is created as a child of a port. If there is a sibling port and no ancestor port, then the sibling port will be selected automatically.

CIM Model

Choose between models CIM 200, CIM 250 GSM, CIM 250 GPRS, or CIM 500

PLC Address

The standard port is 231, but may be overridden if necessary.

Comm Channel

Serial RTU, Open Modbus TCP/IP or Open Modbus TCP

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Station Number (Poll Sequence)

Used by the built-in Polling Driver Tags. Use the Poll Sequence Number field to specify a number that identifies this polling driver's place in the polling sequence for the identified poll group.

For example, if you have 5 polling drivers, each of which is associated with a different communication driver (e.g. Modbus1, Modbus2, etc.), and all 5 polling drivers have the same poll group identified (in their Poll Group Name property), you must enter a number from 1 to 5 for each of the polling drivers to determine the order in which the 5 communication drivers belonging to the poll group will be polled.

I/O Driver Override (optional)

Typically uses a built-in Modbus Compatible Device Driver, but you may use this tool to select another.

Scan Interval

Used by the built-in Polling Driver. The amount of time (in seconds) between requests for data from this Polling Driver tag to the I/O device with which it is associated.

Grundfos Dedicated Controls tag: Auxiliary DI tab

Table of auxiliary digital inputs.

Configuration tools affect only the selected entry in the table. If no entry is selected, no controls are enabled.

Enabled

Controls whether the selected input is enabled.
No other configuration is possible if the input is not enabled.

Custom

The appearance of this parameter as a drop-down matches those on the following tabs, but there is no option other than "Custom".

Description

Use to override the default description of the input.

On Text / Off Text

Displayed by certain widgets when the input is in state 1 (On) or state 0 (Off)

Grundfos Dedicated Controls tag: Auxiliary DO tab

Table of auxiliary digital outputs. Select an entry in the table in order to enable the following configuration controls:

Enabled

Controls whether the selected output is enabled.
No other configuration is possible if the output is not enabled.

Custom option

Select between "Custom" and "Pulse Custom Relay".

Description

Use to override the default description of the output.

On Text / Off Text

Define the text to be displayed by widgets that support this feature.

Grundfos Dedicated Controls tag: Auxiliary AI tab

Table of auxiliary analog inputs. Select an entry in the table in order to enable the following configuration controls:

Enabled

Controls whether the selected output is enabled.
No other configuration is possible if the output is not enabled.

Custom option

Choose between "Custom", "Custom Counter", "Control Source", "Connection" or "VFD Mode"

Description

Use to override the default description of the input.

Scaled Process Data Min and Max

Defines the scaling from raw data (defined by the controller) to the displayed engineering units.

Units

Engineering units, informing the operator what the value represents.

Grundfos Dedicated Controls tag: Display tab

Latitude and Longitude

Holds location coordinates for this tag, thereby allowing it to be represented on a Site Map page.

Custom Details Page

If a custom details page has been created for this context tag, then that page should be selected here. If there is no custom details page, then operators will see the standard Site Details page upon clicking the pin for this tag in a Site Map.

Map Icon

If a custom map icon widget has been defined, you can select it here. That icon will then be used instead of the standard pin when this tag is represented on a Site Map page. If there is no custom map icon, then the standard pin will be used.

Site List Display

Assuming that this tag has site properties, it will be included in the list of a Sites page. What will happen when an operator clicks on this tag in that list depends on the Site List display choice, and on whether any of this tag's children are I/O tags.

  • Display as Site: A click will open the Site Details page as a pop-up.
  • Display as Folder: A click will leave focus on the Sites page, but the list will now show the child tags of this site.
  • Exclude: This tag should not be shown in the Sites page list.

Map Zoom Level

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Closed Grundfos Dedicated Controls tag: Widgets

The following widgets are supported in addition to those built into the custom Grundfos CU36X pages.
(It would be unusual to draw any of the component widgets on its own, therefore they are not described here.)

Alarm Priority Box | Alarm Priority Icon
Alarm List | Site Icon Widget
Site Summary Widget | Site Alarm List
Tag List Widget | Draw HDV Widget
Site Details Widget |

Related information:

Sites & Maps

Site Details Page

Site Map

Custom Map Icons


Grundfos Dedicated Controls Custom Data Log

If creating this tag, you are advised to make it a child of a Grundfos Dedicated Controls tag. Doing so will ensure that links to that controller's data are made automatically. Ensure that the Custom Data Log option is set in the parent controller tag's configuration.

This tag has functions to perform an ad hoc read of the parent Controller's index log, and then based on that data, reads the registers containing the log data. Formats the log data for display with its associated widget.

Related information:

Best Practices for Tags

Grundfos Dedicated Controls

Grundfos Dedicated Controls Event Log

Closed Grundfos Dedicated Controls Custom Data Log properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Grundfos Dedicated Controls Custom Data Log: I/O tab

I/O Device

Will link to the parent Grundfos Dedicated Controls tag's polling driver.

Index Address

Defaults to 47001, the address of the controller's index log.

Log Address

Defaults to 407301, the address of the controller's data log.

Grundfos Dedicated Controls Custom Data Log: Widgets

The Grundfos Dedicated Controls Custom Data Log can be represented by only one widget:

Grundfos Custom Data Log Widget


Grundfos Dedicated Controls Event Log

If creating this tag, you are advised to make it a child of a Grundfos Dedicated Controls tag. Doing so will ensure that links to that controller's data are made automatically.

Ensure that the Event Log option is set in the parent controller tag's configuration.

This tag performs an ad hoc read of the parent Controller's event log registers, formats the data, and stores that data so that it can be displayed by the associated widget.

Related information:

Best Practices for Tags

Grundfos Dedicated Controls

Grundfos Dedicated Controls Custom Data Log

Closed Grundfos Dedicated Controls Event Log properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Grundfos Dedicated Controls Event Log: I/O tab

I/O Device

Will link to the parent Grundfos Dedicated Controls tag's polling driver.

Address

Defaults to 46001

Grundfos Dedicated Controls Event Log: Widgets

The Grundfos Dedicated Controls Event Log can be represented by only one widget:

Grundfos Event Log Widget


Grundfos Dedicated Controls\Pump

These tags are created by VTScada when you configure a Grundfos Dedicated Controls tag. Each controller may have up to six pumps.

Configuration of each pump is automatic, based on the properties of the controller. In rare circumstances, you may override parameters as needed. You should never need to create Grundfos Dedicated Controls\Pump tag directly.

This is a Context-derived type, therefore it can be represented by any widget that applies to a Context tag.

There is also a Grundfos pump control widget, used within the automatically-generated Grundfos Dedicated Controls page.


Grundfos Control MPC

The Grundfos Control MPC is a multi-purpose controller that will work with Modbus RTU (CIM 200), Modbus TCP (CIM 500), UDP/IP BACnet and MSTP BACnet. (MSTP BACnet only if used on foreign networks to which you connect via IP)

A selection of models is available for both the Modbus profile and the BACnet profile.

This one tag contains the child tags needed to run the system in any of the standard closed-loop operating modes (pressure, temperature, flow). Additional child IO tags can be added to match the exact sensor configuration, where they will display on the inputs tab.

Related information:

Best Practices for Tags

Grundfos Dedicated Controls Event Log

Closed Grundfos Control MPC ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Grundfos Control MPC: Settings tab

Units

The device may be used for a variety of control modes, covering measurement of flow, temperature, and pressure. Use this to ensure that the display matches the purpose of the controller and your preferred system of units.

Number of Pumps

Select a number from 0 to 6, matching your system.

Import GENIBus Comms

Enable to view GENIbus communications for detecting problems between the controller and the pumps.

Alarm Simulation

Enable to use the alarm simulation tool in the controller. This will be added to the Summary tab of the automatically-generated station page. To enable the Start button, provide an alarm code in the space provided.

CIM Settings

Enable to view and edit the CIM card settings (Communication Interface Module). Needed only for configuration.

Import Grundfos Version Information

Enable to display Grundfos-specific information on the inputs tab.

Pilot Pump

Select this option if the system contains a dedicated pilot pump for its controls.

Backup Pump

Enable if the system contains a dedicated backup pump for its controls

Tank Filling Application

Enable if the controller is configured for a tank-filling application, in order to allow access to the extra setpoints that are needed.

Control Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Grundfos Control MPC: Communications tab

Port

Select the TCP/IP or Serial Port tag that is to be used for communication with the equipment. The ancestor port is selected automatically if this tag is created as a child of a port. If there is a sibling port and no ancestor port, then the sibling port will be selected automatically.

Station Number (Poll Sequence)

Used by the built-in Polling Driver Tags. Use the Poll Sequence Number field to specify a number that identifies this polling driver's place in the polling sequence for the identified poll group.

For example, if you have 5 polling drivers, each of which is associated with a different communication driver (e.g. Modbus1, Modbus2, etc.), and all 5 polling drivers have the same poll group identified (in their Poll Group Name property), you must enter a number from 1 to 5 for each of the polling drivers to determine the order in which the 5 communication drivers belonging to the poll group will be polled.

Scan Interval

Used by the built-in Polling Driver. The amount of time (in seconds) between requests for data from this Polling Driver tag to the I/O device with which it is associated.

CIM Model

Choose between models CIM 200, CIM 250 GSM, CIM 250 GPRS, CIM 300, CIM 500 Modbus or CIM 500 BACnet.

Driver

Configured automatically in response to your choice of CIM model.

Comm Channel (Modbus compatible profile)

Serial RTU, Open Modbus TCP/IP or Open Modbus TCP

PLC Address (Modbus compatible profile)

The standard port is 231, but may be overridden if necessary.

Network Type (Routing) (BACnet profile)

Set automatically based on your selection of CIM model

Device Node and Device Network Number (BACnet profile)

When operating in foreign network mode of BACnet, specify the network number that the device is on, and specify the device node number on that network.

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

I/O Driver Override (optional)

The device typically uses a built-in Modbus Compatible Device Driver, or BACnet Driver based on your choice of CIM, but you may use this tool to select another.

Closed Grundfos Control MPC: Display tab

The Display tab is used to define the placement (latitude and longitude) of the Polling Driver station. Decimal values should be used rather than degrees, minutes and seconds.

Latitude and Longitude

Holds location coordinates for this tag, thereby allowing it to be represented on a Site Map page.

Custom Details Page

If a custom details page has been created for this context tag, then that page should be selected here. If there is no custom details page, then operators will see the standard Site Details page upon clicking the pin for this tag in a Site Map.

Advanced Configuration:

The default page selection dialog has a filter for "all pages" or "site pages", meaning those that take a site tag as the first parameter.

You can add either of the following two properties in the Edit Properties page of the Application Configuration dialog to restrict this filter:

LimitPageListToSitesPages

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog for all users.

LimitPageListToSitesPagesIfRealmUser

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog if the user belongs to a security group.

Custom Map Icon

If a custom map icon widget has been defined, you can select it here. That icon will then be used instead of the standard pin when this tag is represented on a Site Map page. If there is no custom map icon, then the standard pin will be used.

Site List Display

Assuming that this tag has site properties, it will be included in the list of a Sites page. What will happen when an operator clicks on this tag in that list depends on the Site List display choice, and on whether any of this tag's children are I/O tags.

  • Display as Site: A click will open the Site Details page as a pop-up.
  • Display as Folder: A click will leave focus on the Sites page, but the list will now show the child tags of this site.
  • Exclude: This tag should not be shown in the Sites page list.

Map Zoom Level

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Closed Grundfos Control MPC: Widgets

The following widgets are supported for your Grundfos Control MPC.
(It would be unusual to draw any of the component widgets on its own, therefore they are not described here.)

Alarm Priority Box | Alarm Priority Icon
Alarm List | Site Icon Widget
Site Summary Widget | Site Alarm List
Tag List Widget | Draw HDV Widget
Site Details Widget |


MPE Duplexer Station Tags

Viewing: Reference > Tag Reference > Station Tags > MPE Duplexer Station Tags

MPE Duplexer Station

These create several child tags that do count towards you license limit, but as containers, are not themselves counted.

"MPE" stands for Motor Protection Equipment. A single MPE Duplexer Station tag includes all of the I/O required to monitor and operate a MPE Duplexer station.

Related information:

Best Practices for Tags

Sites & Maps

Site Details Page

Site Map

Custom Map Icons

Closed MPE Duplexer Station properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

MPE Duplexer Station properties Settings tab

Controller Model

The options are, Duplexer or Intrinsically Safe Duplexer. Defaults to Intrinsically Safe.

Number of Pumps

Set the number of pumps in the station, thereby controlling how many associated child tags will be created. Ranges from one to two.

Well Depth

Provide the depth of the well, as measured in the units specified in the next field. Setpoints must be with the range of the well depth provided.

Depth Units

Provide the system of units to be used for the depth of the well. This value is used only as a label on the display.

High Level (Ft)

Provide a number

Lag Level (Ft)

Provide a number

Well Volume

Provide the volume capacity of the well, as measured in the volume units specified in the next field.

Volume Units

Provide the system of units to be used for measuring the volume of fluid in the well. This value is used only as a label on the display.

Lead Level (Ft)

Provide a number

Off Level (Ft)

Provide a number

Low Level (Ft)

Provide a number. Used only if the Intrinsically Safe model has been selected.

Privilege

If you wish to restrict access to the controls of this station, select the custom privilege to be associated with it. Only the operators who have been assigned a security rule that includes this privilege will be able to control the station.

MPE Duplexer Station properties Communications tab

Port

Select the communications port to use for this station. By default, the nearest parent will be selected.

Modbus Configuration

The driver created for this station will be based on the Modbus protocol. (Modbus Compatible Device Driver) Use the fields in this section to configure the details.

Station Number

Poll Sequence if this tag is using a Polling Driver. Also used for sorting the data in a Pump Activity or Derived Flow report.

I/O Driver Override (optional)

Provides a way for you to select an existing driver tag to be used instead of the driver built-into the station.

MPE Duplexer Station properties DisplayTab

The Display tab is used to define the placement (Latitude and Longitude parameters) of the MPE Duplexer station. Decimal values should be used rather than degrees, minutes and seconds.

In most cases, it is easier to set the location using the map interface of the Site Details page than to enter the latitude and longitude values here.

Custom Details Page

A ready-made page is provided for your MPE Duplexer station. This includes a display of all I/O values, alarms and settings that can be used.

If you prefer to build your own parameterized page, to be opened when an operator clicks on this MPE's site draw widget, then select that page in the drop-down list provided in this field.

Parameter: CustomDetailsPage

Advanced Configuration:

The default page selection dialog has a filter for "all pages" or "site pages", meaning those that take a site tag as the first parameter.

You can add either of the following two properties in the Edit Properties page of the Application Configuration dialog to restrict this filter:

LimitPageListToSitesPages

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog for all users.

LimitPageListToSitesPagesIfRealmUser

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog if the user belongs to a security group.

Custom Map Icon

This station will be displayed on all site maps in the application using a pin. You can create and use any icon you like in place of the standard pin. (Instructions are provided elsewhere in this document) If you have done so, you may use this field to select the icon that will represent this station on maps.

Parameter: CustomMapIconParm

Exclude from the site list

When selected, this tag will not be included on a Sites page.

Map Zoom Level

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Closed MPE Duplexer Station Tag Widgets

The following widget are available:

Alarm Priority Box | Alarm Priority Icon
Alarm List | Site Icon Widget
Site Summary Widget | Site Alarm List
Site Details | Pump Control
Well Details | Well Flow
Well Plot | Well Setpoints
Controller Status | Station Summary
Alarm List | Station All Inputs
Station All Outputs | Station Comms
Station Faults | Station Stats
Pump List | Tag List
Analog Control List | Analog Input List
Digital Input List | Digital Output List


MPE Duplexer Child Tags

A single MPE Duplexer Station tag includes all of the I/O required to monitor and operate a MPE Duplexer pumping station. The I/O tags, alarms and more are implemented as child tags of the MPE Duplexer Station.

It is recommended that you do not create instances of these tags, independently of a MPE Duplexer station.

MPE Duplexer Child Tag Widgets

These widgets are components of the overall MPE Duplexer Station displays. While they can be drawn independently, it is recommended that you use the MPE Duplexer Station widgets to create these components in the correct context.

Related information:

MPE Duplexer Station


MPE SC Series Station Tags

Viewing: Reference > Tag Reference > Station Tags > MPE SC Series Station Tags

MPE SC Series Station

These create several child tags that do count towards you license limit, but as containers, are not themselves counted.

MPE stands for Motor Protection Equipment. This tag will support either of the SC1000 or the SC2000 controllers.

Related information:

Best Practices for Tags

Closed MPE SC Series Station properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

MPE SC Series Station properties Settings tab

Controller Model

Specify whether this tag is to be used with the MPE SC1000 or the SC2000 controller.

Number of Pumps

Select the number of pumps that are installed at this station. Possible values range from one to four.

Well Depth

Provide the depth of the well, as measured in the units specified in the next field.

Depth Units

Provide the system of units to be used for the depth of the well. This value is used only as a label on the display.

Flow Units

Provide the system of units to be used for flow. This is required only if flow calculations are supported by the controller.

Well Volume

Provide the volume capacity of the well, as measured in the volume units specified in the next field.

Volume Units

Provide the system of units to be used for measuring the volume of fluid in the well. This value is used only as a label on the display.

Total Daily Flow Units

Provide the system of units to be used for total flow. This is required only if flow calculations are supported by the controller.

Depth Probe Present

Select to box to indicate that your well has a depth probe.

Station Backup Generator Present

Select to box to indicate that your station has a backup generator.

Flow Calculations Supported

Select to box to indicate that your controller supports flow calculations.

Pump VFD Control Supported

Select to box to indicate that your controller provides VFD control.

Privilege

If you wish to restrict access to the controls of this station, select the custom privilege to be associated with it. Only the operators who have been assigned a security rule that includes this privilege will be able to control the station.

MPE SC Series Station properties Communications tab

In this tab, you define the parameters for the Communications Port and the Modbus Driver that will be created automatically as part of this station.

Port

Select the communications port to use. By default, the nearest parent will be selected.

Modbus Configuration

The driver created for this station will be based on the Modbus Compatible Device . Use the fields in this section to configure the details of the Modbus protocol that will be used. For detail, see: Modbus Compatible Device Tags.

Station Number

Poll Sequence if this tag is using a PollDriver. Also used for sorting the data in a Pump Activity or Derived Flow report.

I/O Driver Override (optional)

Provides a way for you to select an existing driver tag to be used instead of the driver built-into the station.

Closed MPE SC Series Station properties Auxiliary DI tab

Provides an Enabled / Disabled option for each of the auxiliary input addresses of the station. The actual value being monitored by each input, N, can be configured using the drop-down list in the "Input N" section of the panel.

Closed MPE SC Series Station properties Auxiliary DO tab

You may define up to six auxiliary digital outputs for an SC2000 controller and up to five auxiliary digital inputs for the SC1000.

Closed MPE SC Series Station properties Auxiliary AI tab

You may define up to four auxiliary analog inputs for the SC2000 controller. The SC1000 does not support auxiliary analog inputs.

Closed MPE SC Series Station properties Display tab

The Display tab is used to define the placement (Latitude and Longitude parameters) of the MPE SC Series station. Decimal values should be used rather than degrees, minutes and seconds.

In most cases, it is easier to set the location using the map interface of the Site Details page than to enter the latitude and longitude values here.

Custom Details Page

A pre-built page is provided for your MPE SC Series station. This includes a display of all I/O values, alarms and settings that can be used.

If you prefer to build your own parameterized page, to be opened when an operator clicks on this MPE's site draw widget, then select that page in the drop-down list provided in this field.

Parameter: CustomDetailsPage

Advanced Configuration:

The default page selection dialog has a filter for "all pages" or "site pages", meaning those that take a site tag as the first parameter.

You can add either of the following two properties in the Edit Properties page of the Application Configuration dialog to restrict this filter:

LimitPageListToSitesPages

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog for all users.

LimitPageListToSitesPagesIfRealmUser

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog if the user belongs to a security group.

Custom Map Icon

This station will be displayed on all site maps in the application using a pin. You can create and use any icon you like in place of the standard pin. (Instructions are provided elsewhere in this document) If you have done so, you may use this field to select the icon that will represent this station on maps.

Parameter: CustomMapIconParm

Exclude from the site list

When selected, this tag will not be included on a Sites page.

Map Zoom Level

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Closed MPE SC Series Station Tag Widgets

The following widgets are available to display information about your application’s MPE SC Series Station tags:

Alarm Priority Box | Alarm Priority Icon
Alarm List | Site Icon Widget
Site Summary Widget | Site Alarm List
Site Details | Pump Control
Well Details | Well Flow
Well Plot | Well Setpoints
Controller Status | Pump Alternation Control
Station Summary | Station Power
Alarm List | Station All Inputs
Station All Outputs | Station Comms
Station Faults | Station Stats
Pump List | Tag List
Analog Control List | Analog Input List
Digital Input List | Digital Output List

Related information:

Sites & Maps

Site Details Page

Site Alarm List

Site Map

Custom Map Icons


MPE SC Child Tags

A single MPE SC Station tag includes all of the I/O required to monitor and operate a MPE SC Series pumping station. The I/O tags, alarms and more are implemented as child tags of the MPE SC Station.

(See: Parent-Child Tag Structures)

It is recommended that you do not create instances of these independently of a MPE SC station.

MPE SC Child Tag Widgets

These widgets are components of the overall MPE SC Station displays. While they can be drawn independently, it is recommended that you use the MPE SC Station widgets to create these components in the correct context.

Related information:

MPE SC Series Station


MultiSmart Station Tags

Viewing: Reference > Tag Reference > Station Tags > MultiSmart Station Tags

MultiSmart Station

The stations are not counted, but each station will create several child tags that do count towards you license limit.

A single MultiSmart Station tag includes all of the I/O required to monitor and operate a MultiSmart pumping station. Configuration is done in part through the standard set of VTScada tag configuration panels and in part through a MultiTrode-supplied XML file that describes your equipment. File names to look for are as follows:

  • DNP3: dnpslave.xml
  • Modbus: mbs.xml

Related information:

Best Practices for Tags

Closed MultiSmart Station properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

MultiSmart Station properties Settings tab

XML Slave Index

Select which slave from the XML file should be used by VTScada when generating the tag list. The is most often 1 (using the first and only slave in the file). The value represents a 1-based index. The spinbox will be limited to the number of slaves defined in the XML file.

Negative Offset

An offset to the level measurement, used to account for the distance from the bottom of the probe to the bottom of the well. Because the zero level in VTScada is relative to the bottom of the probe, failing to add the value of this offset can result in false alarms and incorrectly displayed values.

XML Configuration File and Import XML File

Click the Import XML File button to locate and import the configuration file for this station. A copy is made of the file that you import - no link is maintained to the original file. If the original is edited, you will need to import again to bring those changes into your application. File names to look for are as follows:

  • DNP3: dnpslave.xml
  • Modbus: mbs.xml

The selection list shows the files that have previously been imported.

Privilege

If you wish to restrict access to the controls of this station, select the custom privilege to be associated with it. Only the operators who have been assigned a security rule that includes this privilege will be able to control the station.

MultiSmart Station properties Wells tab

Number of Wells

Lift stations can have either one well or two. All parameters are the same between the two wells.

Well Depth

Provide the depth of the well as measured in the Units value specified (meters, feet or inches). This value is used for the visual representation of the well and as a limit on the possible setpoint values.

Well Volume

Provide the volume capacity of the well, measured in the Units value specified (US gallons or Liters). This value is used by related reports.

Units

Select the system of measurement to be used. Choices are Metric or Imperial.

Level Units

Select how units for the well level and related tags are to display. Choices are "m", "ft", "in", "%", or any custom unit that you care to type.

MultiSmart Station properties Pumps tab

Number of Pumps

Lift stations may have from one to nine pumps.

If this station has more than one well, use the tools provided to define which pump is in which well.

MultiSmart Station properties Communications tab

Port

Select the TCP/IP or Serial Port tag that is to be used for communication with the equipment. The ancestor port is selected automatically if this tag is created as a child of a port.

Protocol

Selection determines what type of communications driver will be created for use in this station. Choices are DNP3 or Modbus

Protocol Configuration

Configuration options vary according to the selected protocol type. For detail, see: DNP3 Driver Tags or Modbus Compatible Device Tags.

Station Number

Poll Sequence if this tag is using a Polling Driver. Also used for sorting the data in a Pump Activity or Derived Flow report.

I/O Driver Override (optional)

Provides a way for you to specify a specific, existing driver tag to be used instead of the driver built-into the station. In most cases this need not be selected.

Closed MultiSmart Station properties DisplayTab

The Location tab is used to define the placement (Latitude and Longitude parameters) of the MultiSmart station. Decimal values should be used rather than degrees, minutes and seconds.

In most cases, it is easier to set the location using the map interface of the Site Details page than to enter the latitude and longitude values here.

Custom Details Page

A pre-built page is provided for your MultiSmart station. This includes a display of all I/O values, alarms and settings that can be used.

If you prefer to build your own parameterized page, to be opened when an operator clicks on this MultiSmart's site draw widget, then select that page in the drop-down list provided in this field.

Parameter: CustomDetailsPage

Advanced Configuration:

The default page selection dialog has a filter for "all pages" or "site pages", meaning those that take a site tag as the first parameter.

You can add either of the following two properties in the Edit Properties page of the Application Configuration dialog to restrict this filter:

LimitPageListToSitesPages

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog for all users.

LimitPageListToSitesPagesIfRealmUser

System section. Set to 1 (TRUE) to prevent access to the "all pages" option in the page selection dialog if the user belongs to a security group.

Custom Map Icon

This station will be displayed on all site maps in the application using a pin. You can create and use any icon you like in place of the standard pin. (Instructions are provided elsewhere in this document) If you have done so, you may use this field to select the icon that will represent this station on maps.

Parameter: CustomMapIconParm

Exclude from the site list

When selected, this tag will not be included on a Sites page.

Map Zoom Level

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Closed MultiSmart Station Tag Widgets

The following widgets are available to display information about your application’s MultiSmart Station tags. In most cases, you need only use the Station Icon or the Station Summary. The remaining methods are components of the station page that will be created for you. Both the Station Icon the Station Summary link to this page.

If your application includes more than one station tag, you may prefer to draw a Station List, which is an automatically created display of Station Summary widgets, one for each station.

Alarm Priority Box | Alarm Priority Icon
Alarm List | Site Icon Widget
Site Summary Widget | Site Alarm List
Site Details | Pump Control
Well Details | Well Flow
Well Plot | All Well Setpoints
Well Setpoints | Controller Profile
Controller Maintenance | Alarm List
Custom Alarms | Station Summary
Station Power | Pump List
Station All Inputs | Station All Outputs
Station Comms | Station Faults
Station Stats | Tag List
Analog Control List | Analog Input List
Digital Input List | Digital Output List

Related information:

Sites & Maps

Site Details Page

Site Map

Custom Map Icons


MultiSmart Station Child Tags

A single MultiSmart Station tag includes all of the I/O required to monitor and operate a MultiSmart pumping station. The I/O tags, alarms and more are implemented as child tags of the MultiSmart Station.

It is recommended that you do not create instances of these tags, independently of a MultiSmart station.

MultiSmart Station Child Tag Widgets

These widgets are components of the overall MultiSmart displays. While they can be drawn independently, it is recommended that you use the MultiSmart widgets to create these components in the correct context.

Related information:

MultiSmart Station


Configuration Tags

Tags in this category relate to the appearance or structure of your application. This list includes Context tags, Font tags and the Realm Display Setup tag.

Related information:

Comm Link Sequencer Tags - Sequence requests for the same communication channel across multiple ports.

Context Tags - Create a generic and customizable template that you can use to define any natural grouping in your application

IP Network Listener Tags - Allows certain driver tags to listen for IP messages.

Font Tags - Specify font and text style characteristics for your labels.

Realm Display Setup Tags - Defines the level of display control, granted to operators connecting to an application from a VTScada Thin Client.


Comm Link Sequencer Tags

Not counted towards your tag license limit.

Comm Link Sequencer tags may be added when your application includes several device drivers that must share the same communication channel and that are themselves unable to determine when the channel is free. Newer radio devices that rely on a TCP/IP or UDP/IP port are particularly likely to experience this problem. This tag will automatically serialize access to the communication channel.

Use the Comm Link Sequencer tag only if you are experiencing communication problems that can be attributed directly to multiple devices attempting to use the same channel at the same time. If device access does not need to be serialized, then doing so will slow communication.

The Comm Link Sequencer is not required when multiple device drivers share the same port. Access to a single port is always serialized. The Comm Link Sequencer extends his sequencing across multiple port tags.

No configuration is required beyond the creation of a Comm Link Sequencer tag as a parent (or ancestor) of the port tags that will use it.

You can monitor this tag by drawing it on any page. The value will match the number of pending requests.

This tag is not logged. In the rare event that you need to view a history of this tag in the HDV, use TempLoggerEnable.

Related information:

Best Practices for Tags

Closed Comm Link Sequencer properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Closed Comm Link Sequencer Tag Widgets

The following widgets are available to display information about your application’s Analog Input tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Fill Widget | LCD 5x7 Matrix Widget
Draw Text Widget | LCD Bar Widget
LCD 7 Segment Widget | Left Bar Widget
Meter 1 Widget | Meter 2 Widget
Meter 3 Widget | Glass Gauge Widget
Classic Gauge Widget | Retro Gauge Widget
Cockpit Gauge Widget | Aqua Gauge Widget
Army Gauge Widget | Backlit Gauge Widget
Nautical Gauge Widget | Quarter Arc Gauge Widget
Linear Gauge Widget | Numeric Value Widget
Right Bar Widget | Top Bar Widget
Two Color Bar Widget |


Context Tags

Not counted towards your tag license limit.

Context tags are used as parents in parent-child tag structures. They provide a generic and customizable template that you can use to define any natural grouping in your application (region, station, city, sub-assembly, etc.). The parameter list for a context tag is left for you to configure. You may add whatever properties you wish. For example, you might add properties named Latitude and Longitude to be able to draw the Context tag on a Site Map, or you might create I/O address fields that can be used by child tags that you add to the Context tag. If you have one type of Context tag that is to be used for sites, you can add another to be used as a connector between those sites.

Notes for Property Value:

  • When entering property values, decimal numbers of up to 15 significant digits will be converted to a numeric value. Numbers with more than 15 significant digits will be converted to an equivalent text string.
  • A decimal number expressed in exponential notation, (e.g. 1.1E-3) will be converted to an equivalent text string.
  • Binary, Octal, and Hexadecimal values are converted to their 32 bit signed integer equivalent. Any such number that exceeds the maximum signed 32 bit value limits (-2,147,483,648, 2,147,483,647) is undefined behavior and will be incorrectly converted to a numeric value.

Your context tags can be turned into new tag-types by assigning them a type-name, then using the Create New Type command from the tag's right-click menu in the Tag Browser. All the child tags will be included as part of the new type definition. This feature is especially useful if the child tags are configured using parameter expressions so that their properties are based on values defined in the parent tag.

Context tags can be given site parameters, allowing them to be located on a site map. Related configuration parameters allow you to choose the icon that will represent the site and the page that will open when an operator clicks on that site. You can also configure how and whether the site will be shown in the Sites List page.

Other tag types also count as "sites", including Polling Drivers and Station tags.

There are three situations where it is helpful to set Exclude from Site List on your Context tags:

- When requesting a Go To Page on any Context tag (or other container type) from the Tag Browser or Alarm Page, the Sites page will be included in the list of possible pages and might be the default.
- The above is also true for child tags of the Context tag.
- Context tags (and new types created from them) are always included in the list of a Sites List Display Options. This may not be appropriate if the Context represents equipment rather than a site.

To prevent these actions, do the following:
1. Select the Add Site Properties button in the Settings tab of the Context tag.
(See: Change the Parameter List if you have already turned the Context into a new type.)
2. Delete all site properties except for SiteListDisplay.
3. In the Display tab, select the option Exclude from the site list
(If any child tags should be included in a site list then select Display as a Folder instead.)

If you have created one or more sites, you can choose to configure another context tag as a connector. Connectors are drawn as a line (you configure the line style) between two sites that have latitude and longitude values. Connectors can have any properties you care to assign and any child tags you want, thus you can use them to represent pipes or transmission lines configured with all the characteristics you require.

Connectors are straight lines between two points. You can create a corner by adding a third site to your map, located between the first and second site, and configuring that intermediate site so that it is not displayed on the map. Add one connector between the first site and the intermediate site, then add a second connector between the intermediate site and the destination site.

Configuration Notes:

Site-related properties or Connector-related properties are most easily added by clicking the Add Site Parameters button in the Settings tab. After adding the properties you will find it easier to configure site or connector properties using the tools in the Site Display tab.

  • A Context tag can be a site or it can be a connector, but it cannot be both. If you click Add Site Properties, all connector-specific properties will be removed. If you click Add Connector Properties, all site-specific properties will be removed.
  • If adding a Type name, ensure that it will be unique to your application, and will not conflict with any existing type such as "Pump" etc. It is best to add a prefix or suffix that is unique to your organization or application. Type names are limited to a maximum of 31 characters.
  • When adding properties, ensure that names do not conflict with existing parameters such as "Name" or "Area". It is best to add a prefix or suffix to each property name that is unique to your organization or application.

Context (Site) Tags and Alarm Notification

Context tags (or custom types derived from a Context tag) may define custom alarm message templates, for use by all alarms occurring within the structure. This is done by adding the desired template name(s) to the Context's list of properties. To create a custom property value that will be dynamic and unique for each instance, use tokens. A token will be replaced by the meaning it represents. All non-token characters will be passed along as a string. (To pass a percent sign as part of a string you must type %%)

A custom template with a value of:

Check: %D%T - %A - %M

will output a message like:

"Check: [Date][Time] - [Area] - [Alarm description]"

You cannot pass an expression in the value field of a Context tag's custom property. To do this, you must create a custom tag type. See Alarm Notification Templates for more detailed instructions.

Related information:

Design Your Own Tags - Use your context tag as the basis for a new tag type.

Automated Tag Configuration - Use expressions in child tags so that they configure themselves based on the parent's configuration.

Create Widgets - Create new multi-part widgets for your multi-tag types.

Site Map - Mapping in general. Sub-topics relate to linking at tag, such as your context tag, to a map.

Sites & Maps

Alarm Message Templates - Control the content of alarm messages.

Best Practices for Tags

Closed Context properties ID tab

The Context Tag's ID tab contains an extra field named, "Type". If, after creating the context tag, you right-click on it in the tag browser and select "Create Type" you will create a new tag type, named after the contents of the Type field.

The name you provide for the type must be a single word and must not duplicate the name of any existing type of tag. An error dialog box will warn you if invalid characters are used, or if the name supplied cannot be used as the name of a new tag type.

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Context tag properties, Settings tab

Context tags may be given a list of named properties. Each copy of the tag may then be given its own unique values for those properties. There is no limit on the number of named properties that you may create.

Property names may not duplicate VTScada reserved words. To be safe, adopt a naming convention that adds a distinct identifier to every name (for example "MA_Name" for My Application...)

By defining properties in a context tag, you provide a method for children of that tag to adapt their configuration values to the parent instance via Parameter Expressions. For example, I/O addresses may be calculated from a BaseAddress value stored in the Context tag instance.

To create a new property click Add, which opens the Add Property dialog:

Property names must be unique, not just in the list of properties, but in the tag itself. VTScada properties such as Name, Area and Description may not be used. Attempting to do so will cause the "Name in Use" dialog to open.

Property names must include letters ("Property2" is valid, but "2" is not). The property name may not include a space or any of the following characters: ! , @ % ^ & * ( ) - ` ~ : ; " ' < > ? / { } [ ] | \ .

You can change any property name, value or comment by clicking on the field in the settings list. Editing is done in-place.

If you turn the context tag and its children into a new type using the Create New Type command in the tag browser, you can still edit the list of properties for the type definition as a whole. See: Modify a Custom Type.

Add Site Properties.

Connectors are not sites, and sites cannot be used as connectors.
Connectors do not have Latitude and Longitude properties. Sites do not have other start and end sites.
To create connectors, you must have both tags configured as sites and tags configured as connectors.

Click this button to add the five properties that relate to site maps, Latitude, Longitude, CustomDetailsPage, CustomMapIconParm and SiteListDisplay. After adding the properties it is easier to assign values for the properties using the Site Display tab. Connector-specific properties will be removed when you add site properties.

  • Values for all five can be set using the Site Display tab.
  • Latitude and Longitude are required if this context tag is to be added to a site map as a pin.
  • SiteListDisplay is necessary if you wish to control whether the tag behaves as a "site" or a "folder" in the Site List page, or should not be shown at all. In the Site List, a "site" will open to a Site Details page when clicked. A "folder" will open within the sites list to show sub-sites (if any) and immediate I/O child tags.
  • CustomDetailsPage is required only if you have or will create a custom page to display the child tags of this context tag. Otherwise, you may delete this property and use the standard Site Details page.
  • CustomMapIconParm is required only if you intend to create a custom pin to mark this Context tag on a Site Map. Otherwise, you may delete this property and use a standard pin.

Add Connector Properties

Connectors are not sites, and sites cannot be used as connectors.
Connectors do not have Latitude and Longitude properties. Sites do not have other start and end sites.
To create connectors, you must have both tags configured as sites and tags configured as connectors.

Click this button to add the five properties that relate to site maps, Latitude, Longitude, CustomDetailsPage, CustomMapIconParm and SiteListDisplay. After adding the properties it is easier to assign values for the properties using the Site Display tab. Connector-specific properties will be removed when you add site properties.

  • CustomDetailsPage is required only if you have or will create a custom page to display the child tags of this context tag. Otherwise, you may delete this property and use the standard Site Details page.
  • StartSite and EndSite are required for all connectors. These will be configured with the two tags that hold site properties to mark the latitude and longitude of the start and end of the connector line.
  • ConnectorColor defines the color of the line. By default the property is gray, defined using an Alpha value of FF and RGB values of E6E6E6. <FFE6E6E6> You may use any of the numeric values from the VTScada color palette instead.
  • ConnectorStyle defines the line type. The drop-down list of the available styles is easier to use than assigning numeric values, which match those provided in the list of VTScada line styles. Note that the line or pipe width cannot be configured as it will scale as the zoom-level changes.
  • ShowConnectorArrows defines which of the three possible arrows should be shown in the display. This is stored as a bit-wise value where bit 0 matches the arrow at the 1/4 position on the line, bit 1 matches the arrow at the half-way position and bit 2 matches the arrow at the 3/4 position. Arrows will always point from the start site towards the end site.
  • CustomMapIconParm is required only if you intend to create a custom widget to mark this Context tag on a Site Map. Otherwise, you may delete this property and use the standard Site Draw widget.
  • SiteListDisplay is necessary if you wish to control whether the tag behaves as a "site" or a "folder" in the Site List page, or should not be shown at all. In the Site List, a "site" will open to a Site Details page when clicked. A "folder" will open within the sites list to show sub-sites (if any) and immediate I/O child tags.

Filter Child Types in the Sites Page

As an example, your custom type might be a city. Within that city (and as child tags of this type) there might be lift stations and other custom types that qualify as sites for the purpose of this list.

When the city tag is viewed in the sites page, you will be able to expand the list to view all subordinate sites. But, you might want to restrict that list to only the lift stations.

You can filter the list of child sites by adding the parameter CustomSiteListFilterType to the parent type, and setting the value of that property to the type name that should be shown in the list. You could also specify the name of a group of types, such as "Station" to filter for tags such as the MultiSmart and MPE.

The filter affects only the immediate children of the tag where it is defined.

Context properties Site Display tab

Before using this page, you must add either site properties or connector properties in the Settings tab.

(Site Configuration)

Context tag - Display tab - Connector option

(Connector configuration)

There are two ways to prevent a site's location pin from being shown on a map: Leave the Latitude and Longitude values empty, or deselect the Show option for the map icon. If the site has latitude and longitude values, but the icon is not displayed, then the indicator beacon will pulse while the cursor is held over the site's coordinates on the map, even though the pin is not displayed.

Latitude and Longitude (Site configuration only)

Holds location coordinates for this tag, thereby allowing it to be represented on a Site Map page if the map icon is shown.

Start Site and End Site (Connector configuration only)

Holds links to the two site tags, between which the connector will be drawn.

Custom Details Page

If a parameterized page (Parameterized Pages) was for this type of tag(*), that page can be selected here. If you did not create a parameterized page for this tag type, then operators will see the standard Site Details page upon clicking the pin for this tag in a Site Map.

The page tool for this field will open the Select Page dialog. Ensure that the filter within that dialog is set to Site Pages. (Select Page dialog)

(*) This feature works best after you turn your Context tag into a new type. Otherwise, your parameterized page would need to accept any Context tag as its parameter.

Map Icon

You might choose to define a location for this site, but not display it on a map. This is sometimes done to add corners for connector lines or pipes.

If a custom map icon widget has been defined, you can select it here. That icon will then be used instead of the standard icon when this tag is represented on a Site Map page. If there is no custom map icon, then the standard widget will be used. A custom map icon is any tag-widget that can be linked to this tag type.

Site List Display

Assuming that this tag has site properties, it will be included in the list of a Sites page. What will happen when an operator clicks on this tag in that list depends on the Site List display choice, and on whether any of this tag's children are I/O tags. Note that the following applies only to the list section of the Sites page, not to the map.

  • Display as Site: A click will open the Site Details page as a pop-up.
  • Display as Folder: A click will leave focus on the Sites page, but the list will now show the child tags of this site.
  • Exclude from Site List: This tag should not be shown in the list section of the Sites page.
  • Only Display Child Tags: This tag is used to group other sites. Those sites should be displayed, but this one should not be displayed. Operators will not need to navigate through this site to reach the child sites.
  • Automatic: If this tag contains child sites, folder display will be used. Otherwise, site display will be used.

Connector Style and Color (Connector configuration only)

Choose whether to display the connector as a pipe or as a line using any of the built-in VTScada line styles. The default color will be gray. Use the color option to select any other color.

Map Zoom Level (Site configuration only)

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Directional Arrows (Connector configuration only)

Up to three arrows can be drawn on the connector, pointing from the first site to the second. These can be added at the 1/4, 1/2 and 3/4 positions of the visible segment of the connector.

Closed Context Tag Widgets

The following widgets are available to display information about your application’s Context tags. Some may not be useful unless your Context tag has been configure to have Latitude and Longitude parameters, or to be a parent to a Polling driver or station tag.

There are no widgets for Connectors.

Alarm Priority Box

Alarm Priority Icon

Alarm List

Draw HDV Widget

Site Alarm List

Site Details Widget

Site Icon Widget

Site Summary Widget

Tag List Widget


Font Tags

Not counted towards your tag license limit.

Font tags contain style settings (including font file selection) that are used throughout your application. This is the only tag type that does not have a numeric value, having instead a VTScada font type.

Several font tags are standard on every installation of VTScada, and you may create your own. The standard fonts are illustrated here:

As a general guideline, if you need fonts that differ in appearance from those that are built-in, you should create new Font Style tags rather than modifying the existing set. Built-in font style tags are used by certain VTScada user interface elements, which may be adversely affected by a significant change in font characteristics.

Font tags appear in the text format ribbon as Saved Fonts.

Related information:

Best Practices for Tags

Closed Font Style properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Font Style properties Settings tab

The Settings tab shows the current property settings, and can be used to change those settings. The majority of the font characteristic setting are accessed by clicking the Change button to open the Font dialog, as illustrated. In addition to the properties set there, you can add the properties, Underline and Fixed Pitch.

Underline

Select this option to underline all text created using this style tag.

Fixed Pitch

In the unusual event that the font you select is not available on the computer where the application is later installed, and that font comes in both fixed and non-fixed pitch versions, then selecting this option will cause the search for an alternative font to be restricted to only fixed-pitch options.

Change

The Change button opens a Font dialog that enables you to configure the property settings (font, style, and size) for the selected Font Style tag.


IP Network Listener Tags

Not counted towards your tag license limit.

Add IP Network Listener tags to your application if you want to be able to accept inbound TCP or (rarely) UDP connections. This tag is for use with the DNP3 and Modbus Compatible Devices, but may also be used by custom drivers.

In addition to use with drivers, an IP Network Listener can also be used with services, such as the SNMP Agent.

The IP Network Listener may be useful for enhanced security when you are employing a Modbus Compatible driver configured for virtual I/O. This will allow you to limit the traffic to or from the driver to approved addresses. Note that when used in this situation, the TCP/IP tag to which the driver is attached must be configured for address 127.0.0.1 and not a blank address, as is common. This will prevent conflicts on the common port.

The IP Network Listener will not be required in most situations. It may be useful if your TCP connections will close between polling intervals and you need to allow the RTU to connect to the driver before the next cycle, perhaps to report a fault condition. It is required by the SNMP Agent in order to provide access to the system. Otherwise, use with caution.
Note that most support calls involving the IP Network Listener tag are solved by determining that the tag was unnecessary and removing it.

While this tag will work with both TCP and UDP, it is intended primarily for TCP connections. Drivers using the UDP protocol may not need a Network Listener unless the RTU is connecting to VTScada using a different IP address each time. If using an IP Network Listener tag with a UDP connection, use care to ensure the port number is set correctly and is compatible with the corresponding UDP/IP port tag configuration.

The IP Network Listener uses a socket server to accept incoming connections. Improper configuration can result in communications failure for UDP/IP Port tags that make use of the same local port number. Refer to UDP/IP Port Tags for more information and further warnings.

Use of an IP Network Listener Tag is generally not recommended for UDP/IP communications. The VTScada engine will listen for UDP/IP datagram packets and place them into existing UDP streams if the remote IP address matches that of the UDP stream.

Multiple Modbus and DNP3 driver tags can share the same IP Network Listener.

Related information:

Modbus Compatible Device: Communications tab - Modbus Compatible Device configuration

DNP3 Driver properties Communications tab - DNP3 driver configuration

SNMP Agent Configuration - Details for enabling an SNMP client to connect and access tag data.

Best Practices for Tags

Closed IP Network Listener properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

IP Network Listener properties Options tab

IP Network Listener tag options

Enable

Accepts a 1 to enable or a 0 to disable inbound connections. The options Expression or Tag allow you to enable or disable connections based on user control of your choice, or based on current operating conditions. Set to 1 (online) by default for all workstations.

Protocol

Select either TCP/IP and UDP/IP, as appropriate for the device your drivers will be communicating with.

Port Number

Define the port that be used for inbound connections. Ensure that your firewall has been configured to allow connections to this port.

Remote Port Number

Enabled only for UDP/IP. UDP responses from VTScada will be sent to this port number. Leave this option Invalid to send responses back to the source port on the RTU.

Review the warnings in the introduction of the UDP/IP Port tag description.

IP Allow List

Optional. As a security measure, this listener may be configured to accept connections only from the IP addresses you add to this list. A range of allowed addresses may be defined by leaving portions empty.

Support is provided for CIDR Closed Classless Inter-Domain Routing ranges. For example, 192.168.1.0/24 or 192.0.0.0/8

Discriminator Options - Idle Time and Sample Limit

These two values control how incoming data is sampled. Sample Limit specifies the number of bytes to be received before the stream is sampled. In the event that the stream is not changing, the passage of Idle Time seconds will trigger a sample. The default values were selected to work in most cases, but you may find that Sample Limit need only be set to 10 bytes when this tag is used by a DNP3 driver.

Closed IP Network Listener Tag Widgets

The following widgets are available to display information about your application’s IP Network Listener tags:

Comm Indicator Widget


Menu Item Tags

Not counted towards your tag license limit.

Menu Item tags are used to represent page menu items and drawing tools within the various palettes. Folders and dividers within menus and palettes are also stored in Menu Item tags.

These tags do not have an ID tab. The configuration panel will vary according to the type of menu item that you are creating or editing.

Menu Item tags can have start conditions, like any other tag. Because there is no ID panel, start conditions are added by right-clicking on the tag in the Tag Browser and selecting "Start condition" from the context menu. But note that start tag expressions are always optimized to run only at start-up. In a Menu Item tag your expression cannot be re-evaluated after the application starts.

Related information:

Add New Menu Items

Best Practices for Tags


Realm Display Setup Tags

Not counted towards your tag license limit.

The usage of the Realm Display Setup tag is described in the VTScada Thin Client Server chapter. It exists only to hold configuration settings that set the level of control granted to operators connecting to an application from a VTScada Internet Client (VIC). There are no widgets, no log-enabled variables and no group memberships.

Realm Display Setup tags do not apply to mobile device connections.

Related information:

Internet Realm

Best Practices for Tags

Closed Realm Display Setup: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Realm Display Setup Tag: Settings tab

The settings tab controls the overall display options. The first drop-down selector is where you choose which realm the settings will apply to. Only realms that include the current application will be available in the list.

You also have the option of making the settings apply to all realms that include this application, rather than just one at a time. To decide whether to use that option, you must choose whether you want to provide different settings to different VIC stations - which would be done via different realms. Changes to this tag take effect immediately. There is no need to restart the application after adding or changing a Realm Display Setup tag.

You can add exactly one Realm Display Setup tag for each realm that includes the application.

Fixed Size Window, Resizable Window or Full Screen

Running full screen implies that the window width and height will be whatever the full (maximum) screen size is.

The full screen option does not apply to Anywhere Client connections.

When a VIC is running in full screen, the Windows title bar and other window borders will not be displayed.

If Fixed Size Window is selected, you gain more control over the VIC window at the server side, while not allowing size control at the VIC. You will be able to set the VIC window size and page style options at the server with this option selected.

The operator will still be able to move the window around on his screen, and will be able to minimize and restore it, provided that the Disable Min/Max Buttons option has not been selected.

Note that if the specified Fixed Size is larger than the resolution of the computer running the client session, scroll bars will appear on the display.

By selecting Resizable Window, you provide the client with the greatest level of control. Operators will be able to re-size their screen at will, limited only by the optional minimum width and height that you may set in this dialog box.

Your choice of display option will affect which of the remaining controls on the screen are available. The description of each of those controls will tell you which window options it is relevant for.

Note that leaving the initial Window Width and Height blank (if available) will result in the VIC taking the maximum screen area as its initial size upon opening.

Initial Window Width and Height Fields

If you have selected Fixed Size Window above, these controls set the window width and height for the client. If you have selected Resizable Window, then these controls set only the initial window size for the first time the application is opened on the client. On subsequent startups, the resizable window will remain at whatever dimensions the operator set.

If Full Screen has not been selected and these two values are also not set, the following configuration options (if set) will be used to determine a default size:

If BrowserWidth and BrowserHeight are defined in the application properties, these values will be used. Otherwise, if DispMgrWidth and DispMgrHeight are set in the application properties, those values will be used. Otherwise, the default width and height will simply fill the screen.

These settings are maintained by the client and so (for a re-sizable application) apply only for the first time the client is opened.

Horizontal Instances / Vertical Instances

Applies only to the VIC. Does not apply to Mobile Clients or VTScada Anywhere Clients.

Create multiple instances of the VTScada screen, each of which can be positioned on its own monitor. The result is similar to the effect of DispMgrHoriz and DispMgrVert on desktop installations.

A multi-monitor VIC is restricted in its behavior to full screen without borders, and DispMgrExtendedDesktop = 1 or equivalent. All monitors must be the same size and resolution, and must be arranged with the primary display in the top left corner.

Minimum Window Width and Height Fields

Sets the minimum width and height that the client is able to resize to. Defaults to 25 pixels.

If these values are not set for a resizable client, then the application will check the configuration file to see whether DispMgrMinWidth and DispMgrMinHeight have been set and if so, will use those. Otherwise, no minimum values will be set.

Disable Min/Max Buttons

This option is not available if Full Screen option is selected. Does exactly what it says to the Min/Max buttons at the top right of the client's screen.

Constrain Aspect Ratio

Available only if the Resizable Window option is selected. Forces the VIC screen to maintain a constant aspect ratio (width to height) while it is being re-sized.

Realm Display Setup Tag: Page Style tab

The Page Style tab includes settings that apply to VIC sessions that display in Full Screen Mode (as set on the Settings tab). This is a list of which elements of both the Title Bar and the Task Bar you wish to make visible.

Elements of the Title Bar and Task Bar:

Title Bar Style:

Provides a series of yes-or-no check boxes controlling which parts of the title bar should be displayed on the VIC including whether the title bar should be displayed at all.

Task Bar Style:

Provides a series of yes-or-no check boxes controlling which parts of the task bar should be displayed on the VIC including whether the task bar should be displayed at all.

Realm Display Setup Tag: Windowed Page Style tab

The Windowed Page Style tab includes settings that apply to pages that display as windows - whether Fixed Size or Resizable, as selected in the Settings tab. The bar items are the same as for the previous tab.

Title Bar Style:

Provides a series of yes-or-no check boxes controlling which parts of the title bar should be displayed on the VIC including whether the title bar should be displayed at all. An image to refresh your memory of the various parts of the screen is included with the previous topic, Page Style tab.

Task Bar Style:

Provides a series of yes-or-no check boxes controlling which parts of the task bar should be displayed on the VIC including whether the task bar should be displayed at all.

Realm Display Setup Tag: Startup Page tab

First page at startup

Provides you with control over which page will open first for users connecting to the realm associated with this tag. You may select the application's default startup page (as configured in the Display tab of the Application Configuration dialog), the last page viewed (for that user), or you may select any page within the application to use as the start page.

Realm Display Setup Tag: Misc Page tab

Specify slippy map settings and On Screen Numeric Keypad settings.

Map Restrictions

Control how much or little of an area an operator may view. 2, being the furthest zoom level allows an operator to view the entire globe. Typically, a closer view is adequate.

You may also enable Area Limiting, as described in Limit the Map Area.

On Screen Numeric Keypad

Enable Use the On Screen Numeric Keypad to display a numeric-only keypad for any edit field that is of type numeric in pages or in configuratioin menus. Adjust the size of the numeric keypad or enable nighttime mode. See Touchscreens

Available Widgets

Realm Display Setup tags work without being drawn.


Style Settings Tags

Not counted towards your tag license limit.

Style Settings tags provide a single point of configuration for many display characteristics, helping to ensure that your pages have a consistent visual style. For example, your industry may specify that a digital value in state 0 (off) should be shown in red, and state 1 (green) should be shown in green. In other industries, the opposite is true, or shades of gray might be used. For widgets that obey the Style Settings value, you need only set your preferences once, and all displays will use a consistent format.

Not all widgets recognize or use the Style Settings tag.

Style Settings tags can be opened from the Tag Browser and also, many widgets and most tags can be configured to use a Style Settings tag and have a direct link (see following image). In the event that both a widget and the tag linked to it are configured with different Style Settings tags, the configuration of the widget takes precedence over the configuration of the linked tag.

"System Style" is the default, included with every copy of VTScada

Many widgets have a similar configuration. Note that this is not available in all widgets.

Style Settings choice in a widget. "No tag selected" means "whatever the I/O tag uses".

One default Style Settings tag, "System Style", is included in every new VTScada application. It will be used by every style-aware tag that has not been configured to use an alternative selection, including no Style Settings tag.

For Digital and Discrete I/O tags, use the following guide:

* If the linked tag has an Equipment Type and the Style has a definition for that type, then those colors and labels are used.
* Otherwise (at least for Digitals), the colors for the data type are used.

Troubleshooting:

  • This object that I've drawn doesn't change with a style setting.
    Does the tag have an Equipment Type? Equipment overrides basic tag type. for example a plain digital I/O will use the style defined under the Digitals tab, but the same I/O with an Equipment Type of Pump will use the style defined under the Equipment tab.
  • I don't see how to link this object to a style setting.

Style Settings are used only by certain widgets. They cannot be used with text, pipes, images, shapes or with widgets that aren't designed to use a Style Setting. It is possible to animate any property of any object, using an expression or a linked tag's value, but that is not the same as using a Style Setting tag.

Every widget's description states whether it can be used with a Style Setting. Also, widgets that can use a Style Setting are marked with a star in the table of contents.

Related information:

Best Practices for Tags

Style Settings properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Style Settings properties Analogs tab

If your I/O tag has an Equipment type, configure the style using the Equipment tab rather than this tab.

Fields in the Analogs tab of this tag are used to set colors and labels for LCD widgets.

Lit LCD Segment

When an LED indicator widget is used for a numeric display, the lit portion will have this color.

Unlit LCD Segment

When an LED indicator widget is used for a numeric display, the unlit portion will have this color, typically using an opacity value less than one.

Style Settings properties Digitals tab

If your I/O tag has an Equipment type, configure the style using the Equipment tab rather than this tab.

The Digitals tab of this tag sets color and text for equipment / status widgets, indicator-lights and other style-aware widgets for digital tags.

The text parameter is used only by widgets that recognize the Style tag and that include text.

Value == 0

Set the text and color of the text, displayed when the associated tag is in the zero state.

Value == 1

Set the text and color of the text, displayed when the associated tag is in state one.

Value == 2 and Value == 3

For digital tags that use two address fields, and therefore can display up to four states, this label and color will be displayed when the associated tag is in state two.

Style Settings properties Exceptions tab

Exceptions refer to alarm states, as displayed by those widgets that have alarm indication features. Note that these do not reflect the priority of the alarm.

The exception indicator will vanish when the alarm normalizes, even if that alarm has not been acknowledged. You can change this behavior by changing the property "AlarmWidgetsShowUnackedNormalAlarm" in the application's properties, setting the value to 1. (This property affects most widgets that indicate alarms using the Style Settings properties, with the exception of the Alarm Priority Indicator, Alarm Priority Box, and high performance graphics widgets.)

Active Alarm

Set the text and color of the text, displayed when the associated tag has an active alarm.

Unacknowledged Alarm

Set the text and color of the text, displayed when the associated tag has an unacknowledged alarm.

Bad Quality

Custom programming, using the VTScada scripting language, must be done to make use of the Quality field of a tag. If the associated tag is using the Quality field, the associated widget will use the label and color set in this field to indicate a bad quality value.

Mismatch

For output tags, if the feedback value for the associated tag does not match its current value, or value last written, this text and color will be displayed on the associated widget.

Invalid

Set the text and color of the text, displayed when the associated tag is in an invalid state. Invalid states usually indicate a break in communications, whether due to faulty configuration or communication.

Style Settings properties Errors tab

The label parameter is not used by any VTScada widgets in this version.

The value property of tags in the ports group, drivers group, the Modem tag and the SMS Appliance tag, will indicate whether that tag is in an error state. When drawn using a Status Color Indicator or Indicator Light widget, the tag's value, which indicates the error state, will be shown using the colors and labels configured here rather than the colors defined in the digitals tab.

No Error

Color to be used when the linked tag is not in an error condition.

Error

Color to be used when the linked tag is in an error condition.

Style Settings Properties: High Performance tab

Properties set here control colors used in high performance HMI graphics such as the Spider Plot widget and HP Analog Bar.

The Default Equipment Status colors (Off and On) can be used by Equipment / Status Color indicators. If enabled within the widget, these colors will be used instead of the On / Off colors for the linked digital I/O tag.

For Equipment / Status Color widgets, when the High Performance option is selected, alarm (exception) colors are NOT shown. Use an Alarm Indicator widget instead.

Style Settings properties: Equipment tab

Used by I/O and Calculation tags that have been assigned an equipment type. Typically, those tags should be Digitals or Enumerated types, which have well-defined values that you can map to style settings. Analog ranges cannot be mapped to individual style settings.

To define a label for Invalid, use the Exceptions tab. This will be used by all tags / widgets and cannot differ by equipment type.

You are free to create as many equipment types as you need, and you may do so from within either an I/O tag on the ID tab or a Style Settings tag on the Equipment tab. The instructions are the same in both cases:

  1. Place the cursor in the Equipment Type field.
    (It does not matter whether the field is blank or shows an existing type.)
  2. Type the name of your new equipment type.
  3. Press the [tab] or [Enter] key on the keyboard.
  4. Click the Apply button.
    The new type is saved.
    If the field had shown an existing type before you started, it is not changed.

You can match properties of label, color and flash to any value that the tag may have. Refer to the following screen capture of the default configuration for a Pump type. A value of 0 in the tag maps to the label "Stopped" and the color gray. A value of 1 in the tag maps to the label "Running" and the color green.

If the tag has a value that is not included in the list, nothing is shown in the widget.

Use the tools along the right side (plus, minus, pencil, import) to add, remove, or edit entries in the list. The last tool in the list, import, gives you the ability to import entries from a comma-separated value (CSV) file. (See instructions later in this topic.)

After selecting or creating an equipment type, create settings for the possible states by clicking the Add button [image]. This will open the Add Value dialog. If you attempt to define the same value twice for a given equipment type, you will be warned to choose another. You will not be warned if you leave a value out of a series, therefore it is best to enter values in order from lowest to highest. Values may be numeric or text.

Note that the default color is transparent.

CSV Import

When there are many possible values or states, you can automate the process of populating the equipment definition by importing labels and values from a comma-separated value (CSV) file. The file must be in the form:

Value,Label,Color,Flash

Where:

  • Value may be any value, numeric or text.
    Any existing entries with the same value will be over-written.
  • Label is text and may by any label.
  • Color is optional and may be either a number from the VTScada color palette, or an hexadecimal value in the form <aaRRGGBB>. If not provided, the default is black.
  • Flash is optional, defaulting to "no flash". If provided, this must be a 1 specifying On, or a 0 specifying Off.

Use

If the equipment type is used for an input tag, the label for each matching value can be displayed by using an I/O Multi-Text widget.

If for an output tag, then the values and matching labels can be used to configure the selections available in a Droplist Widget.


Subordinate Application Tags

Not counted towards your tag license limit.

Provides monitoring and access to all tags in a selected subordinate application. The application holding the Subordinate Application tag is referred to as a Master application.

All the tags in the selected subordinate application will be visible as children of the Subordinate Application tag, so long as all user-defined types defined in the subordinate application are also defined in the master application. If the master application and subordinate application are not built on the same layer where that custom type is defined, then you must copy the definition from the subordinate application to the master application.

A master application can have several subordinate application tags, but each must link to a separate application. If two link to the same application, only one will function at a time.

You must have a security account with the Manager privilege in the subordinate application before you can configure a subordinate application tag to link to that application. You will be prompted for a username and password.

Security Management for Subordinate Applications

It may be convenient for a user to have a single sign-in account that can be used across applications. The only practical way to bundle security access to multiple applications within a single account is to use Windows Security Integration with all the relevant applications.

Active Directory accounts are independent of your applications. They gain access to your applications through AD Security Groups, which map to roles within the applications for which you have enabled Windows Security Integration (WSI). By associating a Windows AD account with the AD Security Groups for several applications, you achieve your goal of creating a single account with access to multiple applications.

For example, consider three applications, A, B and C. They all have a common role Operator and each has a unique role, Role-A, Role-B and Role-C respectively. Assume that all three apps use a common ADGroupPrefix of "VTScada". The AD account will be a member of four AD Groups; VTScada-Operator, VTScada-Role-A, VTScada-Role-B and VTScada-Role-C. The AD account, when used in each app will be assigned two roles, the common Operator and the appropriate Role-X.

You may wish to differentiate the Operator role between the three applications. Do so either by setting a different ADGroupPrefix for each application (the preferred solution) or by creating unique names for roles within each application.

For more information, refer to the Windows Security Integration topics, starting with Running Multiple Applications with WSI.

Do not use the "Shared Security" feature of the Administrative dialog. Windows Security Integration is a better solution. If you attempt to select a subordinate application that uses shared security, a warning message will be displayed.

Note to advanced developers: If writing an expression that involves a subordinate application, the value of a SubordinateApplication tag is TRUE when the subordinate application is running and synchronized with the master application, and FALSE when it is not.

Subordinate Application tags are excluded from tag exports.

Related information:

Master & Subordinate Applications - A full description of master and subordinate applications.

Copy Types to Other Applications - Ensure that types defined in the subordinate are available in the master.

Best Practices for Tags

Closed Subordinate Application tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Subordinate Application tag properties: Settings Tab

The Settings tab holds a drop-down list, from which you can select the subordinate application.

Authentication to an account possessing the Manager privilege is required if the subordinate application is secured. Trihedral strongly recommends that all applications be secured.

Immediately upon selecting the subordinate application, you will be prompted to authenticate with that application.

Enter the user name and password for an account in the subordinate application that possesses the Manager privilege.

Closed Subordinate Application Tag Widgets

The following widgets are available to display information about your application’s Subordinate Application tags.

Alarms in the subordinate application will not propagate to the master application's site icon widgets.

Alarm Priority Box

Alarm Priority Icon

Alarm List

Draw HDV Widget

Site Alarm List

Site Details Widget

Site Icon Widget

Site Summary Widget

Tag List Widget


Legacy Tags

These are tags that are older and hence the name. Legacy tags will always be supported but these tags are largely replaced by I/O & Calculation tags because the latter is generally faster and more efficient and makes better use of the system resources.

Use these legacy tags only if you are certain that they contain unique features that are absolutely necessary for your work.


Analog Input Tags

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

Counted towards your tag license limit.

The role of Analog Input tags is to represent incoming analog data values from equipment processes, and provide widgets to display the data in numeric or graphic form as a bar, gauge, or number.

Analogs can have text values if the driver returns a text value and if all four of the scaling values are set equal. Standard practice is to set all four scale values to 1.

Related information:

Best Practices for Tags

Closed Analog Input properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Analog Input properties I/O tab

The I/O tab contains the properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU). This is done by specifying the driver tag that communicates with the physical I/O device, the address at the physical I/O device from which this tag is to read its data, and the rate at which the I/O device should be scanned for data.

If supported by the communication driver, the Analog Input tag may also be used to write data.

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Address

Provide the address within the I/O device from which this tag is to read data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

If a Write Address is provided the Read Address is used only as feedback and will set the value of the tag regardless of the value written. If the value in the Read Address does not match the value written then the tag's Mismatch flag is set to true and will be reflected in linked widgets, either as a blink or a mismatch color, according to the widget.

Address Assist: (...)

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the Address Assist dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your Communication Driver Tags for more information.

Scan Interval

Provide the frequency, measured in seconds, that the I/O device should be scanned for new data. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data.

Engineering Units

Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc.

You can add a degree symbol to the engineering units by holding down the Alt-key while typing 0176 on the numeric keypad. Release the Alt-key before typing the C or F.

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

Enable Output

If selected, this input tag may also be used to write data to the specified address of the communication driver. A Security Privilege may be set in the Merit tab to restrict access to this feature.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Analog Input properties Scaling tab

The Scaling tab requires values that will be used to convert unscaled, raw data from the I/O device associated with this tag into scaled data that will be reported to operators. VTScada uses an algorithm to calculate this tag's value internally, based on the known unscaled and scaled values you supply.

The default value for each of these fields is stored in an application property. You are advised to change those properties to match the values used by your hardware by using the Edit Properties page of the Application Configuration dialog. You will need to use the Advanced mode of the properties page. The properties to copy and edit are:

  • AnalogUnscaledMinDefault
  • AnalogUnscaledMaxDefault
  • AnalogScaledMinDefault
  • AnalogScaledMaxDefault

Scaling tab for any tag configuration

I/O scaling illustrated

VTScada assumes a linear relationship between the values as shown. The scaled and unscaled process values you provide set the slope of the line, allowing any value on one axis to be mapped to the other.

The values do not limit what the tag can read, but the Scaled Process Min and Max values do limit what the tag can write.

Min and Max Unscaled Process Data (Required.)

Use these to tell VTScada the range of raw values to expect from or write to hardware.

Min and Max Scaled Process Data (Required.)

These values must match the Unscaled Min and Max values. VTScada uses them to convert between the engineering units shown in the SCADA system and the raw values read from or written to the hardware. By default, the "Limit outputs to within Scaled min/max" option is selected. If you deselect this option, the output range limit is disabled. This allows any value, including negative integers, to be sent to the tag. However, scaling is still applied to the new output value, regardless of the value sent to the tag.

Analogs can read text values if those are returned by the driver. Set the first four of the scaling parameters to "1" in order for the tag to interpret data as text.
Better is to use the String I/O tag for reading text data to avoid problems when attempting to mix text and numbers. A text "2" sent to an Analog Input with scaling set to 1 will be scaled to 1.

Analog Input properties Owner tab

This tag can be used in an owner/contributor structure where multiple contributor tags can supply their values to an owner tag.

There is no specific "owner" tag type, rather an owner tag is typically a custom-designed tag that is created using VTScada scripting code.

Analog Input tag - Owner tab

Owner

Specify a tag to which this contributor should supply its data. An owner tag is one which you must design and then create, using the VTScada scripting language.

The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual data value, to questionable data, according to the configuration of the check boxes appearing beneath the Owner field. These check boxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value check box is used to set the value of this contributor tag as the nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack. Priority check box causes the owner tag to keep track of the priority of the contributor's active alarm (or records an Invalid if the contributor is not in an alarm state). Selecting the Set Active/Unack. Priority check box also causes the owner tag to record whether the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values), rather than reading data from their I/O device. When selected, the Record Use of Manual Data check box is used to increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality (Analog and Digital Input only)

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag Quality check box is used to increment the owner tag's count of the number of tags that are contributing quality data by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the Record Tag Validity check box is used to increment the owner tag's count of the number of tags that are contributing questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Analog Input properties Merit tab

Quality Based on

The Quality Based On field is for use when this tag is to be a contributor to a custom-built container tag. Please see the topic Merit tab and Quality tab for details.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Analog Input properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Analog Input properties Alarm tab

Analog Input tag - Alarm tab

If you want this tag to trigger an alarm, use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Analog Input properties Script tab

Analog Input tag - script tab

Optionally, link one or more Script tags to this tag. A Script tag provides a means of creating a procedure, using VTScada’s programming language, that will run whenever this tag’s value changes.

Analog Input properties Logger tab

Analog Input tag - logger tab

Analog Input tags do not have a built-in connection to an Historian and therefore must be linked to a Logger tag if data is to be stored. The Logger tag works with an attached Historian to record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be created as a child of the current tag.

Only one Logger tag can be directly associated with a single input or output tag.

Closed Analog Input Tag Widgets

The following widgets are available to display information about your application’s Analog Input tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Analog Bar & Indicator Widget |
Color Blink Widget | Color Box Widget
Color Fill Widget | Color Line Widget
Compass 1 Widget | Compass 2 Widget
Draw Text Widget | Droplist Widget
LCD Bar Widget | Image Change Widget
Left Bar Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Glass Gauge Widget | Classic Gauge Widget
Retro Gauge Widget | Cockpit Gauge Widget
Aqua Gauge Widget | Army Gauge Widget
Backlit Gauge Widget | Nautical Gauge Widget
Quarter Arc Gauge Widget | Linear Gauge Widget
Antique Gauge Widget | LCD Ring Widget
LCD Arc Widget | LCD Meter Widget
Momentary Button Widget | Multi-Color Widget
Multi-Text Widget | Numeric Entry Widget
Numeric Value Widget | Plot Data Widget
Right Bar Widget | Set Analog Value Widget
Legacy Set Value Button Widget | Legacy Set Value Hotbox Widget
Slider Widget | Text Change Widget
Top Bar Widget | Two Color Bar Widget
Rotary Control Widget (Knob) | Indicator Light Widget
Equipment / Status Color Indicator | LCD 7 Segment Widget
LCD 5x7 Matrix Widget | Sparklines Widget

Related information:

Comparison of Analog Input Versus Analog Status Types


Analog Control Tags

Counted towards your tag license limit.

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

Analog Control tags are used to write values to equipment. While an Analog Status tag can also write a value, the Analog Control tag will give you more tools and options.

Unlike a Digital Control tag, the value of an Analog Control will reflect the last value written. It will also retain that value across application restarts, which is something that a Digital Control tag does not do. But, this value can be misleading if there are alternative means of control such as PLC programming or direct operation of equipment. If possible, it's always worthwhile to have an Analog Status tag that reads the actual state of the equipment being controlled and use that to provide feedback to the Analog Control for display purposes. In all but the most rare circumstances, this feedback should be used only to update the displayed value of the Analog Control.

Analog Control tags need a scaling factor for exactly the same reason as an Analog Status tag. With regard to scaling, they differ in only two ways: there is no option to set a display scaling and there is no deadband.

Related information:

Best Practices for Tags

Retained or Persisted values

Analog Control and Analog Output tags will both retain their last written value across application restarts. Use these tags when there is a need for a value to persist.

String I/O tags with output enabled, and with no driver ("No tag selected" rather than the default, "[*Driver] None found") will retain their last written value across application restarts.

The Digital Control and Digital Output tags do not have a similar feature, but an analog tag can be used in their place, writing a zero or a one. If the intent is to write a clear zero or one with an analog tag, both the scaled and unscaled range should be adjusted for a minimum value of zero and a maximum value of one, so that scaling does not adjust the values.

Record Operator-Entered Values:

While the output tags are designed to write to a device, they can also be used to record purely operator-entered values. For example, an operator may be asked to read a value from a device that is not connected to the automation system and record that value in a place where it can be included in the SCADA system's reports.

To record operator-entered values:

  1. Create an Analog Control tag.
    The name and description should match the information that is to be recorded.
    Do not configure an I/O device or address.
    Ensure that the scaled minimum and maximum values allow the full range of expected numeric values. (The Operator Notes page exists to record text.)
  2. Add a Logger tag to the Analog Control.
    Select the option, Log on Change as well as Time.
    Set the Log Range Interval to a very large value (for example, 3153600000 == 100 years). This ensures that a value will be written to the Historian only upon operator entry.
  3. Draw the Analog Control tag on a page as a Numeric Entry widget, having a relevant label. Operators should note that it is necessary to press enter, or tab away from the data entry field before the value will be saved.

Each time the operator enters a new value, it will be written to the Historian, and may be used in trend graphs and reports. Note that a click on any widget linked to an output tag does not open the trend window.

Closed Analog Control tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Analog Control properties I/O tab

In the I/O tab, you will find the properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU), or to the polling driver responsible for determining the order and rate at which data polls will occur.

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Address

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Engineering Units

Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc

Data Source

[Optional] While Analog Control tags usually take their value from an operator-controlled drawing object, the Data Source field provides the option of configuring this tag to accept a value from another tag or expression instead.

The value from the Data Source can be written to the I/O device, or it can be used to simply update the widget display.

If you have selected a data source that is configured to write output and have also drawn the tag as an object that operators can use to set values, then both can write to the I/O device. The value written will be whichever was most recently changed.

Write output when Data Source changes

When selected, the value supplied by the data source tag or expression will be written to the I/O device and will also be used to set this tag’s value. Selecting this option automatically deselects the "Use Data Source for display only" option.

Use Data Source for display only

When selected, the value supplied by the data source tag or expression will not be written to the I/O device but will be used to set this tag’s value. Selecting this option automatically deselects the "Write output when Data Source changes" option.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Analog Control properties Scaling tab

The Scaling tab is used to convert scaled data (intelligible to operators) into unscaled, raw data for the I/O device. VTScada uses an algorithm to calculate this tag's value internally, based on the known unscaled and scaled values you supply.

The default value for each of these fields is stored in an application property. You are advised to change those properties to match the values used by your hardware by using the Edit Properties page of the Application Configuration dialog.

You will need to use the Advanced mode of the properties page. The properties to copy and edit are:

  • AnalogUnscaledMinDefault
  • AnalogUnscaledMaxDefault
  • AnalogScaledMinDefault
  • AnalogScaledMaxDefault

I/O scaling illustrated

VTScada assumes a linear relationship between the values as shown. The scaled and unscaled process values you provide set the slope of the line, allowing any value on one axis to be mapped to the other.

The values do not limit what the tag can read, but the Scaled Process Min and Max values do limit what the tag can write.

Min and Max Unscaled Process Data (Required.)

Use these to tell VTScada the range of raw values to expect from or write to hardware.

Min and Max Scaled Process Data (Required.)

These values must match the Unscaled Min and Max values. VTScada uses them to convert between the engineering units shown in the SCADA system and the raw values read from or written to the hardware. By default, the "Limit outputs to within Scaled min/max" option is selected. If you deselect this option, the output range limit is disabled. This allows any value, including negative integers, to be sent to the tag. However, scaling is still applied to the new output value, regardless of the value sent to the tag.

Analog Control properties Merit tab

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Analog Control properties Display tab

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Display Order

Used to specify the placement of this tag when viewed in an associated station dialog. See Order tab for further details.

Closed Analog Control Tag Widgets

The following widgets are available to Analog Control tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Blink Widget | Color Box Widget
Color Fill Widget | Comm Line Widget
Compass 1 Widget | Compass 2 Widget
Draw Text Widget | Droplist Widget
 | Image Change Widget
Left Bar Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Momentary Button Widget | Multi-Color Widget
Multi-Text Widget | Numeric Entry Widget
Numeric Value Widget | Plot Data Widget
Right Bar Widget | Set Analog Value Widget
Legacy Set Value Button Widget | Legacy Set Value Hotbox Widget
Slider Widget | Text Change Widget
Top Bar Widget | Two Color Bar Widget
Rotary Control Widget (Knob) | Equipment / Status Color Indicator
Indicator Light Widget | LCD 5x7 Matrix Widget
LCD 7 Segment Widget |
Sparklines Widget |

Related information:

Confirmation Prompts for Output Tags - Control options for confirmation prompt text.


Analog Output Tags

Counted towards your tag license limit.

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

It is the role of analog outputs to take analog data from the user or from another tag, and write it to an I/O device. Analog data can be transmitted by an operator via a slider or a numeric entry field.

In most situations, use Analog Control Tags rather than Analog Output tags.

Related information:

Best Practices for Tags

Retained or Persisted values

Analog Control and Analog Output tags will both retain their last written value across application restarts. Use these tags when there is a need for a value to persist.

String I/O tags with output enabled, and with no driver ("No tag selected" rather than the default, "[*Driver] None found") will retain their last written value across application restarts.

The Digital Control and Digital Output tags do not have a similar feature, but an analog tag can be used in their place, writing a zero or a one. If the intent is to write a clear zero or one with an analog tag, both the scaled and unscaled range should be adjusted for a minimum value of zero and a maximum value of one, so that scaling does not adjust the values.

Closed Analog Output tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Analog Output properties I/O tab

The I/O tab holds the properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU). This is done by identifying the communication driver tag that communicates with the physical I/O device, the address at the physical I/O device from which this tag is to read its data, and the rate at which the I/O device should be scanned for data.

I/O Device

Select the communication driver tag to which data will be written.

By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver's properties dialog.

Address

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Engineering Units

Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc

Data Source

The value output by an analog control can be supplied by an operator via a widget on the screen, it can be supplied by a data source, or both can be used.

Normally, the data source would be another tag or an expression. If both a data source and an operator control are provided, then the value of the control tag will be whichever value was most recently set.

Use Data Source for display only

The data source can be used either as the value of the tag, updating the tag's value whenever the data source changes, or it can be used for display purposes only, leaving the value output by the tag unchanged. Use this check box to select one mode or the other.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Analog Output properties Scaling tab

The Scaling tab requires values that will be used to convert unscaled, raw data from the I/O device associated with this tag into scaled data that will be reported to operators. VTScada uses an algorithm to calculate this tag's value internally, based on the known unscaled and scaled values you supply.

The default value for each of these fields is stored in an application property. You are advised to change those properties to match the values used by your hardware by using the Edit Properties page of the Application Configuration dialog.

You will need to use the Advanced mode of the properties page. The properties to copy and edit are:

  • AnalogUnscaledMinDefault
  • AnalogUnscaledMaxDefault
  • AnalogScaledMinDefault
  • AnalogScaledMaxDefault

I/O scaling illustrated

VTScada assumes a linear relationship between the values as shown. The scaled and unscaled process values you provide set the slope of the line, allowing any value on one axis to be mapped to the other.

The values do not limit what the tag can read, but the Scaled Process Min and Max values do limit what the tag can write.

Min and Max Unscaled Process Data (Required.)

Use these to tell VTScada the range of raw values to expect from or write to hardware.

Min and Max Scaled Process Data (Required.)

These values must match the Unscaled Min and Max values. VTScada uses them to convert between the engineering units shown in the SCADA system and the raw values read from or written to the hardware. By default, the "Limit outputs to within Scaled min/max" option is selected. If you deselect this option, the output range limit is disabled. This allows any value, including negative integers, to be sent to the tag. However, scaling is still applied to the new output value, regardless of the value sent to the tag.

Analog Output properties Owner tab

This tag can be used in an owner/contributor structure where multiple contributor tags can supply their values to an owner tag.

There is no specific "owner" tag type, rather an owner tag is typically a custom-designed tag that is created using VTScada scripting code.

Owner

Specify a tag to which this contributor should supply its data. An owner tag is one which you must design and then create, using the VTScada scripting language.

The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual data value, to questionable data, according to the configuration of the check boxes appearing beneath the Owner field. These check boxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value check box is used to set the value of this contributor tag as the nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack. Priority check box causes the owner tag to keep track of the priority of the contributor's active alarm (or records an Invalid if the contributor is not in an alarm state). Selecting the Set Active/Unack. Priority check box also causes the owner tag to record whether the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values), rather than reading data from their I/O device. When selected, the Record Use of Manual Data check box is used to increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality (Analog and Digital Input only)

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag Quality check box is used to increment the owner tag's count of the number of tags that are contributing quality data by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the Record Tag Validity check box is used to increment the owner tag's count of the number of tags that are contributing questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Analog Output properties Merit tab

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Analog Output properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Analog Output properties Alarm tab

Use the Alarm tab to create new Alarm tags that will be triggered by this tag. The Add button will open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Analog Output properties Script tab

Optionally, link one or more Script tags to this tag. A Script tag provides a means of creating a procedure, using VTScada’s programming language, that will run whenever this tag’s value changes.

Analog Output properties Logger tab

Use the logger tab to associate a single Logger tag with this tag. The Logger tag will work with the attached Historian to record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be created as a child of the current tag.

Note: It is recommended that only one Logger tag be directly associated with a single input or output tag. If you require multiple loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Closed Analog Output Tag Widgets

The following widgets are available to Analog Output tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Blink Widget | Color Box Widget
Color Fill Widget | Comm Line Widget
Compass 1 Widget | Compass 2 Widget
Draw Text Widget | Droplist Widget
 | Image Change Widget
Left Bar Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Momentary Button Widget | Multi-Color Widget
Multi-Text Widget | Numeric Entry Widget
Numeric Value Widget | Plot Data Widget
Right Bar Widget | Set Analog Value Widget
Legacy Set Value Button Widget | Legacy Set Value Hotbox Widget
Slider Widget | Text Change Widget
Top Bar Widget | Two Color Bar Widget
Rotary Control Widget (Knob) | Equipment / Status Color Indicator
Indicator Light Widget | LCD 5x7 Matrix Widget
LCD 7 Segment Widget | Sparklines Widget

Related information:

Confirmation Prompts for Output Tags - Control options for confirmation prompt text.


Analog Status Tags

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

Counted towards your tag license limit.

It is the role of Analog Status tags to read analog data such as well level or a motor speed from an I/O device.

When dealing with analog values, PLCs are typically calibrated to provide a signal from zero to something, depending on the hardware. This may not correspond to the engineering units being measured. The values from the PLC might mean a range of 0 to 100%, -40°F to 451°F, or zero to 140 knots. You will configure your tags to adjust for this, providing the minimum and maximum values of raw, unscaled data from the equipment and the minimum and maximum values that this corresponds to the engineering units being measured. Scaling is always linear.

Values read by Analog Status tags are logged by default. New values are written on change, but not just any change. A deadband of one quarter of one percent (0.25%) of the scaled range of values is applied. Values must change by this much before a new one will be written to the Historian. Naturally, you have complete control over this and can configure any deadband value that you want.

Changes in value smaller than the Deadband setting will not be logged! Always check the settings in the Historian tab.
Analog Status tags will apply a default deadband of 1/4 of one percent of your display scale. (DefaultAnalogDeadbandFractionOfFullScale)
Read about the deadband in the section for the Historian Tab. Do not risk either a value so low that it logs system noise or a value so high that important information is lost.

Related information:

Best Practices for Tags

Closed Analog Status properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Analog Status properties I/O tab

The I/O Tab includes properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU), or to the polling driver responsible for determining the order and rate at which data polls will occur.

Analog Status tag - I/O tab

I/O configuration of an Analog Status tag

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Address

Provide the address within the I/O device from which this tag is to read data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

If a Write Address is provided the Read Address is used only as feedback and will set the value of the tag regardless of the value written. If the value in the Read Address does not match the value written then the tag's Mismatch flag is set to true and will be reflected in linked widgets, either as a blink or a mismatch color, according to the widget.

Address Assist: (...)

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the Address Assist dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your Communication Driver Tags for more information.

Scan Interval

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Deadband (On data reading, for Analog values only)

If defined, the value on the device must change by more than this amount before the tag will register it as a new value. A deadband can greatly improve application efficiency by filtering out noise and eliminating unnecessary work to process that noise as if it were useful data.

The deadband is an absolute value, not a percentage, and is specified in terms of the tag's display values if set or the scaled engineering units otherwise. (Refer to notes for the Scaling tab.) If a deadband value is not provided, one will be calculated automatically based on several factors including the logging deadband and the application property, DefaultDriverDeadbandFractionOfFullScale.

See also: Deadbands for Reading and Logging

History Address

If set, then the address field becomes optional. This field provides a means of reading values as recorded by a data logger.

If both the address and the history address are provided, then the address will be polled for data at the interval set by the Scan Rate, but the values read from the data logger will overwrite the values logged by this tag when it is updated.

The form for the history address will depend on the RTU. Please refer to the addressing reference chapter for your driver.

Note that it is not possible to enter a parameter expression directly in the History Address field. As an alternative, you may enter compound address in the Address field using a parameter expression. For example, if Addr, HistAddr and HistoryRate are all properties of a parent tag, the following expression in the Address field will create a compound address with all three components:

concat(.\Addr , "):(" , .\HistAddr , "):(" , .\HistoryRate )

The characters "):(" separate each component of the address. Do not add a leading or trailing parenthesis around the entire expression.

Further information on reading history information can be found in the topic SCADAPack History Read

History Scan Interval

Sets the time between polls of the history data logger. If a History address has been set, but this field is left blank, then it will default to the value set in the Scan Rate field. The recommended value for this field is 60 seconds. Lesser values may cause communications to slow down.

Note that it is not possible to enter a parameter expression directly in the History Scan Interval field.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Enable Output

This privilege has been moved from Quality tab to the I/O tab. If checked, this input tag may also be used to write data to the specified address of the communication driver. A Security Privilege may be set in the Quality tab to restrict access to this feature.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Analog Status properties Scaling tab

The Scaling Tab requires values that will be used to convert unscaled, raw data from the I/O device associated with this tag into scaled data that will be reported to operators.

Changes in value smaller than the Deadband setting will not be logged! Always check the settings in the Historian tab.
Analog Status tags will apply a default deadband of 1/4 of one percent of your display scale. (DefaultAnalogDeadbandFractionOfFullScale)
Read about the deadband in the section for the Historian Tab. Do not risk either a value so low that it logs system noise or a value so high that important information is lost.

Analogs can read text values if those are returned by the driver. Set the first four of the scaling parameters to "1" in order for the tag to interpret data as text.
Better is to use the String I/O tag for reading text data to avoid problems when attempting to mix text and numbers. A text "2" sent to an Analog Status with scaling set to 1 will be scaled to 1.

The first four fields on this tab affect the tag's value, scaling it from the input range to a desired output range.

The default value for each of these fields is stored in an application property. You are advised to change those properties to match the values used by your hardware by using the Edit Properties page of the Application Configuration dialog. You will need to use the Advanced mode of the properties page. The properties to copy and edit are:

  • AnalogUnscaledMinDefault
  • AnalogUnscaledMaxDefault
  • AnalogScaledMinDefault
  • AnalogScaledMaxDefault

I/O scaling illustrated

VTScada assumes a linear relationship between the values as shown. The scaled and unscaled process values you provide set the slope of the line, allowing any value on one axis to be mapped to the other.

The values do not limit what the tag can read, but the Scaled Process Min and Max values do limit what the tag can write.

Min and Max Unscaled Process Data (Required.)

Use these to tell VTScada the range of raw values to expect from or write to hardware.

Min and Max Scaled Process Data (Required.)

These values must match the Unscaled Min and Max values. VTScada uses them to convert between the engineering units shown in the SCADA system and the raw values read from or written to the hardware. By default, the "Limit outputs to within Scaled min/max" option is selected. If you deselect this option, the output range limit is disabled. This allows any value, including negative integers, to be sent to the tag. However, scaling is still applied to the new output value, regardless of the value sent to the tag.

Display Range Min and Max (Optional.)

These two fields have no effect on the value of the tag.

Set the Min and Max Display Range values to define the default scale range for the HDV trend view and certain widgets, such as the various meters. Use these when values are expected to stay within a portion of the full scale range and it is therefore helpful to adjust the displayed range as needed.

If left blank, the Scaled Process Data Min and Max values will be used as the Display Range values.

Analog Status properties Alarms tab

The Alarms tab contains two (optional) built-in alarms. One is for a high set point and one for a low set point, based on the value of this tag. The initial priority for each is "None", preventing unconfigured alarms from being counted as disabled alarms.

While the priority is set to "None" all other controls are disabled.

The following includes descriptions of features found in the Advanced version of this tab.

Alarm Priority

The Alarm Priority drop-down list enables you to select the priority of the alarm that will be triggered for this tag if its value passes the value defined for the setpoint. The available priorities are:

  • None
  • 0 - Event
  • 1 - Critical Alarm
  • 2 - High Alarm
  • 3 - Warning Alarm
  • 4 - Notice Alarm

If you have defined your own Alarm Priority tags, those will also be available for selection.

Alarm Setpoint

The Alarm Setpoint field enables you to enter the value, beyond which an alarm will be triggered. The source for this field may be a constant, the result of an expression, or the value of a tag.

Alarm Deadband

If noise in the system causes a value to fluctuate above and below the set point, the alarm will repeatedly switch between active and inactive status. By using the deadband, you can avoid filling the alarm history with these events by setting an amount by which the tag’s value return to the normal state before it is considered to no longer be active. The deadband is used only for changing a current alarm’s active status. It does not affect the set point.

Alarm Delay

Spikes in the value being monitored may cause transient alarms. By setting an alarm delay, you can specify that the trigger condition must remain true for a given length of time before the alarm is considered to have occurred.

Disable Alarm

The Disable Alarm field enables you to specify whether the alarm for this tag is disabled or enabled. Disabling of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine maintenance is being performed on the equipment represented by this tag, or when you are aware that another interruption in communications will occur for a period of time. In such situations, the alarm can be disabled until the maintenance is complete and communications are reestablished.

A value of 0 (or any tag or expression that returns 0) means that the alarm has not been disabled. Any value other than 0 in this field indicates that the alarm has been disabled.

The following is an advanced configuration technique. If you do not need to toggle alarm disabling on hundreds of alarms on a frequent basis, this technique is not appropriate for your application.

Each time you toggle an alarm between enabled and disabled, an event is recorded. If you must repeat this operation frequently for hundreds of tags, a large number of events can be recorded.
As an alternative, you could create a non-optimized expression for the alarm setpoint that toggles between the real setpoint and one that is either so high or so low that it can never cause the alarm to trigger. Changes made to the setpoint this way do not result in events being recorded.

Alarm Rearm Time

Applies only if Alarm Rearm Enable is selected for this alarm. If the alarm has been acknowledged, but remains active for the time shown in this field, the alarm will return to the unacknowledged state. Audible and visible warnings configured for this alarm’s priority level, will again be displayed. The Alarm Rearm Time is measured in seconds, and defaults to 3600 (1 hour). The value in this field must be greater than 0.

Alarm Rearm Enable

Controls whether this alarm will revert back to an unacknowledged state if it remains active for the length of time set in Alarm Rearm Time, after having been acknowledged by the operator.

Alarm Pop-up Enable

If the configuration variable AlarmPopupsEnable is set to 1, then setting either the Alarm Pop-up Enable will result in a pop-up dialog being displayed whenever the respective alarm is triggered. It is suggested that this feature be used sparingly.

Sound

The Sound field can be set to blank, 0, 1, or to the name of a .WAV sound file to be played.

If 0, no sound will be played when this alarm is triggered.

If blank or 1, an alarm sound whose properties are configured on the associated Alarm Priority tag will be played.

If the name of a .WAV sound file, it will override any alarm sound configured for the associated Alarm Priority tag. If the specified sound file is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Analog Status properties External Alarms tab

Analog Status tag - external alarms tab

Use the Add button to create new external Alarm tags and the Delete button to remove them. The new alarm tags will be created as children of the current tag.

Analog Status properties Quality tab

Analog Status tag - quality tab

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

Quality Based On

The Quality Based On field can be tied to a driver tag, a tag that monitors driver communication errors, a register in the PLC or RTU, or any other indication of system health. The tag you are configuring will use that value to set an internal variable named QualityIssue. You may test this value in an expression: [TagName]\QualityIssue.

QualityIssue will be a 0 or 1 where "Good Quality" is defined as a value of "0 or Invalid" and "Bad Quality" is defined as any valid, non-zero value. This is consistent with driver communication error values.

Widgets that use the System Style tag will display bad quality using the color set on the Exceptions tab.

The Quality Based On field can also be used when this tag is to be a contributor to a custom-built container tag. Please see the topic, Merit tab and Quality tab, for details.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Analog Status properties Display tab

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Display Order

Used to specify the placement of this tag when viewed in an associated station dialog. See Order tab for further details.

Engineering Units

Provide the units of measure that the scaled value represents. This text will be used by widgets that include engineering units as part of the display. Possible values for this field include "rpm", "degrees C", "%", etc.

You can add a degree symbol to the engineering units by holding down the Alt-key while typing 0176 on the numeric keypad. Release the Alt-key before typing the C or F.

Analog Status properties Logging tab

Analog Status tag - Historian tab

Analog Status Logging tab

Read the label of the deadband setting on your tag! Values smaller than the deadband setting will not be written to the Historian.

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Enable Logging

If values should be logged only while certain conditions are true, you can tie the Enable Logging option to any tag or expression that will change from zero (logging disabled) to non-zero (usually 1; logging enabled).

Deadband

The value of an Analog Status tag is automatically logged on change. The deadband range, specified in the defined engineering units, sets a minimum amount by which the tag's scaled(*) data must change before a new value is written to the log file. This will dampen out minor changes of value, reducing the size of the log file by excluding system noise.

If the deadband value is not set explicitly, the deadband will be the difference between the high and low display scale values (set on the Scaling tab), multiplied by the value of the application property, DefaultAnalogDeadbandFractionOfFullScale. That property defaults to one quarter of one percent (0.25 on a range of 100). Note that display scale values, if not set, default to the minimum and maximum scaled process data values.

No default will be applied to legacy applications. You may choose to set a value.

Closed Analog Status Tag Widgets

The following widgets are available to display information about your application’s Analog Status tags:

Alarm Priority Box | Alarm Priority Icon
Analog Bar & Indicator Widget |
Animated Image Widget | Bottom Bar Widget
Color Blink Widget | Color Box Widget
Color Fill Widget | Color Line Widget
Compass 1 Widget | Compass 2 Widget
LCD 5x7 Matrix Widget | Draw Text Widget
Droplist Widget | Equipment / Status Color Indicator
Image Change Widget | Indicator Light Widget
LCD Bar Widget | LCD 7 Segment Widget
Left Bar Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Glass Gauge Widget | Classic Gauge Widget
Retro Gauge Widget | Cockpit Gauge Widget
Aqua Gauge Widget | Army Gauge Widget
Backlit Gauge Widget | Nautical Gauge Widget
Quarter Arc Gauge Widget | Linear Gauge Widget
Antique Gauge Widget | LCD Ring Widget
LCD Arc Widget | LCD Meter Widget
Momentary Button Widget | Multi-Color Widget
Multi-Text Widget | Numeric Entry Widget
Numeric Value Widget | Plot Data Widget
Right Bar Widget | Rotary Control Widget (Knob)
Set Analog Value Widget | Legacy Set Value Button Widget
Legacy Set Value Hotbox Widget | Slider Widget
Text Change Widget | Top Bar Widget
Two Color Bar Widget | Spider Graph Widget
History Stats Value Widget |


Calculation Tags

Not counted towards your tag license limit.

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

The Calculation tag type is used to hold an expression, with the resulting value of the tag being the result of the expression. This tag type replaces the Function tag.

Related information:

- Reference for the VTScada scripting language.

Best Practices for Tags

Closed Calculation properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Calculation properties Calc tab

The Calc tab holds the expression for the calculation to be performed by this tag. While a choice of Constant, Expression or Tag is provided, you would normally use only Expression.

Calculation

You can use the Calculation to specify a constant numeric value, an expression, or reference another tag that will be the calculation run by this tag. The Calculation field corresponds to the selected associated check box. Select Expression and click on the [image] button to open the expression editor.

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

Questionable Data

Use this field to flag the tag’s data in the event that you suspect the values it is reporting might not be correct, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Calculation properties Owner tab

This tag can be used in an owner/contributor structure where multiple contributor tags can supply their values to an owner tag.

There is no specific "owner" tag type, rather an owner tag is typically a custom-designed tag that is created using VTScada scripting code.

Owner

Specify a tag to which this contributor should supply its data. An owner tag is one which you must design and then create, using the VTScada scripting language.

The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual data value, to questionable data, according to the configuration of the check boxes appearing beneath the Owner field. These check boxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value check box is used to set the value of this contributor tag as the nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack. Priority check box causes the owner tag to keep track of the priority of the contributor's active alarm (or records an Invalid if the contributor is not in an alarm state). Selecting the Set Active/Unack. Priority check box also causes the owner tag to record whether the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values), rather than reading data from their I/O device. When selected, the Record Use of Manual Data check box is used to increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality (Analog and Digital Input only)

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag Quality check box is used to increment the owner tag's count of the number of tags that are contributing quality data by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the Record Tag Validity check box is used to increment the owner tag's count of the number of tags that are contributing questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Calculation properties Display tab

Use the options in this panel to set display characteristics when the tag is represented on a page by widgets or plotted in the Historical Data Viewer. The display scale values are also used when calculating the default deadband used for logging.

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Low and High Scale Values

These fields have no effect on the value of the Calculation tag. They do affect the logging deadband and the default scale ranges when this tag is represented in the HDV or various widgets.

Set the Low Scale Value and High Scale Value to define the default scale range for the HDV trend view and certain widgets, such as the various meters.

Engineering Units

Provide the units of measure that the calculated value represents. This text will be used by widgets that include engineering units as part of the display. Possible values for this field include "rpm", "degrees C", "%", etc.

Calculation properties Alarm tab

If you want this tag to trigger an alarm, use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Calculation properties Historian tab

Historian

New calculation tags will have an Historian attached automatically. If you are updating a legacy application from a version of VTScada that did not have this option, it is possible that some or all Calculation tags may have been configured to log via an attached Logger tag. If so, you should leave the current Logger configuration in place.

Note: in previous versions of VTScada, unlogged calculation tags could be plotted in the HDV, where the plot would start at the moment the tag was added to an HDV display and continue until the next restart. Such temporary logging is not possible if the Calculation tag has an attached logger because the values are now being permanently logged. Turning off the Enable Logging feature does not restore the previous behavior. If you have a use for only temporary logging, remove the Historian connection.

If you select an Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historians are described in the topic, Historian Tag.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible.

Enable Logging

If values should be logged only while certain conditions are true, you can tie the Enable Logging option to any tag or expression that will change from zero (logging disabled) to non-zero (usually 1; logging enabled).

Deadband (Engineering Units)

If an Historian is selected, then the value of this tag is automatically logged on change. Use the deadband range to set a minimum amount by which the tag's value must change before a new value is written to the log file. This will dampen out minor changes of value, shrinking the size of the log file by excluding system noise.

If not specified here, the deadband will be the difference between the high and low scale values (set on the Display tab), multiplied by the value of the application property, DefaultCalculationDeadbandFractionOfFullScale. That property defaults to a quarter of a percent (0.0025). If Low Scale Value and High Scale Value have not been set, the deadband calculation will use a scale range of 100.

Closed Calculation Tag Widgets

The following widgets are available to display information about your application’s Calculation tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Blink Widget | Color Box Widget
Color Fill Widget | Color Line Widget
Compass 1 Widget | Compass 2 Widget
LCD 5x7 Matrix Widget | Draw Text Widget
Equipment / Status Color Indicator |
Image Change Widget | Indicator Light Widget
LCD Bar Widget | LCD 7 Segment Widget
Left Bar Widget | Meter 1 Widget
Meter 2 Widget | Meter 3 Widget
Glass Gauge Widget | Classic Gauge Widget
Retro Gauge Widget | Cockpit Gauge Widget
Aqua Gauge Widget | Army Gauge Widget
Backlit Gauge Widget | Nautical Gauge Widget
Quarter Arc Gauge Widget | Linear Gauge Widget
Antique Gauge Widget | LCD Ring Widget
LCD Arc Widget | LCD Meter Widget
Multi-Color Widget | Multi-Text Widget
Numeric Value Widget | Plot Data Widget
Right Bar Widget | Text Change Widget
Top Bar Widget | Two Color Bar Widget
Spider Graph Widget |


Digital Control Tags

Counted towards your tag license limit.

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

Digital Control tags transmit digital data that is entered by the user or from another tag and write it to an I/O device.

A Digital Control tag might be used to turn a pump off or on, open a valve, or change the mode of a device from manual to auto.

Retained or Persisted values

Analog Control and Analog Output tags will both retain their last written value across application restarts. Use these tags when there is a need for a value to persist.

String I/O tags with output enabled, and with no driver ("No tag selected" rather than the default, "[*Driver] None found") will retain their last written value across application restarts.

The Digital Control and Digital Output tags do not have a similar feature, but an analog tag can be used in their place, writing a zero or a one. If the intent is to write a clear zero or one with an analog tag, both the scaled and unscaled range should be adjusted for a minimum value of zero and a maximum value of one, so that scaling does not adjust the values.

Related information:

Best Practices for Tags

Closed Digital Control properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Digital Control properties I/O tab

The I/O Tab contains properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU), or to the Polling drive responsible for determining the order and rate at which data polls will occur.

Digital Control - I/O Properties

I/O Device

Select the communication driver tag to which data will be written.

By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Parameter Expression or open a selected driver's properties dialog.

Address

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Pulse Duration

If you are using a pulsed signal, enter the duration of the pulse here in seconds or decimal parts of a second.

If the value of Pulse Duration is 0 or blank (Invalid), then a constant value will be written to the I/O device.

A pulsed output is used to send a 1; seldom if ever, a zero. Use care with the configuration of the linked widget or multi-write tag.

Data Source

The value output by the control can be supplied by a data source. For a digital control, the values supplied by the data source should be limited to 1 or 0 (true or false).

Invert Output

Reverse the value of the output before writing.

Invert Data Source

Reverse the value coming from the data source before using.

Digital Control properties Feedback tab

The Feedback tab can be used to select an alarm, alarm priority, digital status, or Digital Control tag that will provide feedback when this tag's control action has successfully been completed.

Digital Control - Feedback tab

Feedback

The Feedback field enables you to specify an existing alarm, alarm priority, digital status, or Digital Control tag whose value can be used to determine whether the control action for this tag was successful. When a value is output by this tag, the feedback tag reads its value from the I/O device at the same address, and compares this value with the expected value(s) configured in the Feedback At State 0 and Feedback At State 1 spin boxes (see following notes).

If the Pulse Duration property for this tag (as set on the I/O tab) is set to a valid value greater than 0 (i.e. a pulsed signal), then the Feedback At State 0 property is ignored, as the logic assumes that the control attempt is always to drive the value of the feedback tag to the Feedback At State 1 value.

The 0 state may be inverted to a 1 before writing to the I/O device if this tag's Invert Output property (I/O tab) is set to 1 (true).

Feedback At State 0

If the Pulse Duration property for this tag, as set on the I/O tab, is set to any of: 0 (the default), invalid, or blank (i.e. a non-pulsed signal) then...

The Feedback At State 0 spin box should be set to the value you expect for the selected Feedback tag when this tag has successfully gone to the 0 state. For example, if you've configured this tag to stop a motor by issuing a value of 0 to the I/O device, you would expect the feedback tag (e.g. a Digital Status tag) to read a 0 back from the I/O device, indicating that your output was received.

Feedback At State 1

If the Pulse Duration property for this tag, as set on the I/O tab, is set to any of: 0 (the default), invalid, or blank (i.e. a non-pulsed signal), then...

The Feedback At State 1 spin box can be used to set the value you expect for the feedback tag when this tag has successfully gone to the 1 state. For example, if you've configured this tag to stop a motor by issuing a value of 1 to the I/O device, you would expect that the feedback tag (e.g. a Digital Status tag) would read 1 back from the I/O device, indicating that the value was received.

This value can be used as the source for an Alarm tag with a time delay to alert the operator that the requested output change has not had the desired effect within a reasonable period of time.

Digital Control properties Merit tab

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Digital Control - Merit tab

Digital Control properties Display tab

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Off Text

Optionally configure text that will be displayed in some of the tag's widgets when the value of this tag is 0 or false / off.

On Text

Optionally configure text that will be displayed in some of the tag's widgets when the value of the tag is 1 or true / on.

Display Order

Used to specify the placement of this tag when viewed in an associated station dialog. See Order tab for further details.

Closed Digital Control Tag Widgets

Digital Control tags enable users to write digital data to a PLC or RTU, which transmits the entered value to the equipment process associated with the tag. The widgets for Digital Control tags enable users to set values to be written to the equipment process associated with the tag, and display these set values.

The following widgets are available to Digital Control tags:

Alarm Priority Box

Alarm Priority Icon

Animated Image Widget

Color Blink Widget

Color Box Widget

Color Line Widget

Equipment / Status Color Indicator

Image Change Widget

Indicator Light Widget

Momentary Button Widget

Legacy Set Value Button Widget

Legacy Set Value Hotbox Widget

Text Change Widget

Two Color Bar Widget

Of the widgets displayed above, only the Momentary Button, Legacy Set Value Button, and Legacy Set Value Hotbox widgets allow users to actually output data to the equipment process associated with the tag being drawn. All other widgets simply display the current value of the tag, which will normally be zero while waiting to write.

Related information:

Confirmation Prompts for Output Tags - Control options for confirmation prompt text.


Digital Input Tags

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

Counted towards your tag license limit.

Digital inputs represent incoming digital data values from equipment, and provide widgets that change color, appearance, or text to impart the value of the digital input and associated equipment.

A Digital Input tag can be a single bit digital input or a double bit digital input. For single bit digital inputs, there are two possible states. For digital inputs that use two address bits, there are four possible states.

Digital inputs clamp raw data values to either zero or one on each input pin (yielding a result of 0, 1, 2, or 3 for pump status and Digital Status tags). Analog zero yields zero, while all other values yield 1. This is effective for analog values that have discrete states (e.g. line voltage can be read for on/off), but pure analog data (e.g. velocity) will only become false when the value drops below the sensitivity of the measuring device.

In most situations, use Digital Status Tags rather than Digital Input tags.

Related information:

Best Practices for Tags

Closed Digital Input properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Digital Input properties I/O tab

The I/O tab holds the properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU). This is done by identifying the communication driver tag that communicates with the physical I/O device, the address at the physical I/O device from which this tag is to read its data, and the rate at which the I/O device should be scanned for data.

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Bit 0 Address

The Bit 0 Address property is the address of the low order bit for this tag in the I/O device. If this is a single bit digital tag, this is the field that specifies the address of that bit.

Address Assist:

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your driver for more information.

Bit 1 Address

The Bit 1 Address property is the address of the high order bit for the digital input in the I/O device. If this is a single bit digital input, this field should be left blank. See following notes on single bit and double bit inputs.

Scan Interval

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

Invert Input

The Invert Input check box enables you to specify whether the value of this tag should be reversed. If selected, the value for this tag will be inverted (i.e. 0 and 1 are swapped).

The typical use for input inversion is in projects where 1 indicates false or off, and 0 indicates true or on. By default, the Invert Input check box is not selected.

Enable Output

If selected, this input tag may also be used to write data to the specified Bit 0 address of the communication driver. Pulsed writes are not available. A Security Privilege may be set in the Merit tab to restrict access to this feature.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Single Bit and Double Bit Digital Inputs

A single bit digital status reads a value of 0 or a 1 from one address on an I/O device. An example of a single bit digital status would be a pump's status, where the pump is either off (0), or on (1).

A double bit digital status reads a value of 0 or 1 from two addresses on an I/O device. An example of an equipment process requiring a double bit digital status might be a valve with 4 states: open, closed, open or close action in progress, or error. The following table shows the possible values for a double bit digital status according to the values at each bit.

State | Bit 1 | Bit 0 | Description | Tag Value
State 0 | 0 | 0 | A process is in action (either the valve is opening, or is closing) | 0
State 1 | 0 | 1 | The valve is closed. | 1
State 2 | 1 | 0 | The valve is open. | 2
State 3 | 1 | 1 | There is an error. | 3
Invalid | Invalid | Invalid | No data. | Invalid

Digital Input properties Owner tab

This tag can be used in an owner/contributor structure where multiple contributor tags can supply their values to an owner tag.

There is no specific "owner" tag type, rather an owner tag is typically a custom-designed tag that is created using VTScada scripting code.

Owner

Specify a tag to which this contributor should supply its data. An owner tag is one which you must design and then create, using the VTScada scripting language.

The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual data value, to questionable data, according to the configuration of the check boxes appearing beneath the Owner field. These check boxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value check box is used to set the value of this contributor tag as the nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack. Priority check box causes the owner tag to keep track of the priority of the contributor's active alarm (or records an Invalid if the contributor is not in an alarm state). Selecting the Set Active/Unack. Priority check box also causes the owner tag to record whether the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values), rather than reading data from their I/O device. When selected, the Record Use of Manual Data check box is used to increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality (Analog and Digital Input only)

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag Quality check box is used to increment the owner tag's count of the number of tags that are contributing quality data by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the Record Tag Validity check box is used to increment the owner tag's count of the number of tags that are contributing questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Digital Input properties Merit tab

Quality Based on

The Quality Based On field is for use when this tag is to be a contributor to a custom-built container tag. Please see the topic Merit tab and Quality tab, for details.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Digital Input properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Digital Input properties Alarm tab

If you want this tag to trigger an alarm, use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Digital Input properties Script tab

Optionally, link one or more Script tags to this tag. A Script tag provides a means of creating a procedure, using VTScada’s programming language, that will run whenever this tag’s value changes.

Digital Input properties Logger tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag and the attached Historian will record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be created as a child of the current tag.

Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Closed Digital Input Tag Widgets

The following widgets are available to display information about your application’s Digital Input tags:

Alarm Priority Box

Alarm Priority Icon

Animated Image Widget

Color Blink Widget

Color Box Widget

Color Line Widget

Equipment / Status Color Indicator

Image Change Widget

Indicator Light Widget

Momentary Button Widget

Plot Data Widget

Legacy Set Value Button Widget

Legacy Set Value Hotbox Widget

Sparklines Widget

Text Change Widget


Digital Output Tags

Counted towards your tag license limit.

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

Digital Output tags take digital information from the operator (via a widget) or from another tag and write it to the I/O device.

The value of a digital output can be:

  • 1 when there is an attempt to set the output that has not yet been confirmed by a change in the feedback value.
  • 0 if neither case is met. i.e. when not performing a write, or after confirmation is received that a write has occurred.
  • Of interest only to programmers: A transient value of 2 will occur when the feedback value changes without any prompting from the digital output. This value is extremely transitory and will not be caught by any alarm.

In most situations, use Digital Control Tags rather than Digital Output tags.

Retained or Persisted values

Analog Control and Analog Output tags will both retain their last written value across application restarts. Use these tags when there is a need for a value to persist.

String I/O tags with output enabled, and with no driver ("No tag selected" rather than the default, "[*Driver] None found") will retain their last written value across application restarts.

The Digital Control and Digital Output tags do not have a similar feature, but an analog tag can be used in their place, writing a zero or a one. If the intent is to write a clear zero or one with an analog tag, both the scaled and unscaled range should be adjusted for a minimum value of zero and a maximum value of one, so that scaling does not adjust the values.

Related information:

Best Practices for Tags

Closed Digital Output properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Digital Output properties I/O tab

The I/O tab contains the properties used to identify and establish a connection to the communication driver tags being used to exchange data with your physical I/O device (e.g. PLC or RTU). This is done by identifying the communication driver tag that communicates with the physical I/O device, and the address at the physical I/O device to which this tag is to write its data.

I/O Device

Select the communication driver tag to which data will be written.

By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver's properties dialog.

Address

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Pulse Duration

If you are using a pulsed signal, enter the duration of the pulse here in seconds or decimal parts of a second.

If the value of Pulse Duration is 0 or blank (Invalid), then a constant value will be written to the I/O device.

A pulsed output is used to send a 1, seldom if ever a zero. Use care with the configuration of the linked widget or multi-write tag.

Data Source

The value output by the control can be supplied by a data source. For a digital control, the values supplied by the data source should be limited to 1 or 0 (true or false).

Invert Output

Reverse the value of the output before writing.

Invert Data Source

Reverse the value coming from the data source before using.

Digital Output properties Feedback tab

The Feedback tab can be used to select an existing tag, or create a new tag belonging to the Digitals Group, that will provide feedback indicating the current status of this tag's control action.

When the feedback tag’s value changes to what was expected as a result of the digital output, then the Digital Output tag’s value will go to 0, indicating that no output is in progress (i.e. the write has finished)

Until the feedback tag changes to the value expected as a result of the digital output (perhaps because a communication error is preventing the output from occurring) then the Digital Output tag’s value will remain at 1, indicating that the output is still in progress.

If the feedback tag’s value changes independently of a write occurring from the digital output, the tag’s value will undergo a transitory change to a 2. This signal is designed for the use of VTScada programmers - it does not last long enough to display and cannot be captured by an alarm.

Feedback

Select or create a tag from the digitals group that will provide the source of the feedback.

Feedback At State 0

The Feedback At State 0 spin box can be used to set the value you expect back from the feedback tag when the digital output has successfully written a 0 (State 0).

Feedback At State 1

The Feedback At State 1 spin box can be used to set the value you expect back from the feedback tag when the digital output has successfully written a 1, 2 or 3 (State 1).

Digital Output properties Owner tab

This tag can be used in an owner/contributor structure where multiple contributor tags can supply their values to an owner tag.

There is no specific "owner" tag type, rather an owner tag is typically a custom-designed tag that is created using VTScada scripting code.

Owner

Specify a tag to which this contributor should supply its data. An owner tag is one which you must design and then create, using the VTScada scripting language.

The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual data value, to questionable data, according to the configuration of the check boxes appearing beneath the Owner field. These check boxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value check box is used to set the value of this contributor tag as the nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack. Priority check box causes the owner tag to keep track of the priority of the contributor's active alarm (or records an Invalid if the contributor is not in an alarm state). Selecting the Set Active/Unack. Priority check box also causes the owner tag to record whether the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values), rather than reading data from their I/O device. When selected, the Record Use of Manual Data check box is used to increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality (Analog and Digital Input only)

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag Quality check box is used to increment the owner tag's count of the number of tags that are contributing quality data by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the Record Tag Validity check box is used to increment the owner tag's count of the number of tags that are contributing questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Digital Output properties Merit tab

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Digital Output properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Digital Output properties Alarm tab

If you want this tag to trigger an alarm, use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Digital Output properties Script tab

Optionally, link one or more Script tags to this tag. A Script tag provides a means of creating a procedure, using VTScada’s programming language, that will run whenever this tag’s value changes.

Digital Output properties Logger tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag will work with the attached Historian to record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be created as a child of the current tag.

Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Closed Digital Output Tag Widgets

Digital Output tags write digital equipment process data to a PLC or RTU. The widgets for Digital Output tags enable users to write this data and view the data being written.

The following widgets are available to Digital Output tags:

Alarm Priority Box

Alarm Priority Icon

Animated Image Widget

Color Blink Widget

Color Box Widget

Color Line Widget

Equipment / Status Color Indicator

Image Change Widget

Indicator Light Widget

Momentary Button Widget

Plot Data Widget

Legacy Set Value Button Widget

Legacy Set Value Hotbox Widget

Text Change Widget

Of these widgets, only the Legacy Set Value Button, Legacy Set Value Hotbox, and Momentary Button methods enable users to output values to the associated tag. The remaining widgets display the value of the tag, which will normally be zero while waiting to write.

Related information:

Confirmation Prompts for Output Tags - Control options for confirmation prompt text.


Digital Status Tags

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

Counted towards your tag license limit.

Digital Status tags accept incoming digital data from an I/O device. A Digital Status tag might be used to read the status (e.g. off or on), or the mode (e.g. running or stopped) of equipment.

VTScada also includes Pump Status tags, which are very similar to Digital Status tags.

A digital status can be a single bit digital input or a double bit digital input. For single bit digital inputs, there are two possible states (off or on, running or stopped), whereas for digital inputs that use two address bits, there are four possible states (e.g. opened, closed, process in action (either opening or closing), or error).

Digital inputs clamp raw data values to either zero or one on each input pin (yielding a result of 0, 1, 2, or 3 for pump status and Digital Status tags). Analog zero yields zero, while all other values yield 1. This is effective for analog values that have discrete states (e.g. line voltage can be read for on/off), but pure analog data (e.g. velocity) will only become false when the value drops below the sensitivity of the measuring device.

Related information:

Best Practices for Tags

Digital Status tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Digital Status properties I/O tab

The I/O tab holds the properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU), or to the polling driver responsible for determining the order and rate at which data polls will occur.

Note: Digital Status tags can have single or double bit addresses. Information on single and double bit digital inputs can be found in Single Bit and Double Bit Digital Inputs.

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Bit 0 Address

The Bit 0 Address property is the address of the low order bit for this tag in the I/O device. If this is a single bit digital tag, this is the field that specifies the address of that bit. The reported value of this digital tag is the data at this address plus two times the data at the Bit 1.

Address Assist:

Several drivers including SNMP, OPC Classic Client, Fisher ROC and others, provide an Address Assist button to help you. The content of the dialog will vary according to the driver. Within this guide, refer to the Driver Addressing topic for your driver for more information.

Bit 1 Address

The Bit 1 Address property is the address of the high order bit for the digital input in the I/O device. If this is a single bit digital input, this field should be left blank.

If the option, Read History is selected, this will become the History Address.

Scan Rate

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Read History

If checked, the field Bit 1 Address becomes History Address and the field History Scan Interval is enabled.

History Address

If set, then the Bit 0 address becomes optional. This field provides a means of reading values as recorded by a data logger.

If both the Bit 0 address and the history address are provided, then the bit 0 address will be polled for data at the interval set by the Scan Rate, but the values read from the data logger will overwrite the values logged by this tag when it is updated.

The form for the history address will depend on the RTU. Please refer to the addressing reference chapter for your driver.

You may enter compound address in the History Address field using a parameter expression. For example, if HistAddr and HistoryRate are both properties of a parent tag, the following expression in the History Address field will create a compound address with both components:

Concat("):(" , ..\HistAddr , "):(" , ..\HistoryRate )

The characters "):(" separate each component of the address. Do not add a leading or trailing parenthesis around the entire expression.

History Scan Interval

Sets the time between polls of the history data logger. If a History address has been set, but this field is left blank, then it will default to the value set in the Scan Rate field. The recommended value for this field is 60 seconds. Lesser values may cause communications to slow down.

Note that it is not possible to enter a parameter expression directly in the History Scan Interval field.

Manual Data

Optionally provide a constant value that will be used instead of input read by the communication driver. It is commonly used when testing a new tag when application is not attached to a live data source. Tags that are using manual data are marked on screen by a flashing exclamation mark.

Invert Input

If the Invert Input check box is selected, the value of the tag being used as the data source is reversed (i.e. a 1 becomes a 0 or a 0 becomes a 1).

Enable Output

If checked, this input tag may also be used to write data to the specified Bit 0 address of the communication driver. Pulsed writes are not available. A Security Privilege may be set in the Quality tab to restrict access to this feature.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Digital Status properties Alarm Setup tab

Optionally configure one alarm based on the status of this tag. Note that while the priority is set to "None" all other controls are disabled.

Alarm Priority

Select the priority of the alarm that will be triggered for this tag. The available priorities are:

  • None (all other controls will be disabled)
  • 0 - Event
  • 1 - Critical Alarm
  • 2 - High Alarm
  • 3 - Warning Alarm
  • 4 - Notice Alarm

If you have defined your own Alarm Priority tags, those will also be available for selection.

Alarm State

Select the trigger for the alarm. The alarm will be triggered when the tag's state becomes one of the following:

0 The alarm is triggered when Bit 0 goes low. The Bit 1 address either has not been provided or is low.

1 The alarm is triggered when Bit 0 goes high. The Bit 1 address either has not been provided or is low.

2 Two addresses provided. Bit 0 goes low and Bit 1 goes high.

3 Two addresses provided. Both Bit 0 and Bit 1 go high.

Upon Change - any change of state triggers an alarm. Note that when the Upon Change option is selected, the trip alarm option will be set and cannot be deselected by the developer.

On Delay

Transient changes in state can result in multiple alarms being triggered. By setting an alarm delay, you can specify that if the tag’s state changes back one which does not constitute an alarm situation, it must remain in that state for a given length of time before the alarm is deemed to be inactive.

Alarm Rearm Time

Applies only if Alarm Rearm Enable is selected for this alarm. If the alarm has been acknowledged, but remains active for the time shown in this field, the alarm will return to the unacknowledged state. Audible and visible warnings configured for this alarm’s priority level, will again be displayed. The Alarm Rearm Time is measured in seconds, and defaults to 3600 (1 hour). The value in this field must be greater than 0.

Alarm Rearm Enable

Controls whether this alarm will revert back to an unacknowledged state if it remains active for the length of time set in Alarm Rearm Time, after having been acknowledged by the operator.

Alarm Disable

Specify whether the alarm for this tag is disabled or enabled. Disabling of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine maintenance is being performed on the equipment represented by this tag, or when you are aware that another interruption in communications will occur for a period of time. In such situations, the alarm can be disabled until the maintenance is complete and communications are re-established.
May be linked to a tag or expression for suppression by design.

The following is an advanced configuration technique. If you do not need to toggle alarm disabling on hundreds of alarms on a frequent basis, this technique is not appropriate for your application.

Each time you toggle an alarm between enabled and disabled, an event is recorded. If you must repeat this operation frequently for hundreds of tags, a large number of events can be recorded.
As an alternative, you could create a non-optimized expression for the alarm setpoint that toggles between the real setpoint and one that is either so high or so low that it can never cause the alarm to trigger. Changes made to the setpoint this way do not result in events being recorded.

Trip Alarm

Select if this alarm is to be a trip alarm.

Trip alarms do not have the attribute of being Active or Inactive based on the value of the Trigger tag. After being triggered, the alarm must be acknowledged by an operator, but the underlying cause of the alarm need not be cleared.

Append State to Alarm Description

When selected, VTScada will append the text used for the state of the tag, as taken from the Off Text and On Text fields in the tag’s I/O tab, to the alarm message.

Pop-up Enable

If the configuration variable AlarmPopupsEnable is set to 1, then setting either the Low Alarm Pop-up Enable or the High Alarm Pop-up Enable, will result in a pop-up dialog being displayed whenever the respective alarm is triggered. It is strongly suggested that this feature be used sparingly.

Sound

The Sound field can be set to blank, 0, 1, or to the name of a .WAV sound file to be played.

If 0, no sound will be played when this alarm is triggered.

If blank or 1, an alarm sound whose properties are configured on the associated Alarm Priority tag will be played.

If the name of a .WAV sound file, it will override any alarm sound configured for the associated Alarm Priority tag. If the specified sound file is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Digital Status properties External Alarms tab

The External Alarms tab is used to display, add or remove separate Alarm tags that are triggered by this Digital Status tag. Use the Add button to create new external Alarm tags and the Delete button to remove them. The new alarm tags will be created as children of the current tag.

Digital Status properties Quality tab

Quality Based on

The Quality Based on field can be tied to a driver tag, a tag that monitors driver communication errors, a register in the PLC or RTU, or any other indication of system health. The tag you are configuring will use that value to set an internal variable named QualityIssue. You may test this value in an expression: [TagName]\QualityIssue.

QualityIssue will be a 0 or 1. "Good Quality" is defined as a value of "0 or Invalid" and "Bad Quality" is defined as any valid, non-zero value. This is consistent with driver communication error values.

Widgets that use the System Style tag will display bad quality using the color set on the Exceptions tab.

The Quality Based On field can also be used when this tag is to be a contributor to a custom-built container tag. Please see the topic Merit tab and Quality tab, for details.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Digital Status properties Display tab

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Off Text

Optionally configure text that will be displayed in some of the tag's widgets when the value of this tag is 0 or false / off.

On Text

Optionally configure text that will be displayed in some of the tag's widgets when the value of the tag is 1 or true / on.

Display Order

Used to specify the placement of this tag when viewed in an associated station dialog. See Order tab for further details.

Digital Status properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Enable Logging

If values should be logged only while certain conditions are true, you can tie the Enable Logging option to any tag or expression that will change from zero (logging disabled) to non-zero (usually 1; logging enabled).

Closed Digital Status Tag Widgets

The following widgets are available to display information about your application’s Digital Status tags:

Alarm Priority Box

Alarm Priority Icon

Animated Image Widget

Color Blink Widget

Color Box Widget

Color Line Widget

Draw Widget

Equipment / Status Color Indicator

History Stats Value Widget

Image Change Widget

Indicator Light Widget

Momentary Button Widget

Plot Data Widget

Legacy Set Value Button Widget

Legacy Set Value Hotbox Widget

Sparklines Widget

Text Change Widget

Two Color Bar Widget


Function Tags

Not counted towards your tag license limit.

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

The Function tag type is used to perform mathematical and logical calculations using numeric values and, optionally, the values of other tags. A Function tag can accept up to four tag values or numeric values as properties, and the result of the calculation becomes the value of the Function tag. Other tags can use the value of a Function tag.

The output of a Function tag with no configured function parameters is undefined. It is not guaranteed to be any specific value, not even invalid.

Function tags are an older technology, maintained for backward-compatibility. You are advised to use Calculation tags for most applications.

Related information:

Best Practices for Tags

Closed Function properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Function properties Operator tab

The Operator tab identifies the operation that will be performed on the inputs for this tag.

OpCode

The OpCode drop-down list enables you to specify the type of operation to be performed on the values associated with this Function tag.

The parameters (values) that will be used for the selected operation, are configured on the tab, Inputs.

  • Parameters that are not configured have no impact on the resulting value of the function.
  • Parameters whose value evaluates to Invalid will cause most function operations to return Invalid.

The supported operations are:

+ | All configured parameters are added. Any parameter that contains a tag or expression that evaluates to Invalid will result in the Function tag having the value, Invalid.
- | Parameter 1 - Parameter 2 - Parameter 3 - Parameter 4 (disregarding any unconfigured parameters). Any parameter that contains a tag or expression that evaluates to Invalid will result in the Function tag having the value, Invalid.
* | Parameter 1 * Parameter 2 * Parameter 3 * Parameter 4 (disregarding any unconfigured parameters). Any parameter that contains a tag or expression that evaluates to Invalid will result in the Function tag having the value, Invalid.
/ | Parameter 1 / Parameter 2 / Parameter 3 / Parameter 4 (disregarding any unconfigured parameters). Any parameter that contains a tag or expression that evaluates to Invalid will result in the Function tag having the value, Invalid.
& | Logical AND. Three results are possible: TRUE, FALSE or Invalid. * To return a value of TRUE, all configured parameters must evaluate to TRUE. * If any configured parameter is FALSE, then the result will be FALSE. * If no configured parameters evaluate to FALSE, but at least one evaluates to Invalid, then the result will be Invalid.
| | Logical OR. Logical Three results are possible: TRUE, FALSE or Invalid. * If any configured parameter is TRUE, then the result will be TRUE. * If all configured parameters are FALSE, then the result will be FALSE. * If no configured parameters evaluate to TRUE, but at least one evaluates to Invalid, then the result will be Invalid.
Average | Average of Parameters 1 through 4 (excluding any undefined values).
Max | Maximum of Parameters 1 through 4 (excluding any undefined values).
Min | Minimum of Function Parameters 1 through 4 (excluding any undefined values).
Integrate | Performs time integral of Parameter 1 * Parameter 2, every Parameter 3 seconds. * If Parameter 2 is not defined, it defaults to a value of 1. * If Parameter 3 is not defined, it defaults to a value of 1 second. For example, if Parameter 2 and Parameter 3 were not defined, the calculation would be Parameter 1 * 1 every 1 second).

Function properties Inputs tab

The Inputs tab identifies the numeric values or tag values that will be factors in the calculation.

Function Parameter X

The Function Parameter 1 through to Function Parameter 4 fields enable you to specify up to four factors in the calculation performed by this tag.

You may use a constant, expression or tag as the source of the value for each parameter. Parameters that are not configured are essentially ignored, in that they will not have an effect on the result of the calculation.

Parameters that are configured, but which evaluate to Invalid, will have an effect on the calculation as noted in the description of each operational code. Note that tags can have an invalid value when there is an error in communication. Many expressions can return a value of Invalid. For example, if attempting to divide by zero.

You cannot select a Function tag as one of its own function parameters.

Function properties Manual tab

The Manual tab contains the Manual Data and Questionable Data properties. The Manual Data field can be used to enter a user-defined value for this tag that will override the value of its calculation. Use the Questionable Data check box to flag this tag’s data as being questionable in the event that you feel the values it is reporting might not be correct, or when this tag has initially been created and you wish to ensure that its data is monitored for validity.

Manual Data

Enables you to set a user-defined value for this tag, rather than reading the value from the associated I/O device (i.e. this user-defined value overrides the data incoming from the equipment).

If this field is anything other than a blank, or an invalid number, then the value from the I/O device is ignored and this value will be used instead.

The widget used by any tag with Manual Data will include an exclamation mark.

If the value entered into the Manual Data field is a 0, the actual value reported by the equipment is also overridden, as 0 is considered a valid value. Therefore, if it is your intention to resume reading data from the I/O device, you must clear the Manual Data field entirely.

Questionable Data

Use this field to flag the tag’s data in the event that you suspect the values it is reporting might not be correct, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Function properties Owner tab

This tag can be used in an owner/contributor structure where multiple contributor tags can supply their values to an owner tag.

There is no specific "owner" tag type, rather an owner tag is typically a custom-designed tag that is created using VTScada scripting code.

Owner

Specify a tag to which this contributor should supply its data. An owner tag is one which you must design and then create, using the VTScada scripting language.

The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual data value, to questionable data, according to the configuration of the check boxes appearing beneath the Owner field. These check boxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value check box is used to set the value of this contributor tag as the nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack. Priority check box causes the owner tag to keep track of the priority of the contributor's active alarm (or records an Invalid if the contributor is not in an alarm state). Selecting the Set Active/Unack. Priority check box also causes the owner tag to record whether the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values), rather than reading data from their I/O device. When selected, the Record Use of Manual Data check box is used to increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality (Analog and Digital Input only)

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag Quality check box is used to increment the owner tag's count of the number of tags that are contributing quality data by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the Record Tag Validity check box is used to increment the owner tag's count of the number of tags that are contributing questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Closed Function properties Display tab

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.

The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application. If a Style Settings tag is an ancestor or else a sibling, it will become the new automatic default.

Function properties Alarm tab

If you want this tag to trigger an alarm, use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Function properties Script tab

Optionally, link one or more Script tags to this tag. A Script tag provides a means of creating a procedure, using VTScada’s programming language, that will run whenever this tag’s value changes.

Function properties Logger tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag works with an Historian to this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be created as a child of the current tag.

You may also select a publisher tag if one is required for your configuration. Eligible ancestor tags, uncle tags or else sibling tags will auto link. Publish must be enabled before data will be published. Disable Publish to stop publishing data.

Closed Function Tag Widgets

The following widgets are available to display information about your application’s Function tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Bottom Bar Widget
Color Box Widget | Color Fill Widget
Color Line Widget | LCD 5x7 Matrix Widget
Equipment / Status Color Indicator |
Image Change Widget | Indicator Light Widget
LCD 7 Segment Widget | Left Bar Widget
Meter 1 Widget | Meter 2 Widget
Meter 3 Widget | Multi-Color Widget
Multi-Text Widget | Numeric Value Widget
Plot Data Widget | Right Bar Widget
Text Change Widget | Top Bar Widget
Two Color Bar Widget | Sparklines Widget


Pump Status Tags

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

An I/O tag with a data type of Digital and an equipment type set to Pump will serve the same purpose as the legacy Pump Status tag.

Counted towards your tag license limit.

Pump status tags accept incoming digital data from pumps. These are similar to Digital Status tags, but are designed specifically for use with pumps. predefined reports, including Pump Activity and Pump Discrepancy are designed to work with data from Pump Status tags.

Digital inputs, including Pump Status tags, clamp raw data values to either zero or one on each input pin (yielding a result of 0, 1, 2, or 3 for Pump Status and Digital Status tags). Analog zero yields zero, while all other values yield 1. This is effective for analog values that have discrete states (e.g. line voltage can be read for on/off), but pure analog data (e.g. velocity) will only become false when the value drops below the sensitivity of the measuring device.

Related information:

Best Practices for Tags

Closed Pump Status tag properties: ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Pump Status properties I/O tab

The I/O tab holds the properties used to identify and establish a connection to the communication driver tag being used to exchange data with your physical I/O device (e.g. PLC or RTU), or to the polling driver responsible for determining the order and rate at which data polls will occur.

Pump status tags can have single or double bit addresses.

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Bit 0 Address

The Bit 0 Address property is the address of the low order bit for this tag in the I/O device. If this is a single bit digital tag, this is the field that specifies the address of that bit. The reported value of this digital tag is the data at this address plus two times the data at the Bit 1.

Note: If a data logger is being used on a tag, it can only be for a single bit address.

Bit 1 Address

The Bit 1 Address property is the address of the high order bit for the digital input in the I/O device. If this is a single bit digital input, this field should be left blank.

Scan Rate

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Read History

If selected, the field Bit 0 Address becomes History Address and the field History Scan Interval is enabled.

History Address

If set, then the Bit 0 address becomes optional. This field provides a means of reading values as recorded by a data logger.

If both the Bit 0 address and the history address are provided, then the Bit 0 address will be polled for data at the interval set by the Scan Rate, but the values read from the data logger will overwrite the values logged by this tag when it is updated.

The form for the history address will depend on the RTU. Please refer to the addressing reference chapter for your driver.

History Scan Interval

Sets the time between polls of the history data logger. If a History address has been set, but this field is left blank, then it will default to the value set in the Scan Rate field. The recommended value for this field is 60 seconds. Lesser values may cause communications to slow down.

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

Invert Input

If the Invert Input check box is selected, the value of the tag being used as the data source is reversed (i.e. a 1 becomes a 0 or a 0 becomes a 1) before it is written to the I/O device.

Enable Output

If selected, this input tag may also be used to write data to the specified Bit 0 address of the communication driver. A Security Privilege may be set in the Quality tab to restrict access to this feature.

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

Pump Status properties Alarm Setup tab

Optionally configure one alarm based on the status of this tag. Note that, while the priority is set to "None" all other controls are disabled.

Alarm Priority

The Alarm Priority drop-down list enables you to select the priority of the alarm that will be triggered for this tag. The available priorities are:

  • None
  • 0 - Event
  • 1 - Critical Alarm
  • 2 - High Alarm
  • 3 - Warning Alarm
  • 4 - Notice Alarm

If you have defined your own Alarm Priority tags, those will also be available for selection.

Alarm State

The Alarm State spin box enables you to select the trigger for the alarm. The alarm will be triggered when the tag's state becomes one of the following:

0 The alarm is triggered when Bit 0 goes low. The Bit 1 address either has not been provided or is low.

1 The alarm is triggered when Bit 0 goes high. The Bit 1 address either has not been provided or is low.

2 Two addresses provided. Bit 0 goes low and Bit 1 goes high.

3 Two addresses provided. Both Bit 0 and Bit 1 go high.

Upon Change - any change of state triggers an alarm. Note that when the Upon Change option is selected, the trip alarm option will be set and cannot be deselected by the developer.

On Delay

Transient changes in state can result in multiple alarms being triggered. By setting an alarm delay, you can specify that if the tag’s state changes back one which does not constitute an alarm situation, it must remain in that state for a given length of time before the alarm is deemed to be inactive.

Alarm Rearm Time

Applies only if Alarm Rearm Enable is selected for this alarm. If the alarm has been acknowledged, but remains active for the time shown in this field, the alarm will return to the unacknowledged state. Audible and visible warnings configured for this alarm’s priority level, will again be displayed. The Alarm Rearm Time is measured in seconds, and defaults to 3600 (1 hour). The value in this field must be greater than 0.

Alarm Rearm Enable

Controls whether this alarm will revert back to an unacknowledged state if it remains active for the length of time set in Alarm Rearm Time, after having been acknowledged by the operator.

Alarm Disable

Specify whether the low alarm for this tag is disabled or enabled. Disabling of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine maintenance is being performed on the equipment represented by this tag, or when you are aware that another interruption in communications will occur for a period of time. In such situations, the alarm can be disabled until the maintenance is complete and communications are reestablished.
May be linked to a tag or expression for suppression by design.

The following is an advanced configuration technique. If you do not need to toggle alarm disabling on hundreds of alarms on a frequent basis, this technique is not appropriate for your application.

Each time you toggle an alarm between enabled and disabled, an event is recorded. If you must repeat this operation frequently for hundreds of tags, a large number of events can be recorded.
As an alternative, you could create a non-optimized expression for the alarm setpoint that toggles between the real setpoint and one that is either so high or so low that it can never cause the alarm to trigger. Changes made to the setpoint this way do not result in events being recorded.

Trip Alarm

Select if this alarm is to be a trip alarm.

Trip alarms differ from level alarms in that they are not active or inactive based on the value of the Trigger tag. After alarms are triggered, they must be acknowledged, but there is no requirement that the cause of the alarm condition be cleared.

Append State to Alarm Description

When selected, VTScada will append the text used for the state of the tag, as taken from the Off Text and On Text fields in the tag’s I/O tab, to the alarm message.

Pop-up Enable

If the configuration variable AlarmPopupsEnable is set to 1, then setting either the Low Alarm Pop-up Enable or the High Alarm Pop-up Enable, will result in a pop-up dialog being displayed whenever the respective alarm is triggered. It is strongly suggested that this feature be used sparingly.

Sound

The Sound field can be set to blank, 0, 1, or to the name of a .WAV sound file to be played.

If 0, no sound will be played when this alarm is triggered.

If blank or 1, an alarm sound whose properties are configured on the associated Alarm Priority tag will be played.

If the name of a .WAV sound file, it will override any alarm sound configured for the associated Alarm Priority tag. If the specified sound file is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Pump Status properties External Alarms tab

The External Alarms tab is used to display, add or remove separate Alarm tags that are triggered by this Pump Status tag. Use the Add button to create new external Alarm tags and the Delete button to remove them. The new alarm tags will be created as children of the current tag.

Pump Status properties Quality tab

Quality Based On

The Quality Based On field can be tied to a driver tag, a tag that monitors driver communication errors, a register in the PLC or RTU, or any other indication of system health. The tag you are configuring will use that value to set an internal variable named QualityIssue. You may test this value in an expression: [TagName]\QualityIssue.

QualityIssue will be a 0 or 1. "Good Quality" is defined as a value of "0 or Invalid" and "Bad Quality" is defined as any valid, non-zero value. This is consistent with driver communication error values.

Widgets that use the System Style tag will display bad quality using the color set on the Exceptions tab.

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Pump Status properties Display tab

Style

When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance. (See: Style Settings Tags)

The default configuration will search for the first ancestor or then sibling tag of the Style Settings type. If there is none, it will use System Style, which is the default style tag that is automatically part of every new VTScada application.

Off Text and On Text

Certain widgets will display the text you configure here. This text will also be used in confirmation boxes for the control action (if configured).

Display Order

Used to specify the placement of this tag when viewed in an associated station dialog. See Order tab for further details.

Pump Status properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Enable Logging

If values should be logged only while certain conditions are true, you can tie the Enable Logging option to any tag or expression that will change from zero (logging disabled) to non-zero (usually 1; logging enabled).

Closed Pump Status Tag Widgets

The following widgets are available to display information about your application’s Pump Status tags:

Alarm Priority Box | Alarm Priority Icon
Animated Image Widget | Color Blink Widget
Color Box Widget | Color Line Widget
Draw Widget | Indicator Light Widget
Image Change Widget | Momentary Button Widget
Plot Data Widget | Legacy Set Value Button Widget
Legacy Set Value Hotbox Widget | Text Change Widget
Two Color Bar Widget | Equipment / Status Color Indicator
 | Sparklines Widget


String I/O Tags

Counted towards your tag license limit.

This is a legacy tag type. You are advised to use the I/O and Calculations Tag instead.
Use this legacy type only if you are certain that it contains unique features that are absolutely necessary to your work.

String I/O tags are used to read or write text values. They are designed to be simple to configure and straight-forward to use.

If you wish to use a String I/O tag for local storage of values, you must clear the I/O device field. Doing so will allow the String I/O tag to retain values without an attached driver.

Retained or Persisted values

Analog Control and Analog Output tags will both retain their last written value across application restarts. Use these tags when there is a need for a value to persist.

String I/O tags with output enabled, and with no driver ("No tag selected" rather than the default, "[*Driver] None found") will retain their last written value across application restarts.

The Digital Control and Digital Output tags do not have a similar feature, but an analog tag can be used in their place, writing a zero or a one. If the intent is to write a clear zero or one with an analog tag, both the scaled and unscaled range should be adjusted for a minimum value of zero and a maximum value of one, so that scaling does not adjust the values.

Reading Strings

If reading string data, note that not all PLCs will store characters in the same in order in registers. Further, registers may vary in size from one PLC type to another.

If the string read from your registers has characters that are not in the order you expected, use the BuffOrder() function in an expression to swap the order of the characters so that they do match what is expected. Do this by creating one I/O and Calculations tag to read the value, then create a second with an expression to read the value in the first and apply the BuffOrder function. The second I/O and Calculations tag will not count against your license because it does not use a read or write address.

Better practice is to program the PLC to send an integer code that can be mapped to a phrase in VTScada. The result can be used in a multilingual application and can reduce the amount of data transmitted.

Example: A BuffOrder call for a word-sized register with the character order swapped:

BuffOrder([<SourceTag>], 0, 1, 2, N)

...where the value N should be the half the length of the buffer.

Related information:

Best Practices for Tags

Closed String I/O properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

String I/O properties I/O tab

Use this tab to specify the device driver and the address where values are to be read or written.

If output strings are to have a minimum length, you can choose to add spaces, further specifying whether those spaces should be added at the beginning, the end, or equally to either side of the string.

I/O Device

Select the communication driver tag from which data will be read.

By default, the tag will look for an ancestor or sibling tag that is a device driver (*Driver). If none is found, the text "--Missing--" will be displayed. If more than one equally qualified tags are found, "--Error: Multiple Drivers--" will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the field will open a dialog with which you can add or remove a Snapshot Expression or open a selected driver's properties dialog.

Address

Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

For some drivers (SNMP and the OPC Classic Client) an address browser is provided to assist you.

Scan Interval

Provide the frequency, measured in seconds, at which the I/O device should be scanned for new data. Reduce system load by setting this as high as possible, as appropriate for the equipment being monitored. If the I/O Device is a Polling driver, which provides its own scan interval, then this field will not accept data. Otherwise, try to keep scan intervals the same, so far as is reasonable, so that drivers can group (coalesce) reads from equipment where you have sequential addresses.

Manual Data

Sets a constant value that will be used instead of live data. Use when testing a new tag if you need to check behavior when a value is outside the normal operating range. Tags that have manual data are marked by a flashing exclamation mark within any linked widgets. Logged values are marked with an exclamation. Always reset this to blank after testing.

Enable Output

If selected, this input tag may also be used to write data to the specified address of the communication driver. A Security Privilege may be set in the Quality tab to restrict access to this feature.

Values that are to be written may be padded with blank spaces to achieve a minimum length

Pad With Spaces

Enabled only when output is enabled. Selecting this box is the first step in specifying a minimum number of characters to be sent in each write operation.

Minimum Length

Enabled only when Pad With Spaces has been selected. Use this to specify the minimum number of characters to be sent in each write operation.

Justify

Enabled only when Pad With Spaces has been selected. Extra spaces, added to meet the minimum string length, may be added at the beginning of the string (Right Justify), at the end of the string (Left Justify) or equally at either end of the string (Center).

Publisher

Select a Publisher tag if one is required for your configuration. Defaults to [*Publisher]. Eligible tags (Publisher tags that are a direct ancestor, uncle or sibling) will automatically link or you can select a tag manually. VTScada publishing configurations may include:

  • An OPC client when your application has a properly-configured OPC Classic Server Setup tag.
  • A Sparkplug B Edge Node or a Sparkplug B Edge Device.
  • A MultiSpeak interface if properly configure. See: MultiSpeak Support.
  • A Data Diode publisher or client tag.

Publish

This tag will publish data if a publisher is configured and this setting is enabled. If this setting is disabled, the tag will stop publishing data.

String I/O properties: Merit tab

Privilege

Select a custom security privilege (Protect Pages and Output Tags) from this drop down to limit the operation of this control to only those operators who have been granted the matching security privilege.

Questionable Data

Use the Questionable Data parameter to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

String I/O properties: Display tab

Use this tab to set tag's position in the I/O lists of a Site Details page, relative to other String I/O tabs.

String I/O properties: Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Enable Logging

If values should be logged only while certain conditions are true, you can tie the Enable Logging option to any tag or expression that will change from zero (logging disabled) to non-zero (usually 1; logging enabled).

Closed String I/O Tag Widgets

The following widgets are available to display information about, or allow data entry for, your application’s String I/O tags:

Draw Text Widget

Set Analog Value Widget

Droplist Widget

String Entry Widget


Oil & Gas Solutions Tags

Tags described in this section are available only to applications built on the Oil & Gas Solutions layer.

The Oil & Gas Solutions layer provides several specialized tag types designed to allow fast and easy configuration of industry-specific applications using VTScada. Some tags in this layer are designed to be created directly by users, while others are created automatically by those tag types.


Dynacard Upload Driver Tag

Dynacard Upload Driver tags will read Dynacard information from a Pump Off Controller (POC). Create your Dynacard Upload Driver tags as children of one of these.

Dynacard data is read from the device using a series of Modbus commands rather than from a single address. For example, a “read” might consist of first writing to the controller, loading its registers with the data you’re looking for, and then sending several read messages to bring back a large block of data. The Dynacard Upload driver handles all of this sequencing and overhead, but uses the POC's Process Driver, a standard Modbus tag, to send and receive the actual messages.

The Dynacard data read from the device is logged by a linked Dynacard Input Tag that you create. These tags store all the card data in the historian (Min/Max Load, Stroke Length, etc.) but the only data shown onscreen are the position/load pairs that make up the Dynacard graph.

Related information:

...POC-DV8 Tag

POC-Lufkin SAM Well Manager

POC-Unico Tags

Weatherford Tag

Best Practices for Tags

Closed Dynacard Upload Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn orange to indicate that you have applied an override.

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Dynacard Upload Driver properties Communications tab

I/O Device

Select that driver tag within the Pump Off Controller that will connect to the Dynacard data on the device.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Export

Specify a CSV format file, to which the Dynacard's read sequence data will be exported. This will allow you to view the sequence of Modbus reads and the addresses that will be used to read the Dynacard data. The sequence will be in the format that is used by the VTScada sequencer module (Sequencing Reads in a Pump-Off Controller)

The Dynacard Upload Driver tags that are automatically created as children of the various VTScada POC tags come preloaded with the proper sequence and in most cases you will not need to make any changes here.

Import

Specify a CSV format file that holds the Modbus read sequence that you want this Dynacard Upload Driver tag to use when reading the Dynacard data from the PLC. Usually the easiest way to edit the sequence is to export the existing sequence, make any necessary changes, save the file and then import that saved file.

Device Clock Time Zone

Select the time zone that the device uses in order to convert the time-stamped data from the device into UTC for storage in the VTScada historian. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for daylight savings time (DST).

Defaults to the server's time zone, but may be set to use the device's clock if that is configured for UTC, otherwise any time zone where the device is located.

Observe Daylight Saving Time

Select if the RTU clock adjusts itself for Daylight Savings Time. Note that this does not necessarily mean that the RTU is in daylight savings time when this is being set. That is determined by the Windows operating system based on the selected time zone.

Read Number of X-Y Points from a Variable

In most cases, the number of X-Y pairs read from the POC are consistent (e.g. there might be 200 pairs of X-Y data that will then translate to 200 points on the Dynacard graph). Some devices can be configured to provide a different number of points each with each Dynacard. The number of points used is stored in a register that is read from the POC along with the rest of the Dynacard data. If that is the case, the Read Number of X-Y Points from a Variable parameter should be set.

The register in the POC that tells us how many points to read needs to be defined in the sequence CSV (which you can see by hitting the Export button). The register must be read and then assigned to the NumPoints variable using the GetValue_Numeric command (Sequencing Reads in a Pump-Off Controller)

Y Values are Read Before X Values

If not selected, X values are read first.

Use an Epoch Date of 01/01/2000 to Calculate Time Stamp

Select if this POC's time stamp format displays the number of seconds since the start of Jan. 1, 2000 (rather than the VTScada standard, which is the number of seconds since the start of Jan. 1, 1970).

Enable Tracing

If selected, a log file will be created under the Data\Trace folder of the application. This will be updated as each step of the Dynacard read sequence is completed. Traces can be useful when debugging problems with the sequence read, particularly if you have used the Export/Import buttons to change from the default sequence.

Closed Dynacard Upload Driver Tag Widgets

The following widgets are available to display information about your tags:

Draw HDV Widget

Tag List Widget


Dynacard Input Tag

Add a Dynacard Input tag to your pump off controller (POC) tag structure as needed in order to read additional Dynacard data. These tags are created automatically as children of the various POC tags.

Dynacard data is read from the device using a series of Modbus commands rather than from a single address. For example, a “read” might consist of first writing to the controller, then loading its registers with the data you’re looking for, and then sending several read messages to bring back a large block of data). The Dynacard Upload driver handles the reading of this data and then passes the results to the Dynacard Input tags for logging. Dynacard Input tags store all the card data in the historian (Min/Max Load, Stroke Length, etc.) but (currently) the only data shown onscreen are the position/load pairs that make up the Dynacard graph.

Related information:

Best Practices for Tags

Closed Dynacard Input properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Dynacard Input properties I/O tab

I/O Device

The Dynacard Upload Driver Tag that reads the data collected by this tag.

Notebook

If you intend to allow operators to add notes to the Dynacard graph, you must select the Notebook Tags that they will use.

Reference Card

The Dynacard Reference Tag that may be used to store copies of this tag's Dynacard graphs that you would like to be able to view easily at a later time.

Poll Schedule

Determines the times at which the driver will poll the POC for this Dynacard's data.

Dynacard Input properties Data Sets tab

This tab controls how this tag is presented on the Dynagraph page. You can set the color of the lines for this Dynacard and, if this Dynacard can support the reading of multiple cards/data sets in a single read, you can also choose the number of those data sets to display.

Dynacard Input properties Historian tab

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

Closed Dynacard Input Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon


Dynacard Reference Tag

The Dynacard Reference tag allows you to store a particular data set from a Dynacard Input tag as a reference. For example, if you take a known good stroke as a reference, you can display that on the Dynagraph next to the current strokes on an ongoing basis. This allows you to see when the two Dynacard data sets are starting to diverge from one another. References are saved from the Dynacard Graph screen (Dynacard Display).

Related information:

Best Practices for Tags

Closed Dynacard Reference properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Dynacard Reference properties Data Sets tab

Number of Data Sets to Display

Choose how many to display, up to a maximum of 10.

Data Set X Color

Choose the color to be used by the matching data set.

Dynacard Reference properties Historian tab

Historian

If an Historian tag is selected, this tag's run-time values will be saved for use in reports and the Historical Data Viewer. Historian configuration and advanced logging options are described in the discussion of the Historian Tags.

If your goal is to disable logging, set the Enable parameter (below) to 0 rather than deleting the Historian parameter.

There are consequences if you change the selected Historian tag after you have begun collecting data. If you switch to a new Historian (perhaps for organizational or load sharing purposes), the data collected for this tag by the previous Historian will become inaccessible. Historian selection and configuration should be done during the project design stage.

Closed Dynacard Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon


Filtered Tag List Tag

May be used in conjunction with PVR reports. Select this tag rather than a Flow Computer or Meter Run in order to create a report that matches all the tags in the filtered list. This reduces the need to redefine the tag list as new tags are added that match the existing filter.

Related information:

Best Practices for Tags

Closed Filtered Tag List properties, ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Filtered List properties Configuration tab

Root Level Tag

The filter will be applied to all tags below this selection.

Tag Type

Include only tags of the type selected. Typically either PVR Data Sources or Dynacard Input tags.

Filter Expression

Filter expression to be evaluated in tag scope as a condition for including the tag. If this parameter is valid and the expression does not return a value of TRUE, the tag will not be included in the filtered list.

Name Filter

Include only tags whose name matches this value. Wildcards (*) may be used.

Area Filter

Include only tags who area property matches this value. Wildcards (*) may be used.

Recursive Search

If not selected, only immediate children of the specified Root Level Tag will be included (assuming that they match all other filter parameters).

Closed Filtered List Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Color Blink Widget

Color Box Widget

Color Line Widget

Equipment / Status Color Indicator

Indicator Light Widget

Image Change Widget

Text Change Widget


FBx Series DNP3 Driver Tag

FBx Series DNP3 driver uses the standard DNP3 communication protocol to retrieve history logs and audit information using file operations. It requires a child DNP3 driver to operate. This driver typically follows the following process:

  1. A read is requested by the user or triggered by another tag such as a polling tag. The request specifies the file type (such as history or alarm & event) and an instance number that corresponds to your Emerson specification tables.

  2. The FBx Series DNP3 driver references the most recent sequence read (the most recent point of relevant data retrieved) and compares it to the latest sequence available.

  3. The FBx Series DNP3 driver returns a file for each outstanding sequence containing the requested data in binary format

If "Reset Sequence" is selected, the driver will start from sequence 0 and read all available sequences up to the newest sequence available.

RPC Service

This FBx Series driver typically does not have its own dedicated RPC (Remote Procedure Call) service. Instead, it relies on a DNP3 driver (child). When configuring server lists for your FBx Series DNP3 driver communications the sever list must be based on the name of the child DNP3 tag.

Related information:

Best Practices for Tags

FBx Series DNP3 Driver Addressing

Closed FBx Series DNP3 Driver Properties ID Tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Closed FBx Series DNP3 Driver tag Communication Properties Tab

I/O Device

Select the DNP3 driver that will communicate with the equipment.

The FBx Series DNP3 driver does not perform its own communications, it gets its data from binary files using the DNP3 protocol.

Device Clock Time Zone

The time zone of the RTU clock. This is used when logging time stamped information such as alarms, events and history.

File Read Time Limit

The maximum amount of time (in seconds) for each file read in an operation. There can be multiple file reads in an operation, if one of these files takes more than the time set (in seconds) the read will fail.

Maximum Writes per Operation

Breaks down the array of values into multiple arrays and sends them separately.

Number of History Points

The amount of history points configured on the FloBoss3000. 610 is the maximum number of history points available. Determines the number of records that can be read at a time.

Enable Tracing

If selected, a log file will be created under the Data\Trace folder of the application.

Configure the flow computer to be compatible with VTScada's FBx Series DNP3 driver tag. Consider the following settings:
* Disable "Require Login" in the flow computer.
* When configuring FloBoss DNP3 objects for a meter in the flow computer, select components with matching numbers. ie. In the Emerson configuration field tool, if Tag = DP Mtr_1 then Station Assignment = Station_1 and so on.
For more information, refer to your Emerson manual and application.

Troubleshooting

  • Cannot write from the VTScada application to the RTU
    Double-check that your flow computer settings do not have "Require Login" enabled.

FBx Series DNP3 Tag Widgets

FBx Series DNP3 Driver File Read Sequence Info

LCD 7 Segment Widget

Numeric Value Widget

Plot Data Widget

Draw HDV Widget

Sparklines Widget

Comm Line Widget

Comm Indicator Widget

FBx Series DNP3 Driver Stats Dialog


FBx Series DNP3 Driver Addressing

The FBx Series DNP3 Driver can perform standard DNP3 read/write(s) and reads for flow computer specific information (file reads).

There are five file types:

Data Type | Initialism | Description
Alarm | AL | Alarm Logs
Event | EL | Event Logs
History | HL | History Logs
DP Meter Configuration | MCG | Differential pressure meter configuration
Linear Meter Configuration | MCL | Linear meter configuration

A Floboss DNP3 driver address is made up of 2 or 3 parts that are dependent on the file type and separated by a colon.

Link your I/O and Calculations tag to your FBx Series DNP3 Driver tag and a button [...] will appear next to the Read and History address fields. This button opens the Address Select, a tool that will guide you through the addressing options.

Alarm (AL)

File Type:Alarm Instance
ex. AL:0

  • The file type for alarm logs is represented as AL

  • There is one option available for Alarm Instance; Legal is represented by a 0 in the address.

Event (EL)

File Type:Event Instance
ex. EL:0, EL:1

  • The file type for event logs is represented as EL

  • There are two options available for Event Instance; Legal = 0 and Non-legal = 1.

History (HL)

File Type:History Instance Number:History Point
ex. HL:20:3

  • The file type for history logs is represented as HL

  • The history Instance Number corresponds with an area and a time interval. The address assist displays the available options in plain text and converts the entry into a numerical code.

  • The history point refers to a specific parameter. You must refer to your Emerson FloBoss manual for more information.

DP Meter Configuration (MCG)

File Type:Meter Run:Enumeration
ex. MCG:1:64

  • The file type for DP meter configuration is represented as MCG

  • The meter run field requires a discrete numerical value identifying the meter run of the Floboss meter

  • Enumeration identifies the specific parameter being configured. The address assist displays the available options in plain text and converts the entry into a numerical code.

Linear Meter Configuration (MCL)

File Type:Meter Run:Enumeration
ex. MCL:3:7

  • The file type for Linear meter configuration is represented as MCL

  • The meter run field requires a discrete numerical value identifying the meter run of the Floboss meter

  • Enumeration identifies the specific parameter being configured. The address select displays the available options in plain text and converts the entry into a numerical code.

Related information:

FBx Series DNP3 Driver Tag


Flow Computer Tags

Like a station tag, each Flow Computer tag will create many I/O tags that count towards your license limit. The number will vary according to configuration.

This tag provides a complete interface to a flow computer (EFM device) for logged data, process data, alarms and events. The Flow Computer tag is the basic building block of the Oil & Gas Solutions approach to EFM devices. It allows a complete field I/O device (flow computer) to be defined as a single tag structure. This Flow Computer tag will automatically generate child tags to perform the necessary device communication, data reading and logging for compliance data, as well as providing a way to define the device-specific I/O tags used for process monitoring and control functions.

There are many configuration options that control which child tags start and how those child tags operate. Flow Computer Overview and Design describes the details of creating a Flow Computer tag. This topic describes each of the child tags of the Flow Computer tag.

One Flow Computer tag is required for each field I/O device (RTU).

Related information:

Best Practices for Tags

Flow Computer Overview and Design

Flow Computer properties ID tab

In a Flow Computer tag, the Name + Description parameters are used to identify the location of the well.
The Area + Alarm Notification Area parameters are used for grouping, filtering, and roster control

Name & Description

Together, these parameters define a unique identifier for the equipment. In some jurisdictions, the description is typically set to the LSD Closed Legal Subdivision address. or UWI Closed Unique Well Identifier coordinates, but you are free to use whatever value makes sense for your system.

Area & Alarm Notification Area

The area parameter is used to group similar tags together, such as all wells within a given region. An Alarm Notification Area can be defined so that separate rosters can be defined within one region, or so that wells from several fields can use one roster.

The Alarm Notification Area property is inherited by several of the Polling Driver children of this tag and then by any I/O or alarms below those. Child tags that are not expected to generate alarms will inherit the Area property.

If no Alarm Notification Area property is defined, all child tags will default to the Area property.

Flow Computer properties I/O tab

Options within this tab vary depending on the selected Device Type. Several parameters are common to most device types and are described here first:

Configuration Address Override File,
Read Address Override File,
Write Address Override File,
CFX Mapping Override File

Not available for all device types.

Not all values read by the flow computer are represented by tags. Some configuration information, such as the gas composition, orifice, or pipe detail, is read by the Meter Run tag and saved as a single configuration record.

The addresses used to read and write this information are usually standard for a given device type, but if you need to change them you may do so by providing a new mapping CSV file to override the standard version. See CSV Override Files for Flow Computers .

The CFX Mapping Override is used to customize the mapping of values in the flow computer to values in a CFX report. For example, some flow computers might represent the pipe material of "Monel" with a 1, while others use a 4. When VTScada prepares the CFX file, it uses this mapping file to figure out which numerical values represent which physical values.

VTScada already knows how to handle the mapping of most device types, and thus this parameter is not required. This setting is primarily used for devices such as those using the Bristol protocol, which have no standard flow computer firmware.

Device Clock Time Zone

Select the time zone that the device uses in order to convert the time-stamped data from the device into UTC for storage in the VTScada historian. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for daylight savings time (DST).

Defaults to the server's time zone, but may be set to use the device's clock if that is configured for UTC, otherwise any time zone where the device is located.

Station Address (This and station address mode are not used for all types)

The station address of the Modicon programmable logic controller. By default, the PLC Address field is set to 1.

An expression may be used to provide the address if needed. This may be required on a network where the address varies depending on the workstation where the tag is running.

Note that, to create a valid expression for an address that contains non-numeric characters, you must enclose the address in quotation marks. e.g. "31.0.0.0" See: Modbus Plus PLC Addressing.

Station Address Mode

Use to limit the range of allowed addresses. Select according to your hardware.

Should only be adjusted if the Flow Computer/POC has been configured to use one of the specific addressing modes.

Standard Address ... 1 - 255 according to Modbus Protocol. Extended addressing ranges are not supported.

Lufkin ELAM Address ... 1 - 2295

TeleBUS Extended Address ... 1 - 65534

Device Type

Device types are grouped by common options for configuration. Expand the type matching your system for relevant detail.

Closed ABB Totalflow

Station ID

The ID assigned to the Totalflow device.

Security Code

A four-digit number used to access to Totalflow device (if device security is enabled).

Read Events Using the New Events Code

Select this box to cause the alarm and events to be interpreted using the ABB Totalflow driver’s NEWEVENT code in the address, rather than the standard EVENT code.

Closed Bristol

Local Address

Local address of the RTU (1 – 127).

Delete Audit Log on Read

When selected, the audit log (also known as the alarm and event log) is cleared from the RTU every time it is read. This may result in more efficient audit log reads when the log is full.

Bristol Network Tag

This identifies the Bristol Network tag that is to be used by all of the flow computer’s Bristol drivers. As a general rule, there should be one Bristol Network tag for each Port tag in the system that is used by Bristol drivers.

Bristol Master RTU

The RTU that is a level above the current flow computer RTU in the Bristol BSAP network hierarchy. This is only relevant for Bristol RTUs that are not in direct communication with the VTScada server but are instead in communication with an intermediary Bristol RTU on a higher level in the network

Override Files

Because Bristol RTUs do not all use a single industry-standard flow computer program, Bristol Flow Computer tags in VTScada make extensive use of address override files.

By default, files for one type of ControlWave program are selected (sample address: @GV.RUN1_PIPE_DIAM). Files for another type of ControlWave program (sample address: @GV.WELL1_PIPE_DIAM) and for an example 3305 program (sample address: A03.PIPE.DIAM) are included with the Oil & Gas Solutions Layer installation. These files can be found below the Oil & Gas Solutions VTScada directory, (C:\VTScada\O&G Solutions\CSV_Overrides). Ensure that you select the set of files with the correct set of addresses for your RTU’s program. If none is a match, choose a set to use as a template for creating your own custom files that work with your custom program. See CSV Override Files for Flow Computers .

Also, note that not all Bristol flow computer programs necessarily use the same history files. Be sure to check the History Logs tab of the Flow Computer tag configuration to ensure that the addresses are correct.

Closed DCR-1000, Hawk-9500, RealFlo, Tbox

All device types in this group use the following Enron Modbus configuration options. Address override files may be used.

Protocol Options

Selects between RTU and Open Modbus/TCP versions of the base Modbus protocol messaging format. Note that this selection is independent of the communication medium chosen so that Modbus RTU packets can be sent and received on TCP/IP and UDP/IP links as well as on direct serial links.

Modbus Address

The device’s Enron Modbus address. This is a numeric value in the range of 1 to 254 and will need to match the setting of your device. For SCADAPack RealFlo devices, the Enron Modbus device address is typically the Standard Modbus address +1.

Closed RealFlo TeleBUS

User ID and User PIN

These must match one of the users that has been configured within the TeleBUS device. If users have not been configured then the defaults can be used: 1 for the ID and 1 for the PIN.

PLC Address

The PLC address, sometimes called the Modbus address, that uniquely identifies the device. This must match the address setting in the device.

Confirm Attempts

After sending a command to the RTU, VTScada will then poll the reply registers until they confirm receipt of the command (see Section 15 TeleBUS Driver Tags for more information). The Confirm Attempts parameter controls the maximum number of times the reply register will be polled before VTScada gives up and assumes that the command will not be completed.

Confirm Delay

After sending a command to the RTU, VTScada will then poll the reply registers until they confirm receipt of the command (see Section 15 TeleBUS Driver Tags for more information). The Confirm Delay parameter controls the wait time between each of these polls of the reply register. A shorter delay may result in faster polls, while a longer delay will minimize bandwidth by requiring fewer polls.

Calculation Method

The RealFlo implementation of the TeleBUS protocol requires knowledge of the calculation method (AGA-3, AGA-7, etc.). Choose the method that matches the one used by your RTU.

Protocol Options

This determines the protocol used by the TeleBUS driver’s lower level Modbus driver.

Closed FloBoss, & ROC variations

All Device Types in this group use the following ROC configuration options. Address override files cannot be used.

Station ID

The ID assigned to the ROC Device.

Host ID

The ID assigned to the VTScada application.

Station Group

The group assigned to the ROC Device.

Host Group

The group assigned to the VTScada application.

Closed FB3x Series DP & FB3x Series-Linear

All Device Types in this group use the following configuration parameter:

Station ID

The ID assigned to the flow computer.

File Read Time Limit

The maximum amount of time (in seconds) for each file read in an operation.

FBx Series-DP and FB3x Series-Linear will work for FB1x and FB2x series devices, however the gas composition writers will not work.

Flow Computer properties Communications tab

The Communication tab sets up a number of settings common to all field I/O devices that are used by the Flow Computer tag and child tags.

Port

Select the communication port used by the field I/O device driver. For most SCADA protocols (including Enron Modbus and ROC) multiple devices may share a single port to create multi-drop communication links. The port type selected here may be any of the standard VTScada port types:

  • Direct connected serial port
  • Dial up modem connected serial port
  • TCP/IP networked port
  • UDP/IP networked port

Time-Out Limit

The length of time, in seconds, that the driver will wait for a reply from the device when in query response mode.

Retries

The number of communication attempts that will be made by this driver if there is no reply to the initial message. An error will be declared after this number has been exceeded.

Process Data Hold

Select this option to have the process I/O tags hold their last read value in the event of a communication failure with the field I/O device.

Disable All Polling

If selected, all polling for this flow computer will be disabled, regardless of the data read settings or the process I/O scan interval settings.

Polling Group

Sets the polling group in all of the subordinate polling drivers. See the Polling Driver section in the standard VTScada help documentation for more details.

Read Configuration Data

Select the frequency and timing for when configuration data will be read. Options for timing vary according to the selected frequency of reads.

Read Daily Logged Data

Select the frequency and timing for when daily logged data will be read. Options for timing vary according to the selected frequency of reads.

Read Hourly Logged Data

Select the frequency and timing for when hourly logged data will be read. Options for timing vary according to the selected frequency of reads.

Read Alarms and Events

Select the frequency and timing for when alarm and event data will be read. Options for timing vary according to the selected frequency of reads.

ads.

Process I/O Scan Interval

Sets the poll interval (in seconds) for the process I/O data read from the field I/O devices.

This rate can be overridden by the manual polling and fast polling schemes used on some of the graphics displays.

Communications Statistics Reset Schedule

The Flow Computer tag tracks several communications statistics for its child drivers (good polls, last error code, etc.). This parameter determines how often those statistics are reset to zero.

Auto-Synchronize RTU Clock

Sets the schedule at which VTScada will attempt to synchronize the device’s internal clock to match the server’s clock. Note that this will account for the device’s time zone, as set in the Device Clock Time Zone parameter on the Communication tab. (Automatic synchronization may not be available for all device types.)

Clock Sync Deadband

The amount by which the RTU clock must differ from the server’s clock before VTScada will attempt to set the RTU’s clock.

To avoid conflicts if a clock is changed over the threshold of a contract hour, there is logic built in so that the clock will never be automatically set back over the threshold of an hour. For example, if the RTU clock is off by five minutes it will not be corrected from 11:03 to 10:58, but rather VTScada will wait and correct it from 11:06 to 11:01. For this reason, if the RTU clock is off by an hour or more it will not be automatically synchronized and should be explicitly reset through another method.

Flow Computer properties Flow Meters tab

Enable up to 11 Meter Run Tags in the Flow Computer tag. For each meter run that is enabled, a number of child tags are started in the Flow Computer to configure, and gather and display information for that meter run.

Enable

If selected, the appropriate Meter Run tag and its child tags will be created as a child of the flow computer.

Meter Properties Button

Open the properties dialog of the associated Meter Run tag. Meter-specific settings are configured directly in their tag. See Meter Run Tags for more information.

The Flow Computer tag offers a convenient convergence point for the management of your first 11 meter runs, but you also have the option of configuring your Meter Run tags manually anywhere in the application. If your Meter Run tags are not auto-generated by the Flow Computer tag, even if the MR number configured is between 1 and 11, you will not be able to open their properties dialog or enable/disable them from this tab.

Your application is not limited to 11 Meter Runs. Additional Meter Run tags can be created manually.

Flow Computer properties: CFX Setup tab

"CFX" is "Common File Exchange". This is a proprietary file format owned by Flow-Cal which is used to report on the production of gas wells.

VTScada uses the parameters on this tab only when writing a CFX Hourly Report or a CFX Daily Report. The parameters are written directly into the appropriate section of the CFX file.

Flow Computer properties Misc. tab

The Misc. tab is used to configure how the Flow Computer will appear on standard VTScada map displays. If left blank, the default values provide access to a set of standard displays described in Flow Computer Displays.

Latitude

Set the latitude for the Flow Computer in decimal degrees. If not defined, the Flow Computer will not appear on map displays. For this setting, positive numbers define locations east of the prime meridian and negative numbers define locations west of the prime meridian. To set a specific location on a map directly, use the standard VTScada “Update Site Location” tool.

Longitude

Set the longitude for the Flow Computer in decimal degrees. If not defined, the Flow Computer will not appear on map displays. For this setting, positive numbers define locations north of the equator and negative numbers define locations south of the equator. To set a specific location on a map directly, use the standard VTScada “Update Site Location” tool.

Custom Tab Label

Allows you to define a tab label on the built-in standard display for displaying the Custom Page Tab.

Page to Display in Custom Tab

Set the page to display on the built-in standard display that is specific to this Flow Computer. This can be a parameterized page and will be handed the tag value of the Flow Computer tag as its first parameter. Used this way, a single page can be used for multiple Flow Computers on their standard display.

Standard Site Dialog Override

If a page is selected for this parameter, that page will be shown instead of the standard flow computer site details page when a Flow Computer tag is clicked on the site list or the slippy map.

Hide Gas Configuration Tab

Selecting this box will hide the configuration tab on the standard flow computer site details page. As an example, it is appropriate to select this box for flow computers measuring liquids.

Security Privilege - Write Configuration Data to RTU

Set the security privilege required to write configuration changes to the field I/O device. If not selected, no security privilege is required for this action.

Security Privilege – Polling

Set the security privilege required to perform a demand poll of the RTU.

Historian

Selects the historian tag to use in conjunction with the data logging of all child tags. In most cases this can be left as the default, “System Historian”. See standard VTScada documentation for more details.

Display as List of Meters

When selected, the flow computer will appear on the sites page and slippy maps as a list of individual meter runs rather than as a single unified flow computer.

Custom Meter Displays Override Site Dialogs

When selected, clicking on the meter run on the sites page or slippy map will bring up the custom page selected on the Meter Displays tab rather than the standard site dialog with that page as one of the tabs. This setting is applicable only when the Display as List of Meters option is selected.

Contract Hour

Sets the contract hour for the PVR Report. It is used by all meters in a Flow Computer. This field expects the contract hour to be in the form of a single number. (For example, enter 8 and not 8:00:00).

Closed Flow Computer Tag Widgets

The following widgets are available to display information about your Flow Computer tags:

Alarm Priority Box

Alarm Priority Icon


Meter Run Tags

Up to 11 Meter Run tags can be created automatically through the Flow Computer tag. Additional meter run tags can be created manually in your application and linked to a Flow Computer device.

Technically you could create all of your Meter Run tags manually and link them to a Flow Computer Device, however, you would lose the convenience of the automated history tag addressing and other child tag generation that is provided by the Flow Computer tag.
You can enable/disable auto-generated Meter Run tags and quickly visit their properties dialogs from a Flow Computer tag-- but you cannot do this with manually generated Meter Run tags.

The Meter Run tags are Oil & Gas Solutions tags that provide three distinct functions:

  • Provide a container to hold hourly logs, daily logs, and process values, all of which are monitored using automatically-generated child tags.
  • Provide a user interface to change commonly adjusted configuration settings for the flow meter run. (This is done using the flow computer tag's display page, not by configuring the Meter Run tag.)
  • Provide the tools to accept and store the meter run configuration values from the field I/O device.

Related information:

Best Practices for Tags

Closed Meter Run properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

If the tag is configured through the Flow Computer tag, the name will be configured automatically. Meter Run tags configured manually must be named manually.

Area

Inherited from the parent tag.

Description

Configured in the parent tag.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Meter Run properties I/O tab

Run Number

The flow computer associates the Run Number with a specific meter. If the Meter Run tag is auto-generated, the Run number will be auto-generated. When manually selecting a Run Number, keep in mind that only one Meter can successfully register each number to a single Flow Computer. It is possible to manually configure more than one Meter Run tag with the same Run Number but only the first one to call to the register will be successfully registered.

Flow Computer Device

Use the tag selector to link the Meter Run tag to a Flow Computer tag. This tag will auto link to an ancestor, uncle or sibling tag unless otherwise manually configured.

I/O Device

If the Meter Run tag was auto generated, this tag selector will auto link to the same driver configured in the parent Flow Control tag.

Config Scan Trigger

A code representing the Read Configuration Data property, set in the parent tag. For example, "M12" means "Monthly on the 12th". "W1" means "Weekly on the first day of the week". Times are set relative to UTC.

This property defaults to inheriting its value from its Flow Computer tag. Generally, it is recommended to leave this property alone and to set the read times on the Communications tab for the Flow Computer tag's properties dialog instead.

Config Read Timeout

The number of seconds to wait after failing to read the configuration data. Defaults to 10 seconds.

Config Read Retries

The number of attempts to make after failing to read configuration data, and before reporting an error. Defaults to 2.

Meter Run properties Logging tab

Links the Meter Run to the Historian selected in the parent tag.

Meter Run Properties Lab Imports tab

Gas composition lab results can be automatically imported into VTScada and written out to the flow computers. The three settings (File Type, File Name and Unique ID Key) are used to match the entries in those lab results files to the Meter Run tag. ( Importing Multiple Gas Well Lab Results Files).

File Type

The file type is a droplist of all of the currently supported lab results formats. When a file is found whose name matches what a meter run is looking for, VTScada will then analyze it based on the format chosen in this parameter. May be any of:

  • AGAT

  • Cygnet

  • MaxxLink Common

  • OAS Chart

  • PVR

  • PVR FDC

Lab Results File Name

The file name is the first criterion used to link a meter run tag with its proper lab result during an import. When a file is detected in the source directory, VTScada tries to match its file name to the file name specified in each meter run. To allow for some variance in the lab file names (e.g. some files may have a date stamp as part of their name) the meter run’s string need only match part of the actual file name. If, for example, the actual file name is “OAS Chart System 06082017.csv”, entering “OAS Chart System” or simply “OAS” in the meter run’s string would be enough to trigger a match. This matching is not case sensitive.

Unique ID Key

The lab report files frequently contain more than one meter run’s worth of data. For this reason, each file type has one of its columns designated as a unique ID or key field. In order for the gas composition results to be uploaded to the flow computer, the value in this unique ID key field must exactly match the Unique ID Key value that was used when configuring the Meter Runs tag (see the table below for more information on the unique ID key fields for the various lab result formats). Any entries in the lab results that do not match one of the meter runs in the system are simply ignored.

File Type | Unique ID Key Column Number | Unique ID Key Column Name
AGAT | 3 | Sample Point Name
Cygnet | 3 | ProTrend_MeterCode
MaxxLink Common | (Row) 16 | Tag ID
Netflow | 2 | Meter Code
OAS Chart | 2 | Meter ID
ProChart | 3 | Sample Point
PVR | 3 | Sample Point
PVR FDC | 5 | ProTrend Meter Code

Meter Run properties Display tab

Use when you prefer to represent a meter run with your own graphics on the Flow Computer display page. The custom tab label and custom tab page will be used instead of the standard “Process” tab.

Parameterized pages can be used for these displays and will be passed the corresponding meter tag object as the first parameter when calling the page. This allows a single page to be used for multiple meters that have a common configuration.

The most common use of this feature is to display process values graphically. Refer Flow Computer Displays for more details on the standard display for the Flow Computer tag.

Latitude & Longitude

Holds the latitude, longitude for the Meter Run.

Custom Tab Label

Text describing the custom page for each meter that has a custom page. You are advised to make the label as brief as possible while remaining descriptive.

Custom Details Page

Select the page to use for meter. Parameterized pages are recommended, where the parameter specifies which meter is to be shown.

Map Icon

Enable or disable a map icon. Leave as default or select a custom icon.

CFX Meter ID

"CFX" is "Common File Exchange". This is a proprietary file format owned by Flow-Cal which is used to report on the production of gas wells.

The CFX Meter ID entered here is used directly in the Meter ID field of the CFX report. If nothing is entered for this parameter then the meter's run number will be used instead. Note that in older versions of VTScada this parameter was used to set the Meter Name field in the CFX report. Now, the Meter Name field is set to the Meter Run tag's description parameter (if it is valid) or to the Meter Run tag's name.

Meter Runs tag properties History Logs tab

Configure the tags that are created automatically underneath the child ‘Daily’ and ‘Hourly’ context tags.

While a large selection of different history tags can be created from this user interface, some devices (such as the ROC RTUs) allow just about anything to be configured as history and as such have no defaults. Any tags that are created manually underneath the ‘Daily’ or ‘Hourly’ context tags will work alongside any that are created using this interface.

Some device software packages, such as the RealFlo or TFlo, have default sets of history tags. To make configuration of these devices easier, you are able to set the history addresses to the defaults for a particular calculation type. Note that choosing one of these defaults will override all other address changes.

Show History Period

Select either the hourly or the daily history addresses for configuration.

Start with defaults for calculation type

Choose between AGA Closed American Gas Association 3 (1985), AGA-3 (1992), or AGA-7.

AGA-7 is selected by default. Changing this parameter will reset all history addresses to their defaults.

History Addresses

Entering an address for a particular value will cause a child analog status tag to be automatically created in the ‘Daily’ or ‘Hourly’ context that uses this address. The tags for any values which are left blank will not be created.

Note the scroll bar to the right of the list of history addresses. It is not possible to show all of them on the screen at once.

Units

The units entered here will be passed down to the child Analog Status tags.

Meter Runs tag properties PVR Report tab

The PVR Closed Process Volume Report Report Tab is used to assign a PVR Report Definition and one or more PVR Report Entity tags to the Meter Runs tag.

The tools within this tab create the link between a Process Volume Report and the data collected by Flow Meters within your Flow Computer.
You must create the PVR Report Definition tag and configure its PVR Report Entity tags before configuring this tab.

PVR Report Definition

Sets the PVR Report Definition tag used to create the report See: PVR Report Definition Tags

Entity

Sets the PVR Report Entity to include in the Flow Computer PVR Report. See: PVR Report Entity Tag

Closed Meter Run Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Report Display AE Data

Flow Meter Details

Meter Run Summary

Read Configuration Button

Site Details

Site Alarm List

Tag List

Site Icon

Alarm List

Draw HDV


POC-DV8 Tag

The POC-DV8 tag is one of four pump-off controllers.

The Pump-Off Controller (POC) tags are designed as a single parent tag that will allow you to completely control and monitor a pump-off controller device. They contain drivers that have been pre-configured with the addresses and poll sequences necessary for reading Dynacard data, setpoints and other telemetry values.

Related information:

Best Practices for Tags

POC-DV8 Overview

...Pump-Off Controller Displays

...Pump-Off Controller Design

...Dynacard Upload Driver Tag

Closed POC-DV8 properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

In a POC tag, the Name + Description parameters are used to identify the location of the well.
The Area + Alarm Notification Area parameters are used for grouping, filtering, and roster control

Name & Description

Together, these parameters define a unique identifier for the equipment. In some jurisdictions, the description is set to the LSD Closed Legal Subdivision address. or UWI Closed Unique Well Identifier coordinates, but you are free to use whatever value makes sense for your system.

Area & Alarm Notification Area

The area parameter is used to group similar tags together, such as all wells within a given region. An Alarm Notification Area can be defined so that separate rosters can be defined within one region, or so that wells from several fields can use one roster.

The Alarm Notification Area property is inherited by several of the Polling Driver children of this tag and then by any I/O or alarms below those. Child tags that are not expected to generate alarms will inherit the Area property.

If no Alarm Notification Area property is defined, all child tags will default to the Area property.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

POC-DV8 properties communications tab

The communications tab of the DV8 tag properties is where you link a port tag and configure communications settings

Port

Select the port tag, through which VTScada will communicate with this device.

Comm Channel

Select the communication channel and protocol to use for this Modbus Compatible Device driver. This will be one of:

  • Serial RTU Select to use the RTU mode of the Modbus serial communications standard.
  • Serial ASCII Select to use the ASCII mode of the Modbus serial communications standard.
  • SA-85 (MB+) Select to use the Modbus Plus communications protocol via a Modicon SA-85 card.
  • Embedded TCP/IP Select to use the Embedded TCP/IP protocol.
  • Open Modbus TCP Select to use the Modicon Open Modbus/TCP specification to receive Modbus protocol over Ethernet TCP/IP.

Station Address

The station address of the Modicon programmable logic controller. By default, the PLC Address field is set to 1.

An expression may be used to provide the address if needed. This may be required on a network where the address varies depending on the workstation where the tag is running.

Note that, to create a valid expression for an address that contains non-numeric characters, you must enclose the address in quotation marks. e.g. "31.0.0.0" See: Modbus Plus PLC Addressing.

Station Address Mode

Use to limit the range of allowed addresses. Select according to your hardware.

Should only be adjusted if the Flow Computer/POC has been configured to use one of the specific addressing modes.

Standard Address ... 1 - 255 according to Modbus Protocol. Extended addressing ranges are not supported.

Lufkin ELAM Address ... 1 - 2295

TeleBUS Extended Address ... 1 - 65534

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Modicon Typed Addr 1 Offset

Applies the offset for "Type specified" Modbus addresses.

"Type specified" means addresses such as the HC1 and IR2 format. This does not apply to addresses written as only numbers. (For example, 40001 is always the first address in the 40000 block, and is equivalent to HR1 when ModiconTypedAddr1Offset is 0, or HR0 when ModiconTypedAddr1Offset is 1)

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Device Clock Time Zone

Select the time zone that the device uses in order to convert the time-stamped data from the device into UTC for storage in the VTScada historian. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for daylight savings time (DST).

Defaults to the server's time zone, but may be set to use the device's clock if that is configured for UTC, otherwise any time zone where the device is located.

Observe Daylight Saving Time

Select if the RTU clock adjusts itself for Daylight Savings Time. Note that this does not necessarily mean that the RTU is in daylight savings time when this is being set. That is determined by the Windows operating system based on the selected time zone.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

POC-DV8 tag properties polling tab

Configure a polling group name, polling schedules and polling interval

Disable All Polling

Select if communications are to be disabled at this site.

Polling Group

Provide a group name that will be used by the polling drivers within this tag. Groups ensure that polling drivers sharing a connection do not all try to poll at the same time. Each child Polling Driver will have its own sequence number within the group.

Useful only when two or more schedules match.

Process I/O Scan Interval

Measured in seconds, this sets the frequency at which process data is read.

Enable Setpoints Driver

If selected, tags in the \Process\Setpoints context will be polled using a dedicated setpoints driver instead of using the standard process driver. This allows the setpoints to be polled at a different rate from the other data.

Schedule Settings

Each polling schedule, when enabled, will offer a choice of "Hourly at", Daily, "Weekly on", or "Monthly on".

In each case, additional selections will be available, relevant to the overall scheduling of the poll.

Schedules are disabled by default. Click the 'disabled' drop-down and select another option for more options to appear.

Min Manual Poll Interval

Sets a minimum time between manual polls.

POC-DV8 properties settings tab

Custom settings including information relavant to widget and overview displays, and security.

Labels and Units, X-Axis & Y-Axis

These are pre-configured with standard values, but you are free to provide your own labels and units to describe your system.

Hide Surface Cards on Graph

When selected, surface cards will not be shown.

Latitude and Longitude

Configure with the controller's location in order to display this site on a map.

Custom Page to Open from Site Maps

By default, the built-in Unico Overview page will open in response to an operator clicking on a site icon. You may create your own page, to use instead. Note that your custom page must be parameterized, taking a POC tag as its parameter.

Before selecting security privileges, you must first create those custom privileges. See: Protect Pages and Output Tags

Security Privilege - Modify Setpoints

Select the custom security privilege that you created in order to protect setpoints within this device.

Security Privilege - Polling Control

Select the custom security privilege that you created in order to protect polling control within this device.

Closed POC-DV8 tag widgets

...Polling Indicator Widget

...Flow Computer Site Draw Widget

...Flow Meter Site Draw Widget

...Dynacard Display Widget

Alarm Priority Box

Alarm Priority Icon

Active Indicator Widget

Data Age Widget

Dynacard Page Button Widget

POC Manual Process Poll Widget

Site Alarm List

Tag List Widget

Site Icon Widget

Alarm List

Draw HDV Widget


POC-Lufkin SAM Well Manager

The POC-Lufkin SAM Well Manager is one of four pump-off controllers.

The Pump-Off Controller (POC) tags are designed as a single parent tag that will allow you to completely control and monitor a pump-off controller device. They contain drivers that have been pre-configured with the addresses and poll sequences necessary for reading Dynacard data, setpoints and other telemetry values.

Related information:

Best Practices for Tags

Closed POC-Lufkin SAM Well Manager properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

In a POC tag, the Name + Description parameters are used to identify the location of the well.
The Area + Alarm Notification Area parameters are used for grouping, filtering, and roster control

Name & Description

Together, these parameters define a unique identifier for the equipment. In some jurisdictions, the description is typically set to the LSD Closed Legal Subdivision address. or UWI Closed Unique Well Identifier coordinates, but you are free to use whatever value makes sense for your system.

Area & Alarm Notification Area

The area parameter is used to group similar tags together, such as all wells within a given region. An Alarm Notification Area can be defined so that separate rosters can be defined within one region, or so that wells from several fields can use one roster.

The Alarm Notification Area property is inherited by several of the Polling Driver children of this tag and then by any I/O or alarms below those. Child tags that are not expected to generate alarms will inherit the Area property.

If no Alarm Notification Area property is defined, all child tags will default to the Area property.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

POC-Lufkin SAM Well Manager properties Communications tab

Port

Select the port tag, through which VTScada will communicate with this device.

Comm Channel

Select the communication channel and protocol to use for this Modbus Compatible Device driver. This will be one of:

  • Serial RTU Select to use the RTU mode of the Modbus serial communications standard.
  • Serial ASCII Select to use the ASCII mode of the Modbus serial communications standard.
  • SA-85 (MB+) Select to use the Modbus Plus communications protocol via a Modicon SA-85 card.
  • Embedded TCP/IP Select to use the Embedded TCP/IP protocol.
  • Open Modbus TCP Select to use the Modicon Open Modbus/TCP specification to receive Modbus protocol over Ethernet TCP/IP.

Station Address

The station address of the Modicon programmable logic controller. By default, the PLC Address field is set to 1.

An expression may be used to provide the address if needed. This may be required on a network where the address varies depending on the workstation where the tag is running.

Note that, to create a valid expression for an address that contains non-numeric characters, you must enclose the address in quotation marks. e.g. "31.0.0.0" See: Modbus Plus PLC Addressing.

Station Address Mode

Use to limit the range of allowed addresses. Select according to your hardware.

Should only be adjusted if the Flow Computer/POC has been configured to use one of the specific addressing modes.

Standard Address ... 1 - 255 according to Modbus Protocol. Extended addressing ranges are not supported.

Lufkin ELAM Address ... 1 - 2295

TeleBUS Extended Address ... 1 - 65534

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Device Clock Time Zone

Select the time zone that the device uses in order to convert the time-stamped data from the device into UTC for storage in the VTScada historian. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for daylight savings time (DST).

Defaults to the server's time zone, but may be set to use the device's clock if that is configured for UTC, otherwise any time zone where the device is located.

Observe Daylight Saving Time

Select if the RTU clock adjusts itself for Daylight Savings Time. Note that this does not necessarily mean that the RTU is in daylight savings time when this is being set. That is determined by the Windows operating system based on the selected time zone.

Read Number of X-Y Points from a Variable

Data is read from a set number of registers. Other information is read at the same time, including a “NumPoints” variable. This states how many of the registers contain actual data.

If the “Read Number of X-Y Points from a Variable” box is selected, VTScada will discard all of the extra registers beyond the number stated in NumPoints before passing the read results back to the Dynacard_Input tags. (See also: Dynacard Upload Driver Tag)

POC-Lufkin SAM Well Manager properties Polling tab

Disable All Polling

Select if communications are to be disabled at this site.

Polling Group

Provide a group name that will be used by the polling drivers within this tag. Groups ensure that polling drivers sharing a connection do not all try to poll at the same time. Each child Polling Driver will have its own sequence number within the group.

Useful only when two or more schedules match.

Process I/O Scan Interval

Measured in seconds, this sets the frequency at which process data is read.

Enable Setpoints Driver

If selected, tags in the \Process\Setpoints context will be polled using a dedicated setpoints driver instead of using the standard process driver. This allows the setpoints to be polled at a different rate from the other data.

Schedule Settings

Each polling schedule, when enabled, will offer a choice of "Hourly at", Daily, "Weekly on", or "Monthly on".

In each case, additional selections will be available, relevant to the overall scheduling of the poll.

Min Manual Poll Interval

Sets a minimum time between manual polls.

POC-Lufkin SAM Well Manager properties Settings tab

Labels and Units, X-Axis & Y-Axis

These are pre-configured with standard values, but you are free to provide your own labels and units to describe your system.

Hide Surface Cards on Graph

When selected, surface cards will not be shown.

Latitude and Longitude

Configure with the controller's location in order to display this site on a map.

Custom Page to Open from Site Maps

By default, the built-in SAM Overview page will open in response to an operator clicking on a site icon. You may create your own page, to use instead. Note that your custom page must be parameterized, taking a POC tag as its parameter.

Before selecting security privileges, you must first create those custom privileges. See: Protect Pages and Output Tags

Security Privilege - Modify Setpoints

Select the custom security privilege that you created in order to protect setpoints within this device.

Security Privilege - Polling Control

Select the custom security privilege that you created in order to protect polling control within this device.

Closed POC-Lufkin SAM Well Manager Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Active Indicator

Data Age

Generic Driver Statistic

Polling Indicator

Dynacard Page Button

Dynacard Page Hotbox

Generic Driver Statistic

POC Manual Process Poll

POC Reset Comm Counts

Dynacard Display

Site Alarm List

Tag List

Site Icon

Alarm list

Draw HDV


POC-Unico Tags

The POC-Unico Well Manager is one of four pump-off controllers.

The Pump-Off Controller (POC) tags are designed as a single parent tag that will allow you to completely control and monitor a pump-off controller device. They contain drivers that have been pre-configured with the addresses and poll sequences necessary for reading Dynacard data, setpoints and other telemetry values.

Related information:

Best Practices for Tags

Closed POC-Unico properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

In a POC tag, the Name + Description parameters are used to identify the location of the well.
The Area + Alarm Notification Area parameters are used for grouping, filtering, and roster control

Name & Description

Together, these parameters define a unique identifier for the equipment. In some jurisdictions, the description is set to the LSD Closed Legal Subdivision address. or UWI Closed Unique Well Identifier coordinates, but you are free to use whatever value makes sense for your system.

Area & Alarm Notification Area

The area parameter is used to group similar tags together, such as all wells within a given region. An Alarm Notification Area can be defined so that separate rosters can be defined within one region, or so that wells from several fields can use one roster.

The Alarm Notification Area property is inherited by several of the Polling Driver children of this tag and then by any I/O or alarms below those. Child tags that are not expected to generate alarms will inherit the Area property.

If no Alarm Notification Area property is defined, all child tags will default to the Area property.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

POC-Unico Communications properties tab

Port

Select the port tag, through which VTScada will communicate with this device.

Comm Channel

Select the communication channel and protocol to use for this Modbus Compatible Device driver. This will be one of:

  • Serial RTU Select to use the RTU mode of the Modbus serial communications standard.
  • Serial ASCII Select to use the ASCII mode of the Modbus serial communications standard.
  • SA-85 (MB+) Select to use the Modbus Plus communications protocol via a Modicon SA-85 card.
  • Embedded TCP/IP Select to use the Embedded TCP/IP protocol.
  • Open Modbus TCP Select to use the Modicon Open Modbus/TCP specification to receive Modbus protocol over Ethernet TCP/IP.

Station Address

The station address of the Modicon programmable logic controller. By default, the PLC Address field is set to 1.

An expression may be used to provide the address if needed. This may be required on a network where the address varies depending on the workstation where the tag is running.

Note that, to create a valid expression for an address that contains non-numeric characters, you must enclose the address in quotation marks. e.g. "31.0.0.0" See: Modbus Plus PLC Addressing.

Station Address Mode

Use to limit the range of allowed addresses. Select according to your hardware.

Should only be adjusted if the Flow Computer/POC has been configured to use one of the specific addressing modes.

Standard Address ... 1 - 255 according to Modbus Protocol. Extended addressing ranges are not supported.

Lufkin ELAM Address ... 1 - 2295

TeleBUS Extended Address ... 1 - 65534

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Modicon Typed Addr 1 Offset

Applies the offset for "Type specified" Modbus addresses.

"Type specified" means addresses such as the HC1 and IR2 format. This does not apply to addresses written as only numbers. (For example, 40001 is always the first address in the 40000 block, and is equivalent to HR1 when ModiconTypedAddr1Offset is 0, or HR0 when ModiconTypedAddr1Offset is 1)

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Device Clock Time Zone

Select the time zone that the device uses in order to convert the time-stamped data from the device into UTC for storage in the VTScada historian. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for daylight savings time (DST).

Defaults to the server's time zone, but may be set to use the device's clock if that is configured for UTC, otherwise any time zone where the device is located.

Observe Daylight Saving Time

Select if the RTU clock adjusts itself for Daylight Savings Time. Note that this does not necessarily mean that the RTU is in daylight savings time when this is being set. That is determined by the Windows operating system based on the selected time zone.

POC-Unico Polling properties tab

Disable All Polling

Select if communications are to be disabled at this site.

Polling Group

Provide a group name that will be used by the polling drivers within this tag. Groups ensure that polling drivers sharing a connection do not all try to poll at the same time. Each child Polling Driver will have its own sequence number within the group.

Useful only when two or more schedules match.

Process I/O Scan Interval

Measured in seconds, this sets the frequency at which process data is read.

Enable Setpoints Driver

If selected, tags in the \Process\Setpoints context will be polled using a dedicated setpoints driver instead of using the standard process driver. This allows the setpoints to be polled at a different rate from the other data.

Schedule Settings

Each polling schedule, when enabled, will offer a choice of "Hourly at", Daily, "Weekly on", or "Monthly on".

In each case, additional selections will be available, relevant to the overall scheduling of the poll.

Min Manual Poll Interval

Sets a minimum time between manual polls.

POC-Unico Settings properties tab

Labels and Units, X-Axis & Y-Axis

These are pre-configured with standard values, but you are free to provide your own labels and units to describe your system.

Hide Surface Cards on Graph

When selected, surface cards will not be shown.

Latitude and Longitude

Configure with the controller's location in order to display this site on a map.

Custom Page to Open from Site Maps

By default, the built-in Unico Overview page will open in response to an operator clicking on a site icon. You may create your own page, to use instead. Note that your custom page must be parameterized, taking a POC tag as its parameter.

Before selecting security privileges, you must first create those custom privileges. See: Protect Pages and Output Tags

Security Privilege - Modify Setpoints

Select the custom security privilege that you created in order to protect setpoints within this device.

Security Privilege - Polling Control

Select the custom security privilege that you created in order to protect polling control within this device.

Closed POC-Unico Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Active Indicator

Data Age

Polling Indicator

Dynacard Page Button

POC Manuall Process Poll Button

POC Reset Comm Counts Button

Site Alarm List

Tag list

Site Icon

Alarm List

Draw HDV


Poll Control Tag

Used in conjunction with a standard VTScada Polling Driver tag to provide increased options for poll scheduling and for on-demand polling. Based on its scan interval, poll schedule and poll trigger parameters, the Polling Control tag will trigger an on-demand poll in the Polling Driver.

Polling Control tags are not used with Flow Computers or Pump Off Controllers, both of which have their own poll scheduling parameters built-in. Instead, this tag is intended to give flow-computer-like polling control to standard VTScada tags.

This tag keeps tracks the polling statistics of its driver, making those accessible via the Generic Driver Statistic Widget. These statistics are reset to zero, based on the Statistics Reset Schedule.

Related information:

Best Practices for Tags

Closed X properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn orange to indicate that you have applied an override.

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Polling Control properties Communications tab

Poll Driver Tag

Specify which Polling Driver is to be controlled by this tag.

Scan Interval

Optional. Provides the same configuration available within the Polling Driver: a regular interval, measured in seconds, for when the device will be polled.

Poll Schedule

The drop-down includes options for Hourly, Daily, Weekly or Monthly.

For each option, controls are provided to specify when and how often the poll will be made. The sample images shows a poll schedule of Hourly, beginning at midnight and repeating every hour.

Poll Trigger

Optional. Allows a poll to be made upon a triggering event. This might be an expression that you create or a link to any tag. A trigger is defined as a value changing from zero to non-zero.

Statistics Reset Schedule

Polling Control properties Settings tab

Security Privilege - Manual Poll

This tag can be drawn as a button that operators may press to force a manual poll of the equipment. Select a custom security privilege that you created earlier in order to restrict who may use that button. (See: Protect Pages and Output Tags)

Site Tag

Closed Polling Control Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon


PVR Report Definition Tags

The data for these reports comes primarily from your Meter Run Tags , configured within Flow Computer Tags . Alternatively, you may use a PVR Report Line Tag to retrieve data from a source other than Meter Runs.

PVR stands for Production Volume Reporting. These provide a way to create a daily report with flexible data content. The report will typically run over a 24-hour period from a configured start time, ignoring the end date of the report generation tools. The report is designed for use with the Oil and Gas Solutions layer, and the times are strongly linked to production data and contract hours.

The report production date is based on the report start date, and the report contract hour is configured individually for each tag included in the report.

When creating this tag, the number of different PVR entities must be selected and a corresponding number of PVR Report Entity Tag child tags will be added automatically. Each of the child PVR Report Entity tags must be configured individually, with each tag providing the content of a row within the report.

The PVR Report Definition tag itself cannot be drawn as a widget on any page.

Related information:

Best Practices for Tags

Closed PVR Report properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, and Description.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn orange to indicate that you have applied an override.

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

PVR Report Definition properties Settings tab

Use this tab to define the number of Report Entity tags to create. Each Report Entity tag defines one row within the report and each must be configured individually.

The maximum number for one report is 20.

Also use this tab to choose whether to include title rows in the report. Selected by default.


PVR Report Entity Tag

PVR Report Entity tags are created automatically as children of PVR Report Definition Tags.
Do not create these tags yourself. To add more to a PVR Report, use the Number of Report Entity Tags control within the parent tag.

Configuration of each PVR Report Entity tag is up to you and must be done manually.

A PVR Entity tag defines the data (report columns) from Meter Run Tags , to be included in a row of a PVR Report for a Flow Computer (Flow Computer Tags ). When the report runs, a row will be created for each meter run / report entity pair that you configure.

Each Report Entity tag can have up to 20 columns.

Related information:

Best Practices for Tags

Closed PVR Report Entity properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Defined automatically by the parent tag. Do not change.

Area

Inherited from the parent tag. There is no reason to change this.

Description

Not useful for PVR Report Enity tags.

PVR Report Entity properties Entity Parameters tab

Parameter labels may vary according to the selected Value Type. "Unused" indicates that a parameter does not apply to the selected Value Type.

Configure column numbers in order beginning with 1.
For each column, select the Value Type before configuring any other property of a column.

It is normal for the parameter backgrounds to turn orange when configured. The Report Entity tags are created automatically, therefore your configuration will count as overrides of the properties.

Make a note of the content of each column. You will need this information later when matching Flow Meters to Report Entities.

Title

Optional. Sets the title to use in the column for this entity.

Precision

Scaling Factor

Value Types:

May be any of the following. For each Value Type, other related parameters are described as appropriate.

Text

A constant, user-defined text string. No other parameters apply.

Tag Variable

Variable or parameter of a tag below a flow meter. For example, a tag's ShortName, Description, etc. The Value Source must include the path to the tag within the Meter structure, followed by the parameter or variable name.

Precision

Optional. Used only with numeric value.

Scaling Factor

Optional. Applied to parameters having a numeric value.

Value Source

The path to the tag and the name of the parameter within that tag. Paths are relative to the Meter Run tag.
Example: Process\Energy\ShortName

Convert UWI

Converts a UWI or LSD value to a standard PVR formatted value, removing any spaces or special characters from the UWI. The following special characters are removed from the UWI string: (-_: /\)

Value Source

The Value Source should be the tag parameter or variable that contains the UWI, relative to the tag that is the basis for the report. For example, if you want to use the UWI from your Meter Run tag’s description then your source would simply be Description

Contract Hour Data

Used to retrieve daily history values that have been timestamped at a particular contract hour. Typically used for devices that have daily logs.

Precision

Specifies the number of decimal places to display

Scaling Factor

The value is multiplied by the scaling factor prior to being added to the report

Value Source

The Value Source should be the name of the tag that is associated with the history, relative to the tag that is the basis for the report. For example, Daily\Flow Duration

Time Frame Notes

This value type will return the oldest value logged between the day’s start time and its end time.

The start time is taken to be:

Production Date + 24 Hours + Contract Hour

While the end time is taken to be:

Start time + 23 hours, 59 minutes and 59 seconds.

For example, if the report production date is June 5th and the contract hour is 8, the report will attempt to retrieve data with a timestamp of June 6th at 08:00.

Contract Hour Data (Lag)

Similar to Contract Hour Data value type, but without the 24-hour time shift.

Time Frame Notes

This value type will return the oldest value logged between the day’s start time and its end time.

The start time is taken to be:

Production Date + Contract Hour

While the end time is taken to be:

Start time + 23 hours, 59 minutes and 59 seconds.

For example, if the report production date is June 5th and the contract hour is 8, the report will attempt to retrieve data with a timestamp of June 5th at 08:00.

Production Date

Outputs the production date of the report in a user-defined format.

Value Source

Specifies the format of the date. Refer to reference topics, Date Formatting Codes or Date Formatting Strings

Data Without Timestamp

Used to report daily values from a device that does not support timestamped data.

Precision

Specifies the number of decimal places to display

Scaling Factor

The value is multiplied by the scaling factor prior to being added to the report

Value Source

The Value Source should be the name of the tag that is associated with the history, relative to the tag that is the basis for the report. For example, “Process\Energy”.

Time Frame Notes

This value type will return the oldest value logged between the day’s start time and its end time.

The start time is taken to be:

Production Date + Contract Hour

The end time is taken to be the start time + 24 hours

Daily Statistic

Used to retrieve a simple statistical value of a tag’s historical values over the contract hour period.

Precision

Specifies the number of decimal places to display

Scaling Factor

The value is multiplied by the scaling factor prior to being added to the report

Value Source

The Value Source should be the name of the tag that is associated with the history, relative to the tag that is the basis for the report. For example, “Process\Energy”.

Column Stat Type

The statistical calculation to perform on the data.

Time Frame Notes

This value type will return the oldest value logged between the day’s start time and its end time.

The start time is taken to be:

Production Date + Contract Hour

The end time is taken to be the start time + 24 hours

Expression

Used to calculate an expression at the time the report is run. The expression must be a script expression, as steady state expressions are not supported.

Precision

If result is numeric, specifies the number of decimal places to display

Scaling Factor

If result is numeric, the value is multiplied by the scaling factor prior to being added to the report

Value Source

Script expression to run

Time Frame Notes

Provides the results of the expression at the time when the report is run

Complex Variable Log

Most I/O tag types log a single value to the Historian. Some tag types, like the Meter Run tag, log several (or in this case hundreds) of variables as a single record (pipe diameter, gas compositions, etc.). For our purposes as they relate to PVR reports, we are calling these tags that log multiple values “complex” tags.

The Complex Variable Log value type allows you to add to your PVR report a single logged variable from a complex tag. Unlike all of the other value type options, which give you their value at a snapshot in time, this will produce the full list of all values saved to the historian within the time-span of the report. Note that this means that an entity containing Complex Variable Log value types will not necessarily give you a single line in the PVR report; it may give you multiple lines, or one line, or none at all, depending on how many records exist in the historian.

The complex tag itself, and any settings pertaining to it, is configured in the Settings tab.

Precision

Specifies the number of decimal places to display for each logged value

Scaling Factor

Each logged value is multiplied by the scaling factor prior to being added to the report

Value Source

The Value Source should be the name of the variable within the complex tag

Time Frame Notes

This value type will return every record logged to this historian between the day’s start time and its end time.

The start time is taken to be:

Production Date + Contract Hour

The end time is taken to be the start time + 24 hours

Daily Summary View

The Value Types: Contract Hour Data, Data Without TimeStamp, Contract Hour Data (Lag), Data Without TimeStamp, and Daily Statistic, provide a means of creating single- or multi-day summaries (shown below). The number of days and offset from production date can be specified, as well as the type of statistic (total, average, maximum, minimum) to apply to the data set.

Value is a Time Stamp

Shown only for Value Type, Complex Variable Log.

PVR Report Entity properties Settings tab

Omit from Title

Will prevent this entity’s column titles from being output to the report, even if the parent PVR Report Definition tag is configured to include titles.

Complex Variable Log Source

This option is used in conjunction with the Complex Variable Log value type (previous tab). Enter the name of the tag that is associated with the history, relative to the tag that is the basis of the report. It is within this tag that the report will search for the variable name specified by the value source field of a complex variable log.

Note that this single tag will be used by each of the complex variable log entries defined on the “Entity Parameters” tab. If you need to get values from another tag...

Only include records where the [image] variable is equal to [image].

This will filter the results of the complex variable log search to return only history records where the specified variable or parameter is equal to the specified value. This variable may be, but does not have to be, one of the variables that are specified on the “Entity Parameters” tab

Use record generation timestamp for complex variable logs

Determines how the historian searches for data in the complex variable log. To understand this parameter, it is important to understand how the VTScada historian logs data.

When any tagged record is logged to the VTScada historian, it is logged in conjunction with a timestamp. Often this timestamp is the current time when the variable is logged, but sometimes a specific timestamp is used instead (for example, when hourly or daily history logs are read, data from many days or hours are entered into the historian at once). In addition to this primary timestamp, the historian also logs the time at which the record was written.

When the historian is later queried for data, it is the standard timestamp that is used to define the data range (e.g. bring back all records between Jan. 1 and Jan. 2). This is usually the desired behavior for the complex variable logs as well, but on rare occasions it may be necessary to bring back all records that were written within a certain period, regardless of whether the data contained in those records is associated with that time period or not.

Select this option to allow that to happen.

Days of history to search when using record generation timestamp

Determines how far back to go for history when the “Use Record Generation Timestamp for Complex Variable Logs” box is checked.

All queries to the VTScada historian are done against the standard timestamp associated with the data. In order to use record generation timestamps instead, the PVR report queries a large amount of history and then filters it based on the generation timestamp afterward. This parameter determines how far back to go for data, noting that the more data you capture, the longer the report will take to run.


PVR Report Line Tag

A PVR Report Line Item is the generic equivalent of the Meter Run tag. Use this when you need to define a PVR report to run against tags that are not part of a Flow Computer. It will work in much the same way, except that the parameter scoping that you use when building the associated PVR Report Entity Tag will be from the perspective of the PVR Report Line Item instead of from the Meter Run.

You will need detailed knowledge of tags in the site you wish to use as the data source for this report before using this tag. Configure the matching PVR Report Entity tag before creating the PVR Report Line tag.

Related information:

Best Practices for Tags

Closed PVR Report Line Item properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together.

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

PVR Report Line Item, PVR Report tab

Variable Resolution Scope (Site Tag)

Select a site tag that will provide the data for this report line item. This takes the place of a Meter Run tag that would otherwise be used.

PVR Report Definition

Select the PVR Report Entity Tag that defines what data from the site tag will be displayed in the columns of the report. The numbers following this selection match the column definitions within the Entity tag, allowing you to choose which of the defined columns to use.

Contract Hour

Sets the contract hour for the PVR Report. It is used by all meters in a Flow Computer. This field expects the contract hour to be in the format of a single number (i.e. enter 8 and not 8:00:00).

Device Clock Time Zone

Select the time zone that the device uses in order to convert the time-stamped data from the device into UTC for storage in the VTScada historian. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for daylight savings time (DST).

Defaults to the server's time zone, but may be set to use the device's clock if that is configured for UTC, otherwise any time zone where the device is located.


SDS Driver Tag

SDS stands for SCADA Data Solutions, the provider of an alternative cloud service to store, process and access data from Emerson® Zedi Smart-Alek® remote electronic flow meter devices. This data can be pulled into VTScada using the SDS Driver. Note that, because the SDS service is not managed by Trihedral Engineering Ltd., any questions regarding the configuration of Zedi Smart-Alek® devices to use the SDS service should be directed to SCADA Data Solutions.

When using the SDS Driver, VTScada must be able to reach the configured URL (typically https://service.scadadatasolutions.com) on the configured port (typically 443).

Related information:

Best Practices for Tags

Closed SDS Driver properties, ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Server List

Select (or create) a named server list. (Driver Server Lists) Servers for the list must be defined using the Application Configuration dialog, as described in Servers for Specific Services. Smaller sites that do not have multiple servers, or that use only the default server list, need not configure this field.

SDS Driver properties, Settings tab

The SDS Driver Settings tab governs the operation of the driver, service authentication, and device identification. To communicate with the SDS service, all parameters must be configured.

URL

The URL of the SDS service to query. Will typically be https://service.scadadatasolutions.com.

API Key

Authentication key used to access data in the cloud service. This key should be provided by SDS when registering your devices with the service.

History Read Limit (Days)

Maximum number of days in the past to read data for.

Meter Type

The type of Zedi Smart-Alek® meter. May be "Orifice" or "E-Tube". The type of meter informs the calculations done on data in processed data requests (GetProcessedData and GetPeriodicData API calls).

Device ID

The identifier of the device whose data is being read. Like the API key, this should be supplied by SDS.

Polling Interval (s)

How often, in seconds, to poll the SDS service.

The SDS driver will poll all data at this configured rate, and will not obey scan intervals configured in I/O tags.

Connect Time Limit (s)

The length of time, in seconds, that the driver should wait for a reply from the device.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

External Trigger

An additional, optional trigger to start reads.

Trace Level

Controls debug logging. A value of 0 (default) disables debug logging, while a value of 3 sets the logging level to high. Logs are recorded to the application "Data/TraceFiles" folder.

SDS Driver Properties, Flow Settings tab

It is expected that in many applications, the SDS driver will be used with a Flow Computer. If so, the Flow Computer tag selected here will disable the remaining flow setting parameters.

Otherwise, use this tab to enter a static set of flow settings to be used for processed data reads (GetProcessedData and GetPeriodicData API calls).

Flow Computer

The linked Flow Computer. When used with a Flow Computer, the flow settings are managed from the Flow Computer page's Configuration tab.

Base Temperature

Baseline temperature of the meter.

Base Pressure

Baseline pressure of the meter

Effluent Correction Factor

Correction factor for effluent.

Contract Hour

Contract hour used for daily history reads.

Orifice Material

Material of the orifice. Options are: 304_316 Stainless Steel, 304 Stainless Steel, 316 Stainless Steel, Monel, and Carbon Steel.

Orifice Ref Diameter

Reference diameter of the orifice.

Orifice Ref Temp

Reference temperature the orifice.

Pipe Material

Material of the pipe. Options are: 304_316 Stainless Steel, 304 Stainless Steel, 316 Stainless Steel, Monel, and Carbon Steel.

Pipe Ref Diameter

Reference diameter of the pipe.

Pipe Ref Temp

Reference temperature the pipe.

Pressure Sensor Type

Type of pressure sensor. Options are Gauge and Absolute.

Atmospheric Pressure

Atmospheric pressure at the meter.

Isentropic Exponent

Isentropic exponent at the meter.

Pressure Tap Location

Location of the tap in relation to the orifice. Options are Upstream or Downstream.

Viscosity

Viscosity of the contents of the pipe.

Gas Composition

Composition of gasses in the pipe, expressed in mole fractions. Note that the gas composition components must sum to 1.

Closed SDS Driver Tag Widgets

The following widgets are available to display information about your SDS Driver tags:

Alarm Priority Box

Alarm Priority Icon

Comm Indicator Widget

Comm Line Widget

Data Age Widget

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget

Sparklines Widget


SDS Driver Addressing

All of the addresses in the following table are considered Historical Addresses, and therefore must be configured as such in I/O tags in order to function correctly.

API Source | Point Address | Point Description
GetAlarms | A:spHigh | High static pressure alarm
GetAlarms | A:spLow | Low static pressure alarm
GetAlarms | A:spValue | Alarm static pressure value
GetAlarms | A:dpHigh | High differential pressure alarm
GetAlarms | A:dpLow | Low differential pressure alarm
GetAlarms | A:dpValue | Alarm differential pressure value
GetAlarms | A:ftHigh | High flowing temperature alarm
GetAlarms | A:ftLow | Low flowing temperature alarm
GetAlarms | A:ftValue | Alarm flowing temperature value
GetAlarms | A:flowHigh | High flow alarm
GetAlarms | A:flowLow | Low flow alarm
GetAlarms | A:flowValue | Alarm flow value
GetAlarms | A:itHigh | High internal temperature alarm
GetAlarms | A:itLow | Low internal temperature alarm
GetAlarms | A:itValue | Alarm internal temperature value
GetAlarms | A:bvHigh | High battery voltage alarm
GetAlarms | A:bvLow | Low battery voltage alarm
GetAlarms | A:bvValue | Alarm batter voltage value
GetAlarms | A:cont1Alarm | Contact 1 status
GetAlarms | A:cont2Alarm | Contact 2 status
GetEvents | E:seq | Event sequence number
GetEvents | E:source | Event source
GetEvents | E:event | Event ID
GetEvents | E:val1 | Event value 1
GetEvents | E:val2 | Event value 2
GetPeriodicData (Hourly) | HH:totalEcfGasVolume | Total ECF Gas Volume
GetPeriodicData (Hourly) | HH:totalGasVolume | Total Gas Volume
GetPeriodicData (Hourly) | HH:totalUncorrectedGasVolume | Total Uncorrected Gas Volume
GetPeriodicData (Hourly) | HH:averageFlowingTemperature | Average Flowing Temperature
GetPeriodicData (Hourly) | HH:averageStaticPressure | Average Static Pressure
GetPeriodicData (Hourly) | HH:totalMass | Total Mass
GetPeriodicData (Hourly) | HH:flowDuration | Flow Duration
GetPeriodicData (Hourly) | HH:noFlowDuration | No Flow Duration
GetPeriodicData (Hourly) | HH:averageDifferentialPressure | Average Differential Pressure
GetPeriodicData (Daily) | DH:totalEcfGasVolume | Total ECF Gas Volume
GetPeriodicData (Daily) | DH:totalGasVolume | Total Gas Volume
GetPeriodicData (Daily) | DH:totalUncorrectedGasVolume | Total Uncorrected Gas Volume
GetPeriodicData (Daily) | DH:averageFlowingTemperature | Average Flowing Temperature
GetPeriodicData (Daily) | DH:averageStaticPressure | Average Static Pressure
GetPeriodicData (Daily) | DH:totalMass | Total Mass
GetPeriodicData (Daily) | DH:flowDuration | Flow Duration
GetPeriodicData (Daily) | DH:noFlowDuration | No Flow Duration
GetPeriodicData (Daily) | DH:averageDifferentialPressure | Average Differential Pressure
GetProcessedData | P:sc | Sample Count
GetProcessedData | P:nc | No-Flow Sample Count
GetProcessedData | P:volFl | Volume Flow Rate
GetProcessedData | P:massFl | Mass Flow Rate
GetProcessedData | P:volFlBse | Base-Corrected Flow Rate
GetProcessedData | P:ecfVolFlBse | ECF-Base-Corrected Flow Rate
GetRawData | R:sp | Static Presure
GetRawData | R:dp | Differential Pressure
GetRawData | R:ft | Flowing Temperature
GetRawData | R:it | Internal Temperature
GetRawData | R:bv | Battery Voltage
GetRawData | R:fi | Flow Interval
GetRawData | R:sc | Sample Count
GetRawData | R:nc | No-Flow Sample Count
GetRawSensorData | S:sensorAPressure | Sensor A Pressure
GetRawSensorData | S:sensorATemperature | Sensor A Temperature
GetRawSensorData | S:sensorBPressure | Sensor B Pressure
GetRawSensorData | S:sensorBTemperature | Sensor B Temperature
GetRawSensorData | S:liquidAVolume | Liquid A Volume
GetRawSensorData | S:liquidBVolume | Liquid B Volume


TeleBUS Driver Tags

TeleBUS is a communications protocol that uses standard Modbus messages to retrieve history logs and audit information. Most TeleBUS messages consist of three Modbus exchanges:

  • A command code is written to the command registers.
  • The reply registers are read until a successful command has been confirmed.
  • Data registers are read.

First, VTScada tells the TeleBUS RTU what information to look for by writing a command code and a meter run number to the command registers (which typically start with register 49500). The command codes indicate to the RTU the kind of data to load into the data registers. As an example, command code 801 can be used to retrieve the AGA-8 gas ratios. Along with the command code itself, we also supply the meter run number and the user/PIN combination.

After that command has been sent the RealFlo RTU will attempt to process it, loading the appropriate data into the data registers. It will then set the reply registers (typically starting with register 49505) to either a copy of the command code or to an error code. After sending a message VTScada’s TeleBUS driver continuously reads these command registers until it finds a match. The number and frequency of these checks can be tuned in the TeleBUS driver’s configuration folder.

Finally, assuming that the reply registers indicate that the operation has been completed successfully, VTScada reads the data registers and brings back the data.

RPC Service

The TeleBUS driver does not have its own RPC Service but rather uses the same one as its child Modbus driver. This is important to know if you are configuring custom server lists for your TeleBUS communications – you should look to create a new sever list based on the name of the child Modbus tag.

TeleBUS Application Properties

TeleBUSFailoverCount = 1

Number of consecutive errors before soft driver failover occurs

TeleBUSMaxReadLength = 125

Maximum block size for TeleBUS reads

Related information:

Best Practices for Tags

Closed Telebus Driver Tag Properties ID Tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

TeleBUS Driver tag Communication Properties Tab

I/O Device

Select the Modbus driver that will communicate with the equipment.

The TeleBUS driver does not perform its own communications, but rather it organizes and sequences a number of Modbus messages that are sent through the standard Modbus driver. As a result, some communications settings may need to be set in the child Modbus driver instead of the TeleBUS driver itself.

Command Register & Reply Register

These allow you to specify the start of the command and reply registers if they are different from the standard RealFlo configuration.

User Number & User PIN

These can be configured in the RTU as a security measure. If this feature is not used both values should set to 1.

Confirm Delay

The number of seconds that the driver will wait between reads of the Reply Registers while waiting for acceptance of a command to be confirmed by the RTU. A shorter delay will result in faster poll times, while a longer delay will minimize bandwidth usage.

Max Confirmation Attempts

Is the number of times the Reply Registers are read without confirmation before the driver assumes that the command cannot be completed and declares a failed communication. This value should be tuned in conjunction with the Confirm Delay parameter – a long confirm delay and many attempts results in long timeouts in the event of a failed message, while a short confirm delay and few attempts may result in the driver giving up too soon before the RTU has a chance to confirm receipt of the command.

Device Clock Time Zone

The time zone of the RTU clock. This is used when logging time stamped information such as alarms, events and history.

Enable Tracing

If selected, a log file will be created under the Data\Trace folder of the application.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Closed TeleBUS Tag Widgets

The following widgets are available to display information about your tags:

Draw HDV Widget

Comm Indicator Widget


TeleBUS Driver Addressing

A VTScada TeleBUS address is made up of four parts, separated by the colon character:

CommandCode:RunNumber:DataAddress:DataType
  • The Command Code indicates to the RTU the type of data that should be loaded into the data registers.
    Please see the RealFlo User and Reference Manual for the list of TeleBUS command codes.
  • The Run Number is the meter run that you wish to interact with.
  • The Data Address is the address in the data registers of the specific piece of information that you’re looking for.

  • The Data Type is an optional parameter that should be set to one of the following:

Data Type | Description
SINT | Signed Short Integer
UINT | Unsigned Short Integer
SLONG | Signed Long Integer
ULONG | Unsigned Long Integer
FLOAT IEEE | Floating Point

If the data type is omitted, a data type of “SINT” will be assumed.

As an example, retrieving the methane gas ratio from meter run 2 requires the following address:

801:2:49781:FLOAT

Bit Reads

The TeleBUS driver does not currently allow bit reads as some other drivers do (e.g. an address of 40001/0 in a Modbus driver will return only bit 0). If you need to read a single bit, first use the TeleBUS driver to read the entire byte into an analog status tag. Then use a separate calculation tag with the following expression to find the value of the bit that you’re looking for:

Bit([<AnalogStatusTagName>], BitNumber)

Special Command Codes

Most command codes result in a single read of the data registers, but there are a few that prompt the driver to do

specialized reads.

Alarm and Event Reads

Command codes 51 (Get requested new events) or 61 (Get requested new alarms) are used to start a read of the RTU’s alarm or event log. The TeleBUS driver will continue reading the logs until they are empty, with each alarm/event being deleted from the RTU’s log as it is read. Users of the Oil & Gas Solutions layer will not likely need to use these command codes, as the event log reading is handled by the flow computer tag.

Daily and Hourly History Log Reads

Command code 11 is used to read the RTU’s hourly history log. The most recent historical value will be read first, and then the driver will continue reading values until it reaches one that has a time stamp which has already been read.

Command code 12 may be used to read the RTU’s daily history log. This works just like command code 11 described above, however it may not be available on some older RTU models. In these cases command code 8888, described below, should be used instead.

The daily history of meter runs 1-3 is made available with a direct read, without the need to load any command into the command registers. The VTScada TeleBUS driver can access this history by using the custom VTScada command code 8888. The reads progress in the same way that they do under command codes 11 and 12, reading back until we reach a record with a time stamp that has already been read.

Note that in all three cases above, the data address used should be the address for the first day’s history – the driver will know where to look for the earlier days’ values. For example, the following are both examples of how to find the daily flow duration history for meter run 2:

12:2:44564:FLOAT
8888:2:46564:FLOAT

Direct Modbus Reads

There are some values, including many of the process values, that are accessed by ignoring the command registers and performing a standard Modbus read. Rather than having to reassign each of these tags to use the Modbus driver, custom VTScada command code 9999 allows you to pass a read directly to the child Modbus driver. For example, the address 9999:1:47528:FLOAT will return the flow rate.

Note that the run number servers no function in this mode, but something must be included in order to maintain a consistent address format


Weatherford Tag

The Weatherford tag is one of four pump-off controllers.

The Pump-Off Controller (POC) tags are designed as a single parent tag that will allow you to completely control and monitor a pump-off controller device. They contain drivers that have been pre-configured with the addresses and poll sequences necessary for reading Dynacard data, setpoints and other telemetry values.

Related information:

Best Practices for Tags

Closed Weatherford properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

In a POC tag, the Name + Description parameters are used to identify the location of the well.
The Area + Alarm Notification Area parameters are used for grouping, filtering, and roster control

Name & Description

Together, these parameters define a unique identifier for the equipment. In some jurisdictions, the description is set to the LSD Closed Legal Subdivision address. or UWI Closed Unique Well Identifier coordinates, but you are free to use whatever value makes sense for your system.

Area & Alarm Notification Area

The area parameter is used to group similar tags together, such as all wells within a given region. An Alarm Notification Area can be defined so that separate rosters can be defined within one region, or so that wells from several fields can use one roster.

The Alarm Notification Area property is inherited by several of the Polling Driver children of this tag and then by any I/O or alarms below those. Child tags that are not expected to generate alarms will inherit the Area property.

If no Alarm Notification Area property is defined, all child tags will default to the Area property.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Weatherford Communications properties tab

Port

Select the port tag, through which VTScada will communicate with this device.

Comm Channel

Select the communication channel and protocol to use for this Modbus Compatible Device driver. This will be one of:

  • Serial RTU Select to use the RTU mode of the Modbus serial communications standard.
  • Serial ASCII Select to use the ASCII mode of the Modbus serial communications standard.
  • SA-85 (MB+) Select to use the Modbus Plus communications protocol via a Modicon SA-85 card.
  • Embedded TCP/IP Select to use the Embedded TCP/IP protocol.
  • Open Modbus TCP Select to use the Modicon Open Modbus/TCP specification to receive Modbus protocol over Ethernet TCP/IP.

Station Address

The station address of the Modicon programmable logic controller. By default, the PLC Address field is set to 1.

An expression may be used to provide the address if needed. This may be required on a network where the address varies depending on the workstation where the tag is running.

Note that, to create a valid expression for an address that contains non-numeric characters, you must enclose the address in quotation marks. e.g. "31.0.0.0" See: Modbus Plus PLC Addressing.

Station Address Mode

Use to limit the range of allowed addresses. Select according to your hardware.

Should only be adjusted if the Flow Computer/POC has been configured to use one of the specific addressing modes.

Standard Address ... 1 - 255 according to Modbus Protocol. Extended addressing ranges are not supported.

Lufkin ELAM Address ... 1 - 2295

TeleBUS Extended Address ... 1 - 65534

Time-Out Limit

Set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver should wait for a reply from the PLC or RTU.

Modicon Typed Addr 1 Offset

Applies the offset for "Type specified" Modbus addresses.

"Type specified" means addresses such as the HC1 and IR2 format. This does not apply to addresses written as only numbers. (For example, 40001 is always the first address in the 40000 block, and is equivalent to HR1 when ModiconTypedAddr1Offset is 0, or HR0 when ModiconTypedAddr1Offset is 1)

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

Device Clock Time Zone

Select the time zone that the device uses in order to convert the time-stamped data from the device into UTC for storage in the VTScada historian. Regardless of the time zone selected with this option, the driver assumes that the device does NOT adjust its clock for daylight savings time (DST).

Defaults to the server's time zone, but may be set to use the device's clock if that is configured for UTC, otherwise any time zone where the device is located.

Observe Daylight Saving Time

Select if the RTU clock adjusts itself for Daylight Savings Time. Note that this does not necessarily mean that the RTU is in daylight savings time when this is being set. That is determined by the Windows operating system based on the selected time zone.

Weatherford Polling properties tab

Disable All Polling

Select if communications are to be disabled at this site.

Polling Group

Provide a group name that will be used by the polling drivers within this tag. Groups ensure that polling drivers sharing a connection do not all try to poll at the same time. Each child Polling Driver will have its own sequence number within the group.

Useful only when two or more schedules match.

Process I/O Scan Interval

Measured in seconds, this sets the frequency at which process data is read.

Enable Setpoints Driver

If selected, tags in the \Process\Setpoints context will be polled using a dedicated setpoints driver instead of using the standard process driver. This allows the setpoints to be polled at a different rate from the other data.

Schedule Settings

Each polling schedule, when enabled, will offer a choice of "Hourly at", Daily, "Weekly on", or "Monthly on".

In each case, additional selections will be available, relevant to the overall scheduling of the poll.

Min Manual Poll Interval

Sets a minimum time between manual polls.

Weatherford Settings properties tab

Labels and Units, X-Axis & Y-Axis

These are pre-configured with standard values, but you are free to provide your own labels and units to describe your system.

Hide Surface Cards on Graph

When selected, surface cards will not be shown.

Latitude and Longitude

Configure with the controller's location in order to display this site on a map.

Custom Page to Open from Site Maps

By default, the built-in Weatherford Overview page will open in response to an operator clicking on a site icon. You may create your own page, to use instead. Note that your custom page must be parameterized, taking a POC tag as its parameter.

Before selecting security privileges, you must first create those custom privileges. See: Protect Pages and Output Tags

Security Privilege - Modify Setpoints

Select the custom security privilege that you created in order to protect setpoints within this device.

Security Privilege - Polling Control

Select the custom security privilege that you created in order to protect polling control within this device.

Closed Weatherford Tag Widgets

The following widgets are available to display information about your tags:

Alarm Priority Box

Alarm Priority Icon

Active Indicator Widget

Data Age Widget

Dynacard Display Widget

Polling Indicator Widget

Dynacard Page Button Widget

POC Manual Process Poll Widget

Site Alarm List

Tag List Widget

Site Icon Widget

Alarm List

Draw HDV Widget


Well Test Tags

The Well Test tag allows the recording, review and editing of a number of other tag values as a single record. When triggered, the Well Test tag records the current value of all of its contributing tags and saves this as a test record. This record can later be accepted or rejected, and optionally some of the values may be edited.

Unlike other tags, the Well Test tag does not read its own I/O values, but rather works to aggregate the values from existing tags into a single record. Before creating a Well Test tag, you should first create Flow Computer Tags with a set of Meter Run Tags that read all of the values that you wish to include.

Upon triggering, the current values of all of the other tags configured as part of a Well Test are recorded as a new well test record.

The Well Test tag is generally used with the Well Test Table Widget, and many of the tag's properties are used to control the setup of the table widget.

Related information:

Best Practices for Tags

Closed WellTest tag properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn orange to indicate that you have applied an override.

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

WellTest tag Timing tab

Configure the Trigger, write delays, time zones, start time and date, end time and date, time/date formats and enable duration field.

Trigger

A new tests is initiated whenever this value changes. May be an expression or a link to any existing tag.
Typically, this will use the same tag as that providing the End Time parameter, where a change signals that a new test has completed.

Write Delay(s)

The number of seconds to wait after the trigger before evaluating the contributing tags and writing the new well test record.

It is advisable to delay for a few seconds to make sure that all of the other values have been read and are up to date before writing the well test record.

Device Clock Time Zone

The time zone of the device. This is used to convert the readings in Start Time and End Time to UTC for storage in the VTScada historian.

Daylight saving time is not supported and all time zones are assumed to follow standard time.

Start Time, Start Date , End Time, End Date

Configure the Time / Date Tag Format parameter before configuring start and end times.

The values in these fields define the start and end times of the well test. The Well Test tag supports time stamps in three formats.

  • If the format is set to "Seconds since midnight / days since Jan. 1, 1970" and if the Start Date and End Date fields are valid, then it assumes that Start Time and End Time are the number of seconds since midnight and that Start Date and End Date are the number of days since Jan. 1, 1970.
  • If the format is set to "Seconds since midnight / days since Jan. 1, 1970" and if the Start Date and End Date fields are invalid, then it assumes that Start Time and End Time are the number of seconds since Jan. 1, 1970.
  • If the format is set to "Floating point containing HHMM/MMDD," Start Date and End Date are always valid and a value of at least three digits must be entered otherwise a blank date for the month will return December of the previous year.
    • HHMM/MMDD format assumes all entries are four-digit numerical values. HHMM entries read the first two digits as the hour (24-hour clock) and the second two digits as the minute. MMDD entries read the first two digits as the month and the second digits as the day. A three-digit entry or less can also be entered, but any unentered digits are read as 0.

For Time and Date, any unentered values are treated as "0". For hours and minutes "0" is the lowest value in each digit. For months, "00" gives the last month of the previous year, and for days, the last day of the previous month.

Values that exceed their expected range (00-59 for minutes; 00-23 for hours; 01-28/29/30/31 for days; 01-12 for months) push the time forward by the amount they are in excess.

HHMM examples:
"77" = 0077 = 77 minutes (1 hour and 17 minutes) and a time of 01:17.
"707" = 0707 = 07:07.
"7007" = 7007 and a time of 22:07 shifted forward by two days.

MMDD examples:
"0000" = 0000 = November 30 of the previous year
"12" = 0012 = December 12 of the previous year.
"1200" = 1200 = November 30 of the current year.
"102" = 0102 = January 2 of the current year.
"1212" = 1212 = December 12 of the current year.
"1240" = 1240 = January 9 of the next year.

If Daylight Savings Time is used on the workstation running VTScada, the value for all Start Time and End Time will be increased by one hour. For example, an entry of "0000" would result in a time of 01:00 rather than 00:00.

Time / Date Tag Format

Refer to the preceding notes on time formats for start and end.

Duration Field is Editable

The duration of the test is taken to be the time stamp of the end time minus the time stamp of the start time. If this box is checked, that default value may be edited after the fact.

WellTest tag I/O N tab

Each section on this tab corresponds to a column of the well test table. If nothing is entered in an I/O Source parameter, that column will not appear on the table.

I/O sources 1 through 5 are configured on the tab, I/O 1. Sources 6 through 10 on tab I/O 2. Sources 11 through 15 on tab I/O 3.

Configure the title, editability, color, and source of IO devices

Title

The title to be used as the column header in the Well Test table.

Field is Editable

Select if a user with appropriate security privileges is allowed to edit this value.

Color

Set the background color to be used for this column in the well test table.

Column text is always black. Choose a light color for contrast.

I/O Source X

The value that will be written as part of the well test record. When the value of the Trigger parameter changes, the well test tag will record the current value of the constant, expression, or tag selected here as part of the well test record

WellTest tag Misc tab

Configure the Well ID, Filter Well Test Table by Column Name, permit the filter to be editable, Configure a Well Test Table filter value, link a historian, configure custom security privileges, configure manual BS&W Total Volume, make it editable or select DS&W color.

Well ID

The value that will be entered in the Well ID column of the well test table. This column will always be included in the table

Well Table Filter Column Name

Set the field name to be shown on the Well Test Table widget's column and in the Well Test Report. When enabled, this name is filterable in widgets and tables. (Default = Well LSD)

Well Test Table Filter Value is Editable

Select to enable editing of the well test table filter value.

Well Test Table Filter Value

The value that will appear in the Well Test Table in your named Well Test Table column (Well LSD by default). This column will always be included in the table.

Historian

The historian tag that will be used to record the well test records. For most systems this should be left set to the default System Historian.

Record Edit Security Privilege

The security privilege that a user account must have in order to edit the well test records using the well test table. If the user account does not have this security privilege than that user can still view the well test records, but cannot edit them.

Manual BS&W Total Volume.

If no tags exist, from which to read this information, the well test table also has the option of letting the user manually enter their BS&W (basic sediment and water) information.

Total Volume Field is editable.

If selected, four additional columns will be added to the well test table: Total Volume, BS&W, Oil Volume and Water Volume.

The total volume column in the table is populated based on the value, tag value or expression entered here in the Manual BS&W Total Volume parameter.

The BS&W column is initially blank, but can be edited by the user. It represents the percentage of the total volume that is made up of free water, sediment, etc.

Once a value has been entered in the BS&W column, the Oil Volume and Water Volume columns will be updated automatically based on the Total Volume and the BS&W percentage.

BS&W Color

Controls the color of all four BS&W fields.

Closed WellTest Tag Widgets

The following widgets are available to display information about your tags:

Well Test Table Widget

Tag List Widget

Draw HDV Widget


Sequencing Reads in a Pump-Off Controller

Reading the Dynacard data (Dynacard Upload Driver Tag) from a pump-off controller is a multi-step process that involves a number of Modbus messages being exchanged with the controller. The Dynacard Upload Driver tags control the sequencing of the messages, and if you are using a standard, supported pump controller you need not worry about this sequence. However, if you have a non-standard controller or are adding support for a new type of flow computer, you may wish to edit this sequence.

You can review your Dynacard's current message sequence by using the Export button provided in the Communications tab of your Dynacard Upload Driver tag’s properties folder. Use this to export the current message sequence to a CSV file, which can be opened up in Excel.

Use the Import button in the same tab to read an edited CSV file and import its sequence into the Dynacard Upload Driver tag.

An example of an exported Dynacard sequence:

The columns are as follows:

Column | Description
Step Name | A unique name given to this step in the sequence.
Step Module | The name of the sequencer module to run during this step.
Parm1 - Parm20 | Parameters to the sequencer module.

When a read is triggered in the Dynacard Upload Driver, it will start at the top of this list and run each step module one after the other in sequence. Refer to the following discussion of each of these modules, their parameters and how they work. Combining them should allow you to perform the necessary sequence of reads and writes to get data from your flow computer.

The Dynacard Structure

Raw registers are read from the pump-off controller and saved in memory. These registers are then parsed for the card data, which is saved in a defined structure within the driver. This structure is logged to the VTScada historian, and certain elements of the Dynacard structure (for example, the force / position data) are shown on the Dynacard screen.

The Dynacard structure, and all of its elements, are listed in the chart below. Not every element will be used for every pump-off controller, but your sequence CSV file should use these names exactly in order to ensure that the data is saved properly.

DataGroup | Variable | Comment
Card1 | CardXY | The force/position data used in the Dynacard chart
 | TimeStamp | If no time stamp is provided, the time at which the data was read will be used.
 | ShutdownID | Shutdown Event ID
 | NumPoints |
 | MaxLoad |
 | MinLoad |
 | StrokeLength |
 | StrokePeriod |
 | ControlMode |
 | DHCardXY | Downhole force/position data
 | DHTimeStamp | Downhole time stamp
 | DHMaxLoad |
 | DHMinLoad |
 | DHShutdownID | Downhole Shutdown Event ID
 | DHNumPoints |
 | DHGrossStroke |
 | DHNetStroke |
 | DHPumpFillage |
 | DHFluidLoad |
Card2 |  | Same variables as Card1 data group
Card3 |  | Same variables as Card1 data group
Card4 |  | Same variables as Card1 data group
Card5 |  | Same variables as Card1 data group
Card6 |  | Same variables as Card1 data group
Card7 |  | Same variables as Card1 data group
Card8 |  | Same variables as Card1 data group
Card9 |  | Same variables as Card1 data group
Card10 |  | Same variables as Card1 data group

Sequencer Modules

This table provides an overview of each module. Full descriptions follow the table.

Module | Description
ReadValues | Reads registers from the pump-off controller and puts them in memory
NewDataGroup | Adds a new DataGroup to the Dynacard structure
GetValue_Numeric | Reads values from memory and saves them in the Dynacard structure as a single numeric value
GetValue_XYCardData | Reads values from memory and saves them in the Dynacard structure as a set of XY Dynacard data. This module assumes that the X and Y values are interleaved within a single block of registers (see full description below)
GetValue_XYCardData_Blocks | Reads values from memory and saves them in the Dynacard structure as a set of XY Dynacard data. This module assumes that the X and Y values are stored in separate blocks of registers (see full description below)
WriteValue | Writes a value to the pump-off controller
ResetValues | Clears memory of the previously read values
SetNextStep | Sets the next step of the sequence that should be run
CondNextStep | Sets the next step of the sequence based on some condition
CounterLimit | Sets the next step or sets an error flag when it has been run a designated number of times
CounterReset | Resets the counter used in the CounterLimit module
TimeDelay | Waits a specified amount of time before proceeding to the next module
EndSequence | Ends the sequence; should be the last module in every sequence

ReadValues

Reads registers from an RTU and stores them in memory.

Parameters:

1 | StartRegister | First register to read
2 | N | Number of registers to read

This module reads any number of registers from the RTU and stores them in memory to be accessed by other modules. Note that this function does not take into account the content of the data being read in any way, including data types. If you wish to read a double floating point, for example, you would start at the appropriate register and request a read of four registers in order to bring back the whole thing.

Note that in many cases, particularly if the Modbus mapping in the pump-off controller is well-organized, it is more efficient to read several values in a single message. If, for example, you wanted to read the data from registers 40010, 40011 and 40013 (but you don’t care about 40012), its usually best to do a single four-register read rather than breaking it out into two smaller reads.

NewDataGroup

Adds a new data group to the Dynacard structure

Parameters:

1 GroupName Label to use for the new data group (Card1, Card2, etc.)

This module adds a new data group to the Dynacard structure, and should be used to separate the data read from different cards. Even if only one card’s data is being read, the “Card1” group should still be added before running any “GetValue” modules.

GetValue_Numeric

Reads values from memory and adds them to the Dynacard structure

Parameters:

1 | VarLabel | Label for the variable in the Dynacard structure
2 | StartRegister | Starting memory register to read (note that these register numbers will match those in the controller's Modbus map)
3 | FormatType | Data type that is being read - see list of acceptable data types below.
4 | UnscaledMin | Unscaled minimum value - used to scale the value we're reading
5 | UnscaledMax | Unscaled maximum value - used to scale the value we're reading
6 | ScaledMin | Scaled minimum value - used to scale the value we're reading
7 | ScaledMax | Scaled maximum value - used to scale the value we're reading
8 | ReverseRegOrder | Set to 1 to read the registers in reverse order (may be necessary for some controllers)
9 | IsTimeStamp | Set to 1 if we are reading a timestamp

The VarLabel should match one of those listed in The Dynacard Structure table at the beginning of this article.

This module reads the registers in memory (see: ReadValues) and interprets them as data values. You can think of this as similar to a standard driver’s read of an RTU, only we’re reading from internal VTScada memory instead of from the pump-off controller directly. The memory registers are mapped the same as those in the pump-off controller, and you can use the parameters to control everything that you would in a standard driver’s read (data type, scaling, reverse order, etc.)

One of the following constants should be used for the FormatType parameter:

Constant | Data Type | Bytes
0 | Short Integer | 2
1 | Long Integer | 4
2 | Unsigned Short Integer | 2
3 | Unsigned Long Integer | 4
4 | Single Precision Floating Point | 4
5 | Double Precision Floating Point | 8
6 | Single Byte (High) | 1
7 | Single Byte (Low) | 1

GetValue_XYCardData

Reads force / position values from memory and adds them to the Dynacard structure.

Parameters

1 | VarLabel | Label for the variable in the Dynacard structure (should be either CardXY or DHCardXY)
2 | StartRegister | Starting memory register to read (note that these register numbers will match those in the controller's Modbus map)
3 | FormatType | Data type that is being read - see list of acceptable data types in the GetValue_Numeric section.
4 | NumPairs | Number of X-Y pairs to read
5 | UnscaledMinX | Unscaled minimum value - used to scale the value we're reading
6 | UnscaledMaxX | Unscaled maximum value - used to scale the value we're reading
7 | ScaledMinX | Scaled minimum value - used to scale the value we're reading
8 | ScaledMaxX | Scaled maximum value - used to scale the value we're reading
9 | UnscaledMinY | Unscaled minimum value - used to scale the value we're reading
10 | UnscaledMaxY | Unscaled maximum value - used to scale the value we're reading
11 | ScaledMinY | Scaled minimum value - used to scale the value we're reading
12 | ScaledMaxY | Scaled maximum value - used to scale the value we're reading

This module reads the position/load registers in memory (see: ReadValues) and interprets them as data values which are later used to create the Dynacard graph. Beginning at the start register, the FormatType (see the GetValue_Numeric section) and the NumPairs variables combine to tell the sequencer how many registers should be read.

This module assumes that X and Y values in the device are interleaved within a single block of registers:

[X1, Y1, X2, Y2, …, Xn, Yn]

GetValue_XYCardData_Blocks

Reads force / position values from memory and adds them to the Dynacard structure.

Parameters

1 | VarLabel | Label for the variable in the Dynacard structure (should be either CardXY or DHCardXY)
2 | StartRegisterX | Starting memory register to read (note that these register numbers will match those in the controller's Modbus map)
3 | StartRegisterY | Starting memory register to read (note that these register numbers will match those in the controller's Modbus map)
4 | FormatTypeX | Data type that is being read - see list of acceptable data types in the GetValue_Numeric section.
5 | FormatTypeY | Data type that is being read - see list of acceptable data types in the GetValue_Numeric section.
6 | NumPairs | Number of X-Y pairs to read
7 | UnscaledMinX | Unscaled minimum value - used to scale the value we're reading
8 | UnscaledMaxX | Unscaled maximum value - used to scale the value we're reading
9 | ScaledMinX | Scaled minimum value - used to scale the value we're reading
10 | ScaledMaxX | Scaled maximum value - used to scale the value we're reading
11 | UnscaledMinY | Unscaled minimum value - used to scale the value we're reading
12 | UnscaledMaxY | Unscaled maximum value - used to scale the value we're reading
13 | ScaledMinY | Scaled minimum value - used to scale the value we're reading
14 | ScaledMaxY | Scaled maximum value - used to scale the value we're reading

This module reads the position/load registers in memory (see: ReadValues) and interprets them as data values which are later used to create the Dynacard graph. Beginning at the start register, the FormatType (see the GetValue_Numeric section) and the NumPairs variables combine to tell the sequencer how many registers should be read.

This module assumes that X and Y values in the device are separated into two distinct blocks of registers:

[X1, X2, …, Xn] and [Y1, Y2, …, Yn]

WriteValue

Writes a value to a register in the pump-off controller.

Parameters

1 | Address | Address of the register in the pump-off controller to write to
2 | Value | Value to write

This module writes a single value to a register in the pump-off controller. The address should be written as though you were performing a standard write with the child Modbus driver. If you wish to write a floating point to register 40001, for example, then the address should be “40001/FLOAT”.

ResetValues

Clears the memory holding the values previously read from the RTU

Parameters

-None

This module clears the memory that holds the values that had previously been read from the RTU by the ReadValues module. Usually this module is not necessary, but you may need to run it in cases where the same registers in the pump-off controller are loaded with different information over the course of the read sequence.

SetNextStep

Sets the next sequence step to be run.

Parameters

1 StepName Name of the step to run next

Usually, the steps of the sequence are run sequentially from top to bottom. This module is used to change that order, specifying the name of the next step to be run (as defined in the first column in the sequence CSV file). After that step runs, the steps will continue to run sequentially from that new point.

CondNextStep

Sets the next sequence step to be run based on a condition being true.

Parameters

1 | CompValue | Main value to compare with the others
2 | DataGroup | DataGroup from the Dynacard structure (optional)
3 | CondCode | Condition comparison code (see notes below)
4 | Comparison1 | Value to compare with CompValue (see notes below)
5 | Step1 | Sequence step to run next if comparison is true
6 | DataGroup1 | DataGroup corresponding to Comparison1 (optional)
7 | Comparison2 | Value to compare with CompValue (see notes below)
8 | Step2 | Sequence step to run next if comparison is true
9 | DataGroup2 | DataGroup corresponding to Comparison2 (optional)
10 | Comparison3 | Value to compare with CompValue (see notes below)
11 | Step3 | Sequence step to run next if comparison is true
12 | DataGroup3 | DataGroup corresponding to Comparison3 (optional)
13 | Comparison4 | Value to compare with CompValue (see notes below)
14 | Step4 | Sequence step to run next if comparison is true
15 | DataGroup4 | DataGroup corresponding to Comparison4 (optional)
16 | Comparison5 | Value to compare with CompValue (see notes below)
17 | Step5 | Sequence step to run next if comparison is true
18 | DataGroup5 | DataGroup corresponding to Comparison5 (optional)

Usually, the steps of the sequence are run sequentially from top to bottom. This module is used to change that order, specifying the name of the next step to be run (as defined in the first column in the sequence CSV file) provided a certain condition is met. After that step runs, the steps will continue to run sequentially from that new point.

As an example, this module is used in the Lufkin SAM pump controller to decide how many registers to read. First we read the control mode, and then if it is either 1 (“Downhole”) or 4 (“VFD – Downhole”) then we read the downhole registers in addition to the standard registers.

The CompValue parameter is the value that will be compared against each of the other Comparison parameters. Each of these parameters can be either of the following:

  • A value that had previously been saved in the Dynacard structure
  • A constant

For example, in the Lufkin SAM case mentioned above we had previously read the control mode with a Get-Value_Numeric, giving it the label “ControlMode”. When doing the comparison to see if it is either a 1 or a 4, we would set the CompValue parameter to “ControlMode”, the Comparison1 parameter to “1” and the Comparison2 parameter to “4”.

If the CompValue or Comparison parameters are values from the Dynacard structure, the DataGroup parameters specify which DataGroup the values reside in within the structure. If no DataGroup parameters are provided, the current DataGroup will be used.

The various Step parameters indicate which step of the sequence to progress to in the event that the comparison is true. The comparisons will progress sequentially until one of them is found to be true, in which case that step will be used and the rest of the comparisons won’t be made. If none of the comparisons is true, the sequencer carries on as usual to the next sequential step.

The CondCode parameter tells the system what kind of comparison should be made. The following chart shows the numeric codes that represent the different options.

CondCode | Operation
0 | ==
1 | !=
2 | <
3 | >
4 | <=
5 | >=

The same CondCode is used for all comparisons.

CounterLimit

Sets the next sequence step or returns an error message when this module has been run a predetermined number of times.

Parameters

1 | VarName | (Optional) Name of counter variable
2 | CountLimit | Number of times this should be run before triggering the next step/the error message
3 | StepName | Sequence step to run next
4 | CustomErrMessage | Error message to return

This module can be used to repeat a section of the sequence several times. A tally is kept of each time this module is run. Once it has run a number of times equal to or greater than its CountLimit, the module will trigger. If the module has not yet reached its count limit, the sequencer will carry on to the next module as usual.

If StepName is valid, the sequencer will progress to that state upon reaching the limit. If the StepName field has been left blank, an error will be returned and the entire sequencer will stop (declaring the read to be a failure). In this latter case, CustomErrMess can be used to set the error message that will be displayed by the driver’s ‘Stats’ button.

VarName can usually be ignored, and is only necessary if you need to maintain two separate counters within the same sequence. In this case, each counter should be given a unique VarName.

CounterReset

Resets the counter used in the CounterLimit module

Parameters

1 VarName Optional) Name of counter variable

This module is used in conjunction with the CounterLimit module defined above. If CounterLimit is going to be used for a given VarName (or lack thereof) multiple times within the same sequence, it can be reset to 0 by calling the Coun-terReset function with that VarName.

TimeDelay

Wait a specified number of seconds before progressing to the next module

Parameters

1 Delay

Time in seconds

EndSequence

Ends the sequence

Parameters

-None


Widget Reference

Topics in this section (see side menu) provide a complete reference to the widgets that come with VTScada. Note that you (or your systems developer) may have created customized widgets that are unique to your application.

Active Indicator Widget

The Active Indicator widget is an indicator that turns green when the associated RTU is the actively connected site. The indicator will otherwise be red.

Add Lock Button Widget

The Add Lock Button widget allows authorized operators to add a Control Lock to the linked tag. If the linked tag is a parent of other tags, then all output tags below that parent will be locked.

Authorized operators are those with the Add / Remove Locks privilege.

Add Note Button

Creates a button on the page that operators may click to add a note to the associated Notebook. Two versions of the button are available.

Add Note Field Widget

Creates a note entry field, similar to that found in the Operator Notes page. Operators can use this to add notes to a preselected Notebook without leaving the page to which this widget was added.

Alarm Lists and Related Tools:

Alarm List

Used to draw a customizable alarm list on any application page. This is what you see in the The Alarm Page, including all tools and filters. When drawing your own list, you have control over which portions of it are shown and how they are configured. You can recreate the alarm page (all options enabled), create a minimalist alarm banner, or some variation in-between.

Alarm list as a simple banner.

If you choose to hide groups of tools, then operators cannot change the values that you set. This banner example shows no tools and uses a column format that does not provide an Ack button. The status bar, border and column titles are still enabled.

Ack All Button

Acknowledge all alarms. This is different from the Ack Shown button. With this tool, "all" means "all", not just "all within the filtered list".

This button is enabled only if there are alarms to acknowledge and you are authorized to acknowledge them

Ack Selected Button

Click to acknowledge a single, selected alarm from a named Alarm List.

This button is enabled only when the logged-on operator selects an unacknowledged alarm.

Ack Shown Button

Creates a button that can acknowledge all alarms shown in the named alarm list. Alarms that are not shown because they do not match the list's current filter, are not acknowledged.

Enabled only if the list has alarms that require acknowledgment, and if the logged-in operator is authorized to acknowledge them.

Alarm List Button

Change the Alarm List to display a different category of alarms. There are 6 possible alarm list categories (Active, Current, Configured, Disabled, History, Unacknowledged). Draw one instance of the alarm list button for each category that you might want to see displayed in the list. (See: Legacy Alarm List)

Mute Button

When clicked, this button will stop all alarm sounds (current and future). No alarm sounds will occur while this button is toggled on. Enabled only when there are alarms to mute and the current operator is permitted to use this feature.

Silence Button

Silence the alarm sound associated with the most recent unacknowledged alarms in your system. New alarms will sound. This button is enabled only when there are alarms to silence and the current operator is permitted to use this feature.

Alarm Priority Box

Provides a visible indication when the linked tag is in an active or unacknowledged alarm state, and when it is either shelved or disabled.

This widget is not visible for alarms that are unacknowledged but no longer active unless the property AlarmPriorityIndicatorShowNormalUnacked is set to 1. (Note that "trip" alarms are never in an active state.) The widget is always displayed when the alarm is shelved or disabled.

If you are working in a Master Application and link your Alarm Priority widget to a tag that is created in that Master Application and that also has child tags from a Subordinate Application, be aware that alarms from the subordinate tags will not flow through the local tag to be shown by your widget. Alarm Priority widgets in a Master Application that are linked directly to tags belonging to a Subordinate Application will work as expected.

Alarm Priority Icon

Provides a visible indication when the linked tag is in an active or unacknowledged alarm state, and when it is either shelved or disabled.

This widget is not visible for alarms that are unacknowledged but no longer active unless the property AlarmPriorityIndicatorShowNormalUnacked is set to 1. (Note that "trip" alarms are never in an active state.) The widget is always displayed when the alarm is shelved or disabled.

If you are working in a Master Application and link your Alarm Priority widget to a tag that is created in that Master Application and that also has child tags from a Subordinate Application, be aware that alarms from the subordinate tags will not flow through the local tag to be shown by your widget. Alarm Priority widgets in a Master Application that are linked directly to tags belonging to a Subordinate Application will work as expected.

Analog Bar & Indicator Widget

Used by: I/O and Calculations tag (although portions may be used by any analog numeric tag).

The Analog Bar and Indicator provides a wealth of current and historical data to the operator at a glance. You have a wide range of configuration options. Note that colors used within the bar are controlled by the attached Style Settings tag.

Click to expand
Vertical, left configuration of the Analog Bar and Indicator widget

Analog Clock

The Analog Clock widget is a dynamic image, displaying the current time.

Animated Image Widget

The Animated Image widget is used to display a short movie that runs while the tag’s value is non-zero. When used for tags that have analog values, the speed of the animation reflects the value of the tag. For tags with simple on or off values (digitals) the animation either runs or not. In all cases, you can set the maximum speed of the animation in frames per second when configuring the widget.

A configured Animated Image (shown in multiple frames).

Antique Bolted Gauge Widget

The Antique Bolted widget represents the associated tag's value as a photorealistic meter

Antique Gauge Widget

The Antique Gauge widget represents the associated tag's value as a photorealistic meter. The divisions used to display the scale range are pre-set for this meter. The engineering units of the linked tag are displayed below the scale.

Aqua Gauge Widget

The Aqua Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Arc Meter Widget

The Arc widget represents the associated tag's value as portion of an arc. The darker portion of the arc starts at the angle you specify, where vertical (North) is zero degrees. Increasing values are indicated by the darker portion sweeping in a clockwise direction. The colors are set by the LED (analog) values of a selected Style Settings tag, and values above the linked tag's alarm setpoint can be indicated.

Four variations on a theme, showing the control you have over arc configuration.

Army Gauge Widget

The Army Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Audio Meter Widget

The Audio widget represents the associated tag's value as photorealistic meter.

Backlit Gauge Widget

The Backlit Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Bar Graph Widget

This widget is used to display the values of a set of tags in the form of a two-dimensional bar graph. The graph updates continuously with changing values.

Recipe Batch Status Widget

The Batch Status widget is used to display information about a recipe batch. Details include the name of the linked recipe tag, the current status, the recipe name, batch number and the last write time.

Bottom Bar Widget

The Bottom Bar widget is used to display a tag's value as a vertical bar, the length of which increases from the top towards the bottom as the tag’s value increases. When the tag’s value is at a minimum, the bar will be shown as a thin line at the top of its range. When the tag’s value reaches its maximum, the widget will be displayed as a rectangle, filling the range.

Border

Borders are most often used to provide a visual indication to operators that a set of controls have some common purpose. Borders can appear raised or sunken relative to the rest of the page, and can be transparent or shaded.

Camera Viewer Widget

The Camera Viewer widget is used to display the live feed from the camera specified in the linked Camera Tag.

Within the Idea Studio, this widget shows only as a placeholder, never as a live image. In the operator view, it will display the feed from the attached camera if available. If the image feed is not available, then a gray rectangle is shown instead.

Campbell PakBus Driver Info Widget

The driver needs to read in a set of Table Definitions from the logger before it can read records. This dialog shows operators what definitions have been read. Select a table from the droplist to display a list of the fields.

Cancel Button - See Execute / Cancel Button Widget

Checkbox Switch Widget

The Checkbox Switch widget is used to create an On/Off control for a two-position SelectorSwitch tag. Each time an operator clicks on the box or attached label, the switch will toggle between positions and a check mark will be displayed for position 1.

This is a control-type widget that is only available for selector switches - it is not available for use as an indicator with Digital Input or Digital Status tags.

Rockwell Control Widget

The Rockwell Control tag widget creates a panel of controls that can be used to send output to the hardware associated with a Rockwell driver tag.

Rockwell Statistics Widget

The Rockwell Statistics widget is used to create a beveled display, listing the statistics about the communications between VTScada and the associated hardware.

Rockwell Information Widget

The Rockwell Information widget is used to create a beveled display, listing information about the associated hardware.

Classic Gauge Widget

The Classic Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Clear Button Widget

The clear button is used with other form-related widgets. When clicked, it clears all values filled in the data entry widgets with "Include in Form" enabled on the same page. For all intents and purposes, this blank value is essentially 'Invalid'.

Cockpit Gauge Widget

The Cockpit Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Color Blink Widget

The Color Blink tag widget is used to create a color box that blinks to indicate the state of the underlying tag. Blinking is an extremely eye-catching visual feature and should only be used in situations where it is of utmost importance for an operator to notice the state of a tag. Do not use this widget casually.

Color Box Widget

The Color Box widget is used to represent the associated tag as a box that changes color based on the tag's value. It is primarily used with that have discrete states such as digitals and alarms, but may also be used with analogs. For an analog tag, the value will be rounded to find the closest match to one of the states.

Color Fill Widget

The Color Fill tag widget is used to draw a tag as an animated bar (Bar Color) that graphically illustrates the value of the associated tag against a background color (Unfilled Color).

If the Changed Color is set, the object must be placed over a region of that color to be visible.

Color Line Widget

The Color Line tag widget is used to draw a line that changes any combination of color, width and style to indicate the state of the associated tag. Can be linked to most numerics, but meant primarily for digitals.

Comm Indicator Widget

The Comm Indicator tag widget is used to draw an indicator square, the color of which indicates the current status of the associated I/O device.

Comm Line Widget

The Comm Line tag widget is used to draw a line that changes any combination of color, width and style to indicate the state of the associated tag. Used for port tags rather than digitals.

Comm Messages Button Widget

The Comm Messages Button tag widget is used to draw a button that can be clicked to display communications data (transmit and receive communication message strings) for an associated communication driver tag.

Show Statistics Button Widget

The communications Show Statistics Button widget is used to draw a button that can be clicked to display communication statistics for either the device associated with the button, or all devices in your system.

Compass 1 Widget

Displays a compass having a needle that rotates according to the tag's value. The compass needle will point to North when the tag's value is 0. Direction of rotation is clockwise for positive values. The full range of the underlying tag's scaled values will cause one rotation.

Compass 2 Widget

Displays a compass having a numeric display that rotates according to the tag's value. The 0-value will point to North when the tag's value is 0. Direction of rotation is counter clockwise for positive values. The full range of the underlying tag's scaled values will cause one rotation.

Connection Status Indicator Widget

The Connection Status Indicator is used to notify operators when the port being monitored is in any of the following states: Disconnected, Connecting, Connected, or Failed.

You may configure the indicator to use any color for each state, and to use any image (or none) to display the status. The default configuration is a color-coded rectangle. Note that the rectangle is solid - it will not interact with active orange as is the case with an Image Change widget.

Control Token Box

This is a multi-use widget for Control Tokens that both indicates current token status and affects token behavior.

Custom Meter Parts:

Compass Indicator

The compass indicator widget represents the associated tag's value as a needle that swings from the defined reference angle through a full circle in response the linked tag's value.

Draw Scale

The draw scale provides tick marks to custom widgets of your own design. These may be radial or linear.

Linear Indicator

The linear indicator widget represents the associated tag's value as a line that moves across the scale range. Any image may be used in place of the line, but it should have a clear pointer to help the operator read the current position of the meter.

Linear Legend Widget

The Linear Legend Widget represents the associated tag's minimum and maximum scale range as a series of numbers in a line. The widget can be oriented either vertically or horizontally. Text can be configured to a set size, or to scale with the widget. In the following example, the horizontal legend has a smaller width than the vertical legend, therefore a smaller font is used.

Linear Scale Widget

The Linear Scale Widget represents the associated tag's minimum and maximum scale range as a series of major and minor tick marks. The widget can be oriented either vertically or horizontally.

Radial Indicator

The radial indicator widget represents the associated tag's value as needle rotating about a fixed center. The red lines shown here are not visible to the operator. They show only in the Idea Studio, as a guide to help you place the indicator. The needle may be any image, any color.

Radial Legend Widget

The Radial Legend widget represents the associated tag's minimum and maximum scale range as a series of numbers around an arc.

Radial Scale Widget

The Radial Scale Widget represents the associated tag's minimum and maximum scale range as a series of major and minor tick marks. The scale will always be round, regardless how the bounding box is stretched. In all cases, the smaller dimension of the bounding box will be used to set the diameter of the scale.

Data Age Widget

The Data Age tag widget is used to display the time of the most recent poll of an RTU in hours, minutes, and seconds.

Data Diode Widgets

Compass Indicator

The Sync Status Indicator widget is used to monitor the status of the Data Diode Client tag in the client application of the Data Diode configuration. This widget is often paired with a Comm Indicator and the Historian Status widget to monitor the status of the Data Diode Client tag. The widget will display its normal color (default green) with the caption "In Sync" unless an error is detected.

This widget will display a normal status unless an error is detected.

An example of the Sync Status Indicator widget in its default state.

Data Age Widget

Starts transmitting outstanding data from the historian to the data diode. The application will resume from the last known transmission and will continue to transmit live information as it becomes available. The transmissions will stop if the Data Diode Publisher Stop button is used or if the publishing application stops.

Data Age Widget

Clicking this button opens a dialog to set the time (UTC) and the date. Click the calendar icon to open a calendar tool for selecting the date. Start from Date/Time will start from the saved state file closest to the selected date/time. If no state file before the selected date/time is found, then VTScada will transfer all data from the beginning. Once the historian is caught up, normal sync will resume.

Transmissions are stopped if the application stops or restarts or if the Data Diode Publisher Stop button is used.

Data Age Widget

This button will stop VTScada from transmitting data from the historian to the Data Diode. This button will remain disabled unless a transmission is underway.

Date Time Selector

This widget is used to select a date and time (timestamp) for:

  • A form
  • The start time of a report
  • The end time of a report

DFS Station Draw

The Data Flow Station Draw tag widget is used to create a button that an operator may click to view information about the modules that have been installed at the physical RTU being represented by the associated tag. The contents of this window will vary according to the station's installed modules.

Draw Widget

The Draw tag widget is used to display a bordered field containing the description of the associated tag on the left, and its value to the right. The description and the border are optional.

If the associated tag type includes an alarm setup then orange dots will appear in the object to indicate that one or both alarms are either not configured or not enabled. For tag types that have both high and low alarms as part of their definition, the upper and lower squares refer to the high and low alarms in that order.

Draw HDV Widget

Add a scalable view of the Historical Data Viewer to any page as a widget. This widget is designed to be linked to a parent tag, which may be either a Context, or a user-defined type that was created from a Context tag. Alternatively, you may select an existing pen group for it to display.

Draw Text Widget

The Draw Text widget is used to display the current value of any of a tag as text. Units (if any) will not be displayed and numeric values will display either 0 or 8 decimal points with no option for user-configuration. If you require just one decimal points of accuracy, or if you would like to display the engineering units that the value represents, then the Numeric Value Widget will be a better choice.

DriverSelect Widget

The DriverSelect widget is used to provide operators with a means to select one of the configured drivers to use exclusively, or to allow the DriverMUX tag to work automatically.

Droplist Control Widget (Legacy version)

The Droplist widget can write an operator-selected value from a defined list to an output device. The write occurs when a value is selected in the list. Use of the confirmation dialog is suggested.

If the linked tag's Questionable Data flag is set, a question mark will be shown before every item in the list.

When displaying Memory Tags that are configured to allow the value to be cleared, the first entry will be "No Data", having a value of "Invalid".

Duration Selector

Select the default time duration for a report.

A button displaying the currently selected duration and a time selector icon

Clicking the widget on the page will open a dialog that allows you to enter a number and select a unit of time.

Enter a value in the numeric field and select a unit of time from the dropdown.

Edit Property Checkbox

The Edit Property Checkbox widget provides a way for operators to switch a specific property on and off. You choose which property can be edited when configuring the widget. These widgets can allow access to certain properties that need to be updated, without granting operators full access to the Application Properties dialog.

If the property can have values other than zero and one, use the Edit Property Field widget.

Edit Property Field

The Edit Property widget is used to allow operators to change an application property value. You choose which property can be edited when configuring the widget. These widgets can allow access to certain properties that need to be updated, without granting operators full access to the Application Properties dialog.

If the property can have values of only zero and one, use the Edit Property Checkbox widget.

Elapsed Time Widget

The Elapsed Time widget is used to display the current value of a Totalizer tag using a time format in hours : minutes : seconds.

Enable Polling Checkbox Widget

Use this widget to give operators the ability to enable or disable polling without needing to open the Polling Driver's properties dialog. Operators must possess either the Modify Tags privilege or the Manual Data privilege to change this setting.

Equipment / Status Color Indicator

Status color indicators can be found in the folders Equipment, Indicators >> Basic, and High Performance. These are images of equipment or ISA symbols that take their color from a Style Settings tag. You can choose whether the indicator should use the style for Digitals, High Performance, or an Equipment type.

Execute / Cancel Button Widget

The Execute / Cancel Button widget is used in combination with either a Set Value Button Widget or a Numeric Entry Widget when that widget's confirmation option is configured to Set Before Execute. This button must be linked to the same I/O tag as the Set Value button or Numeric Entry widget, and that tag must be configured to write.

The exception is if the Set Value uses a separate Feedback tag, in which case this button must be linked to that feedback tag. Refer to the configuration example in the topic, Set Value Button Widget.

Export Comm Log Widget

The Export Comm Log Widget is a button that users can press to export communication log files instantly rather than waiting for a time or numeric limit to trigger the write.

Fast Scan Widget

The Fast Scan widget is used to draw a button that the operator can use to control the poll rate for the associated station. The following example shows a polling driver site draw below the fast scan button. A green outer ring in the site draw indicates normal polling while a blue outer ring indicates that fast scan mode has been enabled.

Folders

Three styles of folder are provided in the palette, but these are all variations on the same widget.

Form Reset Button Widget

This reset button is used with other form-related widgets. When clicked, this widget will reset every form entry enabled widget on the same page back to it's original value at the time of the associated timestamp. The reset button must be on the same page or pop-up as the enabled data-entry widgets.

Frame

A frame is similar to a border, except that it provides a much greater range of formatting options. Frames are used in the construction of Folders.

Three frames.

Glance Meter Widget

The Glance widget represents the associated tag's value as a pointer needle within a bounding arc. There are no scales.

Glass Gauge Widget

The Glass Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Grid

The grid shape creates a rectangular area of any color, visually divided into smaller rectangles by lines.

The background and the lines can be given any color you prefer, or either can be made transparent. Lines may be solid or dashed.

Grundfos Custom Data Log Widget

Used by: Grundfos CU36X Pump Controller Custom Data Log tag to display information collected by that tag. Data beyond Timestamp depends on configuration of your Grundfos controller.

Grundfos Event Log Widget

Used by: Grundfos CU36X Pump Controller Event Log tag to display information collected by that tag.

HDV Button Widget

Create a button that opens an Historical Data Viewer window with a preselected set of tag values, over a preset time range. The HDV page that opens will include all of the standard tools for changing the tag selection, legend, time range and scale factor.

HDV Hotbox Widget

Create a hotbox that opens an Historical Data Viewer window with a preselected set of tag values, over a preset time range. The HDV page that opens will include all of the standard tools for changing the tag selection, legend, time range and scale factor.

Because hotboxes are not visible until the pointer is over them, you are advised to add a label that will help operators find this control.

Historian Status Widget

You can monitor the operational status of all of the Historian tags in your application using the Historian Status widget. Many developers choose to create a page that is dedicated to monitoring the state of their application. The Historian Status widget is usually placed in a prominent location on such a page.

You can find this widget in the palette folder: Analytics >> Trends & Historical Data

History Stats Value Widget

When linked to an analog or digital tag as its data source, the History Stats Value widget will display any one of a selection of statistics about that tag's value. The time span for the statistic must be specified by the operator. You can also allow them to display a different statistic.

The widget updates its value only when the dates are adjusted, and the selected dates are saved per-user session

Horizontal Button Widget

The Horizontal Button widget, one of the native widgets for Selector Switch tags, is a control method used to output one of three possible values. The values will be those configured for the three positions of the selector switch, 0 to 2 in order from left to right.

Horizontal buttons in a normal operating state:

HP Analog Bar

A component of the Analog Bar & Indicator Widget. Refer to that topic for a full discussion.

You may use this widget to build your own custom High Performance HMI widgets.

Bar showing most features enabled

HP Analog Indicator Widget

A component of the Analog Bar & Indicator Widget. Refer to that topic for a full discussion.

You can use this widget to build your own custom High Performance HMI widgets.

Indicator showing a recent trend direction

HP Radial Gauge

The High Performance Radial Gauge widget is a radial version of the HP Analog Bar widget.

This example uses default colors and shows an expected range, recent values, a high alarm (high priority) and a low alarm (critical priority). The widget gives you the option of displaying the alarm ranges using either the matching priority colors or gray.

Illuminated Toggle Switch Widget

The Illuminated Toggle Switch widget is a control method used to output either of two possible values. When used with a digital I/O tag, the switch will send a 1 for on and a zero for off. When used with a Selector switch, the values will be those configured for the first two of the three possible positions of the selector switch.

Image Change Widget

The Image Change is a flexible widget, used to indicate a change in state of its associated tag by any of several methods.

Indicator Light Widget

Indicator Lights can take many forms. Each form is composed of a light and a frame. You can select different lights and frames for each indicator that you have drawn, mixing and matching the pieces.

I/O Multi-Text

The text displayed comes from the linked Style Settings tag (Default if not selected). To use this widget you must:

  • Create an I/O and Calculations tag and assign an Equipment Type.
  • Create a set of Value entries in a System Styles tag for that Equipment Type.

Last Logged Value Widget

The Last Logged Value widget is used to display the value last written to a log file (if any), for either a Totalizer tag or a counter tag.

LCD 5x7 Matrix Widget

The LCD 5x7 Matrix widget represents the associated tag's value as an dot matrix (LED) display. An active alarm will cause the numbers to use the alarm color.

LCD 7 Segment Widget

The LCD 7 Segment widget represents the associated tag's value as an LCD display. An active alarm will cause the numbers to use the alarm color.

LCD Arc Widget

The LCD Arc widget represents the associated tag's value as a series of tick marks, a percentage of which are highlighted according to the tag's value. An option in the configuration enables the meter to display alarm values as red tick marks beyond the alarm set point.

LCD Bar Widget

The LCD Bar widget represents the associated tag's value as an dot matrix (LED) display. If configured, an active alarm will cause the dots above the alarm set point to use the alarm color. Two versions are included in the palette: one with a single column of wide images and one with an array of small images.

LCD Meter Widget

The LCD Meter widget represents the associated tag's value as speedometer type of gauge with a series of tick marks, a needle, and a numeric scale. A percentage of the tick marks will be highlighted according to the tag's value. The numeric portion of the meter will flash red when the linked tag is in an alarm condition.

LCD Ring Widget

The LCD Ring widget represents the associated tag's value as a highly stylized meter, with a numeric display and a series of tick marks, the number of which fluctuates according to the tag's value. An option in the configuration enables the meter to display alarm values as red tick marks beyond the alarm set point.

Left Bar Widget

The Left Bar widget is used to display a tag's value as a horizontal bar, the length of which increases from the right towards the left as the tag’s value increases. When the tag’s value is at a minimum, the bar will be shown as a thin line at the right edge of its range. When the tag’s value reaches its maximum, the widget will be displayed as a rectangle, filling the range.

Legacy Set Value Button Widget

The Legacy Set Value Button tag widget is similar to the Push Button widget, but with a plain appearance and more options. It is used to create a button that operators can use to write any given value to an RTU or PLC.

A typical Legacy Set Value button

Legacy Set Value Hotbox Widget

The Legacy Set Value Hotbox tag widget is identical in function to the Legacy Set Value Button widget. The difference is only in its appearance in your applications. Where the Legacy Set Value Button widget creates a click-able button, the Legacy Set Value Hotbox creates only a rectangular hotbox marking an area where the operator can click. It is up to you to make it clear to the operator what will happen when the hotbox is clicked.

One way that this widget might be used is superimpose hotboxes over an image of equipment from your facility. The boxes should be located over the controls familiar to the operators.

A typical Legacy Set Value hotbox. A label or other target is recommended.

Linear Gauge Widget

The Linear Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value. This meter displays the tag’s value as text, and includes the engineering units in addition to the dial.

Lock Level Box Widget

A Lock Level Box is an Alarm Priority Box, configured to indicate that a Control Lock exists and to show the associated Lock Level number.

Lock Level Icon Widget

A Lock Level Icon is an Alarm Priority Icon, configured to indicate that a Control Lock exists and to show the associated Lock Level (priority) number.

Locks List Widget

A Locks List widget is an Alarm List widget, configured to display active Control Locks.

Make Active Widget

Used in association with the Alarm Notification System, the Make Active tag widget will create a button that can be clicked to select the associated Roster tag as the active roster. This is used to select who will be contacted by the call-out system in the event that an alarm has been triggered and has gone unacknowledged for a defined period of time.

Metal-Themed Meter Widget

The Metal widget represents the associated tag's value as photorealistic meter.

Meter 1 Widget

The Meter 1 widget is used to represent the associated tag's value as a round meter whose dial fluctuates according to the tag's value, and which also displays the value as text. The engineering units of the tag (% in this example) are also shown.

Meter 2 Widget

The Meter 2 widget is used to represent the associated tag's value as a half-round meter whose dial fluctuates according to the tag's value, and which also displays the value as text. The engineering units of the tag are also shown.

Meter 3 Widget

The Meter 1 widget is used to represent the associated tag's value as a numeric display, including the engineering units of the tag (% in this example) in the lower right corner.

Modem Tools Library

Modem Indicator Widget

The Modem Indicator widget displays a graphic of an active modem control, showing the name of the associated Modem tag. When the associated modem is dialing out or answering an incoming call:

  • The widget will flash (green and red activity lights will flash on the control when the modem is active).
  • The text "Incoming Call" will be displayed (for incoming calls).
  • The number being dialed will be displayed (for outgoing calls).

If the modem has failed for whatever reason, a red X will be drawn through the image.

Event Log List

With the Event Log tool you can draw a list that displays the last 256 entries from the Modem Manager's internal log buffer. The most recent entries are shown at the bottom of the list.

Save Log Button

Create a button that the operator can click to save the Modem Manager's internal log buffer to a file for later analysis. View this file with the Event Log List.

Modem Statistics

Use the Statistics tool in the Modem Tools folder of the Widgets palette to draw a list of modem call statistics for analysis.

This differs from the Event Log List, which is used to view the modem entries in the Modem Manager's internal log buffer.

Modem Status

Use the Status tool in the Modem Tools folder of the Widgets palette to draw a list of modem status information for monitoring. Use this tool's properties dialog to view information that is available for each modem. Use the buttons in the center column to select the status monitoring values that you wish to display.

Momentary Button Widget

The Momentary Button widget is used to draw a button that will send one value when pushed and the same or a different value when released. Both the value to write when pushed, and the value to write when released, must be provided before the button will be enabled. While similar in appearance to a Legacy Set Value Button Widget, it has a very different purpose.

Multi-Color Widget

The Multi-color tag widget is used to display a variety of rectangular color swatches in response to changing conditions within the application.

Multi-Line Text Widget

The Multi-Line widget is not linked to any tag. It can be found within the Widgets palette, within the Tools folder >> Standard sub-folder.

Multi-Text Widget

The Multi-text tag widget displays a variety of messages, each in its own color, in response to changing conditions within the application.

Multi-Write Button Widget

The Multi-Write button is used to create a button, with which operators can trigger the operation of a Multi-Write tag.

Multi-Write Hotbox Widget

The Multi-Write hotbox is used to create an area that operators can click within to trigger the operation of a Multi-Write tag.

Nautical Gauge Widget

The Nautical Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Network Link Widget

The Network Link tag widget is used to draw a line indicating the value of the associated Network Status tag. It can tell an operator whether the network link is active, broken or if its current status is unknown.

Note List Widget

Creates a display area on a page for notes that have been added to the associated Notebook tag. A scroll bar will be added to the right edge of the widget when there are more notes than will fit in the given area.

Numeric Entry Widget

The Numeric Entry widget is used to create an entry field into which operators may enter numeric values to write to the associated PLC or RTU. If the Questionable flag is set on the linked tag, the indicator will be displayed to the side of the text field, within its own box.

Numeric Value Widget

The Numeric Value widget is used to display the current value of any of a tag as a number. Units (if any) will be displayed, depending on how you configure the object.

ODBC Statistics

The Show Stats widget for the ODBC manager provides a click-able button that operators can use to view connection statistics.

Open HDV Button

When drawn on a page, this button provides a link to open the Historical Data Viewer as a pop-up with predefined settings for pen group and time duration.

Open HDV Hotbox

Found in the Standard Library folder of the Widgets palette. When drawn on a page, this hotbox provides a link to open the Historical Data Viewer. This tool differs from the Historical Data Viewer entry in the menu in that it can be preconfigured to open a particular pen group and display a pre-set time duration.

Legacy Page Button Widget

The Page Button widget is a navigational tool, used to create a connection from one page to another.

Buttons are always visible, and can be configured with their own label so that operators will know what to expect when they click.

Page Close Button Widget

The Page Close Button widget is a navigational tool, used to allow operators to close pop-up pages. Some operators may find that a Close button is more convenient to use than the "x" in the upper right corner of the window.

Page Close buttons do not operate on full-screen pages. Operators may close only pop-up (windowed) pages.

Legacy Page Hotbox Widget

The Page Hotbox widget is a navigational tool, used to create a connection from one page to another.

The hotbox is invisible unless the pointer is over it, at which time it turns yellow (or any other configured color). It is common to place a hotbox around a text label or an image so that operators will know where to find it, and what page to expect when they click.

Pie Chart Widget

This widget is used to display the relative values of a set of tags in the form of a two-dimensional pie chart.

The chart updates continuously with changing values. The current sum of the included tags is taken as 100% and each slice of the pie represents the matching tag's contribution to that total.

Pie Widget

The Pie widget represents the associated tag's value as portion of a circle. The darker portion of the chart starts at the angle you specify, where vertical (North) is zero degrees. Increasing values are indicated by the darker portion sweeping in a clockwise direction. The colors are set by the LED (analog) values of a selected Style Settings tag, and values above the linked tag's alarm setpoint can be indicated.

PLC Alarm Control Widget

Relevant only to the PLC Alarm Tag. Allows limited configuration of the PLC alarm associated with the linked tag.

Plot Data Widget

The Plot Data tag widget is used to plot the value of the tag being drawn on a graph similar to that displayed on the Historical Data Viewer page. Drag the plot to the right to see earlier data that is no longer visible. Drag the plot all the way to the left to resume the live trend.

Polled Station Widget

The Polled Station tag widget is used to display the number of the RTU that is actively being polled. Displays * between polls.

Power Widget

The Power widget represents the associated tag's value as a photorealistic meter.

Pressure Gauge Widget

The Pressure Gauge widget represents the associated tag's value as radial meter.

Program Spawn Widget

The Program Spawn widget is drawn as a button on any page. In response to being clicked, it will run any configured program that can be found on your computer.

Pulse Beacon Widget

The Pulse Beacon widget indicates the selected site on a map. It is one component of a site icon and is not meant to be used alone.

Push Button Widget

The Push Button widget provides a method for operators to issue control actions, via the linked tag. The widget's configuration holds the value that will be written to the linked tag when the button is clicked.

Quarter Arc Gauge Widget

The Quarter Arc Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Recipe Delete Widget

Equivalent to the Delete button from the Recipe & Batch Management Page.

Operators can use the Delete button widget to remove the currently selected version of a recipe. If there are no more versions, the current recipe will be deleted.

Recipe Export Widget

Equivalent to the Export button from the Recipe & Batch Management Page.

Operators can use the Export button widget to write the parameters of the currently selected recipe to either an Access or an Excel file.

Recipe Note Widget

Notes are associated with batch runs, and can be required by the Start button.

Optionally, you can use this widget to create a text entry field where operators can create a note to be used by the next batch run.

Recipe Retrieve Widget

Operators can use the Retrieve button widget to read the current values of recipe parameters from a PLC. This will query the PLC to which the selected Recipe Book is connected. If no values are available, matching the parameters in the Recipe Book, all recipe values will be set to blank.

This tool may be useful to let the operator know what parameter values were last being used in the PLC.

If the "Recipe Name" Parameter tag has an address, that value will be read out of the PLC as well and will be shown in the recipes droplist. This lets the operator know what recipe the PLC was last running. The same is true for the Parameter tag, "Recipe Version".

Recipe Revert Widget

Operators can use the Revert button widget to discard unsaved parameter values and reload the saved values for the currently selected recipe and version, associated with the linked tag.

Recipe Save Widget

Operators can use the Save button widget to write the current set of parameter values to the currently selected recipe and version in the linked tag.

Recipe Save As Widget

Operators can use the Save As button widget to store the current set of parameter values to a new recipe or version associated with the linked tag.

Recipe Selector Widget

Operators can use the Recipe Selector widget to choose which recipe to run. Recipes must already exist within the linked Recipe Book tag.

Recipe Update Widget

Operators can use the Update button widget to write new values to a running batch process for the currently selected recipe & version. This action is protected by a security privilege. The button is enabled only while a process is running.

Recipe Version Selector

Operators can use the Version Selector widget to select which version of a recipe to process. The drop-down control is enabled only when there are versions to choose from.

Release Token Button

The Release Token Button widget gives users a way to release a Control Token that they had obtained.

The button will be grayed-out / disabled if the user does not have the Control Token. Users other than Control Token Administrators cannot release a token that they do not have ownership of.

Relinquish Command Button Widget

The Relinquish Command Button widget can be used by an authorized operator to relinquish (remove) a value set to a specific priority in a BACnet address. When that happens, lower priority commands will be allowed to set their values to the object. The priority level is determined by the Write Address property of the I/O tag.

Report Tools Library

Report Button Widget

The Report Button tag widget is used to create a button that the operator may click to generate a predefined report. The report must be configured within the associated Report tag, but other widgets are available to allow the operator to change the configuration.

Report Destination Widget

The Report Output Type tag widget is used to draw a group of objects that operators can use to configure the output format and path for their report.

Report Iterations

This tool is used to draw a field into which operators can enter the number of report iterations (i.e. consecutive reports) they wish the report generator to produce. For example, if an operator wishes to generate a report for each day in the last month, they could set the report time period to the last day of the last month (e.g. Thu Nov 30, 2001 12:00 pm), and then enter "30" in the Iterations Entry field.

Report Options Widget

The Report Option List tag widget is used to draw a trio of check boxes that operators can use to select certain formatting attributes for their report.

Report Tag List Widget

The Report Tag List tag widget is used to draw a group of tools that operators can use to select the tags to be included in a report.

Report Type Widget

The Report Type widget is used to create a drop-down list from which operators can select the type of report they wish to generate.

Reporting Period Widget

The Reporting Period widget is used to draw spin boxes and a drop-down list that operators can use to configure the time period for a report. The available presets are shown to the right of the completed widget:

Reporting Period (Enhanced) Widget

The Reporting Period Enhanced widget provides every possible option to configure the time period for a report. You can select from of:

  • A set of predefined full time periods.
  • A set of predefined time lengths prior to the trigger.
  • A custom time period, of any duration and end time.
  • An offset relative to the trigger event.

Request Token Button Widget

The Request Token Button widget gives users a way to request a Control Token for an output tag or a set of output tags.

The button will be grayed-out / disabled if the user already has the Control Token. If no-one else has a control token on this tag and if the user is authorized to use the control, the request will be granted immediately. Otherwise, (by default) the request will be added to a queue of people asking for control of the tag. (Use the property, ControlTokenManualRequestOption to alter this behavior if needed.)

Reset Button Widget

The Reset Button widget is used to create a button in your application that will reset a Totalizer tag or a Counter tag to zero.

Reset Polling History Widget

The Reset Polling History widget is used only by the Enron Modbus Driver. It is drawn as a button, which operators may click to change the next index to be polled back to the first index, which may be a one or zero depending on driver settings. This can be used to re-read all data in the device.

Reset Target Widget

The Reset Target widget is used to create a hotbox that will function in the same way as a Reset Button widget. When an operator clicks on the hotbox, the associated Totalizer tag or counter tag will be reset to its starting value. The reset target is shown as a simple rectangle of the configured color. To make its purpose clear, you should consider placing it above a symbol or text that describes its purpose, as shown here (label added as text).

Retro Gauge Widget

The Retro Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Rewrite Outputs Widget

The Rewrite Outputs widget is used to force a driver to re-send the last set of values, written to outputs. The button will be enabled only if the driver has been configured to store the values.

Right Bar Widget

The Right Bar widget is used to display a tag's value as a horizontal bar, the length of which increases from the left towards the right as the tag’s value increases. When the tag’s value is at a minimum, the bar will be shown as a thin line at the left edge of its range. When the tag’s value reaches its maximum, the widget will be displayed as a rectangle, filling the range.

ROC Driver History Info Button

Creates a button that operators may press to access details about the driver's history. This widget will work only with devices that use the ROC Plus protocol..

ROC History Polling Timestamp Reset

Creates a button that operators can press to reset all of the device's history addresses, resulting in a full read of the RTU on the next poll, rather than only those records that were added since the last successful poll. This will have no effect on data that has already been saved by the VTScada Historian.

Roster Alarm Test Widget

The Roster Alarm Test widget is used to create a check box that operators can click to generate an alarm that will test the roster configured for the Alarm Notification System.

Roster Control Status Widget

Monitor the status information of rosters in the application and force a roster out of a failed state. A reset button will become enabled if a roster is in a failed state. Click the enabled reset button to kick the roster out of its failed state. This widget is subject to realm and Global Tag & Area filtering.

You can find this widget in the palette folder: Tools >> System Status Tools

Rotary Control Widget (Knob)

The Rotary Control enables operators to select a value to write to hardware by turning a knob. This is done by clicking on, then dragging the control clockwise or counter-clockwise. The value that will be set is shown in a tooltip while dragging.

Selector Switch Widget

The Selector Switch widget is used to represent a Selector tag as either a 2-position or a 3-position switch. A common use is to create a Hand-Off-Auto selector.

Service Status Widget

The Service Status widget duplicates the content of the Services Page on a page of your choice within your application. Note that your page must be protected by a custom security privilege that you create. The Service Page Access privilege will not restrict who can view this widget on your page.

Refer to the Services Page for a detailed description of the features of the Service Status widget.

Service Status including the optional legend

Set Analog Value Widget

The Set Analog Value widget is used to create a button that operators may click to write a specific value to an I/O address of the associated tag. Several may be drawn to provide a range of value choices. Note that the configured value is not shown as part of the widget - if you would like it to appear (as shown in the following example) the value must be drawn on the page as text.

Set Value Button Widget

The Set Value Button widget is used to write a value to an output tag, and has the following features that differentiate it from the Legacy Set Value Button Widget.

  • The value to write can come from another tag or an expression.
  • Can display a label or an image.
  • If using a label, you can select the font.
  • Can accept feedback from a tag or expression other than the one used by the linked tag.
  • If the feedback value differs from that configured Feedback Value, a mismatch condition will be shown.
  • Can be disabled.

A typical Set Value Button widget

Show Stats Widget (ODBC)

The Show Stats widget is used to place a button that will open the ODBC Statistics dialog.

Site Alarm List

Use the Site Alarm List widget to draw an alarm list that is prefiltered to show only the alarms in child tags of the linked site or context.

It can also be configured to show all alarms in any tag having an Area property that matches the linked site. Or, it can filter for both child tags of the site, and all tags having a matching Area property.

An acknowledge button will be available for each entry, provided that the logged-on operator has the security privilege required to acknowledge these alarms.

Site Details Widget

Can be drawn directly by the Context tag. Provides the entire content of the Site Details page, but drawn on a page of your choice.

Site Draw Widget

The Site Draw tag widget is used to draw station symbols that represent RTUs These display the status at the station being drawn, using two, concentric color indicators. The Site Draw may be configured to display a label or to show only the indicator circles.

A Site Draw legend is available in the Site Tools folder of the Widgets palette. Adding this to your page will help operators interpret the meaning of the color indicators. The center dot will change color according to the status of I/O within the site - Invalid data or an alarm in any I/O tag will indicted by the dot. The outer ring indicates the status of device driver communication with the site.

Site Icon Widget

The Site Icon Widget creates a color indicator that both displays the status of communications to the associated station and provides a click-able link to the built-in Station Page for the associated station tag. This is very similar to the Site Draw widget, and uses the same color system for its concentric rings.

Site Summary Widget

The Site Summary Widget creates a color indicator that both displays the status of communications to the associated station and provides a click-able link to the built-in Station Page for the associated station tag. It also provides relevant information about the underlying station tag. The full display mode option is shown here:

Slider Widget

The Slider widget is used to create an output control. An operator can drag the slider to set a value which will be output by the associated tag.

Sparklines Widget

Used by: I/O and Calculations tag (although portions may be used by any numeric tag).

The Sparklines widget is similar to a Plot widget but allows operators to see at a glance whether the tag has values below, within, or above the expected range.

A Sparklines widget for an I/O tag, showing the expected range (blue band),
a low alarm, high alarm and high-high alarm.

SMS Indicator Widget

The SMS Modem Indicator widget displays a graphic of an active SMS modem control, showing the name of the associated SMS Appliance tag. It is similar to the Modem Indicator Widget, but displays SMS events rather than a continuous indication of the modem status.

Note the signal strength bars to the right of the device status display, indicating whether your device is receiving an adequate signal from the local tower.

Spider Graph Widget

Used by: I/O and Calculations tag (although portions may be used by any analog numeric tag).

The spider graph widget allows operators to see at a glance whether several related tags have values below, within, or above their expected ranges.

A spider graph showing three tags and their expected value range.

String Entry Widget

The String Entry widget are used with String I/O tags that are configured to write values. Operators can enter the value to be written in the data entry field. The write operation will happen when focus leaves the field, whether by an Enter, a tab, or a click on some other widget. Characters can be masked for privacy.

The example is configured to show the optional title and bevel.

A form field is displayed. A label on the top-left side says "Value to write". A narrow grey line borders the field, evenly spaced, without intersecting the label.

Submit Button Widget

The submit button is used with other form-related widgets. For data entry widgets with "Include in Form" enabled, values can be filled into their fields but it won't be submitted until this submit button is clicked. The submit button must be on the same page or pop-up as the enabled data-entry widgets.

Tag Icon Marker

Most VTScada widgets contain a tag icon marker. This is the yellow symbol that blinks a question mark when the linked tag's Questionable flag is set, and an exclamation mark when the linked tag is using manual data. If a widget has not yet been linked to a tag, the indicator will show a star (asterisk).

Tag List Widget

The Tag List widget provides a highly configurable means of displaying any or all of the child tags attached to a selected parent. If no parent tag is selected, then root of the tag hierarchy is considered to be the parent and any set of tags in the application can be displayed in the list, subject to the configuration of the filtering options.

Text Change Widget

The Text Change tag widget is used to represent the associated tag's value as a text string that changes (text or color) based on the tag's value. While this widget is available to analogs, it is most commonly used with digital and other tags that have clearly defined states (values from 0 up to 3).

If linked to a tag that has values above 3, this widget uses the modulus (remainder) of the tag's value divided by four. For example, 7 is read as 3.

Thermometer Widget

The Thermometer widget represents the associated tag's value as a photorealistic alcohol thermometer.

Toggle Button Widget

The Toggle Button widget is used to display an up / down toggle button, providing digital control and feedback.

When the toggle is pressed (or "down") it has a blue highlight and displays the "down" label. When "up", it does not have the blue highlight.

You control whether the signal sent for pressed / down is a zero or a one. The signal sent for "up" will be the opposite.

Toggle Polling Button Widget

Use this widget to give operators the ability to enable or disable polling without needing to open the Polling Driver's properties dialog. Operators must possess either the Modify Tags privilege or the Manual Data privilege to change this setting.

Toggle Switch Widget

The Toggle Switch widget, one of the native widgets for Selector Switch tags, is a control method used to output either of two possible values. The values will be those configured for the first two of the three positions of the selector switch, 0 to 1.

A variety of switch images are available in the Selector Switches images group. A few of the available choices are shown here (for every On image there are matching images for the Off state and the Invalid state, drawn in the same style).

Tokens List

A Tokens List widget is an Alarm List widget, configured to display active Control Tokens.

Refer to Control Tokens for a full explanation of what Control Tokens are and how they work.

Token Requests List

A Tokens Requests List widget is an Alarm List widget, configured to display active Control Token Requests.

Refer to Control Tokens for a full explanation of what Control Tokens are and how they work.

Top Bar Widget

The Top Bar widget is used to display a tag's value as a vertical bar, the length of which increases from the bottom towards the top as the tag’s value increases. When the tag’s value is at a minimum, the bar will be shown as a thin line at the bottom of its range. When the tag’s value reaches its maximum, the widget will be displayed as a rectangle, filling the range.

Two Color Bar Widget

The Two Color Bar tag widget is used to display tag data using an animated, multi-colored bar. Its appearance is similar to the Color Fill widget with the addition of a second color that will be displayed when the value goes above a set point. A common use of this second color is to provide clear notice that a value is above its safe limit.

Totalizer Widget

The Totalizer widget calculates and displays the combined total of the value of the Pulse Input tag being drawn within a user-defined period of time. Each time the user-defined period of hours has cycled, the Totalizer object will automatically reset to 0 and will begin to recalculate.

Vertical Buttons Widget

The Vertical Buttons widget, one of the native widgets for Selector Switch tags, is a control method used to output one of three possible values. The values will be those configured for the three positions of the selector switch, 0 to 2 in order from top to bottom.

Web Browser Widget

The Web Browser widget is used to display the contents of a specified web page.

Web Browser Navigate Button

Use the Web Browser Navigate Button widget to provide a button that operators can click to navigate to a pre-defined URL in a selected Web Browser Widget. The button will not prompt for a destination URL.

If more than one Web Browser widget exists on a page, give each a name and configure the button with the name of the browser it should control.

Web Browser Navigate Hotbox

Use the Web Browser Navigate Hotbox widget to provide a target that operators can click to navigate to a pre-defined URL in a selected Web Browser Widget. The widget will not prompt for a destination URL.

If more than one Web Browser widget exists on a page, give each a name and configure the hotbox with the name of the browser it should control.

Write Priority Indicator Widget

The Write Priority Indicator widget is used to display the status of a command-able property in a BACnet device. It is composed of two parts:

  • A priority level indicator that shows the priority of the effective command in the device (the highest priority with a non-null value)
  • A command status box that changes its color based on the status of the command priority set by the Write Address of the attached tag.

(sample shows "default")


Active Indicator Widget

Used by: Data Flow RTU Tag, Polling Driver Tag.

* Does not use the Style Settings tag.

The Active Indicator widget is an indicator that turns green when the associated RTU is the actively connected site. The indicator will otherwise be red.

Configuration options in the properties dialog for this widget are as follows:

The properties dialog includes the standard Disable Options: Disable trends, Disable context menu, disable tooltips.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Polling\

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


Add Lock Button Widget

Used by: All tags

* Does not use the Style Settings tag.

The Add Lock Button widget allows authorized operators to add a Control Lock to the linked tag. If the linked tag is a parent of other tags, then all output tags below that parent will be locked.

Authorized operators are those with the Add / Remove Locks privilege.

Related information:

Control Locks

The properties dialog for the Add Lock Button widget:

Tag

Select the tag for which this button will add a lock.
A lock can be applied only to a single tag, but if that tag is a parent, Control Locks will apply to all of the child tags.

Level

Select the Lock Level (priority) for the locks that will be created using this button. Refer to Control Locks

Label

You should provide a label that describes which tag (or hierarchy of tags) will be locked by this button.

Font

Select the font to be used by the label

Image File

Select an image to be used in addition to, or instead of the label.

Confirmation

If selected, operators will be prompted to confirm that they wish to create a Control Lock.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Control Locks


Add Note Button

Used by: Notebook.

* Does not use the Style Settings tag.

Creates a button on the page that operators may click to add a note to the associated Notebook. Two versions of the button are available.

Configuration options for the button are as follows:

Button Label

Enter the text that will be displayed on the button. If the option, "Show a +" is selected, no label will be shown, regardless of the contents of this field.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

Provide text for the tool tip that will be displayed when the operator moves the cursor over the button. The associated Notebook tag name will also be shown - the name to the upper right and the tool tip to the lower right.

Show a "+" rather than label

When selected, the button shows only a plus symbol (as illustrated above).

Widget Folders:

Basic Components\Specialty\Notebook\

Tag Types\Data Logging & Reports\Notebook\


Add Note Field Widget

Creates a note entry field, similar to that found in the Operator Notes page. Operators can use this to add notes to a preselected Notebook without leaving the page to which this widget was added.

Configuration options for the field are as follows:

Color - Foreground and Background

Set the color to be used by text in the editing field and the background color of the field itself.

Font

Select the Font tag that will control the appearance of text within the editing field.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Specialty\Notebook\

Tag Types\Data Logging & Reports\Notebook\


Alarm Lists and Related Tools

You can add an alarm list, configured to show some or all of its tools, to any page in your application. You can customize this list in advance so that operators will see only the details relevant to that page.

All the tools required to work with an alarm list are built into the list widget, but you might decide to suppress everything other than the alarm display and provide additional buttons that perform only specific tasks. For example, rather than providing the full toolbar, you can suppress it and provide an Acknowledge Shown button and a Mute button.

The Alarm Tools folder contains a Legacy Tools sub-folder. These provide backward-compatibility with legacy applications (those built using VTScada 11.1 or earlier), which used an older form of the Alarm List.

You are advised to avoid the legacy tools when building new applications.

Legacy alarm tools worked with named lists. This is no longer true as modern alarm lists have no names (The Legacy Alarm List widget is actually a modern list, customized to look like the legacy list.)
All the alarm library tools described in this topic will work with all lists in the current page or group. If you intend to show more than one list on a page with tools from the alarm library, combine them into groups.


Alarm List

Related Widgets:

Locks List Widget

Tokens List

Token Requests List

Tokens and Token Requests List

Used to draw a customizable alarm list on any application page. This is what you see in the The Alarm Page, including all tools and filters. When drawing your own list, you have control over which portions of it are shown and how they are configured. You can recreate the alarm page (all options enabled), create a minimalist alarm banner, or some variation in-between.

Alarm list as a simple banner.

If you choose to hide groups of tools, then operators cannot change the values that you set. This banner example shows no tools and uses a column format that does not provide an Ack button. The status bar, border and column titles are still enabled.

Related properties: AlarmPageHistoryRecordLimit- Maximum number of alarms that can be viewed at one time in an Alarm List. AlarmPageHistoryRecordHardLimit- Absolute maximum number of alarms that can be viewed in an Alarm List, using the Load More button.

If you have applied Global Tag & Area Filtering, you will see only alarms that pass the filter. A warning is provided, as shown. Alternatively, you can configure the list to ignore Global Tag and Area Filters.

Tag

Link to a tag if (and only if) you want this list to show only alarms from that tag and its children. Use this to create an alarm display that is specific for one site, assuming that the tags for the site are in a hierarchy under selected parent.

Alarm Database

Show alarms in all databases (the default) or from only one alarm database. If set to All, refer to the Remember Selected Database parameter for further control over the widget's behavior. An advanced configuration option is to create named groups of databases for selection. (See: Alarm Database Groups)

Remember Selected Database

(The last tool in the configuration panel, but relevant to the Alarm Database selection.)

Applies only if the Alarm Database parameter is configured as the default (All) and the toolbar is shown so that operators can select a specific Alarm Database while viewing the list. In this case, behavior between visits to the page where this widget is drawn will vary according to whether Remember Selected Database is selected.

  • If selected, then the last database selected in this widget by the operator will be the one they see the next time they return to the page where this widget is drawn. The database selection will continue to include all other choices.
  • If not selected, then the widget will show All Databases each time the operator returns to the page where this widget is drawn, regardless of which database they chose to view earlier. (Default behavior.)

Starting List

The lists are History, Active, Unacked, Current, Shelved, Disabled and Configured. The History list is the first and therefore the default. Current, Active or Unacked (unacknowledged) are the most common lists to use. A related option (Show List Selection) will deny operator selection of other lists if deselected.

Column Format

Select a column format from those defined in the Alarm Database. The selection shows only the name of the format, therefore the following table is provided as a handy reference.

Column Format | Displayed columns
Alarms | Time - Priority - State - Event - Area - Name - Description - Value - Setpoint - Units - Operator - Notes
Events | Time - Area - Name - Description - Workstation - Device - Operator - Notes
Legacy 1 | Event - Priority - Time - Area - Name - Description - Operator
Legacy 2 | Time - Name - Description
Legacy 3 | Time - Ack - State - Event - Priority - Area - Name - Description - Operator
Legacy 4 | Time - State - Event - Priority - Area - Name - Description - Operator
Legacy 5 | Ack - State - Event - Priority - Area - Name - Description - Operator
Legacy 6 | Time - Event - Priority - Area - Name - Description - Operator
Legacy 7 | Time - Name - Description - Ack
Locks

Relevant only to the Alarm List Widget / Locks List Widget. Displays currently active Control Locks and provides a means for authorized operators to release those locks.

Described in Locks List Widget

Popups | Priority - Ack - Name - Description

As an advanced configuration option, you can create your own column formats by writing XML templates. See: Customize Columns in Alarm Displays

Number of Lines

Limit the number of alarms shown in the list. If there are more alarms than this, a scroll bar is added within the grid. If drawn such that there isn't enough room for this many lines, a scroll bar is added outside the grid.

Days of History

Select one of the presets: 1 day, 10 days, 30 days or 90 days, to set the right balance between the time required to populate the list and the amount of information required by the operator.

Text Size

Choose between five sizes of font for the list and the column headings. Sizes range from small to extra large where each size is two points larger than the last.

You also have the option of allowing the widget to remember and use the last user-selected font size rather than defining a default size.

Filter

This button opens the Advanced Filtering dialog. Filters are applied to and saved with the list. The filter bar is always shown with the list so that operators will know that the list they see is filtered. Operators can clear the filter temporarily, but it is reapplied whenever the page is refreshed. They can create (temporary) new filters only if you have selected the option, Show Toolbar.

In the properties dialog, a message is added beside the button to remind you that a filter was created:

Ignore Global Tag and Area Filtering

Global Tag & Area Filtering will not be applied to this alarm list when selected. The filter will still apply to the Alarm Page and to other lists of tags such as the Tag Browser.

Use Theme Color in Toolbar

By default, the title and alarm list selection bars follow the application's theme color. Deselect this option to make changes to those colors.

Background & Text Color

The background color applies to the list, toolbar area and list selection bar if you have not chosen to use the theme color for those areas. Click the 'X' button next to the Background Color to discard color selections and return to the theme color.

If you change the background color, you should also choose a text color that contrasts clearly against the background so that operators do not have trouble reading the information in the list.

Note that the Nighttime Mode tool is enabled only if the background is using the theme colors.

Show Toolbar

The toolbar is the set of buttons across the top of the alarm list. Hide this if you do not want to allow operators to use any of these functions when viewing the list.

Show List Selection

The List Selection bar is used to change what is shown in the alarm list. Hide this if you do not want to allow operators to switch to any list other than the one you configured for this display.

Show Search Fields

The search field is located to the right of the list selection bar. It enables operators to search for alarms that they are allowed to see using any scrap of information known about that alarm. Hide this if you do not want to allow operators to search for alarms other than the ones that your list was configured to show.

Show Column Titles

Column titles are useful for new operators, but those who are familiar with the alarm list will not need the titles to know what each column of information in the list means. You might choose to hide the titles on pages where the extra space is needed.

Show Active Filters

Active filters are those that operators set using the tools in the toolbar. They are shown on a bar that is added below the list selection whenever operator-defined filters are active. If the toolbar is hidden, there are no active filters and therefore no need to either show or hide this option.

When the bar is visible, less space is available for the list of alarms. Choosing to hide active filters, but still allowing operators to set those filters can cause confusion and errors.

VTScada programmers can write code to change the filter automatically. Refer to the function reference for SetCurrentFilter. This technique should be used only by advanced developers.

Show Status Bar

The status bar is shown below the alarm list. It tells the viewer which list is being viewed (History, Current, ...) and how many records are shown in the list. When viewing the History list, the status bar will include the current History Range Limitation.

Show Border

Adds a one-pixel border around the alarm list.


Ack All Button

Acknowledge all alarms. This is different from the Ack Shown button. With this tool, "all" means "all", not just "all within the filtered list".

This button is enabled only if there are alarms to acknowledge and you are authorized to acknowledge them

This button is not limited to any alarm list. "All alarms" means exactly that, excluding only those that the operator may not touch if Realm Filtering is in effect.
If your intent is to acknowledge only those alarms in the filtered list, use the Ack Shown button instead.

The properties dialog for the Ack All button:

Configure button label, and tool tip label or disable control.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

Enter the text that you want to display on this button's tool tip (which opens when the mouse pointer is rested on this button).

Disable Control

This checkbox enables or disables the button. You can disable the button using the checkbox, and through expressions or parameters.


Ack Selected Button

Click to acknowledge a single, selected alarm from a named Alarm List.

This button is enabled only when the logged-on operator selects an unacknowledged alarm.

The properties dialog for a completely configured Ack Selected button:

Configure name, button label, and tool tip label or disable control.

Name

Used only when this button is in the same page or widget as a legacy alarm list, in which case it is required to associate this button with the legacy list.

If this widget is used with a modern Alarm List, it will be associated with that list automatically. If a page will contain two Alarm List widgets, each list and its related control buttons must be grouped into a widget.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

Enter the text that you want to display on this button's tool tip (which opens when the mouse pointer is rested on this button).

Disable Control

This checkbox enables or disables the button. You can disable the button using the checkbox, and through expressions or parameters.


Ack Shown Button

Creates a button that can acknowledge all alarms shown in the named alarm list. Alarms that are not shown because they do not match the list's current filter, are not acknowledged.

Enabled only if the list has alarms that require acknowledgment, and if the logged-in operator is authorized to acknowledge them.

An example of an Ack Shown Editor dialog:

Configure name, button label, and tool tip label or disable control.

Name

Used only when this button is in the same page or widget as a legacy alarm list, in which case it is required to associate this button with the legacy list.

If this widget is used with a modern Alarm List, it will be associated with that list automatically. If a page will contain two Alarm List widgets, each list and its related control buttons must be grouped into a widget.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

The Tool Tips Label field is used to enter the text that you want to display on this button's tool tip (which opens when the mouse pointer is rested on this button).

Disable Control

This checkbox enables or disables the button. You can disable the button using the checkbox, and through expressions or parameters.


Alarm List Button

Change the Alarm List to display a different category of alarms. There are 6 possible alarm list categories (Active, Current, Configured, Disabled, History, Unacknowledged). Draw one instance of the alarm list button for each category that you might want to see displayed in the list. (See: Legacy Alarm List)

The properties dialog for the Alarm List Button:

Name

Used only when this button is in the same page or widget as a legacy alarm list, in which case it is required to associate this button with the legacy list.

If this widget is used with a modern Alarm List, it will be associated with that list automatically. If a page will contain two Alarm List widgets, each list and its related control buttons must be grouped into a widget.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

Enter the text that you want to display on this button's tool tip (which opens when the mouse pointer is rested on this button). Use this field to compensate for the brevity of the button label by providing a more complete description.

Starting List

Select the category of alarms that you want to display in the alarm list when this button is clicked. This can be one of:

  • History
  • Active
  • Unacknowledged
  • Current
  • Disabled
  • Configured


Mute Button

When clicked, this button will stop all alarm sounds (current and future). No alarm sounds will occur while this button is toggled on. Enabled only when there are alarms to mute and the current operator is permitted to use this feature.

All alarm lists are affected by this button.

See also: Silence Button

The properties dialog for the Mute Button:

Configure, button label, and tool tip label or disable control.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

A description of this tool, visible only when the operator hovers the mouse pointer over the button.

Disable Control

This checkbox enables or disables the button. You can disable the button using the checkbox, and through expressions or parameters.


Silence Button

Silence the alarm sound associated with the most recent unacknowledged alarms in your system. New alarms will sound. This button is enabled only when there are alarms to silence and the current operator is permitted to use this feature.

All alarm lists are affected by this button.

See also: Mute Button

The properties dialog for the Silence Button:

Configure button label, and tool tip label or disable control.

Button Label

The text to display on the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

A description of this tool, visible only when the operator hovers the mouse pointer over the button.

Disable Control

This checkbox enables or disables the button. You can disable the button using the checkbox, and through expressions or parameters.


Legacy Alarm Banner

Provided for backward compatibility, this will create the legacy Alarm Banner, which existed in VTScada prior to version 11.2 Do not use in new applications.

Creates a display of alarms, similar to a legacy Alarm List (Legacy Alarm List), except that you cannot filter the banner content. If there is more than one alarm, the most recent is shown at the bottom of the list.

An example of an Alarm Banner properties dialog:

Font

Select the display font for the banner, as configured in one of the available font tags.

Color

Sets the background color for the alarm banner. Because the text is drawn in white, a dark color is recommended for best visibility.

Number of lines

Sets the number of alarms shown in the banner. The most recent alarm is always at the bottom of the list.

Alarm List

Select which alarm category you wish to display in the banner. There are 7 possible alarm list categories (Active, Current, Configured, Disabled, History, Unacknowledged, Shelved).


Legacy Alarm List

Provided for backward compatibility, this will create the legacy Alarm List, which existed in VTScada prior to version 11.2 Use the current Alarm List widget in all new applications.

Used to draw a custom alarm list on any application page. See also Legacy Alarm Banner.

The properties dialog for configuring a Legacy Alarm List .

Name

Enter a name for this custom alarm list.

Font

Select a Font tag to use in this alarm list. The style and font within the Font tag are used to display the alarms and events in this alarm list.

You may choose one of the four default Font tags that are included with every VTScada application, or you can create your own custom Font tag and assign it attributes as you require.

Line Format

Select how much information is displayed in the list. Options include the following:

List Options
Status | Priority | Time | Date | Area | Message | Operator
Time | Date | Message
Time | Date | ACK | Active Icon | Status | Priority | Area | Message | Operator
Time | Date | Active Icon | Status | Priority | Area | Message | Operator
ACK | Active Icon | Status | Priority | Area | Message | Operator
Time | Date | Status | Priority | Area | Message | Operator

You can modify format of the text displayed in the Event/Status and Priority columns by using application properties. (See: Application Properties for Alarms).

Background

Select the background color you want to display for this alarm list. When the Background button is clicked, the Select Color palette will open to enable you to select the color you desire. The selected color is previewed to the right of the Background button. You can also choose to display ruled lines between each alarm.

Starting List

Select the name of the alarm list that you want to display each time the page upon which this alarm list is draw is opened. You may choose from the following alarm lists:

  • Active: Displays all alarms that are in an active state. (That is, all alarms for which the condition that caused them to trigger still exists.) Active alarms are also displayed in the "Current" alarm list (see above).
  • Current: Includes alarms that are either active, unacknowledged, or both.
  • Configured: Includes a reference to all Alarm tags that have been configured for this application.
  • Disabled: Displays all alarms that have been flagged as disabled within your application.
  • History: Displays all alarms and events that have occurred for this application, including operator control actions (e.g. output of a value to equipment), remote configuration actions (such as updating files or tags), Alarm Notification System actions (such as the notification of operators of unacknowledged alarms by voice, pager, or email), and security-related events (such as operators signing in or out).
  • Shelved: Displays all alarms that have been flagged as shelved within your application.
  • Unacknowledged: Displays all alarms that have not yet been acknowledged, regardless as to whether the alarms are still in an active state. Unacknowledged alarms are also displayed in the Current alarm list (see above).


(Legacy) Alarm Date Selector

When viewing alarm history in a legacy Alarm List, you may want to view alarms from some day in the past. Use the Alarm Date Selector to create a button that will open a calendar selector. By selecting a date from the calendar, operators can change the display to show the alarm history from that date. Double arrows at the upper corners of the calendar window allow operators to change the month displayed.

Legacy Alarm List - This button is relevant only in relation to a legacy Alarm List

Selecting Sept. 4th, 2009.

A red circle shows the current date. The tool tip for the Alarm Date Selector button will read "Alarm History Selector".

The selection of alarm list is now obsolete.


(Legacy) Alarm Go To Most Recent Button

This tool is a companion to the Alarm Date Selector. If an operator has adjusted the alarm list display to view the history for a date other than today, the Alarm Go To Most Recent button provides a quick way to reset the list.

Legacy Alarm List - This button is relevant only in relation to a legacy Alarm List

The properties dialog for this button provides only two configuration tools.

Name

Choose which legacy Alarm List this button will affect.

Show Button as Highlighted

If selected, then whenever a date other than that of the most recent alarm is been displayed, this button will gain a highlight.


(Legacy) Filter Dialog Button

Opens an The Advanced Alarm Filtering dialog dialog. Operators can use that dialog to apply one or more filters to the selected Legacy Alarm List.

Legacy Alarm List - This button is relevant only in relation to a legacy Alarm List. See also (Legacy) Filter Field Button

If the label is to include an ampersand (&), enter two ampersands (&&).

The properties dialog for this button will look as shown:

Name

Select which legacy Alarm List this button affects.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

Enter the text that you want to display on this button's tool tip (which opens when the mouse pointer is rested on this button).

The Advanced Alarm Filtering dialog

This dialog provides a variety of ways to filter a custom alarm list. Descriptions follow:

Filtering

Select the Filtering check box to enable the Alarm Filtering dialog.

OR Conditions

If selected, then the filter will pass an alarm matching any of the conditions. Otherwise the alarm must match all of the conditions.

For example, if you set Priority to "1" and Area to "East" then selecting the "OR Conditions" check box would result in filtering based on "Priority is equal to '1', OR Area is equal to 'East'". If the OR Conditions check box is not selected, configured alarm filtering parameters are "AND'ed" together. For example, deselecting the OR Conditions check box would result in filtering based on "Priority is equal to '1', AND Area is equal to 'East'".

Field

The Field column displays the available alarm list fields by which you may filter. You may choose one of:

Message for the Alarm: Used to filter the alarm list by a specific Alarm tag's Description property. Note: Wildcard characters are not permitted. Enter the full description as it appears in the Alarm tag's Description field. In the event that a Description property has not been configured for an Alarm tag, the message for the alarm will contain the name of the Alarm tag, as it appears in its Name field.

Priority: Used to filter the alarm list by a specific alarm priority. The available default alarm priority index numbers are as follows:

Alarm Priority

Index

Associated Alarm Priority Tag Name

No Alarm

0

AlarmPriority0

Critical Alarm

1

AlarmPriority1

High Alarm

2

AlarmPriority2

Warning Alarm

3

AlarmPriority3

Notice

4

AlarmPriority4

Type: Select if you wish to filter the alarm list based on a specific alarm type. Note: By default, all system alarms in VTScada (security, modem, operator logging, and report) have a type of "1000". VTScada programmers may specify their own type values for custom Alarm tags, and can therefore use the Type field to filter them. Custom Alarm tags and applying type filtering is beyond the scope of this guide.

Operator Name: Select if you wish to filter the alarm list based on a specific operator.

Area: Select if you wish this button to filter the alarm list based on a specific Area property. Note: The VTScada alarm system logs security-related events, operator control action-related events, remote configuration-related events, and Alarm Notification System-related events for reporting in the History list on the Alarm page. These entries have the following Areas:

  • Security-related events have a default area of "Security".
  • Operator control action-related events and remote configuration-related events have a default area of "OperatorLog".
  • Alarm Notification System-related events have a default area of "Alarm Dialer".

You can change the field descriptions displayed in the Field column using application properties. See: Application Properties for Alarms.

Alarm Name:

Select to filter based on names. This is useful for viewing the history of a particular alarm, or for limiting the display to alarms matching a name pattern such as PUMP*.

Wildcards are available to expand the selection. The asterisk wildcard (*) matches any number of characters, beginning at the location of the wildcard. The question mark wildcard (?) matches any single character at exactly the location of the wildcard.

Selection:

The Selection column is used to supply a comparison operator and a value to compare the matching field entry to. The following operators are supplied:

Operator

Description

==

Equal To

>

Greater Than

<

Less Than

*?

Wildcard (i.e. you may enter characters combined with either the ? or the * wildcard characters)

!=

Not Equal To

<=

Less Than Or Equal To

>=

Greater Than Or Equal To

!*?

Not Wildcard (i.e. exclude results that match the entered characters combined with either the ? or the * wildcard characters)

Example:

Filter the Alarm List Using the Alarm Filtering Dialog

  1. Click the Filtering check box to enable the Alarm Filtering dialog.

If you set more than one condition in the filter, decide whether the alarms much match all the conditions (e.g. "Priority <=2 AND Area == West") or whether the alarms need match only one of the conditions (e.g. "Priority <= 2 OR Area == West").

  1. If only one of the conditions need be met, select the OR box.
  2. If all the conditions must be met simultaneously, do not select the OR box.
  2. Click the field on which you wish to filter in the Field column.

The corresponding Selection field will become enabled.

  3. Click the operator button until the operator you wish to use appears.
  4. Enter the value on which you wish to filter in the Selection field.
  5. Repeat the previous two steps to configure the next filtering criteria (if necessary).

An example of a completed Alarm Filtering dialog:

  6. Click OK.

The Alarm Filtering dialog will close, and your custom alarm page will reopen, where the Filter Dialog Button object will display a check mark, indicating that the alarm list has filtering applied.

The result of the above configuration is that the associated alarm list will display all alarms whose priority is less than or equal to "2" (i.e. critical and high alarms), and whose area is "East". The following information will assist you in removing filtering criteria from the alarm list.

Remove a filter by clearing it from the Alarm Filtering dialog.


(Legacy) Filter Field Button

Filter a legacy Alarm List by a single, preselected option. Use any alarm property as the basis of the filter.

It is standard practice to create several instances of the Filter Field Button to provide a range of filtering options (including a wildcard to remove all filters).

Filter Field Button tools only allow filtering by one criterion at a time. The Filter Dialog Button tool allows multiple filters, but you cannot preconfigure it.

The Filter Field Button’s properties dialog:

Filtering Rules

You can configure multiple Filter Field Button objects to change the filter on the alarm list according to different criteria. However, you can only add one filter to the alarm list at a time using this method. While the alarm list is being filtered using a Filter Field Button object, the active button stays latched in to indicate the filter that was applied to the alarm list. Clicking a second Filter Field Button object removes the first filter, releases the first button, latches in the second button, and applies the second filter to the alarm list.

Removing Filters

To remove all filters from the alarm list, you should create a single "No Filter" or "Remove Filter" button. A Filter Field Button will remove all filters from the alarm list if configured with a blank Field Value. Only one button is required to remove all filters, regardless of the number of filter buttons you configure.

Name

Required to associate this button with an existing legacy Alarm List.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

Enter the text that you want to display on this button's tool tip (which opens when the mouse pointer is rested on this button). Use this field to compensate for the brevity of the button label by providing a more complete description.

Field Number

Select the alarm database field by which you want to filter.

Area: Filter the alarm list based on a specific Area property.

Note: The VTScada alarm system logs security-related events, operator control action-related events, remote configuration-related events, and Alarm Notification System-related events for reporting in the History list on the Alarm page. These entries have the following Areas:

Security-related events have a default area of "Security".

Operator control action-related events and remote configuration-related events have a default area of "OperatorLog".

Alarm Notification System-related events have a default area of "Alarm Dialer".

Operator: Filter the alarm list based on a specific operator.

Type: Filter the alarm list based on a specific alarm type.

Note: By default, all system alarms in VTScada (security, modem, operator logging, and report) have a type of "1000". VTScada programmers may specify their own type values for custom Alarm tags, and can therefore use the Type field to filter them. Custom Alarm tags and applying type filtering is beyond the scope of this guide.

Priority: Filter the alarm list based on a specific alarm priority.

Message: Filter the alarm list based on a specific Description property.

Note that wildcard characters are not permitted. Enter the full description as it appears in the Alarm tag's Description field. In the event that a Description property has not been configured for an Alarm tag, the message for the alarm will contain the name of the Alarm tag, as it appears in its Name field.

Status: Filter the alarm list based on a specific alarm or event status.

Alarm Status

Index

Active

b1

Unacknowledged

b2

Normal Acknowledged

0

Active Acknowledged

1

Normal Unacknowledged

2

Active Unacknowledged

3

Disabled

4

Field Value

Enter a single, valid criterion by which you wish to filter the alarm list, according to the option you selected in the Field Number drop-down list.

For example: If you select "Priority" in the Field Number drop-down list, you may enter "1" (critical) in the Field Value field. The result is that when this button is clicked, the alarm list will display only those alarms that have a critical priority.


(Legacy) Sort Button

Sort a legacy Alarm List by any numeric property.

Sorting is different from filtering. Sorting does not stop alarms from being displayed in the alarm list. Rather, it changes the order of the items being displayed. Filtering excludes certain entries from being displayed in the alarms list. You can apply both filtering and sorting simultaneously. For example, you may filter to display all alarms that have their Area parameter configured as "East" and sort the results by alarm priority.

To remove sorting, create a second Sort Button with the Field Number set to match the corresponding sort button, and leave the Minimum and Maximum fields blank.

Legacy Alarm List - This button is relevant only in relation to a legacy Alarm List

The properties dialog for the Sort Button dialog.

You cannot sort the History alarm list.

Name

Required to associate this button with a legacy Alarm List.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tips Label

Use this field to compensate for the brevity of the button label by providing a longer description of the button’s function. This text is displayed only when the operator hovers the pointer over the button.

Minimum

Enter the lowest numeric value in the sort range.

The lowest alarm priority is 0 by default.

Maximum

Enter the highest numeric value in the sort range.

The highest alarm priority is "4" by default.

Field Number

Select the name of the alarm database field by which you wish to sort.

Note: this button does a numeric sort - fields with values that are non-numeric are not sorted. Thus, while it is possible to select "Area" it is effective to do so only if areas are numbered rather than named.

Sort Descending

Select if you want to sort the alarm list in descending order (i.e. with the highest priority alarms appearing at the bottom.


Alarm Priority Box

Provides a visible indication when the linked tag is in an active or unacknowledged alarm state, and when it is either shelved or disabled.

This widget is not visible for alarms that are unacknowledged but no longer active unless the property AlarmPriorityIndicatorShowNormalUnacked is set to 1. (Note that "trip" alarms are never in an active state.) The widget is always displayed when the alarm is shelved or disabled.

If you are working in a Master Application and link your Alarm Priority widget to a tag that is created in that Master Application and that also has child tags from a Subordinate Application, be aware that alarms from the subordinate tags will not flow through the local tag to be shown by your widget. Alarm Priority widgets in a Master Application that are linked directly to tags belonging to a Subordinate Application will work as expected.

You can link this widget to a parent tag rather than a specific status tag. When linked to a parent, it will activate when any child tag in the hierarchy is in an active alarm state. The icon will display the highest priority of the set of active alarms.

If the alarm (or set of alarms in child tags) includes a shelved alarm, then the widget will activate and display an S. If the linked tag (or child tags) includes a disabled alarm, the widget will display an X.

If linked to a parent tag, and within the set of child tags there are unacknowledged alarms, active (but acknowledged) alarms, shelved alarms and disabled alarms, then the order of precedence for the display is as follows:

  1. Unacknowledged (icon blinks with the highest priority alarm of the set)
  2. Active (icon shows the highest priority alarm of the set)
  3. Disabled (icon shows an X)
  4. Shelved (icon shows an S)

The color used when shelved or disabled is controlled by the property AlarmPriorityIndicatorColor, defaulting to a pale gray.

This widget is identical to the Alarm Priority Icon, but adds a box that you can place around the image representing the equipment that will trigger the alarm.

The icon is visible only when the linked tag is in an active alarm state. The shape, color, and text shown in the icon are controlled by the configuration of the Alarm Priority Tag used for that alarm.

As with any other widget, operators can right-click to open a pop-up menu for the linked tag, provided that they have sufficient privileges, and that you have not configured the icon to disable the pop-up menu. This menu includes a link to navigate to the Alarm Page. Note that only the icon is a valid target for the right-click. The box portion of this widget will not respond to operator actions. This is done so that the box does not interfere with controls or linked widgets within its area.

The properties dialog for the Alarm Priority Box:

Tag

Link this widget to the tag whose active alarm or control lock state is signaled by the icon.

Style

Linked to the System Style Settings tag by default. This controls only whether the icon should blink while the alarm is unacknowledged. The color of this widget is affected only by the Alarm Priority, not the linked Style Settings tag.

Box Options

Includes options for Line Style, Line Width, Fill Pattern and Fill Opacity. By default, the Alarm Priority Box is a single continuous line. You may select any of VTScada's existing line styles, and any line width up to 30 pixels.

The default box has no fill pattern, but you may add any of VTScada's existing patterns. If using a pattern, and if the box is displayed over other objects on the page, you should decrease the opacity, making it possible for the operator to view both.

Show Icon

Deselect this option to remove the icon, leaving only the box to signal the active alarm state.

Show Icon Label

Select this option to display the text portion of the alarm priority or lock level.

Show Alarm Icon

If selected, the widget will display the Alarm Priority level icon for the associated alarm.

Show Shelved Icon

If selected, the widget will remain visible while the alarm is shelved, notifying operators of that status.

Show Disabled Icon

If selected, the widget will remain visible while the alarm is disabled, notifying operators of that status.

Show Locked Icon

If selected, the widget will show the Lock Level icon for the associated tag, if that tag has a Control Lock applied.

Icon - Position grid

Not available if the icon has been disabled. Click any of the squares to place the icon at that position relative to the box.

Icon - Small / Medium / Large

Not available if the icon has been disabled. Sets the relative size of the icon. This option defaults to medium. Choose a smaller size to avoid overlap with other objects in a crowded page, or a larger size to improve the visibility of the indicator.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Alarm Tools\

High Performance\

Related information:

Alarm Priority Icon

Alarm Priority Tags

Choices for Operator Interaction

AlarmPriorityIndicatorShowNormalUnacked


Alarm Priority Icon

Related Widgets:

Lock Level Icon Widget

Token Level Icon

Provides a visible indication when the linked tag is in an active or unacknowledged alarm state, and when it is either shelved or disabled.

This widget is not visible for alarms that are unacknowledged but no longer active unless the property AlarmPriorityIndicatorShowNormalUnacked is set to 1. (Note that "trip" alarms are never in an active state.) The widget is always displayed when the alarm is shelved or disabled.

If you are working in a Master Application and link your Alarm Priority widget to a tag that is created in that Master Application and that also has child tags from a Subordinate Application, be aware that alarms from the subordinate tags will not flow through the local tag to be shown by your widget. Alarm Priority widgets in a Master Application that are linked directly to tags belonging to a Subordinate Application will work as expected.

You can link this widget to a parent tag rather than a specific status tag. When linked to a parent, it will become activated when any child tag in the hierarchy is in an active alarm state. The icon will display the highest priority of the set of active alarms.

If the alarm (or set of alarms in child tags) includes a shelved alarm, then the widget will activate and display an S. If the linked tag (or child tags) includes a disabled alarm, the widget will display an X.

If linked to a parent tag, and within the set of child tags there are unacknowledged alarms, active (but acknowledged) alarms, shelved alarms and disabled alarms, then the order of precedence for the display is as follows:

  1. Unacknowledged (icon blinks with the highest priority alarm of the set)
  2. Active (icon shows the highest priority alarm of the set)
  3. Disabled (icon shows an X)
  4. Shelved (icon shows an S)

The color used when shelved or disabled is controlled by the property AlarmPriorityIndicatorColor, defaulting to a pale gray.

Place the Alarm Priority Icon on a page, near to whatever image or shape represents the equipment that will trigger the alarm.

The icon is visible only when the linked alarm is in an active state. The shape, color, and text shown in the icon are controlled by the configuration of the Alarm Priority Tag used for that alarm.

As with any other widget, operators can right-click to open a pop-up menu for the linked tag, provided that they have sufficient privileges, and that you have not configured the icon to disable the pop-up menu. This menu includes a link to navigate to the Alarm Page.

The properties dialog for the Alarm Priority Icon:

Tag

Link this widget to the tag whose active alarm or control lock state is signaled by the icon.

Style

Linked to the System Style Settings tag by default. This controls only whether the icon should blink while the alarm is unacknowledged. The color of this widget is affected only by the Alarm Priority, not the linked Style Settings tag.

Show Icon Label

Select this option to display the text portion of the alarm priority.

Show Alarm Icon

If selected, the widget will display the Alarm Priority level icon for the associated alarm.

Show Shelved Icon

If selected, the widget will remain visible while the alarm is shelved, notifying operators of that status.

Show Disabled Icon

If selected, the widget will remain visible while the alarm is disabled, notifying operators of that status.

Show Locked Icon

If selected, the widget will show the Lock Level icon for the associated tag, if that tag has a Control Lock applied.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Alarm Tools\

High Performance\

Related information:

Alarm Priority Box

Alarm Priority Tags

Choices for Operator Interaction

AlarmPriorityIndicatorShowNormalUnacked


Analog Bar & Indicator Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations tag (although portions may be used by any analog numeric tag).

The Analog Bar and Indicator provides a wealth of current and historical data to the operator at a glance. You have a wide range of configuration options. Note that colors used within the bar are controlled by the attached Style Settings tag.

Click to expand
Vertical, left configuration of the Analog Bar and Indicator widget

Related Information:

Style Settings Properties: High Performance tab

Notes:

  • If an I/O tag has both a high alarm and a high high alarm (or low and low low) a faint line is shown at the boundary between their setpoints.
  • All active alarms are shown.
  • The history bar (dark blue in the image shown) is visible only when the Value Range is greater than zero.
  • The trend arrow (blue upwards arrow in the image) is visible only when the Trend Direction time is greater than zero.
  • The expected range is shown only for I/O and Calculation tags that have been configured with these values. (see: I/O and Calculations tag: Scaling tab)

By definition, an expected range should not overlap an alarm setpoint. If you do configure an overlap, do not expect both to show in any widget.

Configuration options for the Analog Bar and Indicator widget

All properties other than the corner radius and the disable options may be configured using numeric values, selected tags, parameters or expressions.

Recent Data Indicators

Value Range (minutes)

Sets the time span from which the minimum and maximum values are obtained, to be represented by the dark blue range bar.

Limited to a range between 0 to 525600 (1 year in minutes).

Trend Direction (minutes)

The current value of the linked tag is compared to the value at the start of the time span set with this property. If the current value is greater, the arrow indicates an increasing trend, otherwise a decreasing trend.

Limited to a range between 0 to 525600 (1 year in minutes).

Display Options

Reference Value

A numeric value that represents the target setpoint of the tag whose history is being displayed by this widget. For example, if the bar and indicator widget represents a motor's speed, the reference value would be the output tag controlling that motor's speed.

This indicator is used only for display purposes. It is not an operator control. Limited to the linked tag's minimum and maximum values.

Horizontal

Controls whether the bar is drawn vertically or horizontally

Indicator on Right / Indicator on Bottom

For vertical bars, controls whether the indicator is drawn on the left or right. For horizontal bars, controls whether the indicator is drawn on the top or the bottom.

Reverse Direction

Flips the widget to its mirror image. If vertical, values would increase towards the bottom of the page. If horizontal, values would increase towards the left of the page.

Draw Drop Shadow

Adds a shadow effect to the bar.

Corner Radius

Use to soften the corners of the bar.

Colors

Style

Refers to the selected Style Settings tag. If you have not selected otherwise, the default System Style Settings tag is used.

All other colors

These default to the configuration of the Style Settings tag, but may be overridden for a specific Bar and Indicator widget.

Widget Folders:

Widgets\High Performance\

Related information:

Style Settings Tags

Choices for Operator Interaction


Analog Clock

Not linked to any tag

* Does not use the Style Settings tag.

The Analog Clock widget is a dynamic image, displaying the current time.

The properties dialog for an Analog Clock:

The only configurable property for the clock is the selection of time zone.

Widget Folders:

Basic Components\Clock\

Tools\Standard Library\


Animated Image Widget

Used by: I/O and Calculations, Alarm tag, Alarm Status tag, Analog Control tag, Analog Input tag, Analog Output tag, Analog Status tag, Calculation tag, Comm Link Sequencer tag, Counter tag, Deadband Control tag, Digital Control tag, Digital Input tag, Digital Output tag, Digital Status tag, Function tag, History Statistics tag, Modem tag, Network Status tag, Pump Status tag, Rate of Change tag, Script tag, Selector Switch tag, SMS Appliance tag, SQL Logger tag, Totalizer tag, Trigger tag.

* Does not use the Style Settings tag.

The Animated Image widget is used to display a short movie that runs while the tag’s value is non-zero. When used for tags that have analog values, the speed of the animation reflects the value of the tag. For tags with simple on or off values (digitals) the animation either runs or not. In all cases, you can set the maximum speed of the animation in frames per second when configuring the widget.

A configured Animated Image (shown in multiple frames).

Notes:

* Modern High-Performance HMI user interfaces generally do not include animated images. Before using, ask whether this widget will improve the operator interface or if the goal is merely aesthetics.

* Animated Images do not use animated GIF files or other single-file animations.

* For those doing development over a VIC thin client, note that it is not possible to select alternate images for your animation in this environment.

* You should NOT use the Animated Image or the Color Blink widgets on pages that will be accessed via a VTScada Thin Client Server, due to possible latency and bandwidth issues. If you must use Animated Image widgets, please ensure that you set the frames per second rate low.

The Animated Image properties dialog will look like the following:

Tag

The Tag field displays the name and description of the tag that is linked to this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Select Images

Opens the Browse for Folder dialog, which you can use to select any folder containing a custom animation. The folder must be within your application's folder structure. Use this option to select a custom animation, not to a different VTScada animation to another.

The folder and its files must have previously been imported into your application. Refer to the topic, Adding Custom Animations.

Old Color (1 and 2)

Used in conjunction with the New Color button. Select a color that will be replaced with another in the image. You may replace up to 2 colors.

For example, several of the provided animations have been created with active orange (RGB 255, 160, 0) so that they may be overlaid with a Color Change widget to dynamically adjust their color. You might wish instead to use blue for the image. To do this, select 255, 260, 0 (Active Orange) as the old color and blue as the new.

The tool used to choose a color is the Select Color Dialog.

New Color (1 and 2)

Used in combination with the Old Color button. Select a new color to replace another in the image. You may replace up to 2 colors.

FPS at Minimum and at Maximum

Use these fields to set the minimum and maximum animation speeds relative to the associated tag’s scaled minimum and maximum values. The animation speed is measured in frames per second (FPS). The values you set here must be within the range of 0 to 30, but there is a way to override these by applying your own minimum and maximum scaling

The default minimum value is 0, indicating that the animation should be stopped when the value of the associated tag is at its minimum. The default maximum is 15, which generally provides an acceptable animation without excessively taxing either your computer’s CPU or display card.

Reverse Direction of Animation

Select this option to run the animation from the last frame to the first frame, rather than from the first frame to the last frame, thereby reversing the apparent direction.

When Paused Show

Select which frame you wish the Animated Image object to show when it is paused. This can be one of:

  • Current Frame: The frame of the animation that last played will be displayed when the animation is paused.
  • First Frame: The first frame of the animation will be displayed when the animation is paused.
  • No Image: No image will be displayed when the animation is paused.

Use Tag's Scaled Min and Max Values

Selected by default. Indicates that the tag’s minimum and maximum scaled process values should be used. If you deselect this box, then you may enter your own scaling values for the tag by using the Minimum Value and Maximum Value fields (see following). These values will only apply to this one animation of the tag.

The net effect of scaling, and therefore the speed at which the animation will run, will depend on the relationship between the tag’s scaling values and those that you set here.

For example, given the following:

  • A tag with scaled values from 0 to 100.
  • A FPS rate at minimum of 0.
  • A FPS rate at maximum of 30.

Setting your own Minimum and Maximum scale values will change the FPS rates as follows:

  • Minimum set to 0 and Maximum set to 50: FPS at minimum is 0 and at maximum is 60.
  • Minimum set to 0 and Maximum set to 200: FPS at minimum is 0 and at maximum is 15.
  • Minimum set to -100 and Maximum set to 100: FPS at minimum is 15 and at maximum is 30.
  • Minimum set to 50 and Maximum set to 100: FPS at minimum is -15 and at maximum is 30.

Minimum Value and Maximum Value

These two fields are enabled only when the Use Tag’s Scaled Min and Max Values check box is not selected. See Use Tag’s Scaled Min and Max Values for a full explanation of the effect of these values.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Animations\

Related information:

Choices for Operator Interaction

Color Blink Widget

Adding Custom Animations


Adding Custom Animations

Animated graphics are an ordered series of individual graphic images, each of which differs from the last by a small amount. When viewed in rapid succession, the visual effect of the differences will appear as motion to the human eye.

For those doing development over a VIC thin client, note that it is not possible to select alternate images for your animation in this environment.

The image and the folder in which they are stored must share a name. You must save each image with a consecutive suffix such as a, b, c, or 1, 2, 3... For example:

You should also create one image to represent the animation. Name this "_template". Images may use any of the formats recognized by VTScada.

Create the images folder within your application folder. Import the images into your application.

  • If the folder exists elsewhere on your workstation, use the Select Images button in the Animated Image widget properties dialog. This will copy the folder to your application and import the images in one step.
  • If you place the folder under your [ApplicationName]\Bitmaps\Animations folder, use the Import File Changes button in the VAM to let your application know that the files exist.

You might also want to create a new palette entry for your custom animation. This is not necessary, but it is convenient.

Use a custom animation

  1. Create a folder filled with the images that will combine to make the animation.
    See notes elsewhere in this topic on Image File Details.
  2. If that folder is located in your [Application Name]\Bitmaps\Animations folder, use the Import File Changes button in the VAM. Otherwise proceed.
  3. In the Idea Studio, drag any animation to a page and link it to one of your tags.
    Widgets folder >> Basic Components >> Images >> Animations.
  4. Open the properties dialog for the widget and click the Select Images button.
  5. Browse to the folder containing the images.
    If the folder is not part of your application, the following prompt appears. Click OK.

Create a palette shortcut for your animation.

Assuming that you have already imported the images in your custom animation folder...

  1. In the Idea Studio, ensure that the Widgets palette is open and browse to the folder, Basic Components >> Images >> Animations.
  2. Copy and paste any one of the existing menu entries.
  3. Open the properties of the copied menu entry.
  4. Change the title to match your animation.
  5. Click the Set Parameters button to open the Animated Image dialog.
  6. Select the folder in which your animations are stored.
  7. Adjust other properties as preferred.
  8. Save the menu entry.

Image File Details:

There are two parts to a VTScada animated image:

  • The directory it is stored in.
  • The file names used by the still images.

All should share a common root file name. Use any of the file formats recognized by VTScada.

Your VTScada application will not use new files and folders until they have been imported by someone who has the Edit Files privilege.

For example, if you were creating an animation named "Bounce" you would first create a sub-folder of the application's Bitmaps\ANIMATIONS folder with that name.

C:\VTScada\YourApp\Bitmaps\ANIMATIONS\Bounce

Always store custom images within your application directory structure, or the OEM folder on which your application is based.

The still frames of the animation are a series of image files that you save to the Bounce folder.

The color black (#000000) is treated as transparent in VTScada. Do not use pure black in your animation's images for any visible area.

The images are ordered by adding a sequence character (A, B, C …) after each file name. For example:

C:\VTScada\YourApp\Bitmaps\ANIMATIONS\Bounce\BounceA.png

C:\VTScada\YourApp\Bitmaps\ANIMATIONS\Bounce\BounceB.png

C:\VTScada\YourApp\Bitmaps\ANIMATIONS\Bounce\BounceC.png

Copy the first image, renaming it to _Thumbnail

C:\VTScada\YourApp\Bitmaps\ANIMATIONS\Bounce\_Thumbnail.png

The sequence character can be a letter or number. File names are not case sensitive.

Use a minimum of three still frames to create an effective animation. The longest animation that comes with VTScada has 18 frames. Most have four to six.

Related information:

Import File Changes Page


Antique Bolted Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Antique Bolted widget represents the associated tag's value as a photorealistic meter

The properties dialog for the Antique Bolted widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Options

Set the number of major divisions and minor divisions within each major division. Defaults to 10 and 5.

Choose whether to include the text used for engineering units within the gauge. Defaults to show units.

Colorization

Use the color selector dialogs to set the color of the needle, text and gauge background. This widget does not use the Style Settings tag.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Antique Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Antique Gauge widget represents the associated tag's value as a photorealistic meter. The divisions used to display the scale range are pre-set for this meter. The engineering units of the linked tag are displayed below the scale.

The properties dialog for the Antique Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Aqua Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Aqua Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

The properties dialog for the Aqua Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Arc Meter Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

The Arc widget represents the associated tag's value as portion of an arc. The darker portion of the arc starts at the angle you specify, where vertical (North) is zero degrees. Increasing values are indicated by the darker portion sweeping in a clockwise direction. The colors are set by the LED (analog) values of a selected Style Settings tag, and values above the linked tag's alarm setpoint can be indicated.

Four variations on a theme, showing the control you have over arc configuration.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

The properties dialog for the Arc widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Minimum Angle & Maximum Angle

Sets the starting point and the ending point for the sweep of the arc. Defaults to 270 degrees for the start angle and 90 degrees for the end angle. The angle is measured in degrees, and increases in the clockwise direction.

Example (b) shows an arc with minimum angle zero and maximum angle of 180 degrees.

Lines

Use to adjust the width of the unlit (background) and lit (foreground) portion of the arc.

Example (c) shows an arc with an unlit width of 18 pixels and a lit width of 8 pixels. The alignment is Center. Alignment applies only when the lit and unlit widths are of differing values, giving you the option of aligning the lit portion against the outside edge, inside edge, or centered within the unlit portion.

Show Alarms

If selected, the arc will indicate when the associated tag is in an active alarm state by using the alarm indication settings as configured in the associated Style Settings tag. Only that portion of the sweep above or below the alarm setpoint will use the alarm indication.

This option is in use for all four of the example images.

Counter Clockwise

If selected, sections of the arc will sweep (increase) in a counter-clockwise direction rather than the standard clockwise.

Show Center Circle & Spacing

These two properties should be used together. The center circle will be displayed using the unlit color of the arc. The spacing controls the size of the circle by setting the number of pixels from the unlit ring of the arc to the perimeter of the circle.

Example (c) shows a center circle in addition to showing lines with varying widths.

Show Value

If selected, the arc will display the current value of the linked tag. Units are not shown.The color will always match that of the lit portion of the arc.If a center circle is shown, then the value will be superimposed on the circle.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Army Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Army Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

The properties dialog for the Army Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Audio Meter Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Audio widget represents the associated tag's value as photorealistic meter.

The properties dialog for the Audio widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Options

Set the number of major divisions and minor divisions within each major division. Defaults to 10 and 5.

Choose whether to include the text used for engineering units within the gauge. Defaults to show units.

Colorization

Use the color selector dialogs to set the color of the needle, text and gauge background. This widget does not use the Style Settings tag.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Backlit Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Backlit Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

The properties dialog for the Backlit Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Bottom Bar Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Deadband Control, Function, History Statistics, Script, Selector Switch, SQL Logger.

* Does not use the Style Settings tag.

The Bottom Bar widget is used to display a tag's value as a vertical bar, the length of which increases from the top towards the bottom as the tag’s value increases. When the tag’s value is at a minimum, the bar will be shown as a thin line at the top of its range. When the tag’s value reaches its maximum, the widget will be displayed as a rectangle, filling the range.

The properties dialog for the Bottom Bar widget will look similar to the following:

Set Color

Opens the Select Color Dialog from which you can select a color for this object.

Low Scale Range and High Scale Range

In most cases, these fields will be display-only, showing the Scaled Process Data Min and Scaled Process Data Max values configured for the associated tag.
These fields become editable when the widget is used to display a function or Calculation tag. The most common use is to provide an output range of 0 to 100 (%) given a data source whose numbers do not match these values (perhaps ranging from 20 to 80, for example). Set the low scale range to the value expected from the data source when it is at its minimum and the high scale range to the value expected from the data source when it is at its maximum.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Basic Components\Bars\

Related information:

Choices for Operator Interaction


Bristol Widgets

Widgets used with Bristol BSAP/IBP Drivers and Bristol Network tags.


Bristol History Info Widget

Used by: Bristol BSAP/IBP Driver.

* Does not use the Style Settings tag.

This widget creates a button that operators can use to view history about the linked Bristol BSAP/IBP driver.

Configuration properties for the Bristol History Info widget.

Button Label

If you have several Bristol drivers, you may want to identify the button for each.

Uses Server's Time Zone

Provides a choice to display "Local" time in the time zone of the server or of the client (for thin clients in different time zones). Defaults to showing the time zone of the server.

Widget Folders:

Tag Types\Alphabetical List of All\Bristol BSAP/IBP Driver


Poll Control Widget (Bristol driver)

Used by: Bristol BSAP/IBP Driver.

* Does not use the Style Settings tag.

This widget creates a set of buttons that operators can use to control the polling. While in normal polling mode the only option is to pause.

After pausing the driver, operators may either resume, or request a single (one-shot) poll.

There are no configurable options in the Bristol Poll Control widget other than the standard options for operator-interaction..

Widget Folders:

Tag Types\Alphabetical List of All\Bristol BSAP/IBP Driver


Poll Status Widget (Bristol driver)

Used by: Bristol BSAP/IBP Driver.

* Does not use the Style Settings tag.

This widget creates a display showing the current polling status of the linked Bristol BSAP/IBP driver.

Configuration properties for the Bristol Poll Status widget.

There are no configuration options for the Poll Status widget other than the standard options for operator-interaction.


Purge Alarms Widget (Bristol driver)

Used by: Bristol BSAP/IBP Driver.

* Does not use the Style Settings tag.

This widget creates a button that operators can use to purge alarms from the linked Bristol BSAP/IBP driver.

Configuration properties for the Bristol Purge Alarms widget.

Configurable options are limited to changing the label. If you have several Bristol drivers, you may want to identify the button for each.

Widget Folders:

Tag Types\Alphabetical List of All\Bristol BSAP/IBP Driver


Send NRT and Time Widget (Bristol)

Used by: Bristol BSAP/IBP Driver.

* Does not use the Style Settings tag.

This widget creates a button that operators can use to refresh the NRT and time in the linked Bristol BSAP/IBP driver.

Configuration properties for the Bristol Send NRT and Time widget.

Configurable options are limited to changing the label. If you have several Bristol drivers, you may want to identify the button for each.

Widget Folders:

Tag Types\Alphabetical List of All\Bristol BSAP/IBP Driver


50077 Read RTU Signals

A choice when importing Bristol tags from the device. This button forces the driver to read all of the signal configuration information from the device. After being read, it can be used as part of the tag import or on the individual I/O tag configuration dialog in the address assist.


Bristol Import Options

This sets the update rate on any I/O tags that the import creates. By default they'll all be set to 1 second.

If the Enable Output option is selected, all imported I/O tags will have their write addresses configured in addition to their read addresses. This may be needed in some circumstances and saves the user from having to enter the write addresses manually.


Call Manager Status Widget

Not linked to any tag. * Does not use the Style Settings tag.

The Call Manager Status widget presents a picture of the current state of voice calls, displaying call attempt, failure, and incoming call counts. This may only an approximate picture because it can be affected by whether servership has changed, network issues, etc.

There are no user-configurable options for this widget.

Assuming that you have multiple servers, you can install multiple VOIP and Twilio configurations (one each per server in the application), as well as voice modems. (Voice modems as a whole are considered a single voice call method, and are listed as such in the new Call Manager Status widget.)

Each method has a unique name, which is the particular mode (VoiceModem, VOIP, or Twilio) concatenated with an underscore, and the name of the workstation it exists on.

The status field of the Call Manager Status widget will vary depending on whether the method is VOIP, Twilio, or voice modems.

The working field will display "Configured" if a call manager has been configured in the application but has not made an attempt yet. After an attempt has been made, the working field will display "Yes" or "No".

Widget Folders:

Tools\System Status Tools

Analytics\Diagnostics


Camera Viewer Widget

Used by: Camera tag

* Does not use the Style Settings tag.

The Camera Viewer widget is used to display the live feed from the camera specified in the linked Camera Tag.

Within the Idea Studio, this widget shows only as a placeholder, never as a live image. In the operator view, it will display the feed from the attached camera if available. If the image feed is not available, then a gray rectangle is shown instead.

To use this tool on either a thick client (workstation) or the VIC, the workstation requires the optional WebView2 component, which is built on the Edge browser from Microsoft. (The Anywhere Client does not require WebView2 to be installed.)
If WebView2 is not installed, it can be obtained by running the VTScada or VIC installer and selecting the option to install WebView2. Alternatively it can be downloaded from Microsoft, via the Evergreen Bootstrapper Installer or via the Evergreen Standalone Installer for machines with restricted access to the Internet.

Other than a link to the selected Camera tag, there are no user-configurable options within this widget.

Widget Folders:

Tools\Standard Library\Camera


Campbell PakBus Driver Info Widget

* Does not use the Style Settings tag.

Used by: Campbell Scientific PakBus Driver tag.

The driver needs to read in a set of Table Definitions from the logger before it can read records. This dialog shows operators what definitions have been read. Select a table from the droplist to display a list of the fields.

The "Copy Address to Clipboard" button becomes active only after the operator selects a field name. Pressing that button copies the address for that table and field to the clipboard to be pasted into an I/O tag's address field.

"Force Read All Data" deletes the last value read from the logger, and starts reading from the beginning. Note that this might take a long time to reload if the logger has a large amount of history.

The "Force Re-Load Table Definitions" button will delete the tag's stored table definitions, forcing it to ask for the table definitions on its next poll of the logger. Note: This will also cause the tag to re-read the logger's data from the beginning of the logger's history.

The properties dialog for the PakBus Driver Info widget. The only user-configurable setting is the label to display on the button. Defaults to "Table info..." if not set.

Widget Folders:

Tag Types\I/O Devices (Drivers)\PLCs and RTUs\Campbell Scientific PakBus Driver\PakBus Driver Info

Related information:

Choices for Operator Interaction


Checkbox Switch Widget

Used by: Selector Switch.

* Does not use the Style Settings tag.

The Checkbox Switch widget is used to create an On/Off control for a two-position SelectorSwitch tag. Each time an operator clicks on the box or attached label, the switch will toggle between positions and a check mark will be displayed for position 1.

This is a control-type widget that is only available for selector switches - it is not available for use as an indicator with Digital Input or Digital Status tags.

When displaying more than one check box on a page, each one must be given a unique value for its Focus ID.

The properties dialog for the check box is as shown:

This widget has a wide range of settings for its appearance and behaviour.

Display

Title

Provide a descriptive label for the check box. May be left blank.

Box on Left

Select whether the box is to go to the right or the left of the label. The label itself will change justification to match the box (left-justified when the check box is on the left and right-justified when the box is on the right).

Invalid Color

Sets the color that will be displayed when the attached Selector Switch tag is in an Invalid state. May indicate either an error in communication or a Selector Switch with no feedback that has not yet been set to any position.

Mismatch Color

Sets the color that will be displayed when the Selector Switch's position feedback indicates that the equipment is in a state other than the one most recently set using this widget.

Not Checked Text / Checked Text

Text to label position 0 (typically "Off") and position 1 (typically "On").

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Forms

Include in Form

Select if this widget is to be included in a data entry form. If selected, this widget will interact with the submit, clear and date time selector widgets.

Time Offset

A numeric value that specifies the quantity of time offset. A time offset is added to a date selector offset. A 15 minute offset applied to an 11:00 AM submission will be recorded as 11:15 AM.

Time Units

A droplist that specifies the unit of time offset in minutes, hours, days or weeks.

Related information:

Numeric Value Widget

String Entry Widget

Droplist Widget

Date Time Selector

Submit Button Widget

Checkbox Switch Widget

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Tools\Forms\


Classic Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Classic Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

The properties dialog for the Classic Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Clear Button Widget

Used by: Data Entry Forms

The clear button is used with other form-related widgets. When clicked, it clears all values filled in the data entry widgets with "Include in Form" enabled on the same page. For all intents and purposes, this blank value is essentially 'Invalid'.

The properties dialog for the Clear Button widget:

Font

The font used to display the label. Defaults to the current system font.

Label

Text to display on the button. Defaults to "Clear".

Confirmation Dialog

If selected, the operator must confirm the action before all values are cleared.

Related information:

Checkbox Switch Widget

Numeric Value Widget

String Entry Widget

Droplist Widget

Date Time Selector

Submit Button Widget

Form Reset Button Widget

Widget Folders:

Tools\Forms\


Cockpit Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Cockpit Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

The properties dialog for the Cockpit Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Color Blink Widget

Used by: I/O and Calculations, Alarm, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Counter, Deadband Control, Digital Control, Digital Input, Digital Output, Digital Status, Network Status, Pump Status, Rate of Change, Selector Switch, Totalizer, SQL Logger, Totalizer, Trigger, .

* Does not use the Style Settings tag.

"2 state" versus "4 state". Not all tags will have all the states shown in these examples. Alarms have only state 0 and state 1 and therefore must use the "2 state" version of this widget.
Digitals might only use two states, but they can have four and therefore must use the "4 state" version of the widget.

The Color Blink tag widget is used to create a color box that blinks to indicate the state of the underlying tag. Blinking is an extremely eye-catching visual feature and should only be used in situations where it is of utmost importance for an operator to notice the state of a tag. Do not use this widget casually.

You can configure two colors for each state: the status color, and the blink color. The widget will alternate between these colors according to the On Time and Off Time configured for each state.

If one of the colors is left unconfigured, or set to transparent, the object will seem to appear and disappear. If the colors are identical, nobody will notice the blinking. In general, it is best to use either a light and dark shade of the same hue, or to leave one of the colors transparent or unconfigured.

If a page is intended to be viewed on a VTScada Thin Client, it is recommended that Color Blink objects and Animated Bitmap objects not be used. This is due to possible latency and bandwidth issues. If you must use Color Blink objects, please ensure that you set slow blink rates.

An example of a configured properties dialog for a Color Blink.

The color blink widget is used most effectively with digital tags, or tags that have binary states such as alarms. If used with an analog tag, the tag’s value will be rounded to obtain the closest value of 0, 1, 2 or 3 (repeating).

State x Color

Opens the Select Color Dialog from which you can choose a color to display when the tag’s value is in the corresponding state.

Blink

This check box must be selected if you wish the completed Color Blink object to alternate (blink) between the State X Color and the corresponding Blink Color.

Blink Color

Opens the Select Color Dialog from which you can choose a blink color to display when the tag’s value is in the corresponding state.

On Time

Sets the amount of time (in seconds or fractions of a second) that the Blink Color should be displayed.

Off Time

Sets the amount of time (in seconds or fractions of a second) that the State X Color should be displayed.

Alarm Color

Opens the Select Color Dialog from which you can choose a blink color to display when the tag’s value is in an alarm state.

Replace Color

Opens the Select Color Dialog from which you can select the background color upon which the completed object will be placed. This object will only be visible when placed over the selected color.

Use Color Replace

Select to indicate that you wish to use the configured Replace Color (see above). If the Use Color Replace check box is not selected, then the object will always be visible over any background color.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Color Indications\

Related information:

Choices for Operator Interaction

Animated Image Widget


Color Box Widget

Used by: I/O and Calculations, Alarm, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Counter, Deadband Control, Digital Control, Digital Input, Digital Output, Digital Status, Function, History Statistics, Modem, Network Status, Pump Status, Rate of Change, Roster, Selector Switch, SMS Appliance, SQL Logger, Totalizer, Trigger.

* Does not use the Style Settings tag.

"2 state" versus "4 state". Not all tags will have all the states shown in these examples. Alarms have only state 0 and state 1 and therefore must use the "2 state" version of this widget.
Digitals might only use two states, but they can have four and therefore must use the "4 state" version of the widget.

The Color Box widget is used to represent the associated tag as a box that changes color based on the tag's value. It is primarily used with that have discrete states such as digitals and alarms, but may also be used with analogs. For an analog tag, the value will be rounded to find the closest match to one of the states.

The properties dialog for a Color Box:

State X Color

Opens the Select Color Dialog from which you can choose a color to display when the tag’s value is in the corresponding state.

Invalid Color

Opens the Select Color Dialog from which you can choose a color to display when the tag’s value is invalid.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Color Indications\

Related information:

Choices for Operator Interaction


Color Fill Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Counter, Deadband Control, Function, Rate of Change, Script, Selector Switch, Totalizer, SQL Logger.

* Does not use the Style Settings tag.

The Color Fill tag widget is used to draw a tag as an animated bar (Bar Color) that graphically illustrates the value of the associated tag against a background color (Unfilled Color).

If the Changed Color is set, the object must be placed over a region of that color to be visible.

An example of the Color Fill properties dialog. There must be a Filled Color, but you are free to leave the Changed Color and Unfilled color properties unselected.

Changed Color

If set, the object will only be visible when placed above an area of this color. The button opens the Select Color Dialog from which you can choose a color. Click the X button to remove the color if you change your mind.

Unfilled Color

Opens the Select Color Dialog from which you can choose a color to display as the background for the bar color.

Bar Color

Opens the Select Color Dialog from which you can choose a color to that will represent the tag’s value.

Use Tag's Scaled Min & Max Values

In most cases, it is best to select this option. When the tag is at its minimum scaled output value, the bar will not be visible and when the tag is at its maximum scaled output value, the bar will fill the area of the widget.
Choosing not to use the tag’s scaled min and max values enables the Minimum Value and Maximum Value controls which you can use to scale the bar length relative to the tag’s output scaled values. The scaling you set will apply only to this one instance of the tag widget. This option is normally used when the object represents tags such as Calculation and Function that do not have their own scaled values.
Unlike widgets such as the Top Bar, the bar for the color fill will be visible only within the area originally drawn for this object, regardless of the scaling you define.

Minimum Value and Maximum Value

The Minimum Value and Maximum Value fields are used to scale the color fill bar relative to the tag’s scaled output values. For example, given a tag with scaled output ranging from 0 to 100:
Setting the widget’s scale range from 0 to 200 results in a bar that reaches only half the length drawn when the tag is at its maximum value.
Setting the widget’s scale range from 0 to 50 results in a bar that reaches its full length when the tag is still only half way to its maximum value.
Unlike widgets such as the Top Bar, the bar for the color fill will be visible only within the area originally drawn for this object, regardless of the scaling you define.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Bars\

Basic Components\Color Indicators\

Related information:

Choices for Operator Interaction

Two Color Bar Widget


Color Line Widget

Used by: I/O and Calculations, Alarm, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Alarm, Calculation, Counter, Digital Control, Digital Input, Digital Output, Digital Status, Function, History Statistics, Pump Status, Rate of Change, Selector Switch, Serial Port, SQL Logger, Totalizer, Trigger, UDP/IP Port.

* Does not use the Style Settings tag.

The Color Line tag widget is used to draw a line that changes any combination of color, width and style to indicate the state of the associated tag. Can be linked to most numerics, but meant primarily for digitals.

The properties dialog for the Color Line:

State X Pen and Invalid Pen

Opens the Select Pen dialog. From this dialog, you can select the color, line style and width that the Color Line object will use to show each state of the underlying tag.

Pen Orientation

Use the Pen Orientation drop-down list to select one of four orientations for the completed Color Line object (horizontal, vertical, left 45 degrees, or right 45 degrees). The orientation remains the same for all tag states.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Indicators\Basic Indicators\

Basic Components\Color Indications\

Related information:

Choices for Operator Interaction


Comm Indicator Widget

Used by: Data Flow RTU, Polling Driver, Allen Bradley Driver, CIP Driver, CalAmp Diagnostic Driver, DDE Client, DNP 3.0 Driver, Driver Multiplexer, MDS Diagnostic Driver, Modbus Compatible Device , Omron Host Link Driver, OPC Classic Client Driver, Siemens S7 Driver, TCP/IP Port, Workstation Driver.

* Does not use the Style Settings tag.

The Comm Indicator tag widget is used to draw an indicator square, the color of which indicates the current status of the associated I/O device.

The properties dialog for the Comm Indicator:

Normal Color

The color to display when the associated I/O device is operating under normal conditions

Error Color

The color to display when the I/O device is in an error state.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Note: when used with the Data Flow RTU driver, the context menu for this widget will have an extra option: "Active".

Data Flow RTU drivers have their own polling feature which can activated or not through their configuration panel. Operators who do not have configuration privileges, but do have either "tag modify" or " manual data" security privileges can toggle the active polling state on or off by right-clicking on this widget and selecting the Active status.

Widget Folders:

Analytics\Communications\Connection Status\

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


Comm Line Widget

Used by: Serial Port, TCP/IP Port, UDP/IP Port.

* Does not use the Style Settings tag.

The Comm Line tag widget is used to draw a line that changes any combination of color, width and style to indicate the state of the associated tag. Used for port tags rather than digitals.

The properties dialog for the Comm Line is as shown:

Color

Opens the Select Pen dialog. From this dialog, you can select the color, line style and width that the Comm Line object will use to show each state of the underlying tag.

Pen Orientation

Use the Pen Orientation drop-down list to select one of four orientations for the completed Comm Line object (horizontal, vertical, left 45 degrees, or right 45 degrees). The orientation remains the same for all tag states.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Connection Status\

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


Comm Messages Button Widget

* Does not use the Style Settings tag.

The Comm Messages Button tag widget is used to draw a button that can be clicked to display communications data (transmit and receive communication message strings) for an associated communication driver tag.

Buttons:

Hold Data The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

The properties dialog for this widget appears as follows:

Button Label

Provide the text (if any) that will be displayed on the button.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Connection Status\

Analytics\Diagnostics\

Related information:

Each driver has its own version of the communication messages dialog, as described in the following topics.

ABB Totalflow Driver

Allen-Bradley Communication Messages Dialog

BACnet Driver

Bristol BSAP/IBP Driver

Bristol Network Tag

CalAmp Diagnostic Driver Communication Messages Dialog

Campbell Scientific Array Driver Communication Messages Dialog

Campbell Scientific PakBus Driver Communication Messages Dialog

Data Flow Communication Messages Dialog

Delta Driver

DNP3 Driver Communication Messages Dialog

Driver Multiplexer

Enron Modbus Driver Communication Messages Dialog

Fisher ROC Driver Communication Messages Dialog

GE Series 90 Driver

IEC 60870-5-104 Driver

MDS Diagnostic Driver Communication Messages Dialog

Mitsubishi Driver

Modbus Compatible Communication Messages Dialog

MQTT Client Driver

NMEA 0183 Communication Messages Dialog

Omron Communication Messages Dialog

Omron FINS Driver

Opto 22 Mux Driver

Polling Driver Messages Dialog

Siemens S7 Communication Messages Dialog

SNMP Communication Messages Dialog

Tesco Driver

TI505 Device Driver

Veeder Root Driver


ABB Totalflow Communication Messages Dialog

This Communication Messages Dialog will be drawn for the ABB Totalflow driver but will not show any data because all communications are done by the COM server, which follows a closed, proprietary protocol

Related information:

ABB Totalflow Driver


Allen-Bradley Communication Messages Dialog

The Comm Messages button will display the following information about an Allen-Bradley driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the Allen-Bradley device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the device for data (sending a read request), but the device is not responding. In this case it is wise to check the properties of the Allen-Bradley driver tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

Allen-Bradley Driver

Allen-Bradley Statistics Dialog


BACnet Communication Messages Dialog

The Comm Messages button will display the following information about a BACnet driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the BACnet device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the linked tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

BACnet Driver


CalAmp Diagnostic Driver Communication Messages Dialog

The Comm Messages button will display the following information about a CalAmp diagnostic driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for the CalAmp hardware, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the CalAmp diagnostic driver tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

CalAmp Diagnostic Driver


Campbell Scientific Array Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Campbell Scientific Array driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Campbell Scientific Array Driver


Campbell Scientific PakBus Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Campbell Scientific PakBus driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Campbell Scientific PakBus Driver


Data Flow Communication Messages Dialog

The Comm Messages button will display the following information about a Data Flow RTU driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for the Data Flow RTU, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal so long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the RTU for data (sending a read request) but the RTU is not responding (as can be seen in the example shown above). In this case it is wise to check the properties of the Data Flow RTU driver tag to make sure all settings are correct.

Related information:

Data Flow RTU Driver

Data Flow Statistics Dialog


Delta Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Delta Driver tag.

  • Displays the full driver name and version.
  • Data may be displayed in any of the 4 types shown.
  • Number Transmitted and Received provides a running count of messages in each direction.
  • Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.
  • The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.
  • If one has the protocol information for the device, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.
  • If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the Delta Driver tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

Delta Driver Statistics Dialog

Delta Driver


DNP3 Driver Communication Messages Dialog

The Comm Messages button will display the following information about a DNP3 diagnostic driver tag.

Log Data (Unique to the DNP3 driver.) Data will be logged to a text file in the application's Data\TraceFiles folder while the LogData button is pressed.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

Data will be logged to a text file in the application's Data\TraceFiles folder while the LogData button is pressed.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

If one has the protocol information for the DNP3 hardware, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the DNP3 driver tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

DNP3 Driver

DNP3 Driver Statistics Dialog


Enron Modbus Driver Communication Messages Dialog

The Comm Messages button will display the following information about an Enron Modbus driver tag in response to a left-click. Note that a right-click on the Show Comm button will open a menu, from which you can view associated alarms or a trend window.

Displays the full driver name and version.

Data may be displayed in any of Decimal, Octal, Hex, or ASCII.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Enron Modbus Driver


Fisher ROC Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Fisher ROC driver tag in response to a left-click. Note that a right-click on the Show Comm button will open a menu, from which you can view associated alarms or a trend window.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Fisher ROC Driver


GE Series 90 Driver Communication Messages Dialog

The Comm Messages button will display the following information about a GE Series 90 driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

GE Series 90 Driver


IEC 60870-5-104 Communication Messages Dialog

The Comm Messages button will display the following information about an IEC 60870-5-104 driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:


Koyo Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Koyo driver tag in response to a left-click. Note that a right-click on the Show Comm button will open a menu, from which you can view associated alarms or a trend window.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Koyo DirectNET Driver


MDS Diagnostic Driver Communication Messages Dialog

The Comm Messages button will display the following information about a MDS diagnostic driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for the MDS hardware, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the MDS diagnostic driver tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

MDS Diagnostic Driver

MDS Diagnostic Driver Statistics Dialog


NMEA 0183 Communication Messages Dialog

The Comm Messages button will display the following information about a NMEA 0183 driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the NMEA 0183 device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the linked tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

NMEA 0183 Driver


Mitsubishi Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Mitsubishi driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for the Mitsubishi PLC, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the Mitsubishi Device tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

Mitsubishi Driver


Modbus Compatible Communication Messages Dialog

The Comm Messages button will display the following information about a Modbus Compatible Device tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for the Modicon PLC, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the Modbus Compatible Device tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

Modbus Compatible Device Driver

Modbus Compatible Device Statistics Dialog


MQTT Communication Messages Dialog

The Comm Messages button will display the following information about an MQTT Client driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

MQTT Client Driver


OCPP Driver Communication Messages Dialog

The Comm Messages button will display the following information about an OCPP driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for OCPP, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the device for data (sending a read request) but the device is not responding. In this case it is wise to check the properties of the OCPP driver tag to make sure all settings are correct.

Related information:

OCPP Driver

OCPP Driver Show Stats


Omron Communication Messages Dialog

The Comm Messages button will display the following information about an Omron driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for the Omron PLC, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the Omron driver tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

Omron Host Link Driver

Omron Statistics Dialog


Omron FINS Driver Communication Messages Dialog

The Comm Messages button will display the following information about an Omron FINS driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Omron FINS Driver


Opto 22 Communication Messages Dialog

The Comm Messages button will display the following information about an Opto 22 Mux driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Opto 22 Mux Driver


Polling Driver Messages Dialog

The Communication Messages dialog for a Polling driver will show the communication messages from the driver tag that this Polling driver is subordinate to.


ScanCom Driver Communication Messages Dialog

The Comm Messages button will display the following information about a ScanCom Driver tag.

  • Displays the full driver name and version.
  • Data may be displayed in any of the 4 types shown.
  • Number Transmitted and Received provides a running count of messages in each direction.
  • Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.
  • The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.
  • If one has the protocol information for the device, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.
  • If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the device for data (sending a read request) but the device is not responding. In this case it is wise to check the properties of the ScanCom Driver tag to make sure all settings are correct.

Related information:

ScanCom Driver Tag

ScanCom Driver Statistics Dialog


Siemens S7 Communication Messages Dialog

The Comm Messages button will display the following information about a Siemens S7 driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for the Siemens S7 PLC, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the Siemens S7 driver tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

Siemens S7 Driver

Siemens S7 Driver Statistics Dialog


SNMP Communication Messages Dialog

The Comm Messages button will display the following information about a SNMP driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If one has the protocol information for the SNMP device, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

Related information:

SNMP Driver

SNMP Driver Statistics Dialog


Tesco Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Tesco driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Tesco Driver


TI505 Communication Messages Dialog

The Comm Messages button will display the following information about a TI505 driver tag.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the TI505 device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the device for data (sending a read request), but the device is not responding. In this case it is wise to check the properties of the TI505 driver tag (station address, comm. channel, etc.) to make sure all settings are correct.


Toyopuc Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Toyopuc Driver tag.

  • Displays the full driver name and version.
  • Data may be displayed in any of the 4 types shown.
  • Number Transmitted and Received provides a running count of messages in each direction.
  • Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.
  • The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.
  • If one has the protocol information for the device, one can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.
  • If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the driver tag (station address, comm. channel, etc.) to make sure all settings are correct.

Related information:

Toyopuc Driver Statistics Dialog

Toyopuc Driver


Veeder Root Driver Communication Messages Dialog

The Comm Messages button will display the following information about a Veeder Root driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Veeder Root Driver


Show Statistics Button Widget

The communications Show Statistics Button widget is used to draw a button that can be clicked to display communication statistics for either the device associated with the button, or all devices in your system.

* Does not use the Style Settings tag.

Example shows the BACnet Statistics dialog. Content will vary by driver.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Which driver type these statistics are for.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess The message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time Time when the last error message was recorded.

Error Date Date when the last error message was recorded.

Error Owner Further details regarding the message.

Error Mem Addr The memory address associated with the error.

The properties dialog for this widget:

You can choose to display statistics for just the attached driver, or for all drivers.

Button Label

Provide the text (if any) that will be displayed on the button.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Connection Status\

Analytics\Statistics\

Analytics\Diagnostics\

Each driver has its own version of the communication statistics dialog, as described in the following topics.

Related information:

ABB Totalflow Driver

Allen-Bradley Statistics Dialog

BACnet Driver

Bristol BSAP/IBP Driver

Bristol Network Tag

CalAmp Diagnostic Driver Statistics Dialog

Campbell Scientific Array Driver Statistics Dialog

Campbell Scientific PakBus Driver Statistics Dialog

CIP Driver Statistics Dialog

CSV Data Driver

Data Diode Client Tag

Data Diode Publisher Tag

Data Flow Statistics Dialog

Delta Driver

DNP3 Driver Statistics Dialog

DriverMUX Statistics Dialog

Enron Modbus Device Statistics Dialog

Fisher ROC Driver Statistics Dialog

GE Series 90 Driver Statistics Dialog

Honeywell Mercury Driver

IEC 60870-5-104 Driver

JSON/XML Driver

MDS Diagnostic Driver Statistics Dialog

Mitsubishi Driver

Modbus Compatible Device Statistics Dialog

MQTT Client Driver

NMEA 0183 Driver Statistics Dialog

Omron Statistics Dialog

Omron FINS Driver Statistics Dialog

OPC Classic Client Driver Statistics Dialog

OPC UA Client Driver

Opto 22 Mux Driver

POC-DV8 Tag

POC-Lufkin SAM Well Manager

POC-Unico Tags

Polling Driver Tags

Fisher ROC Driver

Siemens S7 Driver Statistics Dialog

SNMP Driver Statistics Dialog

SQL Data Query Driver

Tesco Driver Statistics Dialog

TI505 Device Driver

Veeder Root Driver


ABB Totalflow Statistics Dialog

The Show Stats button will display the following information about an ABB Totalflow driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Dt The Response time - that is, the time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Error Mem Addr The memory address related to the last error.

Port Error

Port Number

Related information:

ABB Totalflow Driver

ABB Totalflow Error Codes


Allen-Bradley Statistics Dialog

The Show Stats button will display the following information about an DriverMUX tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Stats For The name of the station for which the statistics are displayed.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Error Mem Addr The PLC address at which the last error occurred.

Serial Error The error number (code) for the serial error (if one has occurred).

Serial ID The ID of the serial error.

SD ID The ID of the KT/SD board, if one has been installed for this I/O device.


BACnet Driver Statistics Dialog

The Show Stats button will display the following information about a BACnet driver tag.

* Does not use the Style Settings tag.

Example shows the BACnet Statistics dialog. Content will vary by driver.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Which driver type these statistics are for.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess The message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time Time when the last error message was recorded.

Error Date Date when the last error message was recorded.

Error Owner Further details regarding the message.

Error Mem Addr The memory address associated with the error.

Related information:

BACnet Driver


CalAmp Diagnostic Driver Statistics Dialog

The Show Stats button will display the following information about a CalAmp diagnostic driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Info Available description about the error.

Related information:

CalAmp Diagnostic Driver

CalAmp Diagnostic Driver Communication Messages Dialog


Campbell Scientific Array Driver Statistics Dialog

The Show Stats button will display the following information about a Campbell Scientific Array driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Related information:

Campbell Scientific Array Driver


Campbell Scientific PakBus Driver Statistics Dialog

The Show Stats button will display the following information about a Campbell Scientific PakBus driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Logger Type The driver's configured logger type.

Module

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Related information:

Campbell Scientific PakBus Driver


CSV Data Driver Statistics Dialog

The Show Stats button will display the following information about a CSV Data driver tag:

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type The type of device driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that is occurring.

Last Error The error number (code) for the last error that last occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

CSV Data Driver


Data Diode Client Statistics Dialog

The Show Stats button will display the following information about a Data Diode Client tag.

This statistics dialog shows a lot of information about the Data Diode Client tag.

Name The name of the client tag for which statistics are being displayed.

Type The type of tag for which statistics are being displayed.

Address The address configured for the linked communication tag.

Error The error number (code) for the current error.

Error Message A message describing the type of communications error that has occurred.

Error Time The time of the last reported error.

Number of Connections The number of active connections between the Data Diode and VTScada

Number Received The number of packets received.

Last Received Time The time of the last transmission.

Error Count The number of errors that have occurred since the system started.

Last Error The error number (code) for the current error.

Last Error Message A message describing the type of communications error that last occurred.

Last Error Time The time of the last reported error.

You can quickly draw this widget by right-clicking the Data Diode Client tag in the tag browser and selecting "Draw". Navigate to the Diagnostics folder and select Comm Stats Btn.

To find the Comm Stats Btn from the widget pallet in Idea Studio, go to Analytics > Diagnostics.

Related information:

Data Diode Client Tag

Show Statistics Button Widget


Data Diode Publisher Statistics Dialog

The Show Stats button will display the following information about a Data Diode Publisher tag.

The statistic dialogs shows current information about the Data Diode Publisher tag.

Name The name of the publisher tag for which statistics are being displayed.

Type The type of tag for which statistics are being displayed.

Address The address configured for the linked communication tag.

Error The error number (code) for the current error.

Error Message A message describing the type of communications error that has occurred.

Error Time The time of the last reported error.

Port Connection Error TCP/IP error code.

Transmitted Count The number of transmitted packets.

Last Transmission Time The time of the last transmission.

Failed Transmission Count The number of failed transmissions.

Last Failed Transmissions Time The time of the last failed transmission.

Error Count The number of errors that have occurred since the system started.

Last Error The error number (code) for the current error.

Last Error Message A message describing the type of communications error that last occurred.

Last Error Time The time of the last reported error.

You can quickly draw this widget by right-clicking the Data Diode Publisher tag in the tag browser and selecting "Draw". Navigate to the Diagnostics folder and select Comm Stats Btn.

To find the Comm Stats Btn from the widget pallet in Idea Studio, go to Analytics > Diagnostics.

Related information:

Data Diode Publisher Tag

Show Statistics Button Widget


Data Flow Statistics Dialog

The Show Stats button will display the following information about a Data Flow RTU driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Stats For The name of the station for which the statistics are displayed.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that is occurring.

Last Error The error number (code) for the last error that last occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

Data Flow RTU Driver

Data Flow Communication Messages Dialog


Delta Driver Statistics Dialog

The Show Stats button will display the following information about a Delta driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Dt The Response time - that is, the time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Mem Addr The memory address associated with the last error

Min Retries The minimum retries recorded for an error.

Max Retries The maximum number of retries recorded for an error.

Avg Retries The average number of retries recorded for an error.

Related information:

Delta Driver Communication Messages Dialog

Delta Driver


DNP3 Driver Statistics Dialog

The Show Stats button will display the following information about a DNP3 driver tag.

Driver Name The full name of the driver for which statistics are being displayed.

Driver Type Identifies the type of driver to which this Show Stats dialog is linked.

Stats For The driver's description.

Version The version number and date that this driver was created.

Debug Log Level Reserved for use when working with technical support.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

DNP3 Driver

DNP3 Driver Communication Messages Dialog


DriverMUX Statistics Dialog

The contents of this dialog will depend on the mode in which the DriverMUX is operating. If set to Alternating or Parallel, the contents will show statistics for the Driver Multiplexer, as follows.

In all other modes, the statistics will be for the selected subordinate driver.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the current error message for this driver.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Last Error Mode Identifies the mode in which the driver was operating at the time of the last error.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

Driver Multiplexer


Enron Modbus Device Statistics Dialog

The Show Stats button will display the following information about an Enron Modbus driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Min Retries The minimum number of attempts at communication (retries) after an error has occurred.

Avg Retries The average number of attempts at communication (retries) after an error has occurred.

Related information:

Enron Modbus Driver


Fisher ROC Driver Statistics Dialog

The Show Stats button will display the following information about a Fisher ROC driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Address The address at which the error occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Related information:

Fisher ROC Driver


GE Series 90 Driver Statistics Dialog

The Show Stats button will display the following information about a GE Series 90 driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Error Mem Addr

Related information:

GE Series 90 Driver


Honeywell Mercury Show Stats

The Show Stats button will display the following information about a Honeywell Mercury driver tag:

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type The type of device driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that is occurring.

Last Error The error number (code) for the last error that last occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

Honeywell Mercury Driver


IEC 60870-5-104 Driver Statistics Dialog

The Show Stats button will display the following information about a IEC 60870-5-104 driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Error Value The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Failed Count The number of failed communications since the system started.

Success Count The number of successful communications since the system started.

Quality A calculation of the communication quality.

Response Time The time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Error Address The address where the last error occurred.

Comm Stats Timestamp The time when these statistics were generated.

Comm Stats Caller Info

Last Success Timestamp The time of the last successful communication.

Last Error Value The error number (code) for the last error that occurred.

Last Error Address The address associated with the last error.

Last Error Timestamp The time of the last error.

Last Error Caller Info The module associated with the last error.

Last Error Message The message associated with the last error number.

Related information:

BSAP Driver Tags


JSON/XML Statistics Dialog

The Show Stats button will display the following information about a JSON/XML driver tag.

Inline DTD and schemas represent an inherent security risk and are not supported by the JSON/XML driver. If you attempt to read such a file, the message, "error: DTD is prohibited" will be returned. No value will be read into the attached I/O.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error. 0 represents no error.

Error Mess A message describing the type of communications error that has occurred. Invalid if no error message is present.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

JSON/XML Driver


Koyo Device Statistics Dialog

The Show Stats button will display the following information about an Koyo driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Min Retries The minimum number of attempts at communication (retries) after an error has occurred.

Avg Retries The average number of attempts at communication (retries) after an error has occurred.

Related information:

Koyo DirectNET Driver


MDS Diagnostic Driver Statistics Dialog

The Show Stats button will display the following information about a MDS diagnostic driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

dt The Response time - that is, the time between a request for information and the message being received.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

MDS Diagnostic Driver

MDS Diagnostic Driver Communication Messages Dialog


Mitsubishi Driver Statistics Dialog

The Show Stats button will display the following information about a Mitsubishi driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being sent.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Mem Addr The memory address associated with the error.

Min Retries The minimum number of attempts at communication (retries) after an error has occurred.

Max Retries The maximum number of attempts at communication (retries) after an error has occurred.

Avg Retries The average number of attempts at communication (retries) after an error has occurred.

Related information:

Mitsubishi Driver


Modbus Compatible Device Statistics Dialog

The Show Stats button will display the following information about a Modbus Compatible Device tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Stats For The name of the station for which the statistics are displayed.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Min Retries The minimum number of attempts at communication (retries) after an error has occurred.

Avg Retries The average number of attempts at communication (retries) after an error has occurred.

Related information:

Modbus Compatible Device Driver

Modbus Compatible Communication Messages Dialog


Motorola ACE Statistics Dialog

The Show Stats button will display the following information about a Motorola ACE Driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Version The version number and date that this driver was created.

Gateway The name of the IP Gateway tag used by this driver.

RTU ID The name of the RTU as specified in the driver configuration.

RTU Type The name of type tables as specified in the configuration file.

Link Status Shows whether the link is connected.

Counts The number of successful communications since the system started.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The name of the module, in which the error occurred.

Error Address May be used to identify which instance of the module, named in Error Owner, caused the error

Related information:

Motorola ACE Driver


MQTT Client Driver Statistics Dialog

The Show Stats button will display the following information about an MQTT Client driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Module reporting The VTScada module name

Value The most recently reported driver value - 0 is success.

Message A message describing the type of communications value that last occurred.

Address The topic name for which the value occurred.

TimeThe UTC time that the most recent value occurred.

dt The Response time - that is, the time between a request for information and the message being received.

Module reporting success The VTScada module name that last reported a success.

Success Count The number of successful communications since the system started.

Last Success Time The UTC time of the last successful communication.

Error Count The number of errors that have occurred since the system started.

Last Error The error number (code) for the last error that occurred.

Last Error Message A message describing the type of communications error that last occurred.

Last Error Time The time of the last reported error.

Last Error Address The topic name for which the error occurred.

Related information:

MQTT Client Driver


NMEA 0183 Driver Statistics Dialog

The Show Stats button will display the following information about a NMEA 0183 driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Dt The Response time - that is, the time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Max Dt The maximum recorded response time.

Min Dt The minimum recoreded response time.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Error Mem Addr The memory address related to the last error.

Related information:

NMEA 0183 Driver


OCPP Driver Show Stats

Omron Statistics Dialog

The Show Stats button will display the following information about an OCPP driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

OCPP Driver

OCPP Driver Communication Messages Dialog


Omron Statistics Dialog

The Show Stats button will display the following information about an Omron driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Stats For The name of the station for which the statistics are displayed.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Min Retries The minimum number of attempts at communication (retries) after an error has occurred.

Max Retries The maximum number of attempts at communication (retries) after an error has occurred.

Avg Retries The average number of attempts at communication (retries) after an error has occurred.

Related information:

Omron Host Link Driver

Omron Communication Messages Dialog


Omron FINS Driver Statistics Dialog

The Show Stats button will display the following information about an Omron FINS driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Related information:

Omron FINS Driver


OPC Classic Client Driver Statistics Dialog

The Show Stats button will display the following information about an OPC Classic Client driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Version The version number and date that this driver was created.

OPC Server Status Information about the attached OPC server.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Mem Addr The memory address on the OPC server, related to the error.

Note: For OPC, the Response time value will vary, since the OPC Classic Client driver does not make requests for data, rather, data is sent to it when changes occur.

Related information:

OPC Classic Client Driver


OPC UA Client Driver Statistics Dialog

The Show Stats button will display the following information about an OPC UA Client driver tag.

Note the Endpoints button. This trouble-shooting tools displays the list of OPC UA Server Endpoint information that is retrieved by the driver and held internally.

An OPC UA server may offer multiple endpoints that can be used by clients to connect to it. The endpoints vary in terms of the authentication methods and security levels. The dialog shows what VTScada has received back from the server when it makes its initial (unsecured) connection to retrieve the endpoints. The driver will then choose the most secure endpoint available with the configured authentication method.

Driver Name The full name of the driver for which statistics are being displayed.

Driver Type The tag type this driver is.

Stats for Identifies the driver.

Version The version number and date that this driver was created.

Debug Log Level Reserved for use when working with technical support.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Message A message describing the type of communications error that has occurred.

Error Address Where the error occurred

Last Error The error number (code) for the last error that occurred.

Last Error Message A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

OPC UA Client Driver


Opto 22 Driver Statistics Dialog

The Show Stats button will display the following information about an Opto 22 driver tag:

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Stats for Identifies the station for which these statistics have been gathered.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Dt The Response time - that is, the time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Related information:

Opto 22 Mux Driver


Rockwell Driver Statistics Dialog

The Show Stats button will display the following information about the status of a Rockwell driver instance. This information is only available on the I/O server for the driver.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Which driver type these statistics are for.

Version The version number and date that this driver was created.

Port Connected "Yes" means there is valid TCP/IP Socket to the device, "No" means no socket

EtherNet/IP Session "Open" means there is a session established with the device, "Closed" means there is no session

Number of CIP Connections Actual number of active CIP Connections/Configured Maximum number of CIP Connections

Read PLC Tags The status of the PLC tag upload which includes:

  • Idle - this device supports a PLC tag upload but it is optional,
  • Completed - the last PLC Tag upload completed successfully,
  • Active(x%) - a PLC tag upload is active with the percent complete,
  • Error- the last attempt failed
  • Not supported - not supported by the device

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess The message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time Time when the last error message was recorded.

Error Date Date when the last error message was recorded.

Error Info Further details regarding the message.

Is my device connected?

You need a TCP/IP socket connection first before an Ethernet/IP Session can be established. After the session is established, CIP Connections should open and the PLC tag upload should start. After the PLC tag upload is completed or idle, your tags should start reading.

If any of the error messages start with an FO, there was a Forward Open failure when attempting to open a CIP Connection. The message should give a suggestion as to why the CIP Connection did not open.

Related information:

Rockwell Driver Tag


ScanCom Driver Statistics Dialog

The Show Stats button will display the following information about a ScanCom driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Dt The time between successive error-free replies. This is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

ResponseTime The time between triggering the read / write and receiving the error-free reply. This can help diagnose a large dt value by determining if the delay is in the communication transaction itself.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Mem Addr The memory address associated with the last error

Min Retries The minimum retries recorded for an error.

Max Retries The maximum number of retries recorded for an error.

Avg Retries The average number of retries recorded for an error.

Related information:

ScanCom Driver Tag

ScanCom Driver Communication Messages Dialog


Siemens S7 Driver Statistics Dialog

The Show Stats button will display the following information about a Siemens S7 driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Version The version number and date that this driver was created.

Stats For The name of the station for which the statistics are displayed.

Counts The number of successful communications since the system started.

Success Count Displays a count of successfully transmitted messages.

Timestamp Displays the time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Response Time The time it takes the PLC/RTU to receive a command, process it and send a response.

Error The error number (code) for the current error.

Error Mess Describes the type of communications error that has occurred.

Failed Count Incremented on each error.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Address If an address was associated with the error, it will be recorded here.


SNMP Driver Statistics Dialog

The Show Stats button will display the following information about a SNMP driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Version The version number and date that this driver was created.

Stats For The name of the station for which the statistics are displayed.

Counts The number of successful communications since the system started.

Timestamp Displays the time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess Describes the type of communications error that has occurred.

Err OID Gives the object ID where the error occurred.

Error Count Incremented on each error.

Last Error The number (code) for the error that last occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Last Err OID A message giving the object ID where the error last occurred.

Error Time The time of the last reported error.

Error Date The date of the last reported error.


SQL Data Driver Statistics Dialog

The Show Stats button will display the following information about an SQL Data driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

SQL Data Query Driver


Tesco Driver Statistics Dialog

The Show Stats button will display the following information about a Tesco driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Error The error number (code) for the current error.

Error Message A message describing the type of communications error that has occurred.

Message Type The data format of the message.

Response Time The time between a request for information and the information being sent.

Success Count The number of successful messages.

Success Time The time of the last successful communication.

Error Count The number of errors that have occurred since the system started.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Last Error Type Indicates the data type of the last message.

Related information:

Tesco Driver


TI505 Show Stats Dialog

The Show Stats button will display the following information about a TI505 driver tag. In this example, no device exists at the specified port and address.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Datestamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Err Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.


Toyopuc Driver Statistics Dialog

The Show Stats button will display the following information about a Toyopuc driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Dt The Response time - that is, the time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Mem Addr The memory address associated with the last error

Min Retries The minimum retries recorded for an error.

Max Retries The maximum number of retries recorded for an error.

Avg Retries The average number of retries recorded for an error.

Related information:

Toyopuc Driver Communication Messages Dialog

Toyopuc Driver


Veeder Driver Statistics Dialog

The Show Stats button will display the following information about a Veeder driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Version The version number and date that this driver was created.

Error The error number (code) for the current error.

Error Message A message describing the type of communications error that has occurred.

Message Type The data format of the message.

Response Time The time between a request for information and the information being sent.

Success Count The number of successful messages.

Success Time The time of the last successful communication.

Error Count The number of errors that have occurred since the system started.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Last Error Type Indicates the data type of the last message.

Related information:

Veeder Root Driver


Compass 1 Widget

Used by: I/O and Calculations, Analog Input, Analog Output, Analog Status, Analog Control, Calculation.

* Does not use the Style Settings tag.

Displays a compass having a needle that rotates according to the tag's value. The compass needle will point to North when the tag's value is 0. Direction of rotation is clockwise for positive values. The full range of the underlying tag's scaled values will cause one rotation.

The properties dialog for the Compass 1 widget:

Use Tag's Scaled Min & Max Values

In most cases, it is best to select this option. The tag's minimum scaled value corresponds to North (0 degrees on the compass) and the maximum scaled output value as well (360 degrees).

If the compass is to represent tags such as Calculation and Function that do not have their own scaled values, then deselect this box and enter the minimum and maximum values that can be expected from the tag.

Minimum Value and Maximum Value

The Minimum Value and Maximum Value fields are used to scale the amount of rotation of the needle, relative to the tag’s scaled output values.

For example, given a tag with scaled output ranging from 0 to 100:

Setting the widget’s scale range from 0 to 200 results in a needle that will rotate by a maximum of 180 degrees.

Setting the widget’s scale range from 0 to 50 results in a needle that will complete two full rotations.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Compass\

Related information:

Choices for Operator Interaction


Compass 2 Widget

Used by: I/O and Calculations, Analog Input, Analog Output, Analog Status, Analog Control, Calculation.

* Does not use the Style Settings tag.

Displays a compass having a numeric display that rotates according to the tag's value. The 0-value will point to North when the tag's value is 0. Direction of rotation is counter clockwise for positive values. The full range of the underlying tag's scaled values will cause one rotation.

The properties dialog for the Compass 2 widget:

Use Tag's Scaled Min & Max Values

In most cases, it is best to select this option. The tag's minimum scaled value corresponds to North (0 degrees on the compass) and the maximum scaled output value as well (360 degrees).

If the compass is to represent tags such as Calculation and Function that do not have their own scaled values, then deselect this box and enter the minimum and maximum values that can be expected from the tag.

Minimum Value and Maximum Value

The Minimum Value and Maximum Value fields are used to scale the amount of rotation of the dial, relative to the tag’s scaled output values.

For example, given a tag with scaled output ranging from 0 to 100:

Setting the widget’s scale range from 0 to 200 results in a dial that will rotate by a maximum of 180 degrees.

Setting the widget’s scale range from 0 to 50 results in a dial that will complete two full rotations.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Compass\

Related information:

Choices for Operator Interaction


Connection Status Indicator Widget

Used by: Serial Port

Enabled for TCP/IP Port and UDP/IP Port, but should not be used for those tags.

* Does not use the Style Settings tag.

The Connection Status Indicator is used to notify operators when the port being monitored is in any of the following states: Disconnected, Connecting, Connected, or Failed.

You may configure the indicator to use any color for each state, and to use any image (or none) to display the status. The default configuration is a color-coded rectangle. Note that the rectangle is solid - it will not interact with active orange as is the case with an Image Change widget.

Use Same Image for All States

Select this box if you wish to use the image selected for State 0 (Disconnected), for all states of the tag.

This option is often used when the selected image's indicator area (the small rectangle at its base) is to be replaced with a new color according to the state of the tag.

Use Image / No Image

Select whether to include an image for the Connector Status.
If not using an image, you should select Color Replace, then position the Connector Status over an area of Active Orange. Everything that is Active Orange below the Connector Status will be replaced with the matching state's color.

Color Replace

Use the Color Replace option if the image includes a color indicator patch, or if you have selected the No Image option. (Color indicators within images are areas of Active Orange.)

Select (Image)

Opens the Select Color Dialog, from which you can choose a color, either to colorize the image, or to replace Active Orange color patches.

Adjust (Image)

Opens the Adjust Image dialog, with its full range of controls over image appearance.

Clear (Image)

Remove the image. Has the same effect as selecting the No Image option.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Color Indications\

Basic Components\Images\

Analytics\Communications\Connection Status

Related information:

Adjust Image Dialog - Tools within the Adjust Image dialog.

Choices for Operator Interaction


Control Token Box

Used by: Any output tag or parent tag

* Does not use the Style Settings tag.

This is a multi-use widget for Control Tokens that both indicates current token status and affects token behavior.

It can be used to indicate whether the current user has a token on the linked widget. The box will be colored the ‘No Token Color’ (red by default) if you do not have a token on the linked tag, the ‘Pending Token Request Color’ (orange by default) if you have a pending token request for the linked tag and the ‘Possessing Token Color’ (green by default) if you possess the token for the linked tag.

The Control Token Box can also be used to request or release a token automatically on the linked tag when the page the widget is drawn upon is opened (auto-request) or closed (auto-release). This aligns well with the security best-practice of placing controls on pop-up pages. (Best Practices for Security) Use the ‘Auto Request/Release’ option to enable this feature.

If you would like to keep the token after closing the page, you can check the ‘Hold Token Button’. If you would automatically re-request the token after losing it, you can check the ‘Auto Re-Request’ check box. The widget can also be made invisible by checking the ‘Hide’ box. (While these notes refer to "closing the page", any action that means the widget is no longer active on screen will have the same effect. For example, if the widget is drawn on a tabbed folder and you switch to a different tab.)

The properties dialog for the Control Token Box object:

No Token Color

Sets the color of the box when you do not have a Control Token on the linked tag.

Pending Token Request Color

Sets the color of the box when you have requested a Control Token on the linked tag.

Possessing Token Color

Sets the color of the box when you have a Control Token on the linked tag.

Auto Request Level

Applies only when you have enabled Auto Request / Release. Sets the Level that will be used for your automatic request.

Auto Request/Release

When selected, this widget will automatically request a Control Token for the linked tag when the page is opened and then automatically release that token when the page is closed.

Auto Re-Request

Certain events can release a token that you hold (For example, token administrators can release a token held by any user.) If this option is selected, and if the page displaying this widget remains open, the widget will automatically create a new request for a Control Token on the linked tag.

Hold Token

If selected then the act of closing the page where this widget is drawn will not release the token that you hold.

Hide

The widget does not need to be visible in order for the Auto Request/Release, Auto Re-Request, and Hold Token features to be active. You might choose to use the widget for the purpose of enabling those features on a page that holds control widgets for a tag but hide the Control Token Box itself.

Global Token

Global tokens grant control of every output in the tag tree from the root. A Global Token will not force the release of other Control Tokens. After a Global Token has been granted, the user must wait until all Control Tokens have been released and then they will assume control.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Control Tokens


Custom Meters

If your site uses meters that do not look like any that are included with VTScada, you can build your own using the components provided in the Tools >> Meter parts folder of the Widgets palette.

A custom meter is a Tag Widget, typically including several parameters for configuration. The subtopics listed in the menu describe the components that are available. For the instructions to assemble these components into a new meter please refer to Create a Tag Widget For One Tag.

Note that the bezel and the glass overlay are images, found in the Meter Parts folder of the Images palette.

Example:

  1. Working in the Idea Studio, create a new, empty tag widget.

  2. When prompted for tag types, select Analog Status tags (assuming that these are what you use most often). You will probably want to also be able to use the meter with other tags that have analog data such as Analog Input and Calculation, but this can be left until later.

  3. You will be prompted for a title. In this example the widget will be named Custom Meter 1.

  4. A nearly-blank screen will open, containing only the Tag Icon Marker. Ignore the marker for now.
  5. In the Widgets palette, navigate to the Tools >> Meter Parts folder.
  6. Start by dragging a scale to the screen. For this example, a Radial Scale was used.

  7. Open this object's properties dialog and adjust the appearance as you wish.
  8. Make a note of any properties that you want to be adjustable in the finished widget. For each, you must create a parameter in your widget. For the scale in this example, only the number of major divisions will be made available to users of our custom widget.
  9. Close the properties dialog then open the Widget Properties ribbon.
  10. Open the Manage Parameters tool and click Add.
  11. The example parameter was named pMajorDivisions (where "p" stands for "parameter"). The type is Short because there should never be more than a few divisions in the meter.

  12. After adding the parameter, click OK to close the Manage Parameters dialog.
  13. Click the Values tool in the Widget Properties toolbar to open the Edit Parameters dialog. Setting values here does not assign defaults. It simply gives the parameter a value to show while working in the Idea Studio.
  14. In this example the value for pMajorDivisions is set to 6.
  15. Re-open the properties dialog for the legend. Set the data source for Major Divisions to Parameters, then select pMajorDivisions.

It is unlikely that you will want to make every parameter of every component of your meter available to users to customize. For those parameters that you do want to want to expose, you must repeat the same sequence of steps that you have just completed.

  16. The next step in this example is to add a radial legend. Drag one to the screen, placing it above the scale.
  17. Re-size the legend so that the text fits within the circle of the scale, then align midpoints.
  18. The number of labels must match the number of major division marks, which is one greater than the number of divisions. You can use the pMajorDivisions parameter as part of an expression.
  19. Change the data source for the number of labels to use Expression.

  20. In the expression field, type pMajorDivisions + 1

  21. Leave the properties dialog open after completing this step. If you would rather have whole numbers in the legend, change the value of the pMajorDivisions parameter to be an odd number.

The numbers in the legend should reflect the scaling of the linked tag. Several steps will be required to achieve this.

  22. Expand the data source for the Tag parameter of the legend and choose Linked Tag Property.

  23. In the drop down list, select Linked Tag (Analog Status).

  24. In the Scaling section of the properties, select the option, Use Tag Scaling, then click OK to close the properties dialog.

The next component to add will be the indicator. A radial Indicator was used for this example.

  25. Place the indicator so that it is aligned with the other components, scaling if desired. If you would like to change the color of the indicator, note that the starting color is blue rather than the standard gray. This means that you must open the advanced options for the indicator and adjust the hue and saturation sliders rather than simply applying a color. Refer to the notes for the Radial Indicator for more information.
  26. The data source must be the Linked Tag (Analog Status), as for the legend. Ensure that the Use Tag Scaling option is selected.
  27. To add a finish to the meter, add images for the bezel and glass overlay. A selection can be found in the Images palette under Widget Parts >> Meter Parts.
  28. Select all components and align midpoints.
  29. Move the entire selection so that your meter just touches the top and left edge of the Idea Studio window. This corner is the standard reference location for all widgets.

  30. If you use the meter with tags other than Analog Status, return to the Widget Properties ribbon and use the Tag Types tool to associate other tags. Analog Input and Calculation are suggested.

To find and use your new meter, you will need to add it to a palette.

  1. In the Widgets palette, open the Gauges folder.
  2. Right-click anywhere within this palette and select New from the menu that opens.
  3. In the New Item dialog, select Advanced.
  4. In the New Menu Item Properties dialog, select Widget.
  5. Find and select Custom Meter 1.
  6. When you return to the New Menu Item Properties dialog, click the Set Parameters button. You may choose to assign a default value here for the number of major divisions. Click OK when finished.
  7. Open a page in the Idea Studio (not a widget) and drag your new meter to that page. Link it to a tag. You may open the properties dialog to adjust the parameter, Number of Major Divisions.

Related information:

Sample Widget - For advanced developers. Source code of the Antique Bolted meter.

Related Tasks:

Create a Tag Widget for One Tag


Compass Indicator

Used by: custom compass designs of your own creation.

The compass indicator widget represents the associated tag's value as a needle that swings from the defined reference angle through a full circle in response the linked tag's value.

The properties dialog for the Compass Indicator:

Data source

The indicator must be linked to a tag before it can be grouped into a new meter as part of a tag widget. Also, a tag must be selected before the "Use tag's scaled min and max values" option can be chosen in the Scaling part of this dialog.

Select / Adjust / Clear Image

The image to be used for the needle. In general, the image should have a vertical orientation. The Adjust option opens the Adjust Image dialog.

Options

Offset from center: A vertical offset, allowing you to position the needle so that a portion is below the center.

Counter Clockwise: Controls the direction that the needle rotates in response to increasing tag values.

Reference angle: The angle that corresponds to both the tag's minimum and maximum scaled value. Angles are measured in degrees, clockwise from vertical.

Dampen movement: When selected, applies an animation effect to needle motion so that the image appears to sweep from one value to another rather than jumping immediately.

Color options

A complete selection of options for controlling the color and opacity of the selected image.

Scaling

Used to set the tag values corresponding to the minimum and maximum angles. It is recommended that you use the tag's scaled values.

Widget Folders:

Tools\Meter Parts


Draw Scale

This is a legacy widget. For new applications, you are advised to use either Linear Scale Widget or Radial Scale Widget.

Used by: custom meters of your own design.

The draw scale provides tick marks to custom widgets of your own design. These may be radial or linear.

The properties dialog for the Draw Scale:

Major and minor tick

Use the buttons to select or adjust the image that will be used for each tick mark. Selected images should always have a vertical orientation for correct alignment along the scale. If you are looking for a specific color that does not appear to be available in the basic colorize menu, open the properties and move the dialog box to the side so you can still see the scale in Idea Studio. Select Adjust for the Major or Minor tick and click advanced. Set the color to white and then use the Hue slider to find the correct color. The color of the ticks on your scale in Idea Studio will change as you move the slider. To replicate the same color in the other tick, follow the same process but copy and paste the hue setting.

Tick mark options

Number of major divisions. Number of major tick marks to display across the scale range of the meter.

Number of minor divisions. Number of minor tick marks to display between each major tick mark.

Relative size. Scale the selected images. This is a multiplier, applied as a scale factor to the images.

Scale options

Choose whether a linear or radial scale will be drawn.

If linear, select a horizontal or vertical orientation for the scale. A vertical image will be turned to the horizontal orientation to show tick marks up a vertical scale. It will be oriented vertically to show tick marks along a horizontal scale.

The tick marks will be placed along one edge of the Draw Scale bounding box. Use the Reflect Image check box to move the scale to the opposite side of the bounding box.

If the radial scale option is selected, set the minimum and maximum values for the scale to fill. Values are measured clockwise from vertical, and the scale will fill from the angle specified as minimum, clockwise to the angle specified as maximum. By way of illustration, note the scale resulting from the default angles, where the minimum (start of the scale) is a larger value than the maximum (end of the scale).

Widget Folders:

Tools\Meter Parts


Linear Indicator

Used by: custom meters of your own design.

The linear indicator widget represents the associated tag's value as a line that moves across the scale range. Any image may be used in place of the line, but it should have a clear pointer to help the operator read the current position of the meter.

The properties dialog for the Linear Indicator:

Data source

The indicator must be linked to a tag before it can be grouped into a new meter as part of a tag widget.

Select (Image)

Opens the Select Image Dialog, from which you can choose the image to use for the indicator.

Adjust (Image)

Opens the Adjust Image dialog, with its full range of controls over image appearance.

Clear (Image)

Remove the image.

Options

Orientation: The direction that the needle image will travel. If vertical is to be selected, it is essential that you choose a horizontal needle.

Reverse direction: Control the direction in which increasing values are represented.

Draw mode:

  • Moving - the value is represented as a moving line:
  • Scale - represented by an expanding bar that fades slightly towards the maximum range.
  • Crop - represented by an expanding bar, that stays sharp to its maximum range, but blurs along the sides.

Dampen movement: When selected, applies an animation effect to needle motion so that the image appears to sweep from one value to another rather than jumping immediately.

Number of steps: If set to 0, the indicator shows the exact value. If set to a larger value, the indicator is divided into the given number of steps and the display will round to the nearest step. So, for example, a step of 1 would mean all on or all off. 20 steps on an indicator that ranges from 0 to 100 would round the display to the nearest multiple of 5.

Scaling

Used to set the tag values corresponding to the minimum and maximum angles. It is recommended that you use the tag's scaled values.

Widget Folders:

Tools\Meter Parts


Linear Legend Widget

Used by: custom meters of your own design. Often used in combination with the Linear Scale widget.

* Does not use the Style Settings tag.

The Linear Legend Widget represents the associated tag's minimum and maximum scale range as a series of numbers in a line. The widget can be oriented either vertically or horizontally. Text can be configured to a set size, or to scale with the widget. In the following example, the horizontal legend has a smaller width than the vertical legend, therefore a smaller font is used.

The properties dialog for the Linear Legend widget.

Tag

The legend must be linked to a tag before it can be grouped into a new meter as part of a tag widget. Also, a tag must be selected before the "Use tag's scaled min and max values" option can be chosen in the Scaling part of this dialog. Note that there is no Link option for this widget - linking must be done from within this properties dialog.

Font

The font tag to be used for the numeric values of the scale.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Number of Labels

Sets the number of labels shown as part of the legend.

Color

Controls the color to be used for the text of the legend.

Orientation

Choose whether the legend should run horizontally or vertically.

Alignment

Sets the placement of the text within the bounding box. For horizontal legends, the options are Top, Center and Bottom. For vertical legends, the options are Left, Center and Right.

Scale Label Size

If selected, the font size with scale with the bounding box of the label. Select this option when the legend is to be used on pages with the Scale Page option enabled. Otherwise, you may find it easier to maintain consistent label sizes by deselecting this option and using the Font selection to control the label size.

Reverse Direction

By default, values increase from left to right (horizontal legend) or bottom to top (vertical legend). Select this option to reverse the direction in which values will increase.

Scaling

Choose whether to provide your own values for the minimum and maximum scaling or to use values supplied by the linked tag. In most cases, it is best to use scaling values from the linked tag.

Widget Folders:

Tools\Meter Parts

Related information:

Linear Scale Widget


Linear Legend Widget (Legacy)

Used by: custom meters of your own design.

The Linear Legend Widget represents the associated tag's minimum and maximum scale range as a series of numbers in a line. The bounding box is square so that the widget can be oriented either vertically or horizontally.

The properties dialog for the Linear Legend widget:

Tag

The legend must be linked to a tag before it can be grouped into a new meter as part of a tag widget. Also, a tag must be selected before the "Use tag's scaled min and max values" option can be chosen in the Scaling part of this dialog.

Font

The font tag to be used for the numeric values of the scale.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Number of labels.

Can be no less than one. If too many numbers are displayed, the numbers will overlap, making it difficult for the operators to read the display.

Color.

Select the color for the legend.

Scale label size.

When selected, the label will scale with the rest of the meter.

Direction and Alignment

May be horizontal or vertical. In both cases, you may choose to align to the left, center or right of the bounding box.

Reverse Direction

You can configure the numbers to increase in either direction by using the Reverse Direction check box.

Scaling

Used to set the smallest and largest values to display on the meter. Unless you are certain that this meter will be used only for a given scale range, it is best to allow the scale to change to match the linked tag.

Widget Folders:

Tools\Meter Parts


Linear Scale Widget

Used by: custom meters of your own design. Often used in combination with the Linear Legend widget.

* Does not use the Style Settings tag.

The Linear Scale Widget represents the associated tag's minimum and maximum scale range as a series of major and minor tick marks. The widget can be oriented either vertically or horizontally.

The properties dialog for the Linear Scale widget.

Number of Major and Minor Divisions

Controls the number of large (major) to be drawn across the scale and the number of small (minor) tick marks to be drawn between major tick marks.

Minor Tick Size

The minor tick size is set as a percentage of the major tick size.
The major tick size is controlled by the bounding box of the widget.

Major and Minor Tick Width

Sets the width of each type of tick mark, measured in pixels. Note that when the correct placement of a tick mark falls between two pixels on the screen, the widget will compensate by using both adjoining rows of pixels, varying the intensity of each row according to the percentage of the correct tick mark placement that would fall upon it.

Orientation

Controls whether the scale should be drawn left to right (horizontally) or up and down (vertically).

Alignment

Sets the placement of the minor tick marks within the bounding box. The major tick marks will always fill the width of the box. For horizontal scales, the options are Top, Center and Bottom. For vertical scales, the options are Left, Center and Right.

Trim Lines

Optional lines that connect the tick marks as shown. In this example trim line 2 of both the major and minor tick marks overlap because the minor tick marks are aligned with the bottom of the bounding box.

Major and Minor Tick Color

Controls the color used for the tick marks.

Widget Folders:

Tools\Meter Parts

Related information:

Linear Legend Widget

Radial Scale Widget - Tick marks used within a radial meter.


Radial Indicator

Used by: custom meters of your own design.

The radial indicator widget represents the associated tag's value as needle rotating about a fixed center. The red lines shown here are not visible to the operator. They show only in the Idea Studio, as a guide to help you place the indicator. The needle may be any image, any color.

The properties dialog for the Radial Indicator:

Data source

The indicator must be linked to a tag before it can be grouped into a new meter as part of a tag widget. Also, a tag must be selected before the "Use tag's scaled min and max values" option can be chosen in the Scaling part of this dialog.

Select (Image)

Opens the Select Image Dialog, from which you can choose the image to use for the indicator.

Adjust (Image)

Opens the Adjust Image dialog, with its full range of controls over image appearance.

Clear (Image)

Remove the image.

Options

Offset from center: A vertical offset, allowing you to position the needle so that a portion is below the center.

Counter Clockwise: Controls the direction that the needle rotates in response to increasing tag values.

Minimum angle & maximum angle: Controls the range of the needle motion, assuming a clockwise rotation. Values are measured in degrees, clockwise, relative to the vertical position.

Dampen movement: When selected, applies an animation effect to needle motion so that the image appears to sweep from one value to another rather than jumping immediately.

Scaling

Used to set the tag values corresponding to the minimum and maximum angles. It is recommended that you use the tag's scaled values.

Widget Folders:

Tools\Meter Parts


Radial Legend Widget

Used by: custom meters of your own design.

The Radial Legend widget represents the associated tag's minimum and maximum scale range as a series of numbers around an arc.

The properties dialog for the Radial Legend widget:

Tag

The legend must be linked to a tag before it can be grouped into a new meter as part of a tag widget. Also, a tag must be selected before the "Use tag's scaled min and max values" option can be chosen in the Scaling part of this dialog.

Font

The font tag to be used for the numeric values of the scale.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Angles

Minimum and maximum angles, measured clockwise around the meter. All angles are measured in degrees, starting at North (vertical) and measured clockwise.

Options

Set the number of labels to display. Can be no less than one.If too many labels are shown, then they will overlap, making it difficult for the operator to read the meter.
Meters will look best if the number of labels is a function of the tick marks shown by the Draw Scale.

Scale Label Size. If selected, the text of the labels will scale with the rest of the meter when resized.

Color: Opens the Select Color dialog, from which you can choose the color to be used for the legend.

Counter Clockwise. If selected, numbers will increase from right to left, counter-clockwise across the meter

Label Rotation: Select one of the following options:

Scaling

Used to set the smallest and largest values to display on the meter. Unless you are certain that this meter will be used only for a given scale range, it is best to allow the scale to change to match the linked tag.

Widget Folders:

Tools\Meter Parts


Radial Scale Widget

Used by: custom meters of your own design. Often used in combination with the Radial Legend widget.

* Does not use the Style Settings tag.

The Radial Scale Widget represents the associated tag's minimum and maximum scale range as a series of major and minor tick marks. The scale will always be round, regardless how the bounding box is stretched. In all cases, the smaller dimension of the bounding box will be used to set the diameter of the scale.

The properties dialog for the Linear Scale widget.

Number of Major and Minor Divisions

Controls the number of large (major) to be drawn across the scale and the number of small (minor) tick marks to be drawn between major tick marks.

Major and Minor Tick Size

Both tick sizes are expressed as a percentage of the lesser dimension of the widget's bounding box. They will scale as the display changes. By default, the major tick size is 10% of the scale's radius. The minor tick mark size is 5%.

Major and Minor Tick Width

Sets the width of each type of tick mark, measured in pixels.

Minimum and Maximum Angle

Controls the angle covered by the scale. Angles in VTScada are measured clockwise from vertical, using degrees. This is why the default minimum angle is a larger number than the default maximum. The scale sweeps clockwise from the 225 degree position, past vertical to the 135 degree position.

Alignment

Sets the placement of the minor tick marks relative to the major tick marks. The minor tick marks may be aligned against the inside edge, center, or outside edge of the major tick marks.

Trim Lines

Optional lines that connect the tick marks as shown. Trim line 1 (major and minor) is towards the outside of the arc and trim line 2 is towards the inside. In this example trim line 2 of both the major and minor tick marks overlap because the minor tick marks are aligned with the outside of the arc.

Major and Minor Tick Color

Controls the color used for the tick marks.

Widget Folders:

Tools\Meter Parts

Related information:

Radial Legend Widget


Data Age Widget

Used by: Data Flow RTU, Polling Driver.

* Does not use the Style Settings tag.

The Data Age tag widget is used to display the time of the most recent poll of an RTU in hours, minutes, and seconds.

An example of a configured properties dialog for the Data Age widget:

Font

Select one of the font tags (or parameter linked to a font tag) that you with to use to display the text. The display will use the default system font if you do not select a font tag.

The parameters button is enabled only if the tag is drawn on a page that includes a font parameter or if the tag is part of a widget and the associated widget editor is open.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Type of Border

Select the type of border you would like to display the data age within. This can be one of three choices, as illustrated:

Text

Opens the Select Color Dialog from which you can choose the color of the text.

Background

Opens the Select Color Dialog from which you can choose the color of the background.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Polling\

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


Data Diode Widgets

Widgets in this section were designed for use with the Data Diode Publisher tag and Data Diode Client tag. Data Diode Publisher widgets are intended for use on the secure app located on the secured side of the Data Diode. Data Diode Client widgets are intended for use on the unsecured client application.

As there is no way to communicate up stream from the unsecured application to the secured application, you cannot configure a working publisher widget on the unsecured client application.

Data Diode Start Button Widget

Starts transmitting outstanding data from the historian to the data diode. The application will resume from the last known transmission and will continue to transmit live information as it becomes available. The transmissions will stop if the Data Diode Publisher Stop button is used or if the publishing application stops.

Data Diode Stop Button Widget

This button will stop VTScada from transmitting data from the historian to the Data Diode. This button will remain disabled unless a transmission is underway.

Data Diode Start From Date/Time Button

Clicking this button opens a dialog to set the time (UTC) and the date. Click the calendar icon to open a calendar tool for selecting the date. Start from Date/Time will start from the saved state file closest to the selected date/time. If no state file before the selected date/time is found, then VTScada will transfer all data from the beginning. Once the historian is caught up, normal sync will resume.

Transmissions are stopped if the application stops or restarts or if the Data Diode Publisher Stop button is used.

Data Diode Publisher Statistics Dialog

The Show Stats button will display the following information about a Data Diode Publisher tag.

The statistic dialogs shows current information about the Data Diode Publisher tag.

Sync Status Indicator Widget

The Sync Status Indicator widget is used to monitor the status of the Data Diode Client tag in the client application of the Data Diode configuration. This widget is often paired with a Comm Indicator and the Historian Status widget to monitor the status of the Data Diode Client tag. The widget will display its normal color (default green) with the caption "In Sync" unless an error is detected.

This widget will display a normal status unless an error is detected.

An example of the Sync Status Indicator widget in its default state.

Data Diode Client Statistics Dialog

The Show Stats button will display the following information about a Data Diode Client tag.

This statistics dialog shows a lot of information about the Data Diode Client tag.

While not exclusively a Publisher tag-related widget, it is a best practice to use a Historian Status Widget on the secured publisher application and the client application.
You can monitor the operational status of all of the Historian tags in your application using the Historian Status widget. Many developers choose to create a page that is dedicated to monitoring the state of their application. The Historian Status widget is usually placed in a prominent location on such a page. You can find this widget in the palette folder: Analytics >> Trends & Historical Data


Sync Status Indicator Widget

Used by: Data Diode Client tag

* Does not use the Style Settings tag.

The Sync Status Indicator widget is used to monitor the status of the Data Diode Client tag in the client application of the Data Diode configuration. This widget is often paired with a Comm Indicator and the Historian Status widget to monitor the status of the Data Diode Client tag. The widget will display its normal color (default green) with the caption "In Sync" unless an error is detected.

This widget will display a normal status unless an error is detected.

An example of the Sync Status Indicator widget in its default state.

If an error is detected (for example, records are receivedout of order or records are missing) the indicator will change to the error color (default red) and display timestamps indicating when the missing data was detected and the last time data was in sync.

An example of the Sync Status Indicator widget in an error state.

The properties dialog for Client Sync Status Indicator:

Link a tag, change the status colors or disable some options in the properties menu.

Normal Color

The color to display when the associated Data Diode Client tag is under normal conditions.

Error Color

The color to display when an error is detected (for example, records are missing).

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Related information:

Data Diode Client Tag

Comm Indicator Widget

Historian Status Widget


Data Diode Start Button Widget

Starts transmitting outstanding data from the historian to the data diode. The application will resume from the last known transmission and will continue to transmit live information as it becomes available. The transmissions will stop if the Data Diode Publisher Stop button is used or if the publishing application stops.

This start button widget is configured on the secure Data Diode publishing application. It is linked to the Data Diode Publisher tag.

The properties dialog for the Data Diode Start Button widget:

If "Reset Published State" is clicked in the settings tab of the Data Diode Publisher tag properties (from the tag browser), then the application will "forget" the last stopped time and will start from the very beginning. Think very carefully before resetting the published state.

Tag

Select a Data Diode Publisher tag

Start Options

  • Start since last stopped time - Starts transmission from last known transmission (Default)

  • Start from calendar date (UTC) - Clicking will open a calendar and allow you to select a date. Transmissions will begin from the selected date until present and continue to transmit live data. Selecting this option will transform your widget into Data Diode Start From Date/Time Button

Button Label

The label should always tell the operator what to expect to happen when they click the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Font

Select a style tag for the button label font

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls


Data Diode Start From Date/Time Button

Clicking this button opens a dialog to set the time (UTC) and the date. Click the calendar icon to open a calendar tool for selecting the date. Start from Date/Time will start from the saved state file closest to the selected date/time. If no state file before the selected date/time is found, then VTScada will transfer all data from the beginning. Once the historian is caught up, normal sync will resume.

Transmissions are stopped if the application stops or restarts or if the Data Diode Publisher Stop button is used.

This start button widget is configured on the secure Data Diode publishing application. It is linked to the Data Diode Publisher tag. The date/time dialog will appear as follows:

The properties dialog for the Data Diode Start From Date/Time Button widget:

Tag

Select a Data Diode Publisher tag

Start Options

  • Start since last stopped time - Starts transmission from last known transmission. Selecting this option will transform your widget into a Data Diode Start Button Widget

  • Start from calendar date/time (UTC) - Clicking will open a dialog allowing you to select a date and time (UTC). Transmissions will begin from the selected date until present and continue to transmit live data. (Default)

Button Label

The label should always tell the operator what to expect to happen when they click the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Font

Select a style tag for the button label font

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls


Data Diode Stop Button Widget

This button will stop VTScada from transmitting data from the historian to the Data Diode. This button will remain disabled unless a transmission is underway.

This widget is one of a set of widgets used to start, stop and monitor Data Diode transmissions.

The properties dialog for the Data Diode Stop Button widget:

Link a publisher tag, change the button label and disable some default options

Tag

Select a Data Diode Publisher tag

Button Label

The label should always tell the operator what to expect to happen when they click the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Font

Select a style tag for the button label font

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls


Date Time Selector

Used by: Data Entry Forms and Reports

This widget is used to select a date and time (timestamp) for:

  • A form
  • The start time of a report
  • The end time of a report

Click anywhere on the widget to open a dialog with an interactive date and time selector.

The properties dialog for the Date Time Selector widget:

Select a font tag or specify the default time preset.

Font

Controls the display characteristics of the Date Time Selector, but not within the dialog.

Preset time to start of

A droplist with several options for the default Date Time Selector time. The options are as follows:

  • This hour - The current hour

  • This day - The current day

  • This week - The current week

  • This month - The current month

  • This year - The current year

  • Last hour - The previous hour

  • Last day - The previous day

  • Last week - The previous week

  • Last month - The previous month

  • Last year - The previous year

  • Now - The current time

Value to Set

Specify whether this widget is intended to be part of a form or for reports.

  • Form Timestamp - The widget is part of a form (and will work with other form widgets on the same page)
    If no Date Time Selector widget is present, the values entered into a form will be logged with the current time as the timestamp.
    If the Date Time Selector widget is set to the current time, the offsets from the form widgets will not apply. There is no recording of future events.
    If a Date Time Selector is present, the values will be logged with the time set on the Date Time Selector. (A event will be recorded at the current time that a form was submitted for the timestamped time.)
    If Time Offset and Time Unit settings are specified, the timestamp will be calculated as:
Date Time Selector's timestamp + (Time Offset × Time Unit)

For example, if a Numeric Entry has a Time Offset of 15 minutes and the Date Time Selector is set to 11:00 AM, the Numeric Entry's value will be logged at 11:15 AM.

  • Report Start Time - select the start time for a report.
  • Report End Time - select the last timestamp to appear in a report.
    If the report runs for a duration of 8 hours, and the Report End Time is 6PM, the timespan of the report will be 10AM to 6PM.

Date Only

When in Date Only mode, only the date will be displayed on the widget. When the widget is clicked, it will open directly to the calendar.

Time of Day

Enabled when in Date Only mode. Date Only mode will only display the date on the widget and opens a date picker. Time of Day gives you the option to specify a time of day.

When set, it will override the "Preset time to start of" option, and add Time of Day to the selected date as an offset.

Adjust for DST

Enabled when in Date Only mode and with a Time of Day specified. Adjust for DST is checked by default.

When the Adjust for DST is selected, the Time of Day of the complete timestamp will be the same, every day of the year, despite any DST adjusted that are made.

For example, if the Time of Day is 6am (i.e. an offset of 6 hours), on the day of a negative time change, where an offset of 6 hours would result in a timestamp of 5am, we will adjust the offset to be 7 hours to maintain the same timestamp.

If Adjust for DST is deselected, the timestamp will be off on DST transition days.

For most use cases, the Adjust for DST option should always be selected. It should only be deselected if the number of hours from midnight is more significant than the timestamp.

Related information:

Numeric Entry Widget

String Entry Widget

Droplist Widget

Checkbox Switch Widget

Form Reset Button Widget

Clear Button Widget

Submit Button Widget


DFS Station Draw

Used by: DFS Station RTU tag

The Data Flow Station Draw tag widget is used to create a button that an operator may click to view information about the modules that have been installed at the physical RTU being represented by the associated tag. The contents of this window will vary according to the station's installed modules.

The properties dialog for the widget. As shown, the only configurable options are to disable tooltips and the context menu.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Equipment\Lift Stations\Data Flow Systems

Related information:

Choices for Operator Interaction


Draw Widget

Used by: Data Flow RTU, Analog Status, Digital Status, Pump Status, Data Flow Pulse Input.

* Can use properties from a Style Settings tag.

The Draw tag widget is used to display a bordered field containing the description of the associated tag on the left, and its value to the right. The description and the border are optional.

If the associated tag type includes an alarm setup then orange dots will appear in the object to indicate that one or both alarms are either not configured or not enabled. For tag types that have both high and low alarms as part of their definition, the upper and lower squares refer to the high and low alarms in that order.

The properties dialog for the Draw widget is as shown:

Font

Select one of the font tags (or parameter linked to a font tag) that you with to use to display the text. The display will use the default system font if you do not select a font tag.

The parameters button is enabled only if the tag is drawn on a page that includes a font parameter, or if the tag is part of a widget and the associated widget editor is open.

Style Settings

Defaults to the System Style tag if no other is selected. This sets the color for the alarm indications. The widget does not use Analog or Digital colors from the style tag.

Digits After Decimal

Controls how many decimal places will be shown in the display. Values will be rounded to the number set here.

Show Units

Controls whether the tag’s engineering units (if set) will be shown as part of the display.

Type of Border

Select whether to display the tag name as well as its value (the Button option) or simply the tag’s value (the No Button option).

Colors (Background)

Opens the Select Color Dialog from which you can choose a color to display as the background to the tag’s value.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Inputs & Outputs\Digital Status

Tag Types\Inputs & Outputs\Analog Status

Tag Types\Inputs & Outputs\Pump Status

Related information:

Choices for Operator Interaction


Draw HDV Widget

* Does not use the Style Settings tag.

Add a scalable view of the Historical Data Viewer to any page as a widget. This widget is designed to be linked to a parent tag, which may be either a Context, or a user-defined type that was created from a Context tag. Alternatively, you may select an existing pen group for it to display.

After adding this widget to a page, the properties dialog allows you to select a pen group but not a tag or other data source. Use the Widget Properties ribbon or the right-click menu to link this widget to a parent tag.
After linking this widget to a tag, there is no way to return to selecting a pen group instead. Replace the widget with a fresh copy.

If linking to a parent tag (Context or user-created type), use the widget's properties dialog to select the child tags that should be included in the plot. You can also configure the appearance of the HDV, including title bar, time selector (footer bar), colors and more. A useful technique is to add the DrawHDV widget to a parameterized page, linking the widget to a page parameter of type, tag. Menu entries or page hotboxes are then configured to use different instances of the user-created tag type when opening the page.

Components of the HDV including the toolbar, legend, and scales may be configured to be hidden or displayed as required.

If running a legacy application (created with 11.0 or earlier), user-created tag types will not link to a Draw HDV widget without additional code. Refer to Moving to the Current Version.

Procedure for use:

  1. Add the Draw HDV Widget to a page.
  2. Link the widget to a context tag or user-defined type, containing the tags to be plotted.
  3. Open the Properties dialog of the Draw HDV Widget.
  4. Open the Tag Selector.
  5. Select child tags and add queries if necessary. Click OK.
  6. Adjust other display options as required.

The legend grid and the divider between the legend and the graph can be adjusted only in the live view, not in the Idea Studio.

  • You can left-click on the graph to add value labels.
  • You can open a properties menu for each pen.
  • The full controls of the HDV window are not shown by default, but may be added using options in the widget's properties dialog.

The properties dialog for the Draw HDV will vary, depending on whether it is linked to a type or using a named pen group.

Linked to a type.

Using a pen group

Access to the Tag Selector (Select Pens (Tags) to Plot) is available only when the widget is linked to a parent tag.

Time Range Mode

Display a fixed time range on the DrawHDV widget. Select a "Custom" time span to enable time range mode. This will enable you to select a start time and end time in the widget property dialog and will enable "Show Elapsed Time" as a plot option.

In time range mode, you can zoom in and drag the plot as usual, however, you cannot scroll past the end time or before the start time.

The plot option "Show Elapsed Time" is TRUE by default in time range mode. Toggle this option to switch between plotting the x-axis with time elapsed or with time stamps.

The time range can be set by any of the following:

Timestamp

Click the "Set Date and Time" button to access calendar controls that you can use to set specific start and end times.

Note that these are absolute values that can be changed only be re-configuring the widget. For relative values that will update based on user-specified parameters select one of the following options.

Tag Value, Parameter, Linked Tag Property, Expression

These are advanced configuration options. Whichever option you select, it must be configured to supply UTC values for the start and end times. These are likely to be relative to whenever the report is run and therefore you will need to write an expression to calculate those UTC values. Look first to the TimeUtils library for a way to generate the boundary times. If that library does not provide the time range you require, refer to notes in the section Time and Date Functions in Expressions.

Tag (If linked to a tag)

The selected context or type, if not using a pen group.

Child Tags (If linked to a tag)

If using a linked tag rather than a named group. The list of child tags of the selected parent that could be plotted, but have not yet been selected.

Selected Tags (If linked to a tag)

If using a linked tag rather than a named group. The list of tags that have been selected to be shown in the HDV widget.

Group (If not linked to a tag)

Select an existing pen group to display.

Time Span

Select the length of time to display in the HDV. Options match those in the full HDV page, ranging from one second to five years.

Text Size

Choose between five sizes of font for the scale labels. Sizes range from small to extra large where each size is two points larger than the last.

You also have the option of allowing the widget to remember and use the last user-selected font size rather than defining a default size.

Show Toolbar

When selected, the full set of HDV tools will be displayed across the top of the widget. The toolbar does not scale, therefore if the widget is not wide enough to show all the buttons, those on the right will be lost.

Show Time Selection

When selected, the HDV's time scroll bar will be added between the graph and the legend.

Views: Plot View, Grid View & Notes

Control whether the widget can display the Plot View, the Grid View, and the Notes view. If more than one is selected, choose which view should be shown by default when the page is opened.

Background Color and Tab Text Color

Sets the background and tab-text colors of the overall widget. (Plot, grid and other text colors are set in the following section.)

Plot View Options

Options as shown to control what will be included in the plot view of the HDV display, including:

  • Choice of color for the background, grid lines and numeric scale. The "X" beside the color choice will reset each value to the default color.
  • Options to display the legend, tag scales, time scales, stacked plots.
  • Option to display a full legend including statistics or simplified legend of tag identification and values only.
  • Option to show the time cursor (vertical line following the pointer).
  • Option to minimize the legend height. When selected, the legend will be no taller than required to show the list of pens, up to a maximum of 50% of the widget height.
  • Option to plot x-axis with time elapsed or time stamps. Only enabled in Time Range mode. In Time Range mode, show elapsed time is TRUE by default.

Grid View Options

Options to control what what will be visible, and what the default settings will be when an operator views the grid. If the toolbar option is not provided, then the default settings will be the only view possible in the grid.

  • Option to show the newest value at the top (or at the bottom if not selected).
  • Select between data retrieval modes, raw values, averages, minimums or maximums.
  • For all data retrieval modes other than raw values, set the time per record (row) for each average, minimum or maximum.
  • Choose colors for the cell background and the grid lines.
    Removing each will result in the default colors being used.

Notes View Options

Choose from the following options of what will be included in the notes tab and how it will be shown.

  • Sort by either the note's original time stamp or date of most recent comment (update) added to the note.
  • Option to display either the date and time when the notes were created, or the age of the note.
  • Choose colors for the text and background.

Widget Folders:

Analytics\Trends & Historical Data

Tools\Standard Library

Tag Types\Organization/Containers\Context

Related information:

Historical Data Viewer (HDV) - Operator's Guide to the Historical Data Viewer.

Operator Notes Page - General information about Operator notes.

HDV Button Widget - Draw a button that will open a customized HDV window.

HDV Hotbox Widget - Draw a hotbox that will open a customized HDV window.

Plot Data Widget - Draw an HDV widget that is linked to a single tag.

File Management Tools - Reference: importing file changes.


Draw Text Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Counter, Deadband Control, History Statistics, Linear Legend, Rate of Change, Script Tag, Selector Switch, Totalizer, SQL Logger.

* Does not use the Style Settings tag.

The Draw Text widget is used to display the current value of any of a tag as text. Units (if any) will not be displayed and numeric values will display either 0 or 8 decimal points with no option for user-configuration. If you require just one decimal points of accuracy, or if you would like to display the engineering units that the value represents, then the Numeric Value Widget will be a better choice.

The properties dialog for the Draw Text object:

Reference: Advanced Formatting: Options for Properties

Display Options

Font

Select one of the font tags (or parameter linked to a font tag) that you wish to use to display the text. The display will use the default system font if you do not select a font tag.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Horizontal Alignment

Sets the position of the text within the display area. You may select left-aligned, right-aligned or centered. To align the display area itself with other elements on the page, see: Alignment and Positioning Tools.

Vertical Alignment

Sets the position of the text within the display area. You may select top-aligned, bottom-aligned or centered. To align the overall widget with other elements on the page, see Align.

Horizontal and Vertical Alignment may be represented as an expression with a value of 0, 1 or 2.
0 = Left or Top
1 = Center
2 = Right or Bottom

Colors

Colors (Text, Background, and Outline)

Opens the Select Color Dialog from which you can select the color of the text (defaults to black), the background (defaults to transparent), and the outline (defaults to transparent).

Outline

Opens the Select Color Dialog, from which you can select a color to use for the widget outline. Defaults to transparent.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Text\

Related information:

Choices for Operator Interaction


DriverSelect Widget

Used by: DriverMux (driver multiplexer) tag.

* Does not use the Style Settings tag.

The DriverSelect widget is used to provide operators with a means to select one of the configured drivers to use exclusively, or to allow the DriverMUX tag to work automatically.

The properties dialog to configure the Driver Select widget is as follows:

Label for 1st, 2nd and 3rd radio buttons

The function of each radio button is defined within the widget. The default labels describe these functions well, but you may choose to use your own labels for each.

Show bevel around radio buttons

Adds a decorative edge to the cluster of three buttons. When the bevel is shown, you may also add a title.

Bevel title

Available only when the bevel is shown around the radio button cluster. If you have more than one DriverMux tag in your application, it would be appropriate to make the title describe which is being affected by the operator’s choices.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Driver Multiplexer\

Tag Types\Communications\Link Management\Driver Multiplexer\

Related information:

Choices for Operator Interaction


Droplist Widget

Formerly, the String Droplist Widget. This has been updated and replaces the older Droplist Control Widget (Legacy version)

Used by: I/O and Calculations, Analog Input, Analog Output, Analog Status, Analog Control, String I/O Tag

The Droplist widget can write an operator-selected value from a defined list to an output device. The write occurs when a value is selected in the list. Use of the confirmation dialog is suggested.

If the linked tag's Questionable Data flag is set, a question mark will be shown before every item in the list.

When displaying Memory Tags that are configured to allow the value to be cleared, the first entry will be "No Data", having a value of "Invalid".

The value matching each label can be text or numeric. Use care to define only values that are appropriate.

Values for each label can be set within the widget's properties dialog, or if the tag has an equipment type, you can set the values within the matching Style Settings properties: Equipment tab

The properties dialog for the Droplist widget:

This widget has a wide range of settings for its appearance and behaviour.

Use Tag Equipment Type Labels

When selected, both labels and values are provided by the equipment type matching the linked tag. These must be configured in the selected Style Settings properties: Equipment tab

Label and Value

The list of possible values, and the label that is associated with each value. Values may be text or numeric. If numeric, there is no requirement that values must be consecutive. (Values of 10, 20, 30 are as valid as 1, 2, 3.) Scaling in your output tag will limit the range of possible values.

You cannot use tags or expressions to create dynamically-assigned values.

Use the tools below the list to create or edit the values and labels. You can also double-click an entry to open it for editing. When creating a list of similar values, you may find it easier to copy and edit entries than to create each individually.

Display

Title

Provide text that will tell the operator what to use this Droplist field for.

Style

Linked to the System Style Settings tag by default. Needed if you choose the option, Use Tag Equipment Type Labels. (See following notes.)

Font

Controls the display characteristics of the data entry field, but not the label. If you set individual characteristics using the Format ribbon, this will be an expression, combining those characteristics. Otherwise, select a font tag.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Mismatch Color

If the driver supports read and write operations at the same address, then when the last value written does not match the value being read, the widget will display the configured mismatch color.

Align Title

Choose whether the title should be included in the vertical alignment calculation. For example, if vertical alignment is top-aligned and the align title option is not selected then the title will extend above the widget's bounding box.

Draw Bevel

Select whether the completed object should be drawn with a beveled border. If the Draw Bevel check box is selected, the completed object will be drawn with a border surrounding it.

Write Blank as Invalid

Do not select when the control writes to a PLC or RTU. This option may be used when required by a Recipe Parameter Tag

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Forms

Include in Form

Select if this widget is to be included in a data entry form. If selected, this widget will interact with the submit, clear and date time selector widgets.

Time Offset

A numeric value that specifies the quantity of time offset. A time offset is added to a date selector offset. A 15 minute offset applied to an 11:00 AM submission will be recorded as 11:15 AM.

Time Units

A droplist that specifies the unit of time offset in minutes, hours, days or weeks.

Related information:

Checkbox Switch Widget

Numeric Value Widget

String Entry Widget

Date Time Selector

Submit Button Widget

Droplist Widget

String Entry Widget

Choices for Operator Interaction

Widget Folders:

Analog Controls\

Text\

Tools\Forms\


Droplist Control Widget (Legacy version)

Support will continue for existing applications, but this widget is not available for use in new applications.

Used by: I/O and Calculations, Analog Input, Analog Status, Analog Output, Analog Control, Selector Switch.

* Does not use the Style Settings tag.

The Droplist Control widget creates a drop-down list from which operators can select discrete values to output. (0 to 31)

Regardless of the text used for each label, output values are integers beginning with 0 and increasing to the largest configured value, up to 31. The example shown here assumes that the underlying control will set the motor speed to 250 when a value of 1 is sent, 500 when a value of 2 is sent and so on.

The properties dialog for the control will appear similar to the following. Note that the control will always output values up to the largest text value configured. Should you skip one of the Text To Display boxes, that value will still be included in the drop list, but will display nothing to tell operators what it is.

The source of the text for each entry in the drop list may be any of: text, a tag value, the value of a selected parameter, or an expression.

Title

Sets the title, should you wish to include one above the drop-down list. Enabled whether the bevel is drawn or not.

Draw Bevel

Encloses the drop down in a beveled rectangle when selected. The example shown at the beginning of this topic uses a title and bevel.

Sort Displayed List

Sort the list alphabetically by label. Output values stay with their title and therefore, are likely to be in a scrambled order after the list is sorted.

Text to Display n

Sets the text to display for each output value, n. The number of items in the list is controlled by the largest value for which the Text to Display field has been configured.

Sort Alphabetically

When selected, the droplist will be reorganized into alphabetic order by text for the output values, rather than being ordered by output value.

Confirmation Dialog

When selected, the operator will be prompted to confirm the control action.

Mismatch Color

Used only when the associated tag is a Selector Switch, or an Analog Input or Analog Status type, configured to write values. When the last value written does not match the value being read, the widget will display the configured mismatch color.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analog controls\

Related information:

Choices for Operator Interaction

Droplist Widget


Duplexes Widget

Deprecated. Available only in applications that use the legacy VTScada layer.

Used by: DataFlow RTU.

* Does not use the Style Settings tag.

The Duplexes tag widget is used to configure a display of the status of all equipment associated with a Data Flow RTU. The completed Duplexes widget shows an image of two pumps in a well, along with a series of data fields, control buttons and an alarm panel that shows critical information about the duplex station.

The properties dialog for a Duplexes widget:

Note: Each field in the Duplexes properties dialog displays only the tags that are associated with the Data Flow RTU tag being drawn.

Pump 1 Running Indicator

Used to associate with this Data Flow RTU tag with the Pump Status tag responsible for reading the status of the first pump belonging to this station.

Pump 1 Hand Mode Indicator

Used to select the Digital Status tag responsible for reading the manual mode (hand) of the first pump belonging to this station.. This feature pre-dates the VTScada selector switch. Each mode of the H-O-A switch in the Duplexes widget is represented by a separate Digital Status tag, all of which must be configured such that only one may be TRUE at a time.

Pump 1 Auto Mode Indicator

Used to select the Digital Status tag responsible for reading the auto mode of the first pump belonging to this station.

Pump 1 Forced On Indicator

Used to select the Digital Status tag responsible for reading the forced on mode of the first pump belonging to this station.

Pump 1 Forced Off Indicator

Used to select the Digital Status tag responsible for reading the forced off mode of the first pump belonging to this station.

Pump 1 Force On Control

Used to select the Digital Status tag responsible for setting the forced on mode of the first pump belonging to this station.

Pump 1 Force Off Control

Used to select the Digital Status tag responsible for setting the forced off mode of the first pump belonging to this station.

Pump 1 Amps

Select the Analog Status tag responsible for reading the Amps for this station.

Well Level

Select the Analog Status tag responsible for reading the level of the well for this station.

Pump 2 Running

Select the Pump Status tag responsible for reading the status of the second pump belonging to this station.

Pump 2 Hand Mode Indicator

Select the Digital Status tag responsible for reading the manual mode of the second pump belonging to this station.

Pump 2 Auto Mode Indicator

Select the Digital Status tag responsible for reading the auto mode of the second pump belonging to this station.

Pump 2 Forced On Indicator

Select the Digital Status tag responsible for reading the forced on mode of the second pump belonging to this station.

Pump 2 Forced Off Indicator

Select the Digital Status tag responsible for reading the forced off mode of the second pump belonging to this station.

Pump 2 Force On Control

Used to select the Digital Status tag responsible for setting the forced on mode of the second pump belonging to this station.

Pump 2 Force Off Control

Used to select the Digital Status tag responsible for setting the forced off mode of the second pump belonging to this station.

Pump 2 Amps

Select the Analog Status tag responsible for reading the Amps for the second pump belonging to this station.

Station Flow

Select the Analog Status tag responsible for reading the total flow for the station.

Widget Folders:

-- none --


Duration Selector

Select the default time duration for a report.

A button displaying the currently selected duration and a time selector icon

Clicking the widget on the page will open a dialog that allows you to enter a number and select a unit of time.

Enter a value in the numeric field and select a unit of time from the dropdown.

The properties dialog for the Duration Selector:

Font

Controls the display characteristics of the Date Time Selector, but not within the dialog.

Default Value

Set the default numeric value and unit of time for the Duration Selector.

Available Units

You can choose to only show select units of time in the Duration Selector dialog. If none are checked, they will all appear. If some are checked, only the checked units will appear.

Related information:

The Report Studio

Report Tags


Edit Property Checkbox

Not linked to any tag.

* Does not use the Style Settings tag.

The Edit Property Checkbox widget provides a way for operators to switch a specific property on and off. You choose which property can be edited when configuring the widget. These widgets can allow access to certain properties that need to be updated, without granting operators full access to the Application Properties dialog.

If the property can have values other than zero and one, use the Edit Property Field widget.

If the property is changed elsewhere, this widget will not refresh until the page is reloaded.

The properties dialog for the Edit Property Checkbox widget:

Section

Application properties are organized by section. Properties that are placed in the wrong section will have no effect. The majority of properties that you are likely to use will be in the System section, but always confirm this before proceeding.

Variable

The name of the property that can be changed using this field.

Label

Should describe this edit property field to the operator.

Box on Left and Alignment

Use these options to obtain the best appearance on a page.

Data Type

Restricts the values that the operator can provide. Must match the value type required by the configured variable.

Properties from the OEM layer that require a restart will be copied to the application incorrectly unless you manually add that property to the local .Startup file before first using the property-setting widget. To manually add a property, go to the Application Configuration > Edit Properties (Advanced Mode). Find and copy (not insert) the property to your application.

Widget Folders:

Basic Components\Specialty\Settings Editing\

Tools\Standard Library\

Related information:

Edit Property Field

Property Reference


Edit Property Field

Not linked to any tag.

* Does not use the Style Settings tag.

The Edit Property widget is used to allow operators to change an application property value. You choose which property can be edited when configuring the widget. These widgets can allow access to certain properties that need to be updated, without granting operators full access to the Application Properties dialog.

If the property can have values of only zero and one, use the Edit Property Checkbox widget.

If the property is changed elsewhere, this widget will not refresh until the page is reloaded.

The properties dialog for the Edit Property Field widget:

Section

Application properties are organized by section. Properties that are placed in the wrong section will have no effect. The majority of properties that you are likely to use will be in the System section, but always confirm this before proceeding.

Variable

The name of the property that can be changed using this field.

Title

Should describe this edit property field to the operator.

View & Vertical Alignment

In most cases, properties that are not immediately available for editing will be shown as gray. You may override this to either make the field invisible, or to force the property to appear normal even though it cannot be changed.

Use the vertical alignment options to obtain the best appearance on a page.

Data Type

Restricts the values that the operator can provide. Must match the value type required by the configured variable.

Minimum and Maximum Values

If the data type is numeric, these restrict the range of values that the operator can provide.

If the data type is text, these restrict the number of characters that may be typed.

Bevel, Title and Focus ID

Use Bevel and Title to improve the appearance of the field.

You can disable a control widget by setting its Focus ID value to zero. The widget will remain visible, but faded.

Properties from the OEM layer that require a restart will be copied to the application incorrectly unless you manually add that property to the local .Startup file before first using the property-setting widget. To manually add a property, go to the Application Configuration > Edit Properties (Advanced Mode). Find and copy (not insert) the property to your application.

Widget Folders:

Basic Components\Specialty\Settings Editing\

Tools\Standard Library\

Related information:

Edit Property Checkbox

Property Reference


Elapsed Time Widget

Used by: Totalizer.

* Does not use the Style Settings tag.

The Elapsed Time widget is used to display the current value of a Totalizer tag using a time format in hours : minutes : seconds.

The "Elapsed Time" widget will only show "time that has elapsed" or "time that the equipment has been running" if that is what the totalizer is counting. To do this, the source for the totalizer must be a tag whose value is 1 when the equipment is on and 0 when the equipment is off.

A Totalizer tag that is accumulating a value such as total flow does not also track its running time. The elapsed time widget cannot show information that is not being collected.

The properties dialog for the Elapsed Time widget will appear as shown:

Font

Select one of the font tags (or parameter linked to a font tag) that you with to use to display the text. The display will use the default system font if you do not select a font tag.

The parameters button is enabled only if the tag is drawn on a page that includes a font parameter, or if the tag is part of a widget and the associated widget editor is open.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Horizontal Alignment

Sets the position of the text within the display area. You may select left-aligned, right-aligned or centered. To align the display area itself with other elements on the page, see: Alignment and Positioning Tools.

Type of Border

Examples of the three border types are shown at the beginning of this topic.

Colors (Text and Background)

Opens the Select Color Dialog from which you can select the color of the text.

The background color against which the text will be displayed can also be defined.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Text\

Analytics\Statistics\

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


Enable Polling Checkbox Widget

Used by: Polling Driver, DataFlow Systems RTU

* Does not use the Style Settings tag.

Use this widget to give operators the ability to enable or disable polling without needing to open the Polling Driver's properties dialog. Operators must possess either the Modify Tags privilege or the Manual Data privilege to change this setting.

While polling is disabled, no communication will be sent or received through the station. To switch from a timed poll to continuous communication, use the Fast Poll option of the Polling Driver.

The properties dialog for the Enable Polling Checkbox object:

Label

Defaults to "Enable Polling". You may provide any text or expression you prefer.

Box on Left

Controls whether the check box will be displayed to the left or the right of the label.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Communications\Link Management\Polling Driver

Related information:

Toggle Polling Button Widget

Choices for Operator Interaction


Equipment / Status Color Indicator

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm, Alarm Status, Analog Control, Analog Input, Analog Output, Analog Status, Calculation, Counter, Deadband, Digital Control, Digital Input, Digital Control, Digital Status, Function, History Statistics, Modem, Network Status, Pump Status, Rate of Change, Roster, Selector Switch, Serial Port, SMS Appliance, SQL Logger, TCP/IP Port, Totalizer, Trigger, UDP/IP Port,

Status color indicators can be found in the folders Equipment, Indicators >> Basic, and High Performance. These are images of equipment or ISA symbols that take their color from a Style Settings tag. You can choose whether the indicator should use the style for Digitals, High Performance, or an Equipment type.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

The properties dialog for a Status Color Indicator widget:

Style

Optionally, select a Style Settings tag to control the colors shown by the light, in response to the linked tag's value and alarm state. See: Style Settings Tags

For Digital and Discrete I/O tags, use the following guide:

* If the linked tag has an Equipment Type and the Style has a definition for that type, then those colors and labels are used.
* Otherwise (at least for Digitals), the colors for the data type are used.

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Equipment

High Performance

Indicators\Basic Indicators\

Related information:

Style Settings Tags

Choices for Operator Interaction


Execute / Cancel Button Widget

This button appears in the Widgets palette as both an Execute Button and a Cancel Button. They are the same.

Used by: I/O and Calculations (all data types). For other output tag types, use the Legacy Set Value Button, which incorporates an Execute / Cancel option.

* Does not use the Style Settings tag.

The Execute / Cancel Button widget is used in combination with either a Set Value Button Widget or a Numeric Entry Widget when that widget's confirmation option is configured to Set Before Execute. This button must be linked to the same I/O tag as the Set Value button or Numeric Entry widget, and that tag must be configured to write.

The exception is if the Set Value uses a separate Feedback tag, in which case this button must be linked to that feedback tag. Refer to the configuration example in the topic, Set Value Button Widget.

A configuration example is provided in the topic, Set Value Button Widget.

The properties dialog for the Execute / Cancel Button widget:

Function

Choose between Execute and Cancel

Label

Optional text to be displayed on the button.

Font

Select a Font tag that sets the display characteristics of the label.

Image File

Optional path and filename to an image that will be shown on the button. The path must be relative to the application's folder; for example: "Bitmaps\MyIcons\Execute.png".

If both a label and an image are specified, the image will appear to the left of the label. If there is no label, the image will be centered on the button.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Buttons & Switches

Buttons & Switches\Basic Controls


Export Comm Log Widget

Not linked to any tag.

* Does not use the Style Settings tag.

This widget is useful only to gather diagnostic information, usually when troubleshooting an issue with Trihedral's technical support team.

The Export Comm Log Widget is a button that users can press to export communication log files instantly rather than waiting for a time or numeric limit to trigger the write.

The action triggered by this widget applies only to communication modules for the Alarm Notification System including the voice modem Call Manager, SMS Appliances, Twilio and VoIP. Other modules that generate log or trace files are not affected.

When a user triggers an export, an empty record will be added to the end of any communication trace files in use by the application (application or system as selected). A message similar to "Force Trace File Generation" will be associated with the new record. All diagnostic information currently in memory will be transferred to the trace files.

Advanced users can perform the same action using the Source Debugger. The button is far more convenient for most users.

The properties dialog for an Export Comm Log Button widget:

At least one of App Logs or System Logs must be selected or else this button will have no effect. Refer to the following notes.

Label

Text to display on the button. Defaults to "Comm Log".

Font

The font used to display the label. Defaults to the current system font.

App Logs

When selected, logs generated by the application are flushed to the relevant trace files.

This includes Twilio, SMSAppliance and CallManager but not VoIP.

System Logs

When selected, logs generated by the system are flushed to the relevant trace files.

This includes VoIP but not Twilio, SMSAppliance and CallManager.

Widget Folders:

Analytics\Diagnostics


Fast Scan Widget

Used by: Data Flow RTU, Polling Driver.

* Does not use the Style Settings tag.

The Fast Scan Immediately option does not work with a Mobile Internet Thin Client (MIC)

The Fast Scan widget is used to draw a button that the operator can use to control the poll rate for the associated station. The following example shows a polling driver site draw below the fast scan button. A green outer ring in the site draw indicates normal polling while a blue outer ring indicates that fast scan mode has been enabled.

There are two ways you may choose to use the Fast Scan tag widget:

  • Configure the completed Fast Scan button as a toggle button that switches between fast poll mode and normal poll mode each time it is clicked. (As shown in the above example.)
  • Draw two instances of the Fast Scan widget: The first as a button that can be clicked to put the station in fast poll mode and the second as a button that can be clicked to put the station in normal poll mode.

An example of the properties dialog for the fast scan widget follows:

Active Label

Enter the label that should appear on the completed button while the associated station is being fast-polled.

Note that the label will not be displayed if the button visibility option is not selected.

Inactive Label

Enter the label that should appear when the associated station is not being fast polled. This option only applies if the Button Visibility check box has been selected.

Enable / Disable / Toggle When Pressed

This set of options controls how the button will function. If you want to draw two buttons: one to enable fast polling and one to disable it, then select Enable for the first instance and disable for the second. If you would like to draw a single button that toggles fast polling on and off, select the Toggle When Pressed option.

Button Visibility

When selected, the button and label will be visible. When not selected, the area occupied by the widget will be replaced with a hotbox, similar to the page change hotbox, visible only when the cursor is located within it.

Because the hotbox version of this button does not include a descriptive label and is not visible when the mouse is not above, it should be placed relative to a label or other screen object so that the operator can find it and will understand its function.

Fast Scan Immediately

Select this option to indicate that you wish the associated RTU to be polled in fast scan mode immediately when this object is displayed. That is, when the page or dialog upon which this object is placed has been opened.

If the Fast Scan Immediately check box is not selected, the completed object must be clicked in order for the fast poll to occur.

Stop When Not Displayed

Often used in conjunction with the Fast Scan Immediately check box, this option can be selected if the associated RTU should immediately return to normal polling mode when the page or dialog box containing this button is closed.

It can also be used as a fail-safe, regardless of how the Fast Scan Immediately option is set, forcing polling to return to normal when the operator leaves the current page, regardless of whether they remembered to set normal polling first.

If the Stop When Not Displayed check box is not selected, the completed object will continue to be fast polled when the page or dialog upon which it has been drawn is closed. Fast polling will continue for the amount of time indicated in the Active Time (Seconds) field (see following).

Fast Scan Interval

Use this option to set the interval (in seconds) at which the RTU will be polled when placed into fast poll mode by the Fast Scan object.

Active Time

Enter the length of time (in seconds) that the RTU will remain in fast poll mode when placed in fast poll mode by the completed object. If the Stop When Not Displayed check box (see above) has been selected, fast poll mode will stop when the page or dialog that the completed object has been drawn on is closed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Analytics\Communications\Polling\

Related information:

Choices for Operator Interaction


Form Reset Button Widget

Used by: Data Entry Forms

This reset button is used with other form-related widgets. When clicked, this widget will reset every form entry enabled widget on the same page back to it's original value at the time of the associated timestamp. The reset button must be on the same page or pop-up as the enabled data-entry widgets.

The properties dialog for the Form Reset Button Widget:

Font

The font used to display the label. Defaults to the current system font.

Label

Text to display on the button. Defaults to "Reset".

Confirmation Dialog

If selected, the operator must confirm the action before all values are reset.

Related information:

Checkbox Switch Widget

Clear Button Widget

Numeric Value Widget

String Entry Widget

Droplist Widget

Date Time Selector

Submit Button Widget

Widget Folders:

Tools\Forms\


GI Poll Button

Used by: IEC 60870-5-104 driver

Requests a General Interrogation poll, which forces a connection to the PLC or RTU and requests that it send an update of all the data registers.

The IEC 60870-5-104 driver sends data on change, so if already connected, it can be assumed that VTScada is up-to-date. Pressing the button in this case will have no effect. This button is most often used for testing purposes.

The properties dialog for the GI Poll widget:

Tag

The Tag field displays the name and description of the IEC 60870-5-104 driver tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Button Label

Use to change the label displayed on the button. May be useful to specify which IEC 60870-5-104 driver will be polled when pressed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Related information:

IEC 60870-5-104 Driver


Glance Meter Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

The Glance widget represents the associated tag's value as a pointer needle within a bounding arc. There are no scales.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

The properties dialog for the Glance widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

The Tag field is only present when editing a completed widget object.

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Needle

The default image is ArrowNeedle, found in the image folder: Widget Parts >> Meter Parts >> Indicators >> Radial.

Minimum Angle & Maximum Angle

Sets the starting point and the ending point for the sweep of the arc. Defaults to 270 degrees for the start angle and 90 degrees for the end angle. The angle is measured in degrees, and increases in the clockwise direction.

Arc Width

Use to adjust the width of the arc. The width is measured from the outside edge towards the center.Values larger than 15 are not recommended.

The needle will scale in proportion to the available space within the arc.

Show Alarms

If selected, the arc will indicate the portion of the available range that would result in an alarm state, using the alarm color configured in the associated Style Settings tag.

If the linked tag is in an active alarm state, the needle will blink using the configured alarm color.

Show Alarms

If selected, values that are beyond the alarm setpoint will be shown using the designated color from the Style tag.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Glass Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Glass Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

The properties dialog for the Glass Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Gradient Color Change Widget

Maintained only for backward compatibility. Do not use in new applications.

The Gradient Color widget was used to overlay any graphic object with a wash of color so that when the associated tag's value changes from 0 to 1 (or any value greater than 0.5 in the case of analogs), the selected color range in the Gradient Color object superimposes itself over the object. Works only on the exact colors in the initial color range.

Example showing pipes in VTS 10.2. This will not work with pipes created in VTScada 11.0 or later.

If the object over which the Gradient Color object is layered is a solid color having an exact match to one of gradient's initial color range shades then the Gradient Color object washes the object with a solid color. If the underlying object is a pipe (created in a legacy application prior to release 11.0), the Gradient Color object will produce a multi-shaded color change.

The initial color range of the gradient color must match the object it is placed above in order for the final color to display. In the case of a pipe, any of the pipe’s shades will work for the gradient color’s initial range. (Note: although rare, this can present an odd situation in the case where one of the pipe shades matches the background of the page. The result is that the gradient color cannot distinguish between the pipe and the page and so will be displayed in its entirety.)

The properties dialog for the Gradient Color widget:

Initial Color Range

Opens the Select Color Dialog, from which you can choose a color matching the object that the Gradient Color will overlay. If the color you select matches any of the shades used for a color range, as used when drawing pipes, then both that color and the matching full color range will be used.

If the Initial Color does not match the overlaid object, the final color will not be shown.

Final Color Range

Opens the Select Color Range Dialog, from which you can choose the color that the overlaid object will turn when the tag associated with this widget has a value of 1.

If the overlaid object is a solid color, gradient color will also be a single color. In this case, the lightest color from the range will be used.

Disable Options

Disable selected operator-interaction features of this widget.

See:

Widget Folders:

None.

Maintained only for backward compatibility. Will not work in new applications.

Choices for Operator Interaction


Grundfos Custom Data Log Widget

* Does not use the Style Settings tag.

Used by: Grundfos CU36X Pump Controller Custom Data Log tag to display information collected by that tag. Data beyond Timestamp depends on configuration of your Grundfos controller.

The widget displays the custom data in a list. A drop-down menu, visible only after a completed read, allows you to select the custom log that you want to view. Options include flow in, height, pump run times, and more.

Use the Reload button to trigger the linked Custom Data Log tag's refresh-data sequence.

Use the Export button to save the displayed information to a CSV-formatted file. You will be prompted for a destination.

Press the keyboard sequence, Ctrl-C to copy the entire log to the Windows clipboard. This can be pasted to a spreadsheet or text file as tab-delimited data.

The properties dialog for the Event Log widget will look similar to the following:

Only two configuration options are available. You can adjust the color of the text and the background.

Widget Folders:

Drawing Tools\Widgets\Equipment\Lift Stations\Grundfos Dedicated Controls\

Drawing Tools\Widgets\Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\


Grundfos Event Log Widget

* Does not use the Style Settings tag.

Used by: Grundfos CU36X Pump Controller Event Log tag to display information collected by that tag.

The widget displays the event log data in a list.

Use the Reload button to trigger the linked Event Log tag's refresh-data sequence.

Use the Export button to save the displayed information to a CSV-formatted file. You will be prompted for a destination.

Use the Reset button to clear the event log. Visible only when there is data to reset.

Press the keyboard sequence, Ctrl-C to copy the entire log to the Windows clipboard. This can be pasted to a spreadsheet or text file as tab-delimited data.

The properties dialog for the Event Log widget will look similar to the following:

Only two configuration options are available. You can adjust the color of the text and the background.

Widget Folders:

Drawing Tools\Widgets\Equipment\Lift Stations\Grundfos Dedicated Controls\

Drawing Tools\Widgets\Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\


HDV Button Widget

Not linked to any tag.

* Does not use the Style Settings tag.

Create a button that opens an Historical Data Viewer window with a preselected set of tag values, over a preset time range. The HDV page that opens will include all of the standard tools for changing the tag selection, legend, time range and scale factor.

The properties dialog for the HDV Button widget:

Button Label

The default label is generic. You are advised to modify this to include more information about what will be included in the plot

If the label is to include an ampersand (&), enter two ampersands (&&).

Pen Group Selector

An existing pen group must be chosen, otherwise this button provides nothing more than a link to an empty HDV page.

Pen groups are created in the Historical Data Viewer page, using the Tag Selector dialog.

Duration Selector

Choose the length of time that will be shown initially when the HDV page opens.

Widget Folders:

Analytics\Trends & Historical Data\

Tools\Standard Library\

Related information:

Pen Groups - Save Tag Selections

Plot Data Widget

HDV Hotbox Widget

Draw HDV Widget

Historical Data Viewer (HDV) - Operator's Guide to the Historical Data Viewer


HDV Hotbox Widget

Not linked to any tag.

* Does not use the Style Settings tag.

Create a hotbox that opens an Historical Data Viewer window with a preselected set of tag values, over a preset time range. The HDV page that opens will include all of the standard tools for changing the tag selection, legend, time range and scale factor.

Because hotboxes are not visible until the pointer is over them, you are advised to add a label that will help operators find this control.

The properties dialog for the HDV Hotbox widget:

Hotbox Color

The default color is yellow. You may wish to choose a color that distinguishes this link from other types of hotbox.

Pen Group Selector

An existing pen group must be chosen, otherwise this button provides nothing more than a link to an empty HDV page.

Pen groups are created in the Historical Data Viewer page, using the Tag Selector dialog.

Duration Selector

Choose the length of time that will be shown initially when the HDV page opens.

Widget Folders:

Analytics\Trends & Historical Data\

Tools\Standard Library\

Related information:

Pen Groups - Save Tag Selections

HDV Button Widget

Plot Data Widget

Draw HDV Widget

Historical Data Viewer (HDV) - Operator's Guide to the Historical Data Viewer


Historian Status

Viewing: Reference > Widget Reference > Historian Status

Historian Status Widget

* Does not use the Style Settings tag.

You can monitor the operational status of all of the Historian tags in your application using the Historian Status widget. Many developers choose to create a page that is dedicated to monitoring the state of their application. The Historian Status widget is usually placed in a prominent location on such a page.

You can find this widget in the palette folder: Analytics >> Trends & Historical Data

There are no user-configurable options available in the properties dialog for this widget.

The Historian Status display will be blank while you are working in Idea Studio. Refer to the live page to see the status display.

All Historian tags in your application will be listed. The grid can be sorted on any column and in either ascending or descending order. Click on the title of any column - once to sort in ascending order and twice to sort in descending order.

Note that the information displayed is from the perspective of the local machine because Historians are both services and tags (much like device drivers).

Current Server and Connection Status:

An Historian is a tag. On any given computer it may running as a primary server, backup server or a client. Current Server shows which machine is considered to be the server for the locally running Historian. The connection status refers to the connection between the Historian and its data store location.

It is possible to monitor the connection to any particular server for a given Historian and therefore to trigger an alarm in the event that the connection is lost - see: Use an Expression to Monitor the Connection.

Queue Length

Shows the number of records in memory, waiting to be written. This number will normally fluctuate slightly with system activity. An ever-increasing value indicates that the hard drive or database cannot keep pace with the data being collected by the Historian and may be taken as a warning of data storage difficulties.

Write Rate

Shows the number of records per second being added to the queue. The DB Store Rate shows the number of records being processed by the database each second. A Write Rate that is consistently higher than the DB Store Rate indicates that the Historian is collecting data faster than the hard drive or database program is able to store it. If this is the case, you should look for ways to improve the performance of the data storage mechanism.

Service Status

The message in the Status column will change depending on the Historian's activity.

"Ready" indicates that, so far as can be found on the current computer, the Historian service is synchronized and is ready to accept records to be written.

"Waiting" indicates that the Historian is waiting for synchronization to finish, or that the service is unavailable.

If the Historian is synchronizing data across servers, the message will indicate the status of that synchronization.

Widget Folders:

Analytics\Trends & Historical Data\

Analytics\Statistics\

Analytics\Diagnostics\

Tools\System Status Tools\


History Stats Value Widget

Used by: Analog Status tag, Counter tag, Digital Status tag, I/O tag, Rate of Change tag, Totalizer tag

* Does not use the Style Settings tag.

When linked to an analog or digital tag as its data source, the History Stats Value widget will display any one of a selection of statistics about that tag's value. The time span for the statistic must be specified by the operator. You can also allow them to display a different statistic.

The widget updates its value only when the dates are adjusted, and the selected dates are saved per-user session

The available calculations include:

  • Time-weighted average - average value over a specified length of time.
  • Minimum value during period
  • Maximum value during period
  • Value at start
  • Count of zero to non-zero transitions (e.g. equipment starts)
  • Non-zero time (example: total time that a pump was running during the period)
  • Totalizer, calculated as the sum of the values logged during the time period.
    Note that this calculation differs substantially from that used by Totalizer tags.
  • Change in value
    The amount a value has changed over time. (In other words, the value at the end of a period minus the value at the beginning.)
  • Change in value with rollover
    The amount a value has changed over time where the tag resets back to 0 each time it reaches a specified rollover value.

This is for hardware that can count to a limited number, then rolls over to start a fresh count. For example, a tag that counts equipment starts, but which can only count from 0 to 15 before wrapping around to start again. This gives a value of sixteen per roll-over since there must be one more start after fifteen to have the roll-over occur. A graph of a very simple case where there is a start every second would look like the following:

(Each rollover must be followed by a fresh start, not a gradually declining value. If there are a series of declining values then, because each is less than the previous, each counts as another rollover.)

The formula used is (RolloverCount * RolloverValue) + (LastValidValue - FirstValidValue).

Where, for any given time interval:

  • Rollovers are counted when a new value is smaller than the last valid value.
  • The RolloverValue is passed to the function in the parameter StaleTime.
  • LastValidValue starts with the last valid value in the previous time interval (if any), and is updated with each new valid value within the time interval.
  • FirstValidValue starts with the last valid value in the previous time interval (if any), and is updated with only the first valid value found in the current time span.

Given this example, suppose that you want a count of starts in each thirty-second interval. In the first interval there is no previous valid value, one wrap-around and a last valid value of 12. (1*16) + (12 - 0) = 28.

This is an idealized case. Consider a more realistic case where not all values are logged. (This may be due to factors such as polling intervals, deadbands, hardware, etc.) The following graph shows the same data where the orange dots represent values obtained and logged and the gray line represents what really happened:

In the first 30 seconds there is one roll-over when the value drops from 13 to 2. The first value is 0 and the last is 11. The Historian will return 27: (1*16) + (11-0) = 27.

The Historian will return 30 for the period from 30 to 60. The first valid value (carried from the previous period) is 11. The last valid value is 9 and there are two roll-overs. (2*16) + (9-11) = 30.

The properties dialog for the History Statistics widget:

Font

Select the font to be used when displaying this widget.

Statistic

Select one of the available statistics, as described earlier in this topic.

Show Units

Choose whether to display the engineering units of the linked tag.

Show Statistic

Choose whether to display the calculated statistic.

Show Time Range

Choose whether to display the time period for which the statistic was calculated.

Allow Statistic Selection

Allow operators to select which statistic to display when setting the time range.

Digits After Decimal

Select how many digits to display in the calculated value.

Rollover Value

Applies only when calculating Change in Value with Rollover.

The maximum value at which an increasing value will reset back to 0. This parameter will be ignored if the Use Tag's Max Value option is selected.

Use Tag's Max Value

Select to use a maximum value from the scaling tab of the tag's configuration as the rollover value. This may vary by tag type and configuration.

If the source tag is an IO tag, the Display Range Max parameter will be used if it is set. Otherwise, the Scaled Process Data Max value will be used.

If the source is an Analog Status tag, the High Scale Value will be used if it is set. Otherwise, the Scaled Process Data Max value will be used.

Horizontal Alignment

Choose whether to align text to the left, the center or the right of the area occupied by the widget.

Colors

Select the color of the text and the widget background. Defaults to black text on an invisible background.

Unique Key

Variables such as dialog positions and sizes are normally retained per-user and per-module. What this means for the History Statistics widget is that the user selections would be saved but shared across all these widgets.

By providing a unique key to this parameter, each History Statistics widget drawn in an application can save its own settings. If used, the key may be any phrase such as, "Main Station Display" or "Treatment Plant Panel", or the provided unique ID.

If the widget is used in a parameterized page, it will be necessary to have a different key for each version of the page that you open. Therefore, this property may be linked to a page parameter or expression.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Text\History Stats Value

Analytics\Statistics\History Stats Value


Horizontal Button Widget

Used by: Selector Switch.

* Does not use the Style Settings tag.

The Horizontal Button widget, one of the native widgets for Selector Switch tags, is a control method used to output one of three possible values. The values will be those configured for the three positions of the selector switch, 0 to 2 in order from left to right.

Horizontal buttons in a normal operating state:

If the underlying selector has only two positions, then only the left and the middle button will be functional. The operator may click the right button, but this will have no effect on the switch position or output. Due to the confusion that this may cause, horizontal buttons should be used only with three-position selector switches.

Color is used to indicate that either a mismatch in state has occurred, or that an alarm is active as shown in the following examples.

Horizontal buttons showing a state mismatch: (See: Selector Switch Tags, for a discussion of mismatch conditions.)

Horizontal buttons showing an active alarm:

The following image shows the properties dialog where you can set the properties of the object.

Position n Text - 1, 2, 3

Set the labels that will appear on the buttons. The buttons are drawn from left to right and match the Position 0 through Position 2 settings of the associated selector switch.

If the label is to include an ampersand (&), enter two ampersands (&&).

Mismatch Color

Use the slider to set the color that will be superimposed on a button in the event of a position mismatch in the selector switch. A sample image displays the result as you adjust the slider.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


HP Analog Bar

* Can use properties from a Style Settings tag.

A component of the Analog Bar & Indicator Widget. Refer to that topic for a full discussion.

You may use this widget to build your own custom High Performance HMI widgets.

Bar showing most features enabled

The history range (shown in dark blue) is visible only if values are set for both Recent Time Range and Refresh time.

Configuration properties for the bar

Configuration properties are plain by design. Where the properties dialog for the Analog Bar and Indicator widget provides a spin box to set the Recent Trend and Refresh Time, this dialog uses raw data entry tools. The purpose is to give you more options when using this tool in custom widgets of your own.

Widget Folders:

High Performance\


HP Analog Indicator Widget

* Can use properties from a Style Settings tag.

A component of the Analog Bar & Indicator Widget. Refer to that topic for a full discussion.

You can use this widget to build your own custom High Performance HMI widgets.

Indicator showing a recent trend direction

The trend direction arrow (shown in blue) is visible only if values are set for both Recent Trend and Refresh time.

Configuration properties for the indicator

Configuration properties are plain by design. Where the properties dialog for the Analog Bar and Indicator widget provides a spin box to set the Recent Trend and Refresh Time, this dialog uses raw data entry tools. The purpose is to give you more options when using this tool in custom widgets of your own.

Widget Folders:

High Performance\


HP Radial Gauge

Used by: I/O and Calculation tag

* Can use properties from a Style Settings tag.

The High Performance Radial Gauge widget is a radial version of the HP Analog Bar widget.

This example uses default colors and shows an expected range, recent values, a high alarm (high priority) and a low alarm (critical priority). The widget gives you the option of displaying the alarm ranges using either the matching priority colors or gray.

By definition, an expected range should not overlap an alarm setpoint. If you do configure an overlap, do not expect both to show in any widget.

The properties dialog for the HP Radial Gauge widget:

(Click to expand image)

Minimum Angle / Maximum Angle

Measured in degrees, clockwise from vertical. Use these to set the angular range for the tag's value.

Defaults to 270 deg for the minimum value and 90 for the maximum angle, as shown in the example.

Bar Width

Expressed as a percentage of the widget's overall width or height (whichever is smaller).

Indicator Image

The default image is a needle. Use this to select and then configure any alternate image that you prefer.

Offset from Center

Measured as a percentage of the image size, this allows the needle (or other selected image) to rotate about a point that is not at the edge of the image.

The widget as seen in the Idea Studio. The red cross at the center of indicator rotation is not displayed to operators.

Indicator Scaling

Permitted values range from 0.5 to 1.5. The default is 1.

This scales the image used for the indicator by as much 50% of the original size up to 150% of the original.

Scaling takes the Offset from Center into consideration, keeping the scaled indicator image at the same relative origin as the original.

Display Options

Show Value / Show Units

Use these options to control whether the current value and the tag's configured engineering units are shown below the gauge.

Value & Units Offset

Measured in pixels, this sets the distance from the bottom of the widget's bounding box, up to the location of the value and units (if displayed). Both value and units are always centered horizontally.

Show Scale

Controls whether a scale and a numeric legend is shown within the arc of the gauge.

There is no option to show one without the other. The linked tag's scaling is used in all cases.

Number of Major Divisions

The number of large spaces in the scale bounded by large tick marks. See note for Major Tick Size.

Number of Minor Divisions

The number of spaces bounded by smaller tick marks between each set of major tick marks.

Major Tick Size

Measured in terms of a percentage of the size of the overall widget's bounding box. Given a default of 10% for the major tick size and a default of 5% for the bar width, this makes the tick marks twice as long as the bar is wide.

Recent Data (minutes)

If set to a value greater than 0, a thin bar (half the width of the overall bar) will show values recorded over the X number of recent minutes.

Must be set to a whole number.

Colors

Style

Defaults to the Style tag selected in the tag linked to this widget.

Tick Marks and Labels

Sets the color used to display tick marks and labels.

Outline

Sets the color used to display the outline of the bar.

Background

Sets the color used to display the background of the bar.

Expected Range

Can be used to override the color that indicates the linked tag's expected range.

Recent Data

Can be used to override the color that indicates the linked tag's recent values. (See: Recent Data property, earlier in this topic.)

Always Show Alarm Colors

If selected, the portion of the bar above or below alarm setpoints is shaded using the Alarm Priority colors. When in an alarm state, only the priority color for the active alarm will show.

If not selected, those portions of the bar are shaded using the Alarm Off color (defaulting to gray). Active alarms are indicated using the appropriate Alarm Priority colors.

Alarm Off

Can be used to override the color that indicates the linked tag's alarm range.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges

High Performance


Illuminated Toggle Switch Widget

* Can use properties from a Style Settings tag.

Used by: Selector Switch.

See also: Toggle Switch Widget

The Illuminated Toggle Switch widget is a control method used to output either of two possible values. When used with a digital I/O tag, the switch will send a 1 for on and a zero for off. When used with a Selector switch, the values will be those configured for the first two of the three possible positions of the selector switch.

To indicate to the operator that the image is a button, a highlight is drawn when the pointer is over the switch.

In the event that the position feedback from the Selector Switch indicates that the actual position is not the same as the requested position, the border of the image will blink using the mismatch color. You should select a color that stands out clearly on your page background, but red is not advised because it is commonly understood to mean that an alarm has been triggered.

The switch works by toggling between positions 0 and 1 whenever the operator clicks on the button. Should the tag be in an invalid state (which will not be unusual when a selector switch is first created) then it is not clear whether the first click should move the switch to the state 0 or the state 1 position. For this reason, a dialog will prompt the operator for an initial position.

The Properties dialog for an Illuminated Toggle.

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Off Light Image / Off Image

The image used for each position is composed of two parts: a basic light and a frame with semi-opaque lens that provides shape to that light.

Within the Bitmaps\Selector Switches\ folder of the Images palette, lights and lens images that are designed to work together will have matching names.

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

On Light Image / On Image

Similar to the Off Light Image and Off Image. Selects the light and lens images to display when the toggle is in position one.

Mouse Over

The Mouse Over image to be used when the toggle is in position one. When left blank, the Illuminated Toggle will be highlighted when the operator moves the pointer over it.

Draw light over image

Reverses the order of the light and the lens. Typically, the lens will contain the On/Off label, therefore choosing this option will hide the label and accentuate the color.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.s

Widget Folders:

Buttons & Switches\

Related information:

Style Settings Tags

Choices for Operator Interaction


Image Change Widget

Used by: I/O and Calculations, Alarm, Alarm Status, Analog Control, Analog In, Analog Out, Analog Status, Calculation, Counter, Deadband, Digital Control, Digital Input, Digital Output, Digital Status, Function, History Statistics, Modem, Network Status, Pump, Rate of Change, Roster, Selector Switch, Serial Port, SMS Appliance, SQL Logger, TCP/IP Port, Totalizer, Trigger, UDP/IP port.

* Does not use the Style Settings tag.

"2 state" versus "4 state". Not all tags will have all the states shown in these examples. Alarms have only state 0 and state 1 and therefore must use the "2 state" version of this widget.
Digitals might only use two states, but they can have four and therefore must use the "4 state" version of the widget.

The Image Change is a flexible widget, used to indicate a change in state of its associated tag by any of several methods.

It can:

  • Display a different image for each state.

For example, a valve might be displayed in a closed position when the value of the associated tag is 0 and in an open position when the value is 1.

  • Display the same image for each of the tag's states, but with a different color applied.
    For example, a gray image can be chosen, then colorized so that it appears to be gray in state zero, but green in state one.
  • Display the same image for each of the tag's states, but with a different color in the image's indicator area for each state

A single pump image might be displayed with the indicator area at its base showing red when the pump is off and green when the pump is on.

  • Represent the state of the associated tag with a color-changing area positioned over areas drawn with Active Orange (RGB 255, 160, 0).

As of VTScada release 11.1, default settings for each image will colorize the entire image rather than the indicator area. This makes the Image Change appear to work the same as an Equipment widget without actually having a link to a Style Tag.
To configure an image change as was done in legacy applications (where only the indicator area would change color) click the Adjust button for each state, then click the Reset to Defaults button within the Adjust Image dialog. This will remove the colorization from the entire image.

Examples follow for each of these ways of using the Image Change widget.

  • Display a different color for each state:

The properties dialog configuration to produce these images is as follows. Note that the colors are applied by colorizing each state, rather than using a Style Settings tag.

  • Display a different image for each state:

The properties dialog configuration to produce these images is as follows.

(The Restore Defaults button in the Adjust Image dialog has been used to remove colorization from each state in this example.)

  • Display the same image for each of the tag's states, but with a different color in the image's indicator area for each state

The properties dialog configuration to produce these images is as follows. Note that the Use State 0 Bitmap for All States check box has been selected.

(The Restore Defaults button in the Adjust Image dialog has been used to remove colorization from each state in this example.)

  • Represent the associated tag with a color-changing area positioned over areas drawn with active orange (RGB 255, 160, 0).

Tag

The Tag field displays the name and description of the tag that is linked to this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Use State 0 Bitmap for All States

Select this box if you wish to use the image selected for State 0 for all states of the tag.

This option is often used when the selected image's indicator area (the small rectangle at its base) is to be replaced with a new color according to the state of the tag.

Use Image / No Image

Select whether to include an image for the Image Change.
If not using an image, you should select Color Replace, then position the Image Change over an area of Active Orange. Everything that is Active Orange below the Image Change will be replaced with the matching state's color.

Color Replace

Use the Color Replace option if the image includes a color indicator patch, or if you have selected the No Image option. (Color indicators patches must be areas of Active Orange.)

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Indicators\Basic Indicators\

Basic Components\Color Indications\

Basic Components\Images\

Related information:

Choices for Operator Interaction


Indicator Light Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm, Alarm Status, Analog Control, Analog Input, Analog Output, Analog Status, Calculation, Counter, Deadband Control, Digital Input, Digital Status, Digital Output, Digital Control, Function, History Statistics, Modem, Network Status, Pump Status, Rate of Change, Roster, Selector Switch, Serial Port, SMS Appliance, SQL Logger, TCP/IP Port, Totalizer, Trigger, UDP/IP Port.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

Indicator Lights can take many forms. Each form is composed of a light and a frame. You can select different lights and frames for each indicator that you have drawn, mixing and matching the pieces.

The properties dialog for an Indicator Light:

Style

Optionally, select a Style Settings tag to control the colors shown by the light, in response to the linked tag's value and alarm state.
See:Style Settings Tags

Light Image

Select an image that will change color according to the style setting. Must be a gray scale image. Light images and lens images that are designed to work together will have matching names in the Lights folder of images palette.

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Lens Image

Select an image that will frame the light, and provide a semi-opaque lens effect.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Indicators\Basic Indicators\

Related information:

Style Settings Tags

Choices for Operator Interaction


I/O Multi-Text

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations tags that have a numeric mode.

The text displayed comes from the linked Style Settings tag (Default if not selected). To use this widget you must:

  • Create an I/O and Calculations tag and assign an Equipment Type.
  • Create a set of Value entries in a System Styles tag for that Equipment Type.

If no values are defined, in the Style Settings tag, this will display the default labels and colors shown in the Digitals tab of the SystemStyle tag ("Off", "On", "2", "3") if current value falls in that range. If the tag has a value that is not listed in the Style Settings tag, nothing is displayed.

The color used for the text is defined in the properties dialog but can use the linked Style Settings tag instead if you would prefer a color that changes according to the tag state. This is a change in behavior from earlier versions.

Reference: Advanced Formatting: Options for Properties

Style

Both the text displayed by the widget for each discrete value, and the assigned color come from the associated Style Settings properties: Equipment tab

If no Style Settings tag is defined in this properties dialog, the Default System Style tag is used. Values must be added and configured in the Equipment tab of that style tag. Nothing will be shown otherwise.

Font

The default Windows system font is used unless you select a Font tag.

Vertical Alignment

Sets the position of the text within the display area. You may select top-aligned, bottom-aligned or centered. To align the overall widget with other elements on the page, see Align.

Horizontal Alignment

Sets the position of the text within the display area. You may select left-aligned, right-aligned or centered. To align the display area itself with other elements on the page, see: Alignment and Positioning Tools.

Horizontal and Vertical Alignment may be represented as an expression with a value of 0, 1 or 2.
0 = Left or Top
1 = Center
2 = Right or Bottom

Colors

Text, Background, and Outline

Opens the Select Color Dialog from which you can select the color of the text (defaults to black), the background (defaults to transparent), and the outline (defaults to transparent).

To set the text color based on the linked Style tag, expand the text color option as shown in the following image. This option is available only for the text color, not the background or outline.

Choosing to use the linked Style color for text instead of a single color.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Text\

Tag Types\Inputs & Outputs\I/O and Calculations\Analog\

Related information:

Style Settings Tags

Choices for Operator Interaction


Last Logged Value Widget

Used by: Counter, Totalizer.

* Does not use the Style Settings tag.

The Last Logged Value widget is used to display the value last written to a log file (if any), for either a Totalizer tag or a counter tag.

The properties dialog for the Last Logged Value:

Font

Select one of the font tags (or parameter linked to a font tag) that you with to use to display the text. The display will use the default system font if you do not select a font tag.

The parameters button is enabled only if the tag is drawn on a page that includes a font parameter, or if the tag is part of a widget and the associated widget editor is open.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Digits after Decimal

Sets the accuracy with which the value is shown. This is for display only - there is no effect on the accuracy of the associated logged value.

Show Units

Sontrol whether the units defined within the Logger tag should be shown in this display.

Horizontal Alignment

Sets the position of the text within the display area. You may select left-aligned, right-aligned or centered. To align the display area itself with other elements on the page, see: Alignment and Positioning Tools.

Type of Border

Examples of the three border types are shown at the beginning of this topic.

Colors (Text and Background)

Opens the Select Color Dialog from which you can select the color of the text.

The background color against which the text will be displayed can also be defined.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


LCD 5x7 Matrix Widget

* Can use properties from a Style Settings tag.

Used by: All numeric tags except Digitals.

The LCD 5x7 Matrix widget represents the associated tag's value as an dot matrix (LED) display. An active alarm will cause the numbers to use the alarm color.

The default colors look best against a dark background, but may be configured as required within the linked Style Settings tag.

The properties dialog for the LCD 5x7 Matrix widget:

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Digits Before Decimal / Digits After Decimal

Sets the number of digits to display. Digits beyond the range of the tag's current value are shown in dim shade, as configured in the linked Style Settings tag.

If linked to an I/O and Calculation tag, you can choose to use the current Digits after Decimal setting from the tag's configuration instead.

Show Alarms

When selected, values that exceed alarm setpoints will be drawn in the Style Settings alarm color (usually red).

Show Leading Zeros

Must be selected in order for leading zeros to be included in the display.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Text\

Related information:

Style Settings Tags

Choices for Operator Interaction


LCD 7 Segment Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Allan Bradley driver, Alarm Status, Analog Control, Analog Input, Analog Output, Analog Status, CalAmp Diagnostic driver, Calculation, Comm Link Sequencer, Counter, DataFlow Station, DDE Client, Deadband Control, Driver Multiplexer, Function, History Statistics, MDS driver, Modem, Motorola RTU driver, Omron driver, OPC Classic Client driver, Polling driver, Rate of Change, Script, Serial port, Selector Switch, Siemens S7, SMS Appliance, SNMP driver, SQL Logger, Totalizer, Workstation driver.

The LCD 7 Segment widget represents the associated tag's value as an LCD display. An active alarm will cause the numbers to use the alarm color.

The default colors look best against a dark background, but may be configured as required within the linked Style Settings tag.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

The properties dialog for the LCD 7 Segment widget:

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Digits Before Decimal / Digits After Decimal

Sets the number of digits to display. Digits beyond the range of the tag's current value are shown in dim shade, as configured in the linked Style Settings tag.

If linked to an I/O and Calculation tag, you can choose to use the current Digits after Decimal setting from the tag's configuration instead.

Show Alarms

When selected, values that exceed alarm setpoints will be drawn in the Style Settings alarm color (usually red).

Show Leading Zeros

Must be selected in order for leading zeros to be included in the display.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Text\

Related information:

Style Settings Tags

Choices for Operator Interaction


LCD Arc Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

The LCD Arc widget represents the associated tag's value as a series of tick marks, a percentage of which are highlighted according to the tag's value. An option in the configuration enables the meter to display alarm values as red tick marks beyond the alarm set point.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

The properties dialog for the LCD Arc widget:

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Minimum and Maximum Angles

Angles are measured clockwise from vertical. These two fields define the start and end points for LCD Arc's sweep.

Number of Sections

Controls the number of segments that will be shown within the meter's sweep. Defaults to 50, but should be reduced if a smaller sweep angle is defined.

Show Alarms

When selected, tick marks past the alarm set point will use the color configured in the style tag.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Style Settings Tags

Choices for Operator Interaction


LCD Bar Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm Status, Analog Control, Analog Input, Analog Output, Analog Status, Calculation, Comm Link Sequencer, Deadband Control, Function, History Statistics, Script, Selector Switch, SQL Logger.

The LCD Bar widget represents the associated tag's value as an dot matrix (LED) display. If configured, an active alarm will cause the dots above the alarm set point to use the alarm color. Two versions are included in the palette: one with a single column of wide images and one with an array of small images.

The default colors look best against a dark background, but may be configured as required within the linked Style Settings tag.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

The properties dialog for the LCD Bar widget:

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Select Bitmap

Choose the image to display for each square of the bar. The default image for the array version of this widget is a 5x5 pixel, light gray rectangle. For the series of stacked bars, it is a 65x11 pixel bar with shaded edges.
If choosing another image, ensure that it is a light shade of gray, to be compatible with the Style Settings tag.

Suggested alternative images can be found in the images folder, Widget Parts >> Meter Parts >> LCD Elements.

Options

Set the number of rows and columns that will be displayed in the array, and the space between each element, measured in pixels.

Show Alarms

When selected, rows that represent values past the alarm set point are displayed using the alarm color in the Style Settings tag.

Scaling

In most cases, a widget will show the scaled values configured within the linked tag. You can override this setting to map the tag's values into any range you prefer to display.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Bars\

Related information:

Style Settings Tags

Choices for Operator Interaction


LCD Meter Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

The LCD Meter widget represents the associated tag's value as speedometer type of gauge with a series of tick marks, a needle, and a numeric scale. A percentage of the tick marks will be highlighted according to the tag's value. The numeric portion of the meter will flash red when the linked tag is in an alarm condition.

The LCD Meter tends to look best on a dark background.

The properties dialog for the LCD Meter widget:

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Tick and Label Color

Sets the color of the segments marks and scaling text around the meter. Defaults to gray <FF929292> so that the labels will be visible against a white background.

Number of Segments

The number of LCD tick marks displayed around the sweep of the meter. The meter will usually look best when this number matches (or is a multiple of) the number of Major Divisions times the number of Minor Divisions.

Number of Labels

Controls the number of text labels displayed around the meter.

Number of Major Divisions

The number of longer white lines around the meter.

Number of Minor Divisions

The number of shorter white lines between each major division.

Digits Before Decimal & Digits After Decimal

These two parameters work together to define the number of LCD digits displayed in the numeric portion of the meter.

The display has room for a maximum of four digits. If adding a fourth digit before the decimal, you must remove the one following.

If linked to an I/O and Calculation tag, you can choose to use the current Digits after Decimal setting from the tag's configuration instead.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Style Settings Tags

Choices for Operator Interaction


LCD Ring Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

The LCD Ring widget represents the associated tag's value as a highly stylized meter, with a numeric display and a series of tick marks, the number of which fluctuates according to the tag's value. An option in the configuration enables the meter to display alarm values as red tick marks beyond the alarm set point.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

The properties dialog for the LCD Ring widget:

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Show Alarms

When selected, tick marks past the alarm set point will use the color configured in the style tag.

Digits After Decimal

Sets the number of digits to show following the decimal point. Digits that would extend outside the ring will be clipped from view. You may need to decrease the font size to display a large number of digits.

If linked to an I/O and Calculation tag, you can choose to use the current Digits after Decimal setting from the tag's configuration instead.

Font Size

Measured in pixels rather than points, this sets the overall size of the font used for the numeric portion of the display.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Style Settings Tags

Choices for Operator Interaction


Left Bar Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Deadband Control, Function, History Statistics, Script, Selector Switch, SQL Logger.

* Does not use the Style Settings tag.

The Left Bar widget is used to display a tag's value as a horizontal bar, the length of which increases from the right towards the left as the tag’s value increases. When the tag’s value is at a minimum, the bar will be shown as a thin line at the right edge of its range. When the tag’s value reaches its maximum, the widget will be displayed as a rectangle, filling the range.

The graphic editor for the Left Bar widget:

Set Color

Opens the Select Color Dialog from which you can select a color for this object.

Low Scale Range and High Scale Range

In most cases, these fields will be display-only, showing the Scaled Process Data Min and Scaled Process Data Max values configured for the associated tag.

These fields become editable when the widget is used to display a function or Calculation tag. The most common use is to provide an output range of 0 to 100 (%) given a data source whose numbers do not match these values (perhaps ranging from 20 to 80, for example). Set the low scale range to the value expected from the data source when it is at its minimum and the high scale range to the value expected from the data source when it is at its maximum.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Basic Components\Bars\

Related information:

Choices for Operator Interaction


Legacy Page Button Widget

Standard Library. Not linked to any tag.

* Does not use the Style Settings tag.

The Page Button widget is a navigational tool, used to create a connection from one page to another.

Buttons are always visible, and can be configured with their own label so that operators will know what to expect when they click.

Note that there is a choice of behavior in one uncommon configuration:

A page button or page hotbox drawn on a windowed (pop-up) page, and that widget calls the same page. You might create this configuration if you have a parameterized page and want to switch parameter values while staying within the pop-up. In this configuration, you can use the PageChangeUpdateSamePopup parameter to control whether another instance of the page is created, or the current page is replaced.

The properties dialog for the Page button widget:

Button Label

The label should always tell the operator what to expect to happen when they click the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Page Name

Select the page to be opened when the operator clicks the button. The Page Menu Page can be selected, as can pages of subordinate applications, if any.

Parameters

Visible only if the selected page has parameters. If so, it is important to select the tags and values that will be used for those parameters when the operator opens the page using this particular button. Failing to do so will result in the operator being prompted for parameter values with every return visit.

Whether the page opens as a pop-up window or full screen, depends on the configuration of the page, and not on any configuration of the button.

Widget Folders:

Page Navigation\

Tools\Standard Library\

Related information:

Add Navigation


Legacy Page Hotbox Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Page Hotbox widget is a navigational tool, used to create a connection from one page to another.

The hotbox is invisible unless the pointer is over it, at which time it turns yellow (or any other configured color). It is common to place a hotbox around a text label or an image so that operators will know where to find it, and what page to expect when they click.

Note that there is a choice of behavior in one uncommon configuration:

A page button or page hotbox drawn on a windowed (pop-up) page, and that widget calls the same page. You might create this configuration if you have a parameterized page and want to switch parameter values while staying within the pop-up. In this configuration, you can use the PageChangeUpdateSamePopup parameter to control whether another instance of the page is created, or the current page is replaced.

The properties dialog for the Page Hotbox widget:

Hotbox Color

While most developers will leave the default color in place for the sake of consistency, you might decide to color-code the hotboxes for various groups of pages in your application. You might also want to ensure that Page Hotboxes use a different color than Legacy Set Value Hotboxes, which are analog control widgets.

Page Name

Select the page to be opened when the operator clicks the hotbox. The Page Menu Page can be selected, as can pages of subordinate applications, if any.

Parameters

Visible only if the selected page has parameters. If so, it is important to select the tags and values that will be used for those parameters when the operator opens the page using this particular hotbox. Failing to do so will result in the operator being prompted for parameter values with every return visit.

Whether the page opens as a pop-up window or full screen, depends on the configuration of the page, and not on any configuration of the hotbox.

Widget Folders:

Page Navigation\

Tools\Standard Library\

Related information:

Add Navigation


Legacy Set Value Button Widget

Used by: I/O and Calculations (all data types), Analog Input tag, Analog Status, Analog Output, Analog Control, Digital Input, Digital Status, Digital Output, Digital Control, Multi-Write, Pump Status, Report, Selector Switch, Trigger.

* Does not use the Style Settings tag.

The Legacy Set Value Button tag widget is similar to the Push Button widget, but with a plain appearance and more options. It is used to create a button that operators can use to write any given value to an RTU or PLC.

A typical Legacy Set Value button

The button can be configured to either write a value immediately, or to set up a value for the next button press. Most commonly, this widget is used with a digital output or control tag and will be drawn twice for that tag: one instance will write a 0 and one instance will write a 1.

If the associated tag is configured to write a pulsed value, the State 1 label will be visible while the write is in progress. Otherwise, only the State 0 label will normally be seen.

If the label is to include an ampersand (&) and you are not using the legacy style, then the & character will need to be doubled to appear.

The properties dialog for the Legacy Set Value Button widget will look similar to the following. Note that the confirmation dialog option is available only when writing a 1 or 0 immediately, or when executing the last set up value.

Configuration options for the Legacy Set Value button

State 0 Label

Set the text that should be displayed on the button when the associated tag is in state 0. In most cases, this will should describe what will happen when the operator presses the button. (for example, "Run" or "Start").

If the label is to include an ampersand (&), enter two ampersands (&&).

State 1 Label

Enter the text that you want to display on the completed button when the associated tag is in state 1 (or a higher value). This should usually provide feedback to the operator to confirm that the button has been clicked (for example, "Running…" or "Starting…").

If the associated tag is a digital output or digital control and has been configured with a pulse duration (see the tag's Pulse Duration property on the I/O tab of its tag properties folder), the State 1 Label will be displayed for the length of the pulse duration. If the tag being drawn has been configured with a pulse duration of "0" then it is recommended that the State 1 Label match the State 0 Label.

Write 0 Immediately / Write 1 Immediately

Choose one of these radio buttons if you want the completed button to write a value of 0 or 1 to the PLC or RTU when it is clicked.

Set Up 0 For Next Execute / Set up 1 For Next Execute

Choose one of these radio buttons if you wish the completed button to set up a value of 0 or 1 to be sent to the associated equipment.

This will not result in the completed button sending a value to the PLC or RTU when it is clicked, rather, it will latch the button on, set the value in memory and wait for a command to execute this value. A second button should be configured with the Execute Last Set Up Value radio button selected.

When the second button (Execute Last Set Up Value) is clicked, the value in memory will be sent to the associated equipment, and the first button will be latched off.

Execute Last Set Up Value

The Execute Last Set Up Value radio button can be selected if you wish the completed button to transmit the last set up value to the associated equipment.

The Execute Last Set Up Value option requires at least two Legacy Set Value Button objects. The first button should be configured with either the Set Up 0 For Next Execute or Set Up 1 For Next Execute radio button selected. When the first button is clicked, it will be latched on, and the associated value (0 or 1) will be set up in preparation for a command to execute. When the second button (Execute Last Set Up Value) is clicked, the value will be transmitted to the equipment, and the first button will be latched off.

Cancel Last Set Up Value

The Cancel Last Set Up Value radio button can be selected if you with the completed button to cancel the last set up value to the associated equipment. A legacy set value button with this option should be drawn whenever you have also drawn one with the Set Up … for Next Execute option set.

Confirmation Dialog

Available only when the button is configured to write a 1 or 0 immediately, or to execute the last set up value. When checked, the operator will be prompted to confirm the control action. The message in the dialog box will be a variation of the following example, depending on the control action selected. See also: Confirmation Prompts for Output Tags.

Use Legacy Style Button

If selected, the button will be shown using an older (resizable) button style. The updated button will provide a more modern appearance to your pages.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


Legacy Set Value Hotbox Widget

Used by: Analog Input, I/O and Calculations, Analog Status, Analog Output, Analog Control, Digital Input, Digital Status, Digital Output, Digital Control, Multi-Write, Pump Status, Report, Selector Switch, Trigger.

* Does not use the Style Settings tag.

The Legacy Set Value Hotbox tag widget is identical in function to the Legacy Set Value Button widget. The difference is only in its appearance in your applications. Where the Legacy Set Value Button widget creates a click-able button, the Legacy Set Value Hotbox creates only a rectangular hotbox marking an area where the operator can click. It is up to you to make it clear to the operator what will happen when the hotbox is clicked.

One way that this widget might be used is superimpose hotboxes over an image of equipment from your facility. The boxes should be located over the controls familiar to the operators.

A typical Legacy Set Value hotbox. A label or other target is recommended.

Configuration options for the Legacy Set Value Hotbox

Write 0 Immediately / Write 1 Immediately

Choose one of these radio buttons if you want the completed button to write a value of 0 or 1 to the PLC or RTU when it is clicked.

Set Up 0 For Next Execute / Set up 1 For Next Execute

Choose one of these radio buttons if you wish the completed button to set up a value of 0 or 1 to be sent to the associated equipment.

This will not result in the completed button sending a value to the PLC or RTU when it is clicked, rather, it will latch the button on, set the value in memory and wait for a command to execute this value. A second button should be configured with the Execute Last Set Up Value radio button selected.

When the second button (Execute Last Set Up Value) is clicked, the value in memory will be sent to the associated equipment, and the first button will be latched off.

Execute Last Set Up Value

The Execute Last Set Up Value radio button can be selected if you wish the completed button to transmit the last set up value to the associated equipment.

The Execute Last Set Up Value option requires at least two Legacy Set Value Hotbox objects. The first button should be configured with either the Set Up 0 For Next Execute or Set Up 1 For Next Execute radio button selected. When the first button is clicked, it will be latched on, and the associated value (0 or 1) will be set up in preparation for a command to execute. When the second button (Execute Last Set Up Value) is clicked, the value will be transmitted to the equipment, and the first button will be latched off.

Cancel Last Set Up Value

The Cancel Last Set Up Value radio button can be selected if you with the completed button to cancel the last set up value to the associated equipment. A legacy set value hotbox with this option should be drawn whenever you have also drawn one with the Set Up … for Next Execute option set.

Hotbox Color

Opens the Select Color Dialog from which you can select a color to display when the mouse pointer is within the area of the hotbox. To reduce confusion, you should consider making this a different color than that of the Page Hotbox.

Confirmation Dialog

Available only when the button is configured to write a 1 or 0 immediately, or to execute the last set up value. When checked, the operator will be prompted to confirm the control action. The message in the dialog box will be a variation of the following example, depending on the control action selected. See also: Confirmation Prompts for Output Tags.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


Linear Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Linear Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value. This meter displays the tag’s value as text, and includes the engineering units in addition to the dial.

The properties dialog for the Linear Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Lock Level Box Widget

A Lock Level Box is an Alarm Priority Box, configured to indicate that a Control Lock exists and to show the associated Lock Level number.

Refer to Control Locks for a full explanation of what Control Locks are and how they work.

When configuring the widget, ensure that the option, Show Locked Icon is selected.


Lock Level Icon Widget

A Lock Level Icon is an Alarm Priority Icon, configured to indicate that a Control Lock exists and to show the associated Lock Level (priority) number.

Refer to Control Locks for a full explanation of what Control Locks are and how they work.

When configuring the widget, ensure that the option, Show Locked Icon is selected.


Locks List Widget

A Locks List widget is an Alarm List widget, configured to display active Control Locks.

Refer to Control Locks for a full explanation of what Control Locks are and how they work.

The Column Format of the list must be set to Locks. When set, the Starting List is restricted to Locks as the only option.

Do not change the Alarm Database selection. The widget will not display Control Locks if the Alarm Database is set to anything other than "All".

Columns display:

Lock Level Icon

The number and color indicate the Lock Level of each Control Lock.

Time

When the lock was added.

Remove

Enabled only for authorized operators (Those having the Add / Remove Lock privilege or the Lock Administrator privilege. Locks may be configured so that only an administrator or an authorized operator who "owns" the lock can remove it.)

Area, Name, Description

Information about the tag to which the Control Lock has been applied. If this is a parent tag, all the child tags will also be locked.

User

The person who created the lock.


Make Active Widget

Used by: Roster tag.

* Does not use the Style Settings tag.

Used in association with the Alarm Notification System, the Make Active tag widget will create a button that can be clicked to select the associated Roster tag as the active roster. This is used to select who will be contacted by the call-out system in the event that an alarm has been triggered and has gone unacknowledged for a defined period of time.

The properties dialog for the Make Active widget:

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Specialty\Roster Control\

Related information:

Choices for Operator Interaction


Metal-Themed Meter Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Metal widget represents the associated tag's value as photorealistic meter.

The properties dialog for the Metal widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

The Tag field is only present when editing a completed widget object.

Options

Set the number of major divisions and minor divisions within each major division. Defaults to 10 and 5.

Choose whether to include the text used for engineering units within the gauge. Defaults to show units.

Colorization

Use the color selector dialogs to set the color of the needle, text and gauge background. This widget does not use the Style Settings tag.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Meter 1 Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Counter, Deadband Control, Function, History Statistics, Rate of Change, Script, Selector Switch, Totalizer SQL Logger.

* Does not use the Style Settings tag.

The Meter 1 widget is used to represent the associated tag's value as a round meter whose dial fluctuates according to the tag's value, and which also displays the value as text. The engineering units of the tag (% in this example) are also shown.

The properties dialog for the Meter 1 widget:

Low Scale Range and High Scale Range

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag's scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag as a meter 1 with a low scale range of 0 and a high scale range of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Digits After Decimal

Used to adjust the displayed accuracy of the meter. The displayed value will be rounded to the number of decimal points set. This is for display purposes only and has no effect on the tag’s value.

If linked to an I/O and Calculation tag, you can choose to use the current Digits after Decimal setting from the tag's configuration instead.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Related information:

Choices for Operator Interaction


Meter 2 Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Counter, Deadband Control, Function, History Statistics, Rate of Change, Script, Selector Switch, Totalizer SQL Logger.

* Does not use the Style Settings tag.

The Meter 2 widget is used to represent the associated tag's value as a half-round meter whose dial fluctuates according to the tag's value, and which also displays the value as text. The engineering units of the tag are also shown.

The properties dialog for the Meter 2 widget:

Low Scale Range and High Scale Range

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag`s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag as a meter 2 with a low scale range of 0 and a high scale range of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Digits After Decimal

Used to adjust the displayed accuracy of the meter. The displayed value will be rounded to the number of decimal points set. This is for display purposes only and has no effect on the tag’s value.

If linked to an I/O and Calculation tag, you can choose to use the current Digits after Decimal setting from the tag's configuration instead.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Related information:

Choices for Operator Interaction


Meter 3 Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Counter, Deadband Control, Function, History Statistics, Rate of Change, Script, Selector Switch, Totalizer SQL Logger.

* Does not use the Style Settings tag.

The Meter 1 widget is used to represent the associated tag's value as a numeric display, including the engineering units of the tag (% in this example) in the lower right corner.

The properties dialog for the Meter 3 widget:

Digits After Decimal

Used to adjust the displayed accuracy of the meter. The displayed value will be rounded to the number of decimal points set. This is for display purposes only and has no effect on the tag’s value.

If linked to an I/O and Calculation tag, you can choose to use the current Digits after Decimal setting from the tag's configuration instead.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Related information:

Choices for Operator Interaction


Modem Tools Library

Viewing: Reference > Widget Reference > Modem Tools Library

Modem Status and Statistics

Use tools in the Modem Tools folder of the widgets palette to configure displays related to the modems in your application. A common practice is to create a page showing the tools from the Modem folder, plus a Modem Indicator widget for each Modem tag in your system.

Taken together, these tools allow you to monitor current and recent modem activity, read modem log files and view collected statistics.

Draw a Modem Indicator for each Modem tag instance in your application.


Modem Indicator Widget

Used by: Modem tags.

* Does not use the Style Settings tag.

The Modem Indicator widget displays a graphic of an active modem control, showing the name of the associated Modem tag. When the associated modem is dialing out or answering an incoming call:

  • The widget will flash (green and red activity lights will flash on the control when the modem is active).
  • The text "Incoming Call" will be displayed (for incoming calls).
  • The number being dialed will be displayed (for outgoing calls).

If the modem has failed for whatever reason, a red X will be drawn through the image.

A modem can be reset by clicking on the widget when the application is in operation mode. A modem can also be marked as failed or unavailable using the Disable option of the shortcut menu (right-click on the widget when the application is in operation mode and select the Disable option).

The Modem Indicator has no configurable options beyond the standard disable options.

Widget Folders:

Analytics\Communications\Modems\

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


Event Log List

With the Event Log tool you can draw a list that displays the last 256 entries from the Modem Manager's internal log buffer. The most recent entries are shown at the bottom of the list.

An example of the Event Log dialog. The only user-configurable option is the title to display at the top of the log.

VTScada also makes it possible to save the data being displayed in the Event Log tool's list to a text file by using the Save Log Button tool.

Modem Event

Description

Modem Manager Started

The Modem Manager has successfully been started.

Server

The server is physically connected to the modem.

Line Name: Phone Line Started

The Modem Manager server has obtained a connection to a modem.

Modem Name: Modem Started on Workstation Name

The identified modem on the identified workstation was successfully initialized.

Modem Name: Answering on Ring X

The modem has successfully answered the incoming call on the ring indicated.

Workstation Name: Queue Call to Serial Port Name: Phone Number in X Seconds

The amount of time in seconds prior to the outgoing call being made. If the number of seconds displayed is 0, then there will be no delay in the call-out time.

In some cases, the Modem Manager may have queued other calls ahead of this outgoing call. In such cases, the number of seconds will reflect the amount of time before a call out is made.

Modem Name: Dialing to Serial Port Name on Phone Number

The modem is attempting to connect to a serial port using a configured phone number.

Modem Name: Connected To: Serial Port Name

The modem has successfully connected to the serial port indicated.

Modem Name: Call Ended To: Workstation Name: On Phone Number

Indicates that having successfully connected to the serial port, the modem can now end the communication.

Modem Name: Ending Call

The modem has completed the call and is now idle.

Use application properties to customize the number of entries that you wish to store in the Modem Manager's internal log buffer as well as the format for each entry.

Widget Folders:

Analytics\Communications\Modems\

Analytics\Diagnostics\

Related information:

Save Log Button

Modem Manager Properties - Reference.


Save Log Button

Create a button that the operator can click to save the Modem Manager's internal log buffer to a file for later analysis. View this file with the Event Log List.

The properties dialog for the Save Log Button dialog:

You can create your own custom label for the button with the Button Label field. If the label is to include an ampersand (&), then double that character (&&). In the File field, use the default name of "modem.log" in most cases.

VTScada will save the modem log file in your application folder, but you may save it to a sub-folder by specifying the folder name. For example: "\Modem Log Files\Modem.log".

VTScada will not create sub-folders automatically. If you specify a sub-folder as the file location, it is up to you to create that folder before running your application.

Widget Folders:

Analytics\Communications\Modems\

Analytics\Diagnostics\

Related information:

Event Log List - View information saved with the Save Log button.


Modem Statistics

Use the Statistics tool in the Modem Tools folder of the Widgets palette to draw a list of modem call statistics for analysis.

This differs from the Event Log List, which is used to view the modem entries in the Modem Manager's internal log buffer.

Modem Manager Statistic | Description
Lines Available | Identifies the total number of available modems.
Lines Used | Identifies the total number of modems that are in use.
Total Outgoing Calls | Displays the total number of outgoing calls made since the application was started.
Failed Outgoing Calls | Displays the total number of outgoing calls that have failed since the application was started.
Total Call Delay | Displays the amount of time in seconds from the request for the modem to the start of communications.

An example of the Statistics properties dialog. There are no user-configurable fields.

Note that some of the statistics collected will depend upon the settings configured for the Modem Manager in the application.

Widget Folders:

Analytics\Communications\Modems\

Analytics\Diagnostics\

Related information:

Event Log List- Display the last 256 entries from the Modem Manager's internal log buffer.

Modem Manager Properties - Reference.


Modem Status

Use the Status tool in the Modem Tools folder of the Widgets palette to draw a list of modem status information for monitoring. Use this tool's properties dialog to view information that is available for each modem. Use the buttons in the center column to select the status monitoring values that you wish to display.

The status display is initially 1064 pixels wide. After placing the display on a page, you may adjust it as required for the best display of the selected columns. In this example, all columns have been selected for display. The image is broken onto two lines, the better to fit this space.

Widget Folders:

Analytics\Communications\Modems\

Analytics\Diagnostics\


Momentary Button Widget

Used by I/O and Calculations, Analog Input, Analog Status, Digital Input, Digital Status, Pump Status, Analog Output, Analog Control, Digital Output, Digital Control, MultiWrite, Pump, Selector Switch, Trigger.

* Does not use the Style Settings tag.

The Momentary Button widget is used to draw a button that will send one value when pushed and (usually) the opposite when released. Both the value to write when pushed, and the value to write when released, must be provided before the button will be enabled. While similar in appearance to a Legacy Set Value Button Widget, it has a very different purpose.

A variety of Momentary Button configurations

This object can be displayed as a button, a hotbox, or a button surrounded by a hotbox. Only the button will have a label (whether surrounded by a hotbox).

Works on touch screens (Windows and VIC) only if not using the hotbox option.
On the Anywhere Client, momentary buttons work as toggling buttons (one tap for down, another tap for up).

Using the SCADA system instead of the PLC for pulsed control carries risk. Carefully consider what might happen to the system if something interrupts communication between the signal at the start and the signal at the end of the pulse.

Configuration options for the Momentary Button

Value to write when button pressed

Set the value that will be written when the completed button is clicked. If the associated tag is an analog output, this may be any value that is legal for that tag. Otherwise, this value should match one of the configured states for the associated digital or selector switch.

If this value is not set, the button will not work.

Value to write when button released

Set the value that will be written at the moment when the operator releases the button.

Button Down Label and Button Up Label

Provide the labels that will be displayed on the button. A different label will be displayed while the button is being clicked than will otherwise be shown. This can provide useful feedback to the operator who can be assured that the button has indeed been clicked and is presumably doing what it is supposed to.

If the label is to include an ampersand (&), enter two ampersands (&&).

Show Button

Deselect if you want to show only a hotbox with no button.

At least one of the button or the hotbox must be shown for this control to operate.

Use Legacy Style Layerable Button

Must be selected in order to add a hotbox.

Show Hotbox (disables touchscreen support)

Add a hotbox (or only a hotbox if Show Button is deselected).

As noted in the label, when a hotbox is enabled this widget will not function when displayed on a touchscreen

Hotbox Color

Opens the Select Color Dialog from which you can select a color for the hotbox object. Defaults to yellow.

Options

Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


Multi-Color Widget

Used by: I/O and Calculations, Allen Bradley driver, Alarm Status, Analog Input, Analog Status, Analog Output, Analog Control, Calculation, Counter, Data Flow RTU, CalAmp Diagnostic driver, DDE Client, Deadband Control, DNP3 driver, Driver Multiplexer, Function, History Statistics, MDS driver, Modem, Modbus Compatible Device , Omron driver, OPC Classic Client, Polling Driver, Rate of Change, Script, Selector Switch, Serial Port, Siemens S7 driver, SNMP driver, SMS Appliance, SQL Logger, Totalizer.

* Does not use the Style Settings tag.

The Multi-color tag widget is used to display a variety of rectangular color swatches in response to changing conditions within the application.

You can create up to 16 colors using the Color 1 through Color 16 tabs. The Color 1 swatch is the default to be shown when no user-defined conditions have been met for any of the other colors.

In the following example, a Multi-color widget has been used to create a background for a Linear Gauge widget. As the associated tag’s value increases, the multi-color serves as a visual warning.

The Multi-color is configured by creating a series of increasing trigger points and assigning a color to display as each point is reached. The trigger points can be given constant values, or can take their value from either a tag or parameter.

The initial color, color 0, does not have a trigger point because it will be the color in effect until the tag’s value reaches the first assigned value. Two versions of the properties dialog for this widget are shown:

What happens if the set point for Color 3 is reached before that of Color 2?

If using constant values, you cannot assign a lower trigger point for a higher color number. This situation can occur if the trigger point for each color is provided by different tags.

The multi-color widget will display each defined color in order from Color 1 through to Color 16. The swatch for Color 1 will be displayed until the comparison condition for Color 2 has been reached. Until the set point for Color 2 has been reached, it does not matter whether any other comparison condition has been exceeded.

After the comparison for Color 2 has been passed, the multi-color will go on to check the comparison for Color 3. If it has already been passed, then the swatch for Color 2 will be skipped in favor of the swatch for Color 3.

The same comparison order is used whether the Tag's value is rising or falling.

Color 1… Color 16 tabs

Select each tab in turn, up to the number of colors you wish to display. Each tab after Color 1 is used to set a trigger point using a constant, tag or parameter, and a color to display when that point is passed. Each successive tab used must have a greater value than the previous.

Set Color

Opens the Select Color Dialog from which you can select a color to display when the matching trigger point has been reached.

Minimum Value for this Color

Sets the trigger point, above which the set color will be displayed (until the next trigger point is reached). The value for this point may be provide by any of a user-defined constant, an expression another tag or a parameter.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Indicators\Basic Indicators\

Basic Components\Color Indicators\

Related information:

Choices for Operator Interaction

Multi-Text Widget - Display a new message, in a unique color, for up to 16 pre-set values.


Multi-Line Text Widget

Used by: None

* Does not use the Style Settings tag.

The Multi-Line widget is not linked to any tag. It can be found within the Widgets palette, within the Tools folder >> Standard sub-folder.

The properties dialog for the Multi-Line Text widget:

Reference: Advanced Formatting: Options for Properties

Font

Choose the Font tag that holds the font selection and other style settings for this text.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Text to Display

The editing dialog for the multi-line text.

Note that while text will wrap to fit the visible space, only those line breaks that you type are added to the text.

Vertical Alignment

Sets the position of the text within the display area. You may select top-aligned, bottom-aligned or centered. To align the overall widget with other elements on the page, see Align.

Horizontal Alignment

Sets the position of the text within the display area. You may select left-aligned, right-aligned or centered. To align the display area itself with other elements on the page, see: Alignment and Positioning Tools.

Horizontal and Vertical Alignment may be represented as an expression with a value of 0, 1 or 2.
0 = Left or Top
1 = Center
2 = Right or Bottom

Type of Border

The two border types simulate an area that is inset in the page or one that is a raised panel on top of the page.

Colors

Sets the color of the text and the background color, against which the text will be displayed.

Widget Folders:

Tools\Standard Library\

Text\

Related Tasks:

Text


Multi-Text Widget

Used by: I/O and Calculations, Allen Bradley driver, Alarm Status, Analog Input, Analog Status, Analog Output, Analog Control, Calculation, Counter, Data Flow RTU, CalAmp Diagnostic driver, DDE Client, Deadband Control, DNP3 driver, Driver Multiplexer, Function, History Statistics, MDS driver, Modem, Modbus Compatible Device , Omron driver, OPC Classic Client, Polling Driver, Rate of Change, Script, Selector Switch, Serial Port, Siemens S7 driver, SMS Appliance, SNMP driver, SQL Logger, Totalizer.

* Does not use the Style Settings tag.

The Multi-text tag widget displays a variety of messages, each in its own color, in response to changing conditions within the application.

You can create up to 16 messages using the Text 1 through Text 16 tabs. The Text 1 message is the default, to be shown when the defined conditions have not been met for any of the other messages.

The following example shows a multi-text display below a Linear Gauge widget. As the tag’s value increases, the multi-text displays a different value to either inform or direct the operator, and uses a different text color to catch the operator’s attention.

The Multi-text is configured by creating a series of increasing trigger points and assigning a color and message to display as each point is reached. The trigger points can be given constant values, or can take their value from either a tag or parameter.

The initial message, text 0, does not have a trigger point because it will be the text displayed until the tag’s value reaches the first assigned value. Two versions of the properties dialog for this widget are shown:

Reference: Advanced Formatting: Options for Properties

What happens if the set point for Text 3 is reached before that of Text 2?

If using constant values, you cannot assign a lower trigger point for a higher text number. This situation can occur if the trigger point for each text message is provided by different tags, parameters, or expressions.

The multi-text widget will display each defined message in order from Text 1 through to Text 16. The message and color for Text 1 will be displayed until the comparison condition for Text 2 has been reached. Until the set point for Text 2 has been reached, it does not matter whether any other comparison condition has been exceeded.

After the comparison for Text 2 has been passed, the multi-color will go on to check the comparison for Text 3. If it has already been passed, then the message for Text 2 will be skipped in favor of the message for Text 3.

The same comparison order is used whether the Tag's value is rising or falling.

Font

Select one of the font tags (or parameter linked to a font tag) that you wish to use to display the text. The display will use the default system font if you do not select a font tag.

The parameters button is enabled only if the tag is drawn on a page that includes a font parameter, or if the tag is part of a widget and the associated widget editor is open.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Text 1… Text 16 tabs

Select each tab in turn, up to the number of messages you wish to display. Each tab after Text 1 sets a trigger point using either a constant, tag or parameter, and message + color combination to display when that point is passed. Each consecutive tab used must set a greater trigger point than the previous.

Minimum Value for this Text

Shown only when Text 2 or greater is open. Sets the trigger point, above which the set color will be displayed (until the next trigger point is reached). The value for this point may be provide by any of a user-defined constant, an expression another tag or a parameter.

Text to Display

Enter the text that you want to have displayed when the tag’s value goes above this trigger point.

Text Color

Opens the Select Color Dialog from which you can select a color to display when the matching trigger point has been reached.

Horizontal Alignment

Configure the text to be left, center or right-aligned within the widget's bounding box.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Text\

Related information:

Choices for Operator Interaction

Multi-Color Widget - Display up to 16, solid colors for increasing values.


Multi-Write Button Widget

Used by: Multi-Write tag.

* Does not use the Style Settings tag.

The Multi-Write button is used to create a button, with which operators can trigger the operation of a Multi-Write tag.

The properties dialog for the Multi-Write button will appear as shown:

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Confirmation Dialog

If selected, the operator is required to confirm the control action before the configured values are written.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Multi-Variable\

Analytics\Communications\Output Controls\

Related information:

Choices for Operator Interaction

Multi-Write Tags


Multi-Write Hotbox Widget

Used by: Multi-Write tag

* Does not use the Style Settings tag.

The Multi-Write hotbox is used to create an area that operators can click within to trigger the operation of a Multi-Write tag.

The properties dialog for the Multi-Write Hotbox:

Hotbox Color

Select the color that will be used to show the hotbox area. Yellow is standard.

Confirmation Dialog

If selected, the operator is required to confirm the control action before the configured values are written.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Multi-Variable\

Analytics\Communications\Output Controls\

Related information:

Choices for Operator Interaction

Multi-Write Tags


Nautical Gauge Widget

Used by: Alarm Status, I/O and Calculations, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Nautical Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

Unlike other meters, Nautical Gauge provides the option of adding a label to the display

The properties dialog for the Nautical Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Label

Text to display on the meter. Due to font size limitations, a maximum of nine characters including spaces will be displayed. The label is centered, therefore clipping will occur on both sides if you provide more characters than will fit.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Network Link Widget

Used with: Network Status

* Does not use the Style Settings tag.

The Network Link tag widget is used to draw a line indicating the value of the associated Network Status tag. It can tell an operator whether the network link is active, broken or if its current status is unknown.

Use the properties dialog for the network link widget to select the line color, width and style for each status, as well as the line’s orientation on the page.

Broken Link, Active Link and Unknown

These three buttons all open the Select Pen dialog. Select the color, line style and pen width that you want to use to represent the Network Link line object for each matching state.

Pen Orientation

Select one of four orientations for the completed Network Link line object (horizontal, vertical, left 45 degrees, or right 45 degrees).

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Connection Status\

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


Next Poll Index Widget

Used by: Enron Modbus Driver

The properties dialog for the Next Poll Index widget:

Tag

The Tag field displays the name and description of the Enron Modbus tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

History Address

Provide the numeric value of the history address being monitored. History addresses typically start at 701.

Font

Select the font tag to be used to format the display. Defaults to the system font if none selected.

Horizontal Alignment

Controls whether the value is left, center or right-aligned within the space provided for the widget.

Colors

Select the colors to be used for the text and for the background of the widget. Defaults to black text on a transparent background.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Related information:

Enron Modbus Driver


Note List Widget

Used with: Notebook.

* Does not use the Style Settings tag.

Creates a display area on a page for notes that have been added to the associated Notebook tag. A scroll bar will be added to the right edge of the widget when there are more notes than will fit in the given area.

All the information in each note will be displayed, including the date and time when the note was recorded, the name of the operator, and the text of the note. New notes are added at the top of the list. Comments may be expanded or hidden within the list.

The display can be configured for color (text and background), font, etc. The properties dialog for the Note List widget:

Colors

Both the text color and the background color may be configured. Clicking either button will cause the Select Color dialog to open.

Font

Use the tag browser button to the right of this field to select the font with which the note will be displayed. If the current page contains Font tag parameters, then you may select from one of these.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Show border

Choose whether to add a border around the note display. Borders can be helpful to draw attention to an area and to delineate the note display from the rest of the page.

Show timestamp as age

By default, each entry in the list will show the date and time when it was created. You can choose to display the note's age instead.

Sort by most recently updated notes.

Controls whether the date of comments added to a note are considered when calculating the sorting order. If this option is not selected, sorting will be done only by the date of the original note, regardless of later comments.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Limit Notes

Limit the notes displayed in this widget to a specific time frame by a span of days. The smallest time frame, Display Today's Notes, will display all notes from midnight of the current date.

Widget Folders:

Basic Components\Specialty\Notebook


Numeric Entry Widget

Used by: I/O and Calculations (numeric data types), Analog Input tag, Analog Status, Analog Output, Analog Control, Counter, Selector Switch, Totalizer.

* Does not use the Style Settings tag.

The Numeric Entry widget is used to create an entry field into which operators may enter numeric values to write to the associated PLC or RTU. If the Questionable flag is set on the linked tag, the indicator will be displayed to the side of the text field, within its own box.

Attempts to enter text in this field will produce the following error message:

Value out of range. (Valid range is 0 to 100). Variable will revert to previous value.

This widget is most commonly used with I/O tags that have an analog or discrete data type. The minimum and maximum permitted values match the tag's configured Scaled Process Data Min and Scaled Process Data Max properties.

For a totalizer or counter tag, it can be used to allow the operator to set the value. In the case of a totalizer that is updating every second, this may prove to be impractical.

For a selector switch, this object provides a way to numerically set the switch position to 0, 1 or 2.

The properties dialog for the Numeric Entry widget:

This widget has a wide range of settings for its appearance and behaviour.

Reference: Advanced Formatting: Options for Properties

Display

Title

Provide text that will tell the operator what to use this Numeric Entry field for.

Font

Controls the display characteristics of the data entry field, but not the label. If you set individual characteristics using the Format ribbon, this will be an expression, combining those characteristics. Otherwise, select a font tag.

Draw Bevel

Select whether the completed object should be drawn with a beveled border. If the Draw Bevel check box is selected, the completed object will be drawn with a border surrounding it.

A beveled border appears as a faint, narrow grey line spaced evenly around the outside of the field. It will not cross through a label.

Show Units

Adds the units, as configured in the tag, to a box on the right of the data input field.

Mask Value

When selected, the value will be masked by asterisks rather than being displayed on the screen or in the event log. This option will most often be selected when the Numeric Entry is being used to write a password to a hardware device, thus preventing other users from discovering the password.

A masked value appears in a field labeled "Enter Password". The digits appear as redacted black dots as opposed to numeric characters.

Align Title

If selected, the title is included in the widget's bounding box.

If not selected, the title is above the widget's bounding box.

Use Tag's Digits After Decimal

Relevant only when linked to an I/O and Calculations tag. The linked tag controls the number of decimal values shown.

Digits After Decimal

Enabled only if the preceding option is not selected. Controls how many digits will be displayed after the decimal point. Has no effect on the number that the operator may enter.

Horizontal Alignment

By default, text is left-aligned within the edit field. You can choose to center or right-align the text instead. Does not affect the title.

Colors

Text Color

Select the color to be used for the input text. Does not apply to the label.

Background Color

Select the color to be used for the background of the input field. Does not apply to the label.

Note: Transparency cannot be applied to the background color.

Mismatch Color

Used only when the associated tag is a Selector Switch, or an Analog Input or Analog Status type, configured to write values. When the last value written does not match the value being read, the widget will display the configured mismatch color.

Options

Data Type

Choose between...

No Confirmation: The value is written when entered (usually by pressing Enter or Tab).

Confirmation Dialog: The operator must confirm the action before the value will be written.

Select Before Operate: Requires a separate Execute Button Widget. The operator must enter a new value in this widget to enable the output, then click the Execute button to complete the action. A Cancel button can be provided, thereby giving operators a chance to "disarm" the widget. (Execute / Cancel Button Widget)

Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Prompt for Date/Time

Enabled only for memory tags. Use when there is a need to record user-supplied data, where that data may have been collected over period of time leading up to the present. Both the collected values and the relevant date and time may be specified. The default date and time are "now" upon first use, following which, the last date and time supplied will be used for each subsequent entry.

When selected, a calendar icon is added to the widget.

A numeric field is displayed with the label "provide a value". A tiny calendar icon appears to the right of the field.

Click this to open the Select Date and Time dialog, where you can entry a value for the memory tag that will be associated with the date and time of your choice.

The Select Date and Time dialog shows a tag name, the calendar date, the current time and a field for the value. Everything but the tag name is editable.

Click the calendar button within this dialog to set the default to "today" and open a calendar from which you can select any date.

Click the time button within this dialog to set the default to "now". To set a different time, use the time entry fields or the up/down arrows to advance the time according to the currently selected portion of the field.

Forms

Include in Form

Select if this widget is to be included in a data entry form. If selected, this widget will interact with the submit, clear and date time selector widgets.

Time Offset

A numeric value that specifies the quantity of time offset. A time offset is added to a date selector offset. A 15 minute offset applied to an 11:00 AM submission will be recorded as 11:15 AM.

Time Units

A droplist that specifies the unit of time offset in minutes, hours, days or weeks.

Widget Folders:

Analog Controls\

Related information:

Choices for Operator Interaction


Numeric Value Widget

Used by: All driver tags, All analog tags and digital tags, Alarm Status, Calculation, Counter, Deadband Control, Function, History Statistics, Modem, Rate of Change, Script, Selector Switch, Serial Port, Totalizer, SQL Logger.

* Does not use the Style Settings tag.

The Numeric Value widget is used to display the current value of any of a tag as a number. Units (if any) will be displayed, depending on how you configure the object.

If the associated tag has a text value, it will not be displayed. If your tag is likely to have a text value, then use the Draw Text Widget instead.

The properties dialog for the Numeric Value object:

Properties dialog for the Numeric Value widget

Reference: Advanced Formatting: Options for Properties

Format

Data Type

May be any of: Decimal, Hex, Octal, or Binary. If a display format other than Decimal is chosen, the Integer Size drop-down will be enabled as will the option, Display Leading Zeros".

Use Tag's Digits After Decimal

Enabled only when the widget is linked, and the Data Type is Decimal. Typically used with I/O tags that have their own display properties set.

Digits After Decimal

Applies only to the Decimal display format. Controls how many decimal places will be shown in the display. Values will be rounded to the number set here.

Integer Size

Applies only to Binary, Octal and Hex display formats. May be any of: Byte, Word (two bytes), Dword (double word or 4 bytes) or Qword (quadruple word or 8 bytes)

Display Leading Zeros

Applies only to Binary, Octal and Hex display formats. If not selected, leading zeros for these values will be truncated. Leading zeros are not displayed for the Decimal display format.

Display Options

Font

Select one of the font tags (or parameter linked to a font tag) that you wish to use to display the text. The display will use the default system font if you do not select a font tag.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Horizontal Alignment

Sets the position of the text within the display area. You may select left-aligned, right-aligned or centered. To align the display area itself with other elements on the page, see: Alignment and Positioning Tools.

Vertical Alignment

Sets the position of the text within the display area. You may select top-aligned, bottom-aligned or centered. To align the overall widget with other elements on the page, see Align.

Horizontal and Vertical Alignment may be represented as an expression with a value of 0, 1 or 2.
0 = Left or Top
1 = Center
2 = Right or Bottom

Show Units

Controls whether the tag’s engineering units (if set) will be shown as part of the display.

Colors

Text, Background, and Outline

Opens the Select Color Dialog from which you can select the color of the text (defaults to black), the background (defaults to transparent), and the outline (defaults to transparent).

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Basic Components\Text\


ODBC Statistics

Not linked to any tag.

The Show Stats widget for the ODBC manager provides a click-able button that operators can use to view connection statistics.

The drop-down menu will include a list of all ODBC connections used by this application.

Note that you cannot view a saved history of diagnostic information until you use this dialog to disable logging.

The properties dialog for the ODBC Manager Show Stats widget:

Button Label

Change the label to describe which statistics are shown.

Widget Folders:

Tools\ODBC Manager

Analytics\Statistics


Oil & Gas Solutions Widgets

Widgets in this section were designed for use with the Oil & Gas Solutions layer, but may be used with any compatible tag.


Compressor (Dynamic) Widget

Used by: Digital Status, I/O and Calculations

* Can use properties from a Style Settings tag.

The Compressor (Dynamic) widget is used to display a compressor image that changes color according to whether the linked equipment is running. The colors are specified by the associated Style Settings tag. Note the existence of the tag, System Style O&G, for use by tags and widgets from the Oil and Gas Solutions layer.

The properties dialog for the Compressor (Dynamic) object:

Style

Optionally, select a Style Settings tag to control the colors shown by the light, in response to the linked tag's value and alarm state. See: Style Settings Tags

Invert States

When selected, the widget will show the running color for a value of 0 and the stopped color for a value of 1.

Running Text

Label to display when the linked tag is in the running state.

Stopped Text

Label to display when the linked tag is in the stopped state.

Label Position

Use the grid of selection boxes to set the position of the label relative to the widget image.

Optionally, use the Disable Label option to prevent the label from being displayed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Equipment (Dynamic)


Compressor (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Compressor (Static) widget is used to display a compressor image.

The properties dialog for the Compressor (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


Control Valve (Dynamic)Widget

Used by: Analog Status, Calculation, Analog Control, I/O and Calculations

* Can use properties from a Style Settings tag.

The Control Valve (Dynamic) widget is used to display a control valve image that changes color according to whether the valve is open or closed. It expects to be linked to a tag with a value that ranges from 0 to 100. The valve appears open when the link tag's value is greater than 95%, closed when it is less than 5%, and traveling otherwise. The colors are pre-configured and consistent with other Oil & Gas Solutions widgets. Note the existence of the tag, System Style O&G, for use by tags and widgets from the Oil and Gas Solutions layer.

Below the widget, a numeric value field will display the current value of the linked tag and below that will be text indicating whether the valve is open (non-zero) or closed (value of zero).

The properties dialog for the Control Valve (Dynamic) object:

Style

If no labels are entered for the OpenText, Closed Text or Travel Text parameters then this widget will default the labels to those in the Digitals section of the selected style tag. See: Style Settings Tags

Digits After Decimal

Defaults to 0.

Show Units

When selected, the units configured in the linked tag are shown following the value.

Invert States

When selected, the widget will appear in the open state for values less than 5 and in the closed state for values greater than 95.

Rotated

When selected, the valve image is shown rotated by 90 degrees clockwise. The value and the label remain horizontal.

Open Text

Label to display when the valve is in the open state.

Closed Text

Label to display when the valve is in the closed state.

Travel Text

Label to display when the valve is in a state of travel.

Label Position

Use the grid of selection boxes to set the position of the label relative to the widget image.

Optionally, use the Disable Label option to prevent the label from being displayed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Equipment (Dynamic)


Control Valve (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Control Valve (Static) widget is used to display a control valve image.

The properties dialog for the Control Valve (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Rotated

When selected, the image is rotated 90 degrees clockwise.

Widget Folders:

Oil & Gas\Equipment (Static)


Digital Text with Label

Used by: Digital Status, I/O and Calculation in digital mode.

* Does not use the Style Settings tag.

The Digital Text with Label widget is similar to the Numeric Display with Label widget, but displays the text configured in the Digital Status tag, or a custom label, defaulting to On or Off.

The properties dialog for the Digital Text with Label widget:

Label Alignment

Select whether the label should be right, center, or left-aligned within the space assigned to it.

Label on Right

If selected, the label will be placed to the right of the value instead of its default position on the left.

Custom Off Label

A label to display in place of what is configured in the tag. Defaults to "Off" if no label is available from the tag.

Custom On Label

A label to display in place of what is configured in the tag. Defaults to "On" if no label is available from the tag.

Custom Label

By default, the linked tag's description is shown. Use this field to specify an alternate label.

Box Width

Small -> the box displaying the value is the same size as the widget's bounding box.

Medium -> the box is approximately 1.5 times the width of the bounding box.

Large -> the box is approximately 2 times the width of the bounding box.

Label Width

Sets the space, in pixels, of the area available for the label. If there are more characters than will fit in the available width, they will be scaled to fit.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Digitals


Discrete Valve (Dynamic)Widget

Used by: I/O and Calculations, Digital Status, Analog Status, Calculation, Analog Control

* Can use properties from a Style Settings tag.

The Discrete Valve (Dynamic) widget is used to display a discrete valve image that changes color according to whether the linked valve is open. The colors are pre-configured and consistent with other Oil & Gas Solutions widgets. Below the image, a label shows the current state of the valve. Note the existence of the tag, System Style O&G, for use by tags and widgets from the Oil and Gas Solutions layer.

The properties dialog for the Discrete Valve (Dynamic) object:

Style

If no labels are entered for the OpenText, Closed Text or Travel Text parameters then this widget will default the labels to those in the Digitals section of the selected style tag. See: Style Settings Tags

Open State

Value that signifies the open state.

Closed State

Value that signifies the closed state.

Travel State

Value that signifies the travel state.

Rotated

When selected, the valve image is rotated 90 degrees clockwise. The label remains horizontal.

Open Text

Label to display when the linked tag is in the open state.

Closed Text

Label to display when the linked tag is in the closed state.

Travel Text

Label to display when the linked tag is in a state of travel.

Label Position

Use the grid of selection boxes to set the position of the label relative to the widget image.

Optionally, use the Disable Label option to prevent the label from being displayed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Equipment (Dynamic)


Dynacard Display Widget

Used by: Pump Off Controllers

* Does not use the Style Settings tag.

This widget holds most of the content of the Dynacard Display page. If choosing to draw this widget on a page of your own, be sure to stretch it large enough to display all of the tools, some of which will not be visible at the default widget size.

The properties dialog for the Dynacard Display widget

Draw Header

Controls whether toolbar is shown.

Draw Setpoints

Part of the tabbed display of Cards, Setpoints, Timeline.
Controls whether the Setpoints tab is included.

Draw Card List

Part of the tabbed display of Cards, Setpoints, Timeline.
Controls whether the Card List tab is included.

Draw Timeline

Part of the tabbed display of Cards, Setpoints, Timeline.
Controls whether the Timeline tab is included.

Enable Slippy Functionality

Select to enable the slippy-map-like pan and zoom functions.

Show Graph Setpoints

Select to display the force and position setpoints as lines or points on the Dynagraph.

Display Tabs on Right

Moves the tabbed display to the left when deselected.

Display X Card / Number of Cards

Use the tab appropriate to the type of POC represented by this widget (Lufkin SAM or Unico / Weatherford).

Provides control over which cards to display and the number of each.

Widget Folders:

Oil & Gas\Pump Off Controller


Dynacard Page Button Widget

Used by: Dynacard tags.

* Does not use the Style Settings tag.

The Dynacard Page Button widget is used to display button that operators can use to navigate to the built-in Dynacard page for the linked tag.

The Dynacard page is built into VTScada's Oil and Gas Solutions layer. By linking the button to a Dynacard tag, you configure which Dynacard will be shown on that page when the operator clicks on or presses this navigation tool.

The properties dialog for the Dynacard Page Button object:

Button Label

Choose a label for the button. Defaults to "Dynacard".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Pump Off Controller


Dynacard Page Hotbox Widget

Used by: Dynacard tags.

* Does not use the Style Settings tag.

The Dynacard Page Hotbox widget is used to display hotbox that operators can use to navigate to the built-in Dynacard page for the linked tag.

The Dynacard page is built into VTScada's Oil and Gas Solutions layer. By linking the hotbox to a Dynacard tag, you configure which Dynacard will be shown on that page when the operator clicks on or presses this navigation tool.

The properties dialog for the Dynacard Page Hotbox object:

Hotbox Color

Choose a color for the hotbox. Note that this is seen only when the pointer is over the area of the hotbox.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Pump Off Controller


Fan (Dynamic) Widget

Used by: Digital Status, I/O and Calculation

* Can use properties from a Style Settings tag.

The Fan (Dynamic) widget is used to display a fan image that changes color according to whether the linked equipment is running. The colors are pre-configured and consistent with other Oil & Gas Solutions widgets. Note the existence of the tag, System Style O&G, for use by tags and widgets from the Oil and Gas Solutions layer.

The properties dialog for the Fan (Dynamic) object:

Style

If no labels are entered for the OpenText, Closed Text or Travel Text parameters then this widget will default the labels to those in the Digitals section of the selected style tag. See: Style Settings Tags

Invert States

When selected, the widget will show the running color / text for a value of 0 and the stopped color / text for a value of 1.

Running Text

Label to display when the linked tag is in the running state.

Stopped Text

Label to display when the linked tag is in the stopped state.

Label Position

Use the grid of selection boxes to set the position of the label relative to the widget image.

Optionally, use the Disable Label option to prevent the label from being displayed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Equipment (Dynamic)


Fan (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Fan (Static) widget is used to display a fan image.

The properties dialog for the Fan (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


Flat Vertical Separator (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Flat Vertical Separator (Static) widget is used to display a flat vertical separator image.

The properties dialog for the Flat Vertical Separator (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


FBx Series DNP3 Driver File Read Sequence Info

Used by: FBx Series DNP3 driver tag

The FBx Series DNP3 Driver File Read Sequence Info widget will create a button that will open a table displaying the driver reads.

File Type

This is the file type that was being looked for during the read. (Ex. history, alarm & events)

Instance

The instance corresponds to a specifications table provided by Emerson.

Last Sequence Read

Each available record is ordered by sequence. The last sequence read denotes the most recent record received in sequence.

Newest Sequence Available

If there are new records available they will have a higher sequence number than the last sequence read. By default, the read will include all new records after the last sequence read up to the newest sequence available.

Last Read Record TS

A time stamp from the last read record.

Reset

"Reset Sequence" will reset last sequence read to 0 and the next read will retrieve every sequence up to the newest sequence available.

The properties dialog for the FBx Series DNP3 Driver File Read Sequence Info widget:

Link your FBx Series DNP3 Driver tag, customize the button label or disable selected operator features.

Button Label

Text to display on the button

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Miscellaneous


FBx Series DNP3 Driver Stats Dialog

The Show Statistics Button Widget button will display the following information about a FBx Series DNP3 driver tag:

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Located in Idea Studio under Analytics > Diagnostics > Comm Stats Btn

Related information:

FBx Series DNP3 Driver Tag


Flow Computer Alarm/Event/History List

Used by: Flow Computer or Meter Test Run.

* Does not use the Style Settings tag.

This widget is part of the Flow Computer Site Details page (Events tab), and is not usually drawn independently.

Note the top row, which is a header. The text will vary depending on the selected DataType (Alarms, Events, Hourly Values or Daily Values). The arrow at the right of each column in the header row (example shows only one) allows operators to sort the list in ascending or descending order.

Calendar controls

Allow the operator to select a range of dates between a defined start and end.

Refresh

This list shows historical data. Use the Refresh button to include events that were loaded from the RTU since displaying the list.

Read Logs

Will force a poll of the RTU when selected. Protected by a user-privilege, selected in the linked tag.

Copy All

Copies the entire data set to the Windows clipboard. Protected by a user-privilege, selected in the linked tag.

Export

Exports the data set to a comma-separated values (CSV) file. The operator will be prompted for the file's name and location. Protected by a user-privilege, selected in the linked tag.

The properties dialog for the Flow Computer Alarm/Event/History List widget:

UseTheme

By default, the control is shown using the application's color theme. If deselected, the control will be shown using the Grey theme.

DataType

In a Site Page, where this widget would normally be drawn, each of the following tabs contains an instance of this widget with a different DataType value. (Tab order does not match the numeric order of DataType values.)

Widget Folders:

Oil & Gas\Flow Computer


Flow Computer Site Draw Widget

Used by: Flow Computer, POC-DV8, POC-Lufkin SAM Well Manager, POC-Unico, Weatherford

* Does not use the Style Settings tag.

The Flow Computer Site Draw widget is used to display a site icon, indicating the current state of the linked tag. Optionally, this can also be used as a navigational tool, opening a selected page in response to an operator's click.

The properties dialog for the Flow Computer Site Draw object:

Use Theme Color

Select to use the application's theme color with the associated site page.

Text Color

Assign the color to be use for the foreground text color within the page.

Click action

This widget can do any of the following in response to an operator's click:

  • Nothing.
  • Open the default Site Page as a pop-up window.
  • Open a custom page. Note that this page should take a Flow Computer tag as a parameter.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:


Flow Computer Manual Poll Widget

Used by: Flow Computer

* Does not use the Style Settings tag.

The Manual Poll widget is used to display a button that operators can use to force a poll on demand.

A range of polling options is possible. You can configure this button to poll any combination of:

  • Process data
  • Daily History
  • Hourly History
  • Alarm and Events

The properties dialog for the Manual Poll object:

Button Label

Text to display on the button

Poll Process

Text to display on the button

Poll Daily History

Text to display on the button

Poll Hourly History

Text to display on the button

Poll Alarm and Events

Text to display on the button

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Flow Computer\Communications


Flow Computer Multisite Manual Poll

Used by: Flow Computer

* Does not use the Style Settings tag.

The Multisite Manual Poll widget is a specialized version of the manual poll button that can be configured to read any combination of your flow computer’s process data, history, or the alarm and event logs with a single button press from the user

A range of polling options is possible. You can configure this button to poll any combination of:

  • Process data
  • Daily History
  • Hourly History
  • Alarm and Events

The properties dialog for the Manual Poll object:

Button Label

Text to display on the button

Poll Process

Select to poll process data

Poll Daily History

Select to poll daily history

Poll Hourly History

Select to poll hourly history

Poll Alarm and Events

Select to poll the alarm and event logs

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Flow Computer\Communications


Flow Meter Details Widget

Used by: Flow Computer tags, Meter Run tags

* Does not use the Style Settings tag.

This widget is used as a portion of the Flow Meter Site Details page. It includes the Alarm and Event (AE) History list, Notes and Maps.

The properties dialog for the Flow Meter Details Widget:

Use Theme Color

If selected, the widget's title bar and background will follow your application's theme color. Gray otherwise.

Text Color

Select the color to use for text. Since most theme colors are dark, this should be light.

Font

Select one of the font tags (or parameter linked to a font tag) that you wish to use to display the text. The display will use the default system font if you do not select a font tag.

Disable the X Tab

Use these eight options to select which tabs should be shown in the widget.

Widget Folders:

Oil & Gas\Flow Computer


General Numeric with Label

Used by: All analog inputs, Calculation

* Does not use the Style Settings tag.

The General Numeric with Label widget is similar to the Numeric Value widget, but by default will include the linked tag's description as the label. Any alternate label may be specified.

The properties dialog for the Numeric Display with Label object:

Value Alignment

Select whether values should be right, center, or left-aligned within the frame.

Label Alignment

Select whether the label should be right, center, or left-aligned within the space assigned to it.

Show Units

Select whether units, as configured in the linked tag, should be shown.

Label on Right

If selected, the label will be placed to the right of the value instead of its default position on the left.

Display Label

Deselect if you prefer to show only the value, without an identifying label.

Digits after Decimal

Controls the number of digits to be shown. Does not recognize the display configuration of linked I/O tags.

Custom Label

By default, the linked tag's description is shown. Use this field to specify an alternate label.

Box Width

Small -> the box displaying the value is the same size as the widget's bounding box.

Medium -> the box is approximately 1.5 times the width of the bounding box.

Large -> the box is approximately 2 times the width of the bounding box.

Label Width

Sets the space, in pixels, of the area available for the label. If there are more characters than will fit in the available width, they will be scaled to fit.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Analogs


Generic Driver Statistic Widget

* Does not use the Style Settings tag.

Displays selected communications information about a driver, such as the current error state, the last error or the success count. This can be used to build customized communications screens or widgets, based on the communications information that is most relevant to your process.

The properties dialog for the Generic Driver Statistic object:

Poll Type

Appearing only when this widget is linked to a flow computer tag, this parameter allows you to specify the flow computer driver(s) that this widget should apply to. For example, you may want statistics on just the daily history communications, on all history communications, or on all communications with the flow computer of any kind.

Statistic

Select one of the Communication Driver Log-Enabled Variables, or its label.

Font

Select the Font tag that will control the appearance of text within the field.

Vertical Alignment / Horizontal Alignment

Controls the alignment of text within the widget's bounding box.

Color - Foreground and Background

Set the color to be used by text in the field and the background color of the field itself.


Meter Run Summary Widget

Used by: Meter Run tags.

* Does not use the Style Settings tag.

The Meter Run Summary widget is the same widget that is drawn on the Flow Computer tag’s site details page.

The properties dialog for the Meter Run Summary object:

Use Theme Color

If selected, the widget's title bar and background will follow your application's theme color. Gray otherwise.

Text Color

Color for the text foreground. If the theme is dark, choose a pale shade.

Font

Select one of the font tags (or parameter linked to a font tag) that you wish to use to display the text. The display will use the default system font if you do not select a font tag

Widget Folders:

Oil & Gas\Flow Computer


Meter (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Meter (Static) widget is used to display a meter image.

The properties dialog for the Meter (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


Numeric Entry with Label

Used by: All analog inputs, Calculation

* Does not use the Style Settings tag.

The General Numeric Entry with Label widget is similar to the Numeric Entry widget, but by default will include the linked tag's description as the label. Any alternate label may be specified.

The properties dialog for the Numeric Entry with Label object:

Value Alignment

Select whether values should be right, center, or left-aligned within the frame.

Label Alignment

Select whether the label should be right, center, or left-aligned within the space assigned to it.

Show Units

Select whether units, as configured in the linked tag, should be shown.

Label on Right

If selected, the label will be placed to the right of the value instead of its default position on the left.

Show Confirmation Dialog

Select in order to prompt operators for confirmation after they enter a new value.

Digits after Decimal

Controls the number of digits to be shown. Does not recognize the display configuration of linked I/O tags.

Custom Label

By default, the linked tag's description is shown. Use this field to specify an alternate label.

Box Width

Small -> the box displaying the value is the same size as the widget's bounding box.

Medium -> the box is approximately 1.5 times the width of the bounding box.

Large -> the box is approximately 2 times the width of the bounding box.

Label Width

Sets the space, in pixels, of the area available for the label. If there are more characters than will fit in the available width, they will be scaled to fit.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Analogs


Tag Order Change Widget

* Does not use the Style Settings tag.

Used to allow operators to change the order of the listed tags.

The properties dialog for the Tag Order Change object:

Sort Variable Name

Defines which variable within the tag is to be used for sorting.

List Scope

Name Filter

Use to limit the selection to tags whose name matches the filter. May include wildcards.

Area Filter

Use to limit the selection to tags whose area property matches the filter. May include wildcards.

Type

Use to limit the selection to tags whose type matches the filter. May include wildcards.

Column 1 Title

Set the title of the first column.

Column 1 Variable

Provide the name of the tag variable to be shown in the first column.

Column 2 Title

Set the title of the second column.

Column 2 Variable

Provide the name of the tag variable to be shown in the second column.


Page Close Widget (OGS)

* Does not use the Style Settings tag.

Closes the current page. Works only when drawn on a pop-up (windowed) page.

The only user-configurable properties for this widget are the label and tooltip:

Widget Folders:

Oil & Gas\Page Tools


Page List Widget

Used by: User-defined tag types with matching parameterized pages.

* Does not use the Style Settings tag.

The Oil & Gas Solutions (OGS) page list widget is a navigational control, designed to work with parameterized OGS display pages. It allows the operator to jump to a given site in a list without needing to reopen the page menu. (In other words, it re-opens the page with a new value for the site parameter.)

This widget can be extensively customized, but its configuration requires planning and an in-depth knowledge of your application’s tag structure.

As an illustration, refer to the partial tag tree shown in the following image. In this example, each Site is a user-defined type, given the type name "SiteType". This will be relevant to the explanation of the button parameters.

Assume that a parameterized page exists for a “SiteType”, displaying tags within that site. Drawing the Page List widget on that page and configuring it with the parent tag, Bedford East, will allow an operator to step through Sites 1 through 4 (and optionally, Station X, which is also a SiteType) without leaving the page and without needing to access the page menu.

The properties dialog shown here is configured for above example of Bedford East sites. "SiteChoice" is the name that was given to the page's parameter.

Current Tag

Used by the widget to keep track of which site is being shown. In almost all cases, this should be the page parameter, through which the site is passed, as shown in the example image.

This parameter is mandatory, and the widget button will be grayed out unless a valid tag (parameter) has been selected.

Label

Provide text that identifies the purpose of the list.

List Context

Type in the full (absolute) path and name of the tag that is the parent of the sites you want to step through. In the provided example, this is Bedford\Bedford East.

Display Name Parameter

The name of the tag parameter that you want to display in the list, identifying one site from another.

Typically, this will be ShortName, although Name is sometimes used in order to provide more context. To display the description of each site instead of the name, wrap the parameter name in a \GetPhrase() call: \GetPhrase(Description).

A parameter from your custom tag type could also be used.

Type

A filter to identify the tag type matching the parameter. In the provided example, the user-defined type was named "SiteType". (This is not a standard VTScada type.)

If not provided, all child tags of the identified context will be used, some of which may not be appropriate for the page parameter.

If the type is set to Context, then further filtering is likely to be necessary.

Name Filter

An optional parameter to limit the list to sites with names matching the filter. Wildcards (*) should be included. In the provided example, four of the sites follow a pattern, Site N, but one is named Station X instead. If no name filter is provided, all five site tags will be shown as the operator steps through the list.

A name filter such as Site* would exclude the site name Station X.

Area Filter

An optional parameter to limit the list to sites with area properties matching the filter. Wildcards (*) may be included.

Page

Typically, the name of the page upon which this navigational button is drawn. As shown in the example, do not configure the parameter for this use case. Use the page selection tool rather than typing the page name.

If left blank, the list will navigate to the default VTScada Sites List Display Options

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:


POC Manual Process Poll Widget

Used by: Pump Off Controller tags

* Does not use the Style Settings tag.

The Manual Poll widget is used to display a button that operators can use to force a poll on demand.

Unlike the manual poll widget for the Flow Computer, the only user-configurable options are the label and the standard disable options.

The properties dialog for the Manual Poll object:

Button Label

Text to display on the button

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Flow Computer\Communications


Polling Indicator Widget

Used by: Flow Computer, Dynacard Input, Polling Driver, POC- DV8, POC-Lufkin SAM Well Manager, POC-Unico, Polling Control, Weatherford

* Does not use the Style Settings tag.

The Polling Indicator widget is used to display a symbol that is animated and gray while polling is in progress and otherwise still and red.

No configuration is available for this widget other than the standard options to disable aspects of operator interaction.

Widget Folders:

Oil & Gas\Flow Computer\Communications


Polling Overview Widget

Used by: Polling Drivers

* Does not use the Style Settings tag.

If you have a lot of wells in the same polling group, it can be useful to know which well is being polled at any given time.

The Polling Overview widget allows you to select a polling group, and it will then show you the well in that group that is being polled. This widget follows your VTScada color theme.

MyPollGroupLabel

The name of the polling group monitored by this widget.

Use Parent Description

Choose whether to display the description field from the parent tag.

Display Station Number

Choose whether to display the station number associated with this polling group

Widget Folders:

Oil & Gas\Flow computer\Communications


Polling Status Widget

Used by: Flow Computers

* Does not use the Style Settings tag.

This widget shows the aggregated polling status of the four drivers underneath the Flow Computer tag. It shows a description of the Flow Computer tag (or the tag’s parent), the polling status icon and the data age. This widget follows your VTScada color theme.

The properties dialog for the Polling Status object.

Use Parent DescriptionButton Label

Select this to use the tag's parent's description in the text display instead of the tag's own description

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Flow Computer\Communications


Prev/Next Page Widget

Used by: User-defined tag types with matching parameterized pages.

* Does not use the Style Settings tag.

The Oil & Gas Solutions (OGS) page change widget is a Next Page / Previous Page navigational control, designed to work with parameterized OGS display pages. It allows the operator to cycle through a number of similar sites without needing to reopen the page menu. (In other words, it re-opens the page with a new value for the site parameter.)

This widget can be extensively customized, but its configuration requires planning and an in-depth knowledge of your application’s tag structure.

As an illustration, refer to the partial tag tree shown in the following image. In this example, each Site is a user-defined type, given the type name "SiteType". Bedford East and Bedford West are also user-defined types, given the type name, "LocationType". This will be relevant to the explanation of the button parameters.

Assume that a parameterized page exists for a “SiteType”, displaying tags within that site. Drawing the Prev/Next Page widget on that page and configuring it with the parent tag, Bedford East, will allow an operator to step through Sites 1 through 4 (and optionally, Station X, which is also a SiteType) without leaving the page and without needing to access the page menu.

You might also use this button as a link to open one parameterized page from another.

The properties dialog shown here is configured for above example of Bedford East sites. "SiteChoice" is the name that was given to the page's parameter.

Current Tag

Used by the widget to keep track of which site is being shown. In almost all cases, this should be the page parameter, through which the site is passed, as shown in the example image.

This parameter is mandatory, and the widget button will be grayed out unless a valid tag (parameter) has been selected.

Button Label

The button will advance in only one direction. Specify whether this is Next or Previous according to the Action.

Action

If this button is used to open one parameterized page from another, then you would likely want to view the current site in the newly opened page.

Otherwise select Next or Prev to choose the order in which this button will step through the sites.

Prev/Next Tag Context

Type in the full (absolute) path and name of the tag that is the parent of the sites you want to step through. In the provided example, this is Bedford\Bedford East. If you had selected Bedford instead, then sites under both Bedford East and Bedford West would be available.

Type

A filter to identify the tag type matching the parameter. In the provided example, the user-defined type was named "SiteType". (This is not a standard VTScada type.)

If not provided, all child tags of the identified context will be used, some of which may not be appropriate for the page parameter.

If the type selection is set to Context, then further filtering is likely to be necessary.

Name Filter

An optional parameter to limit the list to sites with names matching the filter. Wildcards (*) should be included. In the provided example, four of the sites follow a pattern, Site N, but one is named Station X instead. If no name filter is provided, all five site tags will be shown as the operator steps through the list.

A name filter such as Site* would exclude the site name Station X.

Area Filter

An optional parameter to limit the list to sites with area properties matching the filter. Wildcards (*) may be included.

Page Root Scope Level

Needed in the rare case where the parameter configured for the page is a grandparent to the sites through which the button should step. For example, if the parameter linked to the grandparent tag (Bedford in this example) and yet the page is to step through SiteTypes, then the root scope is one level removed. For this example, you would enter a 1 here.

Page

Typically, the name of the page upon which this navigational button is drawn. As shown in the example, do not configure the parameter for this use case. Use the page selection tool rather than typing the page name.

You might use this to link one parameterized page to another, passing along the currently shown site as the parameter (in which case the action would be "Current"), or some other tag selection.

If left blank, the button will navigate to the default VTScada Sites List Display Options

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:


Pump (Dynamic) Widget

Used by: Digital Status, I/O and Calculations

* Can use properties from a Style Settings tag.

The Pump (Dynamic) widget is used to display a pump image that changes color according to whether the linked equipment is running. The colors are pre-configured and consistent with other Oil & Gas Solutions widgets. Below the image, a label shows the current state of the pump. Note the existence of the tag, System Style O&G, for use by tags and widgets from the Oil and Gas Solutions layer.

The properties dialog for the Discrete Valve (Dynamic) object:

Style

If no labels are entered for the OpenText, Closed Text or Travel Text parameters then this widget will default the labels to those in the Digitals section of the selected style tag. See: Style Settings Tags

Mirror Image

When selected, the pump is shown connected to the left rather than to the right.

Invert States

When selected, the widget will show the running color / text for a value of 0 and the stopped color / text for a value of 1.

Running Text

Label to display when the linked tag is in the running state.

Stopped Text

Label to display when the linked tag is in the stopped state.

Label Position

Use the grid of selection boxes to set the position of the label relative to the widget image.

Optionally, use the Disable Label option to prevent the label from being displayed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Equipment (Dynamic)


Pump (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Pump (Static) widget is used to display a pump image.

The properties dialog for the Pump (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


Report Display AE Data Widget

Used by: Flow Computer tags, Meter Run tags

* Does not use the Style Settings tag.

This widget is used as a portion of the Flow Meter Site Details page. It provides the Alarm and Event (AE) History list.

The properties dialog for the Report Display AE Widget:

Use Theme Color

If selected, the widget's title bar and background will follow your application's theme color. Gray otherwise.

Data Type

Select from: Event Report, Alarm Report, Hourly Report, or Daily Report.

Widget Folders:

Oil & Gas\Flow Computer


Reset Statistics Widget

Used by: Flow Computers

* Does not use the Style Settings tag.

Communications statistics, such as the number of successful communications and the number of errors, are tracked by the Flow Computer tag. This button resets those statistics for one, several, or all four of the Flow Computer tag’s drivers.

The properties dialog for the Reset Statistics object. Note that you may choose to reset more than one statistic.

Button Label

Text to be displayed on the button so that operators know its purpose.

Reset Process

Select to reset the stats of the process driver when the button is clicked.

Reset Daily History

Select to reset the stats of the daily history driver when the button is clicked.

Reset Hourly History

Select to reset the stats of the hourly history driver when the button is clicked.

Reset Alarm and Events

Select to reset the stats of the alarm and events driver when the button is clicked.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Oil & Gas\Flow Computer\Communications


Separator (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Separator (Static) widget is used to display a separator image.

The properties dialog for the Separator (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


Tag Variable Droplist Widget

* Does not use the Style Settings tag.

This widget is configured using only parameters, and is not linked to any tag. It allows you to set a value (usually a page parameter) from a list of related values (tags or tag parameters). Whatever the user selects from the droplist is set as the value of the item specified in the widget’s ValueToSet parameter.

This is an advanced widget. Successful configuration requires you to have a detailed knowledge of your tag structure and their properties at a code level.

As an example, given the following tag structure:

The description of the widget's properties will refer to this tag structure as an example.

Value to Set

The value that is going to be changed by the droplist selection. Note that this parameter should be a direct link to an object value, not a text value or other constant. Most commonly, this will be a link to a page parameter as shown here.

Title

The label that is displayed above the droplist.

LabelVar

The tag variable that will be used to provide the label for each element in the droplist. After a list of tags is found (using the filtering parameters below) the widget will look in each of those tags for this variable, using that as the label in the drop list. For example, if “Description” is entered in the LabelVar field, then each of the tags’ descriptions will be shown in the drop list.

ValueVar

The tag variable that will be provided to the ValueToSet parameter after a selection is made in the droplist. After a list of tags is found (using the filtering parameters below), and one of those tags is selected from the list, the widget will look in that tag for this variable and will provide that value to whatever has been selected in the ValueToSet parameter. For example, if “Name” is entered in the ValueVar field, and a “SiteName” (a text page parameter) is select-ed as the ValueToSet parameter, then when a tag is selected from the droplist the SiteName page parameter will be set to the name of the selected tag.

TagType

A filter used to limit the displayed tags to a certain type. In the provided example, if the Site tags were a user-defined tag type, then selecting that type would be enough to limit the displayed to just the ones we want. If the Site tags are standard context tags, however, we will need to provide further filtering using the parameters below in order to exclude the Station X tag.

ListScope

Defines the context for the tags that are to be shown in the drop list. In the provided example, we have a few choices. If we want to display only the Sites in East Bedford, ignoring those in the west, we would enter “Bedford\East Bedford” as the context. If we wanted to display all Sites in both the east and the west, we would enter “Bedford” as the context.

Name Filter

Used to limit the drop list to tags which contain a particular set of characters in their tag names. An asterisk (*) may be used as a wildcard character. In our example, using a name filter of “*Site*” would include all of the Site tags but would exclude the Station X tag.

Area Filter

Used to limit the drop list to tags with a particular Area property.

LimitTags

Used to show only those tags at the current level of the tag tree (as defined by the ListScope parameter). If this is unchecked, child tags below that level may also be shown.

FirstElementLabel

Used to manually control the first element in the droplist. If this parameter is valid, it will appear at the top of the list (before all of the tags).

FirstElementValue

Used to manually control the first element in the droplist. If FirstElementLabel is valid and is selected from the list, this is the value that will be sent to the page parameter selected as the ValueToSet parameter.

Widget Folders:

Oil & Gas\Miscellaneous


Tank (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Tank (Static) widget is used to display a tank image.

The properties dialog for the Tank (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


TeleBUS Statistics Dialog

The Show Stats button will display the following information about a TeleBUS driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Related information:

TeleBUS Driver Tags


Discrete Valve (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Discrete Valve (Static) widget is used to display a discrete valve image.

The properties dialog for the Discrete Valve (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Rotated

When selected, the image is rotated 90 degrees clockwise.

Widget Folders:

Oil & Gas\Equipment (Static)


Vertical Separator (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Vertical Separator (Static) widget is used to display a vertical separator image.

The properties dialog for the Vertical Separator (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


Wellhead (Static) Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Wellhead (Static) widget is used to display a wellhead image.

The properties dialog for the Wellhead (Static) object:

Color

Assign a specific color, create an expression, or select a tag whose value can be used for a color. (VTScada Color Palette)

Widget Folders:

Oil & Gas\Equipment (Static)


Well Search Widget

* Does not use the Style Settings tag.

The Well Search widget does not link to any tag. You must configure is using parameters.

Operators can use this to search through all of the Flow Computer tags in the application using both name and area filters.

By default, the description of each Flow Computer tag is shown in the search results field. Depending on your tag structure you may want to re-configure the widget to use the description of the Flow Computer’s parent tag instead. This widget follows your VTScada color theme.

The properties dialog for the Well Search object:

Use Parent Description

Select this option if your tag configuration is such that it makes more sense to use the description of the Flow Computer's parent tag. Note that this does not affect which tags are searched, only the text that is displayed.

Widget Folders:

Oil & Gas\Flow Computer


Well Test Table Widget

Used by: Well Test tags

The Well Test Table widget is used to display the test records gathered by Well Test Tags, and to allow operators to make changes. Many of the settings of this table are determined not by the widget parameters but rather by the parameters of the linked well test tag itself.

Operators can select start and end dates, refresh the information and export the displayed data to a CSV format file.

Entries in the Well LSD field are editable if the linked tag has been configured to allow editing. (WellTest tag Misc tab)

The last column of each record is the Test State. New test records start off in the Held state, but can be moved to Accepted or Rejected by the operator after the data has been reviewed.
If any of the columns were designated as being editable when the well test tag was configured, the operator can edit them directly by clicking on the field. After these changes are saved, the User Edited column will indicate that changes have been made. The User column will show the VTScada user name of the person who last made changes to the record.

The properties dialog for the Well Test Table object:

Hide Well Test Table Filter

The filter allows operators to choose between showing all wells or viewing only one selected well. You have the option of removing this choice.

Digits After Decimal

This applies only to the Decimal display format. It controls how many decimal places will be displayed in a range of 0 to 9, and defaults to 3. Values will be rounded to the number set here.

Widget Folders:

Oil & Gas\Miscellaneous


Open HDV Button

When drawn on a page, this button provides a link to open the Historical Data Viewer as a pop-up with predefined settings for pen group and time duration.

If the label is to include an ampersand (&), then the & character will need to be doubled to appear.

The configuration dialog for the button:

The Button Label may be changed to display any message you like. Because more than one of these buttons may be added to a page, each displaying the HDV with a different pen group or time duration, the label should indicate what will be shown when the operator presses this particular button.

The Pen Group Selector drop-down list will display all pen groups previously configured in the Historical Data Viewer. The groups must exist before configuring this button - there is no mechanism for creating a new pen group in this dialog.

The Duration Selector is a drop-down list of all the standard time durations available in the HDV, ranging from 1 second to 5 years. When the HDV opens, it will display the selected time duration ending with the current time (i.e. a live data display).

If no pen group is configured, clicking on an instance of this button on a page will simply open the HDV.

This tool may also be drawn as a hotbox rather than as a button.

Widget Folders:

Analytics\Trends & Historical Data\

Tools\Standard Library\

Related information:

Pen Groups - Save Tag Selections

Open HDV Hotbox

Draw HDV Widget

Plot Data Widget


Open HDV Hotbox

Found in the Standard Library folder of the Widgets palette. When drawn on a page, this hotbox provides a link to open the Historical Data Viewer. This tool differs from the Historical Data Viewer entry in the menu in that it can be preconfigured to open a particular pen group and display a pre-set time duration.

The properties dialog for the hotbox:

The Hotbox Color may be changed to display any color you like. Yellow is the default and is most often recognized as indicating a hotbox link.

Because more than one of these hotboxes may be added to a page, each opening the HDV with a different pen group or time duration, the hotbox should be placed around a label that indicates what will be shown when the operator clicks on this particular link.

The Pen Group Selector drop-down list will display all pen groups previously configured in the Historical Data Viewer. The groups must exist before configuring this hotbox - there is no mechanism for creating a new pen group in this dialog.

The Duration Selector is a drop-down list of all the standard time durations available in the HDV, ranging from 1 second to 5 years. When the HDV opens, it will display the selected time duration ending with the current time (i.e. a live data display).

If no pen group is configured, clicking on an instance of this hotbox on a page will simply open the HDV.

This tool may also be drawn as a button rather than as a hotbox.

Widget Folders:

Analytics\Trends & Historical Data\

Tools\Standard Library\

Related information:

Pen Groups - Save Tag Selections

Open HDV Button

Draw HDV Widget

Plot Data Widget


Page Button Widget

Standard Library. Not linked to any tag.

* Does not use the Style Settings tag.

The Page Button widget is a navigational tool, used to create a connection from one page to another.

Buttons are always visible, and can be configured with their own label so that operators will know what to expect when they click.

Consider the configuration of the destination page when using this widget. Page properties can be configured to restrict full screen or popup behaviour.

Note that there is a choice of behavior in one uncommon configuration:

A page button or page hotbox drawn on a windowed (pop-up) page, and that widget calls the same page. You might create this configuration if you have a parameterized page and want to switch parameter values while staying within the pop-up. In this configuration, you can use the PageChangeUpdateSamePopup parameter to control whether another instance of the page is created, or the current page is replaced.

The properties dialog for the Page button widget:

Set a label, select a font tag, connect a page or disable functions in this properties dialog.

Label

Text to be displayed on the button. The label should always tell the operator what to expect to happen when they click the button.

Font

Select a Font tag that sets the display characteristics of the label.

Disable Button

Disables the button, including left and right clicks. This is typically set to an expression that controls whether the button is enabled or not. The expression should return TRUE to disable the button.

Disable Right-Click

Disables the ability to open the page as a pop-up by right-clicking the button.

Page Name

Select the page to be opened when the operator clicks the button. The Page Menu Page can be selected, as can pages of subordinate applications, if any.

Parameters

Visible only if the selected page has parameters. If so, it is important to select the tags and values that will be used for those parameters when the operator opens the page using this particular button. Failing to do so will result in the operator being prompted for parameter values with every return visit.

Widget Folders:

Page Navigation\

Tools\Standard Library\

Related information:

Add Navigation


Page Close Button Widget

Standard Library. Not linked to any tag.

* Does not use the Style Settings tag.

The Page Close Button widget is a navigational tool, used to allow operators to close pop-up pages. Some operators may find that a Close button is more convenient to use than the "x" in the upper right corner of the window.

Page Close buttons do not operate on full-screen pages. Operators may close only pop-up (windowed) pages.

The properties dialog for the Page button widget:

Button Label

The label should always tell the operator what to expect to happen when the click a button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Tool Tip Label

An optional field that may be used to provide more information to the operator when the cursor is over the button.

Widget Folders:

Page Navigation\

Tools\Standard Library\

Related information:

Add Navigation


Page Hotbox Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Page Hotbox widget is a navigational tool, used to create a connection from one page to another.

The hotbox is invisible unless the pointer is over it, at which time it turns yellow (or any other configured color). It is common to place a hotbox around a text label or an image so that operators will know where to find it, and what page to expect when they click.

Consider the configuration of the destination page when using this widget. Page properties can be configured to restrict full screen or popup behaviour.

Note that there is a choice of behavior in one uncommon configuration:

A page button or page hotbox drawn on a windowed (pop-up) page, and that widget calls the same page. You might create this configuration if you have a parameterized page and want to switch parameter values while staying within the pop-up. In this configuration, you can use the PageChangeUpdateSamePopup parameter to control whether another instance of the page is created, or the current page is replaced.

The properties dialog for the Page Hotbox widget:

Configure the hotbox color, link the intended page or disable features in the properties dialog.

Hotbox Color

While most developers will leave the default color in place for the sake of consistency, you might decide to color-code the hotboxes for various groups of pages in your application. You might also want to ensure that Page Hotboxes use a different color than Legacy Set Value Hotboxes, which are analog control widgets.

Disable Button

Disables the hotbox, including left and right clicks. This is typically set to an expression that controls whether the hotbox is enabled or not. The expression should return TRUE to disable the hotbox

Disable Right-Click

Disables the ability to open the page as a pop-up by right-clicking the hotbox.

Page

Select the page to be opened when the operator clicks the hotbox. The Page Menu Page can be selected, as can pages of subordinate applications, if any.

Parameters

Visible only if the selected page has parameters. If so, it is important to select the tags and values that will be used for those parameters when the operator opens the page using this particular hotbox. Failing to do so will result in the operator being prompted for parameter values with every return visit.

Widget Folders:

Page Navigation\

Tools\Standard Library\

Related information:

Add Navigation


Pie Chart Widget

This widget can include any set of numeric tags, but cannot be linked to a tag.

* Does not use the Style Settings tag.

This widget is used to display the relative values of a set of tags in the form of a two-dimensional pie chart.

The chart updates continuously with changing values. The current sum of the included tags is taken as 100% and each slice of the pie represents the matching tag's contribution to that total.

The properties dialog for the Pie Chart widget:

Tags

Use the + button to select all the numeric tags that should be included in the graph. Each defaults to the color black; you will need to select appropriate colors as you add the tags.

Use the - button to remove a tag from the set and the arrows to adjust the order.

Font

Select the font to use for labels and legends.

Label Color

Sets the color of all text used for labels, unless you choose to color labels to match segments.

Outline Color

Relevant only if the outline width is set larger than 0.

Enlarge Segments on Mouseover

When selected, each segment will be visually enhanced when under the mouse pointer.

Show Labels

When selected, labels are shown outside the chart, beside each matching segment. Content and color of the labels depend on the following selections:

Color Labels to Match Segments

If not selected, labels are shown in color set earlier.

Use Tag Descriptions

Applies to both labels and legends. If not selected, tag names are shown instead. For this case, the immediate (short) name of the tag is always shown. Names of parent tags are shown or not according to the following parameter:

Name Depth

Relevant only when Use Tag Descriptions is not selected (tag names are shown rather than descriptions). Minimum value of 1.

This controls how many of each tag's parents are included in the label.

Digits After Decimal

Applies to both labels and the legend. Defaults to 0 digits following the decimal.

Show Legend

Controls whether a legend is shown below the pie chart. The legend cannot be moved elsewhere.

Tag names or descriptions are shown depending on the earlier selection.

Show Values

Applies to both labels and the legend. Controls whether the values are shown as well as the tag names or descriptions.

Show Values as Percentages

Applies to both labels and the legend. If not selected, the current value of each tag is shown.

Show Units

Relevant only when showing actual values, not percentages. Applies to both labels and the legend.

Hole Size (%)

Defaults to 0 and has a maximum value of 99%. If non-zero, the chart is shown as a ring rather than a dot.

Outline Width (pixels)

When set larger than 0, every segment is bounded by an outline of the color set for all.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Charts and Graphs


Pie Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

The Pie widget represents the associated tag's value as portion of a circle. The darker portion of the chart starts at the angle you specify, where vertical (North) is zero degrees. Increasing values are indicated by the darker portion sweeping in a clockwise direction. The colors are set by the LED (analog) values of a selected Style Settings tag, and values above the linked tag's alarm setpoint can be indicated.

These widgets will indicate an active alarm according to the properties of the attached Style Settings tag (Exceptions tab). To continue indicating an alarm that is unacknowledged but no longer active, change the property AlarmWidgetsShowUnackedNormalAlarm in the application's properties, setting the value to 1.

The properties dialog for the Pie widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Minimum Angle

Sets the starting point for the sweep of the pie chart. Defaults to zero, which is vertical. (The North or 12-o'clock position). The angle is measured in degrees, and increases in the clockwise direction.

Show Alarms

If selected, the pie chart will indicate when the associated tag is in an active alarm state by using the alarm indication settings as configured in the associated Style Settings tag. Only that portion of the sweep above or below the alarm setpoint will use the alarm indication.

Counter Clockwise

If selected, sections of the pie chart will sweep (increase) in a counter-clockwise direction rather than the standard clockwise.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


PLC Alarm Control Widget

Relevant only to the PLC Alarm Tag. Allows limited configuration of the PLC alarm associated with the linked tag.

The PLC Alarm Control widget allows control of different properties in six different modes: Disable, Setpoint, Priority, Deadband, Delay, Alarm Condition. Note that all properties controlled by the PLC Alarm Control widget can also be controlled from the "Configure PLC Alarm" dialog in the PLC Alarm tag properties. This dialog is found under the Alarm Setup tab.

Output controls are disabled if the driver cannot communicate with the device.

The properties dialog for the PLC Alarm Control Widget:

Alarm Configuration Setting

Selects which property this widget controls:

  • Disable
  • Setpoint
  • Priority
  • Deadband
  • Delay
  • Alarm Condition

Digits After Decimal

Sets the number of digits to be displayed in the property field. (Does not apply to Disable or Priority.)

Compact View

When selected, only the value field is shown in the widget.

Show Driver Status

If selected, the current status of the driver is shown below the property. Alerts operators if drivers are in an error condition.

Confirmation Dialog

Defaults to selected. Changes require confirmation.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Alarm Tools

Tag Types\Alphabetical List of All\PLC Alarm

Tag Types\Inputs & Outputs\PLC Alarm

Tag Types\Digitals


Plot Data Widget

Used by: All driver tags, All analog tags, Alarm Status, Calculation, Comm Link Sequencer, Counter, Deadband Control, All digital tags, Function, History Statistics, Modem, Pump Status, Rate of Change, Script, Selector Switch, Serial Port, Totalizer, SQL Logger.

* Does not use the Style Settings tag.

The Plot Data tag widget is used to plot the value of the tag being drawn on a graph similar to that displayed on the Historical Data Viewer page. Drag the plot to the right to see earlier data that is no longer visible. Drag the plot all the way to the left to resume the live trend.

Tags drawn using the Plot Data widget must be logged, either by an attached Historian or Logger.

The properties dialog for the Numeric Entry widget:

Time Span

The Display Last field and drop-down list are used to configure the time span to display in the completed Plot Data object.

You may select Minutes, Hours, or Days from the drop-down list, and enter a corresponding number in the field to its left.

Display Time Labels

Select this option if you wish to display incremental units of time along the bottom of the completed Plot Data object.

Show Alarms

Select this option if you wish to display the alarm setpoints (if any), that associated with the tag being drawn on the completed Plot Data object. Alarm setpoints will be drawn as horizontal lines at the values matching the setpoints. This check box will not be enabled if the tag has no associated alarms.

Value To Output

Select which value associated with the tag, should be plotted. For the majority of tags, there will only be one default option, "Value", indicating the value of the tag.

Show Tag Name

Defaults to "No Name". Select either of "Short Name" or "Full Name" to add the tag's name to the marker line when the user examines values across the plot.

Text Size

Choose between five sizes of font for the scale labels. Sizes range from small to extra large where each size is two points larger than the last.

Use Tag's Scaled Min and Max Values

Selected this option if you wish to use the Scaled Process Data Min and Scaled Process Data Max properties configured for the tag being drawn. This will be the most common case.

If plotting a tag such as a Calculation, that does not have scaled process values, you can deselect this box to provide the minimum and maximum values expected.

Minimum Value and Maximum Value

These fields adjust the minimum and maximum values shown on the graph’s vertical axis. They have no effect on the tag’s value, which is what will be plotted.

Show Scales

Select if you wish the minimum and maximum scaling values to display to the left of the completed Plot Data object. Without these values displayed, it can be difficult to judge the meaning of the plotted data.

Plot Line

Opens the Select Color dialog from which you can select the color with which this tag's data will be plotted on the completed object. You should select a color that provides a good contrast from the background.

If this widget is linked to an I/O and Calculations tag that has a set color, and no override is set here, it will use the color from that tag.

Grid Color

Opens the Select Color dialog from which you can select the color with which the grid will be drawn on the completed object. You should select a color that provides only a slight contrast from the background so as to not obscure the plot line.

Background

Opens the Select Color dialog from which you can select the background color with which the Plot Data will be drawn.

Time Scale Color

Opens the Select Color dialog from which you can select the color for the numeric scale. A choice that provides a clear contrast from the background will help operators read the numbers.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Trends & Historical Data\

Related information:

HDV Button Widget

HDV Hotbox Widget

Draw HDV Widget

Choices for Operator Interaction


Polled Station Widget

Used by: DataFlow RTU, Polling Driver.

* Does not use the Style Settings tag.

The Polled Station tag widget is used to display the number of the RTU that is actively being polled. Displays * between polls.

The properties dialog for the Polled Station:

Font

Select one of the font tags (or parameter linked to a font tag) that you wish to use to display the text. The display will use the default system font if you do not select a font tag.

The parameters button is enabled only if the tag is drawn on a page that includes a font parameter, or if the tag is part of a widget and the associated widget editor is open.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Type of Border

Examples of the three border types are shown at the beginning of this topic.

Colors (Text and Background)

Opens the Select Color Dialog from which you can select the color of the text.

The background color against which the text will be displayed can also be defined.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Polling\

Analytics\Diagnostics\

Related information:

Choices for Operator Interaction


Power Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Power widget represents the associated tag's value as a photorealistic meter.

The properties dialog for the Power widget

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Options

Set the number of major divisions and minor divisions within each major division. Defaults to 10 and 5.

Choose whether to include the text used for engineering units within the gauge. Defaults to show units.

Colorization

Use the color selector dialogs to set the color of the needle, text and gauge background. This widget does not use the Style Settings tag.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Widget Folders:

Gauges\

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Related information:

Choices for Operator Interaction


Pressure Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Pressure Gauge widget represents the associated tag's value as radial meter.

The properties dialog for the Pressure Gauge widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Options

Set the number of major divisions and minor divisions within each major division. Defaults to 10 and 5.

Choose whether to include the text used for engineering units within the gauge. Defaults to show units.

Colorization

Use the color selector dialogs to set the color of the needle, text and gauge background. This widget does not use the Style Settings tag.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Program Spawn Widget

Not linked to any tag.

* Does not use the Style Settings tag.

The Program Spawn widget is drawn as a button on any page. In response to being clicked, it will run any configured program that can be found on your computer.

This widget will generally work on a VIC connection, provided that the program being spawned exists in the same path on the client computer as it does on the server. Test to be sure that your selected programs can be spawned by your clients.
On the Anywhere Client, Spawn can be used to open a web link but not run any program
This widget does not work with the MIC client.

Program Spawn is commonly used to open a notebook or spreadsheet.

The properties dialog for the Program Spawn widget:

Program Path and Name

The full path to the program to run.

If the program accepts parameters (such as the name of a file to open), they may be provided after the name of the executable file.

If the command, or if one of the parameters contains a space then enclose the command or the parameter in double quotation marks.

For example, the path to the program file may contain spaces, in which case you must enclose it in quotation marks:

"C:\Program Files\My Program\Run Program.exe"

The path to the program and the name of the executable file both contain spaces, therefore this requires quotation marks.

"C:\Program Files\My Program\Run Program.exe" NewFile.txt

The parameter has no spaces, therefore it does not need to be enclosed in quotation marks.

"C:\Program Files\My Program\Run Program.exe" "New File.txt"

The parameter has a space, therefore must be enclosed in a separate set of quotation marks.

Button Text

The label that will be displayed on the button. Should inform the operator of what to expect when the button is pressed.

Widget Folders:

Basic Components\Specialty\Misc\

Tools\Standard Library\


Pulse Beacon Widget

Used by: Custom site icons

* Does not use the Style Settings tag.

The Pulse Beacon widget indicates the selected site on a map. It is one component of a site icon and is not meant to be used alone.

There are no user-configurable properties for the Pulse Beacon widget.

Widget Folders:

Basic Components\Specialty\Mapping\

Tools\Standard Library\

Related Tasks:

Custom Map Icons


Push Button Widget

Used by: I/O and Calculations, Analog Input, Analog Status, Analog Output, Analog Control, Digital Input, Digital Status, Digital Output, Digital Control, MultiWrite, Pump Status, Selector Switch, Trigger.

* Does not use the Style Settings tag.

The Push Button widget provides a method for operators to issue control actions, via the linked tag. The widget's configuration holds the value that will be written to the linked tag when the button is clicked.

The properties dialog for the Push Button widget:

Configuration options for a Push Button widget

Value to Write

Set the value that will be written when the completed object is clicked. If the associated tag is an analog or digital output, this may be any value that is legal for that tag. Otherwise, this value should match one of the configured states for the associated selector switch.

If this value is not set, the button will not work.

Up Image

The image that will be shown when the button is not being clicked.

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Down Image

The image that will be shown when the button is being clicked.

Mouse Over

The image that will be shown when the cursor is over the image.

Bezel Image

An image that should be scaled to surround the button, so that it does not appear to be floating above a panel.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Buttons & Switches\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


Quarter Arc Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Quarter Arc Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

The properties dialog for the Quarter Arc Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Recipe Management Widgets

Widgets in this section were designed for use with the Recipe & Batch management system. While each of these widgets is independently linked to a Recipe Book, Recipe Parameter or Recipe Trigger tag, they are meant to be used together to provide a subset or variation of existing Recipe & Batch Management pages.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Refer to the side menu for the list of these widgets.

Recipe Batch Status Widget

The Batch History List widget includes the tools available in The Batch History Page. Refer to that topic for a description of each tool within the widget.

This table will display one entry per completed batch and is filterable by recipe book, time span and keywords.

Recipe Batch Status Widget

Displays details of a batch by linked recipe book and a start time stamp. Batch number, recipe book, recipe, version, start time, end time, duration and operator note.

This sample of the Batch Details widget was captured from the Batch Details page that was accessed by double-clicking on an entry from the Batch History page. The widget automatically populated with the relevant information.

Recipe Batch Status Widget

The Batch Setpoints widget appears on The Batch Details Page and is available in the Idea Studio. The Batch Setpoints widget displays the Recipe Parameter tags of a linked Recipe Book tag and the steps, values and start times for a batch specified by timestamp. The first batch to run after the configured start time is the batch that will be displayed in the widget.

A table displaying parameter tags, start time, steps and the values written to the PLC during the applicable batch.

The Parameter column is populated by the linked recipe book tag and the steps, values and start times are populated by the batch correlated with the provided timestamps.

Recipe Batch Status Widget

The Batch Status widget is used to display information about a recipe batch. Details include the name of the linked recipe tag, the current status, the recipe name, batch number and the last write time.

Recipe List Widget

The Recipe List widget includes the tools available in The Batch & Recipe Management Page. Refer to that topic for a description of each tool within the widget.

Recipe Delete Widget

Equivalent to the Delete button from the Recipe & Batch Management Page.

Operators can use the Delete button widget to remove the currently selected version of a recipe. If there are no more versions, the current recipe will be deleted.

Recipe Export Widget

Equivalent to the Export button from the Recipe & Batch Management Page.

Operators can use the Export button widget to write the parameters of the currently selected recipe to either an Access or an Excel file.

Recipe Note Widget

Notes are associated with batch runs, and can be required by the Start button.

Optionally, you can use this widget to create a text entry field where operators can create a note to be used by the next batch run.

Recipe Retrieve Widget

Operators can use the Retrieve button widget to read the current values of recipe parameters from a PLC. This will query the PLC to which the selected Recipe Book is connected. If no values are available, matching the parameters in the Recipe Book, all recipe values will be set to blank.

This tool may be useful to let the operator know what parameter values were last being used in the PLC.

If the "Recipe Name" Parameter tag has an address, that value will be read out of the PLC as well and will be shown in the recipes droplist. This lets the operator know what recipe the PLC was last running. The same is true for the Parameter tag, "Recipe Version".

Recipe Revert Widget

Operators can use the Revert button widget to discard unsaved parameter values and reload the saved values for the currently selected recipe and version, associated with the linked tag.

Recipe Save Widget

Operators can use the Save button widget to write the current set of parameter values to the currently selected recipe and version in the linked tag.

Recipe Save As Widget

Operators can use the Save As button widget to store the current set of parameter values to a new recipe or version associated with the linked tag.

Recipe Selector Widget

Operators can use the Recipe Selector widget to choose which recipe to run. Recipes must already exist within the linked Recipe Book tag.

Recipe Start Widget

Operators can use the Start button widget to initiate processing of the currently selected recipe and version, associated with the linked tag.

Recipe Update Widget

Operators can use the Update button widget to write new values to a running batch process for the currently selected recipe & version. This action is protected by a security privilege. The button is enabled only while a process is running.

Recipe Version Selector

Operators can use the Version Selector widget to select which version of a recipe to process. The drop-down control is enabled only when there are versions to choose from.


Batch Details Widget

Used by: Recipe Book

Displays details of a batch by linked recipe book and a start time stamp. Batch number, recipe book, recipe, version, start time, end time, duration and operator note.

This sample of the Batch Details widget was captured from the Batch Details page that was accessed by double-clicking on an entry from the Batch History page. The widget automatically populated with the relevant information.

Widget Properties

The batch details widget properties allow you to link a recipe book tag, select a start time and optional end time, and customize the text colour by color selector, and the title font and font with style tags.

Tag

Link this widget to a Recipe Book tag.

Start Time

The batch displayed will be the first batch to run after the selected start time.

End Time

Optional. If you specify an end time, this widget will display a snapshot of the information available within that time span. Otherwise, the widget will show all currently known data and update with any new progress on the batch.

Text Color

Default Black. Opens a color selector. You can select the font color.

Title Font

Optional. Select a Style tag to configure the font that will appear in the first line of the widget.

Font

Optional. Select a Style tag to configure the rest of the font, beneath the title.


Batch History List Widget

Used by: Recipe Book

* Does not use the Style Settings tag.

The Batch History Page is accessible from the page menu > Alarms, Reports & Diagnostics > Recipes > Batch History.

The Batch History List widget includes the tools available in The Batch History Page. Refer to that topic for a description of each tool within the widget.

This table will display one entry per completed batch and is filterable by recipe book, time span and keywords.

The properties dialog for the Batch History List widget:

Background Color

Set the color to be used in the background. Select a specific color, link a Style tag, set a parameter, link a tag property or use an expression.

Text Color

Set the color to be used for the text. Select a specific color, link a Style tag, set a parameter, link a tag property or use an expression.

Show Toolbar

Disable to hide the toolbar

Show Border

Add or remove a border around the perimeter of the widget.

Use Theme Color in Toolbar

Use the application color theme set in the Application Configuration menu for the toolbar.

Related information:

The Batch History Page


Batch Setpoints Widget

Used by: Recipe Book Tag

The Batch Setpoints widget appears on The Batch Details Page and is available in the Idea Studio. The Batch Setpoints widget displays the Recipe Parameter tags of a linked Recipe Book tag and the steps, values and start times for a batch specified by timestamp. The first batch to run after the configured start time is the batch that will be displayed in the widget.

A table displaying parameter tags, start time, steps and the values written to the PLC during the applicable batch.

The Parameter column is populated by the linked recipe book tag and the steps, values and start times are populated by the batch correlated with the provided timestamps.

This widget displays the resulting values used in the batch. When a batch is run, the tag values may be subject to a Recipe Proportions tag or otherwise changed before they are written to the PLC. Then VTScada reads the values back and compares them to the expected value. This is the step from which the Batch Setpoint widget values are obtained.

In the Idea Studio, a Batch Setpoints widget will appear blank until it is linked to a Recipe Book tag, and unpopulated until a start time is provided.

Widget Properties

The batch setpoint widget properties allow you to link a recipe book tag, select a start time and option end time, and customize the text color, background color and font with a style tag.

Tag

Link this widget to a Recipe Book tag. This widget will populate the parameter column from the Recipe Book tag, specifically, the Recipe Parameter tags nested in the Recipe Book tag.

Start Time

The batch displayed will be the first batch to run after the selected start time.

End Time

Optional. If you select an end time, ensure that the end time is greater than the span of the batch. If the end time does not fully cover the time span in which the batch was run, the Batch Detail widget will still populate but may not show all of the real steps that ran in the batch.

Text Color

Default Black. Opens a color selector. You can select the font color.

Background Color

Default White. Opens a color selector. You can select the background color.

Font

Optional. Select a style tag to configure the font.


Recipe Batch Status Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

The Batch Status widget is used to display information about a recipe batch. Details include the name of the linked recipe tag, the current status, the recipe name, batch number and the last write time.

The properties dialog for the Batch Status widget. There are no user-configurable options beyond the standard operator-interface controls.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Delete Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Equivalent to the Delete button from the Recipe & Batch Management Page.

Operators can use the Delete button widget to remove the currently selected version of a recipe. If there are no more versions, the current recipe will be deleted.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Delete widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Delete".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Export Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Equivalent to the Export button from the Recipe & Batch Management Page.

Operators can use the Export button widget to write the parameters of the currently selected recipe to either an Access or an Excel file.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Export widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Export".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Import Widget

Used by: Recipe tag

* Does not use the Style Settings tag.

The Recipe Import widget performs the same function as the Import button of a Recipe & Batch Management Page. It will import recipes from either an Access database or an Excel spreadsheet.

Related Notes:

Import / Export Recipes

The properties dialog for the Recipe Import widget:

Font

The font to be used to display the label. Select a VTScada font tag that is defined in your application.

Label

Text to be displayed on the button. May be parameterized or use an expression.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types \ Recipes \ Recipe Book


Recipe List Widget

Used by: Recipe Book

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

The Recipe List widget includes the tools available in The Batch & Recipe Management Page. Refer to that topic for a description of each tool within the widget.

Use this to display a customized version of the Recipe & Batch Management Page on any of your operational pages. The widget can be customized to restrict access to the various tools, substituting your own as needed from those available (Recipe Management Widgets).

The properties dialog for the Recipe List widget:

Use Theme Color in Toolbar

Affects only the toolbar. If not selected, a dark shade of gray will be used.

Background & Text Color

Both must be set here. The widget will not provide an option to select Daytime or Nighttime mode. Use care to choose a text color that contrasts with the background color.

Show Toolbar

The toolbar is optional. You can use other recipe management widgets to provide operators with as much or as little functionality as you like. Related widgets must be linked to the same Recipe Book. They will not be linked to this widget.

Show Status Bar

If selected, shows operators the current status of the linked Recipe Book and the result of the last batch run.

Show Border

Select to add a border around the list widget.

Show Extra Columns

By default, only Parameter and Value are shown.
You can also view the following information from the Recipe Parameter tag: Full name, Description, I/O Address.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book


Recipe Note Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Notes are associated with batch runs, and can be required by the Start button.

Optionally, you can use this widget to create a text entry field where operators can create a note to be used by the next batch run.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Recipe Note widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Note".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Retrieve Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

For detail on spreadsheet and table structure, refer to Import / Export Recipes

Operators can use the Retrieve button widget to read the current values of recipe parameters from a PLC. This will query the PLC to which the selected Recipe Book is connected. If no values are available, matching the parameters in the Recipe Book, all recipe values will be set to blank.

This tool may be useful to let the operator know what parameter values were last being used in the PLC.

If the "Recipe Name" Parameter tag has an address, that value will be read out of the PLC as well and will be shown in the recipes droplist. This lets the operator know what recipe the PLC was last running. The same is true for the Parameter tag, "Recipe Version".

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Retrieve widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Retrieve ".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Revert Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Operators can use the Revert button widget to discard unsaved parameter values and reload the saved values for the currently selected recipe and version, associated with the linked tag.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Revert widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Revert".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Save Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Operators can use the Save button widget to write the current set of parameter values to the currently selected recipe and version in the linked tag.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Save widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Save".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Save As Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Operators can use the Save As button widget to store the current set of parameter values to a new recipe or version associated with the linked tag.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Save As widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Save As".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Selector Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Operators can use the Recipe Selector widget to choose which recipe to run. Recipes must already exist within the linked Recipe Book tag.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

The properties dialog for the Recipe Selector widget. There are minimal user-configurable options beyond the standard operator-interface controls.

Font

Assign a font to be used for labels within the widget.

Title

Provide a title for the selector. Defaults to "Recipe".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Start Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Operators can use the Start button widget to initiate processing of the currently selected recipe and version, associated with the linked tag.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

You can require any of the following operator actions when they use this button:

  • Confirm the action.
  • Enter a number, which will be associated with the new batch.
    This is a text field which may contain any relevant information for the batch.
  • Enter a note, which will then be associated with the batch run.

You can also require that a secondary condition be true before a button press takes effect. A common example might be checking the value of some other Recipe Book tag to ensure that it has finished (or is not running) before allowing the operator to start a new batch.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Start widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Start".

Recipe & Version

Defaults to [Current Recipe], meaning whichever has been selected using the Recipe Selector Widget and Recipe Version Selector.

Alternatively, you can select a specific recipe and version using the two drop-downs. The button will then run only that recipe, regardless of other selections on the page.

Confirmation Dialog

When selected, the operator must confirm the action before processing will begin.

Prompt for Batch Number

When selected, the operator will be prompted for the batch number.

Prompt for Note

When selected, the operator will be prompted to provide a note that will be recorded as part of the history of the batch run.

Additional Enable Condition

Select a tag or create an expression that must be TRUE (1) before operators will be able to use this button to start a batch run.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Update Widget

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Operators can use the Update button widget to write new values to a running batch process for the currently selected recipe & version. This action is protected by a security privilege. The button is enabled only while a process is running.

If confirmation is configured, operators must indicate that they want to proceed with this operation after selecting the button.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

Related Widgets:

Recipe Selector Widget

Recipe Version Selector

The properties dialog for the Update widget.

Font

Assign a font to be used for labels within the widget.

Label

Provide a title for the button. Defaults to "Start".

Confirmation Dialog

When selected, the operator must confirm the action before processing will begin.

Additional Enable Condition

Select a tag or create an expression that must be TRUE (1) in order for the update operation to proceed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Recipe Version Selector

Used by: Recipe Book Tag

* Does not use the Style Settings tag.

The user interface for building, managing and running recipes is provided by the The Batch & Recipe Management Page. You are advised to use this rather than attempt to build a custom UI with the component widgets.

Operators can use the Version Selector widget to select which version of a recipe to process. The drop-down control is enabled only when there are versions to choose from.

Each Recipe Book tag contains internal variables to keep track of the current recipe and current version. Every widget linked to a Recipe Book will refer to those variables, using the same current recipe and version for its operation.
Use the Recipe Selector Widget and Recipe Version Widget to choose which recipe and version should be current.

The properties dialog for the Version Selector widget. There are few user-configurable options beyond the standard operator-interface controls. Version numbers can be created while saving a recipe, assuming that this feature is enabled in the linked Recipe Book tag.

Font

Assign a font to be used for labels within the widget.

Title

Provide a title for the selector. Defaults to "Version".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Recipes\Recipe Book\


Release Token Button

The Request Token Button widget and the Release Token Budget widget are the same widget. The difference is in whether the Release Token option is selected.

Used by: Any output tag or parent tag

* Does not use the Style Settings tag.

The Release Token Button widget gives users a way to release a Control Token that they had obtained.

The button will be grayed-out / disabled if the user does not have the Control Token. Users other than Control Token Administrators cannot release a token that they do not have ownership of.

The properties dialog for the Release Token Button object:

Level

Does not apply to a Release Token Button widget.

Label

Text to display on the button.

This should indicate what tag or tags the user is releasing control over.

Font

The font to use for the label.

Image File

Optional. An image to use instead of, or in addition to, the label. Images are used full size and cannot be scaled or otherwise adjusted.

Whether the image is in the application's Bitmaps folder or the VTScada Bitmaps folder, the path should take the form, "Bitmaps\Subfolder\ImageName.png".

Images must be added to the application before they can be used. See: Import Images

Release Token

This must be selected for the widget to work as a Release Token button.

Global Token

If selected, control will be released for the root tag (if held) and all of its children, not just the tag to which this widget is linked.

Confirmation

If selected, users will be prompted to confirm that they intended to release control.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Control Tokens


Relinquish Command Button Widget

Used only with I/O and Calculations tags attached to BACnet Drivers.

* Does not use the Style Settings tag.

Make this part into a snippet, to be included in Dev_WidgetIntro.htm.

The Relinquish Command Button widget can be used by an authorized operator to relinquish (remove) a value set to a specific priority in a BACnet address. When that happens, lower priority commands will be allowed to set their values to the object. The priority level is determined by the Write Address property of the I/O tag.

The properties dialog for the Relinquish Command Button:

Label

Optional text to be displayed on the button.

Font

Select a Font tag that sets the display characteristics of the label.

Image File

Optional path and filename to an image that will be shown on the button. The path must be relative to the application's folder; for example: "Bitmaps\MyIcons\Relinquish.png". Images must be imported to the application before they can be used. See Import Images

If both a label and an image are specified, the image will appear to the left of the label. If there is no label, the image will be centered on the button.

Confirmation

If selected, users will be prompted to confirm that they intended to release control.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Command Prioritization


Report Button Widget

Used by: Report tag.

* Does not use the Style Settings tag.

The Report Button tag widget is used to create a button that the operator may click to generate a predefined report. The report must be configured within the associated Report tag, but other widgets are available to allow the operator to change the configuration.

If the Report tag is not configured, the button will be drawn but not enabled.

Clicking on an enabled Report Button will produce a status bar and also acknowledge any errors or the completion of the report before giving the option to save the report as a PDF.

Clicking on the report button multiple times will produce report equal to the number of times clicked. The reports will not interfere with each other.

The properties dialog for the Report Button widget:

The Start Time and End Time options are advanced configuration tools. Read through the following notes before configuring.

Example of a Report Button Properties dialog

State 0 Label and State 1 Label

The state 0 label will be shown most of the time. The state 1 label is shown only when the button is pressed and the report runs.

The State 0 label should contain just enough text to allow the operator to know which report will run when the button is clicked and the time frame that will be included in the report (especially if the Re-run last schedule option is selected). The State 1 label should provide confirmation that the button has indeed been clicked upon.

If the label is to include an ampersand (&), enter two ampersands (&&).

Reporting Period

Use Report Tag's Period

Use the period specified in the linked report tag.

Re-run the last schedule

When selected, clicking the button will re-run the last scheduled report rather than generating a report that uses the current time.

The Start and End Time parameters are disabled when Re-run last scheduled is selected.

Custom Period

The option to re-run the last scheduled report is not available when these are configured.

Only two out of the three variables can be configured at a time.

  • Start Time and End Time
  • Start Time and Duration
  • End Time and Duration

The Start Time or End Time can be set by any of the following:

Reporting Period options including Timestamp, Tag Value, Parameter, Linked Tag Property, and Expression

Timestamp or Duration Selector

For the Start Time and End Time, click the "Set Date and Time" button to configure a date and time.

For the Duration option, click the "Set Duration" button to provide a numeric value and select a unit of time from a droplist.

Note that these are absolute values that can be changed only by re-configuring the widget. For relative values that will update based on user-specified parameters select one of the following options.

Tag Value, Parameter, Linked Tag Property, Expression

These are advanced configuration options. Whichever option you select, it must be configured to supply UTC values for the start and end times. These are likely to be relative to whenever the report is run and therefore you will need to write an expression to calculate those UTC values. Look first to the TimeUtils library for a way to generate the boundary times. If that library does not provide the time range you require, refer to notes in the section Time and Date Functions in Expressions.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Report Tools\

Tag Types\Data Logging & Reports\Report\

Related information:

Choices for Operator Interaction


Report Destination Widget

Used by: Report tag.

* Does not use the Style Settings tag.

The Report Output Type tag widget is used to draw a group of objects that operators can use to configure the output format and path for their report.

Information on each of the report output types shown can be found in the topic: Types of Reports. Not all types will include an email option, and for those that do, you must have an email server capable of sending the file. VTScada relies on your email server - it does not provide its own.

The Path option is enabled only when the output type involves saving the report to disk.

The properties dialog for the Report Options widget:

Title

Provide the text you want to display above the completed Report Output Type object group. By default, the text "Report Destination" will be provided. You may leave this field blank if you prefer not to have a title.

Focus ID

Select a number representing the placement of this object in the page’s overall tab order. (Optional)

When you draw objects on a page, each object is given a focus ID that identifies that object's place in the tab order (that is, which object will be selected when the Tab key is pressed). This does not control which object will initially have focus when a page is opened - that belongs to the first item drawn on the page that can receive focus. (i.e. the first graphics statement in the page’s source file).

You can disable a control widget by setting its Focus ID value to zero. The widget will remain visible, but faded.

Draw Bevel

Encloses the object in a beveled rectangle when selected. The example shown at the beginning of this topic uses a title and bevel.

Align Title

Used in conjunction with the Vertical Alignment choice. Selects whether the title is included when aligning the object vertically within its overall bounding area. See Vertical Alignment for an example.

All Users Can Edit

Controls whether all signed in users may use the objects in the completed Report Option List group, without regard as to the privileges that have been granted to their user account.

If not selected, then only users who have the Configure privilege granted to their user account may use the objects in the Report Option List group.

This option is useful for allowing administrative personnel to create and configure reports without granting configuration privileges. Information on the Configure security privilege can be found in "System Privileges".

Vertical Alignment

Locates the object vertically within its drawing area. May be one of Top, Centered or Bottom as shown. You can save time by putting the object where you would like on the screen and not making the drawing area larger than the object.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Report Tools\

Tag Types\Data Logging & Reports\Report\

Related information:

Choices for Operator Interaction


Report Iterations Widget

Viewing: Reference > Widget Reference > Report Iterations Widget

Report Iterations

This tool is used to draw a field into which operators can enter the number of report iterations (i.e. consecutive reports) they wish the report generator to produce. For example, if an operator wishes to generate a report for each day in the last month, they could set the report time period to the last day of the last month (e.g. Thu Nov 30, 2001 12:00 pm), and then enter "30" in the Iterations Entry field.

The report generator produces the first report based on the duration specified by the Start Time and End Time spin boxes, and then generates consecutive reports based on the same time period, but on prior dates (present to past).

The following image shows an example of the Report Iterations dialog.

The result of the above configuration is an entry field labeled, "Number of Previous Periods" into which operators can enter a number representing the number of report iterations they wish the report generator to produce.

Title

Whatever you type for the title will be displayed above the Iterations Entry field. The default title is "Number of Previous Periods".

Focus ID

The Focus ID spin box enables you to select a number representing the order of the completed object in the overall tab order.

When you configure some or all of the report tools on a page, each object is given a focus ID that identifies that object's place in the tab order (that is, which object will be selected when the Tab key is pressed). This does not control which object will initially have focus when a page is opened - that belongs to the first item drawn on the page that can receive focus. (i.e. the first graphics statement in the page’s source file).

Draw Bevel

The Draw Bevel check box is used to indicate whether the completed iterations entry object should be drawn with a beveled border. If the Draw Bevel check box is selected, the completed iterations entry object will be drawn with a beveled border surrounding it. If the Draw Bevel check box is not selected, the completed iterations entry object will be drawn without a beveled border.

Align Title

The Align Title check box is used to specify whether you wish the Iterations Entry field's title to be included in the Vertical Alignment calculation.

Vertical Alignment

The Vertical Alignment radio buttons enable you to specify the alignment to be applied to the Iterations Entry field, and its title and bevel vertically within its drawing area. You may select one of:

  • Top: The Iterations Entry field, its title (if the Align Title check box has been selected), and its bevel (if the Draw Bevel check box has been selected) will be aligned to the vertical top of its drawing area.
  • Centered: The Iterations Entry field, its title (if the Align Title check box has been selected), and its bevel (if the Draw Bevel check box has been selected) will be aligned to the vertical center of its drawing area.
  • Bottom: The Iterations Entry field, its title (if the Align Title check box has been selected), and its bevel (if the Draw Bevel check box has been selected) will be aligned to the vertical bottom of its drawing area.

Widget Folders:

Tools\Report Tools\


Report Options Widget

Used by: Report tag.

* Does not use the Style Settings tag.

The Report Option List tag widget is used to draw a trio of check boxes that operators can use to select certain formatting attributes for their report.

Use Excel to Display screen reports.

This first option applies only to reports that are configured to output to the screen. If that is the case, then selecting this option will cause Microsoft Excel™ to be opened to view the report (if Excel is installed on the workstation). The report would otherwise be shown using a simple text format.

Use separate sheets/tables.

This option applies only if the report is being output to either a spreadsheet (Microsoft Excel™) or a database (Microsoft Access™) and if it has been configured to report on more than one consecutive time period. Each time period will be stored in its own worksheet or table.

The default names will be "Sheet 1", "Sheet 2", or "Table 1", "Table 2" …

Rename sheets/tables.

Applies only if the preceding option also applies and is selected. If selected, each sheet or table will be named for the time period it contains. This name will use the following template:

<Date (Month/day - MMMDD)><Period Start (Hours/Minutes - HHMM)>_<Period End (Hours/Minutes - HHMM)>

For example, a report run on May 25th at 17:20 and covering three consecutive 1-hour time periods will have sheets with the following names:

May251720_1820

May251620_1720

May251520_1620

The properties dialog for the Report Options widget:

Title

Sets the title, should you wish to include one above the option list. Enabled whether the bevel is drawn or not.

Focus ID

Select a number representing the placement of this object in the page’s overall tab order. (Optional)

When you draw objects on a page, each object is given a focus ID that identifies that object's place in the tab order (that is, which object will be selected when the Tab key is pressed). This does not control which object will initially have focus when a page is opened - that belongs to the first item drawn on the page that can receive focus. (i.e. the first graphics statement in the page’s source file).

You can disable a control widget by setting its Focus ID value to zero. The widget will remain visible, but faded.

Draw Bevel

Encloses the object in a beveled rectangle when selected. The example shown at the beginning of this topic uses a title and bevel.

Align Title

Used in conjunction with the Vertical Alignment choice. Selects whether the title is included when aligning the object vertically within its overall bounding area. See Vertical Alignment for an example.

All Users Can Edit

Controls whether all signed in users may use the objects in the completed Report Option List group, without regard as to the privileges that have been granted to their user account.

If not selected, then only users who have the Configure privilege granted to their user account may use the objects in the Report Option List group.

This option is useful for allowing administrative personnel to create and configure reports without granting configuration privileges. Information on the Configure security privilege can be found in "System Privileges".

Vertical Alignment

Locates the object vertically within its drawing area. May be one of Top, Centered or Bottom as shown. You can save time by putting the object where you would like on the screen and not making the drawing area larger than the object.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Report Tools\

Tag Types\Data Logging & Reports\Report\

Related information:

Choices for Operator Interaction


Report Tag List Widget

Used by: Report tag.

* Does not use the Style Settings tag.

The Report Tag List tag widget is used to draw a group of tools that operators can use to select the tags to be included in a report.

If you provide this report drawing tool to operators, you must ensure that they know the following:

  • Only tags that are being logged will have data available for a report.
  • Merely selecting a group of tags with this tool is not sufficient for the associated Report tag to actually use them. The selected tags must either be saved as a group, or loaded as a group.

The filtering and selection tools here are the same as those provided in the Reports page. For details on how to use this, please see: Select Tags for a Report.

The properties dialog for the Report Tag List widget:

Title

Provide the text you want to display above the completed Report Tag List. By default, the text "Tag List" will be provided. You may leave this field blank if you prefer not to have a title.

Focus ID

Select a number representing the placement of this object in the page’s overall tab order. (Optional)

When you draw objects on a page, each object is given a focus ID that identifies that object's place in the tab order (that is, which object will be selected when the Tab key is pressed). This does not control which object will initially have focus when a page is opened - that belongs to the first item drawn on the page that can receive focus. (i.e. the first graphics statement in the page’s source file).

You can disable a control widget by setting its Focus ID value to zero. The widget will remain visible, but faded.

Draw Bevel

Encloses the object in a beveled rectangle when selected. The example shown at the beginning of this topic uses a title and bevel.

Align Title

Used in conjunction with the Vertical Alignment choice. Selects whether the title is included when aligning the object vertically within its overall bounding area. See Vertical Alignment for an example.

All Users Can Edit

Controls whether all signed in users may use the objects in the completed Report Tag List, without regard as to the privileges that have been granted to their user account.

If not selected, then only users who have the Configure privilege granted to their user account may use the objects.

This option is useful for allowing administrative personnel to create and configure reports without granting configuration privileges. Information on the Configure security privilege can be found in "System Privileges".

Vertical Alignment

Locates the object vertically within its drawing area. May be one of Top, Centered or Bottom as shown. You can save time by putting the object where you would like on the screen and not making the drawing area larger than the object.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Report Tools\

Tag Types\Data Logging & Reports\Report\

Related information:

Choices for Operator Interaction


Report Type Widget

* Does not use the Style Settings tag.

The Report Type widget is used to create a drop-down list from which operators can select the type of report they wish to generate.

The list of report types available will vary depending on whether you have any custom reports defined.

At the very least, you can expect to see:

  • Daily Snapshot Report: Displays a "snapshot" of the value of each tag in a selected set of loggers at the current time for a user-defined time period. For example, if at 2:00 pm you select a series of tags, set the time period to "Last Week" and run the report, the daily snapshot report will display the value of each tag at 2:00 pm for the last 7 days.
  • Daily Total Report: Displays the total data accumulated for a selected set of tags at the current time within a user-defined time period. For example, if at 2:00 pm you select a series of tags, set the time period to "Last Week" and run the report, the daily total report will display the value accumulated for each tag by 2:00 pm for the last 7 days.
  • Hourly Snapshot Report: Displays a "snapshot" of the value of each tag in a selected set of loggers at each hour within a user-defined time period. For example, if at 2:00 pm you select a series of tags, set the time period to "Last Week" and run the report, the hourly snapshot report will display the value of each tag every hour for the last week, starting at 2:00 pm today.
  • Hourly Total Report: Displays the total data accumulated hourly for a selected set of tags (starting at the current time) within a user-defined time period. For example, if at 2:00 pm you select a series of tags, set the time period to "Last Week" and run the report, the hourly total report will display the accumulated total for each tag every hour for the last week, starting at 2:00 pm today.
  • Standard Report:Displays the value of the selected tags, every X seconds, for a user-defined time period.

These and other report types are described in greater detail in Selecting a Report Type.

The properties dialog for the Report Type widget is as shown:

Title

Provide the text you want to display above the completed Report Output Type object group. By default, the text "Report Destination" will be provided. You may leave this field blank if you prefer not to have a title.

Focus ID

Select a number representing the placement of this object in the page’s overall tab order. (Optional)

When you draw objects on a page, each object is given a focus ID that identifies that object's place in the tab order (that is, which object will be selected when the Tab key is pressed). This does not control which object will initially have focus when a page is opened - that belongs to the first item drawn on the page that can receive focus. (i.e. the first graphics statement in the page’s source file).

You can disable a control widget by setting its Focus ID value to zero. The widget will remain visible, but faded.

Draw Bevel

Encloses the object in a beveled rectangle when selected. The example shown at the beginning of this topic uses a title and bevel.

Align Title

Used in conjunction with the Vertical Alignment choice. Selects whether the title is included when aligning the object vertically within its overall bounding area. See Vertical Alignment for an example.

All Users Can Edit

Controls whether all signed in users may use the objects in the completed Report Option List group, without regard as to the privileges that have been granted to their user account.

If not selected, then only users who have the Configure privilege granted to their user account may use the objects in the Report Option List group.

This option is useful for allowing administrative personnel to create and configure reports without granting configuration privileges. Information on the Configure security privilege can be found in "System Privileges".

Vertical Alignment

Locates the object vertically within its drawing area. May be one of Top, Centered or Bottom as shown. You can save time by putting the object where you would like on the screen and not making the drawing area larger than the object.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Report Tools\

Tag Types\Data Logging & Reports\Report\

Related information:

Choices for Operator Interaction


Reporting Period Widget

Used by: Report tag

* Does not use the Style Settings tag.

The Reporting Period widget is used to draw spin boxes and a drop-down list that operators can use to configure the time period for a report. The available presets are shown to the right of the completed widget:

The properties dialog for the Reporting Period widget:

Title

Provide the text you want to display above the completed Reporting Period controls group. By default, the text "Reporting Period" will be provided. You may leave this field blank if you prefer not to have a title.

Focus ID

Select a number representing the placement of this object in the page’s overall tab order. (Optional)

When you draw objects on a page, each object is given a focus ID that identifies that object's place in the tab order (that is, which object will be selected when the Tab key is pressed). This does not control which object will initially have focus when a page is opened - that belongs to the first item drawn on the page that can receive focus. (i.e. the first graphics statement in the page’s source file).

You can disable a control widget by setting its Focus ID value to zero. The widget will remain visible, but faded.

Draw Bevel

Encloses the object in a beveled rectangle when selected. The example shown at the beginning of this topic uses a title and bevel.

Align Title

Used in conjunction with the Vertical Alignment choice. Selects whether the title is included when aligning the object vertically within its overall bounding area. See Vertical Alignment for an example.

All Users Can Edit

Controls whether all signed in users may use the objects in the completed Reporting Period controls group, without regard as to the privileges that have been granted to their user account.

If not selected, then only users who have the Configure privilege granted to their user account may use the objects in the Report Option List group.

This option is useful for allowing administrative personnel to create and configure reports without granting configuration privileges. Information on the Configure security privilege can be found in "System Privileges".

Vertical Alignment

Locates the object vertically within its drawing area. May be one of Top, Centered or Bottom as shown. You can save time by putting the object where you would like on the screen and not making the drawing area larger than the object.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Report Tools\

Tag Types\Data Logging & Reports\Report\

Related information:

Choices for Operator Interaction


Reporting Period (Enhanced) Widget

Used by: Report tag.

* Does not use the Style Settings tag.

The Reporting Period Enhanced widget provides every possible option to configure the time period for a report. You can select from of:

  • A set of predefined full time periods.
  • A set of predefined time lengths prior to the trigger.
  • A custom time period, of any duration and end time.
  • An offset relative to the trigger event.

Presets include:

  • Last XX before trigger time

where XX is one of :

7 days, 4 days, 2 days, 1 day, 12 hours, 4 hours, 2 hours or 1 hour

  • Previous XX

Where XX is one of the following full time periods:

Day, week, month, quarter or year

  • Current XX

Where XX is one of :

Day, week, month, quarter or year.

  • Custom

Where custom can be either a Previous (full) Time Period, selected using the Report Duration fields or, Duration and End Time, where the end time is defined to occur at some length of time before the report was triggered and the included time period is defined using the Report Duration.

The properties dialog for the Reporting Period widget:

Title

Provide the text you want to display above the completed Reporting Period controls group. By default, the text "Reporting Period Enhanced" will be provided. You may leave this field blank if you prefer not to have a title.

Focus ID

Select a number representing the placement of this object in the page’s overall tab order. (Optional)

When you draw objects on a page, each object is given a focus ID that identifies that object's place in the tab order (that is, which object will be selected when the Tab key is pressed). This does not control which object will initially have focus when a page is opened - that belongs to the first item drawn on the page that can receive focus. (i.e. the first graphics statement in the page’s source file).

You can disable a control widget by setting its Focus ID value to zero. The widget will remain visible, but faded.

Draw Bevel

Encloses the object in a beveled rectangle when selected. The example shown at the beginning of this topic uses a title and bevel.

All Users Can Edit

Controls whether all signed in users may use the objects in the completed group, without regard as to the privileges that have been granted to their user account.

If not selected, then only users who have the Configure privilege granted to their user account may use the objects in the Report Option List group.

This option is useful for allowing administrative personnel to create and configure reports without granting configuration privileges. Information on the Configure security privilege can be found in "System Privileges".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Report Tools\

Tag Types\Data Logging & Reports\Report\

Related information:

Choices for Operator Interaction


Request Token Button Widget

The Request Token Button widget and the Release Token Budget widget are the same widget. The difference is in whether the Release Token option is selected.

Used by: Any output tag or parent tag

* Does not use the Style Settings tag.

The Request Token Button widget gives users a way to request a Control Token for an output tag or a set of output tags.

The button will be grayed-out / disabled if the user already has the Control Token. If no-one else has a control token on this tag and if the user is authorized to use the control, the request will be granted immediately. Otherwise, (by default) the request will be added to a queue of people asking for control of the tag. (Use the property, ControlTokenManualRequestOption to alter this behavior if needed.)

The properties dialog for the Request Token Button object:

Level

Defaults to Level 1.

Depending on your configuration, higher level requests (where 1 is the highest level) can take a token from a user who requested it at a lower level. That is not the default behavior. Refer to Token Levels vs. Token Actions

Label

Text to display on the button. This should indicate what tag or tags the user is requesting control over.

Font

The font to use for the label.

Image File

Optional. An image to use instead of, or in addition to, the label. Images are used full size and cannot be scaled or otherwise adjusted.

Whether the image is in the application's Bitmaps folder or the VTScada Bitmaps folder, the path should take the form, "Bitmaps\Subfolder\ImageName.png".

Your images must be added to the application before they can be used. See: Import Images

Release Token

Optional. If selected, this becomes a Release Token button.

In general, it is better to use the dedicated Release Token Button.

Global Token

If selected, control will be requested for the root tag and all of its children, not just the tag to which this widget is linked.

Confirmation

If selected, users will be prompted to confirm that they intended to request control.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Control Tokens


Reset Button Widget

Used for: Totalizer, Counter.

* Does not use the Style Settings tag.

The Reset Button widget is used to create a button in your application that will reset a Totalizer tag or a Counter tag to zero.

Button Label

Enter the text you want to display. Labels should be clear but short, as the length of the label determines the size of the button.

If the label is to include an ampersand (&), enter two ampersands (&&).

Confirmation Dialog

Select this option if you want users to be prompted to confirm that they meant to press the reset button. Defaults to selected.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


Reset Polling History Widget

Used by: Enron Modbus Driver

The Reset Polling History widget is used only by the Enron Modbus Driver. It is drawn as a button, which operators may click to change the next index to be polled back to the first index, which may be a one or zero depending on driver settings. This can be used to re-read all data in the device.

The properties dialog for the Reset History Polling widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

History Address

Provide the numeric value of the history address being monitored. History addresses typically start at 701.

Label

Provide a label for the button. This should describe what will happen when an operator clicks this widget.

Confirmation Dialog

When selected, operators must click through a confirmation prompt before the reset will proceed.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\


Reset Broadcast List Manager (CAT CCM5)

Used by: CAT CCM Manager tag only. (CAT M5X CCM Manager)

* Does not use the Style Settings tag.

The Reset Broadcast List Manager widget is used to display a button that operators can use to perform that function with their CAT CM5 CCM Manager tag.

The properties dialog for the Reset Broadcast List object:

Button Label

Defaults to "Reset BCast List".

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:


Reset Target Widget

Used for: Totalizer, Counter.

* Does not use the Style Settings tag.

The Reset Target widget is used to create a hotbox that will function in the same way as a Reset Button widget. When an operator clicks on the hotbox, the associated Totalizer tag or counter tag will be reset to its starting value. The reset target is shown as a simple rectangle of the configured color. To make its purpose clear, you should consider placing it above a symbol or text that describes its purpose, as shown here (label added as text).

Do not place a hotbox around another tag widget. Clicking on a tag widget will open a historical data viewer for that tag, if that option has not been disabled. If this happens when an operator was expecting to reset a Totalizer tag or counter tag, the result is likely to be confusing.

Besides the Disable Options, there are only two configurable options for this widget: the color to be used for the hotbox, and a choice of whether a confirmation dialog will be shown when the operator clicks in the hotbox area.

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


Retro Gauge Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Retro Gauge widget represents the associated tag's value as a photorealistic meter, displaying both labeled major divisions and unlabeled minor divisions, the dial of which fluctuates according to the tag's value.

The properties dialog for the Retro Gauge widget:

Number of Major Divisions

Controls how many labeled divisions will be drawn around the meter. Each labeled division will also be drawn with a longer line.

Number of Minor Divisions

Controls how many unlabeled divisions will be drawn within each major division. Each minor division will be drawn with a shorter line.

Use tag’s scaled min and max values

If selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values

Minimum Value and Maximum Value

Used to set the smallest and largest values to display on the meter. By default, these values will match the tag’s scaled process values.

You can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Rewrite Outputs Widget

Used by: Allen Bradley Driver, CIP Driver, DNP3 Driver, Driver Multiplexer, Modbus Compatible Device , Omron Driver, Siemens S7 Driver, SNMP Driver.

* Does not use the Style Settings tag.

The Rewrite Outputs widget is used to force a driver to re-send the last set of values, written to outputs. The button will be enabled only if the driver has been configured to store the values.

This feature may be required if your application uses certain types of hardware that do not retain a memory of their register values during a power loss. It may also be useful when the physical hardware is replaced because the new device cannot know what was stored in the registers of the old.

The properties dialog for the Rewrite Outputs widget:

There are only two user-configurable options. You may change the text for the button, and you have the option of restricting access to this function by applying an application-specific security privilege.

If the label is to include an ampersand (&), enter two ampersands (&&).

Widget Folders:

Basic Components\Multi-Variable\

Analytics\Communications\Output Controls\


Right Bar Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Deadband Control, Function, History Statistics, Script, Selector Switch, SQL Logger.

* Does not use the Style Settings tag.

The Right Bar widget is used to display a tag's value as a horizontal bar, the length of which increases from the left towards the right as the tag’s value increases. When the tag’s value is at a minimum, the bar will be shown as a thin line at the left edge of its range. When the tag’s value reaches its maximum, the widget will be displayed as a rectangle, filling the range.

The properties dialog for the Right Bar widget:

Set Color

Opens the Select Color Dialog from which you can select a color for this object.

Low Scale Range and High Scale Range

In most cases, these fields will be display-only, showing the Scaled Process Data Min and Scaled Process Data Max values configured for the associated tag.

These fields become editable when the widget is used to display a function or Calculation tag. The most common use is to provide an output range of 0 to 100 (%) given a data source whose numbers do not match these values (perhaps ranging from 20 to 80, for example). Set the low scale range to the value expected from the data source when it is at its minimum and the high scale range to the value expected from the data source when it is at its maximum.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Basic Components\Bars\

Related information:

Choices for Operator Interaction


ROC Driver History Info Button

Used by the Fisher ROC driver.

Creates a button that operators may press to access details about the driver's history. This widget will work only with devices that use the ROC Plus protocol..

Sample history for a ROC Plus device.

The ROC driver reads history from tables within the ROC RTU. In the standard ROC protocol, the values in these tables are arranged by RAM Areas, whereas in the ROC Plus protocol they are arranged in History Segments.

Each time that VTScada reads the device's history, it saves the timestamp of the last value read. For the next read, it compares the new timestamp to the stored value. If there is no new information then the tables will not be read again. Each value is read only once.

If you wish to re-read values that have already been read, click the Reset Times button. This causes the next read to re-read the entire history table, not just the most recent information.

The only user-configurable properties for the button widget are the label and the standard Disable Options.

Related information:

Fisher ROC Driver


ROC History Polling Timestamp Reset

Used by the Fisher ROC driver.

Creates a button that operators can press to reset all of the device's history addresses, resulting in a full read of the RTU on the next poll, rather than only those records that were added since the last successful poll. This will have no effect on data that has already been saved by the VTScada Historian.

Note that there is no confirmation prompt before the reset occurs.

The only user-configurable properties for the button widget are the label and the standard Disable Options.

Related information:

Fisher ROC Driver


Rockwell Control Widget

Used by: Rockwell Driver.

* Does not use the Style Settings tag.

The Rockwell Control tag widget creates a panel of controls that can be used to send output to the hardware associated with a Rockwell driver tag.

There are no configurable options for the Rockwell Control panel.

Widget Folders:

Analytics\Communications\Rockwell Driver

Analytics\Diagnostics\


Rockwell Information Widget

Used by: Rockwell Driver.

* Does not use the Style Settings tag.

The Rockwell Information widget is used to create a beveled display, listing information about the associated hardware.

The Rockwell Information properties dialog:

Auto Refresh PLC Information

Disabled by default. (Information must be refreshed manually.) Use this to set an automatic refresh time of at least one second.

Text Color

Sets the color in which to display the text labels associated with this widget.

Background

Sets the background color for the completed object. Note: The background color you choose should provide a good contrast for the text color.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\CIP/ENIP Driver

Analytics\Diagnostics\


Rockwell Statistics Widget

Used by: Rockwell Driver.

* Does not use the Style Settings tag.

The Rockwell Statistics widget is used to create a beveled display, listing the statistics about the communications between VTScada and the associated hardware.

The Rockwell Statistics properties dialog:

Text Color

Sets the color in which to display the text labels associated with this widget.

Background

Sets the background color for the completed object. Note: The background color you choose should provide a good contrast for the text color.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Rockwell Driver

Analytics\Diagnostics\


Roster Alarm Test Widget

Used by: Roster tags.

* Does not use the Style Settings tag.

The Roster Alarm Test widget is used to create a check box that operators can click to generate an alarm that will test the roster configured for the Alarm Notification System.

The properties dialog for the Roster Alarm Test widget:

Check Box Label

The text you enter here will be displayed to the right of the completed Roster Alarm Test check box. It should clearly tell operators what the purpose of that check box is. By default, the tag name will be used before the words "Alarm Test".

Alarm Message

Set the message you wish the VTScada call-out system to transmit when performing this test. Operators receiving this message should have no doubt that they are seeing a test, not a real alarm.

Alarm Priority

Select the alarm priority you wish to configure for this test alarm. This can be either Priority 1 (i.e. Critical) or Priority 2 (High).

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Specialty\Roster Control\

Related information:

Choices for Operator Interaction


Roster Control Status Widget

* Does not use the Style Settings tag.

Monitor the status information of rosters in the application and force a roster out of a failed state. A reset button will become enabled if a roster is in a failed state. Click the enabled reset button to kick the roster out of its failed state. This widget is subject to realm and Global Tag & Area filtering.

You can find this widget in the palette folder: Tools >> System Status Tools

There are no user-configurable options available in the properties dialog for this widget. You don't need to link this widget. Active Roster tags in your application will be listed. This widget will show the Default Roster but only if it is the Active Roster in the Default Area.

The Roster Control Status display will be blank while you are working in Idea Studio. Refer to the live page to see the status display.

Area

An area is selected during the configuration of a roster tag when it is necessary to specify groups of alarms. This only becomes necessary when you want to send notifications for specific alarms to a specific roster of operators. Only one roster in a given area can be active at a time. If no area is specified, "Default" becomes the default.

Status

Idle | There is currently no active roster activity.
Notifying | The roster is in the notification process.
In Success Delay | The roster has successfully completed the notification process and has paused for a specified delay.
In Failure Delay | The roster has failed to complete the notification process and has paused for a specified delay.

Active Roster

Only one roster in a given area can be active at a time. This column displays the current active roster. If no roster is active in a given area, Default Call-Out Off will be active and will be the displayed "Active Roster".

Notification Stage

- There is currently no active roster activity.
Delay for N seconds The roster is waiting for a configured amount of time to pass.
Calling CONTACT on NUMBER

Where CONTACT = the name of the contact given in the roster and NUMBER/EMAIL = actual contact information.

This stage describes who is currently being contacted, by what means and their actual contact information.

Paging CONTACT on NUMBER
Email CONTACT on EMAIL
Texting CONTACT on NUMBER

Reset

If a roster is In Failure Delay, the reset button will be enabled. Click the reset button to end the delay and kick the roster out of the failure status.

Widget Folders:

Tools > System Status Tools


Rotary Control Widget (Knob)

Used by: I/O and Calculations, Analog Input, Analog Output, Analog Status, Analog Control

* Does not use the Style Settings tag.

The Rotary Control enables operators to select a value to write to hardware by turning a knob. This is done by clicking on, then dragging the control clockwise or counter-clockwise. The value that will be set is shown in a tooltip while dragging.

Properties dialog for the Rotary Control:

Rotary Image

The image that simulates the knob motion by rotating in response to the operator action. Usually a dot or bar that indicates the current position.
If creating your own image, it must be transparent other than the position indicator, which must be directly above the center of the image:

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Stationary Image

The background image, providing context for the rotary image.

Minimum Angle / Maximum Angle

Limit the angle through which the control can rotate. In both cases, the angle is measured clockwise from vertical in units of degrees.

Steps

Sets the precision of the control, relative to the scaling value. The default value enables the operator to select 100 possible values within the scale range. This may not be appropriate for all controls.

Scaling

Choose whether to use the tag's minimum and maximum scaling values or to set alternative scaling values that will be applied to the output value.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Analog Controls\


Selector Switch Widget

Used by: Selector Switch Tags

* Does not use the Style Settings tag.

The Selector Switch widget is used to represent a Selector tag as either a 2-position or a 3-position switch. A common use is to create a Hand-Off-Auto selector.

If the matching Selector tag has been configured for only two positions, the middle position cannot be used. The label will be blank in this case, even if you have specified an override within the widget configuration.

The widget is composed of several user-configurable parts: the base image, the switch image (i.e. the knob) and the labels. Additionally, you can change the switch angle. Any value from 0 to 120 is permitted, but small angles may be difficult for operators to use. The labels will be relocated to match the new switch positions.

The selector switch has built-in mechanisms to provide feedback to the operator. If an alarm occurs due to a mismatch between expected and actual feedback values, the text in the selected position will glow red. In the event of a mismatch between the requested and actual switch position, visual feedback will be provided by the switch blinking between the current position in solid shades and the requested position as semi-transparent. (see the following image:)

If the position feedback is Invalid, the image will simply blink in its set position.

If the Selector tag has only two positions, then the left position in the widget corresponds to position 0 in the Selector tag and the right position is 1. If the Selector tag has three positions, then left corresponds to position 0, the middle to 1 and the right corresponds to position 2.

Stationary Image

Any image may be chosen for the base image, but three in particular are provided in the Selector Switches folder: Plate1a, Plate1a-Large and Plate1b. (See example at the beginning of this topic). The base image provides a background for the switch and the labels.

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Rotary Image

Any image may be chosen for the switch image. The Selector Switches folder provides three options: Switch1a, Switch1a-Large and Switch1b. This provides a control and indicator knob that will appear on the base image background. Variations of the image shown above can be found in the Selector Switches group of the images library and you are free to add your own images.

Switch Angle

This is the angle between each consecutive position of the switch. Any value from 0 to 120 may be set. As shown in the following images, an angle that is too small (5 deg, shown on the left) will be difficult to use, while an angle that is larger (120 deg, shown on the right) may cause the labels to display outside the area of the base image.

Font

Select one of the font tags (or parameter linked to a font tag) that you wish to use to display the text. The display will use the default system font if you do not select a font tag.

The parameters button is enabled only if the tag is drawn on a page that includes a font parameter, or if the tag is part of a widget and the associated widget editor is open.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Color

Opens the Select Color Dialog from which you can select the color of the text.

Position Label Overrides

Set labels within the widget configuration that should be used in place of those configured in the linked tag.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Constrain Aspect Ratio.

Prevents the image from being deformed when resized on the screen.

Widget Folders:

Buttons & Switches\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


Service Status Widget

Used by: Not linked to any tag

* Does not use the Style Settings tag.

The Service Status widget duplicates the content of the Services Page on a page of your choice within your application. Note that your page must be protected by a custom security privilege that you create. The Service Page Access privilege will not restrict who can view this widget on your page.

Refer to the Services Page for a detailed description of the features of the Service Status widget.

Service Status including the optional legend

The properties dialog for the Service Status dialog:

Starting List

Preset the list to be displayed or show the list the operator was last viewing.
Options include: Service Status, Service Architecture, or Last Selected (the default).

Text Size

Adjusts the relative size of the font used in the lists.
Options include Small, Medium, Large, or Last Selected (the default).

Background

Sets the background color of the lists. Defaults to white with gray banding.

Text Color

Sets the color used for text within the lists. Defaults to black.

Filter

Sets a filter that will limit which services are shown in the list. Filtering

Show Toolbar

Controls whether the toolbar (and therefore access to the various tools) is available to operators.

Show List Selection

If selected, operators can select between the Service Status or the Service Architecture list.

Show Search Field

If selected, operators can search for services by name

Show Active Filters

If selected, operators can not only see the active filters but can also remove them.

Show Status Bar

The status bar is at the bottom of the widget, showing the number of services in the filtered list.

Show Border

Controls whether the widget is bounded by a single-line border.

Use Theme Color in Toolbar

If not selected, the toolbar will be shown using the default gray theme.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Diagnostics

Analytics\Statistics

Tools\System Status Tools


Set Analog Value Widget

Used by: I/O and Calculations, Analog Input, Analog Status, Analog Output, Analog Control, Counter, Selector Switch, Totalizer.

* Does not use the Style Settings tag.

The Set Analog Value widget is used to create a button that operators may click to write a specific value to an I/O address of the associated tag. Several may be drawn to provide a range of value choices. Note that the configured value is not shown as part of the widget - if you would like it to appear (as shown in the following example) the value must be drawn on the page as text.

Five Set Analog Value widgets, drawn on an image of a fan. The text and the black backgrounds are not part of this widget.

The properties dialog for the Set Analog Value widget:

Value to Write

Set the value that will be written when the completed object is clicked. If the associated tag is an analog output, this may be any value that is legal for that tag. Otherwise, this value should match one of the configured states for the associated selector switch.

If this value is not set, the button will not work.

Hotbox Color

Opens the Select Color Dialog from which you can select a color for the hotbox object. Because yellow hotboxes are often associated with page changes, you may want to select a distinct color.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Analog Controls\

Related information:

Choices for Operator Interaction


Set Value Button Widget

This widget was introduced in VTScada 12.1. For the older version of the button, refer to Legacy Set Value Button Widget.

Used by: I/O and Calculations (all data types). For other output tag types, use the Legacy Set Value Button.

* Does not use the Style Settings tag.

The Set Value Button widget is used to write a value to an output tag, and has the following features that differentiate it from the Legacy Set Value Button Widget.

  • The value to write can come from another tag or an expression.
  • Can display a label or an image.
  • If using a label, you can select the font.
  • Can accept feedback from a tag or expression other than the one used by the linked tag.
  • If the feedback value differs from that configured Feedback Value, a mismatch condition will be shown.
  • Can be disabled.

A typical Set Value Button widget

Set Value Buttons and Multi-Write tags.

This widget will work with Multi-Write Tags but support is limited:

  • Value to Write must be set to 1 in the widget for use with a Multi-Write tag. No other value will work.
  • Multi-write tags cannot act as feedback tags. To use Select Before Operate in the Set Value, a separate I/O tag must be configured as the feedback tag and used as the linked tag in the Execute / Cancel buttons.

The properties dialog for the Set Value Button widget:

Value to Write

As it says. This can be a constant or you can specify a tag or expression that will supply the value at the time the button is used.

Label

Optional text to be displayed on the button.

Font

Select a Font tag that sets the display characteristics of the label.

Image File

Optional path and filename to an image that will be shown on the button. The path must be relative to the application's folder; for example: "Bitmaps\MyIcons\Start.png".

If both a label and an image are specified, the image will appear to the left of the label. If there is no label, the image will be centered on the button.

Feedback Tag

Use only if the value being written to the device by the linked tag is different from the value you expect to read in as feedback from a successful write. Note that expressions cannot be used as feedback.

Refer to the example later in this topic.

Feedback Value

Enabled only if a Feedback Tag (or expression) is configured. If this value does not match that of the Feedback Tag, the widget will blink to indicate a mismatch.

Confirmation

Choose between...

No confirmation: The value is written when the button is pressed.

Confirmation dialog: The operator must confirm the action before the value will be written.

Select Before Operate: Requires a separate Execute Button Widget. The operator must press this button to enable the output, then click the Execute button to complete the action. A Cancel button can be provided, thereby giving operators a chance to "disarm" the select before operate. (Execute / Cancel Button Widget)

Options

Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Using feedback with a Set Value / Execute / Cancel widget configuration

A typical feedback scenario might involve a valve's open / close controls. You have two solenoids, one to open the valve and another to close. A 1 can be written to either tag to execute their assigned movement.

For the feedback, you would have two sensors, typically arranged together in a 2-bit value.

During operation, you might write 1 to solenoid 2, closing the valve when it's open. Feedback goes to 1 as the signal is received. As soon as the valve's spool starts to move, feedback becomes 0 because neither sensor is activated. As the spool completes the movement, the closed sensor is activated, resulting in 2 as feedback.

This configuration would consist of the Open button (Set Value button) linked to the 'OpenValve' tag, having 1 as Value to Write and 1 as Feedback Value, from the combined 'Solenoid Feedback' tag (which could be either a PLC address or a calculation tag).

The Close button would be linked to the 'CloseValve' tag, also with 1 as Value to Write, and 2 as the Feedback Value, with the same 'Solenoid Feedback' tag set as Feedback Tag. In this case, Execute and Cancel need to be linked to 'Solenoid Feedback' because neither 'OpenValve' nor 'CloseValve' have read addresses.

Widget Folders:

Buttons & Switches

Buttons & Switches\Basic Controls


Show Stats Widget (ODBC)

Used by the ODBC Manager.

* Does not use the Style Settings tag.

The Show Stats widget is used to place a button that will open the ODBC Statistics dialog.

The only user-configurable option is to change the label that appears on the button.

Widget Folders:

Analytics\Statistics\

Tools\ODBC Manager\

Related information:

Monitor the ODBC Interface - For further information on the ODBC Statistics Dialog.


Site Alarm List

Used by: Context, Site tags

Use the Site Alarm List widget to draw an alarm list that is prefiltered to show only the alarms in child tags of the linked site or context.

It can also be configured to show all alarms in any tag having an Area property that matches the linked site. Or, it can filter for both child tags of the site, and all tags having a matching Area property.

An acknowledge button will be available for each entry, provided that the logged-on operator has the security privilege required to acknowledge these alarms.

If fields overlap, select a smaller font in the properties dialog.

The properties dialog for the Site Alarm List widget:

Use Theme Color

Choose whether to match the list to the application's theme coloring.

Text Color

Alarms will be shown against a background of the color configured for each alarm priority. Selected alarms are shown against a gray background. For each of these, a dark font tends to be most easily seen.

Show Title

Choose whether to display the title, "Alarms" above the list. The text of the title is not user-configurable.

Alarms to Display

Use these check boxes to control how the filter is applied. You can choose to display:

  • Only alarms for child tags of this site or context.
  • Only alarms whose area property matches the linked site or context.
  • Both of the above.


Site Details Widget

Can be drawn directly by the Context tag. Provides the entire content of the Site Details page, but drawn on a page of your choice.

The Site Details page is the default destination of the Site Summary and Site Draw widgets. This widget should be used sparingly, if at all.

* Does not use the Style Settings tag.

Related information:

Site Details Page - Shows communication, alarm and I/O information for site and station tags.

Configuration options include the following:

Use Theme

If selected, the color theme of the application will be applied to the Site Details page.

Text Color

Must be numeric, corresponding to any of the colors in the VTScada palette. Used for text within the Site Details page, including labels of I/O tags. Defaults to 15, which is white.

AutoResizeWindow

When selected, the page containing this widget will automatically adjust upon opening to show only the area of the widget, plus any whitespace above or to the left.

This option should be used only when the Site Details widget is drawn on a pop-up window. Unexpected behavior will result when used in the application's main window.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Organization/Containers\Context\


Site Draw Widget

Used by: DataFlow RTU, Polling Driver.

* Does not use the Style Settings tag.

The Site Draw tag widget is used to draw station symbols that represent RTUs These display the status at the station being drawn, using two, concentric color indicators. The Site Draw may be configured to display a label or to show only the indicator circles.

A Site Draw legend is available in the Site Tools folder of the Widgets palette. Adding this to your page will help operators interpret the meaning of the color indicators. The center dot will change color according to the status of I/O within the site - Invalid data or an alarm in any I/O tag will indicted by the dot. The outer ring indicates the status of device driver communication with the site.

Site Draw symbols, when clicked, will open an automatically-generated page containing details about the RTU and I/O tags attached to that station. They can also be configured to open a page of your choice instead.

Note that the label is not considered part of the object’s area when trying to select the object to be moved or edited. You must click on the circles to select the object.

The properties dialog for the Site Draw widget:

Sort Order (Alphabetical or Numeric)

Affects the display of the automatically created site dialog. The input and output tags associated with the station being drawn will be included in this dialog in either alphabetic or numeric order, by their description.

If an order has otherwise been specified by each input and output tag's Order property (on the tag's Order tab), the Sort Order will be ignored.

Display with Label

Select this option if you wish the completed station symbol to be drawn with a label showing the description of the tag being drawn.

Text Color

Select a color for the labels within the site draw page.

Use Theme Color

If selected, the site draw page will use the theme colors of your application. Otherwise, the standard colors of gray and black will be used.

Click Action

The usual action upon clicking a Site Draw dot is for the site dialog to open. This dialog-type page is automatically drawn by VTScada. As an alternative, you may choose to have no action occur, or you may select any page that you have created for the site. If using your own page instead of the site dialog, you should consider parameterizing that page so that it may display the tags relevant to the given server. See: Page Properties Parameters Tab.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Specialty\Mapping\

Tag Types\I/O Devices (Drivers)\PLCs and RTUs\Data Flow System RTU\

Tag Types\Communications\Link Management\Polling Driver\

Related information:

Choices for Operator Interaction


Site Icon Widget

Used by: MultiSmart Station, MPE Duplexer, MPE SC, Context tag.

* Does not use the Style Settings tag.

The Site Icon Widget creates a color indicator that both displays the status of communications to the associated station and provides a click-able link to the built-in Station Page for the associated station tag. This is very similar to the Site Draw widget, and uses the same color system for its concentric rings.

The Properties dialog for the Site Icon widget:

Use Theme

When selected, the station page that opens when the operator clicks on this icon will use the color theme configured for the application. Defaults to gray if not selected.

Text Color

Use to change the color of all text used in the associated Station Page. Text defaults to white if left unselected. Click to open the Select Color dialog.

Click Action

The usual action upon clicking a Site Icon dot is for the site dialog to open. This dialog-type page is built into your application. As an alternative, you may choose to have no action occur, or you may select any page that you have created for the site. If using your own page instead of the site dialog, you should consider parameterizing that page so that it may display the tags relevant to the given server. See: Page Properties Parameters Tab.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

The Site Legend provides a guide to the meaning of each color used in the icon. The center dot will change color according to the status of I/O within the site - Invalid data or an alarm in any I/O tag will indicted by the dot. The outer ring indicates the status of device driver communication with the site.

The Site Legend can be accessed via the Site Tools folder as follows:

  1. Open the Site Tools folder of the Widgets palette.
  2. Drag the Site Legend onto the open page in the Idea Studio.

Widget Folders:

Equipment\Lift Station\

Basic Components\Specialty\Mapping\

Tag Types\I/O Devices (Drivers)\PLCs and RTUs\Data Flow System RTU\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Organization/Containers\Context

Related information:

Choices for Operator Interaction


Site Summary Widget

Used by: MultiSmart Station, MPE Duplexer, MPE SC, Context tag.

* Does not use the Style Settings tag.

The Site Summary Widget creates a color indicator that both displays the status of communications to the associated station and provides a click-able link to the built-in Station Page for the associated station tag. It also provides relevant information about the underlying station tag. The full display mode option is shown here:

The Site Legend provides a guide to the meaning of each color used in the icon.

  1. Open the Widgets palette of the Idea Studio.
  2. Open the folder for any of the widgets that use this widget.
  3. Drag the Site Summary onto the current page of the Idea Studio.
  4. Link the widget to the appropriate tag.
  5. Optionally, adjust the display properties.

Configurable properties available in the VGE for the Site Summary widget:

Basic Display Mode

When selected, only the site name will be shown on the label. Otherwise, the name, description and selected communication properties will be displayed.

Use Theme Color

When selected, the station page that opens when the operator clicks on this icon will use the color theme configured for the application. Defaults to gray if not selected.

Text Color

Use to change the color of all text used in the associated Station Page. Text defaults to white if left unselected. Click to open the Select Color dialog.

Click Action

The usual action upon clicking a Site Icon dot is for the site dialog to open. This dialog-type page is built into your application. As an alternative, you may choose to have no action occur, or you may select any page that you have created for the site. If using your own page instead of the site dialog, you should consider parameterizing that page so that it may display the tags relevant to the given server. See: Page Properties Parameters Tab.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Note: You may wish to add a legend to the page so that operators can understand what the color codes of the dot mean. The legend can be found in the Site Tools folder of the Widgets palette.

Widget Folders:

Equipment\Lift Stations\

Tag Types\I/O Devices (Drivers)\PLCs and RTUs\Data Flow System RTU\

Tag Types\Communications\Link Management\Polling Driver\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Organization/Containers\Context

Related information:

Choices for Operator Interaction


Sites Widget

Can be used to draw a dedicated Sites page on another page.

Does not link to a tag, but (optionally) accepts any of a Station tag, Polling Driver, Context tag, or user-defined type as the Parent Tag parameter. The site display will then be limited to tags in that hierarchy.

Parent

Select any of the types listed above to restrict the list to that parent hierarchy.

Use Theme Color

Follows the theme color of the application when selected. A deep gray otherwise.

Text Color

Sets the color of labels within the display. Where the default theme is a deep gray, a light color works best for the text.

Open Sites as Popups

When selected, sites within the hierarchy open as pop-ups in response to an operator's click, rather than navigating within the widget.

Widget Folders:

Basic Components\Multi-Variable\

Basic Components\Specialty\Mapping\

Tools\Site Tools Library


Slider Widget

Used by: I/O and Calculations, Analog Input, Analog Status, Analog Output, Analog Control, Selector Switch.

* Does not use the Style Settings tag.

The Slider widget is used to create an output control. An operator can drag the slider to set a value which will be output by the associated tag.

Any image may be used for the slider image, although images from the Sliders group or the Arrows group of VTScada images are recommended. The slider may be drawn vertically or horizontally and can be configured with the maximum value at either end of the range.

Feedback is provided to the operator while moving the slider, via a tooltip window. You also have the option of querying the operator for verification before any change is saved. If the slider is used to draw a Selector Switch, or an Analog Input or Analog Status tag, configured to write data, then a mismatch between the current value and the last value read will indicated by a blinking image.

To make the slider intuitive to use, it is recommended that it be placed on or near an instrument image that clearly shows the available range of motion, and provides scale markers for reference.

The properties dialog for the Slider widget:

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Draw Vertically

Select this option if you want the completed Slider object to operate vertically. If you would prefer the Slider to operate horizontally, leave this box unselected.

Maximum Value at Top

When selected, moving the slider up (or to the right if Draw Vertically is not selected) will result in an increase of the value to write. Otherwise, values will increase towards the bottom or left as the slider moves.

Setting Value Tooltip On Right

When selected, a tool tip displaying the value to which the slider is being set, appears on the right of a vertical slider or above a horizontal slider. When not selected, the tooltip appears to the left of the vertical slider, below the horizontal slider.

This check box will be labeled Setting Value Tooltip On Top if the Draw Vertically check box is not selected.

Query Changes

If selected, the operator to be prompted for confirmation of any new value being set.

Scale Image

The Scale Image check box can be selected if you want the slider image to scale along with the overall widget. If not selected, the image will remain the same size and shape as the size of the overall slider is adjusted.

Steps

Sets the precision of the control, relative to the scaling value. The default value enables the operator to select 100 possible values within the scale range. Note that operators may have difficulty selecting a value if you set a large number of steps in a short slider.

Scaling Options

Choose whether to use the tag's minimum and maximum scaling values or to set alternative scaling values that will be applied to the output value.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Analog Controls\

Related information:

Choices for Operator Interaction


Sparklines Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations tag (although portions may be used by any numeric tag).

The Sparklines widget is similar to a Plot widget but allows operators to see at a glance whether the tag has values below, within, or above the expected range.

A Sparklines widget for an I/O tag, showing the expected range (blue band),
a low alarm, high alarm and high-high alarm.

The Sparklines properties dialog, Sparkline tab

Time Span

Set the length of time to be represented by the widget.
The time span cannot be less than one minute or greater than one year. The numeric control will allow only integer values, so if you need a time span of (for example) a day and a half, set it to 36 hours.

Number of points to plot

Use this to control how many historic values are averaged for each point in the sparkline.
Note that the widget is also constrained by its size on the screen. While you can set this number as high as 720, a widget that is 100 pixels wide on the screen can show only 100 points.

Value to Output

For a numeric tag, the only option is "Value" - the value of the tag.
For a driver, this can be any of the numeric, logged values, defaulting to ErrorValue. (See: Communication Driver Log-Enabled Variables)

Show Alarms

If selected, horizontal lines will be drawn for the current setpoint of all configured alarms in the tag, using the appropriate color for each alarm's priority.

Show tag's expected range

Enabled only when the widget is linked to an I/O and Calculations tag.

A band within the expected values from that tag is shown shaded in the widget. Shading uses colors from the selected

Reference line value

Adds a line to the graph that can be used as a target reference. You can use any of three methods to set the value for this line: directly within the widget, from another selected tag's value, or from an expression. If selecting a tag, any of the following may be used: I/O and Calculations, Analog Status, Digital Status, PLC Alarm, Pump Status, Analog Input.

If the value used for the reference line is outside the scale range, it will not be drawn.

Scaling tab of the Sparklines widget

If the automatic option is selected, the spark line will continuously scale so that the minimum and maximum values within the displayed range fill the vertical space of the widget.

You can choose to use the tag's scaled minimum and maximum values instead or assign your own values using the space provided.

Display tab of the Sparklines widget

The option to use tag display parameters is available only when the widget is linked to an I/O and Calculations tag, and display parameters are set within that tag.

By default, the Sparkline is a one-pixel wide black line, drawn smoothly through the data points. You may select any color and width you choose.

Other display parameters are as shown. By default, the background and outline are invisible, but you may add them using colors of your choice.

Disable Options tab of the Sparklines widget

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Trends & Historical Data\

High Performance\


SMS Indicator Widget

Used by SMS Appliance tags.

* Does not use the Style Settings tag.

The SMS Modem Indicator widget displays a graphic of an active SMS modem control, showing the name of the associated SMS Appliance tag. It is similar to the Modem Indicator Widget, but displays SMS events rather than a continuous indication of the modem status.

Note the signal strength bars to the right of the device status display, indicating whether your device is receiving an adequate signal from the local tower.

The indicator will display the color red and the target cellular number when a message is being sent.

When a message is being received, the indicator will display the color green and the cellular number of the device sending the message.

Other messages that may be displayed by the indicator include "Initializing", "Disabled", and "No Workstation".

A modem can be reset by clicking on the widget when the application is in operation mode. A modem can also be marked as failed or unavailable using the Disable option of the shortcut menu (right-click on the widget when the application is in operation mode and select the Disable option).

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Communications\Connection Status\

Analytics\Diagnostics\

Tag Types\Communications\Alarm Notification\SMS Appliance\

Related information:

Choices for Operator Interaction


Spider Graph Widget

* Can use properties from a Style Settings tag.

Used by: I/O and Calculations tag (although portions may be used by any analog numeric tag).

The spider graph widget allows operators to see at a glance whether several related tags have values below, within, or above their expected ranges.

A spider graph showing three tags and their expected value range.

Unlike other widgets, which are linked to tags, you must use the selection tool in this widget's properties dialog to choose which tags to represent within the graph (choosing at least three). Any tag with a numeric value can be selected, but I/O and Calculation tags have expected range data.

You must select three or more tags to display within this widget. No useful information is shown with fewer than three tags.

Notes:

  • As shown in this figure, each ray represents a tag, where 0% of the tag's scaled range is at the center and 100% of the scaled range is at the outer circle.
  • Solid lines connect to the rays at a point representing each tag's current value relative to its scaled range.
    (This is why you must include at least three tags to make the widget useful.)
  • The optional dashed lines connect to the rays at points matching the tag's expected values within its scaled range. Those values must be set in the tag's configuration dialog and exist only for I/O and Calculation tags. (see: I/O and Calculations tag: Scaling tab)
  • The space between the dashed lines is shaded in order to improve visibility. The color of that shading is set in the Style Settings tag being used. (see: Style Settings Properties: High Performance tab)
  • Selected tags are matched to rays as shown in the following properties dialog where the ray pointing up (north) matches the first tag in the list, the next ray clockwise matches the next in the list and so on.
  • You are free to rotate the widget so that the first ray points in any direction.
  • Labels (which are the tag's short name) can be shown for each ray. These are useful only if the selected tags have different short names.

Configuration properties of the spider graph widget

Style

Refers to the selected Style Settings tag. If you have not selected otherwise, the default System Style Settings tag is used.

Tag

The list of tags whose values are shown in the graph. Use the + and - buttons to the right to add or remove tags. Use the up and down arrows to change the order, where the first tag in the list is drawn at the up or north direction and others proceed clockwise around the circle.

Show Expected Range

Draw the dashed lines and shading that represent the normal operating range of the tag. (Available only for I/O and Calculations tags.)

Show Background

Shade the entire widget using the background color configured in the Style Settings tag.

Show Axis Labels

Displays the tag's short name outside the circle near each ray.

Rotation

Turn the entire widget so that the ray representing the first tag in the list points somewhere other than the up (north) position.

Widget Folders:

Widgets\High Performance\Spider Graph

Related information:

Style Settings Tags

Choices for Operator Interaction


Station Widgets

Widgets described in this section are used in the automatically-created station pages for Station tags (Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station). They are rarely used outside of those pages.

You can create your own versions of these widgets (which will work with your custom tag types) by following the directions in the topic Create Widgets.

Station-related widgets such as the Site Icon and Site Summary, which are commonly added to custom pages, are described in the main list of VTScada widgets and are not included in this section.


Controller Status Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station

The Controller Status widget is component of the Station Summary widget, monitoring the linked tag. The content and appearance will vary according to the linked tag and the configuration of that tag.

or

The properties dialog for the Controller Status widget:

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Widget Folders:

Equipment\Lift Stations\MPE Duplexer\

Equipment\Lift Stations\MPE SC\

Equipment\Lift Stations\Grundfos Control MPC\

Equipment\Lift Stations\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Pump Control Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Pump Control widget is used to display a control switch, status, and certain statistics for a pump that is part of a station tag. The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for the Pump Control object:

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Pump

Select the pump within the linked station tag.

Widget Folders:

Equipment\Lift Stations\MultiSmart\

Equipment\Lift Stations\MPE Duplexer\

Equipment\Lift Stations\Grundfos Control MPC\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\Pump\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\Pump\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\Pump\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Station All Inputs Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Station All Inputs widget provides a list of all the station's input tags.

The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for Station All Inputs widget:

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Font Tag

Select the font to be used within the widget.

Name or Description

If selected, the tag's name will be shown.

If not selected, the tag's description will be shown.

Show Grandchildren

Choose whether to include only tags at the top level of the station structure or also those within child tags of the station.

Show Digital Label

Choose whether to include the digital inputs

Show Sub Folder

If selected, analog and digital inputs will be shown in separate folders.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Station All Outputs Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Station All Outputs widget provides a list of all the station's output tags.

The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for Station All Outputs widget:

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Font Tag

Select the font to be used within the widget.

Name or Description

If selected, the tag's name will be shown.

If not selected, the tag's description will be shown.

Show Sub Folder

If selected, analog and digital inputs will be shown in separate folders.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Station Comms Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Station Comms widget provides an overview of communication and polling status within the station.

The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for Station Comms widget:

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Station Control Widgets

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

This topic includes the following widgets, all of which are part of automatically-built station pages and all of which have a similar purpose and configuration.

Analog Control List

Analog Input List

Digital Input List

Digital Control List

The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for one of these widgets. Others are similar.

Name Filter

Tag names to include in the list, typically using a wildcard.

Area Filter

Tag area to include in the list.

Expression Filter

An expression for tag properties that must be matched in order to be included in the list.

Sort Expression

An expression specifying the order by which tags will be sorted in the list.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Font Tag

Select the font to be used within the widget.

Show Children

If not selected, only top-level I/O tags will be included in the list.

Name or Description

If selected the linked tag's name will be shown in the header.

If not selected, the linked tag's description will be shown in the header.

Show Header

If not selected, no header will be shown.

Header

Text to display in the header instead of the name or description.

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Station Details Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Station Details widget provides the content for an automatically-generated Station Details page for the linked station tag. The content and appearance will vary according to the linked tag and the configuration of that tag.

For further detail, see Lift Station Page

The properties dialog for the Station Details object:

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Graphic Spacing

Sets the gap between components of the page. Components vary according to the linked tag and the configuration of that tag.

Widget Folders:

Equipment\Lift Stations\Station Details

Tag Types\Pump Station Controllers\MPE\MPE Duplexer

Tag Types\Pump Station Controllers\MPE\MPE SC Station

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC


Station Faults Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

The Station Faults widget provides an overview of alarms within the station.

The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for Station Faults widget:

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Font Tag

Select the font to be used within the widget.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Station Stats Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Station Stats widget provides an overview of pump statistics within the station.

The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for Station Stats widget:

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Font Tag

Select the font to be used within the widget.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Station Summary Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Station Summary widget provides overall monitoring of a station tag. The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for Station Summary widget:

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Widget Folders:

Equipment\Lift Stations\MultiSmart\

Equipment\Lift Stations\MPE Duplexer\

Equipment\Lift Stations\MPE SC\

Equipment\Lift Stations\Grundfos Control MPC\

Equipment\Lift Stations\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Control MPC\


Well Details Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Well Details widget provides monitoring of pump status, water levels, setpoints, and relevant historical statistics. The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for the Well Details widget:

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Disable Well Plot

When selected, the trend of water levels over the past 24 hours will not be shown.

Disable Well Flow

When selected, the flow statistics will not be shown.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\


Well Flow Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Well Flow widget is used to current status and historical statistics about the rate of flow being pumped out of a well. The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for the Well Flow Widget

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\


Well Plot Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

You can create your own version of this widget, which will work with your custom tag types, by following the directions in the topic Build a Station Widget.

The Well Plot widget is used to a 24-hour trend of levels within a station's well. The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for the Well Plot Widget

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Water Color

Sets the color that will represent water.

Alarm Color

Sets the color with which the alarm setpoint line will be drawn.

Plot Color

Sets the color used for the plot line.

Grid Color

Sets the color used for the background grid.

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Show Scales

If selected, scaling values will be shown along the side of the graph.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\


Well Setpoints Widget

This widget is a part of one of the automatically-built station pages. While it can be added to a user-created page, that is not it's intended purpose.

Used by: Grundfos Control MPC, Grundfos Dedicated Controls, MPE Duplexer Station, MPE SC Station, MultiSmart Station

The Well Setpoints widget is used to set the lead and lag setpoints for the pumps. Differing numbers of profiles may be created depending on the linked station type, with each profile having with a different configuration of setpoints. These are provided to allow operators to quickly switch operating parameters in response to changing conditions such as an approaching rainstorm, etc. The various profiles are used only for changing the pump lead and lag setpoints.

For reference, the display also shows the current depth of water in the well as a blue background.

You can adjust the setpoints using the sliders, or for greater accuracy, you may type values into the fields above each setpoint slider.

The content and appearance will vary according to the linked tag and the configuration of that tag.

The properties dialog for the Well Setpoints widget:

Use Theme

If selected, the overall appearance of the widget will follow the applications color theme. Dark gray otherwise.

Text Color

Sets the color for labels and information within the widget. Defaults to white for visibility against a dark gray background.

Setpoints Tag

Select the parent tag, within the station, of all the setpoint I/O tags.

Widget Folders:

Equipment\Lift Stations\

Tag Types\Pump Station Controllers\MPE\MPE Duplexer Station\

Tag Types\Pump Station Controllers\MPE\MPE SC Station\

Tag Types\Pump Station Controllers\Multitrode\MultiSmart Station\

Tag Types\Pump Station Controllers\Grundfos\Grundfos Dedicated Controls\


String Entry Widget

Used by: I/O and Calculations, Analog Input, Analog Status, String I/O Tag

The String Entry widget are used with String I/O tags that are configured to write values. Operators can enter the value to be written in the data entry field. The write operation will happen when focus leaves the field, whether by an Enter, a tab, or a click on some other widget. Characters can be masked for privacy.

The example is configured to show the optional title and bevel.

A form field is displayed. A label on the top-left side says "Value to write". A narrow grey line borders the field, evenly spaced, without intersecting the label.

The properties dialog for the String Entry widget:

Display

Font

Controls the display characteristics of the data entry field, but not the label. If you set individual characteristics using the Format ribbon, this will be an expression, combining those characteristics. Otherwise, select a font tag.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Title

Provide text that will tell the operator what to use this String Entry field for.

Align Title

Choose whether the title should be included in the vertical alignment calculation. For example, if vertical alignment is top-aligned and the align title option is not selected then the title will extend above the widget's bounding box.

Text

Select the color to be used for the input text. Does not apply to the label.

Background

Select the color to be used for the background of the input field. Does not apply to the label.

Mismatch

If the driver supports read and write operations at the same address, then when the last value written does not match the value being read, the widget will display the configured mismatch color.

Draw Bevel

Select whether the completed object should be drawn with a beveled border. If the Draw Bevel check box is selected, the completed object will be drawn with a border surrounding it.

Mask Value

When selected, the value will be masked by asterisks rather than being displayed on the screen or in the event log. This option will most often be selected when the String Entry is being used to write a password to a hardware device, thus preventing other users from discovering the password.

A masked value appears in a field labeled "Enter Password". The digits appear as redacted black dots as opposed to numeric characters.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Forms

Include in Form

Select if this widget is to be included in a data entry form. If selected, this widget will interact with the submit, clear and date time selector widgets.

Time Offset

A numeric value that specifies the quantity of time offset. A time offset is added to a date selector offset. A 15 minute offset applied to an 11:00 AM submission will be recorded as 11:15 AM.

Time Units

A droplist that specifies the unit of time offset in minutes, hours, days or weeks.

Related information:

Numeric Entry Widget

Choices for Operator Interaction

Checkbox Switch Widget

Numeric Value Widget

String Entry Widget

Droplist Widget

Date Time Selector

Submit Button Widget

String Entry Widget

Widget Folders:

Text\

Tag Types\Inputs & Outputs\I/O and Calculations\String\

Tag Types\Inputs & Outputs\String I/O

Tools\Forms\


Submit Button Widget

Used by: Data Entry Forms

The submit button is used with other form-related widgets. For data entry widgets with "Include in Form" enabled, values can be filled into their fields but it won't be submitted until this submit button is clicked. The submit button must be on the same page or pop-up as the enabled data-entry widgets.

The properties dialog for the Submit Button widget:

Font

The font used to display the label. Defaults to the current system font.

Label

Text to display on the button. Defaults to "Submit".

Event Name

This value will be used in the Name column of the Alarm Page.

Event Area

This value will be used in the Event Column of the Alarm Page.

Clear form values on submission

Enable to automatically clear values from the form upon submission.

Confirmation Dialog

If selected, the operator must confirm the action before all values are submitted.

Close pop-up on submission

If the form is a pop-up, enabling this option will auto close the pop-up when submit is clicked.

Disable Control

When selected, operators will not be able to use this widget to submit the populated values. It is possible to create an expression that will check the identity or privilege set of the current operator before enabling this option. See the examples at the end of Examples of Expressions.

A submit button widget with Disable Control enabled will appear "grayed-out" if displaying a label.

This option affects only the submit button widget being configured. In the unlikely event that a second submit button is added to this page, disabling the first submit button will not disable the second.

Related information:

Numeric Entry Widget

String Entry Widget

Droplist Widget

Checkbox Switch Widget

Form Reset Button Widget

Clear Button Widget

Submit Button Widget

Widget Folders:

Tools\Forms\


Tag Icon Marker

Used by: Widgets

Most VTScada widgets contain a tag icon marker. This is the yellow symbol that blinks a question mark when the linked tag's Questionable flag is set, and an exclamation mark when the linked tag is using manual data. If a widget has not yet been linked to a tag, the indicator will show a star (asterisk).

A Tag Icon Marker is added to all user-created tag widgets automatically. For it to function, the tag that the widget will link to must have at least one of the properties, "Questionable" or "ManualValue".

In the case of user-created tag widgets for tags that do not have either of those properties, you are advised to remove the Tag Icon Marker from the widget. This is most often the case when the widget is designed for use with a user-defined tag type, created from a Context type.

The properties dialog for the Tag Icon Marker widget:

Root / Drawn Tag

If the root tag has the property, "Questionable", this will find that parameter and link to it.

ShowInConfig

If selected, the empty yellow marker will be visible on the widget, within the Idea Studio. This is not the case for VTScada widgets, all of which include a Tag Icon Marker, but may be useful for your custom widgets.

Widget Folders:

Basic Components\Specialty\Misc


Tag List Widget

Used by: Context Tag, Analog Statistics tag, Digital Statistics tag, Station tags. Optionally, by user-created tag types.

* Does not use the Style Settings tag.

The Tag List widget provides a highly configurable means of displaying any or all of the child tags attached to a selected parent. If no parent tag is selected, then root of the tag hierarchy is considered to be the parent and any set of tags in the application can be displayed in the list, subject to the configuration of the filtering options.

The Analog Statistics tag is composed of a number of History Statistics child-tags. The Digital Statistics tag is composed of Counter, History Statistics and Totalizer child tags. All of these child types hold numeric (analog) values.

Use this information in the Tag List configuration when selecting the widget and the types to display using that widget.

The Tag List will display each type of child tag using any of the standard widgets available for that type. For example, the Analog Status tags in the list may be displayed using a Meter4 widget while the Pump Status tags are shown using an Image Change widget.

To make the most effective use of the Tag List Widget, you are advised to create a custom widget that will include all the information to be shown in each row of the list. For example, the Tag List widget could show a set of Analog I/O tags using Numeric widgets, but operators would not be able to tell which number matches which I/O until they hover over a number to see the tool tip. A better solution would be to create a widget that includes all the information for a station, laid out in a row, beginning with the name of that station. Use text (ordinary label text) above each column to identify the content in each column.

The Tag List can be filtered and sorted to select and organize which tags will be included. Also, the list itself may be configured to control where the widgets are placed within it and how it will handle multiple pages when there are too many tags for the configured display area.

The steps shown here outline the general procedure to configure a Tag List Widget. Detailed steps for each part of the procedure are provided in following topics.

  1. Determine the type of the parent tag for which you want to draw a Tag List.
  2. Open the Widgets palette within the Idea Studio.
  3. Open the folder for the selected parent tag type.
  4. Drag a Tag List from the palette onto the current page.
  5. Link the Tag List to the parent tag.
  6. Open its Properties dialog.

  7. For each of the tag types to be included in the display, select the tag type, then select which widget will be used to display that type in this list.
    Note that you are not limited to types for which tag instances exist. You can configure the Tag List so that tags that are added later and that match the selection filter will be displayed automatically.
  8. [Optional] Many widgets can be used by more than one type of tag. If other tag types are to use the same widget chosen in step 2, select those types from the Available Tag Types list and click the arrow button to move them to the Selected Tag Types list.
  9. [Optional] Adjust the display options of the selected widget by clicking the Properties button.
  10. For the remaining tag types that you wish to include in the Tag List, repeat steps 2 through
  11. Click the Filter/Sort tab.
  12. [Optional] Restrict which tags in the structure will be included in the list by using the Filtering options.
  13. [Optional] Sort the tags shown in the Tag List display.
  14. Click the Table Layout tab.
  15. Adjust the appearance of Tag List as required.
  16. Click on OK.

Widget Folders:

Basic Components\Multi-Variable\

Tools\Standard Library\

Tools\Report Tools\

Tag Types\Organization/Containers\Context

Closed Access the Tag List Widget

If you select a Context tag to draw, the Tag List is the default widget.

  1. Select a Context tag in the Tag Browser.
  2. Click Draw, or right-click on the tag and select Draw.
  3. Select the Tag List.
  4. Click on the page to locate the lower-right corner of the list.

A Tag List can be drawn for any parent tag, or for all tags in the application.

  1. Open the Idea Studio.
  2. Access the Widgets palette.
  3. Expand the Tools folder, then the Standard Library folder.
  4. Drag the Tag List to the page.
  5. Link to a parent tag, or open the Properties dialog to select a tag type and a list of widgets.

Next task: Select widgets for the list.

Closed Select Widgets for the List
  1. Click the plus sign beside the Draw Methods list.

The Widget Selection dialog opens.

A widget is chosen by first selecting the tag type to be drawn. With that information, VTScada can provide a list of the available widgets for the chosen tag type.

  2. Select the appropriate tag type from the drop-down list.

This should be the next tag type that you intend to display in the Tag List widget.

A list of the available widgets for that tag type will be displayed. Only one method may be used in the Tag List for each tag type.

  3. Select the appropriate widget.

The Widget Parameters dialog will open. This is a condensed version of the properties dialog that would normally be displayed when using the selected widget.

  4. Set the display parameters that will be used by all instances of this widget in the Tag List display.
    At a minimum, this will include the standard three operator controls: Disable Trend, Disable Navigation or Disable Tooltip.
  5. Click OK.

The tag type that you used to select the widget will be displayed using this method in the Tag List. This is the tag type shown in the Associated Tag Types list.

It is possible that other tag types could also be displayed using this widget. These are the items in the Tag Types Available list.

Next task: Filter and sort the display.

Closed Filter and Sort the Tag List Display

Unless otherwise filtered, all the tags in the parent-child tag structure, that have had a widget selected for their tag type, will be included in the list. You may use the filter options to limit the list to only those tags that are of interest to you.

The first filtering option is "Immediate Children Option". This is selected by default, restricting the display to only those tags one level below the selected parent.

If deselected, then all the tags in the tag structure (that have an associated widget from the previous tab and that are not otherwise excluded by the configuration of the filter) will be included in the Tag List.

Name Filter:

Using the wildcard character, *, enter a pattern to restrict the Tag List to only those tags whose Name property matches the pattern.

Example: "Pump*" - all tags whose name begins with the letters "Pump".

Area Filter:

Using the wildcard character, *, enter a pattern to restrict the Tag List to only those tags whose Area property matches the pattern.

Example: "*zone" - all tags whose area property ends with the letters "zone".

Equipment Type:

If the Tag List displays I/O and Calculation tags, select one of the equipment types used for those tags from the drop-down list.

Expression Filter:

Using the VTScada Expression language, you can create a filter that restricts the Tag List based on tag property or combination of properties. For example: \Units == "FT". This will limit the selection to those tags whose engineering units are "FT".

Note that, if filtering for a value you must use \Root\Value. All other properties can be referenced by simply \PropertyName, but \Value must be preceded by \Root.

You can create complex filters such as "all analogs and all inputs", thereby excluding analog I/O tags that are outputs. The expression would be:

\CheckTagGroup(\Root, "Analogs") && \CheckTagGroup(\Root, "Inputs")

... to get the intersection of the two groups.

Useful groups for the IO tag are Analogs, Analytics, Digitals, Inputs, Outputs, Loggers, Numerics, and Strings.

You could also filter for the I/O tag's mode, but use care: The mode that you see when configuring the tag is a phrase, so that it can be translated in the case of a multi-lingual application. Rather than filter for a mode such as "Analog" or "2-bit Digital", your expression must match the phrase label.

\Mode == "AnalogLabel"

Phrase labels used for the mode parameter include: AnalogLabel, DigitalLabel, DiscreteLabel, Digital2BitLabel, CalculationNumLabel, CalculationStrLabel, and StringLabel.

Sort the Tag List Display

By default, the items in the Tag List will be sorted by name. Using the controls shown here, you may sort the list by other parameters, and may also perform a sub-sort. For example, you might sort the tags by area, then within each area sort by name.

You can also choose whether to sort the list alphabetically or numerically, and in ascending or descending order.

The available fields for sorting are Name (tag name), Area, Tag Type and Draw Method. You can also create an expression that returns a string or a number, to sort based on any tag property. Examples of expressions for sorting include, \Value, \Description, and \Units.

Next task: Configure the tag list layout.

Closed Configure the Tag List Layout

Cell Settings

Each tag in the list, displayed using the selected widget, counts as one cell.

You may set the following options for the cells:

Minimum Width and Height

Measured in pixels. Sets the smallest size that each cell may be. Cells may be as large as required. A widget will not necessarily fill its cell unless you have selected "Stretch to fit".

Stretch to fit.

The widget in each cell will be scaled to fit the cell size.

Maintain Aspect Ratio.

If stretched, determines whether the widget will be stretched equally in width and height.

Horizontal and Vertical Alignment options.

Sets the widget's position within its cell, in the event that the widget does not fill the cell. The default options are to center the cells within the Tag List, both horizontally and vertically. Some users may prefer a table that is left-aligned with entries that start at the top, filling downwards.

Table Settings

Scroll direction

If there are more tags to display than will fit within the area of the Tag List, a scroll bar will be added and the operator can page through the tags. This option controls whether the list scrolls from top to bottom or from left to right.

Display Order

For the tags that fit within the Tag List's area, the order of display - left to right or top to bottom, are controlled by this option. This option is affected by the sorting order selected in the previous tab.

Number of Rows and Number of Columns.

Sets how many rows and columns of cells are to be shown in the Tag List's area. Best fit will take the size and number of cells into account to display multiple rows or columns of cells if there is room.

Row Spacing and Column Spacing.

Adds a margin, measured in pixels, between each row or column, should there be more than one row or column in the displayed tag list.

Unique Key for saving the scroll position

Variables such as dialog positions and sizes are normally retained per-user and per-module. What this means for the tag list is that the scroll position would be saved, but shared across all tag lists.

By providing a unique key to this parameter, each tag list drawn in an application can save its own scroll position. If used, the key may be any phrase such as, "Main Station Display" or "Treatment Plant Panel".

If the folder is used in a parameterized page, it will be necessary to have a different key for each version of the page that you open. Therefore, this property may be linked to a page parameter or expression.

Reserve Space for Scroll Bar

When selected, space will be provided for a scroll bar, whether one is required or not.

Cannot be selected when Hide Scroll Bar is selected.

Hide Scroll Bar

When selected, the view is limited to only the top N drawing methods. (Those that fit the available space.) This may be useful in if you wish to display the values of the top 5 tags based on the sorting and filtering you have configured. By configuring grid dimensions such that rows and columns allow space for N widgets, and then hiding the scroll bar, users can display the top N tags while restricting access to subsequent ones.

Cannot be selected when "Reserve space for scroll bar" is selected.


Text Change Widget

"2 state" versus "4 state". Not all tags will have all the states shown in these examples. Alarms have only state 0 and state 1 and therefore must use the "2 state" version of this widget.
Digitals might only use two states, but they can have four and therefore must use the "4 state" version of the widget.

Used by: Drivers, I/O and Calculations, Alarm, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Counter, Deadband, Digital Input, Digital Output, Digital Status, Digital Control, Function, History Statistics, Modem, Network Status, Pump Status, Network Status, Rate of Change, Roster, Selector Switch, Serial port, SQL Logger, Totalizer.

The Text Change tag widget is used to represent the associated tag's value as a text string that changes (text or color) based on the tag's value. While this widget is available to analogs, it is most commonly used with digital and other tags that have clearly defined states (values from 0 up to 3).

If linked to a tag that has values above 3, this widget uses the modulus (remainder) of the tag's value divided by four. For example, 7 is read as 3.

The properties dialog for the 4-State Text Change widget:

Click to expand

Display Options

Style

Optionally, select Style Settings Tags to control the colors shown by the light, in response to the linked tag's value and alarm state.

Font

Select one of the font tags (or parameter linked to a font tag) that you wish to use to display the text. The display will use the default system font if you do not select a font tag.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Horizontal Alignment

Sets the position of the text within the display area. You may select left-aligned, right-aligned or centered. To align the display area itself with other elements on the page, see: Alignment and Positioning Tools.

Vertical Alignment

Sets the position of the text within the display area. You may select top-aligned, bottom-aligned or centered. To align the overall widget with other elements on the page, see Align.

Horizontal and Vertical Alignment may be represented as an expression with a value of 0, 1 or 2.
0 = Left or Top
1 = Center
2 = Right or Bottom

Labels

State x Text

Provides input fields where you can type the text to display when the tag is in the corresponding state.

Invalid Text

Provides the same function as State x Text for the case when the tag’s value is Invalid.

Colors

State x Color

Opens the Select Color Dialog, from which you can choose a color to display when the tag’s value is in the corresponding state.

Invalid Color

Provides the same function as State x Color for the case when the tag’s value is Invalid.

Text and Background

Opens the Select Color Dialog from which you can select the color of the text (defaults to black) or the background (defaults to transparent).

Outline

Opens the Select Color Dialog, from which you can select a color to use for the widget outline. Defaults to transparent.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Indicators\Basic Indicators\

Basic Components\Text\

Related information:

Choices for Operator Interaction


Thermometer Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Status, Calculation, Comm Link Sequencer, History Statistics, Rate of Change.

* Does not use the Style Settings tag.

The Thermometer widget represents the associated tag's value as a photorealistic alcohol thermometer.

The properties dialog for the Thermometer widget:

Tag

The Tag field displays the name and description of the tag that is associated with this widget. You can use this to select a different tag or parameter to use as the data source for this widget.

Options

Set the number of major divisions and minor divisions within each major division. Defaults to 10 and 5.

Choose whether to include the text used for engineering units within the gauge. Defaults to show units.

You can add a degree symbol to the engineering units when configuring the tag by holding down the Alt-key while typing 0176 on the numeric keypad. Release the Alt-key before typing the C or F.

Colorization

Use the color selector dialogs to set the color of the liquid, text and thermometer background. This widget does not use the Style Settings tag.

Scaling

If Use Tag Scaling is selected, the minimum and maximum range of the meter will be controlled by the tag's scaled minimum and maximum values.

Otherwise, you can override those values to set your own scale range. For example, assume that you have a tag for which the minimum and maximum scaled process values are 20 and 80 respectively. Drawing this tag with a minimum value of 0 and a maximum value of 100 will result in a meter that shows a full range of numbers from 0 to 100, but whose needle will move only between 20 and 80.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\

Related information:

Choices for Operator Interaction


Toggle Button Widget

Used by: I/O and Calculations tag, Digital Status tag

* Can use properties from a Style Settings tag.

The Toggle Button widget is used to display an up / down toggle button, providing digital control and feedback.

When the toggle is pressed (or "down") it has a blue highlight and displays the "down" label. When "up", it does not have the blue highlight.

You control whether the signal sent for pressed / down is a zero or a one. The signal sent for "up" will be the opposite.

The properties dialog for the Toggle Button object:

Style

Link to the appropriate Style Settings tag. Defaults to the System Style.

Override Style Labels

If selected, the following two options will be enabled. Otherwise, the labels will match those defined for a digital tag or the matching equipment type.

Button Up Label

Enabled only when Override Style Labels is selected. Sets the label to display in the "up" position.

Button Down Label

Enabled only when Override Style Labels is selected. Sets the label to display in the "down" position.

Value to write

The default is to write a 1 when the button is pressed and in the "down" position.

The only alternative is to write a 0 when the button is pressed, meaning that 1 will be written on the following press when the button returns to the "up" position.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Button & Switches \ Basic Controls


Toggle Polling Button Widget

Used by: Polling Driver, DataFlow Systems RTU

* Does not use the Style Settings tag.

Use this widget to give operators the ability to enable or disable polling without needing to open the Polling Driver's properties dialog. Operators must possess either the Modify Tags privilege or the Manual Data privilege to change this setting.

While polling is disabled, no communication will be sent or received through the station. To switch from a timed poll to continuous communication, use the Fast Poll option of the Polling Driver.

The properties dialog for the Polling Button object:

Button Up Label

The label displayed when polling is disabled, and a click on this button will enable it. You may provide any text or expression you prefer.

Button Down Label

The label displayed when polling is enabled, and a click on this button will disable it. You may provide any text or expression you prefer.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tag Types\Communications\Link Management\Polling Driver

Related information:

Enable Polling Checkbox Widget

Choices for Operator Interaction


Toggle Switch Widget

Used by: Selector Switch.

See also: Illuminated Toggle Switch Widget

* Does not use the Style Settings tag.

The Toggle Switch widget, one of the native widgets for Selector Switch tags, is a control method used to output either of two possible values. The values will be those configured for the first two of the three positions of the selector switch, 0 to 1.

A variety of switch images are available in the Selector Switches images group. A few of the available choices are shown here (for every On image there are matching images for the Off state and the Invalid state, drawn in the same style).

The color and image choices work the same way as an Image Change Widget. In addition to the images from the Selector Switches image group, you can use any image that has a color indicator region defined within it (pump and motor images commonly include these indicator regions). This will allow you to use an equipment image as a toggle button in your application. You could also choose to not use any image, and simply place the rectangular drawing area over a region of active orange (RGB 255, 160, 0) to create a custom control toggle.

To indicate to the operator that the image is a button, a hotbox is drawn around it. A hotbox is commonly understood to define an area that can be clicked upon as a control action.

In the event that the position feedback from the selector switch indicates that the actual position is not the same as the requested position, the border of the image will blink using the mismatch color. You should select a color that stands out clearly on your page background, but red is not advised because it is commonly understood to mean that an alarm has been triggered.

Select a switch position

The switch works by toggling between states 0 and 1 whenever the operator clicks on the button. Should the tag be in an invalid state (which will not be unusual when a selector switch is first created) then it is not clear whether the first click should move the switch to the state 0 or the state 1 position. For this reason, a dialog will prompt the operator for an initial position, using the terms you provide in the Selection Dialog area.

Selecting the Confirmation Dialog option will force the operator to confirm each click on the button by selecting OK or Cancel from a dialog.

Use State 0 Image For All States

Select this box if you wish to use the image selected for State 0 for all states of the tag.

You might select this if using an image that has an indicator area (a small rectangle at the base), which is to change color according to the state of the tag.

State x Image

Image Select

Opens the Select Image dialog, within which you can browse for images, import new images, and select the image to use.

VTScada recognizes the following image formats: .BMP, .CUT, .EMF,. JPG, .PCX, .PNG, .TIF, .SVG* .WMF

Using .SVG images comes with the following considerations:
• SVGs are resource heavy! They are slower to draw than other image types and roughly twice as costly as .PNG and .JPEG. They are intended for images that must scale without loss of resolution. Reconsider your file type if the image is larger than 1MB or will be redrawn often.
• Animated SVGs are not supported.
• Only elements supported by Microsoft Direct2D are supported. Unsupported elements won't load.
• .SVG images are only supported on Windows 10 version 1703 and up. In applications running on earlier versions of Windows, .SVG images won't load.

Image Adjust

Opens the Adjust Image dialog box, which can be used to change the color and other display characteristics of the image. See: Adjust Image Dialog

Image Clear

Remove the selected image and do not select a replacement.

Invalid Image

Provides the same function as State X Image for the case when the tag’s value is Invalid.

Hotbox Color

When the operator moves the mouse pointer over the Toggle Switch image, a hotbox will appear to help indicate that this is a control that can be clicked. Use this option to select the hotbox color.

Mismatch Color

If the associated Selection Switch tag detects that the actual position of the switch is not the same as the position that the operator requested, a box of the mismatch color will blink around the switch image to indicate a problem. The color selected for this should provide a good contrast from the page background, and should also be a color that the operator will associate with a problem condition.

Confirmation Dialog

Select this option if you want the operator to have to confirm each control action from this object. See also: Confirmation Prompts for Output Tags.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Buttons & Switches\

Related information:

Choices for Operator Interaction Choices for Operator Interaction


Token Level Box

A Token Level Box is an Alarm Priority Box, configured to indicate that a Control Token exists and to show the associated Token Level (priority) number.

Refer to Control Tokens for a full description of Control Tokens.

When configuring the widget, ensure that the option, Show Token Icon is selected.


Token Level Icon

A Token Level Icon is an Alarm Priority Icon, configured to indicate that a Control Token exists and to show the associated Token Level (priority) number.

Refer to Control Tokens for a full description of Control Tokens.

When configuring the widget, ensure that the option, Show Token Icon is selected.


Tokens List

A Tokens List widget is an Alarm List widget, configured to display active Control Tokens.

Refer to Control Tokens for a full explanation of what Control Tokens are and how they work.

The Column Format of the list must be set to Tokens. When set, the Starting List is restricted to Tokens as the only option.

Do not change the Alarm Database selection. The widget will not display Control Tokens if the Alarm Database is set to anything other than "All".

Columns display:

Token Level Icon

The number and color indicate the priority of each Control Token.

Time

When the token was added.

Release

Enabled only for authorized operators (Those having the Add / Release Token privilege or the Token Administrator privilege.)

Aside from Token Administrators, tokens can be released only by their owners, where "ownership" may be restricted not only to a user, but to the workstation or the sign-in session where the user created the token. (Advanced programmers can create a custom definition of ownership through script code.)

Area, Name, Description

Information about the tag to which the Control Token has been applied. If this is a parent tag, all the child tags will also have control tokens.

User

The person who created the token.

Widget Folders:

Tools \ Control Tokens


Token Requests List

A Tokens Requests List widget is an Alarm List widget, configured to display active Control Token Requests.

Refer to Control Tokens for a full explanation of what Control Tokens are and how they work.

The Column Format of the list must be set to Token Requests. When set, the Starting List is restricted to Token Requests as the only option.

Do not change the Alarm Database selection. The widget will not display Control Token Requests if the Alarm Database is set to anything other than "All".

Columns display:

Token Level Icon

The number and color indicate the priority of each Control Token request.

Time

When the token was requested.

Grant

Enabled only for authorized operators (The token owner who has the Add / Release Token privilege or anyone with the Token Administrator privilege.)

Aside from Token Administrators, token requests can be granted only by the person who owns the token, where "ownership" may be restricted not only to a user, but to the workstation, the sign-in session where the user created the token, or other definition as defined by custom code.

Deny

Enabled only for authorized operators (The token owner who has the Add / Release Token privilege or anyone with the Token Administrator privilege.)

See notes under Grant for who may deny requests.

Area, Name, Description

Information about the tag for which a Control Token is being requested.

User

The person requesting the token.

Widget Folders:

Tools \ Control Tokens


Tokens and Token Requests List

A Tokens & Token Requests List widget is an Alarm List widget, configured to display active Control Tokens or Control Token Requests according to the selected tab.

Refer to Control Tokens for a full explanation of what Control Tokens are and how they work.

Refer to Tokens List for details about the Tokens List.

Refer to Token Requests List for details about the Token Requests List.

Widget Folders:

Tools \ Control Tokens


Top Bar Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Deadband Control, Function, History Statistics, Script, Selector Switch, SQL Logger.

* Does not use the Style Settings tag.

The Top Bar widget is used to display a tag's value as a vertical bar, the length of which increases from the bottom towards the top as the tag’s value increases. When the tag’s value is at a minimum, the bar will be shown as a thin line at the bottom of its range. When the tag’s value reaches its maximum, the widget will be displayed as a rectangle, filling the range.

The properties dialog for the Top Bar widget:

Set Color

Opens the Select Color Dialog from which you can select a color for this object.

Low Scale Range and High Scale Range

In most cases, these fields will be display-only, showing the Scaled Process Data Min and Scaled Process Data Max values configured for the associated tag.

These fields become editable when the widget is used to display a function or Calculation tag. The most common use is to provide an output range of 0 to 100 (%) given a data source whose numbers do not match these values (perhaps ranging from 20 to 80, for example). Set the low scale range to the value expected from the data source when it is at its minimum and the high scale range to the value expected from the data source when it is at its maximum.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Gauges\Basic Analogs\

Basic Components\Bars\

Related information:

Choices for Operator Interaction


Two Color Bar Widget

Used by: I/O and Calculations, Alarm Status, Analog Input, Analog Output, Analog Status, Analog Control, Calculation, Comm Link Sequencer, Counter, Deadband, Digital Control, Digital Status, Function, History Statistics, Network Status, Pump Status, Rate of Change, Script, Selector, Totalizer, Trigger, SQL Logger.

* Does not use the Style Settings tag.

The Two Color Bar tag widget is used to display tag data using an animated, multi-colored bar. Its appearance is similar to the Color Fill widget with the addition of a second color that will be displayed when the value goes above a set point. A common use of this second color is to provide clear notice that a value is above its safe limit.

Examples showing the Two Color object, the same object behind a tank cut-away image and again with a value exceeding the set point.

Despite the name, four colors are used to fully configure the Two Color Bar object:

  • The value of the tag is displayed in one color, the Bar Color, shown as green in the example.
  • The portion of the tag's value exceeding a user-defined setpoint value is displayed in a second color. This is the High Color, shown as red in the example.
  • The background of the object's drawing area is displayed in a third color: the Unfilled Color.
  • If you would like this object to be visible only where it overlaps a defined area, you may set the Changed Color to that of the defined area. Any portion of the Two Color object not over that color will be invisible. This feature can be used to build your own tank cut-aways.

The properties dialog for the Two Color widget will look similar to the following. There must be a Filled Color, but you are free to leave the Changed Color and Unfilled color properties unselected.

Animation

Select one of Top, Right, Bottom or Left to set the direction that the bar will grow with increasing values.

Changed Color

If set, the object will only be visible when placed above an area of this color. The button opens the Select Color Dialog from which you can choose a color. Select transparent to stop using the changed color. Click the X button to remove the color if you change your mind.

Bar Color

Opens the Select Color Dialog from which you can choose a color to that will represent the tag’s value.

Unfilled Color

Opens the Select Color Dialog from which you can choose a color to display as the background for the bar color.

Setpoint

Use this field to define the point, above which the tag’s value will be shown using the High Color rather than the Bar Color. May be set using any of a constant value, an expression, a second tag’s value or a page parameter.

High Color

Opens the Select Color Dialog from which you can choose a color to display for the portion of the bar showing the value above the set point.

Use Tag's Scaled Min & Max Values

In most cases, it is best to select this option. When the tag is at its minimum scaled output value, the bar will not be visible and when the tag is at its maximum scaled output value, the bar will fill the area of the widget.

Choosing not to use the tag’s scaled min and max values enables the Minimum Value and Maximum Value controls which you can use to scale the bar length relative to the tag’s output scaled values. The scaling you set will apply only to this one instance of the tag widget. This option is normally used when the object represents tags such as Calculation and Function that do not have their own scaled values.

Unlike widgets such as the Top Bar, the bar for the color fill will be visible only within the area originally drawn for this object, regardless of the scaling you define.

Minimum Value and Maximum Value

The Minimum Value and Maximum Value fields are used to scale the color fill bar relative to the tag’s scaled output values. For example, given a tag with scaled output ranging from 0 to 100:

Setting the widget’s scale range from 0 to 200 results in a bar that reaches only half the length drawn when the tag is at its maximum value.

Setting the widget’s scale range from 0 to 50 results in a bar that reaches its full length when the tag is still only half way to its maximum value.

Unlike widgets such as the Top Bar, the bar for the color fill will be visible only within the area originally drawn for this object, regardless of the scaling you define.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Basic Components\Bars\

Basic Components\Color Indicators\

Related information:

Choices for Operator Interaction

Color Fill Widget


Totalizer Widget

Used by: Data Flow Pulse Input tags

This widget is not used by the Totalizer tag.

* Does not use the Style Settings tag.

The Totalizer widget calculates and displays the combined total of the value of the Pulse Input tag being drawn within a user-defined period of time. Each time the user-defined period of hours has cycled, the Totalizer object will automatically reset to 0 and will begin to recalculate.

The Totalizer tag widget does not calculate the average value of the tag. Rather, it increments the new value to the former value each time the value changes. For example, if the value of the Data Flow Pulse Input tag changes from 27 to 30 to 32 to 21 within the user-defined period of time, the value displayed by the Totalizer object will be 110. It should also be noted that the Totalizer tag widget rounds values off before totaling them (for example, 23.62 will be rounded off to 24 and then added to the total value).

The properties dialog for the Totalizer widget:

Font

Select one of the font tags (or parameter linked to a font tag) that you with to use to display the text. The display will use the default system font if you do not select a font tag.

The parameters button is enabled only if the tag is drawn on a page that includes a font parameter, or if the tag is part of a widget and the associated widget editor is open.

Note: While it is possible (and very easy) to modify the appearance of the text within this widget using the Format ribbon of the Idea Studio, you will find it much easier to manage a group of similar controls by defining a font tag and selecting that for each. Changes to all can then be made by adjusting the properties of a single font tag.

Type of Border

Examples of the three border types are shown at the beginning of this topic.

Colors (Text and Background)

Opens the Select Color Dialog from which you can select the color of the text.

The background color against which the text will be displayed can also be defined.

Restart Period

Set to the number of hours (or fractions of an hour) after which the widget should reset to 0 and begin totaling again.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Statistics\

Related information:

Choices for Operator Interaction


Vertical Buttons Widget

Used by: Selector Switch.

* Does not use the Style Settings tag.

The Vertical Buttons widget, one of the native widgets for Selector Switch tags, is a control method used to output one of three possible values. The values will be those configured for the three positions of the selector switch, 0 to 2 in order from top to bottom.

If the underlying selector has only two positions, then only the top and the middle button will be functional. The operator may click the bottom button, but this will have no effect on the switch position or output. Due to the confusion that this may cause, vertical buttons should be used only with three-position selector switches.

Color is used to indicate that either a mismatch in state has occurred, or that an alarm is active as shown in the following examples.

Vertical buttons in a normal operating state (A), showing a state mismatch (B) and showing an active alarm (C). (See: Selector Switch Tags, for a discussion of mismatch conditions.)

The following image shows the properties dialog where you can set the properties of the object.

Position Text n

Set the labels that will appear on the buttons. The buttons are drawn from top to bottom and match the Position 0 through Position 2 settings of the associated selector switch.

Mismatch Color

Use the slider to set the color that will be superimposed on a button in the event of a position mismatch in the selector switch. A sample image displays the result as you adjust the slider.

Options

Confirmation Dialog / Disable Control / Disable Context Menu / Disable Tooltips.

Refer to Operator Interaction Controls for a full description of these standard widget options.

Widget Folders:

Buttons & Switches\Basic Controls\

Basic Components\Button Controls\

Related information:

Choices for Operator Interaction


Web Browser Widget

Used by: no tags.

* Does not use the Style Settings tag.

The Web Browser widget is used to display the contents of a specified web page.

To use this tool on either a thick client (workstation) or the VIC, the workstation requires the optional WebView2 component, which is built on the Edge browser from Microsoft. (The Anywhere Client does not require WebView2 to be installed.)
If WebView2 is not installed, it can be obtained by running the VTScada or VIC installer and selecting the option to install WebView2. Alternatively it can be downloaded from Microsoft, via the Evergreen Bootstrapper Installer or via the Evergreen Standalone Installer for machines with restricted access to the Internet.

Some websites cannot be viewed in the Anywhere Client because they disallow themselves from being embedded inside other websites (the Anywhere Client is fundamentally "another website") through the X-Frame-Options header. Examples include https://youtube.com.
Those websites will display in a WebBrowser widget on a workstation or VIC, but will not display on the Anywhere Client.

If using a secure connection (TLS) for thin clients, WebBrowser widgets viewed on Anywhere clients can display only secured URLs (https://, not http://)

If you have control over the embedded website, you might consider excluding the X-Frame-Options header for any resources you want to be available to WebBrowser widgets in Anywhere Clients.

Edge and Chrome block PDFs shown in the Web Browser widget when using the Anywhere Client. This is related to the sandbox attribute set on the iframe.

The following example shows https://www.vtscada.com within the Overview page of a VTScada application.

Within the Idea Studio, only a placeholder is shown.

Connections to the website address configured in the widget are made from the client device and are not relayed via VTScada. For example, a thin client showing a widget configured to display https://www.vtscada.com will make this connection directly.

Where the URL is for a camera that is not reachable from end-user devices, (for example a network camera that the VTScada server can connect to but an end user’s phone cannot due to the network configuration) you should use the Camera Tag and the Camera Widget instead of the Web Browser widget. The Camera Tag offers a solution that relays the video stream via the VTScada server.

The properties dialog for the Web Browser object:

URL

The address of the initial website to display on the page.

If given in an expression, the browser will navigate whenever the URL changes.

Private Mode

Select to use private browsing. Has no effect on the Anywhere Client.

Name

A text value that serves as an identifier for the web browser.

Widgets that control the web browser use this identifier to indicate which web browser on the page is the one that they want to control.

Enable JavaScript

Allow JavaScript in the browser.

Enable Context Menu

Allow the right-click context menu in the browser. Always enabled on the Anywhere Client.

Allow URL Domains

Restrict browsing to pages under only the listed domains. The browser will never browse to domains outside that list, whether the user is trying to follow links outside those domains, or if outside links are given in the initial URL or via a navigation widget.

To allow multiple domains, list them one-per-line in the edit field. Leave blank to allow all domains. Has no effect on the Anywhere Client.

Widget Folders:

Tools\Web Browser Tools


Web Browser Navigate Button

Used by: no tags.

* Does not use the Style Settings tag.

Use the Web Browser Navigate Button widget to provide a button that operators can click to navigate to a pre-defined URL in a selected Web Browser Widget. The button will not prompt for a destination URL.

If more than one Web Browser widget exists on a page, give each a name and configure the button with the name of the browser it should control.

The properties dialog for the Web Browser Navigate button:

Name

Enabled only if the page contains a Web Browser widget that has been given a name.

This button searches for the named web browser in the current widget (if any), in the calling widgets (if any), or in the page, in that search order.

Button Label

The text to display on the button. Defaults to "Navigate".

Tool Tip Label

Text to display when the operator hovers over the button.

URL

A pre-defined URL, to which the Web Browser widget will navigate when this button is clicked.

Widget Folders:

Tools\Web Browser Tools


Web Browser Navigate Hotbox

Used by: no tags.

* Does not use the Style Settings tag.

Use the Web Browser Navigate Hotbox widget to provide a target that operators can click to navigate to a pre-defined URL in a selected Web Browser Widget. The widget will not prompt for a destination URL.

If more than one Web Browser widget exists on a page, give each a name and configure the hotbox with the name of the browser it should control.

The properties dialog for the Web Browser Navigate hotbox:

Name

Enabled only if the page contains a Web Browser widget that has been given a name.

This hotbox searches for the named web browser in the current widget (if any), in the calling widgets (if any), or in the page, in that search order.

URL

A pre-defined URL, to which the Web Browser widget will navigate when this hotbox is clicked.

Color

Opens the Select Color Dialog from which you can select a color to display when the mouse pointer is within the area of the hotbox.

Widget Folders:

Tools\Web Browser Tools


Write Priority Indicator Widget

Used only with I/O and Calculations tags attached to BACnet Drivers.

* Does not use the Style Settings tag.

The Write Priority Indicator widget is used to display the status of a command-able property in a BACnet device. It is composed of two parts:

  • A priority level indicator that shows the priority of the effective command in the device (the highest priority with a non-null value)
  • A command status box that changes its color based on the status of the command priority set by the Write Address of the attached tag.

(sample shows "default")

The combination of the color and the priority level determines the status of the command, related to the address priority (default colors):

No priority shown

Box not shaded: no command set at any priority level.

Current priority shown / green box

Current command set and it’s the highest valid priority level.

Higher priority shown / orange box

Current command set and it’s not the highest valid priority level.

Another priority shown (either higher or lower) / box not shaded:

Current command not set and at least one valid priority level is set.

This widget actively reads the Priority_Array property of the address in the selected tag, updating it according to the scan rate property. This may result in higher-than-expected network traffic in limited networks (approximately 70-100 bytes/sec). This will increase for each widget linked to a different tag property drawn in a page. Tags with different priorities for the same address will share the results.

The properties dialog for the --- object:

Scan Rate

The interval between updates from the device. Defaults to once per second.

Not Commanded Color

Sets the color of the box when there are no active commands for the tag's address (default = no color).

Commanded Color

Sets the color of the box when the current priority is set and the highest level for the address (default = green).

Overridden Color

Sets the color of the box when the current priority is set, but there's a higher level set in the device (default = orange).

Auto Request Level

Determine the components of the widget to show:

Show All - both the priority level indicator and the command status box are shown

Show Priority Level Only - only the number showing the effective priority is shown

Show Command Status Only - only the colored box indicating the command status is shown

Show Border

Displays a border surrounding the widget.

Font

The font to display the priority level indicator.

Text Color

The color of the text in the priority level indicator.

Border Color

The color of the border surrounding the control.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Tools\Command Prioritization


Property Reference

You can view, edit and add all properties directly using the Edit Properties page of the Application Configuration page.

Support for multilingual applications caused the following changes to the properties:
* Labels, which had been stored in property files, are now stored in language files.
* Properties that specify time or date formats formerly used numeric codes but now use language phrase identifier keys. (Date and Time Phrase Keys)
* Defaults for the alarm notification templates are now stored in language files.

Basic Mode of the Edit Properties page

The Edit Properties page opens to a simplified view, where three tabs contain the most commonly used properties. You can access the full selection of properties at any time by clicking the Advanced Mode button at the lower right corner of the page.

By changing properties for your application, you can:

  • Choose to run the application in a window instead of in full screen.
  • Change labels on the screen - perhaps to create an application for a language other than English.
  • Control what is said by spoken alarms.
  • Decide whether alarm pop-up messages are to be enabled.
  • And much more.

The general steps to set a value for a property using the Application Configuration dialog are as follows:

  1. Open the Application Configuration dialog.
  2. Open the Edit Properties page.
  3. Find the property...
    1. The most commonly accessed properties can be found in one of the four tabs of the basic mode: Display, Alarms, Historical Data Viewer or Other.
    2. For other properties, click the Advanced Mode button to view a list of all. The list can be sorted by name, type, and value.
    3. Advanced Mode: If the property has not yet been set in the current application, copy it from the underlying OEM layer. OEM properties are shown in gray and have a check mark in the OEM column.
    4. If the property is not listed, click the Insert button to add it.
  4. Change the property's value.
  5. Apply the changes.
  6. Deploy the changes if Automatically deploy local changes is not selected in the "Other" tab of the basic mode.

Properties are stored in text files, in one of three locations:

  • Properties that affect VTScada in general are stored in Setup.INI, located in the VTScada installation folder. This file can be changed only by direct editing. Changes take effect only upon VTScada being restarted.
  • Properties that affect a specific application are stored in Setting.Startup and Settings.Dynamic, within the application folder. Properties from the [LAYER] section of Setup.INI can overridden by adding a copy to one of these files.
  • Properties that affect a specific workstation are stored in a sub-folder of the application named WorkstationSettings. These files are named after the workstation they affect, but also use the extensions .Startup and .Dynamic.


Section Names

Application properties are organized by section. If you change a property to use a section other than the one it was meant for, then that property will be ignored by VTScada. Note the shape of the brackets delimiting each section name.

  • [] Section names in square brackets will be shown in the Application Configuration dialog.
  • <> Section names in angled brackets are hidden from that dialog.

Properties in an hidden section may still be changed, but must be edited directly in the user copy of the Settings file and that file then imported into the application.

The following sections are defined application properties.

Section Name | Used in | Notes
<APPLICATION> Settings.Startup

Introduced in VTS version 10. The <APPLICATION> section includes information that in previous versions of VTScada was stored in the file GDI.WIF, as well as other application-specific properties such as AutoStart.

[Application] | Settings.Dynamic | Similar to <Application> in the .Startup file, but contains application-level properties that may change dynamically. Examples include AutoActivate, Name and VamIcon.
<ALARM_MANAGER> Settings.Startup

The <ALARM_MANAGER. section includes the properties that define the format of alarm records, and the default filter dialog format.

[Areas] Workstation.Startup

When added to one or more of an application's Workstation.Startup files, the [AREAS] section enables you to perform tag area filtering.

<LABELS> Settings.Startup & Settings.Dynamic

Application properties in the <LABELS> section exist only for backward compatibility. Changes to these properties are ignored. You are advised to use the Languages interface to change labels. (Languages)

<SecurityManager-Admin> | Settings.Dynamic | The hidden section, <SecurityManager-Admin>, contains properties set by the Administrative screen of the security manager. These include properties controlling the default AutoLogoff time and minimum password length.
<SecurityManager-PrivSys> | Settings.Dynamic | The hidden section, <SecurityManager-PrivSys>, sets the name used for each of the general privileges.
[StandardServerLists] | Settings.Dynamic | The [StandardServerLists] section defines server lists available to choose from when adding a new service in the Edit Server Lists panel.
[SYSTEM] | Settings.Dynamic & Settings.Startup | The [SYSTEM] section contains a list of variables that will determine the attributes of the application while it is running. Any values in the [SYSTEM] section are added or modified in the root system VTScada module. The [SYSTEM] section corresponds to the class 0 variables in AppRoot.src
[SystemAlarmAreas] | Settings.Startup | The [SystemAlarmAreas] section contains a list of predefined areas in use by VTScada. These are used when filtering the alarm history display to view only certain system such as "Security" and "OperatorLog". Using the area names from this list will cause no harm ("System" is commonly used for port, driver and other tags), but as a general guideline you may wish to avoid using the area names, "Security", "OperatorLog, " and "Report" for I/O tags.
[DefaultEquipmentTypes] Settings.Startup

Equipment type names that are available to new I/O and Calculation tags. This section will not exist in your Settings.Startup file until you create it.

Note that there is no need to add new types here since you can do so easily within any I/O tag in your application.

You might choose to add new types to your Settings.Startup file (or change the default type) if you are creating an OEM layer for distribution.

Each entry in this section must be a key to a phrase matching the type that you wish to create. It cannot be the actual name for the type.

To create an entry, start by creating a new phrase (word) in the Languages panel of your application.(Insert Phrases)

Ensure that you have set the view mode to include the Key column.

Copy the key for the new phrase.

Open your Settings.Startup file in a text editor.

Create a new section, [DefaultEquipmentTypes]

Below that section add the phrase identifier key, setting the value to 1.

[DefaultEquipmentTypes]
R8mwNb7 = 1

Only entries set to 1 are added to the dictionary of available types.

You may add as many equipment types as you like within the section.

Restart the application.

If there is no phrase for the key you enter (phrases are case-sensitive) an error message will be shown.

[ReferenceTypeDefaults] Settings.Startup

Configure an application to identify the default tag for any given *ReferenceType (or *ContextType).

By default, there are two default tags:

  • *Historian = SystemHistorian
  • *Style Settings = SystemStyle

To configure more default tags, you can:

  1. Open application folder.
  2. Open Settings.Startup file.
  3. Add a new section called [ReferenceTypeDefaults] to the end of the file.
  4. Add the default tags under that section: *ReferenceType = Tag full name/UniqueID.

Notes:

This mechanism works regardless of whether EnableSiblingTagAutoLinking is enabled.
This mechanism takes precedence over Sibling Tags Auto Linking for tags at the root level (even when Tag full name/UniqueID cannot be found).

For example:

For the above tag tree, if I have "*Driver = ContextTag2\Driver3" in my Settings.Startup file and EnableSiblingTagAutoLinking is enabled, then:

  • IO1 links to Driver3
  • IO2 links to Driver1
  • IO3 links to Driver2

If I have nothing in my Settings.Startup file and EnableSiblingTagAutoLinking is enabled, then:

  • IO1 links to Driver1
  • IO2 links to Driver1
  • IO3 links to Driver2

If I have "*Driver = WrongTagName/WrongUniqueID" in my Settings.Startup file and EnableSiblingTagAutoLinking is enabled, then:

  • IO1 links to no tag (Invalid)
  • IO2 links to Driver1
  • IO3 links to Driver2


Alarm Notification System Properties

Variables in this section relate to the VTScada Alarm Notification System.

Refer to the side menu for the listing of properties in this section.


AlarmAckCodeAgeLimit

Sets the maximum age of alarms that can be acknowledged by SMS text or email. Defaults to 12 hours (as measured in seconds).

Section: System

Default: AlarmAckCodeAgeLimit = 43200

*No restart required (Settings.Dynamic property)


AlarmAckCodeDigits

The set of characters to use when generating alarm acknowledgment codes for email and SMS messages. The acknowledgment code is not case sensitive. See also: AlarmAckCodeTemplate

Section: System

Default: AlarmAckCodeDigits = 2346789BCDFGHJKLMNPQRTVWXYZ

*No restart required (Settings.Dynamic property)


AlarmAckCodeTemplate

Sets the template for alarm acknowledgment codes, used when acknowledging alarms via email or SMS message. The template contains only asterisks and spaces, setting the number and pattern of characters that will make up the code.

At sites with extremely high numbers of daily alarms, it may be useful to increase the number of characters. See also: AlarmAckCodeDigits

Section: System

Default: AlarmAckCodeTemplate = *** ***

*No restart required (Settings.Dynamic property)


AlarmCheckMail

Used only if the application is configured to accept alarm acknowledgments by email. Sets the frequency at which VTScada will check the inbound email account when there are no unacknowledged alarms. Measured in seconds.

Section: System

Default: AlarmCheckMail = 600

*No restart required (Settings.Dynamic property)


AlarmCheckMailFastPoll

Used only if the application is configured to accept alarm acknowledgments by email. This sets the frequency with which VTScada will check in inbound email account when there are unacknowledged alarms. Measured in seconds.

Some email servers will disable an account that polls too rapidly, as a suspected spam source.

Section: System

Default: AlarmCheckMailFastPoll = 60

*No restart required (Settings.Dynamic property)


AlarmDialerStatusTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Template to be used for the status message of alarms spoken by the Alarm Notification System.

Section: System

Default: AlarmDialerStatusTemplate = Alarm status is %S.

Related information:

Alarm Message Templates - Look here for examples

AlarmDialerTemplate


AlarmDialerTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Provides a template to use for alarms delivered over the phone via the Alarm Notification System. May be a combination of words and replaceable parameter tokens as chosen from the table in Alarm Message Templates:

Section: System

Default: AlarmDialerTemplate = %T. %A %W %M.

Context (Site) Tags and Alarm Notification

Context tags (or custom types derived from a Context tag) may define custom alarm message templates, for use by all alarms occurring within the structure. This is done by adding the desired template name(s) to the Context's list of properties. To create a custom property value that will be dynamic and unique for each instance, use tokens. A token will be replaced by the meaning it represents. All non-token characters will be passed along as a string. (To pass a percent sign as part of a string you must type %%)

A custom template with a value of:

Check: %D%T - %A - %M

will output a message like:

"Check: [Date][Time] - [Area] - [Alarm description]"

You cannot pass an expression in the value field of a Context tag's custom property. To do this, you must create a custom tag type. See Alarm Notification Templates for more detailed instructions.

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmEmailTemplate

AlarmPagerTemplate

AlarmSpeechTemplate

Time and date formatting codes:

AlarmTemplateDateFmt

AlarmTemplateTimeFmt


AlarmEditEmailAck

Used only if the system is configured to allow alarm acknowledgment by email.

When set to 1, operators must add the letters "ACK*" before the alarm code when replying. By default, this is not required.

Useful to prevent alarm acknowledgment in response to an automatic "recipient is away" reply.

Section: System

Default: AlarmEditEmailAck = 0

*No restart required (Settings.Dynamic property)


AlarmEmailAckSubjectTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Template to be used for the subject line of alarm acknowledgment messages sent through email by the Alarm Notification System.

Section: System

Default: AlarmEmailAckSubjectTemplate = Acknowledged %A

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmEmailAckTemplate

AlarmEmailStatusTemplate

AlarmEmailSubjectTemplate

AlarmEmailTemplate


AlarmEmailAckTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Template to be used for the acknowledge message of alarms sent through email by the Alarm Notification System.

Section: System

Default: AlarmEmailAckTemplate = Acknowledged %N

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmEmailAckSubjectTemplate

AlarmEmailStatusTemplate

AlarmEmailSubjectTemplate

AlarmEmailTemplate


AlarmEmailStatusTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Template to be used for the status message of alarms sent through email by the Alarm Notification System.

Section: System

Default: AlarmEmailStatusTemplate = %NStatus: %S

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmEmailAckSubjectTemplate

AlarmEmailAckTemplate

AlarmEmailSubjectTemplate

AlarmEmailTemplate


AlarmEmailSubjectTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Holds the text that will be inserted into the subject line of alarm notifications sent by email.

Section: System

Default: AlarmEmailSubjectTemplate = The VTScada System: %A | %P Priority Alarm

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmEmailAckSubjectTemplate

AlarmEmailAckTemplate

AlarmEmailStatusTemplate

AlarmEmailSubjectTemplate

AlarmEmailTemplate


AlarmEmailTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Provides a template to use for alarms delivered to an email address via the Alarm Notification System. May be a combination of words and replaceable parameter tokens as chosen from the table in Alarm Message Templates:

Section: System

Default: AlarmEmailTemplate = %D %T%NArea: %A%NName: %F%NDesc: %M%N%L

Context (Site) Tags and Alarm Notification

Context tags (or custom types derived from a Context tag) may define custom alarm message templates, for use by all alarms occurring within the structure. This is done by adding the desired template name(s) to the Context's list of properties. To create a custom property value that will be dynamic and unique for each instance, use tokens. A token will be replaced by the meaning it represents. All non-token characters will be passed along as a string. (To pass a percent sign as part of a string you must type %%)

A custom template with a value of:

Check: %D%T - %A - %M

will output a message like:

"Check: [Date][Time] - [Area] - [Alarm description]"

You cannot pass an expression in the value field of a Context tag's custom property. To do this, you must create a custom tag type. See Alarm Notification Templates for more detailed instructions.

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmDialerTemplate

AlarmPagerTemplate

AlarmSpeechTemplate

Time and date formatting codes:

AlarmTemplateDateFmt

AlarmTemplateTimeFmt


AlarmNotifyEmailAcknowledge

Controls whether a confirmation email will be sent after an alarm is acknowledged by email.

Defaults to 1, meaning that a confirmation will be sent.

Section: System

Default: AlarmNotifyEmailAcknowledge = 1

*No restart required (Settings.Dynamic property)


AlarmNotifySMSAcknowledge

Controls whether an acknowledgment message is sent back to the operator after an alarm was successfully acknowledged via SMS text.

Section: System

Default: AlarmNotifySMSAcknowledge = 1

*No restart required (Settings.Dynamic property)


AlarmPagerStatusTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Template to be used for the status message of alarms sent to a pager by the Alarm Notification System.

Section: System

Default: AlarmPagerStatusTemplate = %S.

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmPagerTemplate


AlarmPagerTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Provides a template to use for alarms delivered to a pager via the Alarm Notification System. May be a combination of words and replaceable parameter tokens as chosen from the table in Alarm Message Templates:

Section: System

Default: AlarmPagerTemplate = %D %T. %A. %F. %M.

Context (Site) Tags and Alarm Notification

Context tags (or custom types derived from a Context tag) may define custom alarm message templates, for use by all alarms occurring within the structure. This is done by adding the desired template name(s) to the Context's list of properties. To create a custom property value that will be dynamic and unique for each instance, use tokens. A token will be replaced by the meaning it represents. All non-token characters will be passed along as a string. (To pass a percent sign as part of a string you must type %%)

A custom template with a value of:

Check: %D%T - %A - %M

will output a message like:

"Check: [Date][Time] - [Area] - [Alarm description]"

You cannot pass an expression in the value field of a Context tag's custom property. To do this, you must create a custom tag type. See Alarm Notification Templates for more detailed instructions.

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmPagerStatusTemplate

codes:

AlarmTemplateDateFmt

AlarmTemplateTimeFmt


AlarmPriorityIndicatorShowNormalUnacked

Controls the behavior of the Alarm Priority Icon and Alarm Priority Box when the unacknowledged linked alarm state is no longer in an active state.

This table assumes that an alarm occurs and then transitions to being either inactive or acknowledged.
Note that "trip" alarms are never in an active state.

Property value | Active | Acknowledged | Icon display
0 | Yes | No | Visible and blinking
0 | Yes | Yes | Visible but not blinking
0 | No | No | Invisible
0 | No | Yes | Invisible.
1 | Yes | No | Visible and blinking
1 | Yes | Yes | Visible but not blinking
1 | No | No | Visible and blinking
1 | No | Yes | Invisible.

Section: System

Default: AlarmPriorityIndicatorShowNormalUnacked =


AlarmSMSAckTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Template to be used for the acknowledge message of alarms sent to SMS text devices by the Alarm Notification System.

Section: System

Default: AlarmSMSAckTemplate = Acknowledged:%N%A%N%M

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmSMSStatusTemplate

AlarmSMSTemplate


AlarmSMSStatusTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Template to be used for the status message of alarms sent to SMS text devices by the Alarm Notification System.

Section: System

Default: AlarmSMSStatusTemplate= %N%S

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmSMSStatusTemplate

AlarmSMSTemplate


AlarmSMSTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Provides a template to use for both alarms delivered to an SMS text device via the Alarm Notification System and those delivered using the "compact" email setting in the roster. May be a combination of words and replaceable parameter tokens as chosen from the table in Alarm Message Templates:

Section: System

Default: AlarmSMSTemplate = %D %T%N%A%N%M%N%L

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmSMSTemplate

AlarmSMSStatusTemplate


LimitRosterToParentDB

May be used if legacy behavior is desired for Rosters that are children of custom AlarmDatabase tags.

A Roster that is a child of a custom AlarmDatabase will not report alarms that have a matching area but are in a different AlarmDatabase. This is desirable in most cases, but you have the option to change the behavior so that all will be searched. Note that if you have a large number of custom AlarmDatabases, searching all can cause a significant delay.

When LimitRosterToParentDB is 1 (default) a Roster that is a child of a custom AlarmDatabase will see only alarms in that database. If set to 0, the Roster will report alarms that have a matching area but exist in a different AlarmDatabase.

Section: System

Default: LimitRosterToParentDB = 1

*No restart required (Settings.Dynamic property)


AlphaNumericXFormScheme

Enables you to specify the password scheme to be obeyed by users of the VTScada Alarm Notification System.

  • If set to 0, passwords will be unmapped (i.e. only strictly numeric passwords will be accepted by the Alarm Notification System (e.g. 98443)).
  • If set to 1 (default), letters will be mapped to numbers as per ITU-T E.161 (i.e. the letters Q and Z map to the numbers 7 and 9 respectively).
  • If set to 2, letters will be mapped to numbers as per legacy scheme (i.e. the letters Q and Z map to the number 0).
  • If set to 3, both scheme 1 and scheme 2 above will be accepted (i.e. the letters Q and Z and the numbers 7 and 9 map to the number 0). Please note that this scheme is less secure!

By default, the call-out system has been configured to use alphanumeric passwords. If you change the mapping scheme from its default (i.e. if you change the value of AlphaNumericXFormScheme from 1 to 0, 2, or 3), user passwords will have to be re-entered into the system by telephone. See also: ForcePasswordAltIdSync.

Section: System

Default: AlphaNumericXFormScheme = 1

*No restart required (Settings.Dynamic property)


AnswerAlarmCalls

If set to 0, prevents the Alarm Notification System audio discriminator from being registered with the Modem Manager. This would be useful in an application where the Alarm Notification System is not being used for incoming voice calls, but other drivers are registered for incoming data calls. Up to 30 seconds of time can thereby be saved from each inbound call.

AnswerAlarmCalls should not be confused with the ModemManager setting, AnswerCalls. AnswerCalls determines whether the modem will answer at all. AnswerAlarmCalls determines whether the Alarm Notification System discriminator will be registered with the Modem Manager for use by an incoming call.

Section: System

Default: AnswerAlarmCalls = 1

*No restart required (Settings.Dynamic property)


CallManagerAlarmPriority

Viewing: Reference > Property Reference > Alarm Notification System Properties > CallManagerAlarmPriority

Reference:

CallManagerBadCallLimit

CallManagerShowCredentials

CallMgrMaxLogAge

CallMgrTraceInterval

CallMgrTraceMax

CallOutDelay1

CallOutDelay2

CallOutPriority

ModemCallPrefix

CallManagerAlarmPriority

Defines the Alarm Priority to use when notifying of a Call Manager voice configuration failure alarm.

Default is 1

Section: System

Default: CallManagerAlarmPriority = 1

*No restart required (Settings.Dynamic property)


CallManagerBadCallLimit

Viewing: Reference > Property Reference > Alarm Notification System Properties > CallManagerBadCallLimit

Reference:

CallManagerAlarmPriority

CallManagerShowCredentials

CallMgrMaxLogAge

CallMgrTraceInterval

CallMgrTraceMax

CallOutDelay1

CallOutDelay2

CallOutPriority

ModemCallPrefix

CallManagerBadCallLimit

Defines the number of bad calls in a row for any voice configuration before activating an alarm.

Section: System

Default: CallManagerBadCallLimit= 1

*No restart required (Settings.Dynamic property)


CallManagerShowCredentials

Viewing: Reference > Property Reference > Alarm Notification System Properties > CallManagerShowCredentials

Reference:

CallManagerAlarmPriority

CallManagerBadCallLimit

CallMgrMaxLogAge

CallMgrTraceInterval

CallMgrTraceMax

CallOutDelay1

CallOutDelay2

CallOutPriority

ModemCallPrefix

CallManagerShowCredentials

When set to 1, VTScada will include DTMF Closed Transport Layer Security key values in the logs.

Section: System

Default: CallManagerShowCredentials = 0

*No restart required (Settings.Dynamic property)


CallMgrMaxLogAge

Viewing: Reference > Property Reference > Alarm Notification System Properties > CallMgrMaxLogAge

Reference:

CallManagerAlarmPriority

CallManagerBadCallLimit

CallManagerShowCredentials

CallMgrTraceInterval

CallMgrTraceMax

CallOutDelay1

CallOutDelay2

CallOutPriority

ModemCallPrefix

CallMgrMaxLogAge

Defines the number of seconds before log files on the hard drive are deleted. Defaults to one week.

Section: System

Default: CallMgrMaxLogAge = 604800

*No restart required (Settings.Dynamic property)


CallMgrTraceInterval

Viewing: Reference > Property Reference > Alarm Notification System Properties > CallMgrTraceInterval

Reference:

CallManagerAlarmPriority

CallManagerBadCallLimit

CallManagerShowCredentials

CallMgrMaxLogAge

CallMgrTraceMax

CallOutDelay1

CallOutDelay2

CallOutPriority

ModemCallPrefix

CallMgrTraceInterval

Defines the number of seconds to wait before forcing the log out to the hard drive. Defaults to one day.

Section: System

Default: CallMgrTraceInterval = 86400

*No restart required (Settings.Dynamic property)


CallMgrTraceMax

Viewing: Reference > Property Reference > Alarm Notification System Properties > CallMgrTraceMax

Reference:

CallManagerAlarmPriority

CallManagerBadCallLimit

CallManagerShowCredentials

CallMgrMaxLogAge

CallMgrTraceInterval

CallOutDelay1

CallOutDelay2

CallOutPriority

ModemCallPrefix

CallMgrTraceMax

Defines the number of call manager log entries that will be held internally before writing the log out to the hard drive.

Section: System

Default: CallMgrTraceMax = 1000

*No restart required (Settings.Dynamic property)


CallOutDelay1

Viewing: Reference > Property Reference > Modem Manager Properties > CallOutDelay1

Reference:

CallManagerAlarmPriority

CallManagerBadCallLimit

CallManagerShowCredentials

CallMgrMaxLogAge

CallMgrTraceInterval

CallMgrTraceMax

CallOutDelay2

CallOutPriority

ModemCallPrefix

CallOutDelay1

Indicates the amount of time (in seconds) that you wish the system to wait before notifying designated operators of unacknowledged priority 1 (critical) alarms.

Please review the information on the CallOutPriority and MaxCallAlarmPriorityReported variables.

This property can be overridden within any Roster tag.

Section: System

Default: CallOutDelay1 = 120

*No restart required (Settings.Dynamic property)


CallOutDelay2

Viewing: Reference > Property Reference > Modem Manager Properties > CallOutDelay2

Reference:

CallManagerAlarmPriority

CallManagerBadCallLimit

CallManagerShowCredentials

CallMgrMaxLogAge

CallMgrTraceInterval

CallMgrTraceMax

CallOutDelay1

CallOutPriority

ModemCallPrefix

CallOutDelay2

Indicates the amount of time (in seconds) that you wish the system to wait before notifying designated operators of unacknowledged priority 2 (urgent) alarms.

Please review the information on the CallOutPriority and MaxCallAlarmPriorityReported variables.

This property can be overridden within any Roster tag.

Section: System

Default: CallOutDelay2 = 600

*No restart required (Settings.Dynamic property)


CallOutPriority

Viewing: Reference > Property Reference > Modem Manager Properties > CallOutPriority

Reference:

CallManagerAlarmPriority

CallManagerBadCallLimit

CallManagerShowCredentials

CallMgrMaxLogAge

CallMgrTraceInterval

CallMgrTraceMax

CallOutDelay1

CallOutDelay2

ModemCallPrefix

CallOutPriority

Controls whether the Alarm Notification System should contact operators when alarms have gone unacknowledged for a user-defined period of time. CallOutPriority variable selects the priority of alarms what will be sent by the VTScada Alarm Notification System.

If set to 0, the Alarm Notification System is disabled.

If set to 1, the Alarm Notification System will notify designated operators of only those alarms that have a priority of 1 (critical).

If set to 2, the Alarm Notification System will notify designated operators of only those alarms that have a priority of 1 (critical), or 2 (urgent).

Related property: MaxCallAlarmPriorityReported

Section: System

Default: CallOutPriority = 2

*No restart required (Settings.Dynamic property)


DialCancelOnAck

Controls whether alarms that have been acknowledged should be dialed out to operators.

  • If set to 0, then the VTScada call-out system will continue to dial out to designated operators even after the alarm has been acknowledged.
  • If set to 1 (default), then the VTScada call-out system will cancel call-outs to designated operators after the alarm has been acknowledged.

Section: System

Default: DialCancelOnAck = 1

*No restart required (Settings.Dynamic property)

Additional notes:

  • If DialCancelOnNormal is set and the alarm goes normal, records are removed from the notify list. Otherwise they are left on.
  • If DialCancelOnAck is set and the alarm is acknowledged, records are removed from the notify list.
  • If DialOnActive is set, and an alarm goes active, or becomes unacknowledged, it is added to the notify list.
  • If DialOnClear is set and the alarm goes normal, records are added to the notify list.
  • Active alarm records on the notify list are not resent to contacts who have already been notified once.
  • Normal alarm records on the notify list are only sent to contacts who have received an active notification.
  • After a single pass through the roster contact list, all records that are not on the Unacknowledged list (including any "Normal" records) are removed from the Notify list, unless the EnableRosterListRepeat setting is TRUE.
  • "Being notified" means that an email or SMS text message has been successfully sent to you, unless "Continue Roster Sequence" is checked. It does not guarantee that you have received it, because we have no control over the external network. For voice calls, if the contact logs in, a call is considered as having been notified.

When DialCancelOnAck is set to 0, the alarm notification will not stop after the alarm has been acked. When DialCancelOnNormal is set to 0, the alarm notification will not stop after the alarm has been cleared.
This means that if DialCancelOnNormal and DialCancelOnAck are both set to 0, the alarm notification will keep repeating indefinitely with no stop condition.


DialCancelOnNormal

Controls whether unacknowledged alarms, whose condition has become normal, should be dialed out to operators.

  • If set to 0, then the VTScada call-out system will continue to dial out to designated operators even after the condition that triggered an alarm has returned to normal.
  • If set to 1 (default), then the VTScada call-out system will cancel call-outs to designated operators after the condition that triggered the alarm has returned to normal.

Section: System

Default: DialCancelOnNormal = 1

*No restart required (Settings.Dynamic property)

Additional notes:

  • If DialCancelOnNormal is set and the alarm goes normal, records are removed from the notify list. Otherwise they are left on.
  • If DialCancelOnAck is set and the alarm is acknowledged, records are removed from the notify list.
  • If DialOnActive is set, and an alarm goes active, or becomes unacknowledged, it is added to the notify list.
  • If DialOnClear is set and the alarm goes normal, records are added to the notify list.
  • Active alarm records on the notify list are not resent to contacts who have already been notified once.
  • Normal alarm records on the notify list are only sent to contacts who have received an active notification.
  • After a single pass through the roster contact list, all records that are not on the Unacknowledged list (including any "Normal" records) are removed from the Notify list, unless the EnableRosterListRepeat setting is TRUE.
  • "Being notified" means that an email or SMS text message has been successfully sent to you, unless "Continue Roster Sequence" is checked. It does not guarantee that you have received it, because we have no control over the external network. For voice calls, if the contact logs in, a call is considered as having been notified.

When DialCancelOnAck is set to 0, the alarm notification will not stop after the alarm has been acked. When DialCancelOnNormal is set to 0, the alarm notification will not stop after the alarm has been cleared.
This means that if DialCancelOnNormal and DialCancelOnAck are both set to 0, the alarm notification will keep repeating indefinitely with no stop condition.


DialDTMFFeedback

Improve the accuracy of the user interface by providing an audible feedback indicating that the tone has been detected. When set 1 (true) all phone key presses are spoken back to the user.

This property works for VoIP and Voice Modems, but is not compatible with Twilio.

Section: System

Default: DialDTMFFeedback = 0

*No restart required (Settings.Dynamic property)


DialerAckIndividualAlarms

When set to 1, causes alarms to be spoken, then acknowledged (or ignored) one by one.

Section: System

Default: DialerAckIndividualAlarms = 0

*No restart required (Settings.Dynamic property)


DialerConnectDelay

The interval from when a call is initiated until speech starts.

Section: System

Default: DialerConnectDelay = 5

*No restart required (Settings.Dynamic property)


DialerLocation

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Sets the text to be spoken by the VTScada Alarm Notification System when contacting designated operators by phone. (This variable correlates to the Spoken Name in Phone Greeting field on the Alarm Notification Options dialog.)

Section: System

Default: DialerLocation = The VTScada System


DialerSpeechInit

This is the string to be used to initialize the text-to-speech device for audio calls.

Section: System

Default: DialerSpeechInit = \xPfl=60\


DialerVoice

Should be a voice as listed on the Windows Text to Speech dialog voice droplist. When set to the default "-", the voice used for the Alarm Notification System will be chosen from the Windows Text to Speech control panel.

Changes take effect on the next restart.

Section: System

Default: DialerVoice = -


DialInControl

Enables access to control actions through the Alarm Notification System's phone menu.

Set to 0 (false) to disable control options.

Section: System

Default: DialInControl = 1

*No restart required (Settings.Dynamic property)


DialOnActive

Controls whether active alarms should be dialed out to operators.

  • If set to 0, then the VTScada Alarm Notification System will not notify designated operators of active alarm conditions.
  • If set to 1 (default), then the VTScada Alarm Notification System will notify designated operators of active alarm conditions.

Section: System

Default: DialOnActive = 1

*No restart required (Settings.Dynamic property)

Additional notes:

  • If DialCancelOnNormal is set and the alarm goes normal, records are removed from the notify list. Otherwise they are left on.
  • If DialCancelOnAck is set and the alarm is acknowledged, records are removed from the notify list.
  • If DialOnActive is set, and an alarm goes active, or becomes unacknowledged, it is added to the notify list.
  • If DialOnClear is set and the alarm goes normal, records are added to the notify list.
  • Active alarm records on the notify list are not resent to contacts who have already been notified once.
  • Normal alarm records on the notify list are only sent to contacts who have received an active notification.
  • After a single pass through the roster contact list, all records that are not on the Unacknowledged list (including any "Normal" records) are removed from the Notify list, unless the EnableRosterListRepeat setting is TRUE.
  • "Being notified" means that an email or SMS text message has been successfully sent to you, unless "Continue Roster Sequence" is checked. It does not guarantee that you have received it, because we have no control over the external network. For voice calls, if the contact logs in, a call is considered as having been notified.

When DialCancelOnAck is set to 0, the alarm notification will not stop after the alarm has been acked. When DialCancelOnNormal is set to 0, the alarm notification will not stop after the alarm has been cleared.
This means that if DialCancelOnNormal and DialCancelOnAck are both set to 0, the alarm notification will keep repeating indefinitely with no stop condition.


DialOnClear

Controls whether acknowledged alarms, whose condition has returned to normal on site, should be dialed out to operators, notifying them when the alarm has been cleared.

  • If set to 0 (default), then the VTScada Alarm Notification System will not alert designated operators when an alarm has returned to normal.
  • If set to 1, then the VTScada Alarm Notification System will call out to designated operators when an alarm has returned to normal.

Section: System

Default: DialOnClear = 0

*No restart required (Settings.Dynamic property)

Additional notes:

  • If DialCancelOnNormal is set and the alarm goes normal, records are removed from the notify list. Otherwise they are left on.
  • If DialCancelOnAck is set and the alarm is acknowledged, records are removed from the notify list.
  • If DialOnActive is set, and an alarm goes active, or becomes unacknowledged, it is added to the notify list.
  • If DialOnClear is set and the alarm goes normal, records are added to the notify list.
  • Active alarm records on the notify list are not resent to contacts who have already been notified once.
  • Normal alarm records on the notify list are only sent to contacts who have received an active notification.
  • After a single pass through the roster contact list, all records that are not on the Unacknowledged list (including any "Normal" records) are removed from the Notify list, unless the EnableRosterListRepeat setting is TRUE.
  • "Being notified" means that an email or SMS text message has been successfully sent to you, unless "Continue Roster Sequence" is checked. It does not guarantee that you have received it, because we have no control over the external network. For voice calls, if the contact logs in, a call is considered as having been notified.

When DialCancelOnAck is set to 0, the alarm notification will not stop after the alarm has been acked. When DialCancelOnNormal is set to 0, the alarm notification will not stop after the alarm has been cleared.
This means that if DialCancelOnNormal and DialCancelOnAck are both set to 0, the alarm notification will keep repeating indefinitely with no stop condition.


DisableOutGoingCalls

If set to 1 (true) no alarm notification calls will be made. Defaults to 0 (false).

Section: System

Default: DisableOutGoingCalls = 0

*No restart required (Settings.Dynamic property)


EchoPhoneThroughSpeaker

Enables you to hear the Alarm Notification System’s calls through your PC speakers so that local operators can hear the Alarm Notification System annunciate alarms.

This setting is typically used for demonstration purposes and for debugging, as it can be assumed that a local operator would normally acknowledge an alarm before it is dialed out.

Section: System

Default: EchoPhoneThroughSpeaker = 0

*No restart required (Settings.Dynamic property)


EnableIOSyncOfRequestedValue

Will cause clients to retrieve the mismatch status of the IO tag from a server on application startup or servership changes.

Section: System

Default: EnableIOSyncOfRequestedValue =

*No restart required (Settings.Dynamic property)


EnableLexiconDialog

Selects whether the VTScada Lexicon should be enabled in the Alarms page of the Application Properties dialog.
Disable when using a 3rd party voice that provides its own lexicon configuration.

Section: System

Default: EnableLexiconDialog = 1

*No restart required (Settings.Dynamic property)


EnableRosterListRepeat

If 1 (true), a roster calling out alarms will repeat the roster list indefinitely if the last contact has the "Continue Roster Sequence" check box selected, or if it is a voice contact and no key press is detected on the call.
If 0 (false), all alarms in the roster's list are notified at the end of the contact list, so that the roster contact list is not repeated.

Section: System

Default: EnableRosterListRepeat = 1

*No restart required (Settings.Dynamic property)


EnableTwilio

Set 1 (true) if Twilio is to be enabled. Manage through the Application Properties dialog rather than directly so that related Twilio settings can be configured at the same time.

Section: System

Default: EnableTwilio = 0

*No restart required (Settings.Dynamic property)


EnableTwilioVoiceRecognition

Enable this property to allow users to acknowledge alarm call-outs over the phone by saying their alt ID out loud (as opposed to dialing).

Enabling voice recognition will change the terms of your service with Twilio and comes at a significant additional expense. Check with Twilio before proceeding.

Section: System

Default: EnableTwilioVoiceRecognition = 0

*No restart required (Settings.Dynamic property)


EnableVOIP

Set 1 (true) if VoIP (Voice over Internet Protocol) is to be enabled. Manage through the Application Properties dialog rather than directly so that related VoIP settings can be configured at the same time.

Section: System

Default: EnableVOIP = 0

*No restart required (Settings.Dynamic property)


GiveUpCallTimeout

Specifies how long the alarm dialer will wait for an available modem when making a voice call or pager call to a specific roster entry, before going on to the next roster entry. Defaults to 10 minutes. (600 seconds)

Because of this behavior, it is good practice to alternate media in the roster. For example, after a voice contact, have an email or SMS contact, so that if all modems are disabled, the alarm will still being sent out in a timely manner.

Section: System

Default: GiveUpCallTimeout = 600

*No restart required (Settings.Dynamic property)


HideMenuOnOutgoing

If set to 1 (true), then there is no return to the main menu of the Alarm Notification System for outgoing calls. After hearing the unacknowledged alarms, the operator has the choice of acknowledging the alarms (after which, the dialer will hang up), repeating the list or exiting.

If set to the default, 0, the third option is to return to the main menu and the fourth is to exit.

Section: System

Default: HideMenuOnOutgoing = 0

*No restart required (Settings.Dynamic property)


IncomingCallSection

Determines which section of the Alarm Notification System menu is first spoken when a call is made. By default, the main menu will be used.

Sections are determined by matching this property to the current value of the following properties:

  • MainMenuLabel
  • UnacknowledgedAlarmsLabel
  • ActiveAlarmsLabel
  • ControlLabel
  • StationStatusLabel

Section: System

Default: IncomingCallSection = Main Menu

*No restart required (Settings.Dynamic property)


MaxCallAlarmPriorityReported

Enables you to configure the Alarm Notification System to report alarms with priorities lower than 1 or 2 to operators after contact has been established. If not set (the default) then the CallOutPriority is used.

Does not change the priority of alarms that will cause an alarm notification. See:CallOutPriority

Section: System

Default: MaxCallAlarmPriorityReported = 2

*No restart required (Settings.Dynamic property)


MaxPagerBaudRate

The maximum number of bits per second to be transmitted to the pagers of designated operators by the Alarm Notification System.

Section: System

Default: MaxPagerBaudRate = 2400

*No restart required (Settings.Dynamic property)


MaxPagerMessage

Limits the number of characters that can be sent to a pager by the Alarm Notification System

Section: System

Default: MaxPagerMessage = 256

*No restart required (Settings.Dynamic property)


MenuRepeatMax

The number of times a voice menu will be repeated by the Alarm Notification System before it hangs up if the user makes no keypad input from the phone. For example, if MenuRepeatMax is set to 2, the menu will be heard three times (i.e. repeated twice).

Section: System

Default: MenuRepeatMax = 3

*No restart required (Settings.Dynamic property)


ModemCallPrefix

Viewing: Reference > Property Reference > Alarm Notification System Properties > ModemCallPrefix

Reference:

CallManagerAlarmPriority

CallManagerBadCallLimit

CallManagerShowCredentials

CallMgrMaxLogAge

CallMgrTraceInterval

CallMgrTraceMax

CallOutDelay1

CallOutDelay2

CallOutPriority

ModemCallPrefix

Provide a value for this property only if you need a prefix in front of numbers dialed via a modem. It is a best practice to first attempt to use the dialing rules configured in Windows (in the Phone and Modem settings) for prefixing numbers to a voice modem. Only use this setting as a next resort.

Do not configure as a workstation-specific setting. This must apply globally.

This setting is for numbers dialed via a modem, specifically. If you need to prefix a number for Twilio or VoIP, see Application Configuration > Edit Properties (Basic) > Alarms tab.

Section: System

Default: ModemCallPrefix =

*No restart required (Settings.Dynamic property)


NotificationErrorDelay

This setting exists only to handle a situation that is extremely rare. Do not change this value unless you have been advised to do so by Trihedral Technical Support.

If Continue Roster Sequence is set for all contacts in your Roster, and if all contact methods are email or SMS-ready emails, then if all notification attempts fail (as they might if the mail server starts rejecting messages as 421 errors), the roster can start skipping from contact to contact continuously with only a one second delay between contacts. This can be undesirable.

NotificationErrorDelay sets the time between notification attempts that follow the initial pass through the contact list.

You are advised not to set the delay higher than 5 to 10 seconds depending on your situation.

This property can be set on a roster-by-roster basis by adding it to a parent Context tag.

Section: System

Default: NotificationErrorDelay = 1


PINRetries

Indicates the number of times that a user may attempt to correctly enter their PIN number when responding to the Alarm Notification System.

Section: System

Default: PINRetries = 3

*No restart required (Settings.Dynamic property)


PINTimeOut

Indicates the amount of time (in seconds) after which an operator’s PIN number will time out if the system is idle while the operator is responding to the Alarm Notification System.

Section: System

Default: PINTimeOut = 30

*No restart required (Settings.Dynamic property)


RepeatMenuTime

Indicates the delay (in seconds) between repeats of the menus by the Alarm Notification System if the user makes no keypad input from the phone.

Section: System

Default: RepeatMenuTime = 5

*No restart required (Settings.Dynamic property)


RosterDelay

Sets the default value used when defining delay rules between roster contacts. Delays are set explicitly within the roster tag and do not depend on this property.

Those familiar with legacy versions of VTScada should note that this behavior changed with the release of version 12.1.

Section: System

Default: RosterDelay = 10

*No restart required (Settings.Dynamic property)


RosterFailureBackoffRate

After each failure to contact anyone on the roster, the delay before trying again is multiplied by this value, progressively increasing the time until the next attempt.

Section: System

Default: RosterFailureBackoffRate = 1.5

*No restart required (Settings.Dynamic property)

Related properties:

RosterFailureMinDelay

RosterFailureMaxDelay


RosterFailureMaxDelay

The maximum delay after experiencing a failure to connect with anyone on a roster before trying again. Measured in seconds.

Section: System

Default: RosterFailureMaxDelay = 3600

*No restart required (Settings.Dynamic property)

Related properties:

RosterFailureMinDelay

RosterFailureBackoffRate


RosterFailureMinDelay

Specifies the minimum delay after failing to connect with anyone on a roster before trying again. Measured in seconds.

Section: System

Default: RosterFailureMinDelay = 300

*No restart required (Settings.Dynamic property)

Related properties:

RosterFailureBackoffRate

RosterFailureMaxDelay


RosterListDelay

The number of seconds to wait before repeating the roster list. This property can be overridden within any Roster tag.

Section: System

Default: RosterListDelay = 5

*No restart required (Settings.Dynamic property)


SkipLogonDialout

When set to 1 (true), the challenge / response for calls that dial out to the user will be disabled. The user will not be able to return to the main menu.

Section: System

Default: SkipLogonDialout = 0

*No restart required (Settings.Dynamic property)

Related variables:

IncomingCallSection


SMTPPort

Deprecated. The SendMail function now includes an optional Port parameter. This property will be checked if the SendMail parameter is not specified.

Sets the SMTP port that the configured email server will use. The default value of 25 will work for most SMTP servers. If communicating with a server that uses or requires Transport Layer Security (TLS) such as Gmail, port 587 should be used. Other providers may use non-standard port numbers - consult your provider for details.

Section: System

Default: SMTPPort = 25

*No restart required (Settings.Dynamic property)


SpeechEngine

For systems that include the Alarm Notification System option. Selects the voice engine to use. By default, this will be "-", indicating that the Microsoft SAPI engine should be used.

Customers who have the IVONA® Voice engine from an earlier version of VTScada may continue to use it by ensuring that this property is set to "IVONA".

Section: System

Default: SpeechEngine = IVONA

*No restart required (Settings.Dynamic property)


TwilioMaxLogAge

Twilio log files are circular, meaning that older records are removed to clear room for newer entries.

This property sets the maximum age of entries in the log, defaulting to one week, measured in seconds.

Default: TwilioMaxLogAge = 604800

Section: System

Related properties:

TwilioShowCredentials

TwilioTraceInterval

TwilioTraceMax


TwilioPickupDelay

Sets the interval in seconds from when a Twilio call is initiated until speech starts.

Section: System

Default: TwilioPickupDelay = 5

*No restart required (Settings.Dynamic property)


TwilioShowCredentials

For security purposes, keypresses are masked in the Twilio logs. When this property is set to 1, keypresses are not masked.

Set to 1 only while debugging. It is a security risk to leave this property set.

Default: TwilioShowCredentials = 0

Section: System

Related properties:

TwilioMaxLogAge

TwilioTraceInterval

TwilioTraceMax


TwilioTraceInterval

Save the Twilio trace files at this interval. Defaults to once per day, measured in seconds.

Default: TwilioTraceInterval = 86400

Section: System

Related properties:

TwilioMaxLogAge

TwilioShowCredentials

TwilioTraceMax


TwilioTraceMax

Save the Twilio trace files when this many entries have been recorded. Defaults to 1000.

Default: TwilioTraceMax = 1000

Section: System

Related properties:

TwilioMaxLogAge

TwilioShowCredentials

TwilioTraceInterval


UseLegacyEventPriorityAlarmBehavior

Alarms that you configure with priority 0 (Event) are treated as standard alarms by default. Due to the priority level being 0, they do not signal their state visually or audibly, but each activation and normalization transaction (or trip) will be recorded in the Alarm History.

Use this property to switch to a behavior that was once standard, where priority 0 (Event) alarms were recorded as Event transactions when activated or tripped, but never when conditions normalized.

Section: System

Default: UseLegacyEventPriorityAlarmBehavior = 0

*No restart required (Settings.Dynamic property)

Compare the following snippets from the Alarm page. The configured alarm is the same in both cases; a level-0 (Event) alarm(*) triggered when the I/O tag's value become 1 (running).

Standard behavior. The non-annunciating alarm activates when the operator starts the pump and normalizes when the pump stops sometime later due to an automated process.

Legacy behavior: The event is recorded when the pump changes to its running state.

(*) This is a contrived example. Changes in I/O tag value are logged by default. Adding an event-priority alarm for the sake of record-keeping is redundant and therefore wasteful of resources.


UseSMTPOverTLS

As of VTS 10.1, this property is no longer stored in Settings.Dynamic. Use the Email Options dialog to change its value rather than the Applications Properties dialog.

Controls whether Transport Layer Security (aka SSL) is to be used for communications with your SMTP email server. The following options are available:

UseSMTPOverTLS

Meaning

0

Use plain text mode only. No email will be sent if the server requires TLS.

Non-Zero

Use TLS only. If the server does not support TLS, or if the attempt to use TLS fails, the email will not be sent.

Invalid (default)

If TLS is available on the email server and a connection can be made, TLS mode will be used. Otherwise, the connection will be closed and VTScada will request a plain text connection.

If the email server required TLS mode, but a connection could not be made, the plain text connection will fail.

Section: System

Default: UseSMTPOverTLS =


VOIPCertName

The name of the security certificate for use with SIPS (encrypted call setup and media) when acting as a server.

This will not normally be the case, therefore you should not normally require a certificate name.

Section: System

Default: VOIPCertName =

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Related Properties:

VOIPEnableTLS

VOIPTLSPort


VOIPEnableTLS

Enables use of SIPS (encrypted call setup and media) for VOIP calls. Defaults to ON

Section: System

Default: VOIPEnableTLS = 1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Related Properties:

VOIPTLSPort

VOIPCertName


VOIPMediaPort

The starting/lowest port number to use for the RTP media streams. (ex: port 40000). Can be specified as any port. If not set, by default it will use the ephemeral port range.

VOIP media port settings above are useful when locking down a system to ensure VOIP voice plays over the open port range.

Section: VTScada Library

Default: VOIPMediaPort =

Related Properties:

VOIPMediaPortRange


VOIPMediaPortRange

The size of the range of VOIPMediaPorts which may be used. This begins with and includes VOIPMediaPort. (ex: 100 to allow 100 possible VOIPMediaPorts).

VOIP media port settings above are useful when locking down a system to ensure VOIP voice plays over the open port range.

Section: System

Default: VOIPMediaPortRange =

*No restart required

Related Properties:

VOIPMediaPort


VOIPPickUpDelay

Sets the interval in seconds from when a VoIP call is initiated until speech starts.

Section: System

Default: VOIPPickUpDelay = 10

*No restart required (Settings.Dynamic property)


VOIPPublicAddress

IPv4 address to advertise as the address of the RTP media stream. This is useful in instances where a computer has multiple network interface cards (NICs). VOIPPublicAddress should only be set for machines with multiple NICs where voice does not play when calling out.

Section: System

Default: VOIPPublicAddress =

*No Restart Required


VOIPRegisterTimeout

This defines the preferred registration interval in seconds when connecting to a VoIP provider. Defaults to 300 seconds if unspecified.

Section: System

Default: VOIPRegisterTimeout = 300

*No restart required (Settings.Dynamic property)


VOIPTLSPort

Sets the port to use for SIPS calls. Defaults to 5061

Section: System

Default: VOIPTLSPort = 5061

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Related Properties:

VOIPEnableTLS

VOIPCertName


Alarm Properties

Variables in this section relate to alarms.

Refer to the side menu for the listing of properties in this section.


AckAllAcksOnlyVisible

By default, the Acknowledge All tool in the Alarm Page and Alarm List will acknowledge all alarms that pass the filter currently in effect, including those on the next page of a scrolling display.

When set to 1 (TRUE), only those alarms that are visible in the list will be acknowledged.

Section: System

Default: AckAllAcksOnlyVisible = 0

*No restart required (Settings.Dynamic property)


AckAllEnable

If set to 1 (true), operators will be able to acknowledge all the alarms shown in the list.

Section: System

Default: AckAllEnable = 1


AckAllRequiresConfirmation

If set to 1 (true), operators must click through a confirmation dialog when attempting to acknowledge all the alarms shown in the list.

Section: System

Default: AckAllRequiresConfirmation = 1

*No restart required (Settings.Dynamic property)


ActiveFlashRate

Viewing: Reference > Property Reference > Alarm Properties > ActiveFlashRate

ActiveAlarmFlash

Applies to level alarms, not to trip alarms.

If set to 1, active low setpoint or high setpoint alarms will be signaled by a flashing indicator on the related station symbol and on the tag's Draw Widget on the related station page.

Section: System

Default: ActiveAlarmFlash = 0

*No restart required (Settings.Dynamic property)

Related property: ActiveFlashRate


ActiveCommColor

The color displayed for site symbols, input tags, and in a sites page legend when signaling active communications. The default color is 0 (black).

Section: System

Default: ActiveCommColor = 0

*Restart Required (Settings.Startup property)

Related properties: InactiveCommColor


ActiveFlashRate

Relevant only when ActiveAlarmFlash is set to 1.

Controls the rate at which active alarms should flash on station symbols and station pages. Measured in seconds or fractions of a second.

Section: System

Default: ActiveFlashRate = 2

*No restart required (Settings.Dynamic property)


AlarmAutoNavEnable

If set to 1, automatic alarm page navigation is enabled. New alarms will cause the application to open a page showing the alarm tag or triggering tag, subject to the following conditions:

  • If the alarm tag, tag with a built-in alarm, or tag that triggered the alarm is not visible on any page, then the alarm page will be selected.
  • If more than one page could be selected, VTScada will make a best-choice.

Automatic navigation will occur after a delay, and only if there has been no operator activity during that delay.

Section: System

Default: AlarmAutoNavEnable = 0

*No restart required (Settings.Dynamic property)

Related information:

AlarmAutoNavEnable

AlarmAutoNavTimeout

AlarmAutoNavWindowed


AlarmAutoNavHold

Sets the number of seconds that one page, automatically opened in response to an alarm, will remain visible before another page will be opened by the automatic navigation feature.

This property has no effect on operator navigation.

Section: System

Default: AlarmAutoNavHold = 10

*No restart required (Settings.Dynamic property)

Related information:

AlarmAutoNavEnable

AlarmAutoNavTimeout

AlarmAutoNavWindowed


AlarmAutoNavTimeout

Auto-navigation will only occur if there has been no operator activity for the given number of seconds prior to the triggering of the alarm. Operator activity is defined as any mouse motion or keyboard input.

Section: System

Default: AlarmAutoNavTimeout = 300

*No restart required (Settings.Dynamic property)

Related information:

AlarmAutoNavEnable

AlarmAutoNavTimeout

AlarmAutoNavWindowed


AlarmAutoNavWindowed

Associated with the property, AlarmAutoNavEnable. The page that is automatically opened in response to an alarm will be opened as a window, if possible.

If the page has been configured as Never Open in a Window, it won't.

If the maximum number of pop-up windows is already open (PopupPageLimit) and more pop-ups are prohibited by PopupLimitAction, then the standard error message will occur upon automatic navigation attempting to open a new pop-up page.

Section: System

Default: AlarmAutoNavWindowed = 0

*No restart required (Settings.Dynamic property)

Related information:

AlarmAutoNavEnable

AlarmAutoNavWindowed

AlarmAutoNavTimeout


AlarmColor

Designates the color to be flashed to indicate an alarm (e.g. in the Display Manager's title bar). The default color is red (12).

Has no effect on widgets that indicate alarm conditions.

Section: System

Default: AlarmColor = 12

*No restart required (Settings.Dynamic property)


Alarm Database Groups

(Property name: AlarmDatabaseGroups)

For the majority of applications, there is no need to create extra alarm databases, but locations that maintain large distributed systems might choose to do so. For those that do, it is possible to create display groups so that alarms from several, but not all, databases can be viewed at the same time.

Database groups are defined as an application property, AlarmDatabaseGroups. Multiple groups can be defined within the single property, each with a list of databases. Separate the groups with semi-colons and database names within each group by commas.

[System]
  AlarmDatabaseGroups       = Northeast Group:NorEast,NorWest;Southwest Group:SouWest,SouEast

Here is one example of an alarm database group:

Example: Using an alarm database group

The property definition used for this example:

The entries in AlarmDatabaseGroups refer to the tag names. It is a coincidence that, in the provided example, the descriptions that appear in the screen shot happen to match the tag names.

Section: [System]

Default: AlarmDatabaseGroups =

*No restart required (Settings.Dynamic property)


AlarmDatabasePurgeDelay

It is possible to create orphaned alarms, especially if the tag database is modified outside VTScada. These are purged automatically upon startup, following a delay in seconds specified by this property.

Section: System

Default: AlarmDatabasePurgeDelay = 120

*No restart required (Settings.Dynamic property)

Related information:

Orphaned Alarms


AlarmDatabasePurgeEnable

Set to 1 (true) to allow automatic purging of duplicate and orphaned alarm records from alarm databases.

Section: System

Default: AlarmDatabasePurgeEnable = 1

*No restart required (Settings.Dynamic property)


AlarmDatabasePurgeRate

Number of seconds to wait between each alarm record check. Throttles the purge mechanism.

Section: System

Default: AlarmDatabasePurgeRate = 0.01

*No restart required (Settings.Dynamic property)


AlarmDisplayDateFormat

Controls the format in which dates should be displayed on the Alarm page and in Alarm Lists.

The value may use any of: date formatting codes, date formatting strings or phrase identifier keys within the default languages file.

DateFmtFullNumeric is a phrase key that evaluates to yyyy-MM-dd.

See also: Date Formatting Codes | Date Formatting Strings | Date and Time Phrase Keys

Section: System

Default: AlarmDisplayDateFormat = DateFmtFullNumeric

*No restart required (Settings.Dynamic property)


AlarmDisplayTimeFormat

Controls the format in which times should be displayed on the Alarm page and in Alarm Lists.
The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file.

TimeFmtHMS24Hour is a phrase key that evaluates to HH:mm:ss

See also: Time Formatting Codes | Time Formatting Strings | Date and Time Phrase Keys

Section: System

Default: AlarmDisplayTimeFormat = TimeFmtHMS24Hour

*No restart required (Settings.Dynamic property)


AlarmEventDescX

Viewing: Reference > Property Reference > Alarm Properties > AlarmEventDescX

AlarmEventDesc0 - AlarmEventDesc21

With the introduction of support for multiple languages, these properties have moved to phrases as follows:

AlarmEventDesc0 => DisableLabel

AlarmEventDesc1 => EnableLabel

AlarmEventDesc2 => ActiveLabel

AlarmEventDesc3 => TripLabel

AlarmEventDesc4 => EventLabel

AlarmEventDesc5 => NormalLabel

AlarmEventDesc6 => OffNormalLabel

AlarmEventDesc7 => NormalTripLabel

AlarmEventDesc8 => AcknowledgeLabel

AlarmEventDesc9 => UnknownLabel

AlarmEventDesc10 => NormalAckLabel

AlarmEventDesc11 => ActiveAckLabel

AlarmEventDesc12 => ShelveLabel

AlarmEventDesc13 => UnShelveLabel

AlarmEventDesc14 => NotifyLabel

AlarmEventDesc15 => DecommissionLabel

AlarmEventDesc16 => RecommissionLabel

AlarmEventDesc17 => CommissionLabel

AlarmEventDesc18 => ReconcileLabel

AlarmEventDesc19 => ModifyLabel

AlarmEventDesc20 => RearmLabel

AlarmEventDesc21 => PurgeLabel

Sets the description to display in the Event column of the History list for custom alarm states.

Section: System

Legacy Defaults: (See following list)

AlarmEventDesc0 = Disable

AlarmEventDesc1 = Enable

AlarmEventDesc2 = Active

AlarmEventDesc3 = Trip

AlarmEventDesc4 = Event

AlarmEventDesc5 = Normal

AlarmEventDesc6 = Off Normal

AlarmEventDesc7 = Normal Trip

AlarmEventDesc8 = Acknowledge

AlarmEventDesc9 = Unknown

AlarmEventDesc10 = Normal Ack

AlarmEventDesc11 = Active Ack

AlarmEventDesc12 = Shelve

AlarmEventDesc13 = Unshelve

AlarmEventDesc14 = Notify

AlarmEventDesc15 = Decommission

AlarmEventDesc16 = Recommission

AlarmEventDesc17 = Commission

AlarmEventDesc18 = Rename

AlarmEventDesc19 = Modify

AlarmEventDesc20 = Rearm

AlarmEventDesc21 = Purge

Related information:

AlarmStatusDesc0 - AlarmStatusDesc5


AlarmFlashTaskBar

If set to 1 (true), the entire task bar will flash red while there are unacknowledged alarms that are visible to the logged-on user.

When set to 0 (false) only the alarm indicator blinks.

Section: System

Default: AlarmFlashTaskBar = 0

*No restart required (Settings.Dynamic property)

Related information:

AlarmFlashTaskBarOnVIC


AlarmFlashTaskBarOnVIC

If set to 1 (true), the entire task bar will flash red on VTScada Internet Clients while there are unacknowledged alarms that are visible to the logged-on user.

This feature will consume extra bandwidth when enabled. Use with caution.

Section: System

Default: AlarmFlashTaskBarOnVIC = 0

*No restart required (Settings.Dynamic property)

Related information:

AlarmFlashTaskBar


AlarmFlashTime

Sets the time (in seconds) between flashes of active alarm indicators. (For example, in the Display Manager's title bar).

Does not affect widgets that display alarm conditions.

Section: System

Default: AlarmFlashTime = 0.5

*No restart required (Settings.Dynamic property)

Related Variables: AlarmColor | AlarmFlashTitleBar


AlarmFlashTitleBar

If set to 1 (true), the entire title bar will flash red while there are unacknowledged alarms that are visible to the logged-on user.

When set to 0 (false) only the alarm indicator blinks.

Section: System

Default: AlarmFlashTitleBar = 0

*No restart required (Settings.Dynamic property)

Related information:

AlarmFlashTitleBarOnVIC


AlarmFlashTitleBarOnVIC

If set to 1 (true), the entire title bar will flash red on VTScada Internet Clients while there are unacknowledged alarms that are visible to the logged-on user.

This feature will consume extra bandwidth when enabled. Use with caution.

Section: System

Default: AlarmFlashTitleBarOnVIC = 0

*No restart required (Settings.Dynamic property)

Related information:

AlarmFlashTitleBar

AlarmIndDisableOnVIC

AlarmIndDisable


AlarmIndDisable

Set to 1 (true) to disable the flashing alarm indicator in the Display Manager's title bar.

Use extreme caution in using the AlarmIndDisable variable, as operators will not have a general visual notification of incoming alarms in the system.

Section: System

Default: AlarmIndDisable = 0

*No restart required (Settings.Dynamic property)

Related information:

AlarmIndDisableOnVIC


AlarmIndDisableOnVIC

If set to 1 (true), then the unacknowledged alarms indicator will be disabled on VTScada internet clients. Set to 0 (false) to enable the indicator.

This feature will consume extra bandwidth when enabled. Use with caution.

Section: System

Default: AlarmIndDisableOnVIC = 1

*No restart required (Settings.Dynamic property)

Related information:

AlarmFlashTitleBarOnVIC


AlarmListBGColor

Designates the background color to be used in Site Page alarm lists. Does not affect the main Alarm Page.

Section: System

Default: AlarmListBGColor = <282828>

*No restart required (Settings.Dynamic property)


AlarmListDefaultColumnFormat

If you have created a custom alarm list, use this property to specify that your list should be shown when All Databases is selected. Does not override the default list that will be shown when viewing a specific alarm database.

Section: System

Default: AlarmListDefaultColumnFormat = AlarmStandard

*No restart required (Settings.Dynamic property)

Related information:

Customize Columns in Alarm Displays


AlarmListDefaultSortDir

Can be added to your application properties to define whether alarm lists should be sorted in ascending (0) or descending (1) order by default.

If set, then the user-defined sort order will be retained only while the page or list remains open. If the operator navigates away from the page, then the sort order defined by this property will be used upon return.

Does not apply to the History list.

Section: System

Default: AlarmListDefaultSortDir =

*No restart required (Settings.Dynamic property)

Related information:

AlarmListDefaultSortKey


AlarmListDefaultSortKey

Can be added to your application properties to set default sorting for the alarm list in both the Alarm Page and in custom Alarm Lists.

If set, then user-defined sorting will be retained only while the page or list remains open. If the operator navigates away from the page, then the sort order defined by this property will be used upon return.

The key must be one of the fields of an Alarm Record Structure structure.

Does not apply to the History list.

Section: System

Default: AlarmListDefaultSortKey =

*No restart required (Settings.Dynamic property)

Related information:

AlarmListDefaultSortDir


AlarmListUsePriorityTextColor

If set to 1, alarm text in the Alarm Page and in Alarm Lists will use the color of the matching priority.

Default: AlarmListUsePriorityTextColor = 0

Section: System

*No restart required (Settings.Dynamic property)


AlarmPageBackgroundColor

Sets the background color for the alarm page. If not set, the color will be white or black depending on the operator's choice of daytime or nighttime mode.

Section: System

Default: AlarmPageBackgroundColor =

*No restart required (Settings.Dynamic property)


AlarmPageHistoryRecordHardLimit

The maximum number of records that will be shown in any alarm list is limited by the related property, AlarmPageHistoryRecordLimit.

If there are more records than that value in the selected time frame, a Load More button will be available at the bottom of the list. Load More will allow you to view successive sets of records (always limited to AlarmPageHistoryRecordLimit at a time), up to the maximum number as controlled by AlarmPageHistoryRecordHardLimit which defaults to 100,000.

Section: System

Default: AlarmPageHistoryRecordHardLimit = 100000

Related information:

AlarmPageHistoryRecordLimit


AlarmPageHistoryRecordLimit

Limits the maximum number of records that will be shown in any alarm list. If there are more records than this in the selected time frame, a Load More button will be available at the bottom of the list. Load more will allow you to view successive sets of records (always limited to AlarmPageHistoryRecordLimit at a time), up to the maximum number as controlled by AlarmPageHistoryRecordHardLimit.

Section: System

Default: AlarmPageHistoryRecordLimit = 1000

*No restart required (Settings.Dynamic property)

Related information:

AlarmPageHistoryRecordHardLimit


AlarmPageTextColor

Sets the color for text on the alarm page. If not set, the color will be white or black depending on the operator's choice of nighttime or daytime mode.

Section: System

Default: AlarmPageTextColor =

*No restart required (Settings.Dynamic property)


AlarmPopupsEnable

Toggle to control whether alarm pop-up dialogs (if any) are enabled. Disabled by default.

Section: System

Default: AlarmPopupsEnable = 0

*No restart required (Settings.Dynamic property)


AlarmPrintTimeFormat

The format to use when displaying the time in the alarm message. The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file. (Time Formatting Codes, Time Formatting Strings, Date and Time Phrase Keys)

TimeFmtHMS24Hour is a phrase key that evaluates to HH:mm:ss.

Section: System

Default: AlarmPrintTimeFormat = TimeFmtHMS24Hour

*No restart required (Settings.Dynamic property)


AlarmPrintPort

Used when printing an alarm page. Identifies the port to which the printer is connected. By default, AlarmPrinterPort is set to the default printer as defined in Windows.

Section: System

Default: AlarmPrintPort = DEF:

*No restart required (Settings.Dynamic property)


AlarmPriorityDescWidth

Indicates the maximum number of characters in the alarm priority descriptions when the alarm list is printed.

Related Variables: The AlarmPriorityDescWidth variable enables you to set the maximum number of characters in the alarm priority descriptions when the alarm list is printed. The AlarmStatusDescWidth variable enables you to set the maximum number of characters in the alarm status descriptions when the alarm list is printed.

Section: System

Default: AlarmPriorityDescWidth = 15

*Restart Required (Settings.Startup property)


AlarmPriorityIndicatorColor

Sets the color of the Alarm Priority Icon widget and Alarm Priority Box widget when displaying an alarm that is shelved, disabled, or being edited in the Idea Studio. All three states always use the same color, which defaults to a pale gray.

Section: System

Default: AlarmPriorityIndicatorColor = "<FFEAEAEA>"


AlarmRecommissionAgeLimit

When a tag is compiled, all instances are stopped and their alarms are decommissioned. The tags are then restarted, which commissions the alarms, after which they will eventually reactivate when a valid Value is obtained.

Rather than detecting a new name and therefore commissioning a new alarm, VTScada will check how long it has been since the alarm was decommissioned. If it has been less than 15 minutes as configured with this property, the alarm is restored to the state it had before the decommission (known as a "Recommission") - this will prevent it from reactivating. Otherwise, it will be commissioned as a new alarm.

Section: System

Default: AlarmRecommissionAgeLimit = 900


AlarmRPCEnable

Indicates whether remote procedure calls for alarms are enabled or disabled for this application.

If set to 0 (false), remote procedure calls are disabled for this application.

If set to 1 (true), remote procedure calls are enabled for this application (default)

Section: System

Default: AlarmRPCEnable = 1

*Restart Required (Settings.Startup property)


AlarmSeparatorString

Separates the name of a custom alarm's parent tag from its index in the parent's array of alarms. The default setting for AlarmSeparatorString is a colon, followed by a number hatch, followed by a colon.

Section: System

Default: AlarmSeparatorString = :#:

*Restart Required (Settings.Startup property)


AlarmSnapshotCount

Maximum number of alarm events until the alarm database saves snapshots of the alarm state.

Section: System

Default: AlarmSnapshotCount = 10000

Defaults to AlarmSnapshotInterval or every AlarmSnapshotCount records, whichever is sooner.

*No restart required (Settings.Dynamic property)


AlarmSnapshotInterval

Maximum time in seconds to wait until the alarm database saves snapshots of the alarm state.

Section: System

Default: AlarmSnapshotInterval = 604800
(seven days)

Defaults to AlarmSnapshotInterval or every AlarmSnapshotCount records, whichever is sooner.

*No restart required (Settings.Dynamic property)

Related properties:

AlarmSnapshotMinInterval


AlarmSnapshotMinInterval

Minimum time to wait until alarm database saves snapshots of the alarm state. Defaults to 1 hour (3600 s).

Section: System

Default: AlarmSnapshotMinInterval = 3600

*No restart required (Settings.Dynamic property)

Related properties:

AlarmSnapshotInterval


AlarmSoundDisable

When set to 1 (true), will completely disable alarm sounds. This can potentially improve performance in systems with a large number of alarms and a large number of operator connections.

Section: System

Default: AlarmSoundDisable = 0

*No restart required (Settings.Dynamic property)


AlarmSpeechEnable

Controls whether the text-to-speech alarm feature will be used. Spoken alarms are disabled by default.

Section: System

Default: AlarmSpeechEnable = 0

*No restart required (Settings.Dynamic property)

After setting this value to 1 (true), you must also enable and configure alarm speech within individual Alarm Priority tags.


AlarmSpeechInit

This variable provides an initialization string to the speech engine to control the voice. It can be any XML string accepted by the voice engine. Please refer to the documentation for your configured voice engine for the details of this initialization string. The default value sets voice pitch, volume and speed for the Microsoft SAPI engine.

Section: System

Default: AlarmSpeechInit = <PITCH ABSMIDDLE="-2"/><VOLUME LEVEL="100"/><RATE ABSSPEED="-1"/>

*No restart required (Settings.Dynamic property)


AlarmSpeechQuality

Determines the audio quality, and therefore the data transfer required, for speech. The number used for this variable directly corresponds to the SAPI SPStreamFormat enumeration. When set to the default of 6, the quality that is native to the voice engine will be used.

Section: System

Default: AlarmSpeechQuality = 6

*No restart required (Settings.Dynamic property)

Value | Meaning | Value | Meaning
4 | SAFT8kHz8BitMono | 5 | SAFT8kHz8BitStereo
6 | SAFT8kHz16BitMono | 7 | SAFT8kHz16BitStereo
8 | SAFT11kHz8BitMono | 9 | SAFT11kHz8BitStereo
10 | SAFT11kHz16BitMono | 11 | SAFT11kHz16BitStereo
12 | SAFT12kHz8BitMono | 13 | SAFT12kHz8BitStereo
14 | SAFT12kHz16BitMono | 15 | SAFT12kHz16BitStereo
16 | SAFT16kHz8BitMono | 17 | SAFT16kHz8BitStereo
18 | SAFT16kHz16BitMono | 19 | SAFT16kHz16BitStereo
20 | SAFT22kHz8BitMono | 21 | SAFT22kHz8BitStereo
22 | SAFT22kHz16BitMono | 23 | SAFT22kHz16BitStereo
24 | SAFT24kHz8BitMono | 25 | SAFT24kHz8BitStereo
26 | SAFT24kHz16BitMono | 27 | SAFT24kHz16BitStereo
28 | SAFT32kHz8BitMono | 29 | SAFT32kHz8BitStereo
30 | SAFT32kHz16BitMono | 31 | SAFT32kHz16BitStereo
32 | SAFT44kHz8BitMono | 33 | SAFT44kHz8BitStereo
34 | SAFT44kHz16BitMono | 35 | SAFT44kHz16BitStereo
36 | SAFT48kHz8BitMono | 37 | SAFT48kHz8BitStereo
38 | SAFT48kHz16BitMono | 39 | SAFT48kHz16BitStereo


AlarmSpeechTemplate

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

Provides a template for spoken alarms to use. May be a combination of words and replaceable parameter tokens as chosen from the table in Alarm Message Templates:

Section: System

Default: AlarmSpeechTemplate = %A %W %M

Context (Site) Tags and Alarm Notification

Context tags (or custom types derived from a Context tag) may define custom alarm message templates, for use by all alarms occurring within the structure. This is done by adding the desired template name(s) to the Context's list of properties. To create a custom property value that will be dynamic and unique for each instance, use tokens. A token will be replaced by the meaning it represents. All non-token characters will be passed along as a string. (To pass a percent sign as part of a string you must type %%)

A custom template with a value of:

Check: %D%T - %A - %M

will output a message like:

"Check: [Date][Time] - [Area] - [Alarm description]"

You cannot pass an expression in the value field of a Context tag's custom property. To do this, you must create a custom tag type. See Alarm Notification Templates for more detailed instructions.

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Related information:

Alarm Message Templates - Look here for examples

AlarmDialerTemplate

AlarmEmailTemplate

AlarmPagerTemplate

Time and date formatting codes:

AlarmTemplateDateFmt

AlarmTemplateTimeFmt


AlarmSpeechVoice

Sets which voice in the Microsoft-integrated speech engine is used to speak the alarm. In general, it is best to select the voice using the Microsoft Speech Tools configuration box and set this variable to a dash (-) to indicate "configured Windows voice". If selecting a particular voice, the string must exactly match the desired voice name.

This property is relevant only when SpeechEngine is set to SAPI.

Section: System

Default: AlarmSpeechVoice = -

*No restart required (Settings.Dynamic property)


AlarmStatRange0 - AlarmStatRange3

The four AlarmStatRangeN properties control the time period for each of the four statistics in the Alarm Details dialog.

Each set of properties should be stored in the [SYSTEM] section of your Settings.Dynamic file. The default values are shown here.

Top left box:

AlarmStatRange0 = 1

Top right box:

AlarmStatRange1 = 10

Bottom left box:

AlarmStatRange2 = 30

Bottom right box:

AlarmStatRange3 = 90

Example: You wish to display alarm statistics for a seven-day period instead of ten days in the upper right box.

  1. Open the Application Configuration dialog.
  2. Switch to the Advanced display mode.
  3. Click the Insert button.
  4. Name the new property, AlarmStatRange1.
  5. Leave the section set to System.
  6. Set the value to 7.

The statistics dialog will now show values for 1, 7, 30 and 90 days.


AlarmStatusDesc0

Viewing: Reference > Property Reference > Alarm Properties > AlarmStatusDesc0

AlarmStatusDesc0 - AlarmStatusDesc5

With the introduction of support for multiple languages, these properties have moved to the phrases as follows:

AlarmStatusDesc0 => TripLabel

AlarmStatusDesc1 => NormalLabel

AlarmStatusDesc2 => AlarmLabel

AlarmStatusDesc3 => NormalLabel

AlarmStatusDesc4 => AlarmLabel

AlarmStatusDesc5 => DisabledLabel

Provides the description for the alarm status in all alarm lists except the history list, which uses the AlarmEventDesc0 through the AlarmEventDesc21 variables.

Section: System

Legacy values: See following list

AlarmStatusDesc0 = Trip

AlarmStatusDesc1 = Normal

AlarmStatusDesc2 = Alarm

AlarmStatusDesc3 = Normal

AlarmStatusDesc4 = Alarm

AlarmStatusDesc5 = Disabled

Related information:

AlarmEventDesc0 - AlarmEventDesc21


AlarmStatusDescWidth

Indicates the maximum number of characters in the alarm status descriptions when the alarm list is printed. The only exception is when the History list is being printed because the History list displays events rather than status.

Related Variables: The AlarmPriorityDescWidth variable enables you to set the maximum number of characters in the alarm priority descriptions when the alarm list is printed. The AlarmStatusDescWidth variable enables you to set the maximum number of characters in the alarm status descriptions when the alarm list is printed.

Section: System

Default: AlarmStatusDescWidth = 14

*No restart required (Settings.Dynamic property)


AlarmTemplateDateFmt

Controls the date format used in spoken (and other) alarms when the %D formatting variable is used.

The value may use any of date formatting codes, date formatting strings or phrase identifier keys within the default languages file. (Date Formatting Codes, Date Formatting Strings, Date and Time Phrase Keys)

DateFmtFullNumeric is a phrase key that evaluates to yyyy-MM-dd.

Section: System

Default: AlarmTemplateDateFmt = DateFmtFullNumeric

*No restart required (Settings.Dynamic property)

Related information:

AlarmTemplateTimeFmt


AlarmTemplateTimeFmt

Controls the time format used in spoken (and other) alarms when the %T formatting variable is used.

The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file. (Time Formatting Codes, Time Formatting Strings, Date and Time Phrase Keys)

TimeFmtHM12Hour is a phrase key that evaluates to hh:mm tt

Section: System

Default: AlarmTemplateTimeFmt = TimeFmtHM12Hour

*No restart required (Settings.Dynamic property)

Related information:

AlarmTemplateDateFmt


AlarmWidgetsShowUnackedNormalAlarm

Most widgets that indicate alarms according to the configuration of an attached Style Settings tag will only do so while the alarm is active. (Does not apply to Alarm Priority Indicator, Alarm Priority Box, and high performance graphics widgets.)

You can cause the widgets to continue indicating alarms that are unacknowledged but no longer active by changing the value of this property to 1.

Section: System

Default: AlarmWidgetsShowUnackedNormalAlarm = 0

*No restart required (Settings.Dynamic property)


AlmListTextColor

Applies only to the deprecated Alarm Banner widget. Will not affect modern Alarm List widgets or the Alarm Page.

Sets the color to be used for text in the alarm list. If set to Invalid, alarms will be displayed using their priority color. Defaults to white (15).

Section: System

Default: AlmListTextColor = 15

*No restart required (Settings.Dynamic property)


AlmPgStartList

Selects the default list of alarms to display when the Alarm page opens.

Select any of the following values:

Value | Description
-2 | Current list (merged active & unacknowledged lists)
-1 | Configured list (all registered alarms)
0 | History list (a historical list of all alarms)
1 | Disabled list (all disabled alarms)
2 | Active list (all active alarms)
3 | Unacknowledged list (all unacknowledged alarms)
4 | (or greater) User-defined lists

Section: System

Default: AlmPgStartList = -2

*No restart required (Settings.Dynamic property)


ApplyMuteSilencePerComputer

Controls whether the Mute and Silence controls of the Alarm Page affect only the current computer or whether the settings will affect all computers that the current user logs onto

Section: System

Default: ApplyMuteSilencePerComputer = 1

*No restart required (Settings.Dynamic property)

Related information:

ApplyMuteSilencePerUser

ApplyMuteSilencePerUser | ApplyMuteSilencePerComputer | Result
1 | 1 | (default) Silence and mute affect only the logged-on user on the current computer.
0 | 1 | Changes to silence and mute will affect only the current workstation, but will remain in effect for all users until changed.
1 | 0 | Changes to silence and mute affect only the current user, but will follow a user who logs out from one computer and in on another.
0 | 0 | Changes to silence and mute will affect all users on all workstations.


ApplyMuteSilencePerUser

Controls whether the Mute and Silence controls of the Alarm Page affect only the current user (resetting when a new user logs on) or whether the settings will affect all users who subsequently sign in at the current workstation.

Section: System

Default: ApplyMuteSilencePerUser = 1

*No restart required (Settings.Dynamic property)

Related information:

ApplyMuteSilencePerComputer

ApplyMuteSilencePerUser | ApplyMuteSilencePerComputer | Result
1 | 1 | (default) Silence and mute affect only the logged-on user on the current computer.
0 | 1 | Changes to silence and mute will affect only the current workstation, but will remain in effect for all users until changed.
1 | 0 | Changes to silence and mute affect only the current user, but will follow a user who logs out from one computer and in on another.
0 | 0 | Changes to silence and mute will affect all users on all workstations.


AutoAckClearedAlarms

Do not set if operators are expected to acknowledge alarms. Use only in situations where operators do not use VTScada to acknowledge alarms.

If set to 1 (true) then all alarms in the application will be set as acknowledged automatically upon clearing (the trigger condition returning to normal).

Does not apply to Trip alarms.

Section: System

Default: AutoAckClearedAlarms = 0

*No restart required (Settings.Dynamic property)


BackupAlarmPriority

Legacy setting. For new applications, use PollDriverAlarmPriority instead.

Sets the priority for the alarm that is triggered when the backup server takes over polling.

Section: System

Default: BackupAlarmPriority = 3

Related information:

BackupSwitchCount


FlashUnackedAlarmsOnServer

When 1 (true), unacknowledged alarms, that the current user is able to view, will blink in the alarm list to draw operator attention. Does not affect the alarm display of an internet client.

Section: System

Default: FlashUnackedAlarmsOnServer = 0

*No restart required (Settings.Dynamic property)

Related information:

FlashUnackedAlarmsOnVIC


FlashUnackedAlarmsOnVIC

Affects the alarm display for Internet Clients. When 1 (true), unacknowledged alarms, that the current user is able to view, will blink in the alarm list to draw operator attention.

If your internet connection is limited by bandwidth restrictions, Trihedral recommends that you do not enable this option for the VIC display.

Section: System

Default: FlashUnackedAlarmsOnVIC = 0

*No restart required (Settings.Dynamic property)

Related information:

FlashUnackedAlarmsOnServer


HighlightUnackedAlarms

When selected, unacknowledged alarms in the alarm list will be highlighted with the color matching their priority, to draw operator attention.

Separate options exist for the server and VIC displays, which will cause the alarm to flash.

Section: System

Default: HighlightUnackedAlarms = 1

*No restart required (Settings.Dynamic property)

Related information:

FlashUnackedAlarmsOnServer

FlashUnackedAlarmsOnVIC


MakeActiveAlarmUnackedWhenEnabled

Set to 1 to mark an alarm in its active state as unacknowledged when it becomes enabled

Section: System

Default: MakeActiveAlarmUnackedWhenEnabled = 0

*No restart required (Settings.Dynamic property)


MakeActiveAlarmUnackedWhenUnshelved

Set to 1 to mark an active alarm as unacknowledged when it becomes unshelved.

Section: System

Default: MakeActiveAlarmUnackedWhenUnshelved = 0

*No restart required (Settings.Dynamic property)


MakeActiveAlarmUnackedWhenUnsuppressed

Set to 1 to mark an active alarm as unacknowledged when the suppression event ends.

Section: System

Default: MakeActiveAlarmUnackedWhenUnsuppressed = 0

*No restart required (Settings.Dynamic property)


ManualUnshelveDoesNotAckNormalAlarm

By default, a manually unshelved normalized alarm will transition to the acknowledged state. Set this property to 1 to prevent that behavior so that the normalized alarm remains unacknowledged after an operator manually unshelves it.

Section: System

Default: ManualUnshelveDoesNotAckNormalAlarm = 0

*No restart required (Settings.Dynamic property)


MaxMuteDuration

Maximum length of time in seconds, for which an operator may mute an alarm. No default value.

Section: System

Default: MaxMuteDuration =

*No restart required (Settings.Dynamic property)


MaxNoteCacheCount

The maximum number of alarm notes per alarm database that will be cached in memory for faster retrieval.

Section: System

Default: MaxNoteCacheCount = 25000

*No restart required (Settings.Dynamic property)


MaxNoteCacheDuration

Maximum number of days that alarm notes will be cached in memory for faster retrieval.

Section: System

Default: MaxNoteCacheDuration = 10000

*No restart required (Settings.Dynamic property)


MaxShelveDuration

Maximum length of time in seconds, for which an operator may shelve an alarm. No default value.

Section: System

Default: MaxShelveDuration =

*No restart required (Settings.Dynamic property)


MinMuteDuration

Minimum length of time in seconds, for which an operator may mute an alarm. No default value.

Section: System

Default: MinMuteDuration =

*No restart required (Settings.Dynamic property)


MinShelveDuration

Minimum length of time in seconds, for which an operator may shelve an alarm. No default value.

Section: System

Default: MinShelveDuration =

*No restart required (Settings.Dynamic property)


MuteAlarms

Controls whether all alarms are to be muted at the start of each user's session.

If set to 1 (true), then all alarms are muted at startup.

Section: System

Default: MuteAlarms = 0

*Restart Required (Settings.Startup property)


NoLegacyAlarmDesc

Controls whether VTScada will log the full, translated description of an alarm in an alarm record, in addition to logging the description's PhraseID (if there is one). The setting also tells the Alarm Page whether to display the legacy Description field in the alarm record, or just display the translated PhraseID.

This property is set to 1 (TRUE) in any new application added since 11.5 / 12.0. All older applications will default this setting to 0 (FALSE).

For new applications, which use PhraseIDs for their descriptions, all that needs to be logged is the PhraseID. Logging the translated description is a waste of resources and therefore NoLegacyAlarmDesc should be set to 1.

In legacy applications, whose descriptions were configured prior to the existence of the concept of PhraseIDs, all the historical alarm records have the alarm description stored in the legacy Description field and therefore NoLegacyAlarmDesc should be set to 0.

It is more efficient for an application to set NoLegacyAlarmDesc = 1.

Section: System

Default: NoLegacyAlarmDesc =1

*No restart required (Settings.Dynamic property)


NormalUnackedAlarmColor

Designates the background color to used for cleared alarms in alarm lists. Defaults to green.

Default: NormalUnackedAlarmColor = <FF00FF00>

Section: System


NoteMinLengthForAck

Sets the minimum length for notes that are prompted for when 'Require note when acknowledging alarm' (NoteRequiredForAck) is 1 (true). If left at 0 (false), operators may cancel the note entry dialog and acknowledge the alarm without recording a note.

Not relevant unless NoteRequiredForAck is 1.

Section: System

Default: NoteMinLengthForAck = 0

*No restart required (Settings.Dynamic property)

Related information:

NoteRequiredForAck

NoteMinLengthForShelve

NoteMinLengthForUnshelve


NoteMinLengthForShelve

Sets the minimum length for notes that are prompted for when 'Require note when shelving alarm' (NoteRequiredForShelve) is 1 (true). If left at 0, operators may cancel the note entry dialog and shelve the alarm without recording a note.

Not relevant unless NoteRequiredForShelve is 1.

Section: System

Default: NoteMinLengthForShelve= 0

*No restart required (Settings.Dynamic property)

Related information:

NoteRequiredForShelve

NoteMinLengthForAck

NoteMinLengthForUnshelve


NoteMinLengthForUnshelve

Sets the minimum length for notes that are prompted for when 'Require note when unshelving alarm' (NoteRequiredForUnshelve) is 1 (true). If left at 0, operators may cancel the note entry dialog and unshelve the alarm without recording a note.

Not relevant unless NoteRequiredForUnshelve is 1.

Section: System

Default: NoteMinLengthForUnshelve= 0

*No restart required (Settings.Dynamic property)

Related information:

NoteRequiredForUnshelve

NoteMinLengthForAck

NoteMinLengthForShelve


NoteRequiredForAck

When set to 1 (true), operators will be prompted to add a note when acknowledging an alarm. The note is not mandatory unless the related property, NoteMinLengthForAck, is set greater than zero.

Notes will be added to the notebook associated with the database that belongs to the alarm being acknowledged.

Section: System

Default: NoteRequiredForAck = 0

*No restart required (Settings.Dynamic property)

Related information:

NoteMinLengthForAck

NoteRequiredForShelve

NoteRequiredForUnshelve


NoteRequiredForShelve

When set to 1 (true), operators will be prompted to add a note when shelving an alarm. The note is not mandatory unless the related property, NoteMinLengthForShelve, is set greater than zero.

Notes will be added to the notebook associated with the database that belongs to the alarm being shelved.

Section: System

Default: NoteRequiredForShelve = 0

*No restart required (Settings.Dynamic property)

Related information:

NoteMinLengthForShelve

NoteRequiredForAck

NoteRequiredForUnshelve


NoteRequiredForUnshelve

When set to 1 (true), operators will be prompted to add a note when unshelving an alarm. The note is not mandatory unless the related property, NoteMinLengthForUnshelve, is set greater than zero.

Notes will be added to the notebook associated with the database that belongs to the alarm being unshelved.

Section: System

Default: NoteRequiredForUnshelve = 0

*No restart required (Settings.Dynamic property)

Related information:

NoteMinLengthForUnshelve

NoteRequiredForAck

NoteRequiredForShelve


PollDriverAlarmDisable

0 (false) by default. If set to 1 (true), VTScada will not trigger an alarm when a polling driver fails-over from the primary to a backup server.

The alarms are decommissioned rather than disabled, so that they do not appear on the list of disabled alarms.

Section: System

Default: PollDriverAlarmDisable = 0

*No restart required (Settings.Dynamic property)

Related Properties:

PollDriverAlarmOnDelay

PollDriverAlarmPriority


PollDriverAlarmOnDelay

Sets the delay before an alarm is triggered when a polling driver fails-over from the primary to a backup server. This is a balance between having prompt notification and avoiding nuisance alarms due to transient network issues. Defaults to 60 seconds.

Section: System

Default: PollDriverOnDelay = 60

*No restart required (Settings.Dynamic property)

Related Properties:

PollDriverAlarmOnDelay

PollDriverAlarmPriority


PollDriverAlarmPriority

Sets the priority assigned to alarms triggered when the polling driver fails-over from the primary to a backup server. Defaults to "Warning" (3).

Section: System

Default: PollDriverAlarmPriority = 3

*No restart required (Settings.Dynamic property)

Related Properties:

PollDriverAlarmPriority

PollDriverAlarmOnDelay


RecordAlarmStatusWhileDisabled

Set to 1 to allow an alarm's active / normal status to be logged while it is disabled. Set to 0 to prevent it.

If 1, the active / normal status will be hidden unless revealed using the Show Disabled Alarms tool.

Section: System

Default: RecordAlarmStatusWhileDisabled= 0

*No restart required (Settings.Dynamic property)


RecordAlarmStatusWhileSuppressed

Set to 1 to allow an alarm's active / normal status to be logged while it is suppressed. Set to 0 to prevent it.

If 1, the active / normal status will be hidden unless revealed using the Show Suppressed Alarms tool.

Section: System

Default: RecordAlarmStatusWhileSuppressed = 0

*No restart required (Settings.Dynamic property)


RecordSuppressionStatus

Set to 1 to log the suppression status of an alarm. Set to 0 to prevent frequent suppression events from filling your alarm history.

If 0, the alarm can still be suppressed but there will be no record of when it was suppressed or unsuppressed and it will not appear in the Suppressed list.

Section: System

Default: RecordSuppressionStatus = 1

*No restart required (Settings.Dynamic property)


SecurityAlarmArea

*Restart Required (Settings.Startup property)

Indicates the area to display in the alarm list for security-related alarms.

Section: System

Default: SecurityAlarmArea = Security

Related Properties

SecurityAlarmPriority


SecurityAlarmPriority

*Restart Required (Settings.Startup property)

Priority level to use for Security Manager alarms. Defaults to 4 (Notice)

Section: System

Default: SecurityAlarmPriority = 4

Related Properties

SecurityAlarmArea


UnackAlarmFlash

Indicates whether unacknowledged low setpoint or high setpoint alarms should or should not be signaled by a flashing indicator on the related station symbol and station page.

If set to 1 (default), unacknowledged alarms will cause the related station symbol and station page to display a flashing alarm indicator.

Section: System

Default: UnackAlarmFlash = 1


UnackFlashRate

Indicates the rate (in seconds) at which unacknowledged alarms should flash on station symbols and station pages if the UnackAlarmFlash variable (see above) is set to 1.

The UnackFlashRate variable may be set to fractions of a second (e.g. ".5") if you desire a faster flash rate.

Section: System

Default: UnackFlashRate = 1


WavAmplitude

Adjusts the volume of alarm tones, ranging from 0 (mute) to 32,768 (full). This value represents the peak of a generated 16-bit signed wave amplitude.

Section: System

Default: WavAmplitude = 12288

*No restart required (Settings.Dynamic property)


WAVType

Indicates the type of waveform produced by the WAVGenerator module.

This may be set to one of:

Value | Meaning
0 | Sine
1 | Square
2 | Saw (default)

Section: System

Default: WAVType = 2

*No restart required (Settings.Dynamic property)


Color Properties

Variables in this section relate to colors.

Refer to the side menu for the listing of properties in this section.


BadQualityColor

Controls the color displayed when a tag is experiencing bad data quality. The default display color for bad data quality is orange.

You can associate basic I/O tags with each other in such a way that the quality of one tag is based on the value of another (refer to the I/O tag's Quality tab). If the Quality of the associated tag is non-zero, blank, or invalid, the data quality is assumed to be good, otherwise, the data is assumed to be bad.

Section: System

Default: BadQualityColor = <FF8000>

*No restart required (Settings.Dynamic property)


ButtonFace

Sets the background color for buttons.

If unspecified (default), ButtonFace uses the GetSystemColor(15) function to return the system color for buttons as defined in Windows.

Section: System

Default: ButtonFace =

*Restart Required (Settings.Startup property)


ButtonHighlight

Sets the highlight color for the sides of buttons.

If unspecified (default), ButtonHighlight uses the GetSystemColor(20) function to return the system color for button highlights as defined in Windows.

Section: System

Default: ButtonHighlight =

*Restart Required (Settings.Startup property)


ButtonShadow

Sets the shadow color for the sides of buttons.

If unspecified (default), ButtonShadow uses the GetSystemColor(16) function to return the system colors as defined in Windows.

Section: System

Default: ButtonShadow =

*Restart Required (Settings.Startup property)


ButtonTextColor

Sets the color of the text label for buttons.

If unspecified (default), ButtonTextColor uses the GetSystemColor(18) function to return the system color as defined in Windows.

Section: System

Default: ButtonTextColor =

*Restart Required (Settings.Startup property)


DefaultBGColor

Sets the background color used when no page is displayed in the Display Manager. By default, the background color to display is white (15) for VTScada applications and black (0) for script applications. For valid color values, please refer to "VTScada Color Palette" .

Section: System

Default: DefaultBGColor = 15

*No restart required (Settings.Dynamic property)


DefaultPageColor

Sets the default background color for new pages. By default, the page background color to display is white (15). For valid color values, refer to "VTScada Color Palette" .

Section: System

Default: DefaultPageColor = 15

*No restart required (Settings.Dynamic property)


DefaultPageColor

Viewing: Reference > Property Reference > Color Properties > DefaultPageColor

DefGraphicBColor

Sets the default fill color used in the Select Brush color palette, and for all geometric drawing tools featuring a brush or fill color. The default brush color is red. For valid color values, refer to the VTScada Color Palette.

Section: System

Default: DefGraphicBColor = 12

*Restart Required (Settings.Startup property)


DefGraphicPColor

Sets the default pen color used in the Select Pen color palette, and for all geometric drawing tools featuring an outline or pen color. The default pen color is black. For valid color values, please refer to VTScada Color Palette.

Section: System

Default: DefGraphicPColor = 0

*Restart Required (Settings.Startup property)


DialogBGColor

Sets the background color for dialogs. By default, the background dialog color is obtained from the system using the GetSystemColor(15) function.

Section: System

Default: DialogBGColor =

*Restart Required (Settings.Startup property)


DigitalIndicator0Color

Controls the color of digital indicators, as shown in the I/O listing of a Sites page, when the matching tag's state is 0. Defaults to light gray.

Section: System

Default: DigitalIndicator0Color = 8

*No restart required (Settings.Dynamic property)


DigitalIndicator1Color

Controls the color of digital indicators, as shown in the I/O listing of a Sites page, when the matching tag's state is 1. Defaults to green.

Section: System

Default: DigitalIndicator1Color = 10

*No restart required (Settings.Dynamic property)


DigitalIndicator2Color

Controls the color of digital indicators, as shown in the I/O listing of a Sites page, when the matching tag's state is 2. Defaults to blue.

Section: System

Default: DigitalIndicator2Color = <0080DD>

*No restart required (Settings.Dynamic property)


DigitalIndicator3Color

Controls the color of digital indicators, as shown in the I/O listing of a Sites page, when the matching tag's state is 3. Defaults to purple.

Section: System

Default: DigitalIndicator3Color = <8000FF>

*No restart required (Settings.Dynamic property)


DigitalIndicatorAlarmColor

Controls the color of digital indicators, as shown in the I/O listing of a Sites page, when the matching tag is in an alarm state. The indicator will also blink while the alarm is unacknowledged. Defaults to red.

Section: System

Default: DigitalIndicatorAlarmColor = 12

*No restart required (Settings.Dynamic property)


DigitalIndicatorInvalidColor

Controls the color of digital indicators, as shown in the I/O listing of a Sites page, when the matching tag's state is Invalid. Defaults to black.

Section: System

Default: DigitalIndicatorInvalidColor= 0

*No restart required (Settings.Dynamic property)


FieldHighlight

Controls the highlight color for the sides of fields.

If left invalid (which it is by default), FieldHighlight uses the GetSystemColor(15) function to return the system colors as defined by the user in Windows.

Section: System

Default: FieldHighlight =

*Restart Required (Settings.Startup property)


FieldShadow

Controls the shadow color for the sides of fields.

If left invalid (default), FieldShadow uses the GetSystemColor(18) function to return the system colors as defined by the user in Windows.

Section: System

Default: FieldShadow =

*Restart Required (Settings.Startup property)


GrayedText

Sets the color for inactive (disabled) text.

If left invalid (default), GrayedText uses the GetSystemColor(17) function to return the system colors as defined by the user in Windows.

Section: System

Default: GrayedText =

*Restart Required (Settings.Startup property)


InvalidColor

The color that will be displayed for tag widgets in the event that their value is invalid. By default, the invalid color is set to black (0).

May be overridden in some widgets, or by the System Style tag, where applicable.

Related Variables: State0DefColor |State1DefColor |State2DefColor |State3DefColor

Section: System

Default: InvalidColor = 0

*Restart Required (Settings.Startup property)


MenuBgnd

The background color for the shortcut menu that opens when any graphic object representing a tag is right-clicked. (The navigation menu) The default setting is invalid, meaning that the color is derived from system settings.

If setting this property, choose contrasting colors for the MenuBgnd and MenuTextColor variables so that the text on the shortcut menu is not invisible or difficult to read.

Related Variables: The MenuTextColor, SelectedBgnd, and SelectedText variables indicate the colors used for non-selected shortcut menu text, the highlight used for selected shortcut menu text, and the color used for selected shortcut menu text (respectively).

Section: System

Default: MenuBgnd =

*Restart Required (Settings.Startup property)


MenuTextColor

The color of the text used to display the menu items on the shortcut menu that opens when any graphic object representing a tag is right-clicked. The default setting is invalid, and the default color is derived from system settings.

Section: System

Default: MenuTextColor =

*Restart Required (Settings.Startup property)


NormalColor

The color displayed for site symbols, input tags, and in the legend when experiencing normal conditions. The default color is 10 (light green).

Section: System

Default: NormalColor = 10

*Restart Required (Settings.Startup property)


OffColor

Specifies the color to be used in the Duplexes widget to indicate an off state for digital control and pump status tags. The default color is 10 (light green).

Section: System

Default: OffColor = 10

*Restart Required (Settings.Startup property)


OnColor

Specifies the color to be used in the Duplexes widget to indicate an on state for digital control and pump status tags. The default color is 12 (light red).

Section: System

Default: OnColor = 12

*Restart Required (Settings.Startup property)


OpaqueBackground

Default value for the opacity of background images added to pages.

If set to 0 (false), then the background images are drawn onto the background as transparent backgrounds (default).

If set to 1 (true), then background images are to be destructively drawn onto the background (opaque).

Section: System

Default: OpaqueBackground = 0

*Restart Required (Settings.Startup property)


PollDisabledColor

Modify the color to be used to indicate when polling has been disabled for a station. The default color is purple (13).

Section: System

Default: PollDisabledColor = 13

*Restart Required (Settings.Startup property)


ReceiveColor

Specifies the color used to display data received from the I/O devices on the default Communications Data page. The ReceiveColor variable is set to 10 (light green) by default.

By default, the Communications Data page has a black background. If you choose to change the color in which received data is displayed, be sure to choose a color that contrasts well with black.

Please read the information provided for the TransmitColor variable.

Section: System

Default: ReceiveColor = 10

*No restart required (Settings.Dynamic property)


SelectedBGnd

Indicates the color of the highlight used to indicate that a menu item is selected on the shortcut menu that opens when any graphic object representing a tag is right-clicked. The default setting is invalid, and the default color is derived from system settings.

It is recommended that you choose contrasting colors for the SelectedBgnd and SelectedText variables so that the text on the shortcut menu is not invisible or difficult to read.

If SelectedBgnd is set to invalid (as it is by default), then the text color for the shortcut menu is derived from the GetSystemColor(13) function.

Related Variables: The MenuBgnd, MenuTextColor, and SelectedText variables indicate the colors used for the background of the shortcut menu, non-selected shortcut menu text, and the color used for selected shortcut menu text (respectively).

Section: System

Default: SelectedBgnd =

*Restart Required (Settings.Startup property)


SelectedText

Indicates the color of text when highlighted in the shortcut menu that opens when any graphic object representing a tag is right-clicked. The default setting is invalid, and the default color is derived from system settings.

It is recommended that you choose contrasting colors for the SelectedBgnd and SelectedText Color variables so that the text on the shortcut menu is not invisible or difficult to read.

If SelectedText is set to invalid (as it is by default), then the color for text highlighted in the shortcut menu is derived from the GetSystemColor(14) function.

Related Variables: The MenuBgnd, MenuTextColor, and SelectedText variables indicate the colors used for the background of the shortcut menu, non-selected shortcut menu text, and the highlight color used for selected shortcut menu text (respectively).

Section: System

Default: SelectedText =

*Restart Required (Settings.Startup property)


State0DefColor

Indicates the default color for state 0 for widgets for digital tags. This setting can be overridden on an individual basis in the tag's widget's settings. By default, state 0 is set to be represented by a light red color (12).

Related Variables: The State0DefColor variable should be used together with the State1DefColor, State2DefColor, State3DefColor and InvalidColor variables to make the default settings for different states unique and comprehensive.

Section: System

Default: State0DefColor = 12

*Restart Required (Settings.Startup property)


State1DefColor

Indicates the default color for state 1 for widgets of digital tags. This variable can be overridden on an individual tag basis in the tag's widget's settings. By default, state 1 is set to be represented by a light green color (10).

Related Variables: The State1DefColor variable should be used together with the State0DefColor, State2DefColor, State3DefColor and InvalidColor variables to make the default settings for different states unique and comprehensive.

Section: System

Default: State1DefColor = 10

*Restart Required (Settings.Startup property)


State2DefColor

Indicates the default color for state 2 for widgets of digital tags. This variable can be overridden on an individual tag basis in the tag's widget's settings. By default, state 2 is set to be represented by a light cyan color (11).

Related Variables: The State2DefColor variable should be used together with the State0DefColor, State1DefColor, State3DefColor, and InvalidColor variables to make the default settings for different states unique and comprehensive.

Section: System

Default: State2DefColor = 11

*Restart Required (Settings.Startup property)


State3DefColor

Indicates the default color for state 3 for widgets of digital tags. This variable can be overridden on an individual basis in the tag's widget's settings. By default, state 3 is set to be represented by a light gray color (7).

Related Variables: The State3DefColor variable should be used together with the State0DefColor, State1DefColor, State2DefColor, and InvalidColor variables to make the default settings for different states unique and comprehensive.

Section: System

Default: State3DefColor = 7

*Restart Required (Settings.Startup property)


TransmitColor

Specifies the color used to display data transmitted to I/O devices on the default Communications Data page. The TransmitColor variable is set to 11 (light cyan) by default.

By default, the Communications Data page has a black background. If you choose to change the color in which transmitted data is displayed, be sure to choose a color that contrasts well with black.

Please read the information provided for the ReceiveColor variable.

Section: System

Default: TransmitColor = 11


UnselectedBgnd

Sets the background color for alarm list items that are not selected in the alarm list.

If set to invalid (as it is by default), the background color for alarm list items not selected in the alarm list is derived from the GetSystemColor( 5) function.

Related Variables: The UnselectedText variable sets the color for the text of non-selected alarm list entries.

Section: System

Default: UnselectedBgnd =

*Restart Required (Settings.Startup property)


UnselectedText

Sets the text color for alarm list entries that are not selected in the alarm list.

If set to invalid (as it is by default), the background color for alarm list items not selected in the alarm list is derived from the GetSystemColor( 8) function.

Related Variables: TheUnselectedBgnd variable sets the background color for alarm list items that are not selected in the alarm list.

Section: System

Default: UnselectedText =

*Restart Required (Settings.Startup property)


WindowBgnd

Sets the background color for windows.

If set to invalid (as it is by default), then the background color is derived from the GetSystemColor( 5) function.

Section: System

Default: WindowBgnd =

*Restart Required (Settings.Startup property)


WindowFrame

Sets the border color for windows.

If set to invalid (as it is by default), then the border color is derived from the GetSystemColor( 6) function.

Section: System

Default: WindowFrame =

*Restart Required (Settings.Startup property)


Communication Driver Properties

The variables in this section relate to communication drivers and communications.

Refer to the side menu for the listing of properties in this section.


#DataLines

Sets the maximum number of communication lines to display on the VTScada Communications Data page.

The VTScada Communications Data page is relevant only for use with the DataFlow RTU tag.

Section: System

Default: #DataLines = 100

*Restart Required (Settings.Startup property)


ABDF1IgnoreAckNak

Adds a small performance increase to the Allen Bradley DF1 driver when using the "Multi-Message Mode".

Note that this setting will affect all drivers using "Multi-Message Mode" mode and may not work with some devices. Default value is 0 (disabled).

Section: System

Default: ABDF1IgnoreAckNak = 1

*No restart required (Settings.Dynamic property)


ABDF1SerialMessages

Sets the maximum number of outstanding messages for the Allen Bradley DF1 driver when using the "Multi-Message Mode".

Section: System

Default: ABDF1SerialMessages = 4

*No restart required (Settings.Dynamic property)


ABFailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate

Default: ABFailoverCount = 1

Section: System

*Restart Required (Settings.Startup property)


AddressParseErrorTimeout

Sets the frequency at which address parsing errors are reported for tags that have an addressing error and are continuously attempting to write.

Measured in seconds.

Section: System

Default: AddressParseErrorTimeout = 20

*No restart required (Settings.Dynamic property)


BackupSwitchCount

Sets the number of consecutive communication errors that need to occur when polling Data Flow RTUs before switching to the first specified backup server.

Section: System

Default: BackupSwitchCount = 30

*Restart Required (Settings.Startup property)

Related information:

PollDriverAlarmPriority


BristolFailoverCount

Determines how many consecutive errors can occur under a service before it attempts to fail over to a different server.

All Bristol drivers under a Bristol Network tag utilize a single service regardless of if SharedRPC is enabled. This setting should be set, at minimum, to the total number of drivers in the network or however many fails that should occur in the system altogether before servership switch.

If a BristolFailoverCount is not set, the Bristol driver sets the failover count value to 10

Section: VTScada Library

Default: BristolFailoverCount =

*No restart required (Settings.Dynamic property)


CampbellCheckSig

If 1 (true), VTScada will check the signature bytes sent after each command response to the Campbell device. This should typically be enabled unless there is an application-specific reason to disable it.

Section: System

Default: CampbellCheckSig = 1

*No restart required (Settings.Dynamic property)


CampbellCRLFWaitTime

Sets the amount of time (in seconds) VTScada will wait for the asterisk character after carriage returns (Enter keys) have been sent when initializing communication with the device.

Section: System

Default: CampbellCRLFWaitTime = 0.3

*No restart required (Settings.Dynamic property)


CampbellCRSendCount

Sets the number of carriage return (or Enter keys) that should be sent when connecting to the Campbell devices. Normally, this should be set to 1.

Section: System

Default: CampbellCRSendCount = 1

*No restart required (Settings.Dynamic property)


CampbellCRSendWaitTime

Sets the amount of time (in seconds) VTScada will wait after each carriage return (Enter key) sent.

Section: System

Default: CampbellCRSendWaitTime = 0.3

*No restart required (Settings.Dynamic property)


CampbellFailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate.

Section: System

Default: CampbellFailoverCount = 0

*Restart Required (Settings.Startup property)


CampbellNoLastMatchRequired.htm

Viewing: Reference > Property Reference > Communication Driver Properties > CampbellNoLastMatchRequired.htm

CampbellNoLastMatchRequired

When not set (0), the driver will attempt to obtain an exact match of values for read-alignment of last readings with new readings. Can normally be left at its default value of 1.

Section: System

Default: CampbellNoLastMatchRequired = 1

*No restart required (Settings.Dynamic property)


CampbellProgressWindow

When enabled, a progress window will be displayed while the Campbell devices are downloading data. This will typically be enabled (1) on larger systems using dedicated servers or disabled (0) on systems using a single workstation.

Section: System

Default: CampbellProgressWindow = 0

*No restart required (Settings.Dynamic property)


CampbellReadAllFirstTime

The Campbell Scientific devices are data loggers that can store large amounts of data internally. When VTScada communicate with them, the default operation is to read only the data that has not already been read. The driver will remember the last item read, and resume from that point.

When set to 1 (true), this property causes the driver to read all logged data in the device when communication is first established. This will be in effect only when the driver is created and connected to the device for the first time.

Section: System

Default: CampbellReadAllFirstTime = 0

*No restart required (Settings.Dynamic property)


CampbellReadOnStart

When set (1), this property forces the driver to do a read of any new data in the RTU as soon as the driver is started instead of waiting until the first time it is polled.

Section: System

Default: CampbellReadOnStart = 0

*No restart required (Settings.Dynamic property)


CampbellRTULabel

Provides a text description of the Campbell devices that will show up in the Tag Browser.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: CampbellRTULabel = Campbell Scientific Array Driver

*No restart required (Settings.Dynamic property)


CampbellSearchWindowSize

Used for tuning by VTScada when searching for timestamps in the Campbell memory bank. The larger this window size, the quicker the search will be but the longer the download will take. The default of 2000 should be used in most circumstances. Valid values range from 100-65535.

Section: System

Default: CampbellSearchWindowSize = 2000

*No restart required (Settings.Dynamic property)


CampbellTestMode

If set to 1 (true), data for Campbell devices should be read from a file, and not from the device. Should not be enabled unless testing specific functions of the driver.

Section: System

Default: CampbellTestMode = 0

*No restart required (Settings.Dynamic property)


CIPENIPSharedRPC

Indicates whether the same RPC service will be used for all instances of the CIPENIP driver.

If set to 1 (true), the same RPC service is used for all instances of CIPENIP.

drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

Section: System

Default: CIPENIPSharedRPC = 0

Related information:

Shared RPC


CIPForwardCloseAdvance

Used to compensate network latency in CIP communications, to avoid the situation of Forward Close commands reaching the destination after the connection has already been closed in the PLC.

May need to be increased for slower links, such as cellular and radio. Default: .5 seconds.

Default: CIPForwardCloseAdvance = .5

Section: System

*No restart required (Settings.Dynamic property)


CIPPLCConnAttLimit

Defines the maximum number of connection attempts to a CIP driver before recommending that an alternate server be tried.

Section: System

Default: CIPPLCConnAttLimit =


CIPTransTimeOutCount

Defines the number of transaction timeouts for a CIP-based driver before the connection is dropped.

Section: System

Default: CIPTransTimeOutCount = 5

*No restart required (Settings.Dynamic property)


CommFailColor

Sets the color displayed in site symbols, Draw widgets, and in the legend when communications with the site have failed. The default color is 12 (light red).

Section: System

Default: CommFailColor = 12

*Restart Required (Settings.Startup property)


CommStatsQualityFactor

Quality of communication is measured by the following formula:

Q = Q * qF + (1 - qF) * (1 - !Error)

where Error is a Boolean stating whether the driver reported an error

state, and the initial value of quality, Q, is defined as 1.

Each time a driver completes a read or write, a new value of the quality is calculated.

qF in this equation stands for QualityFactor and is set by this system variable.

Section: System

Default: CommStatsQualityFactor = 0.99

*Restart Required (Settings.Startup property)


CommStatsUpdateRate

Sets the frequency, in seconds, of when communication statistics are logged if no error has happened.

Statistics are logged whenever an error is encountered regardless of this frequency setting.

Section: System

Default: CommStatsUpdateRate = 300

*Restart Required (Settings.Startup property)


DataFlowStationName

Enables you to specify the title for Data Flow RTU tags. This title appears in the Tag Browser’s Types drop-down list, and on the title bar of all tag properties folders of this tag type. By default, Data Flow RTU tags are titled, "Data Flow RTU".

Section: System

Default: DataFlowStationName = Data Flow System RTU

*Restart Required (Settings.Startup property)

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.


DeltaDigitalMaxBlockSize.htm

Viewing: Reference > Property Reference > Communication Driver Properties > DeltaDigitalMaxBlockSize.htm

DeltaDigitalMaxBlockSize

May be added to a Settings.Dynamic file to limit the size of a read block for digitals, similar to what DeltaVTSMaxBlock does for analogs. Refer to the manufacturer's documentation for your device.

Section: System

Default: DeltaDigitalMaxBlockSize = 2000

Related information:

DeltaVTSMaxBlock


DeltaVTSMaxBlock

May be added to a Settings.Dynamic file to limit the number of analogs included in a read.

Section: System

Default: DeltaVTSMaxBlock = 125

Related information:

DeltaDigitalMaxBlockSize


DemoMode

Enables you to set your VTScada applications to operate in simulation mode, as though a fully-configured system is in operation. The following tags will update to a random value, once every 60 seconds, provided that their area property is set to "Demo".

  • Analog Status
  • Digital Status
  • Pump Status
  • DataFlow Station
  • Data Flow Pulse Input

If set to 1, the simulation mode is switched on. Requires a restart.

Section: System

Default: DemoMode = 0

*Restart Required (Settings.Startup property)

The SimulateIO property is similar, but affects drivers rather than tags that have a "Demo" property.

The DFSimulateOn property further enables you to enhance the simulation by mocking the transmission and reception of data from Data Flow RTUs to the application.


DFSDriverAlarmArea

Sets the area value to be used for an alarm triggered in response to a DataFlow Driver running on backup.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: DFSDriverAlarmArea = System

*No restart required (Settings.Dynamic property)


DFSDriverAlarmDescription

Sets the description value to be used for an alarm triggered in response to a DataFlow Driver running on backup.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: DFSDriverAlarmDescription = Running on backup server

*No restart required (Settings.Dynamic property)


DFSDriverAlarmDisable

Set to 1 (true) to disable the alarm triggered by a DataFlow driver running on backup.

Section: System

Default: DFSDriverAlarmDisable = 0

*No restart required (Settings.Dynamic property)


DFSDriverAlarmName

Sets the name value to be used for an alarm triggered in response to a DataFlow Driver running on backup.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: DFSDriverAlarmDescription = Data Flow Driver Backup Alarm

*No restart required (Settings.Dynamic property)


DFSDriverAlarmOnDelay

Sets the delay in seconds before an alarm is triggered in response to a DataFlow Driver running on backup.

Section: System

Default: DFSDriverAlarmOnDelay = 60

*No restart required (Settings.Dynamic property)


DFSDriverAlarmPriority

Sets the priority value assigned to alarms triggered in response to a DataFlow Driver running on backup. By default, these are recorded with a priority level of 3 - "Warning".

Section: System

Default: DFSDriverAlarmPriority = 3

*No restart required (Settings.Dynamic property)


DFSimulateOn

Enables you to set your VTScada applications to operate in simulation mode, as though data is being transmitted and received from Data Flow RTUs.

If set to 0 (default), then the Data Flow simulation mode is turned off.

Your system must consist of at least one Data Flow RTU driver tag whose selected I/O device is a serial port tag in order for the simulation to work. If the simulation is working properly, data should appear to be transmitted and received on the Communications Data page.

The DemoMode variable further enables you to enhance the simulation by mocking data as if a fully-configured system with multiple I/O tags is in operation.

Section: System

Default: DFSimulateOn = 0

*Restart Required (Settings.Startup property)


DisableCommStats

Disable the logging of communication statistics for all drivers by setting the value to 1.

You can disable the logging of communication statistics for a specific driver type by prepending the drive type name in front of this variable like so:

<DriveTypeName>DisableCommStats = 1

For example, to disable logging for the Allen Bradley driver use the following:

AllenBradleyDisableCommStats = 1

Set to 0 (false) by default.

Section: System

Default: DisableCommStats = 0

*No restart required (Settings.Dynamic property)


DNP3DataInvalidOnFail

Controls whether DNP3 drivers should invalidate data on communications failure. Set to 1 (true) by default.

Section: System

Default: DNP3DataInvalidOnFail = 0


DNP3DelayedResponseTimeout

The maximum time to wait (in seconds) for a file transfer response.

Section: System

Default: DNP3DelayedResponseTimeout = 300

*No restart required (Settings.Dynamic property)


DNP3FailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate

Section: System

Default: DNP3FailoverCount =

*Restart Required (Settings.Startup property)


DNP3MaxFileSize

The maximum size (in bytes) for a permitted file transfer.

Section: System

Default: DNP3MaxFileSize = 2097152

*Restart Required (Settings.Startup property)


EnronBoolMaxBlockSize

Maximum number of standard Boolean values requested in a single read.

Section: System

Default: EnronBoolMaxBlockSize = 2000

*No restart required (Settings.Dynamic property)


EnronContinuousHistoryRead

When 1 (true), a single history poll will continue reading until all new history has been read

Section: System

Default: EnronContinuousHistoryRead = 1

*No restart required (Settings.Dynamic property)


EnronHistoryReadStartUpDelay

Seconds to wait for Enron history tags to initialize before timing out with a comms error.

Section: System

Default: EnronHistoryReadStartUpDelay = 10

*No restart required (Settings.Dynamic property)


EnronLongMaxBlockSize

Maximum message block size for standard long integer or floating point reads.

Section: System

Default: EnronLongMaxBlockSize = 62

*No restart required (Settings.Dynamic property)


EnronMaxHistoryBlockSize

Maximum message block size for history log reads.

Section: System

Default: EnronMaxHistoryBlockSize = 59

*No restart required (Settings.Dynamic property)


EnronPropagateOnlyOnDataChange

If set, driver will not process incoming data if it hasn't changed since the last read. Note that this setting does not apply to history reads or event log reads (which are always processed).

Section: System

Default: EnronPropagateOnlyOnDataChange = 1


EnronShortMaxBlockSize

Maximum message block size for standard short integer reads.

Section: System

Default: EnronShortMaxBlockSize = 125

*No restart required (Settings.Dynamic property)


FastPollCommColor

Indicates the color to display for site symbols, input tags, and in the legend when a site is being fast polled. The default color is 9 (light blue).

The available color values are identified in VTScada Color Palette.

Section: System

Default: FastPollCommColor = 9

*Restart Required (Settings.Startup property)


FastPollDuration

Sets the duration (in seconds) for which fast polling will last after a station page has been opened. The default is 5 minutes (300 seconds).

Section: System

Default: FastPollDuration = 300

*Restart Required (Settings.Startup property)

Related information:

FastPollRate

FastPollCommColor


FastPollRate

Controls the rate (in seconds) at which fast polling occurs.

Section: System

Default: FastPollRate = 2

*Restart Required (Settings.Startup property)

Related information:

FastPollDuration

FastPollCommColor


GESeries90FailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate.

Section: System

Default: GESeries90FailoverCount = 0

*Restart Required (Settings.Startup property)


IECFailoverCount

Count of errors before a soft failover to a redundant server is attempted.

Section: System

Default: IECFailoverCount = 10

*Restart Required (Settings.Startup property)


IECPropagateOnlyOnDataChange

If set, driver will not process incoming data if it hasn't changed since the last read. Note that this setting does not apply to history reads or event log reads (which are always processed).

Section: System

Default: IECPropagateOnlyOnDataChange = 1

*No restart required (Settings.Dynamic property)


InactiveCommColor

Sets the color displayed for site symbols, input tags, and in a site page legend when communications with the site are inactive (i.e. idle, not failed communications). The default color is 10 (light green).

Section: System

Default: InactiveCommColor = 10

*Restart Required (Settings.Startup property)

Related Properties: ActiveCommColor


KoyoFailoverCount

Number of communication failures before switching to backup.

Section: System

Default: KoyoFailoverCount =

*Restart Required (Settings.Startup property)


MercuryDriverAlarmXXXPriority

Where XXX is the item number (only a certain subset of item numbers are alarms).

Values may include the following:

0 = event

1-4 = trip

blank = disabled

Section: System

Default: MercuryDriverAlarmXXXPriority = 3


MercuryDriverEventXPriority

Where XXX is the item number (only a certain subset of item numbers are alarms).

Values may include the following:

0 = event

1-4 = trip

blank = disabled

Section: System

Default: MercuryDriverEventXPriority = 0


MercuryDriverTAPriority_XXXX

Where XXXX is a particular trigger type. Refer to the list of defaults within this topic.

Values may include the following:

0 = event

1-4 = trip

blank = disabled

Section: System

Defaults: MercuryDriverTAPriority_XXXX = 3

MercuryDriverTAPriority_Time =

MercuryDriverTAPriority_Volume =

MercuryDriverTAPriority_Alarm = 3

MercuryDriverTAPriority_SerialAccess =

MercuryDriverTAPriority_MeterReaderAccess =

MercuryDriverTAPriority_KeypadFieldCal =

MercuryDriverTAPriority_KeypadConfigAccess =

MercuryDriverTAPriority_ItemChange =

MercuryDriverTAPriority_Reset =

MercuryDriverTAPriority_AlarmClear = 3

MercuryDriverTAPriority_Shutdown =

*No restart required (Settings.Dynamic property)


MitsubishiFailoverCount

Number of retries before failing over for all instances of the Mitsubishi type. Changes require a restart of the application before taking effect.

Section: System

Default: MitsubishiFailoverCount = 0

*Restart Required (Settings.Startup property)

Related information:

Mitsubishi Driver


MitsubishiPortSharedRPC

Controls whether the same RPC service should be used for all instances of the Mitsubishi driver tags that are connected to the same serial port or TCP/IP connection.

MitsubishiPortSharedRPC enables Mitsubishi devices that share the same serial port or TCP/IP connection to be grouped with the same device, enabling Mitsubishi I/O that uses different radio channels to be polled from separate PCs.

If set to 0 (false), then the same RPC service is not used for all instances of the Mitsubishi tag type that are connected to the same serial port or TCP/IP connection (default). Changes require a restart of the application in order to take effect.

Section: System

Default: MitsubishiPortSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Mitsubishi Driver

MitsubishiSharedRPC


MitsubishiSharedRPC

Controls whether the same RPC service should be used for all instances of the Mitsubishi driver.

If your networked application uses a polling driver, then it is recommended that this variable be set to 1.

If set to 0 (false), then the same RPC service is not used for all instances of the Mitsubishi tag type (default).

Do not use if your drivers are attached to DriverMUX tags.

Section: System

Default: MitsubishiSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Mitsubishi Driver

MitsubishiPortSharedRPC


ModiconDigitalMaxBlockSize

May be added to a Settings.Dynamic file to limit the size of a read block for digitals, similar to what ModiconVTSMaxBlock does for analogs. Refer to the manufacturer's documentation for your device.

Section: System

Default: ModiconDigitalMaxBlockSize = 2000

Related information:

ModiconVTSMaxBlock


ModiconFailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate

Section: System

Default: ModiconFailoverCount =

*Restart Required (Settings.Startup property)


ModiconPropagateOnlyOnDataChange

If set, driver will not process incoming data if it hasn't changed since the last read. Note that this setting does not apply to history reads or event log reads (which are always processed).

Section: System

Default: ModiconPropagateOnlyOnDataChange = 1

*No restart required (Settings.Dynamic property)


ModiconTypedAddr1Offset

Applies the offset for "Type specified" Modbus addresses. For example, the IC0025 device should be 1-based.

May be set in a parent context tag if you have Modbus devices with differing address offsets.

"Type specified" means addresses such as the HC1 and IR2 format. This does not apply to addresses written as numbers only. (For example, 40001 is always the first address in the 40000 block, and is equivalent to HR1 when ModiconTypedAddr1Offset is 0, or HR0 when ModiconTypedAddr1Offset is 1)

Section: System

Default: ModiconTypedAddr1Offset = 1

*Restart Required (Settings.Startup property)


ModiconVTSMaxBlock

May be added to a Settings.Dynamic file to limit the number of analogs to included in a read.

Section: System

Default: ModiconVTSMaxBlock = 125

Related information:

ModiconDigitalMaxBlockSize


NMEAFailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate

Section: System

Default: NMEAFailoverCount = 0

*Restart Required (Settings.Startup property)


NoInitialDriverDial

If NoInitialDriverDial is set to 0, drivers using modems will automatically make a call when VTScada starts. If set to 1, they will not do so. The list of affected drivers is:

  • AB,
  • DNP3
  • Modicon,
  • Omron

Section: System

Default: NoInitialDriverDial = 1

*No restart required (Settings.Dynamic property)


NoSoftDriverFailure

In the event of failed communications, controls whether or not there will be a driver failover to a backup.

  • If set to 1 (true), then the drivers do not switch to backup on failed communications (default).
  • If set to 0 (false), then the drivers do switch to backup on failed communications.

If you have two servers, both of which are on the same network/subnet, then the likelihood of the backup being able to reach the equipment when the primary cannot is slim. The problem is most likely a device or communications-chain issue. In this case, there is no need to have the servers failing back and forth.

As a general rule, it is better to set NoSoftDriverFailure to 1 (true) unless the servers are on completely different networks with separate paths to the devices.

For legacy OEM applications (12.0.0.6 or older) default = 0

Section: System

Default: NoSoftDriverFailure = 1

*No restart required (Settings.Dynamic property)


OmronFINSDriverSemTimeOut

Time in seconds after which the driver semaphore (last communication) is assumed to have failed.

Section: System

Default: OmronFINSDriverSemTimeOut = 10

*No restart required (Settings.Dynamic property)


OmronFINSFailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate

Section: System

Default: OmronFINSFailoverCount =

*Restart Required (Settings.Startup property)


OmronFINSServerFailTimeOut

Time in seconds after which a server failure is assumed.

Section: System

Default: OmronFINSServerFailTimeOut = 30

*No restart required (Settings.Dynamic property)


OmronFailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate

Section: System

Default: OmronFailoverCount =

*Restart Required (Settings.Startup property)


OPCUAClientBlockSize

Controls the maximum number of monitored items that will be placed into a single subscription in an OPC UA Server session.

This is intended for use where the OPC UA server does not provide this value in its server capabilities and has a lower limit than the default 1000 monitored items per subscription that VTScada uses.

Section: System

Default: OPCUAClientBlockSize = 1000

Restart required


OPCUAClientDriverFailoverCount

Number of communication failures to tolerate before initiating a soft failover (trying from another service).

Relevant only if NoSoftDriverFailure is 0.

Section: System

Default: OPCUAClientDriverFailoverCount = Invalid

Restart required


PakBusClockAdjustDiff

The deadband for updating the RTU’s internal clock. If the data logger returns a clock time that differs by more than this parameter, the PakBus driver will send a message to adjust the data logger’s clock. The default value is 5.

Section: System

Default: PakBusClockAdjustDiff = 5

*No restart required (Settings.Dynamic property)


PakbusFailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate

Section: System

Default: PakbusFailoverCount =

*Restart Required (Settings.Startup property)


PakBusInvalidDataPortTimeOut

The time to wait (in seconds) before declaring an error if the connection was not established. The default value is 3 seconds.

Section: System

Default: PakBusInvalidDataPortTimeOut = 3

*No restart required (Settings.Dynamic property)


PakBusInvTableDefRetries

If the PakBus Driver receives an "Invalid Table Definitions" error from a data logger, the driver will immediately attempt to obtain updated table definitions from the RTU. This can be a very time-consuming process since the driver will then have to poll the data logger for its entire history.

PakBusInvTableDefRetries protects against false positives in this scenario. The PakBus Driver will only discard its current table definitions if it receives a number of consecutive "Invalid Table Definitions" errors equal to this parameter. The default value is 3.

Section: System

Default: PakBusInvTableDefRetries = 3

*No restart required (Settings.Dynamic property)


PakBusMoreRecsExistCheck

When the PakBus Driver reads records from a data logger, it continues to request data until the data logger response contains a "No More Records" flag. This parameter determines how many additional times the PakBus Driver must receive this message before it will stop the query. The default value is 1.

Section: System

Default: PakBusMoreRecsExistCheck = 1

*No restart required (Settings.Dynamic property)


ROCPropagateOnlyOnDataChange

If set, driver will not process incoming data if it hasn't changed since the last read. Note that this setting does not apply to history reads or event log reads (which are always processed).

Section: System

Default: ROCPropagateOnlyOnDataChange = 1

*No restart required (Settings.Dynamic property)


RockwellDriverDHRIOChannels

Number of DH+ channels that can be addressed in a 1756-DHRIO card.

Section: System

Default: RockwellDriverDHRIOChannels = 2

*Restart Required (Settings.Startup property)


RockwellDriverMaxCPInstance

The maximum Connection Point instance number to use.

Section: System

Default: RockwellDriverMaxCPInstance = 1

*Restart Required (Settings.Startup property)


RockwellDriverMaxInboundPacketSize

Sets the maximum inbound packet size for your Rockwell drivers.

Section: System

Default: RockwellDriverMaxInboundPacketSize = 476

*Restart Required (Settings.Startup property)


RockwellDriverMaxOutboundPacketSize

Sets the maximum outbound packet size for your Rockwell drivers.

Section: System

Default: RockwellDriverMaxOutboundPacketSize = 476


RockwellDriverMaxStringLength

Sets the maximum string length for your Rockwell drivers.

Section: System

Default: RockwellDriverMaxStringLength = 84

*Restart Required (Settings.Startup property)


RockwellMaxUploadIdle

The maximum idle time in seconds for the tag upload procedure during tag importing.

Section: System

Default: RockwellMaxUploadIdle = 15

*No restart required (Settings.Dynamic property)


RockwellPollB4BuildComplete

Set to 1 (TRUE) in order to poll before all reads are built.

Section: System

Default: RockwellPollB4BuildComplete = 0

*No restart required (Settings.Dynamic property)


RockwellReadsBeforeAddressError

Number of reads before setting an address error.

Section: System

Default: RockwellReadsBeforeAddressError = 2

*No restart required (Settings.Dynamic property)


RockwellWriteMode

Set to 1 for Fragmented (0x53) or 2 for Tag (0x4D)

Section: System

Default: RockwellWriteMode = 0

*No restart required (Settings.Dynamic property)


SiemensS7FailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate.

Section: System

Default: SiemensS7FailoverCount = 0

*Restart Required (Settings.Startup property)


SiemensS7PropagateOnlyOnDataChange

If set, driver will not process incoming data if it hasn't changed since the last read. Note that this setting does not apply to history reads or event log reads (which are always processed).

Section: System

Default: SiemensS7PropagateOnlyOnDataChange = 1


SimulateIO

Enables you to set your VTScada applications to operate in simulation mode, as though a fully-configured system is in operation. The following drivers will generate a random value for attached input tags approximately every 15 seconds while SimulateIO is TRUE (1). Input tags do not require any particular value for their Area parameter. Attached output tags are not given random values and values are not written.

  • AB driver
  • Campbell RTU
  • DNP3
  • FINS
  • GESeries90
  • Koyo
  • Modbus
  • Motorola
  • Omron
  • OPCClient
  • PakBus
  • Workstation Status

If set to 1, the simulation mode is switched on.

Section: System

Default: SimulateIO = 0

*No restart required (Settings.Dynamic property)

The DemoMode property is similar, but affects only certain status tags with "Demo" in their Area parameter.

The DFSimulateOn property further enables you to enhance the simulation by mocking the transmission and reception of data from Data Flow RTUs to the application.


SNMPAgentEnable

If set to 1 (true), then the SNMP agent will be enabled. Defaults to 0, disabled.

Section: System

Default: SNMPAgentEnable = 0

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentReadCommunity | SNMPAgentWriteCommunity | SNMPAgentWriteEnable


SNMPAgentInformRetryInterval

The number of seconds between InformRequest retries. Defaults to 3.

Section: System

Default: SNMPAgentInformRetryInterval = 3

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentInformRetryLimit


SNMPAgentInformRetryLimit

Sets the number of retry attempts for InformRequests. Defaults to 1.

Section: System

Default: SNMPAgentInformRetryLimit = 1

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentInformRetryInterval


SNMPAgentIPListener

The SNMP Agent uses the IP Network Listener tag to provide access to the system. This tag provides features such as IP filtering and connection audit logs. This property specifies the name of the IP Network Listener to use for access. Defaults to "SNMP Agent Server Port", which should be the name that you give the tag. If you assign another name to the tag, change this property to match.

Section: System

Default: SNMPAgentIPListener = SNMP Agent Server Port

*Restart Required (Settings.Startup property)


SNMPAgentMaxRepetitionsCap

A cap on max-repetitions in an SNMP GetBulk request. Max-repetitions is a parameter in the SNMP GetBulk request.

Section: System

Default: SNMPAgentMaxRepetitionsCap = 1000

*No restart required (Settings.Dynamic property)

Related information:

SNMPGetBulkDistributor Tag


SNMPAgentMaxTCPSize

Largest SNMP message size allowed over TCP transport, measured in bytes. Defaults to 8192.

Section: System

Default: SNMPAgentMaxTCPSize = 8192

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentSessionTimeout

SNMPAgentMaxUDPSize


SNMPAgentMaxUDPSize

Sets the largest SNMP message allowed over UDP transport, measured in bytes. Defaults to 1472.

Section: System

Default: SNMPAgentMaxUDPSize = 1472

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentSessionTimeout

SNMPAgentMaxTCPSize


SNMPAgentReadCommunity

Sets the SNMP community name for read-only access. Defaults to "public".

Section: System

Default: SNMPAgentReadCommunity = public

*No restart required (Settings.Dynamic property)

SNMPAgentEnable | SNMPAgentWriteCommunity | SNMPAgentWriteEnable


SNMPAgentSessionTimeout

Controls the number of seconds until an idle NMS Closed Network Management System session is closed (def: 60)

Section: System

Default: SNMPAgentSessionTimeout = 60

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentMaxTCPSize

SNMPAgentMaxUDPSize


SNMPAgentSNMPVersion

SNMP version used by the VTScada SNMP Agent. Set to 1 for v2c, 3 for v3.

Section: System

Default: SNMPAgentSNMPVersion = 1

*No restart required (Settings.Dynamic property)


SNMPAgentTagExposedProperties

Defines a list of tag properties to include in the SNMP MIB generated by VTScada.

If left blank, the following tag properties are published: Name, Value, Quality, Timestamp, Type, Description, Area, Units, Device, Address. Applies to new I/O tags and also to legacy analog and digital tags.

If specified, this acts as a complete list of properties to publish and will exclude any properties that are not included. Specify properties in a comma-separated list. For example: Name, Value, Timestamp.

For applications that need to send out notifications (ie. TRAPS/INFORMS) at least one of the following must be included: Value, Quality or Timestamp.

Notifications sent out of VTScada always contain any of the 3 fields that are part of the MIB. If all 3 are part of the MIB then all 3 are contained in the notifications, if 2 are part of the MIb then only those 2 are sent out. At least one of these 3 properties and those fields must be part of the MIB Closed Management Information Base. A hierarchy of the information available to an SNMP device, organized by numbered Object Identifiers (OIDs).

Section: System

Default: SNMPAgentTagExposedProperties =

*No restart required (Settings.Dynamic property)


SNMPAgentTagNotifyMode

Tag change notifications. This is set numerically as follows:

0 == Disable

1 == Server Only (default)

2 == Enable

Section: System

Default: SNMPAgentTagNotifyMode = 1

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentTrapCommunity

SNMPAgentTrapHost

SNMPAgentTrapPort


SNMPAgentTrapCommunity

SNMP community name for notification messages. Defaults to "public".

Section: System

Default: SNMPAgentTrapCommunity = public

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentTagNotifyMode

SNMPAgentTrapHost

SNMPAgentTrapPort


SNMPAgentTrapHost

Maintained only for backward compatibility. New applications should not use this setting. Instead, create an "SNMP Destination Tag", for use only when the Agent is set to SNMP Version 2.

The host name or IP address to send traps/informs. Set blank to disable.

Section: System

Default: SNMPAgentTrapHost =

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentTagNotifyMode

SNMPAgentTrapCommunity

SNMPAgentTrapPort


SNMPAgentTrapPort

Maintained only for backward compatibility. New applications should not use this setting. Instead, create an "SNMP Destination Tag", for use only when the Agent is set to SNMP Version 2.

UDP port to send traps/informs. Defaults to 162.

Section: System

Default: SNMPAgentTrapPort = 162

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentTagNotifyMode

SNMPAgentTrapCommunity

SNMPAgentTrapHost


SNMPAgentWriteCommunity

Sets the SNMP community name for write access. Defaults to none.

Section: System

Default: SNMPAgentWriteCommunity =

*No restart required (Settings.Dynamic property)

Related information:

SNMPAgentEnable | SNMPAgentReadCommunity | SNMPAgentWriteEnable


SNMPAgentWriteEnable

Must be set to 1 (true), to enable write access. Defaults to 0, disabled.

Section: System

Default: SNMPAgentWriteEnable = 0

*No restart required (Settings.Dynamic property)

Do not enable write access over an unsecured network.

Related information:

SNMPAgentEnable | SNMPAgentReadCommunity | SNMPAgentWriteCommunity


SNMPDriverLegacyV3Notifications

In legacy applications (those built prior to the release of VTScada 12.1), notifications carrying different usernames were accepted if they had the same credentials. For example, if you had specified three users: User1, User2, User3, then all these users would have the same credentials (the legacy credentials) and were all represented by a default username in the USM data base. Traps carrying any of the three user names were accepted.

Every SNMP driver now has its own sets of separate credentials, and therefore the legacy behavior does not apply unless this property is set to 1.

Section: System

Default: SNMPDriverLegacyV3Notifications =

*No restart required (Settings.Dynamic property)


SNMPDriverOctetStringMaxSize

Specifies the expected maximum size in bytes of OCTETSTRING data to be read by any SNMP driver in the application.

This will allow multiple IO tags to be coalesced in a single GET request. If this property is left invalid then no OCTETSTRING GET requests will be coalesced. If set, the value must be a valid integer.

Section: System

Default: SNMPDriverOctetStringMaxSize =

*No restart required (Settings.Dynamic property)


SNMPFailoverCount

Controls how many connection attempts will be made before a failure is set and an alternate is recommended.

Defaults to 5, but can be set to any number greater than 0.

If an invalid or out of bounds value is provided, the variable will default to 5.

Section: System

Default: SNMPFailoverCount = 5

*No restart required (Settings.Dynamic property)


SNMPv3AgentMinSecurityLevel

This specifies the SNMP security level the VTScada SNMP agent will use when the SNMP version is set to v3.

0 for no security, 1 for authentication only, 2 for authentication and encryption.

Section: System

Default: SNMPv3AgentMinSecurityLevel = 2

*No restart required (Settings.Dynamic property)


SNMPv3AgentReadAuthPassword

Encrypted authentication password for the read user. This property can be set only by using the fields provided in the 'Other' tab of the Edit Properties dialog, basic mode. Do not attempt to edit this property directly. Enabled only when the v3 Security level is set to at least "authentication only".

Section: System

Default: SNMPv3AgentReadAuthPassword =

*No restart required (Settings.Dynamic property)


SNMPv3AgentReadAuthProtocol

Specifies the authentication protocol in use for the username defined in SNMPv3AgentReadUser.

  • 0 = MD5
  • 1 = SHA1

Section: System

Default: SNMPv3AgentReadAuthProtocol =

*No restart required (Settings.Dynamic property)


SNMPv3AgentReadPrivPassword

Encrypted privacy password for the read user. This property can be set only by using the fields provided in the 'Other' tab of the Edit Properties dialog, basic mode. Do not attempt to edit this property directly. Enabled only when the v3 Security level is set to at least "authentication and encryption".

Section: System

Default: SNMPv3AgentReadPrivPassword =

*No restart required (Settings.Dynamic property)


SNMPv3AgentReadPrivProtocol

Specifies the privacy protocol in use for the username defined in SNMPv3AgentReadUser.

  • 0 = DES
  • 1 = AES-128
  • 2 = 3DES with Reeder key extension
  • 3 = AES-256 with Blumenthal key extension

Section: System

Default: SNMPv3AgentReadPrivProtocol =

*No restart required (Settings.Dynamic property)


SNMPv3AgentReadUser

Username for an SNMPv3 user with read-only permission.

Section: System

Default: SNMPv3AgentReadUser =

*No restart required (Settings.Dynamic property)


SNMPv3AgentTrapAuthPassword

Encrypted authentication password for the trap user. This property can be set only by using the fields provided in the 'Other' tab of the Edit Properties dialog, basic mode. Do not attempt to edit this property directly. Enabled only when the v3 Security level is set to at least "authentication only".

Section: System

Default: SNMPv3AgentTrapAuthPassword =

*No restart required (Settings.Dynamic property)


SNMPv3AgentTrapAuthProtocol

Specifies the authentication protocol in use for the username defined in SNMPv3AgentTrapUser.

  • 0 = MD5
  • 1 = SHA1

Section: System

Default: SNMPv3AgentTrapAuthProtocol =

*No restart required (Settings.Dynamic property)


SNMPv3AgentTrapPrivPassword

Encrypted privacy password for the trap user. This property can be set only by using the fields provided in the 'Other' tab of the Edit Properties dialog, basic mode. Do not attempt to edit this property directly. Enabled only when the v3 Security level is set to at least "authentication and encryption".

Section: System

Default: SNMPv3AgentTrapPrivPassword =

*No restart required (Settings.Dynamic property)


SNMPv3AgentTrapPrivProtocol

Specifies the privacy protocol in use for the username defined in SNMPv3AgentTrapUser.

  • 0 = DES
  • 1 = AES-128
  • 2 = 3DES with Reeder key extension
  • 3 = AES-256 with Blumenthal key extension

Section: System

Default: SNMPv3AgentTrapPrivProtocol = 0

*No restart required (Settings.Dynamic property)


SNMPv3AgentTrapUser

Username for an SNMPv3 user for sending traps.

Section: System

Default: SNMPv3AgentTrapUser =

*No restart required (Settings.Dynamic property)


SNMPv3AgentWriteAuthPassword

Encrypted authentication password for the write user. This property can be set only by using the fields provided in the 'Other' tab of the Edit Properties dialog, basic mode. Do not attempt to edit this property directly. Enabled only when the v3 Security level is set to at least "authentication only".

Section: System

Default: SNMPv3AgentWriteAuthPassword =

*No restart required (Settings.Dynamic property)


SNMPv3AgentWriteAuthProtocol

Specifies the authentication protocol in use for the username defined in SNMPv3AgentWriteUser.

  • 0 = MD5
  • 1 = SHA1

Section: System

Default: SNMPv3AgentWriteAuthProtocol = 0

*No restart required (Settings.Dynamic property)


SNMPv3AgentWritePrivPassword

Encrypted privacy password for the write user. This property can be set only by using the fields provided in the 'Other' tab of the Edit Properties dialog, basic mode. Do not attempt to edit this property directly. Enabled only when the v3 Security level is set to at least "authentication and encryption".

Section: System

Default: SNMPv3AgentWritePrivPassword =

*No restart required (Settings.Dynamic property)


SNMPv3AgentWritePrivProtocol

Specifies the privacy protocol in use for the username defined in SNMPv3AgentWriteUser.

  • 0 = DES
  • 1 = AES-128
  • 2 = 3DES with Reeder key extension
  • 3 = AES-256 with Blumenthal key extension

Section: System

Default: SNMPv3AgentWritePrivProtocol =

*No restart required (Settings.Dynamic property)


SNMPv3AgentWriteUser

Username for an SNMPv3 user with read and write permissions.

Section: System

Default: SNMPv3AgentWriteUser =

*No restart required (Settings.Dynamic property)


SQLDataQueryDriverDefaultDBType

The property applies only to the SQL Data Query Driver.

A numeric value, setting the default database type for the SQL Data Query Driver tag.

Value | Default database type
0 | MSSQL
1 | MS Access
2 | Oracle
3 | MySQL

Section: System

Default: SQLDataQueryDriverDefaultDBType = 2

*No restart required (Settings.Dynamic property)


SQLDataQueryDriverDefaultTableName

Sets the default table name for use by the SQL Data Query Driver tag.

Section: System

Default: SQLDataQueryDriverDefaultTableName = RealAnalog

*No restart required (Settings.Dynamic property)


SQLDataQueryDriverFailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate.

Section: System

Default: SQLDataQueryDriverFailoverCount =

*Restart Required (Settings.Startup property)


SQLDataQueryDriverMaxTagsPerQuery

Viewing: Reference > Property Reference > Communication Driver Properties > SQLDataQueryDriverMaxTagsPerQuery

Concepts:

Table Structure and Notes

SQL: Reference and Examples

Reference:

SQLQueryHideLegacyTables

SQLQueryHistoryNoOverridesTableName

SQLQueryHistoryNoOverridesTableSupportsTPP

SQLQueryMaxResultRows

SQLQueryTableTPPs

SQLDataQueryDriverMaxTagsPerQuery

The SQL Query Driver tag places a limit on the number of tags that can included per query. Use this setting to adjust that limit as required.

Section: System

Default: SQLDataQueryDriverMaxTagsPerQuery = 25

*No restart required (Settings.Dynamic property)


TescoDriverDiagnosticLogAge

Sets the length of time for which a log file should be kept before it is deleted. This ensures that log files do not accumulate without limit. Measured in seconds, the default is one week.

Section: System

Default: TescoDriverDiagnosticLogAge = 604800

*No restart required (Settings.Dynamic property)


TescoDriverDiagnosticLogDuration

Sets the period of time to include in each diagnostic file, after which a new file is created. Measured in seconds, the default value is one day.

Section: System

Default: TescoDriverDiagnosticLogDuration = 86400

*No restart required (Settings.Dynamic property)


TescoDriverDiagnosticLogEnable

Turns on file-based diagnostic logging for detailed troubleshooting of the driver. Files are stored in the Trace Files location with one folder per driver.

The format does not consume a large amount of disk space, but note that this logging is somewhat heavy on CPU and disk activity and therefore should be disabled except when there is a need to diagnose problems.

Section: System

Default: TescoDriverDiagnosticLogEnable = 0

*No restart required (Settings.Dynamic property)


TescoDriverDiagnosticLogRecentSize

Controls how many recent diagnostic log messages should be stored in memory. This helps capture driver behavior in memory dumps. Set to 0 to turn it off.

Section: System

Default: TescoDriverDiagnosticLogRecentSize = 100

*No restart required (Settings.Dynamic property)


TescoDriverDisableCommStats

Disables Comm Stat logging for all Tesco Drivers

Section: System

Default: TescoDriverDisableCommStats = 0

*Restart Required (Settings.Startup property)


TescoFailoverCount

Number of communication failures to tolerate before initiating a soft failover (trying from another service).

Relevant only if NoSoftDriverFailure is 0.

Section: System

Default: TescoFailoverCount = Invalid

*Restart Required (Settings.Startup property)


TescoPortErrorDelay

Number of seconds to wait after a port connection error before the connection can be retried. This helps to prevent continuous connection attempts when a device is unreachable.

Section: System

Default: TescoPortErrorDelay = 15

*No restart required (Settings.Dynamic property)


TI505FailoverCount

Number of consecutive errors required before a server marks itself as bad by calling RecommendAlternate.

Section: System

Default: TI505FailoverCount = 0

*Restart Required (Settings.Startup property)


TI505PropagateOnlyOnDataChange

If set, driver will not process incoming data if it hasn't changed since the last read. Note that this setting does not apply to history reads or event log reads (which are always processed).

Section: System

Default: TI505PropagateOnlyOnDataChange = 1

*No restart required (Settings.Dynamic property)


TI505SharedRPC

Controls whether the same RPC service will be used for all instances of the TI 505 driver.

If set to 1 (true), the same RPC service is used for all instances of TI 505. drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

Section: System

Default: TI505SharedRPC= 0

*Restart Required (Settings.Startup property)

Related: Shared RPC


ToyopucDriverVTSMaxBlock

May be added to a Settings.Dynamic file to limit the number of blocks included in a read. The maximum value (and default) is 512.

Section: System

Default: ToyopucDriverVTSMaxBlock = 512

*No restart required (Settings.Dynamic property)


VRDPLCConnAttLimit

Sets the number of PLC connection attempts that a Veeder Root driver should make before failing.

Section: System

Default: VRDPLCConnAttLimit = 5

*No restart required (Settings.Dynamic property)


VTSDriverClearDataOnServerLossDelay

Seconds without an I/O server before a client will invalidate read values.

The default of 10 will be adequate in most instances, but can cause problems in applications with RPC problems or with hundreds of RPC services. In these cases, increasing to longer delay value can be beneficial. Setting this value too low can have negative consequences that must be accounted for with tight clock synchronization

Section: System

Default: VTSDriverClearDataOnServerLossDelay = 10

*No restart required (Settings.Dynamic property)


Control Lock and Token Properties

Variables in this section relate to the Control Lock system and the Control Token system.

Refer to the side menu for the listing of properties in this section.


ControlLockAutoUnlockUponLogout

Enables an automated lock release mechanism when set to 1.

Automatic lock release is disabled when lock ownership is enabled under mode 2 for MachineID or mode 3 for custom hook ownership.

Section: System

Default: ControlLockAutoUnlockUponLogout = 0

*No restart required (Settings.Dynamic property)


ControlLockCanOnlyRemoveOwnLock

By default, anyone with either the Lock Add / Remove privilege or the Lock Administrator privilege can remove any set lock.

Setting this property to 1 changes the behavior such that locks can be removed only by either the person who owns the lock or by anyone who possesses the Lock Administrator privilege.

Lock ownership can be defined in several ways. (Refer to Control Lock Security)

Section: System

Default: ControlLockCanOnlyRemoveOwnLock = 1

*No restart required (Settings.Dynamic property)


ControlLockLevelIconXOffset

Sets the default horizontal offset location of the Lock Level number in a Lock Level Box widget.

Section: System

Default: ControlLockLevelIconXOffset = 0

*No restart required (Settings.Dynamic property)


ControlLockLevelIconYOffset

Sets the default vertical offset location of the Lock Level number in a Lock Level Box widget.

Section: System

Default: ControlLockLevelIconYOffset = -3

*No restart required (Settings.Dynamic property)


ControlLockLevelXColor

Where "X" is 1, 2, 3,...

Sets the color to be used when showing control lock icons of the matching level. Typically set to an alpha-RGB string using the format <AARRGGBB> but may use a number from the legacy VTScada color palette. (The alpha value is optional in a color string and will default to FF if not specified.)

Section: System

Defaults:

ControlLockLevel1Color = <FF0000>

ControlLockLevel2Color = <FFA000>

ControlLockLevel3Color = <FFFF00>

*No restart required (Settings.Dynamic property)


ControlLockLevelXLabel

Where "X" is 1, 2, 3,...

Sets the phrase key (or text if no phrase key exists) to be used when showing control locks of the matching level. Lock levels default to "Level 1", "Level 2", etc. if the matching label is not defined.

A typical use-case would be to label Lock Levels as "Maintenance", "Testing", "Warning", etc.
The labels appear as tooltips when hovering over lock icons in the Lock List widget.

Section: System

Defaults:

ControlLockLevel1Label =

ControlLockLevel2Label =

ControlLockLevel3Label =

*No restart required (Settings.Dynamic property)


ControlLockLevelXPreventControl

Where "X" is 1, 2, 3, etc. match a defined Control Lock Level.

Three Lock Levels 1, 2, and 3, are defined in every application. When ControlLockLevelXPreventControl is set to 0, locks with the matching Lock Level, X, do not prevent control.

You can create new Lock Levels by adding new ControlLockLevelXPreventControl properties to your application, setting X to 4, 5, 6, etc.

Section: System

Defaults:

ControlLockLevel1PreventControl = 1

ControlLockLevel2PreventControl = 1

ControlLockLevel3PreventControl = 1

*No restart required (Settings.Dynamic property)


ControlLockNoteMinLength

Relevant only when ControlLockNoteRequiredForAdd or ControlLockNoteRequiredForRemove is set.

This property sets the minimum number of characters required when an operator creates a note. A value of 0 (the default) allows the operator to skip past the Create Note dialog when setting or removing a lock.

Section: System

Default: ControlLockNoteMinLength = 0

*No restart required (Settings.Dynamic property)


ControlLockNoteRequiredForAdd

When set to 1, operators must create a note when locking controls.

The length of the note is controlled by ControlLockNoteMinLength. Setting that to 0 (the default) allows operators to skip past the Create Note dialog without typing.

Section: System

Default: ControlLockNoteRequiredForAdd = 0

*No restart required (Settings.Dynamic property)


ControlLockNoteRequiredForRemove

When set to 1, operators must create a note when unlocking controls.

The length of the note is controlled by ControlLockNoteMinLength. Setting that to 0 (the default) allows operators to skip past the Create Note dialog without typing.

Section: System

Default: ControlLockNoteRequiredForRemove = 0

*No restart required (Settings.Dynamic property)


ControlLockOwnerMode

Relevant only when ControlLockCanOnlyRemoveOwnLock is set to 1, thereby enabling the Lock Ownership feature of Control Locks. That property restricts which locks users with the Lock Add/Remove privilege can remove, such that they can only remove locks that they ‘own’.

The definition of ownership varies according to this property as follows:

Anyone with the Lock Administrator privilege can always remove any lock.

0. Session ID ownership (ControlLockOwnerMode=0)

Users only own locks that they create during a given session. Each time a user signs on, a new session ID is generated. Therefore, signing in and setting a lock, signing off, and then signing in again would result in the same user being in a different session and not be able to remove the locks they set in the first session. This extends to both thin and thick clients. Even if the same user is signed in on several clients, locks added on one will not be removable on other clients.

1. Account ID ownership (ControlLockOwnerMode=1)

This is the most straightforward ownership mode. As the name suggests, ownership is defined by the account ID that added the lock. If the same user is signed into several machines they would be able to remove locks set on other machines / clients.

2. Machine ID ownership (ControlLockOwnerMode=2)

In this mode, ownership is defined by the machine ID. This is useful way to segregate removal permissions based on physical workstations. When ownership is set to this mode, AutoUnlockUponLogout does not apply.

3. Custom Hook ownership (ControlLockOwnerMode=3)

Applies only to those who are developing their own code that involves Control Locks. When ownership is set to this mode, AutoUnlockUponLogout does not apply.

Ownership is defined by a custom hook provided by the customer within their code: ControlLockIsOwnerHook.SRC.

Section: System

Default: ControlLockOwnerMode = 1

*No restart required (Settings.Dynamic property)


ControlLocksEnabled

Must be set to 1 to enable the Control Locks feature of VTScada.

Control Locks disable all writes to selected tags from the VTScada user interface and are typically applied to dangerous equipment while operators are performing maintenance.

Section: System

Default: ControlLocksEnabled = 0

*No restart required (Settings.Dynamic property)


ControlTokenAutoReleaseUponLogout

Controls whether Control Tokens requested in the current session should be released automatically when the owner signs out (i.e. upon session termination). By default, tokens will continue to exist when the owner signs out. Token Requests made during the session will also be automatically denied (i.e. removed from request list) if ControlTokenAutoReleaseUponLogout is true.

Note: Ownership may be tied to a specific session or workstation rather than simply to the account that created the Control Token, in which case the owner may not regain control of the token upon signing back in (a new session) or signing in at a different workstation. Refer to ControlTokenOwnerMode

Section: System

Default: ControlTokenAutoReleaseUponLogout = 0

*No restart required (Settings.Dynamic property)


ControlTokenAutoRequestOption

If the configured condition is met, automated requests for tokens will always be added to the request list if there is currently a token being held by a different owner for that tag or that tag's parent.

For example, when set to 1 (the default) automated requests for a control token will always be added to the token request list if there is currently a token being held by a different owner for that tag or that tag's parent. If not, the request will go through and you will be granted the token directly. If set to 0, then no automated request will ever be added to the request list. For all other values of this property, the result of an automated request for a token will depend on whether the priority level of the request is greater (lower level number) than the priority level of the existing token, or less. (Other comparisons are possible.)

Requests made by the Control Token Box widget are examples of an automated requests.
Requests made using the Request button are a manual request.

Section: System

Default: ControlTokenAutoRequestOption = 1

*No restart required (Settings.Dynamic property)

Possible values:

0 | Never
1 | Always
2 | If request level priority > token level priority (lower number / higher priority takes precedence)
3 | If request level priority >= token level priority
4 | If request level priority < token level priority
5 | If request level priority <= token level priority
6 | If request level priority == token level priority
7 | If request level priority != token level priority


ControlTokenAutoStealOption

Controls whether to grant an automatic token request for a token on a tag that is currently being controlled by another owner. An example of an automated request would be a request made by the Control Token Box widget.

For example, when set to 0 (the default) no automated process will remove the current user's token. If set to 1, then any automated request for a token will remove the current user's token and grant the requester said token. As well, it does not necessarily need to remove a token but it will grant a token to the requester, effectively always transferring control (e.g. requesting a token for a tag whose parent has a token placed on it). For all other values of this property, the result of an automated request for a token will depend on whether the priority level of the request is greater (lower level number) than the priority level of the existing token, or less. (Other comparisons are possible.)

Section: System

Default: ControlTokenAutoStealOption = 0

*No restart required (Settings.Dynamic property)

Possible values:

0 | Never
1 | Always
2 | If request level priority > token level priority (lower number / higher priority takes precedence)
3 | If request level priority >= token level priority
4 | If request level priority < token level priority
5 | If request level priority <= token level priority
6 | If request level priority == token level priority
7 | If request level priority != token level priority


ControlTokenCanOnlyRemoveOwnToken

Controls whether Control Token owners can release only their own token, or if they are able to release tokens held by any user.

Defaults to 1, so that token owners can release only their own tokens.

Section: System

Default: ControlTokenCanOnlyRemoveOwnToken = 1

*No restart required (Settings.Dynamic property)


ControlTokenEnableOwnerMonitor

Controls whether VTScada will automatically release stale tokens and token requests. Enabled by default.

Section: System

Default: ControlTokenEnableOwnerMonitor = 1

Related Properties:

ControlTokenMonitorTime

ControlTokenOwnerHeartbeat

ControlTokenPendingRequestStaleTime

ControlTokenStaleTokenTime


ControlTokenEnablePopupRequests

Must be enabled for Control Token owners to see a popup notification when another user requests a token on a tag that they currently control.

Section: System

Default: ControlTokenEnablePopupRequests = 1

*No restart required (Settings.Dynamic property)


ControlTokenLevelXColor

To create new Control Token levels beyond the three provided, add this property to your application. X should be a number defining the new level and must start at 4, increasing sequentially as you add more. Do not skip level numbers.

The level is created and the indicator color for that level are created simultaneously with each new ControlTokenXLevelColor property.

You may also define a label for the level. The default (in English) will be "Level X", where X matches the level number. If defining custom labels, you may wish to start at 1 in order to maintain consistency across all.

Section: System

Default: ControlTokenLevel1Color = <FF0000>

Related Properties: ControlTokenLevelXLabel


ControlTokenLevelXLabel

Use to set a label other than "Level X" for each Control Token level.

If defining a custom label for a custom level (4 and above), you are advised to start at 1 in order to maintain consistency across the set. The default values are blank, meaning that the labels (in English) for the three default levels will be "Level 1", "Level 2", and "Level 3"

Section: System

Default: ControlTokenLevel1Label =

Related Properties: ControlTokenLevelXColor


ControlTokenManualRequestOption

Controls whether a user's request for a control token will be added to the request list.

For example, when set to 1 (the default) user requests for a control token will always be added to the token request list if another user currently has a control token that applies to said tag. If set to 0, then no user request will ever be added to the request list. For all other values of this property, the result of a user's request for a token will depend on whether the priority level of the request is greater (lower level number) than the priority level of the existing token, or less. (Other comparisons are possible.)

Section: System

Default: ControlTokenManualRequestOption = 1

*No restart required (Settings.Dynamic property)

Possible values:

0 | Never
1 | Always
2 | If request level priority > token level priority (lower number / higher priority takes precedence)
3 | If request level priority >= token level priority
4 | If request level priority < token level priority
5 | If request level priority <= token level priority
6 | If request level priority == token level priority
7 | If request level priority != token level priority


ControlTokenManualStealOption

Controls whether to grant a manual token request for a token on a tag that is currently being controlled by another owner. An example of a manual request would be a request made by the clicking the Token Request button.

For example, when set to 0 (the default) no manual process will remove the current user's token. If set to 1, then any manual request for a token will remove the current user's token and grant the requester said token. As well, it does not necessarily need to remove a token but it will grant a token to the requester, effectively always transferring control (e.g. requesting a token for a tag whose parent has a token placed on it). For all other values of this property, the result of a manual request for a token will depend on whether the priority level of the request is greater (lower level number) than the priority level of the existing token, or less. (Other comparisons are possible.)

Section: System

Default: ControlTokenManualStealOption = 0

*No restart required (Settings.Dynamic property)

Possible values:

0 | Never
1 | Always
2 | If request level priority > token level priority (lower number / higher priority takes precedence)
3 | If request level priority >= token level priority
4 | If request level priority < token level priority
5 | If request level priority <= token level priority
6 | If request level priority == token level priority
7 | If request level priority != token level priority


ControlTokenMaxAge

Not set by default, meaning that there is no maximum age for Control Tokens.

If set to a number (measured in seconds), Control Tokens will be released automatically when that age is reached.

Section: System

Default: ControlTokenMaxAge =

*No restart required (Settings.Dynamic property)


ControlTokenMonitorTime

The Control Token Manager will check its list of tokens and requests every time either list changes (including both additions and removals). The check will ensure that it is up to date and determine whether any token or request holders have been lost and should therefore be considered stale and therefore released (tokens) or denied (requests).

In addition to token activity triggering this check, the Control Token Manager will check its dictionary at a rate determined by this property, defaulting to one hour (3600 seconds).

Section: System

Default: ControlTokenMonitorTime = 3600

Related Properties:

ControlTokenEnableOwnerMonitor

ControlTokenOwnerHeartbeat

ControlTokenPendingRequestStaleTime

ControlTokenStaleTokenTime


ControlTokenOwnerHeartbeat

Sets the frequency with which tokens and token request owners send an update to the token server to indicate that they are still connected. If a token or request owner is silent for ControlTokenStaleTokenTime or ControlTokenPendingRequestStaleTime seconds, it is assumed to have gone "stale".

This addresses the situation where a token owner shuts down without signing out and without releasing the tokens they hold. (For example, a workstation crash.) After a configurable length of time, those tokens or requests will be released.

Section: System

Default: ControlTokenOwnerHeartbeat = 30

Related Properties:

ControlTokenEnableOwnerMonitor

ControlTokenMonitorTime

ControlTokenPendingRequestStaleTime

ControlTokenStaleTokenTime


ControlTokenOwnerMode

Controls the mode of Control Token ownership according to the following possible values. If the related property, ControlTokenCanOnlyRemoveOwnToken, is set to 1 then users may not be able to release tokens that they created, depending on the value of this property.

0 -> Session ID ownership

Users will only own tokens that have been applied during a given session, where "session" means a unique sign-in. If the user also signs in at a different workstation or via a thin client, that counts as a different session and they will not own the tokens from the first session. Further, if tokens are not configured to release automatically when the user signs out, then the act of signing out and signing back in will mean that the user no longer owns the original Control Tokens because those belong to the earlier session, not directly to the user.

1 - > Account ID ownership

This is the most straightforward ownership mode. Ownership is defined by the account id that requested the token. If the same user is logged into several machines their ownership of the Control Tokens extends across all machines.

2 -> Machine ID ownership

In this mode, ownership is defined by the machine ID. This is useful way to segregate release permissions based on physical workstations.

3 -> Custom Hook ownership

Ownership is defined by a custom hook that must be written by the customer, ControlTokenIsOwnerHook.SRC.

Creation of a custom hook is an advanced scripting task. Details are provided in Custom Ownership Mode for Control Tokens.

Section: System

Default: ControlTokenOwnerMode = 1

*No restart required (Settings.Dynamic property)


ControlTokenPendingRequestStaleTime

Sets the length of time after which VTScada determines a token to be stale when there are pending requests for that token. Defaults to one minute.

If there are no requests for the token, the time until release is set by ControlTokenStaleTokenTime, which also sets the stale time for all requests.

Has no effect unless ControlTokenEnableOwnerMonitor is set to 1.

Section: System

Default: ControlTokenPendingRequestStaleTime = 60

Related Properties:

ControlTokenEnableOwnerMonitor

ControlTokenMonitorTime

ControlTokenOwnerHeartbeat

ControlTokenStaleTokenTime


ControlTokenRequestMaxAge

Not set by default, meaning that there is no maximum age for Control Token Requests.

If set to a number (measured in seconds), Control Token Requests will be denied (and therefore deleted) automatically when that age is reached.

Section: System

Default: ControlTokenRequestMaxAge =

*No restart required (Settings.Dynamic property)


ControlTokensEnabled

This can be set globally as an application property for the entire system (tag tree) or it can be set locally as a property of a Context tag (or user-defined type derived from a Context tag), affecting only specific parts of the tag tree.

Section: System

Default: ControlTokensEnabled = 0

*No restart required (Settings.Dynamic property)


ControlTokenStaleTokenTime

Sets the length of time after which VTScada determines a token to be stale when there are no pending requests for that token. This interval also applies separately to all token requests. Defaults to one day.

If there are requests for the token, the time until it is determined to be stale is set by ControlTokenPendingRequestStaleTime.

Has no effect unless ControlTokenEnableOwnerMonitor is set to 1.

Section: System

Default: ControlTokenStaleTokenTime = 86400

Related Properties:

ControlTokenEnableOwnerMonitor

ControlTokenMonitorTime

ControlTokenOwnerHeartbeat

ControlTokenPendingRequestStaleTime


Data Diode Properties

Variables in this section relate to VTScada Data Diode features

Refer to the side menu for the listing of properties in this section.


DataDiodeClientDisconnectTimeout

Specifies the seconds to wait for data on the receiving machine before disconnecting the socket. The value must be greater than the value of DataDiodePublisherPingInterval on the sending machine.

Will use no value less than 30. Defaults to 30.

Section: System

Default: DataDiodeClientDisconnectTimeout = 30

*No restart required (Settings.Dynamic property)


DataDiodeClientMaxLogAge

Defines the number of seconds to wait before forcing the Data Diode Client log out to the hard drive.

Defaults to 1 week represented in seconds.

Section: System

Default: DataDiodeClientMaxLogAge = 604800

*No restart required (Settings.Dynamic property)


DataDiodeClientMaxLogFiles

Defines the maximum number of Data Diode Client logs that will be stored on the hard drive.

Section: System

Default: DataDiodeClientMaxLogFiles = 20

*No restart required (Settings.Dynamic property)


DataDiodeClientMaxPacketNum

The total number of packets that the Data Diode Client can buffer. Each packet is up to 65535 bytes.

Section: System

Default: DataDiodeClientMaxPacketNum =

*No restart required (Settings.Dynamic property)


DataDiodeClientTraceInterval

Defines the number of seconds to wait before forcing the Data Diode Client log out to the hard drive.

Defaults to 1 day represented in seconds.

Section: System

Default: DataDiodeClientTraceInterval = 86400

*No restart required (Settings.Dynamic property)


DataDiodeClientTraceMax

Maximum number of entries in the Data Diode Client circular trace buffer

Defines the number of Data Diode Client log entries that will be held internally before writing the log out to the hard drive.

Section: System

Default: DataDiodeClientTraceMax = 1000

*No restart required (Settings.Dynamic property)


DataDiodePublisherFailoverCount

Number of communication failures to tolerate before initiating a soft failover (trying from another server).

Section: System

Default: DataDiodePublisherFailoverCount = 5

*No restart required (Settings.Dynamic property)


DataDiodePublisherMaxLogAge

Defines the number of seconds to wait before forcing the Data Diode Publisher log out to the hard drive.

Defaults to 1 week represented in seconds.

Section: System

Default: DataDiodePublisherMaxLogAge = 604800

*No restart required (Settings.Dynamic property)


DataDiodePublisherMaxLogFiles

Defines the maximum number of Data Diode Publisher logs that will be stored on the hard drive.

Section: System

Default: DataDiodePublisherMaxLogFiles = 20

*No restart required (Settings.Dynamic property)


DataDiodePublisherMaxQSize

The maximum number of bytes that Data Diode Publisher can buffer in the publish queue. If this number is exceeded, Data Diode Publisher will pause.

Defaults to 64 MB.

Section: System

Default: DataDiodePublisherMaxQSize =

*No restart required (Settings.Dynamic property)


DataDiodePublisherPingInterval

Specifies the time that a socket can have no data transmitted before a "ping" packet will be sent to the receiving machine to determine that the connection it still good.

Will use no value less than 10. Defaults to 10.

Section: System

Default: DataDiodePublisherPingInterval = 10

*No restart required (Settings.Dynamic property)


DataDiodePublisherPortConnErrorDelay

The number of seconds for the Data Diode Publisher to wait after a port error before trying to connect again

Section: System

Default: DataDiodePublisherPortConnErrorDelay =

*No restart required (Settings.Dynamic property)


DataDiodePublisherSendInterval

The number of seconds for the Data Diode Publisher to wait before sending the next packet. This is used to calibrate the output from the publisher for the client; Avoid exceeding the client's processing ability.

Section: System

Default: DataDiodePublisherSendInterval =

*No restart required (Settings.Dynamic property)


DataDiodePublisherTraceInterval

Defines the number of seconds to wait before forcing the Data Diode Publisher log out to the hard drive.

Defaults to 1 day represented in seconds.

Section: System

Default: DataDiodePublisherTraceInterval = 86400

*No restart required (Settings.Dynamic property)


DataDiodePublisherTraceMax

Maximum number of entries in the Data Diode Publisher circular trace buffer.

Defines the number of Data Diode Publisher log entries that will be held internally before writing the log out to the hard drive.

Section: System

Default: DataDiodePublisherTraceMax = 1000

*No restart required (Settings.Dynamic property)


HistorianPublisherManagerMaxLogAge

Defines the number of seconds before log files on the hard drive are deleted.

Do not let the service publish trace logs get any older than one week (default).

Section: System

Default: HistorianPublisherManagerMaxLogAge = 604800

*No restart required (Settings.Dynamic property)


HistorianPublisherManagerMaxLogFiles

Max number of service publish trace logs.

Defines the maximum number of publish manager log that will be stored on the hard drive.

Section: System

Default: HistorianPublisherManagerMaxLogFiles = 20

*No restart required (Settings.Dynamic property)


HistorianPublisherManagerTraceInterval

Save the service publish trace files at this interval: once per day

Defines the number of seconds to wait before forcing the log out to the hard drive. Defaults to the equivalent of one day.

Section: System

Default: HistorianPublisherManagerTraceInterval = 86400

*No restart required (Settings.Dynamic property)


HistorianPublisherManagerTraceMax

Maximum number of entries in the service publish circular trace buffer.

Defines the number of publish manager log entries that will be held internally before writing the log out to the hard drive.

Section: System

Default: HistorianPublisherManagerTraceMax = 1000

*No restart required (Settings.Dynamic property)


HistorianPublishManagerCriticalDiskSpace

The maximum amount of disk space, measured in MB, that VTScada will use for storing publish state files. Futher writes are disabled when this size is reached.

Section: System

Default: HistorianPublishManagerCriticalDiskSpace = 10000

*No restart required (Settings.Dynamic property)


HistorianPublishManagerFlushInterval

Minimum interval, in seconds, between service publish bursts.

Section: System

Default: HistorianPublishManagerFlushInterval = 2

*No restart required (Settings.Dynamic property)


HistorianPublishManagerMaxPendingRecords

The maximum number of historian service functionality records to send in one publication.

Section: System

Default: HistorianPublishManagerMaxPendingRecords = 300

*No restart required (Settings.Dynamic property)


HistorianPublishManagerMaxStateNum

The maximum number of publish state files that will be stored on the hard drive.

Section: System

Default: HistorianPublishManagerMaxStateNum = 30

*No restart required (Settings.Dynamic property)


HistorianPublishManagerSyncInterval

The minimum number of seconds between service publish state synchronizations.

Section: System

Default: HistorianPublishManagerSyncInterval = 60

*No restart required (Settings.Dynamic property)


Display Manager Properties

Variables in this section relate to the Display Manager.

Example: If you want your application to be inside a standard Windows window, (i.e. a resizable window with a title bar and control buttons) use the following settings:

DispMgrResizable = 1
DispMgrFullScreen = 0
DispMgrMinMaxDisabled = 0

Refer to the side menu for the listing of properties in this section.


AllowedLanguages

A list of the languages (from those available in an application) that will be available for selection in the Languages page of the Application Configuration dialog.

Refer to notes in Languages.

Section: Layer

Default: AllowedLanguages = EN

*No restart required (Settings.Dynamic property)


AppTheme

Added to Settings.Dynamic upon selecting a color theme other than the default.

This property holds the name of the selected color theme for an application. Theme names and their associated color definition are specified in your application's Setup.INI file.

Section: Layer

Default: (No default. Undefined until a theme is chosen.)


AutoCommitInterval

Sets the time interval, measured in seconds, of automated commits done while the Idea Studio is open.

Section: System

Default: AutoCommitInterval = 10800

*No restart required (Settings.Dynamic property)


AutoOpenIdeaStudio

Automatically opens the Idea Studio when a user having configuration privileges logs into an application.

Section: System

Default: AutoOpenIdeaStudio = 0

*No restart required (Settings.Dynamic property)


BitmapDirExt

Controls whether the directory for the images displayed in the Select Bitmap dialog (which is opened when you click the Image palette in the Idea Studio) will be shown in the title bar of the dialog, with the name and extension for each displayed image file shown beneath the image.

Section: System

Default: BitmapDirExt = 0

*No restart required (Settings.Dynamic property)


BMPath

Sets the path to the root folder for all images for use in the application. (For example, images selected using the Bitmap tool, or images selected using the Image Change widget for digital input tags.)

You must specify an existing directory. VTScada does not automatically generate a new directory based on the specified path.

Section: System

Default: BMPath = Bitmaps\

*Restart Required (Settings.Startup property)


DialogMoveTime

This variable sets the time to wait before saving a dialog's new position.

Section: System

Default: DialogMoveTime = 0.5

*No restart required (Settings.Dynamic property)


DisablePageSnapShotting

If set to 1 (true), snapshots views of pages will not be created as you navigate away from the page.
If pages are especially complex, setting this to 1 can significantly speed navigation between pages.

Defaults to 0 (false) for backward-compatibility..

Section: System

Default: DisablePageSnapShotting = 0

*No restart required (Settings.Dynamic property)


DisplayManagerTitle

Sets the title of the application as displayed beside the logo in the window title bar and also on the Windows task bar.

If not set, the application name is used.

Section: System

Default: DisplayManagerTitle =

*No restart required (Settings.Dynamic property)


DispMgrAspectRatio

Constrain the aspect ratio of a page window when users are changing the window size. With DispMgrAspectRatio set to 1 the ratio of the width to height will not change.

Section: System

Default: DispMgrAspectRatio = 0

*No restart required (Settings.Dynamic property)


DispMgrBMPMarginBottom

Sets the width of the bottom margin for the background image of a page.

Related Variables: DispMgrBMPMarginBottom DispMgrBMPMarginLeft |DispMgrBMPMarginLeft DispMgrBMPMarginRight |DispMgrBMPMarginsWin |DispMgrBMPMarginTop

Section: System

Default: DispMgrBMPMarginBottom = 0

*No restart required (Settings.Dynamic property)


DispMgrBMPMarginLeft

Sets the width of the left margin for the background image of a page

Related Variables: DispMgrBMPMarginBottom |DispMgrBMPMarginLeft DispMgrBMPMarginRight |DispMgrBMPMarginsWin |DispMgrBMPMarginTop

Section: System

Default: DispMgrBMPMarginLeft = 0

*No restart required (Settings.Dynamic property)


DispMgrBMPMarginRight

Sets the width of the right margin for the background image of a page.

Related Variables: DispMgrBMPMarginBottom | DispMgrBMPMarginLeft |DispMgrBMPMarginLeft DispMgrBMPMarginsWin |DispMgrBMPMarginTop

Section: System

Default: DispMgrBMPMarginRight = 0

*No restart required (Settings.Dynamic property)


DispMgrBMPMarginsWin

Sets all four margins around a background image in a windowed page.

Related Variables: DispMgrBMPMarginBottom | DispMgrBMPMarginLeft |DispMgrBMPMarginLeft DispMgrBMPMarginRight |DispMgrBMPMarginsWin DispMgrBMPMarginTop

Section: System

Default: DispMgrBMPMarginsWin = 0

*No restart required (Settings.Dynamic property)


DispMgrBMPMarginTop

Sets the width of the top margin around the background image of a page.

Related Variables: DispMgrBMPMarginBottom | DispMgrBMPMarginLeft |DispMgrBMPMarginLeft DispMgrBMPMarginRight |DispMgrBMPMarginsWin

Section: System

Default: DispMgrBMPMarginTop = 0

*No restart required (Settings.Dynamic property)


DispMgrDateFormat

Specify how the date is to display in the upper corner of the VTScada title bar. The value may use any of date formatting codes, date formatting strings or phrase identifier keys within the default languages file. (Date Formatting Codes, Date Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: DispMgrDateFormat = DateFmtMonthDay

*No restart required (Settings.Dynamic property)


DispMgrExtendedDesktop

For use only when DispMgrHoriz and DispMgrVert are in use to obtain multiple displays.

When used in conjunction with DispMgrHoriz and DispMgrVert to define an array of monitors and respective Display Manager instances, this supports the Windows extended desktop mode for use with multiple monitors. This means that a special graphics card is not required to support multi-monitor Display Manager instances.

Note the following:

  • All monitors must be set to the same display resolution (e.g. 1920x1200).
  • The layout defined byDispMgrHoriz andDispMgrVert must match the layout defined using the Windows display settings
  • The top-left monitor must be set in Windows as the primary monitor.
  • Normally, correct configuration would involve not setting DispMgrWidth and DispMgrHeight, and would require DispMgrTitleBorder = 0. If you insist on setting DispMgrTitleBorder to 1, DispMgrWidth and DispMgrHeight must be set to the actual resolution of the monitor, minus the Windows title bar height.
  • This configuration covers the Windows task bar.

  • This feature is not intended to have any impact on thin clients, including the VIC.

Section: System

Default: DispMgrExtendedDesktop =

*No restart required (Settings.Dynamic property)


DispMgrFullScreen

If set to 1 (true), the Display Manager displays in full screen mode. No Windows title bar is present.

DispMgrWidth and DispMgrHeight height take precedence over DispMgrFullScreen. If these settings are in use, DispMgrFullScreen will not work.

Section: System

Default: DispMgrFullScreen = 1

*No restart required (Settings.Dynamic property)


DispMgrHeight

Sets the height (vertical) of the Display Manager in pixels. If set to invalid (default), DispMgrHeight uses the VStatus(Self(),27) call to determine the default height of the Display Manager based on the video board and screen characteristics of your workstation.

This setting applies to the page area, not the entire VTScada application. Borders, scroll bars and the title bar must all be accounted for in addition to the DispMgrHeight value.

The border of a window can vary in width depending on the value set for your Active Window Border Size (found in the advanced properties of the Windows Desktop Properties: Appearance) If set to 1, the border will be 4 pixels around the window. Each additional number in the setting adds one pixel. Thus, if your screen resolution is set to 1024x768 and you set the DispMgrHeight to 768, the page will not fit the window, since the page height will exceed the available space by a distance equivalent to the width of two borders, plus the title bar, plus the horizontal scroll bar, if visible.

As a guideline, the DispMgrHeight should be set at least 60 pixels less than the current screen height.

Related Variables: To set the width of the Display Manager, use DispMgrWidth.

This variable takes precedence over setting DispMgrFullScreen = 1.

Section: System

Default: DispMgrHeight =

*No restart required (Settings.Dynamic property)


DispMgrHidden

EnableShowHide must be set to 1.

This property is set only in combination with a workstation name (that is, in a WorkstationSettings file). If EnableShowHide is 1, the application will be hidden from view while running.

Do not set this property without a Workstation name unless your intention is for the application to be hidden on all workstations while running. You are strongly advised to change the property only by using the Toggle Visibility icon in the VAM. Doing so will ensure that the change affects only the current workstation.

Section: Layer

Default: DispMgrHidden = 0

*No restart required (Settings.Dynamic property)

Related properties:

EnableShowHide

LogOffUponHide


DispMgrHoriz

Use to tile multiple display windows on the screen. DispMgrHoriz sets the number of pages to display horizontally.

Related properties: DispMgrVert, DispMgrExtendedDesktop

The property, DispMgrResizable, is treated as 0 (false) when using multiple display windows with DispMgrHoriz, DispMgrVert

Both the DispMgrHoriz and the DispMgrVert variables must be set to a numeric value in order for the Display Manager to tile multiple windows. Setting only one of these variables will have no effect.

To stretch your desktop across two or more monitors, you must also configure the display resolution in the Windows™ control panel. This option is not available to all graphics cards.

Section: System

Default: DispMgrHoriz =

*No restart required (Settings.Dynamic property)


DispMgrMinHeight

Sets a minimum height in pixels for a window when set to a value greater than 0.

Users will not be able to change the window height to a size less than the value of this variable.

Section: System

Default: DispMgrMinHeight =

*No restart required (Settings.Dynamic property)


DispMgrMinMaxDisabled

Controls the presence of minimize and maximize buttons in the Windows title bar of the Display Manager if the title bar is visible (DispMgrFullScreen not set to 1).

If set to 1 (true), minimize and maximize buttons are not present in the Windows title bar.

Section: System

Default: DispMgrMinMaxDisabled = 0

*No restart required (Settings.Dynamic property)


DispMgrMinWidth

Sets a minimum width for a window when set to a value greater than 0. Users will not be able to change the window width to a size less than the value of this variable.

Section: System

Default: DispMgrMinWidth =

*No restart required (Settings.Dynamic property)


DispMgrPageStyle

Controls the page style characteristics of a full screen VTScada page.

Section: System

Default: DispMgrPageStyle = 16777215

*No restart required (Settings.Dynamic property)

This is a bitwise variable with the following meanings for the bits:

Value | Constant | Meaning
0x000001 | PSTTB | Show title bar
0x000002 | PSBMP | Deprecated. Show title bar bitmap
0x000004 | PSLGN | Show title bar logon button
0x000008 | PSGFX | Show title bar graphic editor {Btn}
0x000010 | PSDTE | Show title bar date & time
0x000020 | PSIND | Show title bar alarm indicator
0x000040 | PSNOT | Show title bar page notes buttons
0x000080 | PSPRN | Show title bar print button
0x010000 | PSTAG | Show title bar tag browser button
0x020000 | PSAPP | Show title bar application properties button
0x040000 | PSFBB | Show title bar forward/back buttons
0x080000 | PSULI | Show title bar unlinked indicator
0xFF00FF | PSTTT | Show all title bar decorations
0x000100 | PSMBR | Show task bar
0x000200 | PSMNU | Show list menu button and menu
0x000400 | PSMPB | Show task bar page buttons
0x000800 | PSMFB | Deprecated. Show task bar "<" and ">" buttons
0x001000 | PSMPM | Show task bar add/remove buttons
0x002000 | PSMHD | Deprecated. Hold page button changes target
0x004000 | PSTMN | Show tile menu button and menu
0x00FF00 | PSMMM | Show all menu bar decorations

Related information:

DispMgrWPageStyle


DispMgrResizable

Controls whether users can resize the Display Manager when in windowed mode (i.e. when the DispMgrFullScreen variable is set to 0).

Set to 0 to disable resizing or 1 to allow.

Section: System

Default: DispMgrResizable = 1

Related Variables:

DispMgrFullScreen must be set to 0 in order for DispMgrResizable to take effect.

DispMgrHeight, DispMgrWidth, BrowserHeight, and BrowserWidth variables will apply to the Display Manager only until the window has been re-sized, after which the Display Manager will retain the newly adjusted size.

If DispMgrMinMaxDisabled is set to 1, the Display Manager will not have Windows minimum and maximize buttons, but the window will be resizable by dragging its borders.

The property, DispMgrResizable, is treated as 0 (false) when using multiple display windows with DispMgrHoriz, DispMgrVert


DispMgrStartupPageX

DispMgrStartupPageX is for multi-monitor setups. Where X is the index number of the monitor and the Value is the name of the page to open on start-up. Insert one property per monitor to be configured. When this property is enabled, the startup page radio buttons in the Application Configuration menu will become disabled.

Insert properties via Application Configuration > Edit Properties > Advanced

Section: System

Default: DispMgrStartupPageX =

*No restart required.

Related information:

Add a Property


DispMgrTimeFormat

Specifies the format of the time displayed in the Display Manager's upper right corner. The default format for the time will look similar to: "1:38 AM". The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file. (Time Formatting Codes, Time Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: DispMgrTimeFormat = TimeFmtHM12Hour

*No restart required (Settings.Dynamic property)


DispMgrTitleBorder

When set to 0, disables the title bar and borders.

When set to 1 or when missing altogether, the title bar and borders are unaffected.

Section: System

Default: DispMgrTitleBorder = 1

*No restart required (Settings.Dynamic property)


DispMgrVert

Use to tile multiple display windows on the screen. DispMgrVert sets the number of pages to display vertically.

Related property: DispMgrHoriz

The property, DispMgrResizable, is treated as 0 (false) when using multiple display windows with DispMgrHoriz, DispMgrVert

Both the DispMgrHoriz and the DispMgrVert variables must be set to a numeric value in order for the Display Manager to tile multiple windows. Setting only one of these variables will have no effect.

To stretch your desktop across two or more monitors, you must also configure the display resolution in the Windows™ control panel. This option is not available to all graphics cards.

Section: System

Default: DispMgrVert =

*No restart required (Settings.Dynamic property)


DispMgrWidth

Sets the width of the Display Manager in pixels. If set to invalid (default), DispMgrWidth uses the VStatus(Self(), 26) call to determine the default width of the Display Manager based on the video board and screen characteristics of your workstation.

This setting applies to the page area, not the entire VTScada application. Borders, scroll bars and the title bar must all be accounted for in addition to the DispMgrWidth value.

The border of a window can vary in width depending on the value set for your Active Window Border Size (found in the advanced properties of the Windows Desktop Properties: Appearance) If set to 1, the border will be 4 pixels around the window. Each additional number in the setting adds one pixel. Thus, if your screen resolution is set to 1024x768 and you set the DispMgrWidth to 1024, the page will not fit the screen, since the page width will exceed the available space by a distance equivalent to the width of two borders, plus the vertical scroll bar, if visible.

As a guideline, the DispMgrWidth should be set at least 8 pixels less than the current screen width.

Related Variables: To set the height of the Display Manager, use DispMgrHeight.

This variable takes precedence over setting DispMgrFullScreen = 1.

Section: System

Default: DispMgrWidth =

*No restart required (Settings.Dynamic property)


DispMgrWPageStyle

Controls the page style characteristics of a windowed VTScada page.

Section: System

Default: DispMgrWPageStyle = 0

*No restart required (Settings.Dynamic property)

This is a bitwise variable with the following meanings for the bits:

Value | Constant | Meaning
0x000001 | PSTTB | Show title bar
0x000002 | PSBMP | Deprecated. Show title bar bitmap
0x000004 | PSLGN | Show title bar logon button
0x000008 | PSGFX | Show title bar graphic editor {Btn}
0x000010 | PSDTE | Show title bar date & time
0x000020 | PSIND | Show title bar alarm indicator
0x000040 | PSNOT | Show title bar page notes buttons
0x000080 | PSPRN | Show title bar print button
0x010000 | PSTAG | Show title bar tag button
0x020000 | PSAPP | Show title bar app. properties button
0x040000 | PSFBB | Show title bar forward/back buttons
0x080000 | PSULI | Show title bar unlinked indicator
0xFF00FF | PSTTT | Show all title bar decorations
0x000100 | PSMBR | Show task bar
0x000200 | PSMNU | Show menu button and menu
0x000400 | PSMPB | Show task bar page buttons
0x000800 | PSMFB | Deprecated. Show task bar "<" and ">" buttons
0x001000 | PSMPM | Show task bar add/remove buttons
0x002000 | PSMHD | Deprecated. Hold page button changes target
0x00FF00 | PSMMM | Show all menu bar decorations

Related information:

DispMgrPageStyle


DispMgrX

Sets the default X coordinate (horizontal) of the Display Manager's upper left corner if the Display Manager is not in full screen mode.

Related Variables: To set the Y coordinate of the Display Manager's upper left corner, use the DispMgrY variable.

To set the height of the Display Manager, use the DispMgrHeight and DispMgrWidth variables.

Section: System

Default: DispMgrX = 0

*No restart required (Settings.Dynamic property)


DispMgrY

Sets the default Y coordinate (vertical) of the Display Manager's upper left corner if the Display Manager is not in full screen mode.

Related Variables: To set the X coordinate of the Display Manager's upper left corner, use the DispMgrX DispMgrYvariable.

To set the height of the Display Manager, use the DispMgrHeight and DispMgrWidth variables.

Section: System

Default: DispMgrY = 0


LinearIndicatorOverage

Used by linear indicator and meter widgets. If the value of the linked tag exceeds the scaled display of the widget, an overage of this percentage is allowed.

Used to indicate that the value is out of range (not at either limit of the widget range) while restricting the size of the resulting display.

Section: System

Default: LinearIndicatorOverage = 10

*No restart required (Settings.Dynamic property)

Related information:

RadialIndicatorOverage


LSAlarmColor

Lift Station Alarm Color. The color of alarm text in Lift Station I/O widgets.

Section: System

Default: LSAlarmColor = <FF4040>

*No restart required (Settings.Dynamic property)


LSDefaultTheme

Default theme to use for site and station graphics.

Section: System

Default: LSDefaultTheme = Grey

*No restart required (Settings.Dynamic property)


MaintainAspectRatio

Used in combination withScaleDisplayContent. If set to 1 (true), then pages will maintain their aspect ratio when stretched.

Section: System

Default: MaintainAspectRatio = 1

*No restart required (Settings.Dynamic property)


Name

Holds the name (display name) of the application. Changing the name makes no fundamental difference to an application.

Section: Application

Default: Name = New Application

*No restart required (Settings.Dynamic property)


NumHistoryItems

Limits the number of items shown in the Recent Pages area of the tile menu.

Section: System

Default: NumHistoryItems = 10

*No restart required (Settings.Dynamic property)


RadialIndicatorOverage

Used by radial indicator and meter widgets. If the value of the linked tag exceeds the scaled display of the widget, an overage of this percentage is allowed.

Used to indicate that the value is out of range (not at either limit of the widget's range) while preventing a "wrap around" if the value is excessively outside the range.

Section: System

Default: RadialIndicatorOverage = 10

*No restart required (Settings.Dynamic property)

Related information:

LinearIndicatorOverage


PageChangeUpdateSamePopup

Relevant when a Page Button widget or Page Hotbox widget is drawn on a windowed (pop-up) page, and that widget calls the same page. You might create this configuration if you have a parameterized page and want to switch parameter values while staying within the pop-up. In this configuration, you can use the PageChangeUpdateSamePopup parameter to control whether another instance of the page is created, or the current page is replaced.

PageChangeUpdateSamePopup = 0

A new instance of the page will be opened as a pop-up.

PageChangeUpdateSamePopup = 1

The existing pop-up page will remain open and its parameters will be updated. (Default)

Section: System

Default: PageChangeUpdateSamePopup = 1

*No restart required (Settings.Dynamic property)


PageNoteDateFormat

Set the date format to display on Page Notes. The value may use any of date formatting codes, date formatting strings or phrase identifier keys within the default languages file. (Date Formatting Codes, Date Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: PageNoteDateFormat = DateFmtFullWrittenWithDOW

*No restart required (Settings.Dynamic property)


PageNoteTimeFormat

Set the time format to display on Page Notes. The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file. (Time Formatting Codes, Time Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: PageNoteTimeFormat = TimeFmtHM12Hour

*No restart required (Settings.Dynamic property)


PageShuffleDelay

Viewing: Reference > Property Reference > Display Manager Properties > PageShuffleDelay

Concepts:

Page Shuffling

Reference:

PageShuffleEnable

PageShuffleList

PageShufflePauseDuration

PageShuffleRealms

PageShuffleDelay

Controls the length of time each page is displayed when shuffling is enabled. Either a single delay to display all pages in PageShuffleList or a comma-separated list of delays to apply to each page (in which case it must contain the same number of entries as PageShuffleList).

(Where "shuffle" means "display in sequence automatically with a specified delay")

Section: System

Default: PageShuffleDelay =

*No restart required (Settings.Dynamic property)

Example:

PageShuffleDelay = 30,45,30

- length of time to show each page


PageShuffleEnable

Viewing: Reference > Property Reference > Display Manager Properties > PageShuffleEnable

Concepts:

Page Shuffling

Reference:

PageShuffleDelay

PageShuffleList

PageShufflePauseDuration

PageShuffleRealms

PageShuffleEnable

Controls whether automatic page shuffling is enabled. Only specified pages will shuffle.

(Where "shuffle" means "display in sequence automatically with a specified delay")

Section: System

Default: PageShuffleEnable = 0

*No restart required (Settings.Dynamic property)


PageShuffleList

Viewing: Reference > Property Reference > Display Manager Properties > PageShuffleList

Concepts:

Page Shuffling

Reference:

PageShuffleDelay

PageShuffleEnable

PageShufflePauseDuration

PageShuffleRealms

PageShuffleList

Comma-separated list of page modules to cycle between. Do not specify page titles. This list must contain the declared module name for each page, which can be obtained from AppRoot.SRC or (in most cases) from the name of the source code file holding that page.

For example, the Overview page is declared as Overview in AppRoot.SRC and is also the name of the source code file:

  [ (PAGES)
    Overview Module "Pages\Overview.SRC";
  ]

(Code snippet from AppRoot.SRC of most applications)

Section: System

Default: PageShuffleList =

*No restart required (Settings.Dynamic property)

Example:

PageShuffleList = Page1,Page2("TagName"),Page3

- where Page2 has its first parameter set to TagName


PageShufflePauseDuration

Viewing: Reference > Property Reference > Display Manager Properties > PageShufflePauseDuration

Concepts:

Page Shuffling

Reference:

PageShuffleDelay

PageShuffleEnable

PageShuffleList

PageShuffleRealms

PageShufflePauseDuration

Amount of time to pause page shuffling when mouse or keyboard actions are detected.

(Where "shuffle" means "display in sequence automatically with a specified delay")

Section: System

Default: PageShufflePauseDuration = 60

*No restart required (Settings.Dynamic property)

Example:

PageShufflePauseDuration: 60

- pause the shuffling for 1 minute if the mouse is moved


PageShuffleRealms

Viewing: Reference > Property Reference > Display Manager Properties > PageShuffleRealms

Concepts:

Page Shuffling

Reference:

PageShuffleDelay

PageShuffleEnable

PageShuffleList

PageShufflePauseDuration

PageShuffleRealms

In this context, "Realms" refers to Security Realms, not thin client realms.

Either a single realm name or a comma separated list of realms for which the shuffling is enabled. To add the logged off and non-realm users to the list add a blank entry after a comma at the end of the list. The order of the realms does not relate to the order of the PageShuffleList and PageShuffleDelay settings

(Where "shuffle" means "display in sequence automatically with a specified delay")

PageShuffleRealms is optional. If specified, it will work only when a user in the matching security realm is signed in.
If not specified, page shuffling applies to all realms.

Section: System

Default: PageShuffleRealms =

*No restart required (Settings.Dynamic property)

Example:

PageShuffleRealms = WEST

- only users in the WEST realm will see shuffling


ScaleDisplayContent

Controls whether the contents of the pages shown in the Display Manager should be stretched or shrunk to fit within the Display Manager's display area. Applies only to pages that have been configured to use the default.

If set to 1 (true), then the contents of the pages shown in the Display Manager are stretched or shrunk to fit within the Display Manager's display area.

Section: System

Default: ScaleDisplayContent = 0

*No restart required (Settings.Dynamic property)

Automated display scaling works reasonably well when enlarging the page. It cannot do as good a job when shrinking a display for a smaller screen. In particular, labels embedded within buttons or widgets are more likely to be truncated than scaled down.
Always design for the smallest screen that the application will be displayed upon. Further information is provided in Size Pages for Differing Screens


ShowUnlinkedIndicators

When set to 1 (true), an indicator will be shown on each unlinked tag widget.

Section: System

Default: ShowUnlinkedIndicators = 0

*No restart required (Settings.Dynamic property)


SiteDetailsWindowed

Controls the default behavior of whether a Site Details page will open full screen or in a pop-up window. Has no effect on pages that are set to "Always display in window" or "Never display in window".

  • When set to 1 (true), the details page will be displayed in a pop-up window unless the page is set to "Never display in a window".
  • When set to 0 (false), the site details page will open in the main window, unless the page is set to "Always display in a window".

Section: System

Default: SiteDetailsWindowed = 1

*No restart required (Settings.Dynamic property)


SlippyMapMaxZoomLevel

The maximum (closest in) zoom level allowed. On the default maps, this is close enough to see building outlines within a small number of city blocks.

Section: System

Default: SlippyMapMaxZoomLevel = 2

*No restart required (Settings.Dynamic property)


SlippyMapMinZoomLevel

The minimum (furthest out) zoom level allowed. On the default maps, this shows the entire planet, projected as a rectangle.

Section: System

Default: SlippyMapMinZoomLevel = 2

*No restart required (Settings.Dynamic property)


ThemedPageBGColor

Set the background color for the following pages:

  • Page Menu Page
  • Site Details Page
  • Site List Page (with map)
  • Station Page

Define the color using hexadecimal aRGB Closed A colour value, defined as four, two-digit hexadecimal values. Alpha - Red - Green - Blue. An Alpha value of FF is assumed if only the RGB values are provided. values, having the form <AARRGGBB> for alpha, red, green, blue.

Example:

ThemedPageBGColor = <FFFFD30C>

You must include the angle brackets. (The example color was chosen to be unmistakable, if not desirable.)

Section: System

Default: ThemedPageBGColor =

*No restart required (Settings.Dynamic property)


TitleLogoTarget

Sets the page that should be opened when an operator clicks the logo at the top of a page.

If using a parameterized page, then a list of parameters for the page can be provided as a comma-separated list in parentheses following the page name. Set the parameter list to Invalid if none should be provided.

You can disable the page navigation behavior of the title logo by setting this property to blank.

Section: System

Default: TitleLogoTarget = PageMenuPage(Invalid)

*No restart required (Settings.Dynamic property)


Editing and Debugging Properties

Variables in this section relate to code editing and debugging.

Refer to the side menu for the listing of properties in this section.


Language

Where dynamic language change support is provided, this should be set to the index of the current language (from an enumeration of the supported languages) whenever the language is changed. This provides a trigger for code that needs to rebuild message texts.

Usually set in the Languages page of the Application Configuration dialog.

Section: System

Default: Language = 0

*No restart required (Settings.Dynamic property)


NoModal

Allows most modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. dialogs to be made non-modal.

If set to invalid (as it is by default), then the application will default to the NoModal flag variable in Setup.INI (or its default if NoModal is not set in Setup.ini)

If set to 0 (false), then most modal dialogs are not made non-modal.

If set to 1 (true), then most modal dialogs are made non-modal.

Setting NoModal to other than its default can affect your application adversely if users are allowed to click outside of dialogs that were intended to be modal.

Section: System

Default: NoModal =

*No restart required (Settings.Dynamic property)


NoOpChangeDialog

Use to suppress the dialog that is displayed when a user attempts to make an operational change to a tag.

Is set to 0 (false), then the dialog is not suppressed (default).

If set to 1 (true), then the dialog is suppressed.

Section: System

Default: NoOpChangeDialog = 0

*No restart required (Settings.Dynamic property)


NVShowCheckFilesDlgCount

When more than this many NetworkValues files need to be checked, a dialog will be displayed so that the user knows that the system has not hung.

Section: System

Default: NVShowCheckFilesDlgCount = 10000

*No restart required (Settings.Dynamic property)


NVShowDialogs

If set to 1 (true) then the Network Values service will show dialogs on startup. The purpose of these dialogs is to let the operator know that the system is still working when there are a large number of files to check.

Section: System

Default: NVShowDialogs = 1

*No restart required (Settings.Dynamic property)


OnTop

Indicates whether the Debugger (as opposed to Source Debugger) should appear on top of all other screens.

If set to 0 (false), then the Debugger does not appear on top of all other screens (default).

If set to 1 (true), then the Debugger does appear on top of all other screens.

Section: System

Default: OnTop = 0

*No restart required (Settings.Dynamic property)


General Properties

Variables in this section relate to the application in general.

Refer to the side menu for the listing of properties in this section.


AppKeywords

This property must be inserted. It is not present in any layer by default.

Can be created by application developers who want their application to appear on a specific Application List within the VTScada Application Manager. The list will be created if it does not already exist. Use commas (without spaces) to make this application a member of multiple lists.

Section: System

Default: (no default)

*No restart required (Settings.Dynamic property)

Related Properties

Keywords


AutoActivate

Controls whether the application will activate automatically when VTScada starts.

Defaults to 0 (false).

Section: Application

Default: AutoActivate = 0

*No restart required (Settings.Dynamic property)


AutoOverrideOEMPages

Meant for use with OEM layer applications. Affects behavior in derived applications, not the application where this is set.

Controls whether derived applications will automatically override pages (by creating a local copy in the derived application) without informing the user or giving them the opportunity to choose whether to override or create a renamed of the page.

Defaults to 1 (TRUE) to maintain legacy behavior.

Section: System

Default: AutoOverrideOEMPages = 1

*No restart required (Settings.Dynamic property)

When set to 0 (FALSE), developers working in derived applications will see the following prompt upon opening the Idea Studio for any page that exists (and for which there is source code) in the OEM application.

If making a copy, you are strongly advised against making the copy's name match the original. Doing so will only lead to confusion as you try to keep track of which page is the original and which is the copy.


AutoStart

Controls whether the application will start automatically when VTScada starts. Before the application starts, VTScada will display a dialog, giving the user a chance to abort the startup. This dialog is shown for AutoStartDlgTimeout seconds (defaulting to 10). AutoStartDlgTimeout

Defaults to 0 (false).

Section: Application

Default: AutoStart = 0

*No restart required (Settings.Dynamic property)


DefaultExcelType

Sets the default for VTScada operations that create Excel files.

This can be changed to .xls if necessary, but the maximum number of columns will be reduced from 16384 to 255.

Section: System

Default: DefaultExcelType = .xlsx

*No restart required (Settings.Dynamic property)


DefaultMaxEmailSize

Sets the default value controlling the maximum size in bytes of incoming emails that VTScada will open.

Can be changed using the Alarms tab of the Edit Configuration page's basic mode.

Section: System

Default: DefaultMaxEmailSize = 100000

*No restart required (Settings.Dynamic property)


DoNotStart

When set to 1 (true) the application cannot be started. It can and will be activated when needed.

This property is commonly used to prevent an OEM layer from starting.

Unlike most other properties, this property applies only to the application where it is set. Preventing an OEM layer from starting does not cause applications built on that OEM layer to also not start.

Section: Application

Default: DoNotStart = 0

*No restart required (Settings.Dynamic property)

Related information:

HideFromVAM


DoNotSyncLayer

Relevant only for OEM layers. When set to 1, updates to the layer on one server will not be synchronized across other servers.

This property takes priority over SyncOEMLayers.

This property must be added to your OEM layer application if required. It is not included by default.

DoNoSyncLayer requires a full restart of VTScada, not just the application.

Section: Application

Default: No default / not set.

*Restart Required (Settings.Startup property)


FriendlyTagServiceNames

When set to 1, tag-related network services base their names on the human-readable tag names rather than the unique IDs of tags.

Note: Legacy applications created prior to version 10.2 will have service names that are based on Unique ID values. If FriendlyTagServiceNames is set to 0 or does not exist in your application, the application must be running in order to edit the server list and unique ID values must be used.

Section: Layer

Default: FriendlyTagServiceNames = 1

*Restart Required (Settings.Startup property)


HideFromVAM

Controls whether the application is visible in the VTScada Application Manager when loaded in the VAM's list. Set to 1 (true) to hide the application. OEM layers, which are not meant to be run, but which must be present in the VAM, are sometimes hidden from view.

Unlike most other properties, this property is local to the application where it is set. Hiding an OEM layer does not cause applications built on that OEM layer to also be hidden.

The application can be displayed again by adding it back into the VAM as an existing application.

Section: Application

Default: HideFromVAM = 1

*No restart required (Settings.Dynamic property)

Related information:

DoNotStart

HideVAM


Keywords

Do not edit. This workstation-specific property is maintained by the VAM.

"Keywords" applies to the application lists in the VTScada Application Manager (VAM) and define which list(s) contain this application. It is set when defining lists using the tools in the VAM.

Section: System

Default: Keywords =

*Restart Required (Settings.Startup property)

Related Properties

AppKeywords


LayerNetworkValuesDetailTracing

Set to 1 to enable debug tracing for LayerNetworkValues.

Do not leave on indefinitely

Section: Layer

Default: LayerNetworkValuesDetailTracing = 0

No restart required


LocalScopeSyntax

Must be set 1 (true) for the "." character to function as a scope operator.

  • Will default to 0 for legacy applications (those created prior to VTScada release 11.2).
  • Will default to 1 for new applications.

Section: Application

Default: LocalScopeSyntax = 1

*Restart Required (Settings.Startup property)

Use care if changing this property in a legacy application because (in rare cases) user-created code might include the dot as part of a variable name.


MaxSpeakToFileLength

Sets the maximum length of a phrase that will be accepted by the function, SpeakToFile, measured by the number of characters in that phrase.

Section: System

Default: MaxSpeakToFileLength = 1000

*No restart required (Settings.Dynamic property)


MapZoomTransitionThreshold

If more than this many sites are displayed on the current map, zoom operations will jump directly to the specified level rather than transition through intermediate levels.

Section: System

Default: MapZoomTransitionThreshold = 300

*No restart required (Settings.Dynamic property)


MaxNestedExpressionDepth

Sets 200 as the maximum number of function calls that can be included in a single expression. (Most commonly encountered when creating deeply nested IfElse expressions.)

If you encounter this limit, do not increase the maximum nested expression depth. Rather, look for ways to rewrite your code to avoided nested expressions (see following options).

Section: Layer

Default: MaxNestedExpressionDepth = 200

*Restart Required (Settings.Startup property)

Writing long "If Else - Else - Else ... " expressions is not efficient and can be avoided. To prevent excessively nested expressions, the property MaxNestedExpressionDepth limits you to 200 function calls (including IfElse) within a single expression. There is no need to test this limit, regardless of the complexity of your application.

Alternatives to nested IfElse structures:

A common task is to build a string based on the current value of a tag (or several tags). For this example, suppose that you need to build a message or address that varies with a tag's current state. A long and inefficient method might be to write:

[SomeTagName] == 0 ? "Message (or) Address 0"
                   :
[SomeTagName] == 1 ? "Message (or) Address 1"
                   :
[SomeTagName] == 2 ? "Message (or) Address 2"
                   :
 etc. for 100 or more messages...

There are alternatives:

Option 1

A much easier method is to use a CASE statement in steady state. All statements will execute, but only the result of the statement matching the requested index will be returned.

X = Case([SomeTagName],
     { 0 } "Message (or) Address 0",
     { 1 } "Message (or) Address 1",
     { 2 } "Message (or) Address 2",
     { etc });

Option 2

Another option is somewhat more complicated to create, but has the benefit that the messages are stored in application properties instead of code and therefore can be added to or edited by anyone with the Configuration privilege. It is not necessary to write more code when messages change or new messages are created.

1. Create a set of application properties for each situation:

 Situation0         = Message or Address 0
 Situation1         = Message or Address 1
 Situation2         = Message or Address 2
   (etc.)

2. Write an expression that uses the Variable function to concatenate the tag value onto the prefix "Situation" to return the appropriate property value.

 Variable(Concat("Situation",[<SomeTagName1>]))

No comparisons or If-Else statements are required. This single line of code can return any message that you have created. For more complicated situations, use Concat to build the appropriate property name or combine several values into one message or address.


NetworkValuesDetailTracing

Set to 1 to enable debug tracing for NetworkValues.

Do not leave on indefinitely

Section: System

Default: NetworkValuesDetailTracing = 0

*No restart required (Settings.Dynamic property)


OEMHelp

Defines the path to user-created documentation for use with SetHelp() function calls.

Section: System

Default: OEMHelp =

*No restart required (Settings.Dynamic property)

Related Information:

Custom Help Files - Examples and required preparation

HelpFile

SetHelp


SMSTextSubstitution

Replaces characters not expressed as single bytes in both ASCII and GSM 03.38 character sets. Some cell modems appear not to use the GSM 03.38 extension table when translating ASCII characters, excluding characters such as "|", "^", "[", "]", "~", "\" and the curly brackets VTS script uses as comment delimiters.

Section: System

Default: SMSTextSubstitution =

*No restart required (Settings.Dynamic property)


SyncOEMLayers

Set to 1 (true) to cause all OEM Layers for this application to synchronize their configuration using this layer's configuration server list.

It is often the case that an OEM layer will be distributed to multiple client sites, each with a different network layout. A server list in the OEM layer itself would be difficult or impossible to maintain, therefore it is best to use each dependent application's server list.

If 0 (false) then an OEM layer would need its own server list for configuration synchronization, or the update would need to be applied to each workstation individually. As a general rule, this property should be managed only in the top-most (aka. dependent) layer.

Section: Layer

Default: SyncOEMLayers = 1

*No restart required (Settings.Dynamic property)

Related Properties

DoNotSyncLayer


VAMIcon

Identifies the bitmap file (.BMP, .JPG or .PNG) that will be displayed beside the application name in the VTScada Application Manager.

If not set (default), the application's icon will use whatever was defined in the layer that it is based on. This will usually be the VTScada logo. Images larger than 38x20 pixels will be scaled to fit. In order for the icon to blend smoothly into the VAM, rather than appearing as a rectangle, any pixels in the image file that are not a part of the actual icon should be transparent.

Section: Application

Default: VAMIcon =

*No restart required (Settings.Dynamic property)

Related information:

Display Tab of the Edit Properties Page


Thin Client Server and Client Properties

Variables in this section relate to the VTScada Thin Client Server & clients

Refer to the side menu for the listing of properties in this section.


BrowserHeight

Measured in pixels. Sets the height for the VTScada Internet Client.

If unspecified (default), the window height is set automatically.

Section: System

Default: BrowserHeight =

*No restart required (Settings.Dynamic property)


BrowserWidth

Measured in pixels. Sets the width for the VTScada Internet Client.

If unspecified (default), the window width is set automatically.

Section: System

Default: BrowserWidth =

*No restart required (Settings.Dynamic property)


BrowserX

Specifies the X coordinate for the top left corner of a new VTScada Internet Client window.

Section: System

Default: BrowserX = 0

*No restart required (Settings.Dynamic property)


BrowserY

Specifies the Y coordinate for the top left corner of a new VTScada Internet Client window.

Section: System

Default: BrowserY = 0

*No restart required (Settings.Dynamic property)


Enable

A Boolean property controlling whether OpenID Connect authorizations are allowed. (The corresponding property to disallow username/password to a VTScada Thin Client Server is RemoteAuthMethodsDisallowed, within the <SECURITYMANAGER-ADMIN> section). This and other OIDC related properties are viewable only after enabling OIDC. See also OpenID Connect Authentication.

If set to 0, clients cannot connect to a VTScada Thin Client Server using OpenID Connect authorizations.

Default: Enable = 0

Section: <SecurityManager-OIDC>

Related information:

RemoteAuthMethodsDisallowed

Some sites may maintain two (or more) VTScada Thin Client Servers, where username/password logons are permitted to some but not others. To achieve this, create workstation-specific configuration files where RemoteAuthMethodsDisallowed is set to usernamepassword for one server but not another. An example is provided in the topic,Workstation-Specific Properties


RealmAreasExcludeInvalid

Used when Realm Filtering is in effect. When an application uses realm filtering, it is customary to configure one or more users that do not have a group membership and grant to these users viewing access to all areas. The variable RealmAreasExcludeInvalid controls whether tags that do not have any area defined will be included or excluded from view.

If RealmAreasExcludeInvalid is set to 1, then no user will be able to view tags that do not have an associated area.

If the area filter is set to include every area in the application, then the area filtering is considered to be disabled. In this case, tags with Invalid areas will be shown to the user even if RealmAreasExcludeInvalid is set to 0 (FALSE).

Section: System

Default: RealmAreasExcludeInvalid = 1


RemoteAuthMethodsDisallowed

Prevent the specified access method via VIC/MIC/Anywhere Client. Valid values include blank, oidc, usernamepassword, or a combination of oidc and usernamepassword separated by spaces. If both are specified (last option in the list) then no connection is possible.

(A corresponding property to disallow OpenID Connect authorizations is Enable, within the <SECURITYMANAGER-OIDC> section.)

If set to usernamepassword, clients cannot connect to a VTScada Thin Client Server using a standard username and password combination.

Section: <SecurityManager-Admin>

Default: RemoteAuthMethodsDisallowed =

*No restart required (Settings.Dynamic property)

Related information:

Enable

Some sites may maintain two (or more) VTScada Thin Client Servers, where username/password logons are permitted to some but not others. To achieve this, create workstation-specific configuration files where RemoteAuthMethodsDisallowed is set to usernamepassword for one server but not another. An example is provided in the topic,Workstation-Specific Properties


RootNamespace

If your applications makes use of realm-area filtering and if you allow remote access to the VTScada Thin Client Server then you must define a realm for super-user access and declare it in the RootNamespace property. Accounts that are not part of any security realm (super-users) will not have access to any Thin Client Server realm otherwise.

The value of RootNamespace must not match any defined security realm.

Section: System

Default: RootNamespace =


ShowDisplayAnywhere

If disabled (set to 0) the thin client landing page will not show an option to connect to the VTScada Anywhere Client.

Section: System

Default: ShowDisplayAnywhere =

*No restart required (Settings.Dynamic property)

Related information and properties:

Thin Client Landing Page Configuration

ShowDisplayVIC

ShowDisplayMobile

ShowDownloadStandalone


ShowDisplayMobile

If disabled (set to 0) the thin client landing page will not show an option to connect to the VTScada Mobile Internet Client.

Default: ShowDisplayMobile = 1

Section: System

*No restart required (Settings.Dynamic property)

Related information and properties:

Thin Client Landing Page Configuration

ShowDisplayVIC

ShowDisplayAnywhere

ShowDownloadStandalone


ShowDisplayVIC

If disabled (set to 0) the thin client landing page will not show an option to connect to the VTScada Internet Client.

Section: System

Default: ShowDisplayVIC = 1

*No restart required (Settings.Dynamic property)

Related information and properties:

Thin Client Landing Page Configuration

ShowDisplayAnywhere

ShowDisplayMobile

ShowDownloadStandalone


ShowDownloadStandalone

If disabled (set to 0) the thin client landing page will not show an option to download the standalone VTScada Internet Client (VTSX.exe).

Section: System

Default: ShowDownloadStandalone =

*No restart required (Settings.Dynamic property)

Related information and properties:

Thin Client Landing Page Configuration

ShowDisplayVIC

ShowDisplayAnywhere

ShowDisplayMobile


ThinClientDisclaimer

Specifies the name of an HTML file that will be displayed to operators connecting to the application via a thin client (VIC or Anywhere). If specified in an OEM layer application, the message will be used for all dependent applications unless locally overridden. You can find an example thin client disclaimer in ..\Examples\ExampleThinClientDisclaimer.html

The HTML file must be added to the application's version control system. Import File Changes Tool
This should be a complete HTML document. JavaScript content will not execute.

Section: Application

Default: ThinClientDisclaimer =

*No restart required (Settings.Dynamic property)


ThinClientFraming

Restricts the locations within which the thin client pages may be placed within an iframe.

Accepted values:

'none':

Quotes included, this specifies nothing may place the thin clients within an iframe.

'self':

Quotes included, this specifies only VTScada itself may place the thin client within an iframe. This requires protocol scheme and port numbers on the system to be identical.

A space separate list of hosts:

No quotes should be present. This list of hosts will be allowed to place the thin client within an iframe. The list format follows that accepted by Content-Security-Policy headers.

The recommended value is 'none', which offers the greatest level of protection. If a list of hosts is specified, they should be as restrictive as possible for the application to ensure malicious sources can not conduct UI redress attacks.

Section: System

Default: ThinClientFraming = 'none'

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


Logging & Reporting Properties

Variables in this section relate to logging.

Refer to the side menu for the listing of properties in this section.


HistorianBroadcastMaxSize

The maximum number of service updates to send in one broadcast.

Section: System

Default: HistorianBroadcastMaxSize = 500

*No restart required (Settings.Dynamic property)


HistorianBroadcastMinInterval

The minimum number of seconds between service updates.

Section: System

Default: HistorianBroadcastMinInterval = 1

*No restart required (Settings.Dynamic property)


HistorianConnectionRetryDelay

The number of seconds that an Historian should wait before retrying a connection.

Section: System

Default: HistorianConnectionRetryDelay = 1

*No restart required (Settings.Dynamic property)


HistorianDataAgeSweepIntervalDivisor

If data age storage limiting mode is used, then the sweep interval will be the data age divided by this value.

Sweep intervals do not fall on any defined moment in time.

If you have chosen to delete data, the only guarantee is that records stored since the parameter modification and newer than the limit are kept. Records that are newer than the limit BUT older than the parameter modification may be deleted.
Older records will be swept eventually and it is seldom worthwhile to focus on the value of the Sweep Interval.

If storage limiting is in effect, then regardless of any property settings, the maximum interval between sweeps will be no greater than 365 days and no less than one hour.

Section: System

Default: HistorianDataAgeSweepIntervalDivisor = 4

*No restart required (Settings.Dynamic property)

The term "sweep interval" is slightly misleading in that the interval actually sets the time between creation of new record sequences, "blocks", in the Historian. During a sweep, entire record sequences older than the number of days or records to keep, are removed. Changes to the sweep interval do not affect existing record sequences. Sweeps may occur on any of application startup, workstation becomes the server, and again after the next interval since the last sweep.

Sweeping is done based on when data was recorded, which may differ from the data timestamp, especially in the case of manually entered data. Sweeping is based only on the age of the record sequence and is not done on a tag-by-tag basis, nor do sweep intervals line up with calendar dates such as January 1st.

Again, if you have chosen to delete data, the only guarantee is that records newer than the limit are kept and that limit may be set to any length of time. Older records will be swept eventually.


HistorianDefaultArchiveInterval

If data age storage limiting mode is used, then this value sets default and maximum archive interval in seconds (365 days). Records are guaranteed to be kept for this length of time.

Section: System

Default: HistorianDefaultArchiveInterval= 31536000

*No restart required (Settings.Dynamic property)


HistorianFailoverInterval

The interval between successive Historian server failover attempts.

Section: System

Default: HistorianFailoverInterval = 60

*No restart required (Settings.Dynamic property)


HistorianODBCTableNames

Includes HistorianODBCTableNames0 through HistorianODBCTableNames10

Holds the base portion of the table name and the matching schema string to be used when an Historian is configured to use ODBCSingleTable. Use only ASCII characters. Non-ASCII characters will be removed.

Refer to Historian Data Storage

Section: System

Defaults:

  HistorianODBCTableNames0  = Numerics,     Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-R8|Value!-UI4
  HistorianODBCTableNames1  = Digitals,     Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-UI1|Value!-UI4
  HistorianODBCTableNames2  = Strings,      Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-STR|Value!-UI4
  HistorianODBCTableNames3  = Historians,   Timestamp-TSTAMP-T|MachineID-STR-M|Availability-BOOL-U
  HistorianODBCTableNames4  = Notebooks,    Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-STR
  HistorianODBCTableNames5  = Ports,        Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-I2
  HistorianODBCTableNames6  = Drivers,      Timestamp-TSTAMP-T|GenTimestamp-UI4-A|ErrorValue-I2|FailedCount-I2|FailedRetryCount-I2|SuccessCount-I2|Quality-R8|ResponseTime-R8|ErrorAddress-STR
  HistorianODBCTableNames7  = Modems,       Timestamp-TSTAMP-T|GenTimestamp-UI4-A|LCallFailures-R8|LCallState-R8|LEnabled-R8|LFailure-R8|LMediaMode-R8|LOffHook-R8|LCurrentNumber-STR
  HistorianODBCTableNames8  = Transactions, Timestamp-TSTAMP-T|GenTime-R8|TransactionID-BYTES|ErrorCode-I4|Encoding-I4|PackedData-BYTES
  HistorianODBCTableNames9  = Alarms,       Timestamp-TSTAMP-T|PackedData-PACK|Area-STR|Encrypted-BOOL|PackedInfo-PACK
  HistorianODBCTableNames10 = DataFlowTag,  Timestamp-TSTAMP-T|GenTimestamp-UI4-A|ErrData1-UI1|ErrData10-UI1|ErrData11-UI1|ErrData12-UI1|ErrData13-UI1|ErrData14-UI1|ErrData15-UI1|ErrData16-UI1|ErrData17-UI1|ErrData18-UI1|ErrData19-UI1|ErrData2-UI1|ErrData20-UI1|ErrData21-UI1|ErrData22-UI1|ErrData23-UI1|ErrData24-UI1|ErrData25-UI1|ErrData26-UI1|ErrData27-UI1|ErrData28-UI1|ErrData29-UI1|ErrData3-UI1|ErrData30-UI1|ErrData31-UI1|ErrData32-UI1|ErrData4-UI1|ErrData5-UI1|ErrData6-UI1|ErrData7-UI1|ErrData8-UI1|ErrData9-UI1|ErrMod-UI1|ErrorValue-I2|FailedCount-I2|FailedRetryCount-I2|SuccessCount-I2|Quality-R8|ResponseTime-R8|ErrorAddress-STR

*Restart Required (Settings.Startup property)


HistorianWriteBufferMaxLength

Sets the maximum number of records per tag name that will be retained in the Historian WriteHistory buffer.

Section: System

Default: HistorianWriteBufferMaxLength = 100

*No restart required (Settings.Dynamic property)


HistorianWriteBufferMaxTimeDiff

Sets the number of seconds for which backup buffer data will be retained. The time difference is relative to the most recent server timestamp

Section: System

Default: HistorianWriteBufferMaxTimeDiff = 15

*No restart required (Settings.Dynamic property)


LegacyHistoryPath

Deprecated. Maintained only for backward compatibility.

Required only on a workstation that does not have its own copy of the data. Typically set to a network path, identifying the machine and the folder (usually "History") where the legacy data is stored.


LogPath

Deprecated as of VTScada 10. If present, should be left unchanged.

Indicated the path at which the data files for tags whose data is being recorded by logger tags are stored. You must append the name of the directory you specify for the LogPath with a backslash (example: LogPath = C:\VTScada\History ).

If set to invalid (as it is by default), LogPath will automatically save the data files to the application directory.

This path can be a relative path (e.g. MyData\), or an absolute path (e.g. C:\VTScada\MYData\). If the directory you reference does not exist, VTScada will create it for you. A relative path is recommended, as it enables you to move the application without consequence at a later date. You should decide upon the path to which you wish the data files to be saved prior to creating your application. The name given each data file is, by default, tagname.DAT (i.e. the name of the tag whose data is being logged by the logger tag).

UNC path names (i.e. those of the form ServerName://Path/ ) may not be used.

Section: System

Default: LogPath =

*Restart Required (Settings.Startup property)


NotesTimestampFormat

Controls how timestamps are shown on notes:

0 = date/time

1 = age

Section: System

Default: NotesTimestampFormat = 1

*No restart required (Settings.Dynamic property)


RESTAllowedOrigins

Expand the list of allowed origins for REST queries by adding them to this setting. Separate allowed origins with a semicolon. Should be set to the scheme/host/port of the URL used to visit the page. For example, if your queries are hosted on your company website, you might set this to https://MyCompany.com

When running REST queries from a page that you store locally (not hosted on a web server), leave this property unset or append "null" to the list of origins. For example if opening an HTML file stored on your computer directly from Windows Explorer, and if an allowed origin is set, configure as https://MyCompany.com;null

This property is not set by default, therefore all origins are allowed.

Section: System

Default: RESTAllowedOrigins =

*No restart required (Settings.Dynamic property)


SoapServicesRealmName

Applies only to installations that include Remote Data Access as part of the license and that are using Soap Services.

Part of the configuration of an ODBC data source name (DSN) is to specify the VTScada realm to which the ODBC driver will connect. The property, SoapServicesRealmName must be given a value matching this realm or set of realms, where each name is separated by a semicolon.

Section: System

Default: SoapServicesRealmName =

*No restart required (Settings.Dynamic property)

Related information:

SQL Queries


SQLPaginationEnabled

When set to 1 (true) REST queries are limited to 10,000 rows and a page token is returned with the result set. Subsequent queries should include that token in order to retrieve the next set of results.

The pagination is supported only when retrieving historical data from the History table, the custom table name set by \SQLQueryHistoryNoOverridesTableName, and the History TPP tables.

Retrieving alarm history doesn’t support pagination.

Section: System

Default: SQLPaginationEnabled = 1

*No restart required (Settings.Dynamic property)


SQLQueryHideLegacyTables

Viewing: Reference > Property Reference > Logging & Reporting Properties > SQLQueryHideLegacyTables

Concepts:

Table Structure and Notes

SQL: Reference and Examples

Reference:

SQLDataQueryDriverMaxTagsPerQuery

SQLQueryHistoryNoOverridesTableName

SQLQueryHistoryNoOverridesTableSupportsTPP

SQLQueryMaxResultRows

SQLQueryTableTPPs

SQLQueryHideLegacyTables

Prior to release 11.1 of VTScada, logged tag data was stored in separate tables. These legacy tables may still be viewed if this application property SQLQueryHideLegacyTables is set to 0 (false). If set to 1 (true), only the History table (and any History:TPP tables) will be visible.

Section: System

Default: SQLQueryHideLegacyTables = 0

*No restart required (Settings.Dynamic property)


SQLQueryHistoryNoOverridesTableName

Viewing: Reference > Property Reference > Logging & Reporting Properties > SQLQueryHistoryNoOverridesTableName

Concepts:

Table Structure and Notes

SQL: Reference and Examples

Reference:

SQLDataQueryDriverMaxTagsPerQuery

SQLQueryHideLegacyTables

SQLQueryHistoryNoOverridesTableSupportsTPP

SQLQueryMaxResultRows

SQLQueryTableTPPs

SQLQueryHistoryNoOverridesTableName

May be set to a text value, which VTScada will then use as a table name. SQL Queries that refer to this table will return all values stored with the same tag name and timestamp. A common value to assign for this property is "HistoryWithDuplicates".

(Under normal conditions, when there are multiple values stored for a tag value, all having the identical timestamp, VTScada assumes that the extras are duplicates and will return only a single value per timestamp.)

Section: System

Default: SQLQueryHistoryNoOverridesTableName = HistoryWithDuplicates

*No restart required (Settings.Dynamic property)

Related information:

SQLQueryHistoryNoOverridesTableSupportsTPP

Table Structure and Notes - Refer to sub-section, "Multiple Values per Time Stamp"


SQLQueryHistoryNoOverridesTableSupportsTPP

Viewing: Reference > Property Reference > Logging & Reporting Properties > SQLQueryHistoryNoOverridesTableSupportsTPP

Concepts:

Table Structure and Notes

SQL: Reference and Examples

Reference:

SQLDataQueryDriverMaxTagsPerQuery

SQLQueryHideLegacyTables

SQLQueryHistoryNoOverridesTableName

SQLQueryMaxResultRows

SQLQueryTableTPPs

SQLQueryHistoryNoOverridesTableSupportsTPP

In most cases when querying for duplicates from the history table, queries that aggregate data will not be useful. This property may be set to false to direct VTScada to ignore such queries.

Section: System

Default: SQLQueryHistoryNoOverridesTableSupportsTPP = 1

Related information:

SQLQueryHistoryNoOverridesTableName


SQLQueryMaxRequestLength

Sets the maximum payload size (measured in bytes) that will be accepted by the VTScada HTTP server in a REST or SOAP request. While this affects both POST and GET requests, POST is usually preferred for requests that exceed 32KB. GET requests are limited in size by factors outside the control of VTScada.

If sending requests that require this property to be set to a larger value, you may find that processing and data retrieval for those requests can consume excessive time and memory.

Section: System

Default: SQLQueryMaxRequestLength = 32768

*No restart required (Settings.Dynamic property)

Related properties:

HTTPMaxEntityLength

SQLQueryMaxResultCells

SQLQueryMaxResultRows


SQLQueryMaxResultCells

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Sets a maximum amount of cells, which is the number of rows times the number of columns, that will be returned in response to any SQL query. Defaults to 1000000. Columns in the WHERE and ORDER BY clause are included when calculating the number of columns. The Timestamp column is excluded.

Section: System

Default: SQLQueryMaxResultCells = 1000000

Related properties:

HTTPMaxEntityLength

SQLQueryMaxRequestLength

SQLQueryMaxResultRows


SQLQueryMaxResultRows

Viewing: Reference > Property Reference > Logging & Reporting Properties > SQLQueryMaxResultRows

Concepts:

Table Structure and Notes

SQL: Reference and Examples

Reference:

SQLDataQueryDriverMaxTagsPerQuery

SQLQueryHideLegacyTables

SQLQueryHistoryNoOverridesTableName

SQLQueryHistoryNoOverridesTableSupportsTPP

SQLQueryTableTPPs

SQLQueryMaxResultRows

Sets a maximum number of rows that will be returned in response to any SQL query. Defaults to 10000.

Section: System

Default: SQLQueryMaxResultRows = 10000

*No restart required (Settings.Dynamic property)


SQLQueryParserDepthLimit

Controls how deeply-nested SQL queries may be, when run against the VTScada SQL API.

Defaults to 300. Increasing this setting to an excessive number may lead to a crash due to resource consumption.

Section: System

Default: SQLQueryParserDepthLimit = 300

*No restart required (Settings.Dynamic property)


SQLQueryTableTPPs

Viewing: Reference > Property Reference > Logging & Reporting Properties > SQLQueryTableTPPs

Concepts:

Table Structure and Notes

SQL: Reference and Examples

Reference:

SQLDataQueryDriverMaxTagsPerQuery

SQLQueryHideLegacyTables

SQLQueryHistoryNoOverridesTableName

SQLQueryHistoryNoOverridesTableSupportsTPP

SQLQueryMaxResultRows

SQLQueryTableTPPs

Used by the ODBC Server option to group data records by time interval. By adding the application property, SQLQueryTableTPPs, you can retrieve tag data from specific time intervals. The format of the statement is:

SQLQueryTableTPPs = <time frame specifier>

where the time frame specifier takes the form of a digit and a letter. The letter indicates the units in which time interval is measured (hours: H , weeks: W, etc.) and the digit specifies the number of units of each interval that should pass between each record.

The available time interval units are:

MS - milliseconds

S - seconds (this is the default, therefore the S may be omitted)

M - minutes

H - hours

D - days

W - weeks

Y - years

Section: System

Default: SQLQueryTableTPPs = 1m;1h;1D;1W

*No restart required (Settings.Dynamic property)


SQLTagParmExtraColumns

Used when querying the Parms_AllTypes table (Table Structure and Notes ). Specifies extra columns to be returned in addition to the collected tag parameters.

Section: System

Default: SQLTagParmExtraColumns = TagType,TagTypeLabel,UniqueID,ShortName,ParentTag,NChildren,HasGrandchildren,Value,DisplayAddress,StationNumber,IsString,IsAnalog,IsDigital,IsDiscrete,IsInput,IsOutput,IsPump,IsDriver,EquipmentType,IsAnalytic

*No restart required (Settings.Dynamic property)


StorageLocation

Sets the location for storage of data from a named Historian tag. Must be added to your application. The name of the tag must precede this property name. For example, to specify a storage location for the SystemHistorian tag, add the property "SystemHistorianStorageLocation".

Defaults to the Data\History directory under your application. If using the VTScada history database, this value should be a folder name. If using an ODBC database, this should be either the DSN or a valid connection string for the database.

Section: System

Default: StorageLocation

*No restart required (Settings.Dynamic property)


StorageType

Sets the type of storage for a named Historian tag. Must be added to your application. The name of the tag must precede this property name. For example, to specify a storage type for the SystemHistorian tag, add the property "SystemHistorianStorageType".

Defaults to the VTScada proprietary database. The only other valid value is "ODBC" for all other storage types.

Section: System

Default: StorageLocation

*Restart Required (Settings.Startup property)


TraceUserConfigActions

Adds events to the alarm history whenever a user makes an online configuration change. On by default.

Default: TraceUserConfigActions = 1


UseLegacyHistoryPriorTo

Sets a timestamp marking the latest date and time that legacy data was recorded. This will usually be the moment that the application was converted from one system to the other but, if your application is configured to use a time-delay when logging data, then you may need to adjust the UseLegacyHistoryPriorTo value to account for the offset.

The time should be specified in the UTC timezone. For example, "2012-04-01 12:35:30.304", or the equivalent using a time stamp.

Section: [Application]

Default: UseLegacyHistoryPriorTo =

*No restart required (Settings.Dynamic property)


NotesTimestampSort

Controls how notes are sorted for display:

0 = by original timestamp

1 = by most recently updated

Section: System

Default: NotesTimestampSort = 1

*No restart required (Settings.Dynamic property)


Numeric Keypad Properties

Use these numeric keypad properties to enable and modify the numeric keypad on a VTScada workstation. The following properties are found in Settings.Dynamic and no restart is required for changes to take effect.

UseOnScreenKeypad

OnScreenKeypadNighttimeMode

OnScreenKeypadSize

To enable and modify the numeric keypad for thin client applications, you must use Realm Display Setup Tags


OnScreenKeypadNighttimeMode

Workstation Specific Setting.

Enable to switch to nighttime mode for the numeric keypad. The default mode displays a light keypad with dark characters and borders. Nighttime mode displays a dark keypad with light characters and borders.

This feature is intended for touchscreen environments.

For thin-client configuration, see Realm Display Setup Tags

Section: System

Default: OnScreenKeypadSize = 0

*No restart required (Settings.Dynamic property)


OnScreenKeypadSize

Workstation Specific Setting.

Set the height and width of the keypad window in pixels. Adjust for better usability on large or small screens.

This feature is intended for touchscreen environments.

For thin-client configuration, see Realm Display Setup Tags

Section: System

Default: OnScreenKeypadSize = 300

*No restart required (Settings.Dynamic property)


UseOnScreenKeypad

Workstation Specific Setting.

Enables numeric-only keypad that automatically displays for any edit field that is of type numeric in pages or configuration menus.

This feature is intended for touchscreen environments.

For thin-client configuration, see Realm Display Setup Tags

Section: System

Default: UseOnScreenKeypad = 0

*No restart required (Settings.Dynamic property)


Mapping Properties

The majority of the properties related to slippy maps are stored in Setup.INI and must be edited directly in that file, requiring a restart of VTScada on the mapping server. These include:

SlippyMapBulkDownloadMaxZoomDiff

SlippyMapCriticalDiskSpace

SlippyMapDownloadFailoutTime

SlippyMapDownloadTimeLimit

SlippyMapMaxConcurrentDownloads

SlippyMapMaxRetryDelay

SlippyMapMaxTileSize

SlippyMapOSMDisable

The following are stored in your Settings.Dynamic file and can be changed using tools in the Display tab of the Application Properties dialog.

SlippyMapMaxZoomLevel

SlippyMapMinZoomLevel


MapAreaLimiting

A comma-delimited set of four values that define the minimum and maximum, latitude and longitude values used to limit the allowed area for browsing of slippy maps. Defaults to no value, indicating no limit on map browsing.

When set, the order of the values is: Lower Latitude, Left Longitude, Upper Latitude, Right Longitude

For example: 47.196309,-66.391279,43.180215,-59.810468

Refer to Limit the Map Area

Section: System

Default: MapAreaLimiting =

*No restart required (Settings.Dynamic property)


Mobile Browser Properties

Variables in this section relate to the mobile browser.

Refer to the side menu for the listing of properties in this section.


ContainerTerm

Specifies the word to be used for containers (stations, context tags, sites, etc) that may be browsed into.

Section: System

Default: ContainerTerm = Sites

*No restart required (Settings.Dynamic property)


EnableMobileMaps

Enables the display of slippy maps in the mobile browser interface. Disabled by default.

See also, the Setup.INI property MobileSlippyMapTilesSource1.

Section: System

Default: EnableMobileMaps=


IdleWebSessionTimeout

Sets the length of time, after which an inactive mobile browser client will be signed out and the session terminated, thereby freeing the license key. Measured in minutes.

Note that this property is part of the <SECURITYMANAGER-ADMIN> section, and therefore can be added only by editing your Settings.Dynamic file.

Section: <SECURITYMANAGER-ADMIN

Default: IdleWebSessionTimeout = 5


MaxSnapshotsPerMobileUser

Sets the number of page snapshots that will be stored in any user's snapshot folder before older snapshots are deleted. (Oldest snapshots are deleted first.)

Defaults to 5 if missing or invalid. If any value less than 1 is used, this will default to 1.

Note that this is the number of snapshots stored per user, not the overall total number of snapshots.

Section: System

Default: MaxSnapshotsPerMobileUser = 5

*No restart required (Settings.Dynamic property)


MobileBrowserAlarmHistoryMaxRecords

Sets the maximum number of alarm history records to display in the Mobile browser. The limit exists so that operators can see the most recent records without waiting for an large number of records to load.

Section: System

Default: MobileBrowserAlarmHistoryMaxRecords = 100

*No restart required (Settings.Dynamic property)

Related properties

MobileBrowserAlarmHistoryTimeRange


MobileBrowserAlarmHistoryTimeRange

Sets the maximum number of days of alarm history to display in a mobile browser.

Section: System

Default: MobileBrowserAlarmHistoryTimeRange = 30

*No restart required (Settings.Dynamic property)

Related properties

MobileBrowserAlarmHistoryMaxRecords


MobileBrowserAutoRefreshPeriod

Specifies the Auto-refresh period for mobile browser pages in list-view mode (measured in seconds). Note that the browser connection must be restarted before a change to this setting will go into effect.

Section: System

Default: MobileBrowserAutoRefreshPeriod = 60

*No restart required (Settings.Dynamic property)


MobileBrowserDisablePageGraphics

If set to 1 (true), this disables page graphics in the mobile browser display, changing the display to a version that minimizes the required bandwidth to the device, as well as the CPU load on the server.

Has no effect on the number of mobile browser client licenses.

Section: System

Default: MobileBrowserDisablePageGraphics = 0

*No restart required (Settings.Dynamic property)


MobileBrowserSnapshotRefreshPeriod

Specifies the Auto-refresh period for mobile browser pages in graphic-view mode (measured in seconds). Note that the browser connection must be restarted before a change to this setting will go into effect.

Section: System

Default: MobileBrowserSnapshotRefreshPeriod = 600

*No restart required (Settings.Dynamic property)


MobilePageMaxRenderTime

Specifies the Maximum time, in seconds, that a page may run before tags are collected from it for the mobile browser view.

Section: System

Default: MobilePageMaxRenderTime = 2

*No restart required (Settings.Dynamic property)


Modem Manager Properties

Variables in this section relate to the Modem Manager.

Refer to the side menu for the listing of properties in this section.


AnswerCalls

Controls whether you wish the Modem Manager to answer calls.

If set to 1 (true), the Modem Manager will answer incoming calls.

Section: System

Default: AnswerCalls = 1

*No restart required (Settings.Dynamic property)


CallInterval1

Viewing: Reference > Property Reference > Modem Manager Properties > CallInterval1

CallInterval1 Through CallInterval10

Defines the number of seconds to wait after a connection attempt in a call cycle fails.

The number following "CallInterval" matches the connection attempt, 1 through 10.

Related Variables: CycleLength

CycleLength sets the number of times that CallInterval1 through CallInterval10 occur.

CycleDelay sets the amount of time that the system will wait before beginning the entire call cycle again.

Section: System

Defaults:

CallInterval1 = 5

CallInterval2 = 60

CallInterval3 = 120

CallInterval4 = 120

CallInterval5 = 600

CallInterval6 = 600

CallInterval7 = 600

CallInterval8 = 600

CallInterval9 = 600

CallInterval10 = 600

*Restart Required (Settings.Startup property)


CycleDelay

Number of seconds to wait after CycleLength failed attempts occurred to connect to a phone number. After this time interval, the calls are attempted again and failed attempts restart after a time delay of CallInterval1. For BABT (British Telecom) rules, no more than four cycles may occur in a four-hour period. The default of 55 minutes (3300 seconds) causes one call cycle every hour.

Section: System

Default: CycleDelay = 3300

*No restart required (Settings.Dynamic property)


CycleLength

Number of attempts for a connection to a single phone number before CycleDelay occurs and call attempts restart with retry intervals starting at CallInterval1 again (assists in support of BABT (British Telecom) rules). Any CallInterval variables with intervals larger than CycleLength are ignored. If CycleLength is invalid, all retries beyond 10 use CallInterval10.

Section: System

Default: CycleLength = 5

*No restart required (Settings.Dynamic property)


DataIdleTime

Number of seconds to wait after data stops arriving (after initial data starts on an incoming call) before data tested to determine which driver should handle it.

Section: System

Default: DataIdleTime = 1

*No restart required (Settings.Dynamic property)


DialResetTime

A configurable time delay (in seconds or fractions of a second) between the hanging-up of a modem, and its selection for use in a new call. This delay enables the system driver to reset the modem to a known state. At low baud rates it may be necessary to extend this time.

Section: System

Default: DialResetTime = 5

*No restart required (Settings.Dynamic property)


DialWaitTime

Sets the delay (in seconds) to wait before retrying a failed modem operation after no dial tone, or no response is received from the modem.

Section: System

Default: DialWaitTime = 10

*No restart required (Settings.Dynamic property)

Related Variables: The HangUpDelay property sets the number of seconds to wait before hanging up the modem when there are no active attempts to read or write


GuardTone

Defines a .wav file that will be played every \ModemSpeechTO seconds while an audio call is silent. If not defined, then nothing is played.

Section: System

Default: GuardTone = PhonePip.wav

*No restart required (Settings.Dynamic property)


HangUpDelay

Sets the number of seconds to wait to hang up the modem when there are no active attempts at communications (i.e. no active attempts to read or write).

Related Variables: TheDialWaitTime variable sets the number of seconds to wait before retrying a failed modem operation.

Section: System

Default: HangUpDelay = 10

*No restart required (Settings.Dynamic property)


HelloPacketLength

Maximum number of bytes to accept as the initial message to be passed on to the drivers to determine the type of protocol and station address initiating the incoming call. The maximum allowable value is 1024.

Section: System

Default: HelloPacketLength = 1024

*No restart required (Settings.Dynamic property)


InitialDataDelay

The number of seconds the system should wait to receive initial data on an incoming call from an RTU before proceeding with further attempt at communications.

Section: System

Default: InitialDataDelay = 10

*No restart required (Settings.Dynamic property)


InitialDataDelay1

Required only in rare circumstances when an RTU that calls in requires a challenge before it will begin sending data.

If defined, this value must be less than InitialDataDelay.

Section: System

Default: InitialDataDelay1 =

*No restart required (Settings.Dynamic property)


InitModemsDisabled

If defined as true (i.e. a non-zero numeric value), then all modems are started in Disabled mode.

If this is defined for a workstation, then only the modems owned by that workstation are affected.

Section: System

Default: InitModemsDisabled =


MaxHandOffCount

When Modem Manager answers a call, but no registered VTScada driver accepts it, Modem Manager hands the call off to the next application that handles incoming modem calls. If another application accepts the call, Modem Manager increments a count of concurrent handed-off calls. While this count equals MaxHandOffCount, no further calls are handed off.

If MaxHandOffCount is not defined, then there will be no restrictions on call hand offs.

Section: System

Default: MaxHandOffCount =

*No restart required (Settings.Dynamic property)


MinModemsFree

The minimum number of free modems that must be maintained to handle incoming calls.

This parameter lets the Modem Manager keep a pool of modems available for incoming calls. An outgoing call will be queued while there are less than MinModemsFree modems unused.

Related Variables: If AnswerCalls has been set to 0 (default), then the MinModemsFree variable is ignored.

Section: System

Default: MinModemsFree = 0

*No restart required (Settings.Dynamic property)


MMCycleTime

Relevant only when there is more than one modem in a networked application. When MMCycleTime is invalid, only the modem on the primary server will be used by the Alarm Notification System, so long as that modem is available.

If set to zero, the least recently used modem of all those available will be preferred.

If set to a numeric value greater than zero, then only the modem on the primary server will be used (while it is available) until one or more of the other modems has been unused for MMCycleTime seconds, after which the least recently used of those modems will be preferred.

Section: System

Default: MMCycleTime = 86400

*No restart required (Settings.Dynamic property)


MMDropOrphanCallTimeout

After a collision between inbound and outbound calls, the inbound call may be orphaned. Wait for MMDropOphanCallTimeout seconds before dropping the call.

Section: System

Default: MMDropOrphanCallTimeout = 300

*No restart required (Settings.Dynamic property)


MMLogDateFormat

The date format to be used for the elements in the Modem Manager's event log.

If MMLogDateFormat is set to -1, no time is recorded in the list. Date Formatting Codes

Section: System

Default: MMLogDateFormat =

*No restart required (Settings.Dynamic property)


MMLogLevel

The Modem Manager's event log records events at four levels of detail (0..3). Setting this value to non-zero enables the additional information to be viewed.

Section: System

Default: MMLogLevel = 0


MMLogTimeFormat

Indicates the time format for the elements in the Modem Manager's event log (see "Modem Manager Programming Interface"). The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file. (Time Formatting Codes, Time Formatting Strings, Date and Time Phrase Keys)

If MMLogTimeFormat is set to -1, no time is recorded in the list.

Section: System

Default: MMLogTimeFormat = TimeFmtWithMilliseconds

*No restart required (Settings.Dynamic property)


MMRPCTimeout

The number of seconds to wait before failing an attempt to connect to another workstation. Connections that require multiple RPC hops use multiples of this timeout value.

Section: System

Default: MMRPCTimeout = 60

*No restart required (Settings.Dynamic property)


MMUnAvailRetry

If a modem cannot be used due to some reason external to VTScada, the modem manager will poll the modem periodically in case the status changes. MMUnAvailRetry can be added to your Settings.Dynamic file to control how often the modem will be checked. Defaults to 60 seconds if missing or invalid.

Section: System

Default: MMUnAvailRetry


ModemAlarm

If set to 0, this will override the ModemAlarm module, effectively disabling the recording of modem manager events in the alarm history. This may be useful in applications that otherwise generate a large number of modem manager alarm log entries.

Section: System

Default: ModemAlarm =


ModemAutoReset

Controls the number of minutes to wait before retrying a modem that has been marked as failed.

Section: System

Default: ModemAutoReset = 5

*No restart required (Settings.Dynamic property)


ModemManagerLogSize

Indicates the number of entries to be stored in the Modem Manager’s log file. If one intends to log modem manager events then this value should be set to at least 256.

If the variable is not set, then no logging of modem events will occur until the Event Log is first displayed on the screen. The Event Log modem palette tool permits you to view these log entries.

Section: System

Default: ModemManagerLogSize = 1000.

*Restart Required (Settings.Startup property)


ModemName Device

Viewing: Reference > Property Reference > Modem Manager Properties > ModemName Device

<ModemName>Device

Normally, local modem(s) are allocated to any modem devices on the local machine on a first-available basis. This parameter may be set to force a particular relationship by associating a modem tag name with an explicit modem device name. Because modem device names are not always predictable, this parameter may be set for a workstation.

Section: System

Default: <ModemName>Device =


ModemName Disabled

Viewing: Reference > Property Reference > Modem Manager Properties > ModemName Disabled

<ModemName>Disabled

If this is defined and set to 1 (true) then the modem identified by ModemName is started in Disabled mode.

Section: System

Default: <ModemName>Device =


ModemRetries

The number of failed connection attempts that do not get to the ringing/busy signal stage before the modem is declared to have failed.

Section: System

Default: ModemRetries = 10

*No restart required (Settings.Dynamic property)


ModemSpeechTO

Defines the interval (in seconds) between playing the wave file identified by \GuardTone (if any).

Section: System

Default: ModemSpeechTO = 3.5


ModemTCPIPPort

The Modem Manager needs to be able to setup socket-based communications between different PCs to stream the modem data. This parameter sets the base port number. The Modem Manager will start with this base and will try to open a socket, incrementing the port number until successful.

For historical reasons, the port actually used for the connection is always at least 1 more than the configured setting. (e.g. if ModemTCPIPPort == 50000, the actual port will be at least 50001). This can be relevant when setting up firewalls, etc

Section: System

Default: ModemTCPIPPort = 50000

*No restart required (Settings.Dynamic property)


SiteRetries

Indicates the number of unsuccessful connection attempts to a specific remote phone number before deeming the connection a failure.

If SiteRetries successive connection attempts for the same call fail, then that call is abandoned. These call attempts may be tried via a number of different modems.

Section: System

Default: SiteRetries = 10

*No restart required (Settings.Dynamic property)


SquelchDetectDelay

Indicates the number of seconds to wait for the first byte of noise on the modem line after answering an incoming call.

Related Variables: The SquelchIdleTime variable enables you to set the number of seconds to wait for idle time after squelch noise has been detected, while the SquelchPacketLength variable enables you to set the maximum number of bytes of noise to accept before the modem hangs up on an incoming call.

Section: System

Default: SquelchDetectDelay = 0

*No restart required (Settings.Dynamic property)


SquelchIdleTime

Indicates the number of seconds to wait for idle time after squelch noise is detected to decide that real data is to follow. InitialDataDelay starts counting after this time.

Related Variables: The SquelchDetectDelay variable enables you to set a number of seconds the modem should wait for the first byte of noise on the modem line after answering an incoming call, while the SquelchPacketLength variable indicates the maximum number of bytes of noise to accept before the modem hangs up on an incoming call.

Section: System

Default: SquelchIdleTime = 0.25

*No restart required (Settings.Dynamic property)


SquelchPacketLength

Indicates the maximum number of bytes of noise to accept before the modem is hung up after answering an incoming call.

Related Variables: The SquelchDetectDelay variable enables you to set a number of seconds the modem should wait for the first byte of noise on the modem line after answering an incoming call, while the SquelchIdleTime variable indicates the number of seconds to wait for idle time after squelch noise is detected to decide that real data is to follow.

Section: System

Default: SquelchPacketLength = 65536

*No restart required (Settings.Dynamic property)


UseSerialAreaInModemCall

Controls whether modem selection will rely on the Area property configured for Serial Port tags.

If set to 1, UseSerialAreaInModemCall forces calls to a remote RTU site to use only modems with an area property matching that of the serial port tag. The benefit is that a voice modem, used for the Alarm Notification System and configured without an area property, would not be used for data calls.

If set to 1 and there is no modem with an area matching the serial port, then the call will simply be canceled.

If UseSerialAreaInModemCall is set to "0", the area configured for serial port tags has no bearing on modem calls. (This is the default, for backwards compatibility issues).

Section: System

Default: UseSerialAreaInModemCall = 0


UseUnimodem

Indicates whether you want the UniModem V driver to appear in the list of available modem drivers

Trihedral supplies its own modem driver / TAPI Service Provider (TSP). By default, only Trihedral's driver will appear in the available list. If UseUnimodem is set to "1", the older UniModem V driver will also be available for you to select.

Section: System

Default: UseUnimodem = 0


MultiSpeak Interface Properties

Variables in this section relate to the MultiSpeak communication protocol.

Refer to the side menu for the listing of properties in this section.


MultiSpeakLegacyIOPublish

Controls whether Legacy IO tags (Analog Status, Digital Output, etc.) are included as Multispeak tags for ScadaAnalogChangedNotification and ScadaStatusChangedNotification messages. This property also controls whether such tags appear in the GetAllScadaPoints list.

When enabled, this property can greatly increase the load on your servers. Legacy I/O tags do not have tag by tag control over publishing, therefore there could be a large number of notifications.
You can mitigate that by adding this property to a parent Context tag and setting it to 1 there. It will apply only to those legacy I/O tags below that Context.

If not set, only I/O and Calculations tags will be used.

Section: System

Default: MultiSpeakLegacyIOPublish = 0

*No restart required (Settings.Dynamic property)


MultiSpeakMaxMessagePoints

Controls the maximum number of ScadaAnalog, ScadaStatus or ScadaPoint items that VTScada will send in a single message.

GetAllScadaPoints, ScadaAnalogChangedNotification, and ScadaStatusChangedNotification will all return arrays of points, and this property sets the maximum for a single message.

When one message would otherwise send more points than the limit set by this property, GetAllScadaPoints will use pagination, whereas the Notification methods will send multiple notifications

Section: System

Default: MultiSpeakMaxMessagePoints = 100

*No restart required (Settings.Dynamic property)


MultiSpeakMaxPointIDLength

Imposes a maximum PointID length, measured in characters.

The PointID is usually the VTScada Tag unique ID but if the unique ID is longer than this setting a 10 character hash-generated string will be used in its place.

This property should be set to 38 for compatibility with Milsoft's DisSPatch™ OMS.

Section: System

Default: MultiSpeakMaxPointIDLength =

*No restart required (Settings.Dynamic property)


MultiSpeakMessageRetries

Sets the maximum number of PingURL requests to be tried before VTScada will give up and report an error.

Section: System

Default: MultiSpeakMessageRetries = 5

*No restart required (Settings.Dynamic property)


MultiSpeakMessageTimeout

The number of seconds that VTScada will wait to receive a response before giving up on the current request.

VTScada sends successive PingURL requests on startup and on notification failure until one succeeds. Each request is separated by a pause of MultiSpeakMessageTimeout seconds.

Section: System

Default: MultiSpeakMessageRetries = 20

*No restart required (Settings.Dynamic property)


MultiSpeakMHCompanyAttribute

Outgoing MultiSpeakMsgHeader Company attribute value.

If notifications sent by VTScada have their responses successfully received from Milsoft but no outages/normalization events are reported, make sure that the Company name set in Milsoft matches MultiSpeakMHCompanyAttribute if set or the default value "Trihedral Engineering Ltd." otherwise .

Section: System

Default: MultiSpeakMHCompanyAttribute = Trihedral Engineering Ltd.

*No restart required (Settings.Dynamic property)


MultiSpeakNotificationDelay

When there is a change in value of tags that are configured to publish, a notification is sent via ScadaAnalogChangedNotification and ScadaStatusChangedNotification.

VTScada will wait MultiSpeakNotificationDelay seconds after that first change of value in order to collect any other changed values so that a longer list can be sent in the single message. This reduces the number of messages sent, and also prevents fast-changing tags from triggering a large number of notifications. (Only the current value is used when building the message.)

Section: System

Default: MultiSpeakNotificationDelay = 5

*No restart required (Settings.Dynamic property)


MultiSpeakPingURLProbingPeriod

Sets the frequency of checks to verify that a MultiSpeak endpoint remains available during long periods of inactivity.

Measured in seconds, this value defaults to 3600 if not otherwise set. Use care if changing this value. Frequent checks may cause an overload of network traffic.

Section: System

Default: MultiSpeakPingURLProbingPeriod = 3600

*No restart required (Settings.Dynamic property)


MultiSpeakRealmNames

The realm names that can be used by other MultiSpeak end points to connect into VTScada. If more than one realm name is available, separate those names by semi-colons.

The MultiSpeak interface is enabled only when this property is set to at least one valid realm.

Section: System

Default: MultiSpeakRealmNames =

*No restart required (Settings.Dynamic property)


MultiSpeakServiceEnable

Copy from OEM layer and set to TRUE (1) to enable MultiSpeak as a service for an application.

Your application must be secured with an account that enables thin client access, and have realms/server setup configured. See MultiSpeak Support for much more information.

Section: System

Default: MultiSpeakServiceEnable = 0

*No restart required (Settings.Dynamic property)


MultiSpeakSubscriptionMethods

A comma-separated value (CSV) list of notification methods that VTScada will send to the configured subscriber. This is equivalent to the MethodsList that would be provided in the RegisterForService method.

The list should include either or both of SCADAAnalogChangedNotification and SCADAStatusChangedNotification.

Notification methods listed here will not be invoked unless also included in the methods of a GetMethods response returned by the endpoint.

Section: System

Default: MultiSpeakSubscriptionMethods =

*No restart required (Settings.Dynamic property)

Examples:

MultiSpeakSubscriptionMethods = SCADAAnalogChangedNotification,SCADAStatusChangedNotification

Analogs and digitals

MultiSpeakSubscriptionMethods = SCADAAnalogChangedNotification

Only the analogs

MultiSpeakSubscriptionMethods = SCADAStatusChangedNotification

Only the digitals


MultiSpeakSubscriptionPassword

Password to authenticate notification messages. This is equivalent to the ResponsePwd field in the RegisterForService method. If authentication is not required this property should be left blank (Invalid).

Section: System

Default: MultiSpeakSubscriptionPassword =

*No restart required (Settings.Dynamic property)


MultiSpeakSubscriptionURL

Destination endpoint where VTScada will send notification messages. This should be the server name (could be fully qualified) of the MultiSpeak endpoint. By default, HTTP and port 80 will be used. Port 443 will be used for HTTPS.

This is the same as the ResponseURL that is provided in the RegisterForService method.

Section: System

Default: MultiSpeakSubscriptionURL =

*No restart required (Settings.Dynamic property)

Examples:

OMS_Server

Basic server name. Will use HTTP over port 80 implicitly.

OMS_Server:81

Basic server name using port 81.

https://alpha.trihedral.com

Fully qualified domain name using HTTPS and port 443 (implicit).

https://alpha.trihedral.com:442

Fully qualified domain name using HTTPS and port 442.


MultiSpeakSubscriptionUsername

Username to authenticate notification messages. This is equivalent to the ResponseUserID field in the RegisterForService method. If authentication is not required this property should be left blank (Invalid).

Section: System

Default: MultiSpeakSubscriptionUsername =

*No restart required (Settings.Dynamic property)


MultiSpeakTraceFileSize

Maximum size in MB of the MultiSpeak diagnostic trace file. When the file reaches this size, the oldest half is deleted.

Section: System

Default: MultiSpeakTraceFileSize =

*No restart required (Settings.Dynamic property)


MultiSpeakTraceLevel

Diagnostic trace level for the MultiSpeak service. A lower value will log only important messages to the file, while a higher level will log more diagnostic details about the service. Setting it to 0 turns off logging.

0 - Off

1 - Low

2 - Medium

3 - High

Section: System

Default: MultiSpeakTraceLevel = 1

*No restart required (Settings.Dynamic property)


MultiSpeakTraceMemorySize

The log records written to the trace file are also stored in memory. This setting controls how many are kept in a FIFO buffer. Keeping a non-zero value in this setting allows recent Multispeak diagnostics to be included in a memory dump for analysis by Trihedral.

Section: System

Default: MultiSpeakTraceMemorySize = 100

*No restart required (Settings.Dynamic property)


Port Properties

Variables in this section relate to the functioning of I/O ports.

Refer to the side menu for the listing of properties in this section.


SerialShareSemaphore

The application property, SerialShareSemaphore has been marked as deprecated. In the unusual event that you have multiple devices attempting to use the same channel at the same time across multiple ports, you might consider adding Comm Link Sequencer Tags to serialize requests.

Related information:

Comm Link Sequencer Tags - Serialize requests for the same communication channel across ports.

Ori SerialShareSemaphoreginal description follows:

Enables multiple serial ports to share the same semaphore. Doing so prevents more than one driver from using more than one of the serial ports in the group at a time, thereby preventing two drivers on different serial ports connected to different radios sharing the same frequency from colliding.

To allow serial ports to share the same semaphore, set SerialShareSemaphore to "1" (the default is "0"). The result is that all serial ports with the same Area parameter will use the same semaphore.

Section: System

Default: SerialShareSemaphore = 0

*No restart required (Settings.Dynamic property)


SerPortDisconnectDelay

Controls how long the serial port will wait to return to an idle state after a driver releases the port semaphore. The purpose of this feature is to allow multiple drivers to share a Serial Tag in ‘serial’ mode (vs. modem mode).

There is a backward compatibility issue (prior to version 7.1) in that older port drivers did not have to acquire the port semaphore to cause the port to open. This will most likely affect drivers that operate in a listen mode, as they will now have to acquire the port semaphore to keep the port open.

To address this issue, set SerPortDisconnectDelay to a negative number. This will disable serial port sharing over the entire application, but will allow legacy driver to use the serial ports.

Section: System

Default: SerPortDisconnectDelay = 1

*No restart required (Settings.Dynamic property)


TCPIPPortMaxRcvLen

Indicates the maximum size of the receive buffer for the TCP/IP Port tag type.

Related Variables: The TCPIPPortMaxXmtLen variable enables you to set the size of the transmit buffer for the TCP/IP Port tag type.

Section: System

Default: TCPIPPortMaxRcvLen = 16384

*Restart Required (Settings.Startup property)


TCPIPPortMaxXmtLen

Deprecated. Do not use in new code.

Indicates the maximum size of the transmit buffer for the TCP/IP Port tag type.

Related Variables: The TCPIPPortMaxRcvLen variable enables you to set the size of the receive buffer for the TCP/IP Port tag type.

This property has become redundant because buffer management is now handled by Windows.

Section: System

Default: TCPIPPortMaxXmtLen = 16384
*Restart Required (Settings.Startup property)


Object Selection Marquee Properties

A marquee appears around an object that has been selected in a group of objects and whose Style dialog is open for modification.

Refer to the side menu for the listing of properties in this section.


MarqueeDashColor

Sets the first of two contrasting colors for the dashes of the marquee that appears when a selected object's properties are being displayed. The default color index is 15 (white).

Section: System

Default: MarqueeDashColor = 15

*No restart required (Settings.Dynamic property)


MarqueeSolidColor

Sets the second of two contrasting colors for the dashes of the marquee that appears when a selected object's properties are being displayed. The default color index is 0 (black).

Section: System

Default: MarqueeSolidColor = 0

*No restart required (Settings.Dynamic property)


MarqueeSpeed

Sets the speed (in fractions of a second) at which the marquee moves when a selected object's properties are being displayed.

Section: System

Default: MarqueeSpeed = 0.1

*No restart required (Settings.Dynamic property)


ODBCManager Properties

Variables in this section relate to the ODBCManager

Refer to the side menu for the listing of properties in this section.


ODBCManagerAllowDeleteAll

When TRUE (1) a Delete command without a where clause will remove all records in a table. Defaults to FALSE.

Section: System

Default: ODBCManagerAllowDeleteAll = 0

*No restart required (Settings.Dynamic property)

Related information:

ODBC Manager Service


ODBCManagerCheckBackupLog

Sets how frequently the ODBC manager will check the log for new error messages.

Section: System

Default: ODBCManagerCheckBackupLog = 300

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerConnectDelay

Maximum length of time, in seconds, to wait for an ODBC connection. If missing or invalid, will default to 30.

Section: System

Default: ODBCManagerConnectDelay = 5

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerDateFormat

Controls how dates are displayed when using ODBCManager tools.

Defaults to 30 (yyyy-MM-dd) Refer to Date Formatting Codes for other options.

Section: System

Default: ODBCManagerDateFormat = 30

*No restart required (Settings.Dynamic property)

Related information:

ODBC Manager Service


ODBCManagerDisconnectOnError

When set to TRUE (1) the ODBC manager will disconnect upon errors.

Section: System

Default: ODBCManagerDisconnectOnError = 0

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerExecuteDelay

Maximum length of time, in seconds, to wait for an ODBC query. If missing or invalid, will default to 60.

Section: System

Default: ODBCManagerExecuteDelay = 300

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerFormatNumeric

When TRUE, values returned in a result are assumed to be numeric and formatted as such unless otherwise indicated.

Section: System

Default: ODBCManagerFormatNumeric = 1

*No restart required (Settings.Dynamic property)

Related information:

ODBC Manager Service


ODBCManagerLogViewer

Sets the editor to use by default when viewing log files generated by the ODBC manager.

Section: System

Default: ODBCManagerLogViewer = NotePad.EXE

*No restart required (Settings.Dynamic property)

Related information:

ODBC Manager Service


ODBCManagerMaxConnectTime

An ODBC connection will close automatically after this many seconds of inactivity.

Section: System

Default: ODBCManagerMaxConnectTime = 600

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerMirrorToDisk

Used as a parameter when connecting to a database. When set to True, and if supported by the database, a mirror file will be created that can be used for backup recovery if needed.

Mirror files are stored in the subdirectory "MirrorDir" and have the extension "*.DAT".

Section: System

Default: ODBCManagerMirrorToDisk = 0

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerPaceRecovery

Relevant only when ODBCManagerMirrorToDisk is set to 1 and when recovering data from a mirror file. Sets a delay in seconds between reading successive files.

Section: System

Default: ODBCManagerPaceRecovery = 1

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerReconnectDelay

Sets a delay in seconds between successive connections to a database.

Section: System

Default: ODBCManagerReconnectDelay = 5

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerRollbackOnConnect

When set TRUE (1) any open transactions will be rolled back on connection to the database.

Section: System

Default: ODBCManagerRollbackOnConnect = 1

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerThreaded

When TRUE (1) threaded connections are attempted to the data source. Defaults to TRUE.

Section: System

Default: ODBCManagerThreaded = 1

*No restart required (Settings.Dynamic property)

Related information:

ODBC Manager Service


ODBCManagerTimeFormat

Controls how time is displayed when using ODBCManager tools.

Defaults to 2 (hour:minute:seconds) Refer to Time Formatting Codes for other options.

Section: System

Default: ODBCManagerTimeFormat = 2

*No restart required (Settings.Dynamic property)

Related information:

ODBC Manager Service


ODBCManagerTraceOn

Controls whether the ODBC manager writes error messages to its log file in Application Directory\ODBCManager\ODBCTransaction.LOG

Section: System

Default: ODBCManagerTraceOn = 0

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


ODBCManagerUseDriverTimeout

When set to TRUE (1) the ODBC manager will use the database driver's default timeout value when connecting.

Section: System

Default: ODBCManagerUseDriverTimeout = 0

*Restart Required (Settings.Startup property)

Related information:

ODBC Manager Service


Operator Logging Properties

Variables in this section relate to the logging of operator actions.

Refer to the side menu for the listing of properties in this section.


OperatorLogArea

Enables you to set the area for logged operator control actions so that operator control action entries in the History list can be conveniently sorted. If not present the area of the alarm or event will be used.

Section: System

Default: OperatorLogArea = OperatorLog

Related information:

VTScada Event Logging


OperatorLogging

Operator logging is a feature in VTScada that logs any value changes made to output tags and their related equipment via tag widgets such as SetValue Button, SetValue Hotbox, Numeric Entry field, and Slider. Data recorded includes the operator's username, the name and description of the tag, the new value, and the workstation from which the change was made. See: Operator Control Action Logging.

The OperatorLogging variable enables you to turn operator control action logging to the Alarms.log file on or off. By default, operator control action logging is turned on (OperatorLogging = 1).

If set to 0 (false), then control actions performed by operators are not logged to Alarms.log, and so cannot be displayed in the History list on the Alarm page.

Section: System

Default: OperatorLogging = 1

*Restart Required (Settings.Startup property)

Related information:

VTScada Event Logging


OperatorLogName

Enables you to set the name to display for all logged operator control action events (for example, the setting of a digital output tag via a SetValue button to 1).

Section: System

Default: OperatorLogName = OperatorLog

Related information:

VTScada Event Logging


OperatorLogTemplate

Optional format that may be created for operator log entries. This variable affords customers more flexibility in the format of the operator log message that is added to the alarm history when an operator performs a control operation.

OperatorLogTemplate is not part of newer applications. If added, it must contain a series of elements whose meanings are as follows. Note that these elements are case-sensitive.

^M | [Deprecated] Machine name
^U | [Deprecated] User name
^T | Tag name
^D | Quoted tag description
^d | Unquoted tag description
^A | Tag area
^O | Old value
^N | New value
^C | ChangedLabel (Phrase identifier key) or OperatorLogChangedLabel (Property value)
^F | FromLabel (Phrase identifier key) or OperatorLogFromLabel (Property value)
^I | ToLabel (Phrase identifier key) or OperatorLogToLabel (Property value)

Elements may be used in any order.

Section: System

Default: OperatorLogTemplate = ^C ^F ^O ^I ^N

*No restart required (Settings.Dynamic property)

Related information:

VTScada Event Logging


Page Properties

Variables in this section relate to application pages.

See also:Display Manager Properties

Refer to the side menu for the listing of properties in this section.


AnalogInputWidth

Applies only when UseOldSiteDialog is set to 1.

Sets the width (in pixels) of the analog input column (including Analog Input, Analog Status, Pulse tags) for station pages.

Section: System

Default: AnalogInputWidth = 200

*Restart Required (Settings.Startup property)


DefaultContainerDetailsPage

Sets the default page to use on the Sites page when a container does not have a Custom Details Page. Defaults to the built-in SiteDetailspage.

Section: System

Default: DefaultContainerDetailsPage = SiteDetailsPage

*No restart required (Settings.Dynamic property)


DefaultPage

Selects the page that the Display Manager should open if no other page is specified.

Section: System

Default: DefaultPage = PageMenuPage

*No restart required (Settings.Dynamic property)


DigitalInputWidth

Applies only when UseOldSiteDialog is set to 1.

Sets the width (in pixels) of the digital input column (including Digital Input, Digital Status, Pump Status tags) for station pages.

Section: System

Default: DigitalInputWidth = 200

*Restart Required (Settings.Startup property)


DisableGoToPage

Deactivates the Go To Page feature in both the Tag Browser and the Alarm Page. Recommended if you rely on restricted access to hotboxes to prevent unauthorized access to certain pages rather than using security privileges within those pages.

Section: System

Default: DisableGoToPage = 0

*No restart required (Settings.Dynamic property)

Related information:

DisableGoToPageAsPopup


DisableGoToPageAsPopup

Enable to deactivate the Go To Page Pop-up feature in both the Tag Browser and the Alarm Page. This will prevent pop-up windows from opening. Recommended for multi-monitor environments with pages you want to keep free of obstruction (ex. an Alarms Page). This property is similar to DisableGoToPage, but it only disables pop-ups.

If you have disabled this property and the pop-up feature has not become re-enabled, check to see if DisableGoToPage is enabled. If DisableGoToPage is enabled it will override DisableGoToPageAsPopup and disable both Go To Page and Go To Page Popup.

Section: System

Default: DisableGoToPageAsPopup = 0

*No restart required (Settings.Dynamic property)

Related information:

DisableGoToPage


DisablePageNotes

When set to 1, no page notes or page note toolbar will be displayed for the workstation.

Section: System

Default: DisablePageNotes = 0

*No restart required (Settings.Dynamic property)


DisableUSDialog

When set to 1 (true) disables the dialog that prompts for parameter values when opening an under-specified (US) parameterized page.

Section: System

Default: DisableUSDialog = 0

*No restart required (Settings.Dynamic property)


HideInaccessiblePages

If set to 1 (true), it hides pages that the current user cannot open. It also hides folders that only contain pages that the current user cannot open. If set to 0 (false), inaccessible pages will be hidden in the home page but not in the task bar and folders will always be shown.

Section: System

Default: HideInaccessiblePages = 1

*No restart required (Settings.Dynamic property)


HotBoxImage

May be set to the name of an image file to be used instead of the default rectangle. To use this property:

  1. Save the image file in the root folder of the application.
  2. Add the image to the application (Import File Changes)
  3. Set this property to the name of the image file.
  4. Restart the application.

You are free to experiment with images, but a 248x248 .PNG format image file is recommended. An opaque border around a transparent center may work well.

Section: System

Default: HotBoxImage =

*No restart required (Settings.Dynamic property)


HotBoxTransparency

If set to 0, the default HotBox will not be visible when the pointer is over the widget's area.

If not set (default) the HotBox will be visible.

Section: System

Default: HotBoxTransparency =

*No restart required (Settings.Dynamic property)


MaxRecipeBooksInBatchHistoryList

Within the Batch History page Recipe Book drop-down list, each existing Recipe Book tag can be selected to filter out all Recipe Books except for the one of interest or you may select "All" to display batches from all existing Recipe Book tags. However, if the number of existing Recipe Book tags exceeds the value of this property, the option to select "All" will disappear to prevent potentially displaying an excessive number of batches. Displaying an excessive number of batches is counter-intuitive for finding specific batch information and could have a negative impact on system performance.

Section: System

Default: MaxRecipeBooksInBatchHistoryList = 30

*No restart required (Settings.Dynamic property)


MaxWinPage

The maximum number of instances of windowed pages that can be opened at one time for any given page.

Section: System

Default: MaxWinPage = 1

*Restart Required (Settings.Startup property)


Page

Tells VTScada which page to open in the Display Manager when the application starts.

If set to invalid, the Display Manager will show the last page that was viewed before the application was stopped.

Section: System

Default: Page = PageMenuPage Closed A page module that will show all the pages in the menu as a series of tiles. Each tile is a live view of the matching page and can be clicked to open that page.

*No restart required (Settings.Dynamic property)


PageButtonToolTipBalloonStyle

Gives the option of having larger, balloon style tool tips that can display large amounts of text.

When set to 0, displays normal tool tip. When set to 1, displays a balloon tool tip.

Section: System

Default: PageButtonToolTipBalloonStyle = 0

*No restart required (Settings.Dynamic property)


PageSnapshotsMaxInMemory

Limits the number of images retained for use by the tiled menu page when displaying a cached view of pages rather than a live view. Images are retained in memory, therefore it is important to consider the effect on your system resources before increasing this value.

Section: System

Default: PageSnapshotsMaxInMemory = 10

Related information:

PageSnapshotCacheThresholdCount

PageSnapshotCacheThresholdPct


PageButtonToolTipDelay

Specifies a time delay in seconds before the tool tip is initially displayed. Re-show and time on screen delays are left as default. The value set here will apply to all tooltips in a window. If set to 0 then only the standard delay used with VTScada tool tips will be in effect.

Section: System

Default: PageButtonToolTipDelay = 2

*No restart required (Settings.Dynamic property)


PageButtonToolTipEnable

Controls display of tool tip on page buttons in the task bar according to the following table of values:

Value | Description
0 | Does not display tooltips over page buttons
1 | Displays the page title only, but not as a tool tip, thereby being consistent with other VTScada tooltips on the taskbar.
2 | Displays the page description or the PageToolTipLabel specific to the page.
3 | Displays both the page title and PageToolTipLabel value in the tool tip, with the page title showing in bold. If no value has been provided for the PageToolTipLabel, then an empty gap will be present after the page title.

Section: System

Default: PageButtonToolTipEnable = 3 (page title and tool tip)

*No restart required (Settings.Dynamic property)


PageButtonToolTipFont

This provides a way to select the font that the tool tip is to display in. Most Windows fonts are available for use. If not specified then the default system font will be used. The height will be set to 8pts unless specified in WinToolTipCtrl.

Section: System

Default: PageButtonToolTipFont Arial

*No restart required (Settings.Dynamic property)


PageSnapshotCacheThresholdCount

Controls whether the tiled page menu shows a live image of each page, based on a count of tiles displayed.

When the number of tiles exceeds this count, a cached view will be shown for each tile instead of a live view.

Section: System

Default: PageSnapshotCacheThresholdCount = 12

*No restart required (Settings.Dynamic property)

Related information:

PageSnapshotCacheThresholdCount

PageSnapshotCacheThresholdPct

PageSnapshotsMaxInMemory


PageSnapshotCacheThresholdPct

Controls whether the tiled page menu shows a live image of each page, based on a comparison of the width of each tile to the overall width of the VTScada window.

When the width of any tile is less than this percentage of the overall window, a cached view will be shown for each tile instead of a live view.

Section: System

Default: PageSnapshotCacheThresholdPct = 0.20

*No restart required (Settings.Dynamic property)

Related information:

PageSnapshotCacheThresholdCount

PageSnapshotsMaxInMemory


PageToolTipLabel

Not an application property, although described in this section.

Programmers can modify a page's source code to store a long description of a page in this variable. The text will be displayed in a tool tip, visible when the pointer is held over the page name, displayed in the task bar. PageButtonToolTipBalloonStyle should be set to 1 to provide space for long descriptions and PageButtonToolTipEnable should be set to 2 or 3 to enable the display of the text.

To enable translation, PageToolTipLabel should refer to a key in the languages panel.

Section: System

Default: PageToolTipLabel = Page Tool Tip

*No restart required (Settings.Dynamic property)


PopupCloseOnPageClose

Causes all pop-up pages to close instantly and automatically when an operator navigates from one page to another in the main display.

Note that navigating between folders in the tiled Page Menu Page does not count as changing the main display because each navigation folder is still within the same Page Menu Page.

If 0, (the default) then pop-up pages will remain open while an operator moves from one page to another in the main display.

Section: System

Default: PopupCloseOnPageClose = 0

*No restart required (Settings.Dynamic property)

(For clarity, pinned pages at the bottom of the screen are not "open" or "closed". The list is a form of navigation menu.)

Related information:

PopupPageLimit

PopupLimitAction


PopupLimitAction

Controls what will happen when the operator attempts to open more pages than allowed by the property, PopupPageLimit. The following options are possible:

PopupLimitAction | Action to take
Not set / 0 | Allow all pop-up pages to open.
1 | Warn, but allow the page to open if the operator chooses. (default)
2 | Prevent the page opening, and display an error message.
3 | Close the oldest pop-up page before proceeding to open the requested page.
4 | Close the newest pop-up page before proceeding to open the requested page.

Section: System

Default: PopupLimitAction = 1 (Warn, but allow on confirmation)

*No restart required (Settings.Dynamic property)

Related information:

PopupPageLimit

PopupCloseOnPageClose


PopupPageLimit

Sets the maximum number of pop-up pages that can be open at any time. Trend pop-ups, launched by clicking on a tag do not count towards this total.

May be any positive number from zero up. Defaults to eight.

Negative numbers are treated as zero. Decimal values are rounded down to the nearest integer.

Section: System

Default: PopupPageLimit = 8

*No restart required (Settings.Dynamic property)

Related information:

PopupLimitAction

PopupCloseOnPageClose


ProgSpawnTitle

Indicates the label to display in the title bar (and under the button in the site tools palette) for the program spawn drawing object belonging to the site tools palette.

Section: System

Default: ProgSpawnTitle = Program Spawn

*No restart required (Settings.Dynamic property)


SitesPageIconLoadTime

Sets the time interval that VTScada waits to see if a particular site icon has finished loading on a map. The default is 0.1. If this is too short, the following symptom may occur: On a map with many site icons, if any icons overlap, clicking on the overlapping area might cause both of the site pages to open in addition to a site selection dialog. Increasing this timeout to 1 second can alleviate this problem.

Section: System

Default: SitesPageIconLoadTime = 0.1

*No restart required (Settings.Dynamic property)


StretchBackground

Indicates whether background images should be stretched to fit the pages on which they appear. If set to 1 (true), then background images are stretched to fit the pages on which they appear.

Section: System

Default: StretchBackground = 0

*No restart required (Settings.Dynamic property)


TPPath

Indicates the path for background images for pages.

If TPPath is set to invalid (as it is by default), then the path for background images defaults to the Backgrounds directory within the application directory's Bitmaps directory (i.e. \ApplicationDirectory\Bitmaps\Backgrounds).

Section: System

Default: TPPath = Invalid

*No restart required (Settings.Dynamic property)


UseOldSiteDialog

When set to 1 (true) the older VTScada station page will be shown when an operator clicks on a Site Draw widget that is associated with a Polling Driver or DataFlow RTU tag.

Section: System

Default: UseOldSiteDialog =

*No restart required (Settings.Dynamic property)


Report Generation Properties

Variables in this section relate to report generation.

Refer to the side menu for the listing of properties in this section.


AnalogSummaryReportTimeUnits

Sets the time unit to be used when summarizing flow data. If flow is measured in units per second, set this value to 1. If flow is measured in units per minute, set this value to 60.

Section: System

Default: AnalogSummaryReportTimeUnits = 60

*No restart required (Settings.Dynamic property)


DefaultEmailSubject

Sets the default text to be placed in the subject line of an emailed report if a subject is not defined by the user.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: DefaultEmailSubject = Trihedral VTScada System

*No restart required (Settings.Dynamic property)


EmailServer

Deprecated. If present in an application that is ported to 10.1 or later, the value will be transferred to the new storage format. Subsequent changes to this property will be ignored.

Set the name or IP address of the email server for emailed reports (e.g. mail.trihedral.com).

Section: System

Default: EmailServer =

*No restart required (Settings.Dynamic property)


EmailSubject

Holds the text to be entered in the subject line of emails sent to designated operators by the VTScada Report System.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: EmailSubject = The VTScada System:

*No restart required (Settings.Dynamic property)


EmailUserName

Sets the default user name to be placed in an emailed report if not otherwise defined by the user.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: EmailUserName =

*No restart required (Settings.Dynamic property)


PumpReportSortPumps

By default, the Pump Activity and Pump Discrepancy reports will sort the tags being reported by Station Number and then by description alphabetically.

To have the tags reported in the order provided to the report, set this property to 0.

Default: PumpReportSortPumps = 1

Section: System


ReportBrowseDir

Indicates the default directory in which to start browsing when selecting a destination for report output files.

Section: System

Default: ReportBrowseDir =

*No restart required (Settings.Dynamic property)


ReportDateFormat

Does not apply if a file name is provided. Sets the date format to be used in report file names when no file name is provided by the user. For report file names, the slash character (/), will be replaced by a dash (-).

The value may use any of date formatting codes, date formatting strings or phrase identifier keys within the default languages file. To change the date format within reports, adjust the phrase DateFmtFullWritten.

Related information:

Date formats by date code: Date Formatting Codes

Building a custom date format string: Date Formatting Strings

Phrase identifier keys for date and time labels: Date and Time Phrase Keys

Section: System

Default: ReportDateFormat =DateFmtFullNumeric (Phrase Key)

*No restart required (Settings.Dynamic property)


ReportOutputDir

Indicates the default directory in which to store automatically generated reports.

Section: System

Default: ReportOutputDir =

*Restart Required (Settings.Startup property)


ReportTempDir

Indicates the default directory to use for temporary file storage during report generation.

Section: System

Default: ReportTempDir =

*No restart required (Settings.Dynamic property)


ReportTemplateDir

Indicates the default directory to use to browse for Excel screen report templates.

Section: System

Default: ReportTemplateDir =

*No restart required (Settings.Dynamic property)


ReportTimeZoneAware

Deprecated. Do not use in new code.

Makes the report page time zone aware. If an operator, located in another time zone, connects to the application via a VTScada Internet Client and runs a report, this variable controls whether that report will be displayed using the time zone of the operator (ReportTimeZoneAware = 1) or of the server (ReportTimeZoneAware = 0)

Reports must be configured to use this variable in their calls to GetLog

Section: System

Default: ReportTimeZoneAware = 1


ScreenReportsInExcel

Indicates whether VTScada reports whose chosen output format is "Screen Display" should be displayed in a window, or in a Microsoft Excel spreadsheet.

If set to 0 (false), then the report data is displayed in a window.

If set to 1 (true), then the report data is displayed in a Microsoft Excel spreadsheet.

This variable is maintained for backwards compatibility only. VTS version 6.6 and later use a "Use Excel to display report" check box that can be selected to display a screen report using Excel.

Section: System

Default: ScreenReportsInExcel = 1

*No restart required (Settings.Dynamic property)


StartOfWeek

Enables you to specify the starting day of the week for previous week report generation (i.e. when "Previous Week" is the selected time period for a report).

The available options are:

1 Monday (default), 2 Tuesday, 3 Wednesday, 4 Thursday, 5 Friday, 6 Saturday, 7 Sunday

Section: System

Default: StartOfWeek = 1

*Restart Required (Settings.Startup property)


Application Settings for RPC

Variables in this section relate to remote procedure calls and the RPC Manager.

Refer to the side menu for the listing of properties in this section.


ABSharedRPC

If set to 1 (true), then the same RPC service will be used for all instances of the Allen-Bradley tag type.

drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

Section: System

Default: ABSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


CampbellSharedRPC

When enabled, all Campbell devices share an RPC Service. This enables all Campbell device drivers to run on the same RPC server. If any should fail, then control for the entire group shifts.

drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

Section: System

Default: CampbellSharedRPC = 0


DataradioSharedRPC

Controls whether the same RPC service will be used for all instances of Dataradio.

If set to 0 (false), the same RPC is NOT be used for all instances of Dataradio (default).

drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

Section: System

Default: DataradioSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


DDESharedRPC

Controls whether the same RPC service will be used for all instances of DDE.

If set to 0 (false), the same RPC is NOT be used for all instances of DDE (default).

drivernameSharedRPC properties are stored in Settings.Startup, not Settings.Dynamic. Changes require a restart of the application in order to take effect.

Section: System

Default: DDESharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


DNP3SharedRPC

Indicates whether the same RPC service will be used for all instances of DNP3.

If set to 0 (false), the same RPC is not used for all instances of DNP3 (default).

Section: System

Default: DNP3SharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


DriverSetupDelay

Sets the number of seconds a VTScada driver will wait before trying to resend data when an attempt has failed.

  • Recommended if your drivers are attached to Polling Drivers.
  • Do not use if your drivers are attached to DriverMUX tags.

Section: System

Default: DriverSetupDelay = 60


DriverRPCOptimization

Obsolete as of version 12.0. Driver RPC is now always optimized.

Caused drivers to send only what has changed, rather than an entire read block. Introduced with VTScada 10.0 - defaults to 1 for new applications, but 0 (false) for applications being upgraded.

Developers may set the value to 1 (true) after all servers have been upgraded.

Section: System

Default: DriverRPCOptimization = 1


KoyoSharedRPC

Koyo shared RPC. If set, all Koyo PLCs will share the same RPC name, "KoyoDriverService".

Section: System

Default: KoyoSharedRPC = 0

*Restart Required (Settings.Startup property)


MDSSharedRPC

Controls whether the same RPC service will be used for all instances of MDS. If set to 1 (true), the same RPC service is used for all instances of MDS.

Section: System

Default: MDSSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


ModiconPortSharedRPC

Controls whether the same RPC service should be used for all instances of the Modbus Plus tag type that are connected to the same serial port or TCP/IP connection.

ModiconPortSharedRPC enables Modbus devices that share the same serial port or TCP/IP connection to be grouped with the same device, enabling Modbus I/O that uses different radio channels to be polled from separate PCs.

If set to 0 (false), then the same RPC service is not used for all instances of the Modicon tag type that are connected to the same serial port or TCP/IP connection (default).

Section: System

Default: ModiconPortSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC

Related Variables: the behavior of the ModiconSharedRPC will be overridden when this property is equal to 1 (true).

Note for multi-server applications using advanced server lists: If ModiconPortSharedRPC is set to 1, each Modbus-compatible driver service will be renamed to a combination of "ModiconServer" followed by the port name.

For example, if the Modbus Plus tags are attached to a port named "PrimaryTCPPort" in an application where ModiconPortSharedRPC has been set to 1, then the driver service will be named "ModiconServerPrimaryTCPPort".


ModiconSharedRPC

Controls whether the same RPC service should be used for all instances of the Modicon tag type.

If your networked application uses a polling driver, then it is recommended that this variable be set to 1.

If set to 0 (false), then the same RPC service is not used for all instances of the Modicon tag type (default).

Do not use if your drivers are attached to DriverMUX tags.

Section: System

Default: ModiconSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC

Related Variables: This property will be overridden when ModiconPortSharedRPC property is set 1 (true).


NMEADriverSharedRPC

Set to 1 (true) to share one RPC service. Defaults to 0 (false).

Section: System

Default: NMEADriverSharedRPC = 0

*Restart Required (Settings.Startup property)


OmronFINSSharedRPC

If set to 1 (true) all Omron FINS drivers will share the same RPC service. Defaults to 0, whereby the RPC service will be the name of the driver tag. If 1, the RPC service will be "OmronFINSServer".

Section: System

Default: OmronFINSSharedRPC = 0

*Restart Required (Settings.Startup property)


OmronSharedRPC

Indicates whether the same RPC service should be used for all instances of the Omron tag type. If set to 0 (false), then the same RPC service is not used for all instances of the Omron tag type (default).

Section: System

Default: OmronSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


OPCClientSharedRPC

Controls whether the same RPC service should be used for all instances of the OPC Classic Client Driver tag type.

If set to 0 (false), then the same RPC service is not used for all instances of the OPC Classic Client Driver tag type (default).

Section: System

Default: OPCClientSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


OPCServerRequestRateThreshold

Suppress outgoing publishes from the OPC Classic Server to clients during times of heavy interaction between the OPC Classic Server and a client. The value represents a threshold for callbacks per second. When GetOPCServerRequestRate is above the OPCServerRequestRateThreshold, the most recent Publish call from every tag is held until the value drops back down below the limit.

Note that GetOPCServerRequestRate applies across all applications and OPCServerRequestRateThreshold is an application-level property. You can control how each application responds to high engine activity.

Section: Application

Default: OPCServerRequestRateThreshold =

*No restart required (Settings.Dynamic property)

Related information:

GetOPCServerRequestRate

OPCServerRequestRefreshPeriod


OPCServerRequestRefreshPeriod

The interval used to update GetOPCServerRequestRate. The default is 5 seconds. This is the minimum period of time recommended for an accurate reading but frequent enough to return to normal publishing quickly after high engine activity subsides.

Section: Application

Default: OPCServerRequestRefreshPeriod = 5

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Related information:

GetOPCServerRequestRate

OPCServerRequestRateThreshold


OPCUAClientSharedRPC

Indicates whether the same RPC service should be used for all instances of the OPC UA tag type.

If set to 0 (false), then the same RPC service is not used for all instances of the OPC UA tag type (default).

Section: System

Default: OPCUAClientSharedRPC= 0

Related information:

Shared RPC


PakBusSharedRPC

When enabled indicates that all PakBus Drivers should have a shared RPC Service. This enables all PakBus Drivers to run on the same server. If any should fail, then control for the entire group shifts. The default value is 0.

Section: System

Default: PakBusSharedRPC = 0

*Restart Required (Settings.Startup property)


RemCfgTransLog

Indicates whether configuration database transactions should be logged. If set to 0 (false), then remote configuration database transactions are not logged.

Section: System

Default: RemCfgTransLog = 0

*No restart required (Settings.Dynamic property)

Related information:

Shared RPC


SiemensS7PortSharedRPC

Indicates whether the same RPC service will be used for all instances of the SiemensS7 tag type connected to a common TCPIP/Serial port If set to 0 (false), the same RPC is not to be used for all instances of SiemensS7Port (default).

If set to 1 (true), the same RPC service is used for all instances of SiemensS7Port.

Section: System

Default: SiemensS7PortSharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


SiemensS7SharedRPC

Indicates whether the same RPC service will be used for all instances of the SiemensS7 driver. If set to 1 (true), the same RPC service is used for all instances of Siemens.

Section: System

Default: SiemensS7SharedRPC = 0

*Restart Required (Settings.Startup property)

Related information:

Shared RPC


TescoSharedRPC

Typical SharedRPC setting. This (when 1) causes the driver to use a single service list for all Tesco Drivers.

Section: System

Default: TescoSharedRPC = 0

*Restart Required (Settings.Startup property)


VDRSharedRPC

Indicates whether the same RPC service will be used for all instances of the Veeder Root driver.

If set to 0 (false), the same RPC is not used (default).

Section: System

Default: VDRSharedRPC = 0

*Restart Required (Settings.Startup property)


Security Properties

Refer to the side menu for the listing of properties in this section.

Certain configuration settings related to security are stored in the file, Settings.Dynamic. Many of these variables can be changed only by directly editing this file in your application's root directory, and then importing the edited file using the Application Configuration dialog. Only authorized accounts may import a file that has been edited.

All custom privileges that you create in an application are named according to the pattern PrivDescN where N is a number starting at 0.

For example, if you have added 4 customized custom privileges to your application, they would appear as follows:

<SECURITYMANAGER-PRIVAPP>
PrivBitsTotal = 4
PrivDesc0 = Zone A Operation,0
PrivDesc1 = Zone B Operation,1
PrivDesc2 = Zone C Operation,2
PrivDesc3 = Zone D Operation,3

The label is used for display purposes, including the selection drop-down in each output tag's Merit tab and the security property of each page.

The number following the property sets its value, which is to be used in code. Note that this value is an offset from 16. Referring to the preceding example, where the page has been protected with the custom privilege "Zone A Operation", the first few lines of the source code of that page will look like the following:

[
Title = "Overview";
Color = "<FFFFFFFF>";
SecBit = 16;
]

PrivDes0, having number 0 in the list above, means that it's actual value to be used in code is 16 + 0 = 16.

Take careful note of each property's section. Three distinct sections are used for security-related properties. A property will be ignored if it is associated with the wrong section.

UserName

Related Tasks:

Import File Changes Page


AccountLockoutTime

Sets the length of time, measured in minutes, for which the user will be locked out after supplying an incorrect password MaxFailedLoginAttempts times, or MaxRateFailedLoginAttempts within the AccountRateWindow time frame.

Section: SecurityManager-Admin

Default: AccountLockoutTime = 1

*Restart Required (Settings.Startup property)

Related information:

AccountRateWindow

MaxFailedLoginAttempts

MaxRateFailedLoginAttempts


AccountRateWindow

Used in combination with MaxRateFailedLoginAttempts to distinguish between logon attempts made by a person and those made by an automated attack.

AccountRateWindow is a time period measured in seconds. If MaxRateFailedLoginAttempts are made within this time, the account is locked.

If there are MaxFailedLoginAttempts consecutive failed attempts within any time frame, the account will be locked.

Section: SecurityManager-Admin

Default: AccountRateWindow = 15

*Restart Required (Settings.Startup property)

Related information:

AccountLockoutTime

MaxFailedLoginAttempts

MaxRateFailedLoginAttempts


ADGroupPrefix

The prefix to be added to a VTScada role name for the equivalent Active Directory Security Group.

Section: <SecurityManager-Admin>

Default: ADGroupPrefix = VTScada-

Hidden section property. Must be edited within the file (Settings.Dynamic), not in the user interface. Ensure that you import file changes after editing any of the property files.

Related properties:ADGroupPrefix ADGroupSearchBase | ADRefreshPeriod | ADUserSearchBase


ADGroupSearchBase

Relevant when Windows Security Integration is being used and logons are slow due to the user being a member of a large (>100) number of AD security groups.

This information should be used only when absolutely necessary in the circumstance noted. A side effect will be that external changes to the AD such as renaming an OU specified in a search base will then cause all AD logons for VTScada to fail.

Use this property to restrict the AD LDAP queries for the user to a particular portion of the AD LDAP tree using LDAP syntax. For example, "ADGroupSearchBase = OU=SCADA, dc=example, dc=com" to restrict that particular search to the SCADA OU in the example.com domain.

Default: ADGroupSearchBase =

Section: <SecurityManager-Admin>

Hidden section property. Must be edited within the file (Settings.Dynamic), not in the user interface. Ensure that you import file changes after editing any of the property files.

Related properties:ADGroupSearchBase | ADRefreshPeriod | ADUserSearchBase


ADRefreshPeriod

Sets the interval in seconds between checks for changes to the accounts in the Active Directory for the logged-on users.

Section: <SecurityManager-Admin>

Default: ADRefreshPeriod = 900

Hidden section property. Must be edited within the file (Settings.Dynamic), not in the user interface. Ensure that you import file changes after editing any of the property files.

Related properties:ADRefreshPeriod | ADGroupSearchBase | ADUserSearchBase


ADUserSearchBase

Relevant when Windows Security Integration is being used and logons are slow due to the user being a member of a large (>100) number of AD security groups.

This information should be used only when absolutely necessary in the circumstance noted. A side effect will be that external changes to the AD such as renaming an OU specified in a search base will then cause all AD logons for VTScada to fail.

Use this property to restrict the AD LDAP queries for the user to a particular portion of the AD LDAP tree using LDAP syntax. For example, "ADUserSearchBase = OU=SCADA, dc=example, dc=com" to restrict that particular search to the SCADA OU in the example.com domain.

Section: <SecurityManager-Admin>

Default: ADUserSearchBase =

Hidden section property. Must be edited within the file (Settings.Dynamic), not in the user interface. Ensure that you import file changes after editing any of the property files.

Related properties:ADUserSearchBase | ADGroupSearchBase | ADRefreshPeriod


AutoAddADUsers

Controls whether authorized Windows accounts are automatically added to the VTScada Security Manager upon initial successful logon. Cannot be enabled when Security Realms are in use.

Section: SecurityManager-Admin

Default: AutoAddADUsers = 0

*No restart required (Settings.Dynamic property)


AutoLogOff

Viewing: Reference > Property Reference > Security Properties > AutoLogOff

cAutoLogOff

Measured in minutes, sets the length of time after which a user is signed out if VTScada does not detect activity.

Section: SecurityManager-Admin

Default: AutoLogOff = 15

*No restart required (Settings.Dynamic property)


AutoLogOffMax

Sets the maximum length of time available for the variable cAutoLogOff.

Section: SecurityManager-Admin

Default: AutoLogOffMax = 720

*No restart required (Settings.Dynamic property)


AutoLogOffMin

This variable sets the minimum value that can be selected from the Minutes of Inactivity spinbox in the Administrative Settings Security Manager dialog. A value of zero means "no automatic logoff". You might wish to set this to at least 1 to prevent managers from selecting that option.

Section: SecurityManager-Admin

Default = AutoLogOffMin = 0

*No restart required (Settings.Dynamic property)


ForcePasswordAltIdSync

By default, SecurityManager keeps encrypted passwords and alternate ids in sync during user update, but only if they were in sync to begin with. If this variable is 1, it will always keep them in sync.

If you intend to use an alternate ID for purposes other than for alarm dialler support, this value should be set to 0 (false).

See also: AlphaNumericXFormScheme

Section: SecurityManager-Admin

Default: ForcePasswordAltIdSync = 1

*No restart required (Settings.Dynamic property)


GroupLogin

Enables the realm name field in the Sign in dialogs. Accounts that have been assigned a realm name will be able to enter it in that field.

The NameSpaceDelimiter property is also part of security realm configuration, and must be specified before you can assign realm names to accounts.

Section: System(1)

Default: GroupLogin = 0

*No restart required (Settings.Dynamic property)

(1)In legacy applications, this property was defined in the <SecurityManagager-Admin> section. It will work in either section, but the System definition takes precedence.

Related information:

NameSpaceDelimiter


MaxFailedLoginAttempts

Sets the number of times in a row that a user may attempt to sign in with an incorrect password before being locked out of the system for AccountLockoutTime minutes. Defaults to twenty-five (25) consecutive attempts will result in the account being locked.

Attempts made within a user-defined time span are subject to a lower threshold before lockout. See related information.

Section: SecurityManager-Admin

Default: MaxFailedLoginAttempts = 25

Application restart required before changes will take effect.

Related information:

AccountLockoutTime

AccountRateWindow

MaxRateFailedLoginAttempts

SecurityAlarmPriority


MaxRateFailedLoginAttempts

Sets the number of times in a row that a user may attempt to sign in with an incorrect password, and within the time span defined by AccountRateWindow, before being locked out of the system for AccountLockoutTime minutes. This value is lower than MaxFailedLoginAttempts on the assumption that an automated attack will make repeated attempts much faster than would a person.

Defaults to three (3)

Section: SecurityManager-Admin

Default: MaxRateFailedLoginAttempts = 3

Application restart required before changes will take effect.

Related information:

AccountRateWindow

AccountLockoutTime

MaxFailedLoginAttempts


NameSpaceDelimiter

Do not use characters that could also be part of account names as the NameSpaceDelimiter. For example, a dot is typically part of an account name for any system using Windows Authentication.
While several characters are legal, you are strongly advised to use a colon, which will work dependably in all situations.

Required to specify the characters that will be used to separate security groups from account names. If NameSpaceDelimiter has a valid value, then group security accounts are enabled for your application (see "Security Namespaces").

Security groups enable the subdivision of the user base into "super users" and "group users". The primary application is for realm-area filtering.

The GroupLogin property is also part of security group configuration, and must be enabled before users will be able to enter a group name while signing in.

Section: System(1)

Default: NameSpaceDelimiter =

*No restart required (Settings.Dynamic property)

(1)In legacy applications, this property was defined in the <SecurityManagager-Admin> section. It will work in either section, but the System definition takes precedence.

Related information:

GroupLogin


NoteAddRequiresAuthentication

When set, a logon prompt will be displayed whenever an attempt is made to save a note, requiring the author to prove that he or she is authorized to created notes. The note will be attributed to account used to sign in, even if another account is currently signed in.

Logging-on to save a note does not change the logged-on user account. This challenge is used only for saving the note.

It is expected that security will be enabled and operator accounts created before notes are added. The challenge resulting from NoteAddRequiresAuthentication will be displayed regardless of whether you have actually enabled security.

Use of Proximity Card Readers is suggested if enabling this feature.

Section: System

Default: NoteAddRequiresAuthentication = 0

*No restart required (Settings.Dynamic property)


PasswordDisplay

Indicates the display that users view when entering their passwords in the Sign in dialog (that appears when the Sign in button is clicked) to help protect password entries from detection.

This variable can be set to one of three values:

Value | Description
0 | Displays the characters in the password as they are entered by the user.
1 | Displays asterisks equal to the password length as the characters are entered by the user (default).
2 | Displays a number of asterisks that vary in length as the password is entered by the user.

Section: SecurityManager-Admin

Default: PasswordDisplay = 1


PasswordMinLen

Indicates the minimum number of characters that can appear in any user's password.

The default was changed from 1 to 8 in version 12.2.03. All new applications made after 12.2.03 will have a default of 8. The minimum password length of pre-existing applications will be unchanged.

Section: SecurityManager-Admin

Default: PasswordMinLen = 8

*No restart required (Settings.Dynamic property)


PasswordTimeLimit

If the application is configured for automatic expiration of passwords, this variable stores the number of days that passwords will be valid for. For each user, the time of their last password reset is stored within SecMgr.DAT.

Section: SecurityManager-Admin

Default: PasswordTimeLimit =

*No restart required (Settings.Dynamic property)


PasswordWarningTime

This variable stores the number of days prior to password expiration during which the user will be warned upon logon.

This feature applies only if the application is configured for automatic expiration of passwords, and also to provide a warning prior to password expiration.

Section: SecurityManager-Admin

Default: PasswordWarningTime =

*No restart required (Settings.Dynamic property)


pcProxBaudRate

The default baud rate for communication with the proximity card reader connection.

Section: System

Default: pcProxBaudRate = 9600

*No restart required (Settings.Dynamic property)


pcProxConnectCheckTO

Period at which the connection to the proximity card reader should be re-checked. Disabled when set to zero (the default).

Section: System

Default: pcProxConnectCheckTO = 0

*No restart required (Settings.Dynamic property)


pcProxDataBits

The default data bit setting for communication with the proximity card reader connection.

Section: System

Default: pcProxDataBits = 8

*No restart required (Settings.Dynamic property)


pcProxEnable

Controls whether ports will be scanned for a proximity card reader. Defaults to off (0). Scanning will begin from the last port used.

Section: System

Default: pcProxEnable = 0

*No restart required (Settings.Dynamic property)

Related information:

pcProxExcludePortx

pcProxPortNum

PcProxPortScanHigh

pcProxPortScanLow


pcProxExcludePortx

If it is known that devices other than a proximity card are on various ports, you should exclude those port numbers.

"x" should be replaced by the port to be excluded from scanning, and the value of the property should then be set to 1 to exclude that port.

For example, if an auxiliary input device is installed on port 3, you would set:

pcProxExcludePort3 = 1

Ports that are associated with modems are automatically excluded from scanning.

Section: System

Default: pcProxExcludePortx =

All port numbers from pcProxPortScanLow to PcProxPortScanHigh will be scanned, excepting those associated with modems, if pcProxEnable is set to 1.

Related information:

pcProxExcludePortx

pcProxPortNum

PcProxPortScanHigh

pcProxPortScanLow


pcProxParity

The default parity bit setting for communication with the proximity card reader connection.

Section: System

Default: pcProxParity = 0

*No restart required (Settings.Dynamic property)


pcProxPortNum

Set this value if you know the port number to which the proximity card reader will be attached. Not set by default.

Use with caution: the port number may change if the USB device is unplugged temporarily. In general, it is better to allow VTScada to search for the device.

Section: System

Default: pcProxPortNum =

*No restart required (Settings.Dynamic property)

Related information:

pcProxPortNum

pcProxExcludePortx

PcProxPortScanHigh

pcProxPortScanLow


PcProxPortScanHigh

Specifies the highest port number to scan for a proximity card reader. Defaults to 16.

Section: System

Default: PcProxPortScanHigh = 16

*No restart required (Settings.Dynamic property)

Related information:

PcProxPortScanHigh

pcProxExcludePortx

pcProxPortNum

pcProxPortScanLow


pcProxPortScanLow

Specifies the lowest port number to scan for a proximity card reader. Defaults to 3.

Section: System

Default: pcProxPortScanLow = 3

*No restart required (Settings.Dynamic property)

Related information:

pcProxPortScanLow

pcProxExcludePortx

pcProxPortNum

PcProxPortScanHigh


pcProxStopBits

The default stop bit setting for communication with the proximity card reader connection.

Section: System

Default: pcProxStopBits = 1

*No restart required (Settings.Dynamic property)


PrivBitsTotal

Indicates the total number of custom privileges that have been configured for this application.

PrivBitsTotal should not be set to invalid, or errors will occur in your application. If there are no custom privileges for your application, you should set PrivBitsTotal to 0, as it is by default.

Each time you add a new custom privilege using the PrivDescX variables (that is PrivDesc0 through to PrivDesc239), you must remember to increment PrivBitsTotal by 1. For example, if you've specified 5 custom privileges using the PrivDesc0 through to PrivDesc4 variables, then you should set PrivBitsTotal to 5. It should be noted that this process is only necessary if you are manually adding custom privileges. If you use the Administrative Settings dialog to add custom privileges, VTScada automatically updates the PrivBitsTotal and PrivDescX variables.

Section: SecurityManager-PrivApp

Default: PrivBitsTotal = 61

*No restart required (Settings.Dynamic property)


PrivDescX

Where "X" is the number of the privilege starting at 0. Each PrivDescX variable is set equal to the name of the privilege.

If no custom privileges have been added to your application, the PrivDescX variables are invalid.

Related Variables: The PrivBitsTotal variable represents a running total of the custom privileges you have configured. PrivBitsTotal must always have a value matching the number of PrivDescX variables present for your application.

Section: SecurityManager-PrivApp

Default: PrivDescX = Invalid

When referred to by code, custom privilege numbers are offset by 16. 0 -> 16, 1 -> 17, etc.

Example:

<SECURITYMANAGER-PrivApp>
PrivBitsTotal = 2
AppPrivDefault =
PrivDesc0 = Station 1 Access, 0
PrivDesc1 = Station 2 Access, 1


PromptForBadAltID

Indicates whether users should be prompted if validation of their alternate ID fails during user management. The purpose is to avoid passwords that will be the same on touchtone keypads.

If set to 1 (default), prompt user if validation of their alternate ID fails during user management. Duplicate passwords are disallowed.

If set to 0, do not prompt user if validation of their alternate ID fails during user management. Duplicate passwords are allowed

Section: SecurityManager-Admin

Default: PromptForBadAltID = 1

*No restart required (Settings.Dynamic property)


ReadOnlyStation

The default system privilege mask for a read-only workstation does not grant the configuration privilege or the edit files privilege. If you configure the workstation you are using to be read-only, you will have no means to do further configuration at that workstation, or even to reverse that change. Your only recourse will be to move to another workstation on your system and use the Version Control system to reverse the change.
DEFINING A WORKSTATION TO BE READ-ONLY IS BEST DONE FROM ANOTHER WORKSTATION.

When set to 1 (true), tag write operations on the named workstation will be prevented.

Intended for use with named workstations, therefore this property should be added to a Workstation.Dynamic file rather than Settings.Dynamic.

Section: System

Default: ReadOnlyStation = 0

Related Information:

Read-Only Workstation

StationMaskApp

StationMaskSys


SharedContexts

Matches the field "Enable Shared User Logins" of the security manager's Administrative Options dialog. When set, a user need only sign in once on a workstation for all application contexts that share a security database. This applies to applications that share security with an OEM layer and to the separate contexts of the application and its control buttons in the VAM.

Section: SecurityManager-Admin

Default: SharedContexts = 1


SharedSecurity

Shared Security (Security Provider) is a deprecated feature.
Do not use.
Windows Security Integration is suggested as an alternative.

Matches the field, "Enable Shared Security" of the security manager's Administrative Options dialog. Enables shared security if set to 1 in an OEM layer.

Section: SecurityManager-Admin

Default: SharedSecurity = 0


ShowUserRealm

If the user is assigned to a realm this enabled property will display the username and realm name in the title bar.

Section: System

Default: ShowUserRealm = FALSE

*No restart required (Settings.Dynamic property)


StationMaskApp

Relevant only on workstations whereReadOnlyStation is set. Does not apply otherwise. A full discussion is provided in the topic, Read-Only Workstation.

This is a bitwise value that controls which application privileges are enabled at a read-only workstation. The privileges assigned to the operator will also apply. For a privilege to be accessible, it must be enabled for the operator as well as the workstation. If a privilege is disabled for the person who is logged in, they will still not be able to access that privilege. See also: StationMaskSys

The default system privilege mask for a read-only workstation does not grant the configuration privilege or the edit files privilege. If you configure the workstation you are using to be read-only, you will have no means to do further configuration at that workstation, or even to reverse that change. Your only recourse will be to move to another workstation on your system and use the Version Control system to reverse the change.
*******************************************************
*** DEFINING A WORKSTATION TO BE READ-ONLY ***
*** IS BEST DONE FROM ANOTHER WORKSTATION. ***
*******************************************************
(A remote connection using a VIC or Anywhere client does not count as working at another workstation. Do not proceed unless your application has a Client / Server Configuration)

If creating a StationMaskApp, you are advised to set the workstation property to match the name of the read-only station where it will be in effect. There is no default value for StationMaskApp.

Default:
Section: <SecurityManager-Admin>

Note that <SecurityManager-Admin> is a hidden section. You can create this property using the Application Configuration dialog, but you cannot edit it there.

Application privileges are numbered starting at 16, as shown in the Privileges dialog (Protect Pages and Output Tags) when Show Privilege Numbers is selected.

Bits are numbered starting at zero, and reading from the right to the left. Therefore, to discover which bits to set when creating StationMaskApp, you must subtract 16 from every application privilege as shown in the Privileges dialog. (Privilege 16 is bit 0, privilege 17 is bit 1.)

Using the StationMaskApp property to enable an application privilege that allows authorized operators to write through a protected I/O tag will have no effect. Read-only stations cannot write to I/O under any circumstances. Any privilege to allow I/O writes is meaningless at a read-only station.


StationMaskSys

Relevant only on workstations whereReadOnlyStation is set. Does not apply otherwise. A full discussion is provided in the topic, Read-Only Workstation.

The default system privilege mask for a read-only workstation does not grant the configuration privilege or the edit files privilege. If you configure the workstation you are using to be read-only, you will have no means to do further configuration at that workstation, or even to reverse that change. Your only recourse will be to move to another workstation on your system and use the Version Control system to reverse the change.
*******************************************************
*** DEFINING A WORKSTATION TO BE READ-ONLY ***
*** IS BEST DONE FROM ANOTHER WORKSTATION. ***
*******************************************************
(A remote connection using a VIC or Anywhere client does not count as working at another workstation. Do not proceed unless your application has a Client / Server Configuration)

This is a bitwise value that controls which system privileges are enabled at a read-only workstation. The privileges assigned to the operator will also apply. For a privilege to be accessible, it must be enabled for the operator as well as the workstation. This mask does not grant privileges to those who do not otherwise possess them. See also: StationMaskApp

StationMaskSys can be set in different layers of VTScada. The privileges of each layer will inherit the privileges of the parent layer before it. Privileges enabled or disabled at the VTS Library layer will be overwritten by privileges at the OEM layer and the result will be overwritten again at the Application layer.

In the following example, the bitwise value has been shortened to 8 bits for the sake of brevity.

If StationMaskSys is set to 11111111 at the VTS Library layer, 0000 at the OEM layer and 11 at the Application layer...

Then the value at the OEM layer will become 11110000 (taking the VTS Library layer and adulterating it with the OEM layer value) and....

Then the value at the Application layer will become 11110011 (taking the OEM layer value and adulterating it with the Application layer value).

Leaving the StationMaskSys set to Default

While there is a default value for this property, it will not be visible in your Application Configuration dialog.

The default is copied below for your convenience and can be used as a starting point when defining your own StationMaskSys. A comment is provided above the value to help you count the bits from right to left.

Section:  <SecurityManager-Admin>
;                60       50        40        30        20        10
;                0987654321098765432109876543210987654321098765432109876543210
StationMaskSys = 0000011010010100110000100001010000000100000000000101000000100

The default value permits only the following privileges. The signed on operator must also posses these privileges, because setting a privilege in the station mask does not grant that privilege to any operator who has not already been granted it.

(The following refers to the default value, as shown in the example.)

2 - Account Modify

9 - Application Stop

11 - Tag Parameter View

23 - Thin Client Access

31 - Alarm Page Access

33 - History Page Access

38 - Page Note Hide

43 - Sites Page Access

44 - Maps Page Access

49 - Global Tag & Area Filter

52 - Recipe Page Access

54 - Remote Tag Value/History Retrieve

55 - Service Page Access

As new privileges become available, their default value will be provided.

Setting customized privileges with StationMaskSys

When setting a custom StationMaskSys value be aware that any missing bits will be padded on the end with a 1, enabling those privileges.

As new privileges are added the bitwise length will inevitability change. If your custom StationMaskSys value is shorter than the new default, the missing bits will default as enabled until the value is updated. No matter what the default value of the new privilege is in a default StationMaskSys, it will be enabled in an unchanged custom StationMaskSys value.

Bit Number | System Privilege
0 | Configure
1 | Account View
2 | Account Modify
3 | Accounts Manager
4 | Security Administrator
5 | Alarm Disable
6 | Manual Data
7 | Questionable
8 | Alarm Acknowledge
9 | Application Stop
11 | Tag Parameter View
14 | Edit Files
15 | Deploy Changes
16 | Revert Changes
17 | Page Add
18 | Page Modify
19 | Page Delete
20 | Tag Add/Copy
21 | Tag Modify
22 | Tag Delete
23 | Thin Client Access
24 | Alarm Mute
25 | Alarm Silence
26 | Group Modify
27 | Group Save
28 | Group Delete
29 | Pen Modify
30 | Note Add
31 | Alarm Page Access
32 | Reports Page Access
33 | History Page Access
34 | Deprecated
35 | Thin Client Monitor Access
36 | Thin Client Monitor Admin
37 | Page Note Edit
38 | Page Note Hide
39 | Advanced Version Control
40 | Application Manager View
41 | Manage Tag Types
42 | Alarm Shelve
43 | Sites Page Access
44 | Maps Page Access
45 | Operator Notes Page Access
46 | Edit Data
47 | Remote Data Access
48 | Control Outputs
49 | Global Tag & Area Filter
50 | Change recipes
51 | Start recipe batches
52 | Open the Recipe & Batch Management Page
53 | Edit contacts in Roster tags.
54 | Restricts access to the main History table when making remote queries. (Access to defined SQL Views can permitted on a tag-by-tag basis.)
55 | User may access the Services page
56 | User may force a service to change servers
57 | User can create Control Locks and can remove Control Locks over which the user has "ownership"
58 | User can remove any Control Lock
59 |
60 | Able to release a control token from any tag.


SysPrivDefault

Indicates the default general privileges available to those users who are not signed in to the application. The defined general privileges will also be granted to newly-created user accounts by default.

Related Privileges: AppPrivDefault

You may also define default application-specific privileges to those users who are not signed in to the application. The defined custom privileges will also be granted to newly-created user accounts by default.

Section: SecurityManager-Admin

Default: SysPrivDefault =

*No restart required (Settings.Dynamic property)


SysPrivSuppress

Indicates whether general privileges have been suppressed or revealed. Each digit following the SysPrivSuppress variable represents a general privilege, each of which can be turned on or off using a "0", a "1", or a "2" respectively. Digits have meaning according to their placement counting from the right. Leading zeros are not required

If set to "0", the associated general privilege is revealed.

If set to "1", the associated general privilege is suppressed in all security dialogs, except the Administrative Settings dialog.

If set to "2", the associated general privilege is suppressed in all security dialogs, including the Administrative Settings dialog.

By default, all general privileges are revealed in all security dialogs. A table showing the index of each general privilege in the SysPrivSuppress variable can be found in: Suppress and Reveal System Privileges Using the SysPrivSuppress Variable.

Section: SecurityManager-Admin

Default: SysPrivSuppress = 00000000000000000000000000000000000

*No restart required (Settings.Dynamic property)


UserName

Indicates the registered username of the signed in user. If no user is signed in to the application, UserName will be invalid.

Section: n/a

Default: Username = Invalid


VICSmartcardsEnable

If set to 1 (TRUE), and if all supporting configuration has been completed, operators may authenticate their identity at a VTScada Internet Client (VIC) using a smart card. See: Smart Card Support

Section: <SECURITYMANAGER-ADMIN>

Default: VICSmartcardsEnable =


Tag Properties

Variables in this section relate to tags.

Refer to the side menu for the listing of properties in this section.


AnalogControlName

The label displayed in the Tag Browser for the analog control tag type.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.


AnalogScaledMaxDefault

Applies only to Analog Status and Analog Control tags, not to I/O and Calculations tags.

Holds the default value for the maximum scaled value, corresponding to the maximum unscaled value as read from hardware.

This value is used in the scaling tab when configuring new analog tags.

Section: System

Default: AnalogScaledMaxDefault = 100

*No restart required (Settings.Dynamic property)


AnalogScaledMinDefault

Applies only to Analog Status and Analog Control tags, not to I/O and Calculations tags.

Holds the default value for the minimum scaled value, corresponding to the minimum unscaled value as read from hardware.

This value is used in the scaling tab when configuring new analog tags.

Section: System

Default: AnalogScaledMinDefault = 0

*No restart required (Settings.Dynamic property)


AnalogStatusName

The label displayed in the Tag Browser for the analog status tag type.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.


AnalogUnscaledMaxDefault

Applies only to Analog Status and Analog Control tags, not to I/O and Calculations tags.

Holds the default value for the maximum unscaled value (raw equipment value) as read from hardware.

This value is used in the scaling tab when configuring new analog tags.

Section: System

Default: AnalogUnscaledMaxDefault = 4095

*No restart required (Settings.Dynamic property)


AnalogUnscaledMinDefault

Applies only to Analog Status and Analog Control tags, not to I/O and Calculations tags.

Holds the default value for the minimum unscaled value (raw equipment value) as read from hardware.

This value is used in the scaling tab when configuring new analog tags.

Section: System

Default: AnalogUnscaledMinDefault = 0

*No restart required (Settings.Dynamic property)


AreaExclude

Used by Tag Area Filtering

Controls whether tags belonging to any area not listed in the [AREAS] section of the Workstation.Startup configuration file will be excluded from being loaded at startup, or will be loaded at startup (see: Tag Area Filtering).

If AreaExclude is set to 0 (false), then all tags belonging to areas not listed in the [AREAS] section of Settings.Startup are loaded at startup.

If AreaExclude is set to 1 (true), then all tags belonging to areas not listed in the [AREAS] section of Settings. Startup are not loaded at startup.

Related Variables: The AreaFilter variable must be set to 1 (true - which it is by default) in order for area filtering to work.

Section: System

Default: AreaExclude = 0

*Restart Required (Settings.Startup property)


AreaFilter

Used by Tag Area Filtering

Controls whether the settings of the [AREAS] section and the AreaExclude variable of the Settings. Startup file will be ignored or observed.

If set to 1 (true), then both the [AREAS] section and the AreaExclude variable in Settings. Startup are observed.

Section: System

Default: AreaFilter = 1

*Restart Required (Settings.Startup property)


Areas

Viewing: Reference > Property Reference > Tag Properties > Areas

[Areas]

File: Workstation.Startup

When added to one or more of an application's Workstation.Startup files, the [AREAS] section enables you to perform tag area filtering. In summary, you list the tag areas that you wish to load on a given workstation, followed by an equals sign, followed by a 1.

Example:

[AREAS]
AreaA = 1
AreaB = 1

The result of this example is that, for the workstation matching the name .Startup file name that these values are stored in, tags configured with AreaA or AreaB as their Area property will be loaded at startup. If the AreaExclude variable is set to 1 in the [System] section of the file, then only tags with these areas will be loaded.

Related information:

Tag Area Filtering Details and examples.


CameraTagConnectionLimit

Override the Camera Tag maximum connection limit. The default connection limit is 15. Exceeding the Camera Tag default connection limit may slow VTScada. Note that the maximum number that can be set is 50 as the HTTP client also has a maximum 50 connection limit. The maximum connection limit cannot be exceeded.

Section: System

Default: CameraTagConnectionLimit = 15

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


CanRedefineOEMType

The security privilege, Manage Tag Types must be granted to your account before you can edit any tag type, whether user-defined or OEM.

This property must be set to 1 (true) before you will be able to redefine OEM tag types. You are advised to use caution if setting this property to 1. The act of redefining an OEM type can have effects that are both undesirable and difficult to reverse.

Default: CanRedefineOEMType = 0

Section: System

*No restart required (Settings.Dynamic property)


DefaultAnalogDeadbandFractionOfFullScale

Use this to set a default deadband that limits logging of Analog Status tags to changes that exceed a calculated threshold.

The deadband will be calculated as the Display Range multiplied by this value. If a Display Range is not configured, the Max Scale Value minus the Min Scale Value will be used.

Defaults to one quarter of one percent.

Section: System

Default: DefaultAnalogDeadbandFractionOfFullScale = 0.0025

*No restart required (Settings.Dynamic property)

Related Properties:

DefaultCalculationDeadbandFractionOfFullScale

DefaultDriverDeadbandFractionOfFullScale


DefaultCalculationDeadbandFractionOfFullScale

Use this to set a default deadband for the display and logging of Calculation tags. The deadband will be calculated as the High Scale Value minus the Low Scale Value, multiplied by this value.

The default value of this property is 0.0025, resulting in a default deadband value of 0.25 being applied to all calculation tags that are not otherwise configured. (Default values for High Scale and Low Scale are 100 and zero, respectively.)

Section: System

Default: DefaultCalculationDeadbandFractionOfFullScale = 0.0025

*No restart required (Settings.Dynamic property)

Related Properties:

DefaultAnalogDeadbandFractionOfFullScale

DefaultDriverDeadbandFractionOfFullScale


DefaultDriverDeadbandFractionOfFullScale

Use this to set a default deadband that limits the values read by analog tags to changes that exceed a calculated threshold.

The deadband will be calculated (in part) as the Display Range multiplied by this value. If a Display Range is not configured, the Max Scale Value minus the Min Scale Value will be used.

Defaults to one tenth of one percent.

Section: System

Default: DefaultDriverDeadbandFractionOfFullScale = 0.0010

*No restart required (Settings.Dynamic property)

Related Properties:

DefaultAnalogDeadbandFractionOfFullScale

DefaultCalculationDeadbandFractionOfFullScale


DigitalControlName

The label displayed in the Tag Browser for the digital control tag type.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.


DigitalStatusName

The label displayed in the Tag Browser for the digital status tag type.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.


DisableControlWidgetIfMismatched

TRUE to disable a control widget if it is currently executing (Select Before Operate)

Section: System

Default: DisableControlWidgetIfMismatched = 0

*No restart required (Settings.Dynamic property)

Related properties:

DisableControlWidgetIfSelected

DisableControlWidgetIfOtherMismatched

DisableControlWidgetIfOtherSelected

DisabledControlWidgetOpacity


DisableControlWidgetIfOtherMismatched

TRUE to disable a control widget if another control is currently executing (Select Before Operate).

Default: DisableControlWidgetIfOtherMismatched = 0

Section: System

Related properties:

DisableControlWidgetIfSelected

DisableControlWidgetIfMismatched

DisableControlWidgetIfOtherSelected

DisabledControlWidgetOpacity


DisableControlWidgetIfOtherSelected

TRUE to disable a control widget if another control has already "selected" a value (Select Before Operate)

Default: DisableControlWidgetIfOtherSelected = 0

Section: System

Related properties:

DisableControlWidgetIfMismatched

DisableControlWidgetIfSelected

DisableControlWidgetIfOtherMismatched

DisabledControlWidgetOpacity


DisableControlWidgetIfSelected

TRUE to disable a control widget if it has already "selected" a value (Select Before Operate)

Default: DisableControlWidgetIfSelected = 0

Section: System

Related properties:

DisableControlWidgetIfMismatched

DisableControlWidgetIfOtherSelected

DisableControlWidgetIfOtherMismatched

DisabledControlWidgetOpacity


DisabledControlWidgetOpacity

Relevant to output widgets that:

  • Use an image rather than text
  • Can be disabled.

When the control widget is disabled by any means, it will be made partially transparent by the amount specified in this property. Opacity can range from 0 (invisible / not drawn) to 1 (fully visible).

(Control widgets that use text rather than an image are "grayed-out" when disabled.)

Section: System

Default: DisabledControlWidgetOpacity = 0.4


DiscretesWithoutEquipmentTypeUseDigitalLabels

TRUE for a discrete tag to use digital labels from a Style Settings tag when the discrete has no EquipmentType.

FALSE to just show the discrete number. Only applies for discrete values 0-4.

Section: System

Default: DiscretesWithoutEquipmentTypeUseDigitalLabels = FALSE

*No restart required (Settings.Dynamic property)


EnableSiblingTagAutoLinking

When disabled, tags will automatically link to their ancestor tag. This was the default behavior just prior to Version 12.2. When enabled, tags will automatically link to direct ancestors or uncle tags first or else sibling tags if a relevant sibling is available.

This setting is disabled by default in applications that were created before the release of VTScada 12.2.

This setting is enabled by default in applications that were created after the release of VTScada 12.2.

If you enable this property in an application that was created before the release of VTScada 12.2, any tags that have established a link to other tags with an auto-linking configuration ( [*TagType] ex. [*Drive], [*Port] etc) may automatically link to tags in a way that you did not anticipate and could break your application.

Section: System

Default: Special. See notes.

*Restart Required (Settings.Startup property)


HelpFile

Sets the name of the help file with which tags are to be associated. For full information, see: Custom Help Files

Section: System

Default: HelpFile = VTSHelp\MadCapWebHelp

*No restart required (Settings.Dynamic property)

Related Information:

Custom Help Files - Examples and required preparation

OEMHelp

SetHelp


InvalidText

Text to display for tags whose data value is invalid. Not used by all widgets.

Section: System

Default: InvalidText = ??

*Restart Required (Settings.Startup property)


NewTagPublishParmValue

Set the default for the value of the Publish setting in new publishable tags.

This setting defaults to TRUE in new applications and FALSE in applications that existed before the introduction of this property in version 12.2.

Section: System

Default: NewTagPublishParmValue = 1

*No restart required (Settings.Dynamic property)


OpenSitesAsPopup

Applies to all sites whose opening behavior is not explicitly configured. Set 1 (true) to open a site page from the Sites page as a pop-up. Set to 0 (false) to open it embedded in the Sites page

Section: System

Default: OpenSitesAsPopup = 0

*No restart required (Settings.Dynamic property)


ParmChangedColor

Sets the background color to be used in configuration panels when tag parameters are changed. Defaults to a light green.

Section: System

Default: ParmChangedColor = 63

*No restart required (Settings.Dynamic property)


ParmInfoCreatedByLabel

Used only when ParmInfoHistoryEnabled is set to 1 (true) and there is a record of who created the value.

Controls the format of the tool tip that displays information about the creation of the configuration panel variable being pointed to.

Accepts up to three string parameters of the format %s, in the following order: creator name, creation date, creation time.

Section: <LABELS>

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Default: ParmInfoCreatedByLabel = Tag created by %s on %s at %s

*No restart required (Settings.Dynamic property)


ParmInfoCreatedOnLabel

Used only when ParmInfoHistoryEnabled is set to 1 (true) and there is no record of who created the value.

Controls the format of the tool tip that displays information about the creation of the configuration panel variable being pointed to.

Accepts up to two string parameters of the format %s, in the following order: creation date, creation time.

Section: <LABELS>

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Default: ParmInfoCreatedOnLabel = Tag created on %s at %s

*No restart required (Settings.Dynamic property)


ParmInfoDateFormat

Sets the format of the date displayed in the tag creation or modification history tooltips.

While you may override the value with a date format (see: Date Formatting Strings) you are advised to use the phrase editor instead. The ID for the phrase is shown as the default value for this parameter.

Section: Labels

Default: ParmInfoDateFormat = DateFmtFullWrittenWithDOW

*No restart required (Settings.Dynamic property)


ParmInfoHistoryEnabled

When enabled (set to 1) details about the most recent change to a tag's parameter can be viewed by hovering over that parameter in the properties dialog.

Those details are displayed according to the formats stored in the phrases for your current language. See the list of related phrase keys.

Section: System

Default: ParmInfoHistoryEnabled = 1

Related phrase keys:

ParmInfoCreatedByLabel

ParmInfoCreatedOnLabel

ParmInfoDateFormat

ParmInfoLastModByLabel

ParmInfoLastModOnLabel

ParmInfoTimeFormat


ParmInfoLastModByLabel

Used only when ParmInfoHistoryEnabled is set to 1 (true) and there is a record of who modified the value.

Controls the format of the tool tip that displays information about the modification of the configuration panel variable being pointed to.

Accepts up to three string parameters of the format %s, in the following order: name of the user who modified the value, modification date, modification time.

Section: <LABELS>

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Default: ParmInfoLastModByLabel = Modified by %s on %s at %s

*No restart required (Settings.Dynamic property)


ParmInfoLastModOnLabel

Used only when ParmInfoHistoryEnabled is set to 1 (true) and there is no record of who modified the value.

Controls the format of the tool tip that displays information about the modification of the configuration panel variable being pointed to.

Accepts up to two string parameters of the format %s, in the following order: modification date, modification time.

Section: <LABELS>

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Default: ParmInfoLastModOnLabel = Modified on %s at %s

*No restart required (Settings.Dynamic property)


ParmInfoTimeFormat

Sets the format of the time displayed in the tag creation/modification history tooltips.

Section: Labels

Default: ParmInfoTimeFormat =

*No restart required (Settings.Dynamic property)


PLCAlarmCfgDeadbandDigits

Controls the number of digits after the decimal for the deadband of the PLC Alarm tag.

Section: System

Default: PLCAlarmCfgDeadbandDigits = 2

*No restart required (Settings.Dynamic property)


PLCAlarmCfgDelayDigits

Controls the number of digits after the decimal for the delay property of a PLC Alarm tag.

Section: System

Default: PLCAlarmCfgDeadbandDigits = 2

*No restart required (Settings.Dynamic property)


PLCAlarmCfgSetpointDigits

Controls the number of digits after the decimal for the setpoint of the PLC Alarm tag.

Section: System

Default: PLCAlarmCfgSetpointDigits = 2

*No restart required (Settings.Dynamic property)


PulseInName

Indicates the label to display in the title bar of the tag properties folder for Data Flow Pulse Input tags. This label also determines the label that is displayed in the Tag Browser’s Types drop-down list for the pulse input tag type.

Section: <LABELS>

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Default: PulseInName = Pulse Input

*Restart Required (Settings.Startup property)


ParmOverrideColor

Sets the color to be used in configuration panels when child tag properties are overridden. Defaults to pale orange.

Section: System

Default: ParmOverrideColor = 183

*No restart required (Settings.Dynamic property)


RateOfChangeTagRPCInterval

In a multi-server application, Rate of Change Tag information is distributed from the server to workstations at regular intervals, as set by this value. The update frequency is measured in seconds.

Section: System

Default: RateOfChangeTagRPCInterval = 60

*No restart required (Settings.Dynamic property)


RateOfChangeTagRPCThreshold

In a multi-server application, Rate of Change Tag information is distributed from the server to workstations at regular intervals (see: RateOfChageTagRPCInterval) or when the tag’s value has changed by at a relative amount.

This variable sets the percentage amount by which the rate of change value must change before it will be distributed from the server to client workstations.

Section: System

Default: RateOfChangeTagRPCThreshold = 5

*No restart required (Settings.Dynamic property)


RecordManualDataInEventLog

When set to 1 (TRUE) an event will be logged each time the manual data value of any tag is modified by an operator. Changes made by parameter expressions or by rolling back to an earlier version are not logged.

The event record will include:

  • The name, area, and description of the tag.
  • The name of the user who changed the value and the machine ID of the workstation where this was done.
  • The time and date of the change.
  • The value and units of the new value.

Section: System

Default: RecordManualDataInEventLog = 1

*No restart required (Settings.Dynamic property)


RememberNewTagParameters

When set to the default value of 1 (true), new tags will initialize to the same parameters as the last tag created. This behavior can be disabled by setting the value to 0, thus causing all new tags to initialize as if they were the first ones being created in the application.

Section: System

Default: RememberNewTagParameters = 1

*No restart required (Settings.Dynamic property)


SiteToolsConfirmOutput

Used by the automatically-generated output controls in a Site Details page. When set to 1 (true), operators must confirm all control actions sent from the Site Details page. If set to 0 (false), no confirmation is required.

Section: System

Default: SiteToolsConfirmOutput = 1

*No restart required (Settings.Dynamic property)


SparkplugBEngUnitsProperty

Engineering units identifier label for Sparkplug B/MQTT driver. This is one of the keys within a Metric's Properties array used to determine which property carries the units for a given metric. Wildcards are valid. The default will match any string that contains "Unit" (it is not case sensitive).

Section: System

Default: SparkplugBEngUnitsProperty = *Unit*

*No restart required (Settings.Dynamic property)

Related information:

SparkplugBRangeMaxProperty

SparkplugBRangeMinProperty


SparkplugBRangeMaxProperty

Range maximum identifier label for Sparkplug B. This is one of the keys used within a Metric's Properties array to extract extra tag information.

Section: System

Default: SparkplugBRangeMaxProperty = engHigh

*No restart required (Settings.Dynamic property)

Related information:

SparkplugBEngUnitsProperty

SparkplugBRangeMinProperty


SparkplugBRangeMinProperty

Range minimum identifier label for Sparkplug B. This is one of the keys used within a Metric's Properties array to extract extra tag information.

Section: System

Default: SparkplugBRangeMinProperty = engLow

*No restart required (Settings.Dynamic property)

Related information:

SparkplugBEngUnitsProperty

SparkplugBRangeMaxProperty


SparkplugLegacySTATE

For the MQTT client driver acting as a SCADA/IIoT host. Enable if you want the driver to use the legacy pre- 3.0.0 STATE topic and message format.

Current format

State topic example: "spBv1.0/STATE/SCADAHostID"

Message payload (JSON format): {"online" : true or false, "timestamp" : ts}

Legacy format

State topic example: "STATE/SCADAHostID"

Message payload: OFFLINE or ONLINE

Section: System

Default: SparkplugLegacySTATE = 0

*No restart required (Settings.Dynamic property)

Related information:

MQTT Client Driver


SQLLoggerDefaultLogInterval

Indicates the interval between log entries.

Section: System

Default: SQLLoggerDefaultLogInterval = 60

*Restart Required (Settings.Startup property)


SQLLoggerDefaultMaxDataAge

Controls the default for the "Auto-Delete Records Older than (days)" parameter of the SQLLoggerGroup.

Section: System

Default: SQLLoggerDefaultMaxDataAge = 365

*Restart Required (Settings.Startup property)


SQLLoggerDefaultTagDataTableName

Indicates the table name the logger expects to find in the log database, to use for writing tag value information.

Section: System

Default: SQLLoggerDefaultTagDataTableName = VTS_TAGDATA

*Restart Required (Settings.Startup property)


SQLLoggerDefaultTagIdTableName

Indicates the table name the logger expects to find in the log database, to use for writing tag ID information.

Section: System

Default: SQLLoggerDefaultTagIdTableName = VTS_TAGID


SQLLoggerDeleteInterval

Indicates in seconds, how often to purge old records. By default, this runs daily.

Section: System

Default: SQLLoggerDeleteInterval = 86400

*No restart required (Settings.Dynamic property)


SQLLoggerDeleteOffset

Indicates, in seconds for each logger delete interval, how long after the beginning of the interval the purge should occur. Taken with the default of 86400 for SQLLoggerDeleteInterval, this sets the purge to take place at 30 seconds past midnight each day.

Section: System

Default: SQLLoggerDeleteOffset = 30

*No restart required (Settings.Dynamic property)


SQLLoggerGroupSharedRPC

If set to 1 (true) then the same RPC service will be used for all instances of SQLLoggerGroup, making it easier to specify which server to use for all SQL Logger Groups.

Section: System

Default: SQLLoggerGroupSharedRPC = 0

*Restart Required (Settings.Startup property)


SQLLoggerLogInvalids

Indicates whether invalid values should be logged by the SQL logger.

Section: System

Default: SQLLoggerLogInvalids = 1

*Restart Required (Settings.Startup property)


TagField1Name

Indicates the field name for the first field in the tag properties folders for all tag types.

It is NOT recommended that you modify this variable, as doing so may adversely affect remote configuration.

Related Variables: The TagField2Name and TagField3Name variables enable you to configure the field names for the second and third fields in the tag properties folders for all tag types.

Section: System

Default: TagField1Name = Name

*Restart Required (Settings.Startup property)


TagField2Name

Indicates the field name for the second field in the tag properties folders for all tag types.

It is NOT recommended that you modify this variable, as doing so may adversely affect remote configuration.

Related Variables: The TagField1Name and TagField3Name variables enable you to configure the field names for the first and third fields in the tag properties folders for all tag types.

Section: System

Default: TagField2Name = Area

*Restart Required (Settings.Startup property)


TagField3Name

Indicates the field name for the third field in the tag properties folders for all tag types.

It is NOT recommended that you modify this variable, as doing so may adversely affect remote configuration.

Related Variables: The TagField1Name and TagField2Name variables enable you to configure the field names for the first and second fields in the tag properties folders for all tag types.

Section: System

Default: TagField3Name = Description


UserFilterIconColorize

Boolean (1 or 0) option. When set to 1 (true) the user filter icon will be colorized while a filter is in effect. Defaults to 1.

Default: UserFilterIconColorize = 1

Section: System


UserFilterIconFlash

Boolean (1 or 0) option. When set to 1 (true) the user filter icon will blink while a filter is in effect. Defaults to 0.

Default: UserFilterIconFlash = 0

Section: System


UserFilterMode

Controls which parts of the Global Tag & Area Filtering can be seen and used. Use the following table of values:

UserFilterMode | Meaning
0 | Disable user filtering
1 | Enable user-area filtering only
2 | Enable user-tag filtering only
3 | Enable user-area and user-tag filtering

Default: UserFilterMode = 3

Section: System


Time Synchronization Manager Properties

Variables in this section relate to the Time Synchronization Manager.

Refer to the side menu for the listing of properties in this section.


TimeSyncEnable

Enable or disable the Time Synchronization Manager.

Section: System

Default: TimeSyncEnable = 1

*No restart required (Settings.Dynamic property)

Related Variables: TimeSyncMicroAdjust, TimeSyncUpdtItrvl, TimeSyncRPCQMax.


TimeSyncMicroAdjust

Enables the clock to be adjusted incrementally instead of instantly.

Section: System

Default: TimeSyncMicroAdjust = 1

*No restart required (Settings.Dynamic property)

Related Variables: TimeSyncEnable, TimeSyncUpdtItrvl, TimeSyncRPCQMax.


TimeSyncRPCQMax

Enter the maximum size for the RPC queue on the server. If the RPC queue exceeds this size, no time synchronization will occur.

Section: System

Default: TimeSyncRPCQMax = 500

Related Variables: TimeSyncEnable, TimeSyncMicroAdjust, TimeSyncUpdtItrvl.


TimeSyncUpdtItrvl

Enter the time synchronization update interval in seconds.

Section: System

Default: TimeSyncUpdtItrvl = 900

*No restart required (Settings.Dynamic property)

Related Variables: TimeSyncEnable, TimeSyncMicroAdjust, TimeSyncRPCQMax.


Tooltip Properties

Variables in this section relate to Tool Tips.

Refer to the side menu for the listing of properties in this section.


NoBalloonTips

The style of tooltips for an application.

If set to 0, then tooltips will be displayed in the balloon style.

If set to 1, then tooltips will be displayed in the textbox style.

Section: System

Default: NoBalloonTips = 1

*No restart required (Settings.Dynamic property)


ShowTip

Enables or disables tooltips. If set to 1 (true), then all tooltips are enabled (default).

Section: System

Default: ShowTip = 1

*No restart required (Settings.Dynamic property)

Related information:

TipOff - Sets the duration of the tooltip's display time.

TipOn - Sets the length of the pause before the tooltip will be displayed.


TipBack

Sets the background color for the tooltip displayed when setting a value using a rotary control or a slider.

Affects other tooltips only when visual themes are disabled in Windows.

When changing the TipBack variable, take into consideration the text and outline colors set by the TipFore variable to ensure clear contrast between colors.

Section: System

Default: TipBack =

*Restart Required (Settings.Startup property)

Related information:

VTScada Color Palette - Values that can be used for this property

TipFore - Sets the contrasting foreground color

ShowTip - If it is set to false (0), then all other tooltip variables are ignored.


TipFore

Sets the foreground (text and outline) color for the tooltip displayed when setting a value using a rotary control or a slider.

Affects other tooltips only when visual themes are disabled in Windows.

When changing the TipFore variable, take into consideration the background color set by the TipBack variable, as the background, text, and outline of tooltips must be set in such a way that they can be clearly read.

Section: System

Default: TipFore =

*Restart Required (Settings.Startup property)

Related information:

VTScada Color Palette - Values that can be used for this property

TipBack - Sets the contrasting background color

ShowTip - If it is set to false (0), then all other tooltip variables are ignored.


TipOff

Sets the number of seconds for which a tooltip will be displayed after being activated.

Section: System

Default: TipOff = 10

*Restart Required (Settings.Startup property)

Related information:

ShowTip - If it is set to false (0), then all other tooltip variables are ignored.

TipOn - Sets the length of the pause before the tooltip will be displayed.


TipOn

Sets the time, measured in seconds, for which the pointer must hover over an object before any tooltip linked to that object will be shown.

Section: System

Default: TipOn= 1

*Restart Required (Settings.Startup property)

Related information:

ShowTip - If it is set to false (0), then all other tooltip variables are ignored.

TipOff - Sets the duration of the tooltip's display time.


Trending (HDV) Properties

Variables in this section relate to trending and the Historical Data Viewer page.

Refer to the side menu for the listing of properties in this section.


AITrendEnable

If set to 1 (true), then a windowed version of the Trends page will open when an operator clicks a widget linked to an Analog Input or Analog Status tag.

Section: System

Default: AITrendEnable = 1

*No restart required (Settings.Dynamic property)

Related properties: DITrendEnable


DITrendEnable

Controls whether a pop-up trend window (HDV) will open in response to an operator left-clicking any widget linked to a Digital Status, Digital Input and Pump Status tag.

Does not apply to widgets linked to I/O and Calculations tags.

If set to 1 (true), then a windowed version of the Trends page will open when a digital input tag's widget is clicked while the application is in operation mode.

Section: System

Default: DITrendEnable = 1

Related Variables: AITrendEnable


DontLogTrendPens

Enables you to disable logging to disk of live trend data. By default, pens (tags) that are not logged will display values in the HDV from the moment they are added to a trend graph. To do so, temporary logging must be allowed.

If set to 0 (false), VTScada will log live trend data to disk (default).

Section: System

Default: DontLogTrendPens = 0


HDVAnalogAlarmsVisibility

If set to 1, the setpoint value for any alarms related to analog tags that are being plotted on the graph will be visible.

If set to 0 (default), the setpoint value for any alarms related to analog tags that are being plotted on the graph will be invisible.

Section: System

Default: HDVAnalogAlarmsVisibility = 0

*No restart required (Settings.Dynamic property)


HDVAnalogPenAutoScaling

Sets the behavior of auto scaling of analog pens in the Historical Data Viewer when the Analog Pen Property, Use System Default is selected.

Automatic pen scaling was introduced with version 11.2.22. In upgraded legacy applications, this value will default to 0 (false) to disable automatic scaling. In new applications, this property will default to 1 (true) to enable automatic scaling.

Section: System

Default: HDVAnalogPenAutoScaling = 1

*No restart required (Settings.Dynamic property)

(1 in new applications, 0 in upgraded legacy applications that were created prior to the release of 11.2.22)


HDVAnalogPenAverageVisibility

Sets the default for whether the average value of analog tags is plotted on the graph on the Historical Data Viewer.

If set to 1 (default), then the average values for analog tags will be displayed.

Properties for individual pens may be set using the Pen Properties dialog, available in the legend.

Section: System

Default: HDVAnalogPenAverageVisibility = 1

*No restart required (Settings.Dynamic property)


HDVAnalogPenMinMaxVisibility

Sets the default for whether the peaks (min and max values) of analog tags are plotted on the graph on the Historical Data Viewer.

If set to 1 (default), then the peak values for analog tags will be displayed.

Properties for individual pens may be set using the Pen Properties dialog, available in the legend.

Section: System

Default: HDVAnalogPenMinMaxVisibility = 0

*No restart required (Settings.Dynamic property)


HDVAnalogPenScale

Sets the default scale to be used for all analog plots on the Historical Data Viewer page. This can be one of:

  • Linear
  • Square Root
  • Logarithmic

Properties for individual pens may be set using the Pen Properties dialog, available in the legend.

Section: System

Default: HDVAnalogPenScale = Linear

*Restart Required (Settings.Startup property)


HDVAnalogPenStyle

Sets the default style of the plot line for analog pens on the Historical Data Viewer page.

HDVAnalogPenStyle can be set to one of the following values:

0 - Invisible Plot

1 -Solid

2 -Dashed

3 -Dotted

4 -Dot-dashed

5 -Dot-dot-dashed

Properties for individual pens may be set using the Pen Properties dialog, available in the legend.

Section: System

Default: HDVAnalogPenStyle = 1

*No restart required (Settings.Dynamic property)


HDVAnalogPenVisibility

Sets the default for whether analog tags are plotted on the graph on the Historical Data Viewer page. If set to 1 (default), then analog plots will be visible on the graph after being added to the legend.

If set to 0, then analog plots will not be visible on the graph after being added to the legend.

Properties for individual pens may be set using the Pen Properties dialog, available in the legend.

Section: System

Default: HDVAnalogPenVisibility = 1

*No restart required (Settings.Dynamic property)


HDVAnalogPenWidth

Sets the default width of analog tags plotted on the graph on the Historical Data Viewer.

Defaults to 1 pixel.

Properties for individual pens may be set using the Pen Properties dialog, available in the legend.

Section: System

Default: HDVAnalogPenWidth = 1


HDVAnalogScalesVisibility

Sets the default for whether value scales should be displayed to the side of the analog plot area on the Historical Data Viewer page.

If set to 1, the value scales will be displayed (default).

Properties for individual pens may be set using the Pen Properties dialog, available in the legend.

Section: System

Default: HDVAnalogScalesVisibility = 1

*No restart required (Settings.Dynamic property)


HDVDataRetrievalWaitTime

Defines the number of seconds to wait before displaying a message that HDV data retrieval is under way.

Section: System

Default: HDVDataRetrievalWaitTime = 2

*No restart required (Settings.Dynamic property)


HDVDateFormat1

Set the date format to display beneath the plot areas on the Historical Data Viewer page when the duration is set to low increments. The value may use any of date formatting codes, date formatting strings or phrase identifier keys within the default languages file. (Date Formatting Codes, Date Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: HDVDateFormat1 = DateFmtMonthDay

*No restart required (Settings.Dynamic property)


HDVDateFormat2

Set the date format to display beneath the plot areas on the Historical Data Viewer page when the duration is set to high increments. The value may use any of date formatting codes, date formatting strings or phrase identifier keys within the default languages file. (Date Formatting Codes, Date Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: HDVDateFormat2 = DateFmtFullWritten

*No restart required (Settings.Dynamic property)


HDVDigitalGridColor

Sets the color to display for the vertical grid lines on the digital plot area on the Historical Data Viewer page. The default color is pale gray.

Section: System

Default: HDVDigitalGridColor = 245

*No restart required (Settings.Dynamic property)


HDVDigitalPenVisibility

Sets the default visibility of digital tags plotted on the graph on the Historical Data Viewer page. If set to 1 (default), then digital plots will be visible on the graph after being added to the legend.

Section: System

Default: HDVDigitalPenVisibility = 1

Related properties: HDVNotesLineVisibility

*No restart required (Settings.Dynamic property)


HDVDigitalScalesVisibility

Sets the default for whether the value scales should be displayed beside the digital plot area on the Historical Data Viewer page. If set to 1, the value scales will be displayed.

Properties for individual pens may be set using the Pen Properties dialog, available in the legend.

Section: System

Default: HDVDigitalScalesVisibility = 1

*No restart required (Settings.Dynamic property)


HDVDisplayTimeSelectionScrollBar

Controls whether the Date/Time scrollbar on the Historical Data Viewer page should be visible.

If set to 1, the Date/Time scrollbar will be visible.

Section: System

Default: HDVDisplayTimeSelectionScrollBar = 1

*No restart required (Settings.Dynamic property)


HDVDisplayToolbar

Controls whether the toolbar on the Historical Data Viewer page should be visible. If set to 1, the toolbar will be visible.

Section: System

Default: HDVDisplayToolbar = 1

*No restart required (Settings.Dynamic property)


HDVGridCellColor

If set, this value provides a default color for the cells in the Grid view of the Historical Data Viewer

Section: System

Default: HDVGridViewColor = 15

*No restart required (Settings.Dynamic property)


HDVGridViewColor

If set, this value provides a default color for the grid view in the Historical Data Viewer.

Section: System

Default: HDVGridViewColor =

*No restart required (Settings.Dynamic property)


HDVGridViewSortOrder

Enables the sorting of the Historical Data Viewer Grid by timestamp in either ascending or descending order.

If set to 0 (the default) the order will be ascending, meaning that the most recent value is at the bottom of the page with older values scrolling off the top of the page.

If set to 1, the order will be descending.

Section: System

Default: HDVGridViewSortOrder = 0

*No restart required (Settings.Dynamic property)


HDVHorizontalGridColor

Controls the color of the horizontal grid lines on the analog plot area on the Historical Data Viewer page. The default color is pale gray.

Section: System

Default: HDVHorizontalGridColor = 245

*No restart required (Settings.Dynamic property)


HDVLayoutBGColor

Controls the color for the background of the area surrounding the Date/Time scroll bar at the bottom of the Historical Data Viewer page.

Section: System

Default: HDVLayoutBGColor = 15

*No restart required (Settings.Dynamic property)


HDVLayoutTextColor

Controls the color used for text in the Historical Data Viewer, outside the area of the graph or grid.

Defaults to 0 (Black)

Section: System

Default: HDVLayoutTextColor = 0

*No restart required (Settings.Dynamic property)


HDVLegendVisible

Controls whether the legend pane on the Historical Data Viewer page should be visible. If set to 1, the legend will be visible. If set to 0, the legend will be invisible.

Section: System

Default: HDVLegendVisible = 1

*No restart required (Settings.Dynamic property)


HDVMaxDataSources

Sets the maximum number of pens that will display on the Historical Data Viewer page. "Pen" refers to all data sources displayed on the graph and includes notebooks. This limit applies to all pens including analog tags, digital tags and notebooks.

Selected pens in excess of this number are not shown. There is no warning.

Section: System

Default: HDVMaxDataSources = 100

*No restart required (Settings.Dynamic property)


HDVNotesLineVisibility

Controls whether vertical lines should be drawn on the graph on the Historical Data Viewer page to indicate the presence of a note. If set to 1, a vertical line will be displayed on the graph to indicate the presence of a note. I

Section: System

Default: HDVNotesLineVisibility = 1

Related property: HDVNotesPenVisibility

*No restart required (Settings.Dynamic property)


HDVNotesPenVisibility

Controls whether arrows should be drawn on the graph on the Historical Data Viewer page to indicate the presence of a note. If set to 1, an arrow will be displayed on the graph to indicate the presence of a note.

Section: System

Default: HDVNotesPenVisibility = 1

*No restart required (Settings.Dynamic property)


HDVPlotBGColor

Enables you to change the background color of the plot area of the graph on the Historical Data Viewer page. The default color is white (15).

Section: System

Default: HDVPlotBGColor = 15

*No restart required (Settings.Dynamic property)


HDVPlotSigFigs

Controls the number of significant figures used in the Historical Data Viewer pen legend for analog values. Note that this refers to significant figures, not digits after the decimal point.

Section: System

Default: HDVPlotSigFigs = 3

All digits to the left of the decimal point will always be shown, regardless of the value of this property.

Examples:

Value | HDVPlotSigFigs | Shown in Legend
12.567 | 1 | 13
12.567 | 2 | 13
12.567 | 3 | 12.6
125.67 | 3 | 126
125.67 | 5 | 125.67
125.67 | 6 | 125.67

*No restart required (Settings.Dynamic property)


HDVPlotTextColor

Controls the color used for text in the Historical Data Viewer, within the area of the graph or grid.

Defaults to 0 (Black)

Section: System

Default: HDVPlotTextColor = 0

*No restart required (Settings.Dynamic property)


HDVPlotViewColor

Enables you to indicate the background color to display around the legend (if the legend is present (see HDVLegendVisible above), and the analog and digital plot areas on the Historical Data Viewer page. The default color is the system gray.

Section: System

Default: HDVPlotViewColor =

*No restart required (Settings.Dynamic property)


HDVShowAllScales

Controls whether the value scales should be displayed to the side of the plot areas on the Historical Data Viewer page.

Boolean value, controlling only whether the scale is shown or not. Does not control whether the scale is full or best fit.

Section: System

Default: HDVShowAllScales = 1

*No restart required (Settings.Dynamic property)


HDVShowTimeScales

Controls whether the time scales are displayed beneath the plot area on the Historical Data Viewer page.

Section: System

Default: HDVShowTimeScales = 1

*No restart required (Settings.Dynamic property)


HDVSimpleLegend

Used by the Historical Data Viewer's plot legend to select between a full legend with all statistics, or a simplified legend.

If set to 1 (true) the number of columns displayed in the legend will be reduced.

Section: System

Default: HDVSimpleLegend = 0

*No restart required (Settings.Dynamic property)


HDVTimeCursorColor

Sets the color of the vertical marker line (when enabled) attached to the mouse pointer when over the plot areas of the Historical Data Viewer page. The default color is a medium gray.

Section: System

Default: HDVTimeCursorColor = 7

*No restart required (Settings.Dynamic property)


HDVTimeFormat1

Set the time format to display beneath the plot areas on the Historical Data Viewer page when the duration is set to low increments. The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file. (Time Formatting Codes, Time Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: HDVTimeFormat1 = TimeFmtHM24Hour

*No restart required (Settings.Dynamic property)


HDVTimeFormat2

Set the time format to display beneath the plot areas on the Historical Data Viewer page when the duration is set to high increments. The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file. (Time Formatting Codes, Time Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: HDVTimeFormat2 = TimeFmtHMS24Hour

*No restart required (Settings.Dynamic property)


HDVVerticalGridColor

Controls the color of the vertical grid lines on the analog plot area on the Historical Data Viewer page. The default color is pale gray.

Section: System

Default: HDVVerticalGridColor = 245

*No restart required (Settings.Dynamic property)


IncludeAreaNotesWithTrendedTags

When opening the HDV by clicking on a tag, the default behavior is for all notebooks associated with the tag's area property to be included in the plot.

Set this to 0 to disable the automatic inclusion of area notebooks on the plot.

Section: System

Default: IncludeAreaNotesWithTrendedTags = 1

*No restart required (Settings.Dynamic property)

Related Properties:

IncludeGroupNotesWithTrendedTags


IncludeGroupNotesWithTrendedTags

When opening the HDV by clicking on a tag, the default behavior is to include all notebooks associated with any pen group that the tag is a member of.

Set this to 0 to disable the automatic inclusion of group notebooks on the plot.

Section: System

Default: IncludeGroupNotesWithTrendedTags = 1

*No restart required (Settings.Dynamic property)

Related Properties:

IncludeAreaNotesWithTrendedTags


InterpolateAnalogPlots

Set to 1 to turn on interpolated mode, interpolating data for analog devices.

Section: System

Default: InterpolateAnalogPlots = 0

*No restart required (Settings.Dynamic property)


TempLoggerEnable

Do not enable unless you have identified a clear need to do so. In certain circumstances, having the temporary logger enabled will cause the Historian data store to grow too quickly.

This property exists as a convenience for plotting trends of tags that are not logged. When enabled, a temporary log will be created for the tag, starting at the moment when you add it to the Historical Data Viewer. Temporary logging will continue so long as the HDV window remains open, plotting the tag, plus the number of minutes specified in TempLoggerExpiryPeriod.

Logging is done on change, or every 30 seconds if no change has occurred.

Section: System

Default: TempLoggerEnable =

*No restart required (Settings.Dynamic property)

Related properties: TempLoggerExpiryPeriod


TempLoggerExpiryPeriod

Relevant only if you have set TempLoggerEnable to 1.

Sets the length of time that temporary logging of non-logged tags will continue after the HDV has been closed, or the non-logged tag is removed from the plot.

Section: System

Default: TempLoggerExpiryPeriod = 300

*No restart required (Settings.Dynamic property)

Related properties: TempLoggerEnable


TrendOnTop

Indicates whether an open, windowed version of the Trends page always remains on top or your system pages.

If TrendOnTop is set to 1 (true), then an open, windowed version of the Trends page always appears on top of system pages (default).

Section: System

Default: TrendOnTop = 1


TrendTimeFormat

Set the time format for all times displayed in the trend window. The value may use any of time formatting codes, time formatting strings or phrase identifier keys within the default languages file. (Time Formatting Codes, Time Formatting Strings, Date and Time Phrase Keys)

Section: System

Default: TrendTimeFormat= TimeFmtHMS24Hour


Wizard Engine Properties

Variables in this section relate to the VTScada Wizard Engine.

Refer to the side menu for the listing of properties in this section.


WizardFinishText1

Viewing: Reference > Property Reference > Wizard Engine Properties > WizardFinishText1

WizardFinishText

Text displayed in the Finish screen of a wizard.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: WizardFinishText =

*No restart required


WizardFinishTitle

Title used for the Finish screen of a wizard. The two letter sequence ^W will be replaced by the name of the wizard.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: WizardFinishTitle =

*No restart required


WizardWelcomeLabel

Sets the Welcome label for the wizard engine. The two letter sequence ^W will be replaced by the name of the wizard.

The value may be set using the Languages panel of the Application Configuration dialog. Enable keys in the view dialog to search for the default entry.

Section: System

Default: WizardWelcomeLabel =

*No restart required


[APPS] Section Variables

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The [APPS] section of the Setup.ini configuration file consists of a list of the paths to all the applications that have been added to the VTScada Application Manager's (VAM's) list of available applications. An application must be added to the list before it can be started, or used as an OEM layer without starting.

An example of the syntax of the variables in the [APPS] section:

[APPS]
0 XY\
0 Example\
0 TUTSIM\
1 TUTORIAL\
0 D:\Backups\HydroSCADAApplication

The application directory for each application appears under the [APPS] section. If the application exists within the VTScada directory, a relative path to the application is listed. However, if the application exists outside the VTScada directory, and absolute path (including the drive letter) is given (e.g. the last application in the example above has an absolute path, indicating that this application directory exists outside the VTScada installation or product directory).

Auto Start

Each variable in the [APPS] section is prefaced by either a "0" or a "1", indicating whether the application is an auto start application. Those applications prefaced by a "1" will start automatically when the VTScada program is run.

This is not the list of applications visible in the VAM. Applications may be visible in zero or more lists, as stored in .JSON files within the folder, C:\VTScada\ApplicationManager\Data. (Assuming a default installation to C:\VTScada)

You are advised to use the tools within the VAM to edit the list of applications. Attempting to edit the list in Setup.INI without also editing all matching entries in the relevant .JSON files may cause errors.


[HTTP-Unauthenticated] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

HTTP access to files and folders is restricted to those listed in the [HTTP-Unauthenticated] section of your Setup.INI file. Application folders do not need to be added to this list to run those applications on a thin client. ([HTTP-Unauthenticated] Section)

The default set of files and folders is as follows. For each listed folder, access is allowed to the files in that folder within the VTScada installation and to all of its sub-folders.

[HTTPServer-Permitted]

  Resources\      = 1 ; Allow access to bitmap image libraries
  vts.css         = 1 ; Allow access to vts.css in the {installation} folder
  vts.htm         = 1 ; Allow access to vts.htm in the {installation} folder
  AnywhereClient\ = 1 ; Allow access to features required by the Anywhere Client
  Data\           = 1 ; Allow access to map tiles
  VTS\mobile\     = 1 ; Allow access to features required by the Mobile Client


<LABELS> Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Properties in the <LABELS> section exist only for backward compatibility. Changes to these properties are ignored. You are advised to use the Languages interface to change labels. (Languages)


[LAYER] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The [LAYER] section of the Setup.ini configuration file contains layer-specific, inheritable settings. It functions similarly to the "SYSTEM" section, with the major differences being that all layer settings are dynamic and they are stored internally in the "LayerSettings" object within each layer. This means that unlike "SYSTEM", these values are properly inherited and available to each layer even when the application associated with the layer isn't running.

You can create application-specific overrides of add any of the following properties by adding them to your application's Settings.Dynamic file.

AutoExportToUCDelay

AutoExportToUserCopy

AutomaticDeploy

AutoRecover

ConfigListBroadcastWait

NoIconFile

RepositoryCommentDisable

RepositoryCommentMinLen

RepositoryShowCloneHistory

ScriptIconFile

SyncServAuditDeferTime

SyncServConnectTimeout

SyncServSyncTimeout


AutoExportToUCDelay

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The time period in seconds between a repository notification and a User Copy export. This delay reduces redundant exports.

Section: Layer

Default: AutoExportToUCDelay = 1


AutoExportToUserCopy

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Toggles automatic export of application changes to the user copy.

Section: Layer

Default: AutoExportToUserCopy = 1


AutomaticDeploy

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

All changes are automatically deployed when this flag is non-zero

Section: Layer

Default: AutomaticDeploy = 1


AutoRecover

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Automatically reload Layer working copies from Repository if Layer did not stop safely.

Section: Layer

Default: AutoRecover = 1


ConfigListBroadcastWait

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Time (in seconds) that a machine waits before sending directed notification of a change in the Configuration server list.

Section: Layer

Default: ConfigListBroadcastWait = 10


NoIconFile

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Icon to display in the Information panel when no icon is yet selected

Section: Layer

Default: NoIconFile = Resources\Icons\NoIcon.bmp


RepositoryCommentDisable

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Set to 1 (true) to disable prompting for repository comments

Section: Layer

Default: RepositoryCommentDisable = 0


RepositoryCommentMinLen

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Sets a minimum length for the user comments, stored with version changes, thereby enforcing the use of comments.

Section: Layer

Default: RepositoryCommentMinLen =

Related information:

Commenting Changes


RepositoryShowCloneHistory

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Set to 1 (true) to display version history for branches that existed prior to cloning an application.

Section: Layer

Default: RepositoryShowCloneHistory = 0


ScriptIconFile

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Icon to display in the VAM for script applications

Section: Layer

Default: ScriptIconFile = Resources\Icons\Script.png


SyncServAuditDeferTime

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Time that a server will coalesce audit-only updates before sending them to clients

Section: Layer

Default: SyncServAuditDeferTime = 10


SyncServConnectTimeout

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

On Layer Activation, time that VTScada will wait for a client to acquire a connection to a server.

Section: Layer

Default: SyncServConnectTimeout = 10


SyncServSyncTimeout

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

On Layer Activation, time that VTScada will wait for a client to finish synchronizing with a server.

Section: Layer

Default: SyncServSyncTimeout = 60


[LINKTOLERANCE-…] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

In networked or remote situations, when two workstations connect, the response time from one workstation to the other can vary, partly due to CPU loading, but mostly due to link throughput limitations. The solution to this matter is to set up link tolerances for particular workstations so that other workstations can link them using the specified tolerance values, thereby solving the response time variance.

The purpose is to apply a safety factor to the RPC timeout values. RPCResendDelay, RPCReconnectTime and RPCPingInterval all specify an amount of time to wait before assuming that there has been a communication error and taking action.

A "tolerance factor" is specified as a percentage value, applied to each of the three RPC properties listed above, on a workstation-by-workstation basis. A tolerance factor of "100" is unity, "300" is 3 times the value, and "50" is half of the value. This enables the specification of a set of base and system default values and tolerances for each peer-to-peer connection that requires them.

You ultimately have a series of choices in how you set up the link tolerance values for a particular workstation. In each of the instances described here, you must use "[LINKTOLERANCE-" followed by one of the suffixes in the following table:

Suffix | Description | Example
Workstation Name | Specify the name of the local workstation or a remote workstation (e.g. "FREDSPC"). | [LINKTOLERANCE-FREDSPC]
Workstation IP | Specify the IP address of the local workstation or a remote workstation (e.g. "192.168.5.50"). | [LINKTOLERANCE-198.168.5.50]

Having stated that it is possible to use IPs, it should be noted that we strongly recommend that you use workstation names over IP addresses wherever possible, especially in networks where the workstations may be dual-homed, or where dynamic IPs are assigned. This will help to avoid any miscommunication that could occur in the event that an IP is reassigned to a third workstation while transmissions between two workstations are in progress. Because workstation names are unique, it is good practice to condition yourself to use workstation names, rather than IP addresses, even if yours system configuration does not require the use of workstation names.

After you have established the [LINKTOLERANCE-…] section for a given workstation, you can list the names or IPs of the workstations that will connect to this workstation, followed by the specific link tolerance value each workstation listed should use. Further, you can specify a default tolerance for all workstations (not otherwise specified) to use when connecting to this workstation.

Example:

[LINKTOLERANCE-JOESPC]
Default = 200
[LINKTOLERANCE-FREDSPC]
TARASPC = 300
Default = 150
BILLSPC = 100

This example will cause workstation JOESPC to have a 200% tolerance of all workstations connected to it. FREDSPC will have a 300% tolerance of workstation TARASPC, a 100% tolerance of BILLSPC, and a 150% tolerance of all other workstations.

To resolve ambiguity and provide flexibility, each workstation uses a set of methods and rules to extract the tolerance variable from the Setup.ini file when a connection is established. For further information on these methods and rules, link tolerances, and RPC, see Link Tolerances.


[OEM] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The [OEM] section of the Setup.ini configuration file contains variables that can be used by an original equipment manufacturer (OEM), or system integrator to customize the VTScada software for their company.

The following is a complete list of variables belonging to the Setup.ini configuration file's [OEM] section.

HideVAM

HideWAM

NoSplash


HideVAM

Controls whether the VTScada Application Manager (VAM) is displayed when the VTScada program runs.

Requirements

  • At least one application must be set to auto-run in order for this variable to take effect.

  • User must possess no less than the "Configure" privilege to set.

  • A full restart of VTScada.

This setting can be accessed from Application Config > Edit Properties (Basic mode) > Other tab under the subheading "VTScada Application Manager". The setting is labeled "Hide VAM from users without "Application Manager View" privilege".

When VTScada is running as a service, this setting is ignored and the ability to set it via the application config is disabled.

HideWAM has been replaced by HideVAM. HideWAM will still work in Setup.INI, but is checked only on startup, at which time its value is used to set the newer HideVAM. Run-time code that needs to use hide the VAM must use HideVAM instead of HideWAM.

If set to 0 (false), the VAM is not hidden.

If set to 1 (true), the VAM is hidden when the application restarts automatically. See: AutoStart

Section: System

Default: HideVAM = 0

HideVAM has no effect unless the application is configured to start automatically. DO NOT SET HideVAM unless at least one account has the View Application Manager privilege. (This property will affect unsecured applications, in which case nobody will be able to see the VAM because nobody has the required privilege.)
When HideVAM is set, the VAM will stop when all applications stop.

In applications where HideVAM is enabled, it is recommended that AutoStartDlgTimeout be reconfigured to zero seconds. (AutoStartDlgTimeout = 0).
See the VTScada Application Manager section of the Security Guidelines Manual for more information.

Related information:

AutoStartDlgTimeout


HideWAM

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

(Web Application Manager. VTScada was originally named "WEB")

Controls whether the VTScada Application Manager (VAM) is displayed when the VTScada program runs. At least one application must be set to auto-run in order for this variable to take effect.

HideWAM has been replaced by HideVAM. HideWAM will still work in Setup.INI, but is checked only on startup, at which time its value is used to set the newer HideVAM. Run-time code that needs to hide the VAM must use HideVAM instead of HideWAM.

If set to 0 (false), the VAM is not hidden and is displayed when VTScada runs.

If set to 1 (true), the VAM is hidden when VTScada runs.

Section: System

Default: HideWAM = 0


NoSplash

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

When set to 1 (true) the initial splash screen animation will not run when VTScada starts.

Section: System

Default: NoSplash = 0


[REMOTE] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The Setup.ini [REMOTE] section variables apply to the VTScada Thin Client Server. The server enables remote access to applications using the Internet.

Related information:

ClientCabPath

HTTPServerMaxHeaderLength

HTTPServerMaxHeaders

HTTPServerThreads

ManualVICServerLists

RefreshRate

VICMonitorLogFileName


ClientCabPath

Deprecated. Do not use in new applications. .Cab elements are obsolete in the HTTP server.

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Identifies the path to the VTSX.cab file on the VTScada server. This .cab file is automatically installed when you install the VTScada Browser Support component from the VTScada installation CD. By default, the path to the VTSX.cab file is "VTSX\Distribution\VTSX.cab".

It is unlikely that you will have occasion to change the path defined by ClientCabPath.

Section: System

Default: ClientCabPath = vtsx/distribution/vtsx.cab


HTTPServerMaxHeaderLength

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Limits the amount of work that will be done on malformed (possibly malicious) HTTP request headers. Use this property to set the maximum number of characters (including the terminating CR/LF) in a header line. Any request in excess of this limit will be met with error response 413.

Section: Remote

Default: HTTPServerMaxHeaderLength = 8192

Related information:

HTTPServerMaxHeaders


HTTPServerMaxHeaders

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Limits the amount of work that will be done on malformed (possibly malicious) HTTP request headers. Use this property to set the maximum number of headers that will be permitted in a request. Any request in excess of this limit will be met with error response 413.

Default: HTTPServerMaxHeaders = 100

Section: Remote

Related information:

HTTPServerMaxHeaderLength


HTTPServerThreads

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The HTTPServerThreads variable enables you to configure the number of consecutive threads that may run simultaneously without interfering with one another.

Default: HTTPServerThreads = 50


ManualVICServerLists

Obsolete as of version 12.1.30

Refer to notes in Moving to the Current Version


RefreshRate

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Enables you to designate how often (in seconds) the list of applications will automatically refresh following an AppsList request.

Entering a value of 0 indicates that the AppsList display will not be refreshed.

Section: Remote

Default: RefreshRate = 60


VICDistributionPath

Path to the distribution file for the VTScada Internet Client. Replaces ClientCabPath.

Section: System

Default: VICDistributionPath = VTSX/Distribution/VICSetup.exe

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


VICMonitorLogFileName

Sets the name of the file to which the VTScada Thin Client Monitor application will save log information.

Section: System

Default: VICMonitorLogFileName = VICMonitorLog.txt

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


[RPCManager-AllowIP] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

If present, then only the IP addresses and subnet ranges listed will be permitted to connect to this machine, and this machine will only issue connection attempts to the IP addresses and subnet ranges listed.

The [RPCManager-AllowIP] section is evaluated before the [RPCManager-ExcludeIP] section (see following topic), therefore, any addresses found in the Exclude section will only have effect if they are also permitted by the Allow section - in effect, first being permitted, then finally, being denied.

The effect of the AllowIP section is to provide security by only permitting connections to and from a set of known IP addresses. . This means that if your VTScada system can connect to different subnets, VTScada RPC traffic can be restricted to one of the subnets. This also provides the benefit of allowing you to exclude connections between a development system and a live system.

[RPCManager-ExcludeIP] has no effect unless [RPCManager-AllowIP] has been defined and is not empty.

Example:

[RPCManager-AllowIP]
  IP = 192.168.1.5
       ; Single IPv4 address
  IP = fe80::2063:0bf4:32c4:43ad
       ; Single IPv6 address
  IP = 192.168.0.0/24
       ; IPv4 subnet range
  IP = 2046:470:1f2c:b56/32
       ; IPv6 subnet rangeRPCManager

[RPCManager-ExcludeIP]
  IP = 192.168.0.22

This will allow the individual IPs 192.168.1.5 and fe80::2063:0bf4:32c4:43ad to be used for RPC connections and any computer on the 2046:470:1f2c:b56/32 subnet and any computer in the IPv4 address range 192.168.0.0->192.168.0.255 except for 192.168.0.22.

To refuse all inbound RPC connections and prevent all outbound connections, set only the local machine's IP address in the AllowIP section:

[RPCManager-AllowIP]
IP = 127.0.0.1


[RPCManager-ExcludeIP] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

[RPCManager-ExcludeIP] has no effect unless [RPCManager-AllowIP] has been defined and is not empty.

As described in RAS Clients (see "RAS Clients"), from VTS 5.1502 onwards, a workstation running VTScada can accommodate RAS clients on any subnet, including one already used by a LAN connection. You can achieve this by adding an [RPCManager-ExcludeIP] section to Setup.ini, and instructing the RPC Manager via this section to not create or accept connections with specific IPs or subnet ranges.

By specifying the IP that the RAS host presents as its own IP to the RAS client, the RAS client will not create a connection to the RAS host IP, but will only connect to the other IPs by which the host workstation is known.

For example, if a workstation running VTScada had an IP of 192.168.0.40, and that workstation was configured to support a RAS client, such that the RAS client would see the host workstation as 192.168.0.150, and the RAS client would be assigned an IP address from a pool of addresses from the range of 192.168.0.151 to 192.168.0.155, then the following section should appear in the RAS client's Setup.ini file, so that the RAS client will only make a connection to 192.168.0.40 (which will b done over the RAS link), and not to 192.168.0.150:

[RPCmanager-ExcludeIP]
IP = 192.168.0.150

Note that this is not necessary if the RAS IP address pool is on a different subnet from any other IP of the RAS host, so long as no routing exists between the two subnets.

From VTScada version 5.18 onwards, it is not necessary to exclude any IP addresses on the server, however, if the IP cannot be accessed by a connecting client VTScada system, it is advisable to exclude it from the RPC Manager's view using the method exemplified above.

To refuse all inbound RPC connections and prevent all outbound connections, set only the local machine's IP address in the AllowIP section:

[RPCManager-AllowIP]
IP = 127.0.0.1


[RPCMANAGER-NETPRIORITY] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

In multi-homed situations, RPC Manager will help with communications where multiple network interfaces appear on a workstation.

You can configure the RPC Manager to use the available networks in two ways:

  • Prioritized
  • Round-robin.

These two methods can be described as follows:

Prioritized

The available networks are arranged in an order of priority. The RPC Manager always uses the highest priority available network for transmission.

Round-robin

All network interfaces are treated equally, and RPC Manager traffic is sent using each interface in turn. This method could be used to improve the tolerance of the distributed system for network failures, and is the default behavior.

The above two methods can be combined where there are two or more networks, such that some of the networks can be prioritized and the others left as round-robin. RPC Manager traffic will always be sent over the prioritized network first, using the remaining two networks in round-robin mode if the prioritized network link to a workstation fails.

To establish the prioritized mode, you can enter the a subnet mask identifying the subnet that the remote machine is on for each network that the local server should communicate with in order of priority, using CIDR notation as follows:

<IP address>/<number of bits specifying the subnet mask>

Where, the number of bits specified is applied to the IP address from the most significant end. A mask value of 24 specifies the first three numeric parts of the IP address (8-bits per number) and is otherwise equivalent to a subnet mask of 255.255.255.0. A mask of 16, the first two numeric parts (subnet mask 255.255.0.0), and so forth.

For example, you have two routes of communication between Server A and Server B as shown.

You would prefer to have traffic use the Internet routing when available, to reduce communication costs.

On Server A, configure the Setup.INI file as follows:

[RPCManager-NetPriority]
IP = 192.168.2.0/24

On Server B, configure the Setup.INI file as follows:

[RPCManager-NetPriority]
IP = 192.168.1.0/24

This example specifies that for Server A, IPs on subnet 192.168.2 are to be given priority over IPs to the same workstation on all other subnets. Likewise, for Server B, IPs on subnet 192.168.1 are to be given priority over IPs to the same workstation on all other subnets.

If an IP on the preferred subnet becomes unusable, any available IPs on other subnets will have RPCs transmitted to them in round-robin fashion.

For further information on these methods and multi-homed systems and RPC, see Multi-homed Systems.

Related information:

GetSubnetPriority

SetSubnetPriority

GetPreferredSubnet

GetLastUsedSubnet


[SYSTEM] Section

The following variables are set in the [SYSTEM] section of the Setup.ini configuration file.

Related information:

AccountsChangeDlgWait

ActivateProgressDelay

AutoStartDlgTimeout

CompileProgressDelay

ConvertProgressDelay

DbTraceDaysToPreserve

DbTraceFileSize

DefaultLanguage

DialogServiceFailoutTime

DisableVAMPerAppColoring

EnableShowHide

ErrorLogFileName

HelpServerPath

HTTPAllow

HTTPDeny

LogOffUponHide

LowBatteryPercent

LowBatteryTime

MinAltIDLength

MobileSlippyMapTilesSource1

OrderlyShutdown

PrintWidth

QuickAddTypeGUID

ReloadWCProgressDelay

RepoClashWait

RPCCompress

RPC Manager Properties

ShutdownOnLowBattery

SlippyMapDownloadFailoutTime

SlippyMapMaxRetryDelay

SlippyMapOSMDisable

TagNameDelimiter

VICAutoAddDebugTools


AccountsChangeDlgWait

If the user doesn't respond to an accounts modify (from file change) confirmation dialog within this many seconds, the original accounts file is retained. Defaults to 60 seconds if not set to a valid number.

Section: System

Default: AccountsChangeDlgWait = 60

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


ActiveLanguage

Selects the language to use for text in the VTScada Application Manager. Does not affect language selection in any application.

If not set, DefaultLanguage is used.

Section: System

Default: ActiveLanguage = en

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Related properties:

DefaultLanguage

ShowDefaultOnFailedLookup


ActivateProgressDelay

Suppress activation progress dialog for this many seconds. Recommended for preventing short-duration operations from showing any progress dialog.

Section: System

Default: ActivateProgressDelay = 0.5

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


AllowRemoteTest

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Set to 1 (TRUE) to enable remote testing on the machine. You must restart VTScada for the change to take effect.

Machines running VTScada with an R&D license are exempt from changes to this property, therefore, it will not affect internal multi-machine testing.

Allowing Remote Testing is less secure. If you allow remote testing and you need to access your machine on an unsecure network (such as at an airport, or in a hotel), it is strongly recommended that you set this property to 0 (FALSE).

Section: System

Default: AllowRemoteTest = 0


AutoStartDlgTimeout

Used when an application has been configured to start automatically. Before the application starts, VTScada will display a dialog, giving the user a chance to abort the startup. This dialog is shown for AutoStartDlgTimeout seconds (defaulting to 10). See also: AutoStart

In applications where HideVAM is enabled, it is recommended that AutoStartDlgTimeout be reconfigured to zero seconds. (AutoStartDlgTimeout = 0).
See the VTScada Application Manager section of the Security Guidelines Manual for more information.

Section: System

Default: AutoStartDlgTimeout = 10

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Related information:

HideVAM


CompileProgressDelay

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Suppress compilation progress dialog for this many seconds

Section: System

Default: CompileProgressDelay = 1


ConvertProgressDelay

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Suppress conversion progress dialog for this many seconds.

Section: System

Default: ConvertProgressDelay = 0.5


DbTraceDaysToPreserve

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Enables you to set the number of days that a trace file will be kept for use by the Trace Viewer application, after which the trace file will be deleted.

Default: DbTraceDaysToPreserve = 30


DbTraceFileSize

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Enables you to set the maximum number of records to be stored in a single trace file (for use by the Trace Viewer application).

Default: DbTraceFileSize = 40000


DefaultLanguage

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Sets the language file to use for the VTScada Application Manager. Defaults to US English (en).

By design, there is no control in the user-interface to change this property. Do not change to another language until you have created a phrase in your desired language for every possible phrase key.

Section: System

Default: DefaultLanguage = en

Related properties:

ActiveLanguage

ShowDefaultOnFailedLookup


DialogServiceFailoutTime

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

If VTScada is running as a service it will wait these many seconds for an undisplayable user query before defaulting the result. It will attempt to display the query on a VIC if one is available.

Section: System

Default: DialogServiceFailoutTime = 10


DisableVAMPerAppColoring

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

If set, the VTScada Application Manager's list of applications will use default coloring rather than show each application using its assigned color theme.

Default: DisableVAMPerAppColoring = 0

Section: System


DrawServiceListEnableSwitchingAll

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

TRUE to enable the ability to manually switch all filtered RPC services to another server

Section: System

Default: DrawServiceListEnableSwitchingAll = TRUE

Related information:

DrawServiceListEnableSwitchingSelected

DrawServiceListServerSwitchAllRequiresConfirmation

DrawServiceListServerSwitchRequiresConfirmation

DrawServiceListUpdateRate


DrawServiceListEnableSwitchingSelected

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

TRUE to enable the ability to manually switch a selected RPC service to another server

Section: System

Default: DrawServiceListEnableSwitchingSelected = TRUE

Related information:

DrawServiceListEnableSwitchingAll

DrawServiceListServerSwitchAllRequiresConfirmation

DrawServiceListServerSwitchRequiresConfirmation

DrawServiceListUpdateRate


DrawServiceListServerSwitchAllRequiresConfirmation

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

TRUE to require confirmation when manually switching all filtered RPC services to another server.

Section: System

Default: DrawServiceListServerSwitchAllRequiresConfirmation = 1

Related information:

DrawServiceListEnableSwitchingAll

DrawServiceListEnableSwitchingSelected

DrawServiceListServerSwitchRequiresConfirmation

DrawServiceListUpdateRate


DrawServiceListServerSwitchRequiresConfirmation

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

TRUE to require confirmation when manually switching a selected RPC service to another server

Section: System

Default: DrawServiceListServerSwitchRequiresConfirmation = 1

Related information:

DrawServiceListEnableSwitchingAll

DrawServiceListEnableSwitchingSelected

DrawServiceListServerSwitchAllRequiresConfirmation

DrawServiceListUpdateRate


DrawServiceListUpdateRate

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Rate at which the service list information is updated (seconds)

Section: System

Default: DrawServiceListUpdateRate = 1

Related information:

DrawServiceListEnableSwitchingAll

DrawServiceListEnableSwitchingSelected

DrawServiceListServerSwitchAllRequiresConfirmation

DrawServiceListServerSwitchRequiresConfirmation


EnableShowHide

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

When set to 1 (true), all application entries in the VAM will have a Toggle Visibility icon. While this property will normally be set from within an individual application's Edit Properties dialog, it does affect all applications

Section: System

Default: EnableShowHide = 0

Related properties:

LogOffUponHide

DispMgrHidden


ErrorLogFileName

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Name of the file used to log error information.

Section: System

Default: ErrorLogFileName = Errors.log


HelpServerPath

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Holds the URL for the location of the web server storing help files for use by VTScada Internet Clients.

When a VIC user presses the "F1" key on their keyboard, if the required help file is not present on the user's workstation, VIC will automatically request the help file from the location specified by the HelpServerPath variable. If this variable is not defined, then the default value is used, resulting in VIC requesting the help file from the VTScada HTTP server to which the user first connected.

The value for HelpServerPath should be set to an absolute URL, including the protocol prefix (e.g. http://some.server.com/help/files", "https://some.server.com/help/files"). VIC will then add the uppercase name of the required help file to the request (e.g. "DEVELOPERSGUIDE.CHM").


HTTPAllow

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Use to permit a single IP address or a set of IP addresses and/or subnet specifiers (in CIDR notation) separated by semicolons. Other than using a range, you cannot define multiple addresses.

If HTTPDeny is also set, then note that rules set using HTTPDeny take precedence over HTTPAllow.

Examples:

HTTPAllow = 192.168.0.0/24;2001:1432:b6d:1234::/64

which gives permission to the IPv4 address range 192.168.0.1 to 192.168.0.255 and to the IPv6 address range 2001:1432:b6d:1234:0000:0000:0000:0000 to 2001:1432:b6d:1234:ffff:ffff:ffff:ffff

Allowing a single address:

HTTPAllow = 192.168.1.32

Allowing a range of addresses:

HTTPAllow = 192.168.1.0/24

Section: System

Default: No default.


HTTPDeny

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Use to deny access to a single IP address or a set of IP addresses and/or subnet specifiers (in CIDR notation) separated by semicolons. Other than using a range, you cannot define multiple addresses.

If HTTPAllow is also set, then note that rules set using HTTPDeny take precedence over HTTPAllow.

Deny a single address:

HTTPDeny = 192.168.1.32

Denying a range of addresses:

HTTPDeny = 192.168.1.0/24

Refer to HTTPAllow for further examples.

Section: System

Default: No default.


HTTPMaxEntityLength

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Sets the maximum payload size (measured in bytes) that will be accepted by the VTScada HTTP server in a POST request. Defaults to just under 10Mb.

Default: HTTPMaxEntityLength = 10000000

Section: System

Related properties:

SQLQueryMaxRequestLength

HTTPRequestMaxSize


HTTPRequestMaxSize

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Limits the buffering of HTTP requests. HTTPMaxRequestSize also limits the overall maximum size of a WebSocket message (and, indirectly, individual WebSocket protocol frames).

While having a limit is strictly a security aspect (reducing the ability of an external malicious actor to consume VTScada memory), it may need to be increased where large WebSocket messages are expected.

Section: System

Default: HTTPRequestMaxSize = 16384

Related Properties

HTTPMaxEntityLength


LogOffUponHide

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Used only when EnableShowHide has been set to 1 (true).

When LogOffUponHide is 1 (default), users will be logged off automatically when the application is hidden. The default setting is recommended for most situations.

Default: LogOffUponHide = 1

Section: System

Related properties:

EnableShowHide

DispMgrHidden


LowBatteryPercent

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Used by the OrderlyShutdown feature. Sets the threshold for the percentage of battery power remaining, below which VTScada will undergo an orderly, automatic shutdown.

VTScada monitors the Windows provided GetSystemPowerStatus API call to obtain the status of the system power supply. The status indicates whether the system is running on AC or DC power, whether the battery is charging, and how much battery life remains.

Any UPS driver that provides updates to Window’s view of the power state of the system should work with this in-built ability.

Section: System

Default: LowBatteryPercent = 10

Related information:

ShutdownOnLowBattery

LowBatteryTime

OrderlyShutdown


LowBatteryTime

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Used by the OrderlyShutdown feature. Sets the threshold for the estimated number of minutes of remaining battery power remaining, below which VTScada will undergo an orderly, automatic shutdown.

VTScada monitors the Windows provided GetSystemPowerStatus API call to obtain the status of the system power supply. The status indicates whether the system is running on AC or DC power, whether the battery is charging, and how much battery life remains.

Any UPS driver that provides updates to Window’s view of the power state of the system should work with this in-built ability.

Section: System

Default: LowBatteryTime = 15

Related information:

ShutdownOnLowBattery

LowBatteryPercent

OrderlyShutdown


MinAltIDLength

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Sets the minimum number of characters required for an alternate ID value. Defaults to four if not otherwise set.

Trihedral Engineering strongly discourages any reduction in the number of characters required for identification. Any reduction in the number of possible combinations makes it easier for an attacker to compromise your system.

Section: System

Default: MinAltIDLength = 4


MobileSlippyMapTilesSource1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

May be used to specify an alternate source for map tiles to be used by the mobile browser interface. You may assign any Open Street Map compatible URL.

Default: No default. Must be added to Setup.INI


OrderlyShutdown

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

If set to 1 (true), VTScada to do an automatic shutdown when it detects that the workstation is relying on a UPS power supply that is failing. Detection uses one of the three related variables: ShutdownOnLowBattery, LowBatteryPercent or LowBatteryTime.

VTScada monitors the Windows provided GetSystemPowerStatus API call to obtain the status of the system power supply. The status indicates whether the system is running on AC or DC power, whether the battery is charging, and how much battery life remains.

Any UPS driver that provides updates to Window’s view of the power state of the system should work with this in-built ability.

Section: System

Default: OrderlyShutdown = 1


PrintWidth

Enables you to set the width of Alarm page and Operator Notes printouts. Measured in printed characters.

Section: System

Default: PrintWidth = 80

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


QuickAddTypeGUID

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

When creating an application with the Quick Add function, the application will be based on the OEM layer with this GUID.

Section: System

Default: QuickAddTypeGUID = current GUID of the VTScada layer


ReloadWCProgressDelay

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Suppress working copy reload progress dialog for this many seconds

Section: System

Default: ReloadWCProgressDelay = 0.5


RememberLoginDuration

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Sets the maximum length of time for which the Anywhere client logon credentials will be stored when the Remember Me option is selected during connection. Units are minutes.

Section: System

Default: RememberLoginDuration = 20160


RepoClashWait

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Time (in seconds) that Repository Clash dialog will be displayed before the layer is automatically reloaded.

Section: System

Default: RepoClashWait = 300


ReportErrorSilenceAll

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Silences error reports on the current workstation. Because this is a Setup.INI property, it affects all applications on the current workstation and only the current workstation.

Trihedral strongly advises that you not set this property on any server.
Use only on workstations that are not part of any server list.

Section: System

Default: ReportErrorSilenceAll = 0


RPCCompress

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Should be enabled only when there is a very low-bandwidth LAN link in the network such as a radio or RS-232 link.

Enabling RPC compression other than on very low bandwidth links can result in excessive CPU utilization.

Section: System

Default: RPCCompress = 0


RPC Manager Variables

Viewing: Reference > Property Reference > System Properties - Setup.ini > [SYSTEM] Section > RPC Manager Variables

RPC Manager Properties

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The following Setup.INI properties are documented within the RPC Manager chapter .

RPCBufferLength - This is the maximum TCP/IP buffer length to use for RX and TX buffers.

RPCConnectPort - The TCP/IP port that RPC Manager tries to connect to.

RPCMaxPacketSize - Specifies the maximum size of an encoded remote procedure call before the call will be fragmented over a number of transmissions.

RPCMaxStartDelay - Controls startup behavior if the workstation name is not valid.

RPCPingInterval - Specifies the time that a socket can have no data transmitted before a "ping’ packet will be sent to all the receiving end to determine that the socket it still good.

RPCReconnectTime - Specifies the seconds to wait for data on a socket before disconnecting the socket.

RPCResendDelay - Specifies the time to wait for an acknowledgment after sending a packet before resending the packet

RPCSktConnectAttemptMax - Specifies the number of attempts to open a socket before it is declared to be closed.

RPCSktResendAttempts - Specifies the maximum number of attempts to send an RPC packet.

RPCServerPort - The TCP/IP port that RPC Manager "listens" on.

RPCSocketDeadTime - Specifies the number of seconds that a session will remain alive with no socket connection.

RPCSocketResendAttempts - Specifies the number of packet re-sends that will occur without acknowledgment, before the socket is closed.

RPCTrace- Set to a non-zero value to log all RPC activity to the disk file "RPCTRACE.TXT", in the VTScada installation directory.

RPCUseBuffered - When non-zero this will cause RPC to read the TCP/IP IP and Name once only from the low-level socket stream and cache this information.


ShowDefaultOnFailedLookup

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

If no phrase is available in the currently selected language for a phrase key used in the display, then both the phrase from the default language (English) and the matching phrase key will be shown instead.

If this property is not enabled, then only the phrase from the default language will be shown. This makes it more difficult to find phrase keys matching untranslated phrases.

This property can be changed using a check box within the VAM's Settings dialog.

Section: System

Default: ShowDefaultOnFailedLookup = 1

Related properties:

ActiveLanguage

DefaultLanguage


ShutdownOnLowBattery

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Used by the OrderlyShutdown feature. Monitors a status parameter for the battery and enables VTScada to do an automatic shutdown if it detects that the battery state has reached the defined "Low" level.

VTScada monitors the Windows provided GetSystemPowerStatus API call to obtain the status of the system power supply. The status indicates whether the system is running on AC or DC power, whether the battery is charging, and how much battery life remains.

Any UPS driver that provides updates to Window’s view of the power state of the system should work with this in-built ability.

Section: System

Default: ShutdownOnLowBattery = 0

See Also: OrderlyShutdown, LowBatteryPercent, LowBatteryTime


SlippyMapBulkDownloadMaxZoomDiff

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Maximum difference between the zoom levels of the large and small maps in the Bulk Download dialog.

Section: System

Default: SlippyMapBulkDownloadMaxZoomDiff = 7


SlippyMapCriticalDiskSpace

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The maximum amount of disk space, measured in MB, that VTScada will use for storing map tiles. Further writes are disabled when this size is reached.

Section: System

Default: SlippyMapCriticalDiskSpace = 10000


SlippyMapDownloadFailoutTime

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

If the Internet connection error lasts for at least this many seconds, broadcast to other potential servers that the current primary does not have an Internet connection, allowing them to make the attempt. Measured in seconds.

Section: System

Default: SlippyMapDownloadFailoutTime = 10


SlippyMapDownloadTimeLimit

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Seconds to wait for a response from a map tile server when downloading a map tile.

Section: System

Default: SlippyMapDownloadTimeLimit = 1


SlippyMapMaxConcurrentDownloads

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Maximum number of concurrent connections to a map tile server permitted when downloading map tiles.

Section: System

Default: SlippyMapMaxConcurrentDownloads = 2


SlippyMapMaxRetryDelay

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Maximum time between download tests, measured in seconds.

Section = System

Default: SlippyMapMaxRetryDelay = 60


SlippyMapMaxTileSize

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Maximum allowable size of a tile, measured in bytes. Tiles larger than this will not be saved to your server.

Section: System

Default: SlippyMapMaxTileSize = 70000


SlippyMapOSMDisable

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Set to 1 (true) if Open Street maps are disabled. (CARTO® maps are always enabled.)

Section: System

Default: SlippyMapOSMDisable = 1


SmartcardUPNMatch

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

May be defined in the case where you are using Smart Card Support, you have multiple certificates, and you want the system to use one certificate automatically rather than present a selection dialog.

The property value is assigned a "match" string, which is compare against the User Principal Name (UPN Closed User Principal Name) in certificates found on the Smartcard. For example: *.trihedral.com

The wildcard characters "*" and "?" are supported with their usual meanings, where ? may be replaced by one of any character and * may be replaced by any number of any characters.

If the entry is not present or invalid, no field matching is done and cards with multiple certificates will see the certificate selection dialog.

If there are multiple certificates on the card and there are no UPN matches, or there is more than one UPN match, the certificate selection will be presented.

Section: Security Manager

Default: smartcardUPONMatch =

*No restart required (Settings.Dynamic property)


TagNameDelimiter

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Sets the closing delimiter to be used for the short name (display name) of tags. May be changed to an alternative character if a legacy application is to be used in the current version of VTScada and tags in that application used the "]" as part of their name.

Section: System

Default: TagNameDelimiter = ]


VICAutoAddDebugTools

Indicates whether VTScada system tools (such as the Source Debugger, Profiler, etc.) should be accessible from VICs.

If set to 1, the VTScada system tools will be accessible by VIC users (default).

Default: VICAutoAddDebugTools = 1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


[SlippyMapRemoteTileSourceN] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

In legacy versions of VTScada, SlippyMapRemoteTileSourceN was a variable. It is now a set of numbered sections (where N is 1, 2, 3...) containing several variables.

Do not edit tile sources from CARTO, unless you are removing those sources. CARTO maps are supplied by licensing agreement and include an API key that is unique to each VTScada installation. API keys cannot be shared.

Only Trihedral can encrypt API keys. If using your own custom APIKeyValue, it will have to be stored in plain text, and APIKeyEncrypted set to 0.

Several map sources are provided with VTScada. You may add more, change the URL for any source, or remove sources.

Example:

[SlippyMapRemoteTileSource2]
URL1 = https://enterprise-a.basemaps.cartocdn.com/rastertiles/voyager/
URL2 = https://enterprise-b.basemaps.cartocdn.com/rastertiles/voyager/
URL3 = https://enterprise-c.basemaps.cartocdn.com/rastertiles/voyager/
URL4 = https://enterprise-d.basemaps.cartocdn.com/rastertiles/voyager/
Label = MapVoyagerLabel
APIKeyName = api_key
APIKeyValue = SAsfaFFKUUVfARJM2LzyE7d1LkENJ6udok5vmwejZWSoOe7glZ7zYSqJPLI3P3UP/
APIKeyEncrypted = 1
BulkDownload = 1
CopyrightURL1 = www.openstreetmap.org/copyright
CopyrightLabel1 = © [OpenStreetMap contributors]
CopyrightURL2 = https://carto.com/attribution
CopyrightLabel2 = © [CARTO]
Default = 1
BGColor = <FFC0C0C0>
Extension = .png

Properties within this section:

URL1, URL2, ..., URLn

Required. One or more URLs for downloading map tiles. Only provide more than one URL if the map tile provider has more than one server. The URL can use one of the following two formats:

http://a.mymaps.com/path/

With this format, the URL will automatically be extended to http://a.mymaps.com/path/z/x/y.png when retrieving a tile at z/x/y.

http://a.mymaps.com/path/%Z/%Y/%X

In case the URL does not conform to the z/x/y format, the URL can contain placeholders that will be replaced by the appropriate values. The available placeholders are "%Z", "%X", "%Y" and "%KEY". The %KEY placeholder can be used instead of the APIKeyName property, such as https://a.mymaps.com/path/%Z/%Y/%X?api_key=%KEY.

Label

Required. Label of the map style that shows in the style selector

APIKeyName

Name of the API-key parameter in the URL. The API-key name and value are automatically appended to the URL as an HTTP parameter if specified. This is not applicable if the %KEY placeholder is used.

APIKeyValue

The actual API key. Note that only Trihedral can encrypt API keys. If using your own this must be stored in plain text.

APIKeyEncrypted

1 if the API key has been encrypted. 0 otherwise. Note that only Trihedral can encrypt API keys. If using your own this must be set to 0.

BulkDownload

1 if bulk download is allowed for the map source. Defaults to 0.

CopyrightURL1, CopyrightURL2, ... , CopyrightURLn

Copyright links.

CopyrightLabel1, CopyrightLabel2, ... , CopyrightLabeln

Copyright text that shown at the bottom right corner on the map page.

Default

1 to make this the default map style. Defaults to 0.

BGColor

Map window background color. Defaults to light gray.

Extension

Format of map tiles. This may be either .png or .jpg, with .png as the default if not specified.

Private

GUIDs of applications that may have access to the map source. Separate by comma. Omit this field if the map source is public to all applications

Do not skip numbers when defining tile sources. If you have [ SlippyMapRemoteTileSource1], [ SlippyMapRemoteTileSource2] and [SlippyMapRemoteTileSource4], then only the first two will be available for users to select.


[Themes] Section

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

The color themes available to the VAM are defined in this section of Setup.INI. Each takes the following form:

Theme = ThemeName, Hue, Saturation, Brightness, Contrast

For example:

[Themes]
Theme = Gray,0,0,1.1,1
Theme = Navy,-15,2,0.7,1
Theme = Burgundy,110,2,0.5,1


[TRACE] Section

The following list identifies a number of Setup.ini variables that are used for the purposes of tracing data transmissions of a variety of different VTScada services.

The following variables can be set using the Trace VTScada Actions utility, which enables you to trace VTS' actions to a text file.

Related information:

TraceBrowser

TraceCM

TraceDispMgr

TraceDlg

TraceMenuEd

TraceModem

TraceNav

TracePageMgr

TracePLimit

TraceRamRecs

TraceRPC

TraceSQL

TraceToFile

TraceTool

TraceUserConfigActions

TraceVAM


TraceBrowser

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Indicates whether to trace the Tag Browser.

If set to 1 (true), the Tag Browser is traced (default).

Default: TraceBrowser = 1


TraceCM

Trace Configuration Management actions (adds ReportError data to the trace)

Default: TraceCM = 1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


TraceDispMgr

Indicates whether the Display Manager should be traced.

If set to 1 (true), the Display Manager is traced (default).

Default: TraceDispMgr = 1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


TraceDlg

Indicates whether system dialogs (i.e. 4BtnDialog, ODBCErr, ErrList, Err Queue), should be traced.

If set to 1 (true), then system dialogs are traced (default).

Default: TraceDlg = 1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


TraceMenuEd

Indicates whether the Menu Editor should be traced.

If set to 1 (true), then the Menu Editor should be traced (default).

Default: TraceMenuEd = 1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


TraceModem

Indicates whether the Modem Manager service should be traced.

If set to 1 (true), then the Modem Manager should be traced (default).

Default: TraceModem = 1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


TraceNav

Indicates whether the Navigator (shortcut menus) should be traced.

If set to 1 (true), the navigator is traced (default).

Default: TraceNav = 1

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.


TracePageMgr

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Indicates whether the Page Manager should be traced.

If set to 1 (true), then the Page Manager is traced (default).

Default: TracePageMgr = 1


TracePLimit

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Indicates the maximum number of bytes of data saved for a traced module's parameter.

Default: TracePLimit = 256


TraceRamRecs

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Indicates the number of trace records to store in RAM.

Section: System

Default: TraceRamRecs = 1024


TraceRPC

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Indicates whether the RPC Manager should be traced.

If set to 1 (true), then the RPC Manager is traced (default).

Default: TraceRPC = 1


TraceSQL

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Indicates whether SQL calls should be traced.

If set to 1 (true), then SQL calls should be traced.

Default: TraceSQL = 0


TraceTagCfg

Indicates whether tag properties folders should be traced.

If set to 1 (true), then tag properties folders are traced (default).

Default: TraceTagCfg = 1


TraceToFile

Indicates whether to trace to file.

If set to 1 (true), then tracing data is saved to a text file named "VTSTrace.txt".

Default: TraceToFile = 0


TraceTool

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Indicates whether tracing should be done for VTScada libraries, and drawing objects.

If set to 1 (true), then VTScada libraries, and drawing objects are traced (default).

Default: TraceTool = 1


TraceVAM

Part of Setup.INI, in your installation folder.
This property is not part of the Application Configuration dialog.

Indicates whether to trace the VTScada Application Manager (VAM).

If set to 1 (true), then the VAM is traced (default).

Default: TraceVAM = 1


Function Reference

Examples are not always provided for any function flagged as "deprecated".
Functions noted as being for advanced users only may not have examples.

Closed Alarm Functions
Ack | Acknowledge an alarm.
AckAllAlarms | Acknowledge all unacknowledged alarms available to the current user.
AckAllAlarmsPlusDlg | Acknowledge all unacknowledged alarms available to the current user after confirmation
AddToList | Adds an alarm to the specified list in an Alarm Database, usually a custom list.
AdHocAlarm | Evaluates an ad hoc alarm
AlarmCondition | Returns TRUE (1) if the monitored tag has an active alarm.
AlarmUnAckCondition | Returns TRUE (1) if the monitored tag has an unacknowledged alarm.
Commission | (Alarm Manager module) Commission the alarm by adding it to the Configured list.
Decommission | (Alarm Manager module) Decommission an alarm by name.
EvaluateAlarm | (Alarm Manager module) Passes a new value to an alarm, to be compared to the setpoint.
GetAlarmConfiguration | (Alarm Manager module) Returns a copy of an alarm's configuration structure from the master alarm list, creating it if it does not already exist.
GetAlarmList | (Alarm Manager module) Returns filtered lists of records from alarm databases.
GetAlarmObject | (Alarm Manager module) Returns an alarm object value given an alarm name.
GetAlarmStat | Returns the number of alarms in the given tag and its descendents, where those alarms match the specified statistic.
GetAlarmStateStats | (Alarm Manager module) Returns a structure containing the cumulative alarm state statistics for the specified tag.
GetAlarmStatus | (Alarm Manager module) Returns a reference to an alarm's status structure in the master database, providing access the alarm's current state without having to make additional function calls.
GetContainerNumActive | Returns the number of active alarms within a hierarchy of tags.
GetContainerNumUnacked | Returns the number of unacknowledged alarms within a hierarchy of tags.
GetNameOfRecord | (Alarm Manager module) Given an alarm record, returns the tag name.
GetNumUnacked | (Alarm Manager module) Returns either the number of unacknowledged alarms or a Yes/No flag to indicate that the alarms exist. If realm-area filtering is in use, results will be limited to the operator's realm.
GetUserNameOfRecord | (Alarm Manager module) Given an alarm record, returns the user name associated with the transaction.
IsActive | (Alarm Manager module) Will indicate if an alarm is currently active.
IsDisabled | (Alarm Manager module) Will indicate if an alarm is currently disabled.
IsShelved | (Alarm Manager module) Will indicate if an alarm is currently shelved. It can be used either as a subroutine or as a called function.
IsSuppressed | (Alarm Manager module) Will indicate if an alarm is currently suppressed.
IsUnacked | (Alarm Manager module) Will indicate if an alarm is currently unacknowledged.
MakeAlarmRecordSpeechFile | Generates a .wav file from an alarm record to audibly speak an alarm.
MuteSound | (Alarm Manager module) This subroutine is used to turn off alarms sounds for all alarms, both current and future.
PAlmPriority | (VTS Library) Draws a droplist of the currently available alarm priorities with an optional title or bevel or both.
RemoveFromList | Removes an alarm from the specified list in an Alarm Database, usually a custom list.
SetShelved | AlarmManager plug-in, that handles the shelving and unshelving of alarms.
SilenceSound | (Alarm Manager module) This subroutine will silence the current sounding alarm.
The following alarm functions are deprecated or obsolete as of version 11.2
Acknowledge | Deprecated. (Alarm Manager module) Will acknowledge an alarm.
Active | Deprecated. (Alarm Manager module) Tells the Alarm Manager to activate an alarm. This subroutine will activate an alarm and signal it as unacknowledged.
Disable | Deprecated. (Alarm Manager module) Tell the Alarm Manager to disable an alarm. Disable will also clear any active or unacknowledged state that might exist.
Enable | Deprecated (Alarm Manager module) Tell the Alarm Manager to enable an alarm.
Event | Deprecated. (Alarm Manager module) Tell the Alarm Manager when an alarm event occurs. This subroutine will cause an entry to be added to the log file without changing the alarm status.
ListAdd | Deprecated. (Alarm Manager module) This subroutine will add the alarm object to a list. This is useful if a user-defined list has been created.
ListRemove | Deprecated. (Alarm Manager module) This subroutine will remove the alarm object from a list. This is useful if a user-defined list has been added.
Normal | Deprecated. (Alarm Manager module) Use this function to tell the Alarm Manager when an alarm clears. This subroutine will deactivate the alarm. It will not affect the unacknowledged status.
NormalTrip | Deprecated (Alarm Manager module) This subroutine will deactivate an alarm and signal it as unacknowledged.
OffNormal | Deprecated. (Alarm Manager module) This subroutine will activate the alarm. However, it will not affect the unacknowledged status.
Popup | Deprecated. (Alarm Manager module) Causes an alarm pop-up dialog to display.
Register (Alarm Manager) | Deprecated. (Alarm Manager module) Inform the Alarm Manager that a module instance may wish to generate alarms in the future.
SetEnable | Deprecated. (Alarm Manager module) Use in preference to Enable to enable or disable alarms build into tags.
TransferFields | Deprecated (Alarm Manager module) The TransferFields subroutine will transfer the values for each field into the returned FieldValues array. The values are found in the scope passed in using the variable names found in the FieldNames array.
Trip | Deprecated. (Alarm Manager module) Tell the Alarm Manager to when a trip alarm event occurs. This subroutine will signal an alarm as unacknowledged.
Unregister (Alarm Manager) | Deprecated. (Alarm Manager module) Notify the Alarm Manager that an alarm has been removed. This will not generate an alarm, it just removes it from the list of all configured alarms.
Closed Array Functions
AdjustArray | Changes the array information for a variable.
AMax | Array maximum. This function returns the maximum value in a sub-range of a numeric array.
AMin | Array minimum. This function returns the minimum value in a sub-range of a numeric array.
ArrayDimensions | Returns the number of dimensions in an array.
ArrayOp1 | Performs a mathematical operation on an array with respect to a scalar value.
ArrayOp2 | Performs a mathematical operation on an array with respect to another array.
ArraySize | Returns the number of elements in an array dimension.
ArrayStart | Returns the first element in an array dimension
ArrayToBuff | Returns a buffer containing the numeric data from an array.
ArrayToDictionary | Returns a dictionary if given an array of key names and a matching array of values.
AValid | Returns the number of valid elements in an array sub-range.
BuffToArray | Reads an array from a formatted buffer containing numerical data and returns the number of elements read.
BuffToPointer | Converts a buffer of numeric data to array of pointers. This function reads from a formatted buffer containing numeric data, writes to locations specified by an array of pointers, and returns the number of elements read.
Compress | Eliminate invalid array entries.
DeleteArrayItem | Deletes an element from a single dimension dynamically allocated array and returns the modified array.
Filter | Sets the value of one array element to invalid if the corresponding value in another array element is invalid.
FiltHigh | Sets the values in an array sub-range that fall above a specified upper limit to a new value.
FiltLow | Sets the values in an array sub-range that fall below a specified lower limit to a new value.
GenerateQRCode | Returns a 2D array which represents a QR code for a given string.
InsertArrayItem | Insert Array Item. This function inserts an element into a dynamically allocated array and returns the modified array.
LookUp | Looks up a value in an array and returns the index of the element containing that value.
MakeArray | Create and initialize an array in one line of code.
Mean | Returns the mean (average) of a portion of a numerical array.
New | Allocates memory for an array from RAM and returns a pointer to that array.
PointerToBuff | Returns a buffer containing the numeric data from the variables pointed at by each element of the array.
ReadX | Reads numeric data from a text file into the elements of an array.
ReadXY | Reads data points from a file into the elements of two arrays.
SDev | Returns the statistical sample standard deviation for a subsection of an array.
Sort | Allows the sorting of an array subsection according to the order of another array.
SortArray | Sorts an array of arrays based upon the key information provided by the second parameter.
Sum | Returns the arithmetic sum of all the valid array elements in a specified portion of a numeric array.
TextSearch | Returns the array index of the first occurrence of the given text key in an alphabetically ordered array.
Unpack | Unpacks a set of values from a stream into a single dimensional array or a set of variables referenced by object parameters, and returns the number of items unpacked.
UnpackData | (RPC Manager Library) This method unpacks a stream into an array or set of module instance parameters. Subroutine call only.
Variance | Returns the statistical sample variance for a subsection of an array.
WatchArray | Watches an array and returns true if any of its elements types or values change.
Closed Bitwise Operation
And | Returns the bit-wise AND of its two parameters as a 32-bit unsigned integer.
Bit | Returns the on/off status of a bit in a number.
Not | Returns the result of a 32 bit unsigned bitwise logical NOT operation.
Ones | Returns the number of bits set in an integer number.
Or | Performs a bit-wise OR operation and returns the result.
SetBit | Sets or clears a specific bit in a value and returns the result.
XOr | Returns the bitwise exclusive OR of its parameters.
Closed Bubbles and Threads
Bubble | Starts a new child bubble and launches the given module into a new script thread in that bubble.
BubbleList | Lists the running child bubbles of the current bubble.
BubbleQueueLength | Reports the length of the queue of messages from the current bubble's parent bubble or one of its children.
BubbleReceive | Receives a message from the given bubble.
BubbleSend | Sends a message to the given bubble.
ProcessingLoad | Returns the current VTScada processing load of the calling bubble.
RunInBubble | Starts a new thread in the given child bubble and launches the given module into that script thread.
Thread | Launches a module in its own separate thread.
ThreadHistory | Returns in an array, the history of execution for all threads.
ThreadIdle | Returns TRUE when the ToDo list for a given thread is empty.
ThreadList | Returns a two dimensional array containing the name and statement last executed by each VTScada thread.
ThreadName | Returns the name of a thread.
ThreadPriority | Allows advanced users to set a specified thread to one of six priorities, ranging from idle to time critical.
TODBC | Performs an ODBC command.
TODBCBeginTrans | Indicates to an ODBC-compliant database that a transaction is to be started.
TODBCCommit | Indicates to an ODBC-compliant database that a transaction is to be committed
TODBCConnect | Forms a connection to an ODBC database.
TODBCDisconnect | Stops a connection to the ODBC database.
TODBCRollback | Indicates to an ODBC-compliant database that a transaction is to be discarded.
Closed Certificate Operations
AddCertificate | Returns a structure of information about a supplied X.509 certificate.
CheckCertificateChain | Checks the chain of trust of a certificate
FindCertificate | Locates a certificate in a certificate store.
GetCertificateInfo | Returns a structure of information about a supplied X.509 certificate.
ListCertificates | Enumerates X.509 certificates in a certificate store resident on the local computer.
MakeSelfSignedCertificate | Creates a new self-signed certificate.
RemoveCertificate | Removes a certificate from a certificate store.
SetCertificateProperty | Sets a modifiable property on a stored certificate.
Closed Clipboard
ClipboardGet | Returns the current contents of the system clipboard as a string. This function enables an application to perform text "paste" operations.
ClipboardPut | Set the current contents of the system clipboard to a string. This function enables an application to perform text "copy" or "cut" operations.
Closed Color
Blend | Returns an aRGB color value that is a given percentage between two specified colors.
Brush | Returns a brush value.
Cls | Clears the screen and sets its background color.
ColorSelect | (System Library) Color Selection Tool. This module draws a color selection button and its accompanying display area.
GetColorInfo | Returns the brush and pen information for a given graphic statement.
GetEquipmentColor | Returns a defined Equipment Color that was set in a style tag based on the equipment type of an IO tag
GetSystemColor | Returns the colors for the user-configured Windows™ colors.
PalStatus | Returns the current palette settings.
PColorSelect | (VTS Library) Draws a button that opens a color selection dialog and an area that displays the currently selected color.
Pen | Returns a pen value.
PixelColor | Returns the color of a pixel in the window.
ZColorChange | Changes one color within a region to another color.
Closed Com
ActiveX | Instantiates an ActiveX object. An ActiveX object is treated as a COM client interface that requires a client window area in which to draw.
COMClient | Instantiates COM objects that do not possess a user interface.
COMEvent | Sets an event subroutine context for an existing COM client interface.
COMStatus | Returns the last status information that occurred for a specified COM client interface.
Closed Compilation And On-Line Modifications
ActiveCode | ActiveCode returns the code value of the currently active statement in the given module instance.
ActiveState | ActiveState returns the code value of the currently active state in the given module instance.
ActiveWindow | ActiveWindow returns the object value of the root module instance in the current active window.
AddModule | Adds a new module to an existing module and returns the value of the newly created module.
AddOptional | Adds a new statement to an action script and returns its own error code.
AddPageToApp (Obsolete) | Creates a new application page.
AddParameter | Adds an existing variable as a module parameter and returns the number of parameters in the module.
AddState | Adds a new state to an existing module and returns its state value.
AddStatement | Adds a new statement to an existing state and returns its own error code.
AddVariable | Adds a new variable to an existing module and returns its variable value.
AdjustArray | Changes the array information for a variable.
AdjustCode | Adjusts the offsets and sizes of items stored in the .RUN file within the document file.
BuffToParm | Convert buffer of numeric data to parameters. This function reads module parameters from a formatted buffer containing numerical data and returns the number of data items read.
Call | Starts an instance of the module specified by its first parameter.
CalledInstances | Returns the object values of module instances that are called by a particular module.
Caller | Takes a given object value for a module and returns the object value of the module by which it was called.
CanEditDoc | Returns an indication as to whether the document for the given module can be edited.
Cast | Takes a value and returns a different type of value, if possible.
ChildDocs | Gets the module values for the root and all descendent modules that match the conditions defined by the second parameter.
ClearModule | Deletes the contents (all variables and states) of a module without removing the module itself.
ClearState | Deletes all of the statements in a state.
Compile | Compiles text and creates a new function. The type of return value is determined by its input parameters.
ConstCount | Returns the number of constant parameters in a function.
CreateModule | Creates a new module and returns a pointer to it.
CriticalSection | Marks a section of a module as a critical section and will not allow interruption of its execution by other threads.
Debugger | (System Library) Starts the VTScada debugger.
DeleteModule | Deletes a module from the system.
DeleteOptional | Deletes a statement from an action script.
DeleteState | Deletes a state from a module.
DeleteStatement | Deletes a statement from a state.
DeleteVariable | Deletes a variable from a module.
DelPageFromApp | Deletes a system page from an application.
FileRootModule | Parses the document file that contains the given module to find the root module in that file. Returns the module value of the root module.
FindAction | Returns an action from the list of actions in a state.
FindVariable | Searches for a variable by text name and returns a variable value.
FirstState | Sets the first state in a module.
ForceState | Sets the next state to start when the action script completes.
FormalParms | Returns the number of formal parameters declared in a module.
GetDefaultValue | Returns a variable's default value.
GetLiveMJPEG | Configured within a camera tag module, returns a reference to the current frame retrieved from the IP camera.
GetID | This returns the ID (opcode) of a given function.
GetInstance | Returns the object value of a module instance.
GetModuleRefBox | Get Module Reference Box
GetModuleText | Returns information about a module's document file.
GetOneParmText | Returns the text for one parameter of a function.
GetOverrides | Returns an array of OpCodes and the module value that will run when each OpCode is executed
GetParmText | Returns the text for all parameters of a function.
GetParserOffset | Returns the offset before the last compiled statement.
GetReturnValue | Returns a module's return value.
GetState | Returns the code value for the specified state.
GetStatement | Returns the code value for the specified statement.
GetStatementNum | Returns the statement number for the specified statement.
GetStateText | Returns the text for the specified state.
GetToken | Reads the next token from a stream and returns the token type.
GetTransitText | Get Transition Document Text. This function returns information about the documentation of an action.
GetVariableText | Returns information about the documentation of a variable.
GetXformRefBox | Get Transform Reference Box. This function returns the reference box for any transform of a module.
LastSelected | Returns the most recently selected graphics statement.
ListVars | Returns a list of variables.
LoadDLL | Loads a Microsoft Windows™ dynamic link library.
LoadModule | Loads a module from its .RUN files and returns a pointer to that module.
LValue | Left-hand Side Value. This function returns an indication of whether its argument can be used on the left-hand side of an assignment.
MakeDAG | Constructs a Directed Acyclic Graph (DAG - an internal function representation).
MakeNonPersistent | Takes a variable and makes it not persistent.
MakeNonShared | Takes a shared variable and makes it not shared.
MakePersistent | Takes a variable and makes it persistent (static).
MakeShared | Takes a variable and makes it shared.
MCSInstance | Module Calling Structure Instance. This function returns the object value of a module called by another module.
MCSMod | Module Calling Structure Module. This function returns the module value from a line of code that calls that particular module.
ModuleFileName | Returns the full path (including the drive letter) and file name of the document (.SRC) file of a module.
NParm | Returns the number of parameters listed in a module instance.
NumParms | Returns the number of parameters of a statement.
NumSets | Returns the number of statements that are currently active in setting a particular variable.
NumVariables | Returns the number of variables in a module.
OwningModule | Returns the module which contains a certain variable.
ParserSRO | Adds a scope resolution reference to a variable on the top of the PARSER_STACK given the stack and the object variable.
PersistentSize | Returns the size in bytes of a variable's persistent value size in the persistent value (.VAL) file.
RemoveParameter | Removes a parameter from a module's parameter list.
ReplaceStatement | Replaces a statement with another statement.
ResetParm | Can reset parameters that become latched.
ResyncDoc | Synchronizes the time and date for the document and .RUN files.
RUNFileName | Returns the name of the .RUN file for a module including the full drive and path.
RUNFileVersion | Returns the minimum version of VTScada that can read the .RUN files produced by the current version.
SaveModule | Saves a module definition to its *.RUN file.
SetDefault | Sets the default value for a variable.
SetModuleRefBox | Sets the reference box for a single instance of a module.
SetLibrary | Sets the library for an application.
SetModuleRefBox | Sets the default reference box for a module.
SetModuleText | Sets the module's .SRC file information.
SetOneParmText | Sets the text for one parameter of a function.
SetParameter | Sets a parameter in a statement.
SetParmText | Sets the text for the parameters of a function.
SetParserParm | Sets the value for the last parameter on the parser stack and returns its own error code.
SetRefRect | Sets the first four constant parameters of a layered graphic statement.
SetStateText | Sets the information about the text of a state in a .SRC file.
SetTransfer | Sets the destination for an action.
SetTransitText | Sets the information about the documentation of an action in the .SRC file.
SetVariableClass | Sets the class number of a variable and returns its previous class number.
SetVariableText | Sets the information about the documentation of a variable in the .SRC file.
SetVariableType | Sets the data type for the variable, so that only values of that data type can be stored in the variable.
StateList | Returns a list of states for a module.
StatementInstance | Takes a given code value and object and returns a code pointer value for that instance.
StateName | Returns the text name of the given state.
SubStatementIndex | Returns the index of a function within the statement where it is called.
VarAttributes | Returns the attributes bit field of a variable.
Closed Configuration
NewTagsFullyStarted | Returns TRUE if all new tags have started, run their Refresh modules, and started any children.
ModifyTags | Can be used to create, modify, or delete running tags. Replacement for StartTag.
OpChange | Wrapper for TagMigrator\OpChange. Performs an immediate deploy of a single tag change without disturbing any other tag changes already in place on the local branch.
SimpleOpChange | Immediately deploys a single parameter change on a single tag without disturbing any other tag. Makes use of OpChange.
StartTag | (Deprecated. See: ModifyTags) Is used to create tags by starting new instances of the tag type specified in the parameter list. When creating an application that requires child tags, it is recommended that this function be used in place of the older ChildLaunch function.
Closed Configuration Management
AcquireLock | Subroutine to acquire an exclusive lock on reading/writing working copy files across all applications.
AppIsRunning | Reports whether the application has been started and the start-up process is complete.
AppIsStarted | Returns TRUE if the application has been started.
AppIsStarting | Returns TRUE if the application is currently in the process of starting.
ApplyChangeSetFile | Apply a named ChangeSet to an application layer.
CaptureSettings | Gathers a single property value or an accumulated section and returns the result in a tabular format.
Combine | Performs a Merge2 operation with automated conflict resolution and change priority.
CommitEditedFiles | This function compiles and commits edited files if the compile succeeds.
DirectApply | Applies a set of changes directly to the repository, without disturbing existing (non-conflicting) changes already on either branch.
EditFile | Informs the configuration management system that a file has been modified in the working copy, typically before making a call to CommitEditedFiles.
GetAppInstance | Asynchronously, retrieves the Layer object (LayerRoot) for a particular application specified by its GUID.
GetCodeObj | Retrieves the "Code" object associated with the layer.
GetCurrentSubordinate | Retrieves the current subordinate driver value of the Driver Multiplexer tag.
GetINIProperty | Given an array of INIProperty structures, returns the value of a given property from that array.
GetLoadedAppInstance | Synchronously, retrieves the Layer object (LayerRoot) for a particular application specified by its GUID.
GetOEMLayer | Retrieves the layer root module of the OEM layer (should one exist) of the layer this is called against.
GetPlatformInfo | Gathers information about the current application and the workstation it is running on.
GetSubordinateDriver | Returns the subordinate driver object of the Driver Multiplexer tag based on the input parameter.
GetWCPath | Returns the full working copy path for an application.
GetWCRevision | Returns the revision structure for the repository revision currently in use by the working copy.
HasCompilationErrors | Reports if the working copy presently has unresolved compilation errors
HasUndeployedChanges | Finds whether the local machine is maintaining changes that have not been deployed, including changes that have been recorded by EditFile but have yet to be committed.
IsAppEditable | Returns TRUE if the application can currently accept changes without being re-started.
IsOnLocalBranch | Returns TRUE if the local machine is maintaining changes that have not been deployed within the repository.
IsRunOnly | Returns TRUE if the application is a run-file-only app, according to the WC contents.
LayerInUse | Returns true if the application is running, or if there are any applications that depend on this layer, running or not.
Merge | Applies a set of changes (the output of a Diff operation) to a buffer.
Merge2 | Attempts to apply two different Diff buffers to a single origin buffer.
ReadINIProperties | Gathers the sum of all of the properties files in this layer and all of its parents including the local workstation files.
ReleaseLock | Releases a working copy semaphore that was acquired by AcquireLock.
ReadPropertiesFile | Reads a single Settings file and returns an INIFile Structure.
RecordProperty | Helper function used to record settings without needing to explicitly interact with the settings files.
RepoSubscribe | Allows the caller to specify a callback which will be triggered whenever the application’s repository changes.
SetINIProperty | Given an INIFiles structure, this function sets the property with the specified name and section to the specified value
Start | Start an application.
LayerRoot\Stop | Stop an application.
WriteINIProperties | The opposite to ReadINIProperties.
WritePropertiesFile | Write a single Settings file according to the properties in an INIFile structure.
Closed Container And Contributor
AddContributor | Adds a contributor to a container.
DeleteContributor | Removes a contributor from a container.
GetContributors | Returns a copy of an array of object values of contributors for a given container.
PContributor | (VTS Library) Draws a splitlist displaying all contributors to a specific tag.
Closed Cryptography
Base64Decode | Performs a Base64 decode of a buffer. If the two optional parameters are not supplied, this function simply calls Base64Decoder.
Base64Decoder | Performs a Base64 decode of a buffer.
Base64Encode | Wrapper for Base64Encoder
Base64Encoder | Performs a Base64 encode of a buffer
CheckSignature | Checks a digital signature with a key given a handle returned from Hash().
CryptRandom | Returns a buffer of random byte values.
Decode | Returns the plain value of a cipher that is the result of the Encode function.
Decrypt | The Decrypt function decrypts data previously encrypted using the Encrypt function. It is the VTScada analog of the CryptoAPI CryptDecrypt call.
DeriveKey | Generates a cryptographic session key from a seed value.
Encode | Processes a VTScada string using a configurable selection of compression, encryption, encoding and secure hashing.
Encrypt | The Encrypt function encrypts data. The algorithm used to encrypt the data is designated by the Key parameter. It is the VTScada analog of the CryptoAPI CryptEncrypt call.
ExportKey | The ExportKey function exports a cryptographic key or a key pair from a CSP in a secure manner as a Key BLOB. It is the VTScada analog of the Crypto API ExportKey call.
GenerateHMAC | Calculates the hash-based message authentication code (HMAC) for a given key and input message.
GenerateKey | The GenerateKey function generates a random cryptographic session key or a public/private key pair. A handle to the key or key pair is returned. This handle can then be used as needed with any CryptoAPI function requiring a key handle. It is the VTScada analog of the CryptoAPI’s CryptGenKey call.
GenerateSignature | Generates a digital signature of a handle returned from Hash().
GetCryptoProvider | The GetCryptoProvider function is used to acquire a handle to a particular key container within a particular cryptographic service provider (CSP). This returned handle can then be used to make calls to the selected CSP. It is the VTScada analog of the CryptoAPI CryptAcquireContext call.
GetKeyParam | The CryptGetKeyParam function retrieves data that governs the operations of a key. It is the VTScada analog of the CryptoAPI’s CryptGetKeyParam call.
Hash | Generates a hash - a text string of bytes - of the given string.
ImportKey | The ImportKey function transfers a cryptographic key from a key BLOB into a CSP (cryptography service provider). It is the VTScada analog of the CryptoAPI’s ImportKey call.
SetKeyParam | The SetKeyParam function customizes various aspects of a session key's operations. The values set by this function are not persisted to memory and can only be used with in a single session. It is the VTScada analog of the CryptoAPI SetKeyParam call.
Closed Database And Data Source
DBAdd | Executes in its own thread to add a record to a VTScada database and returns an indication of parameter errors.
DBGetStream | Executes in its own thread to convert a database to a stream, and returns an indication of parameter errors.
DBInsert | Identical to DBAdd, except will not update existing records.
DBListGet | Executes in its own thread to retrieve certain records from a list in a VTScada database and returns an indication of parameter errors.
DBListSize | Executes in its own thread to retrieve the size of a certain list in a VTScada database and returns an indication of parameter errors.
DBRemove | Executes in its own thread to remove a record from a VTScada database and returns an indication of parameter errors.
DBSystem | Creates a VTScada database and returns its value. The maximum field length is 65,523 characters. If the field length is longer than 65,523 characters, the DBSystem call will return invalid.
DBTransaction | Executes in its own thread to perform a transaction on a VTScada database and returns an indication of parameter errors.
DBUpdate | Executes in its own thread to update a VTScada database from a given stream and returns an indication of parameter errors.
DBValue | Returns a certain value retrieved from a VTScada database.
ODBC | Performs an ODBC command and returns a (dynamically allocated) array if required.
ODBCBeginTrans | Indicates to a specified ODBC-compliant database that a transaction is to be started.
ODBCColumns | Returns a dictionary of column names grouped by the tables that contain them.
ODBCCommit | Indicates to a specified ODBC-compliant database that a transaction is to be committed.
ODBCConfigureData | Configures an ODBC data source and returns its error code.
ODBCConnect | Forms a connection to an ODBC-compliant database and returns the ODBC value associated with that database.
ODBCDisconnect | Stops a connection to the ODBC database.
ODBCRollback | Indicates to a specified ODBC-compliant database that a transaction is to be rolled back (discarded).
ODBCSources | Retrieves a list of ODBC data sources and returns it as a (dynamically allocated) array.
ODBCStatus | Returns the requested information about the last ODBC statement to execute.
ODBCTables | Retrieves a list of the tables present in an ODBC-compliant database and returns it as a dynamically allocated array.
RegisterCustomTable | Registers a name for a virtual database table and defines what information will be available from that table.
SQLQuery | A launched module that executes an SQL query on data in a VTScada application.
TODBC | Performs an ODBC command. Similar to ODBC except that it runs in its own thread.
TODBCBeginTrans | Indicates to an ODBC-compliant database that a transaction is to be started. TODBCBeginTrans is similar to ODBCBeginTrans, except that it runs in its own thread.
TODBCCommit | Indicates to an ODBC-compliant database that a transaction is to be committed. TODBCCommit is similar to ODBCCommit, except that it runs in its own thread.
TODBCConnect | Forms a connection to an ODBC database. Similar to ODBCConnect except that it runs in its own thread (see "Comments" section for differences)
TODBCDisconnect | Stops a connection to the ODBC database. Similar to ODBCDisconnect except that it runs in its own thread (see "Comments" section for differences).
TODBCRollback | Indicates to an ODBC-compliant database that a transaction is to be discarded. TODBCRollback is similar to ODBCRollback, except that it runs in its own thread.
TServerList | Executes in its own thread and creates a pointer to an array of all servers visible from this workstation. Returns a flag indicating its status upon completion.
Closed DDE
DDE | Returns the value of the data for a specific item from a DDE server program. This function is a DDE client.
DDEPoke | Sends a value for a specific item to a DDE server program.
DDEShareAdd | Adds a new DDE share name to the SYSTEM.INI file or the registry and returns its own error code.
DDEShareDel | Deletes a DDE share name from the SYSTEM.ini file or the registry and returns its own error code.
SetDDEServer | Sets the DDE topic name for a window.
Closed Dictionary
ArrayToDictionary | Returns a dictionary if given an array of key names and a matching array of values.
ClearVarMetaData | The opposite of SetVarMetaData, this statement removes all metadata associated with a variable.
Dictionary | Creates a database-like storage structure that provides efficient addition, retrieval and removal of information linked to key values.
DictionaryCopy | Create a new dictionary with contents identical to an existing dictionary. It is expected that this function will be used rarely, since in most cases it will be more efficient to hand off a reference to a dictionary rather than build a duplicate of it.
DictionaryRemove | Removes a key / value pair from a dictionary, providing a means to regain memory space and remove data that is no longer needed.
GetKeyCount | Return a count of the number of keys stored by the given dictionary.
GetNextKey | Allows a linear search through a dictionary in place. i.e. without copying the contents to an array.
GetVarMetadata | Every variable object contains an embedded value. This function is used to retrieve those values.
HasMetaData | Tests whether a given variable is a dictionary. Because the default behavior of most operands and functions on dictionaries is to return just the value of the dictionary’s root, this function provides the only means to determine whether a variable contains a dictionary.
IsDictionary | A synonym for HasMetadata. Tests whether the parameter is a dictionary.
ListKeys | Returns an array of all keys used within a dictionary. It is expected that this function will be used primarily in the context of metadata (extended information attached to a variable). ListKeys also enables you to discover what is in a dictionary.
MakeDictionary | Create and initialize a dictionary with one line of code
MetaData | If used with a variable which is not currently a dictionary, this command attached meta data to that variable, thereby creating a dictionary object. The primary purpose in this case is to provide a means of associating extended data with a variable.
RootValue | Retrieves the root value from a dictionary. This function will always attempt to return a value that is not itself a dictionary. If the value stored as the root of the given dictionary is also a dictionary, this function will return the root value from that second dictionary. Should all root values be other dictionaries (which would imply that the dictionary at the end of the chain must actually be an earlier dictionary) then RootValue will traverse the chain until it finds a root value which is an earlier dictionary (i.e. the end of the chain before it loops back) and will return that root value. This is the only situation where the command will return a dictionary as the result.
SetVarMetadata | Every variable object contains an embedded value. This function is used to set those values.
Closed DLL
DLL | Returns a value of a type specified by its parameter from a call to Microsoft Windows™ dynamic link library using the C calling convention.
LoadDLL | Loads a Microsoft Windows™ dynamic link library.
Closed Editor
AddEditorText | Inserts a text string into a text editor.
CurrentLine | Deprecated. Returns the text string that is the current line in an editor.
Editor | Deprecated. Displays an editor on the screen.
ForceEvent | Deprecated. Forces the editor to perform an action based on the information provided.
GoToOffset | Deprecated. Forces an editor to move to a location in its text.
MakeEditor | Returns an editor value which is used by an editor
MoveEditor | Deprecated. Moves the Editor to the given line and column.
SetEditMode | Sets the graphics edit mode for a window.
ZEditField | Draws a layered text edit field in a window and returns a status value.
Closed Email
SendMail | Sends a string to an email server using the Simple Mail Transport Protocol (SMTP)
ValidateEmailAddrs | This subroutine validates a string of email addresses, and returns TRUE if the email addresses in the string are syntactically valid, or FALSE if they are not.
Closed Error Manager
ReportError | Post error information to VTS Trace and optionally, to the display.
Closed File I/O
CheckFileExist | (System Library) This subroutine checks for the existence of the specified file.
CheckPathExist | (System Library) This subroutine checks for the existence of the specified path.
CopyDir | (System Library) This subroutine recursively copies a directory's files and sub-directories down through the entire directory tree.
Dir | Performs a search in the given directory and returns an array of matching file names.
FileChooser | Provides an edit box for specifying a file name, along with a label and a browse button.
FileDialogBox | Displays a threaded system common file dialog box.
FileFind | Performs a recursive search down through the directory tree structure and returns an array of matching file names.
FileRootModule | Parses the document file that contains the given module to find the root module in that file. Returns the module value of the root module.
FileSize | Returns the size of a disk file in bytes.
FileStream | Returns a stream attached to a disk file or printer, and is suitable for use in SWrite.
FindFile |
FRead | Reads values from a formatted file and returns the number not read.
FWrite | Writes ASCII or binary data to a file and may also be used to create or delete a file. It returns the number of data items not written.
Get | Deprecated. Reads an array of historical data from a file (written by Save or SaveHistory) and returns the relative file position of the file entry following the last one read, or an error code.
GetFileAttribs | Returns information about the specified file.
GetHistory | Deprecated. Get History from a File written by Save or SaveHistory. This threaded function retrieves an array of data from a .DAT file for a certain time span. If the parameters to GetHistory are valid and an attempt is made to get the data, the return value is 0, otherwise, if no attempt is made to get the data, the return value is 1.
GetLog | This launched module returns an array of logged data. Marked for removal, but still in use as of VTScada 12.2. Use GetTagHistory instead for all new code.
GetLogInfo | Deprecated. Interrogates a historical data file, or a set of historical data files, and returns overall time, date, and record count information either for the entire file(set), or for a specified time range.
LoadMIB | Loads a specified MIB or set of MIBs and returns a dictionary describing the hierarchy of the MIBs.
MkDir | Creates a directory on a disk and returns its own error code
ModifyConfiguration | Provides a safe way to write to configuration files.
ModuleFileName | Returns the full path (including the drive letter) and file name of the document (.SRC) file of a module.
ReadConfiguration | This function provides a safe way to read configuration files.
ReadINI | This subroutine read a variable entry from a Settings file or a buffer containing one and returns its value.
ReadSectINI | This subroutine read an entire section entry from a Settings file or a buffer containing one and returns a 2-dimensional array containing variable names and their values.
ReadX | Reads numeric data from a text file into the elements of an array.
ReadXY | Reads data points from a file into the elements of two arrays.
Rename | Renames an existing file.
ResyncDoc | Synchronizes the time and date for the document and .RUN files.
RmDir | Destroys a directory on a disk and returns its own error code.
RUNFileName | Returns the name of the .RUN file for a module including the full drive and path.
RUNFileVersion | Returns the minimum version of VTScada that can read the .RUN files produced by the current version.
Save | Deprecated. This threaded function stores data in a circular historical data file at times indicated by a condition and returns the record number last written to disk.
SaveFile | Helper function to save files or streams on a server, VIC or Anywhere Client.
SaveHistory | Deprecated. This threaded function saves an array of data to a .DAT file for a certain time span.
SetCodeText | Will modify a source code file to replace the text for a given CodeValue with the new text.
SetFileAttribs | Sets the attributes of the specified file.
SpeakToFile | Executes on the speech thread to speak the supplied text to a .wav format audio file.
SplitPath | Breaks up a file path name into its components.
TempFileStream | Uses the OS tmpfile() function to create a temporary file on disk and to connect a stream to the temporary file. The temporary file is removed when the stream is closed or no longer referenced or if the VTScada process is terminated.
TGet | Deprecated. This threaded function reads an array of historical data from a file (written by Save or SaveHistory) and returns an indication of parameter errors.
WriteHistory | (Historian Manager Library) This subroutine writes a variable's value to a Settings file or a buffer containing one and returns its error code.
WriteSectINI | (System Library) This subroutine writes an entire section to a Settings file or a buffer containing one and returns its error code.
XMLWrite | Converts the instance of a type, as specified by XMLNodeTreeIn, into XML.
Closed Function Library
BinaryToIP | Converts an IP address from binary notation to decimal.
DetectFlatline | Returns TRUE if the monitored value stays the same for a specified length of time.
FormatInteger | Given a numeric value, returns that value converted to Hex, Octal or Binary as specified.
GetDisplayValue |
GetEquipmentColor | Returns a defined Equipment Color that was set in a style tag based on the equipment type of an I/O tag.
GetEquipmentLabel | Returns a defined Equipment Label that was set in a style tag based on the equipment type of an I/O tag.
GetPhrase | Returns the key matching a given phrase.
MakeParmPhrase | Returns a \ParmPhrase structure given a phrase key and parameters.
OilVolumeCorrectionFactor | Returns a coefficient to adjust a volume of oil to different temperature and pressure conditions.
OilVolumeCorrectionToBase | Wrapper for OilVolumeCorrectionFactor, used to determine the volume correction factor for shifting a fluid at alternate conditions to standard conditions (60°F, 0 psig).
ShellTemperatureCorrection | Returns a coefficient to adjust the calculation of volume within a tank.
TableInterpolation | Given a graph described by a CSV file containing X and Y values, this function will interpolate a Y value for any provided X value within the range of the graph.
TrimSpaces | Returns text with leading and trailing spaces removed.
Closed Graphics
4BtnDialog | (System Library) Draws a message dialog with up to 4 buttons and 3 lines of text and returns the number of the button that was pressed.
AlignSelected | Deprecated. Aligns selected graphic objects.
Bevel | (System Library) Draws a titled beveled box.
BitmapInfo | Returns information about an image.
Brush | Returns a brush value.
CaptureImage | Creates an image handle from a GUIStretch operation
CheckBox | (System Library) Draws a check box with (optional) label.
Click | Returns an indication of whether the mouse pointer is within a specified screen area and a particular button combination is being pressed.
ClosePopUp |
ColorSelect | (System Library) Color Selection Tool. This module draws a color selection button and its accompanying display area.
CommitFocused | This function causes any edit field, while being edited, to output the value currently found in that field.
Coordinates | Deprecated. Sets the VTScada screen coordinate limits (also called "world coordinates") used by the graphics functions.
CoordToPixel | Takes a specified coordinate pair within a given window and returns the overall, onscreen pixel location.
Crop | Modifies an existing image, producing a new one that displays a sub-section of the original.
DateSelector | Displays a calendar, from which operators can select a date.
DecodeParms | Takes a string of page parameters for a MenuItem tag and returns the values assigned for those parameters.
DialogInitPos | (System Library) Attempts to position a dialog so that it is not started beyond the left, right, top, or bottom of the visible screen.
DragHandle | Drags a selected graphic object's selected handle.
DrawArcPath | Draws an arc in any window.
DrawChordPath | Draws a chord in any window.
DrawEllipticalPath | Draw an ellipse in any window.
DrawPath | Draws a polygon in any window.
DrawPiePath | Draws a pie in any window.
DrawQRCode | Draw a QRCode at a given location.
DrawScale | (Meter Parts Library) Will draw a scale (i.e. tick marks) for a linear or radial type meter. These marks are images (normally lines) indicating the major and minor divisions of the entire scale. This function must be called inside a GUITransform to work properly.
DropList | (System Library) Draws a droplist with (optional) title or bevel or both.
Edit | (System Library) Draws an edit field with (optional) title or bevel or both.
EditINI | (VTS Library) Draws an edit field from which a value of an application property in Settings.Startup may be set.
EditINICheckBox | (VTS Library) Draws a check box with which an application property in Settings.Startup may be set true or false.
Editor | Displays an editor on the screen.
FileDialogBox | Displays a threaded system common file dialog box.
FocusID | Returns the focus ID of the object in a window that currently has the input focus.
Folder | (System Library) Draws a tabbed folder dialog.
Font | Returns a font value.
FontDialog | Displays a threaded system common font dialog box.
GetColorInfo | Returns the brush and pen information for a given graphic statement.
GetDisplayIndex | Returns the index of the caller's display instance.
GetDisplayRoot | Climbs the call tree looking for the best display context.
GetModuleRefBox | Get Module Reference Box
GetPathBound | Returns the bounding box coordinates for a path.
GetSelected | Returns a selected graphic item in a window.
GetSelectedInfo | Returns information about selected graphic item(s) in a window.
GetShapePath | Returns the path value which defines the shape of a polygon.
GetSystemColor | Returns the colors for the user-configured Windows colors.
GetTrajectoryPath | Returns the Path value which defines the trajectory of a graphic object.
GetTransform | Returns the transform value applied to a graphic statement.
GetXformRefBox | Get Transform Reference Box. This function returns the reference box for any transform of a module.
Grid | Places a (lined) grid pattern on the screen.
GridList | (System Library) Draws a list in the style of a spreadsheet.
GUIArc | Draws an arc in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUIBitmap | Draws an image of any of the following formats in a window and returns an indication when selected by a mouse button or the <ENTER> key. Available formats include: BMP, EMF, WMF, APM, CUT, PCX, JPG, PNG, and TIF
GUIButton | Draws a push-button in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUIChord | Draws a chord in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUIEllipse | Draws an ellipse in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUIPie | Draws a pie-shaped wedge in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUIPipe | Deprecated. Use PathDraw. Draws a 3 dimensional, shaded pipe in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUIPolygon | Draws a multi-sided polygon in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUIRectangle | Draws a rectangle in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUIText | Draws formatted text in a window and returns an indication when selected by a mouse button or the <ENTER> key.
GUITransform | Applies a graphical transformation to all graphics in a module and returns an indication when selected by a mouse button or the <ENTER> key.
HScrollbar | (System Library) Draws a horizontal scrollbar and returns its position.
HoursEntry | Displays a time editing field.
IconMarker | Deprecated. Creates the question mark and exclamation mark graphics, used to indicate questionable and manual data in a widget.
ImageArray | Reads an existing image handle and returns another one containing an image created from that handle by tiling the image a given number of times.
ImageParmSet | Returns a structure of image attributes that can be passed to an image-based widget.
ImageSweep | Reads an existing image handle and returns another one containing an image created from that handle by tiling the image a given number of times along an arc-shaped path.
IPAddressList | Displays a list of IP address which can be added to or removed from.
LastSelected | Returns the most recently selected graphics statement.
LinearIndicator | (Meter Parts Library) Will draw a linear type indicator. A linear indicator can be drawn in 3 different ways: Scaled from min to current position, cropped from min to current position or as a line that moves to the current position. This function must be called inside a GUITransform to work properly.
LinearLegend | (Meter Parts Library) Draws a legend (i.e. the text labels) for a linear type meter. They are drawn in a line, either horizontally or vertically, with consistent spacing. This function must be called inside a GUITransform to work properly.
Listbox | (System Library) Draws a listbox with scrollbar (if required) and indicates the selected item.
MakeBitmap | Loads an image file of types BMP, EMF, WMF, APM, CUT, PCX, JPG, PNG, or TIF into memory and returns a handle to the result. Returns Invalid upon failure.
MapDraw | Draws a "slippy" map, showing a list of site tags as pins on that map.
ModifyBitmap | Reads an existing image handle and produces a new one with modifications. The original image is not altered. Returns invalid upon failure.
ModuleSnapshot | Launched module that draws a module as an image.
MoveWindow | Will move a window to the specified coordinates.
NextFocusID | Moves the focus position to a specific ID number.
Normalize | Returns a normalized value.
NumSelected | Returns the number of selected graphics statements in a window.
Output | Deprecated. Places formatted numbers or text on the screen.
PalStatus | Returns the current palette settings.
ParentWindow | Returns the object value of the nearest non-child window.
PasteObjects | Pastes the code for multiple GUITransforms into a page source file.
Path | Returns a graphics path value.
PathDraw | Used within a Idea Studio handler to inform the engine that a path is being drawn, and to set the appearance of that path
Pen | Returns a pen value.
Pending | Returns the number of statements of a certain type pending.
Pick | Returns an indication of whether the locator (e.g. mouse) has had a specified change in its button status.
Pipe | Deprecated. Draw a Double Line
PixelColor | Returns the color of a pixel in the window.
PhraseDroplist | Language-sensitive droplist.
PhraseEdit | Language-sensitive editfield. This module draws an editfield with (optional) title and bevel.
Plot | Displays a plot of a subsection of a numeric array in a particular area of the window.
PlotBuff | Displays a plot of a subsection of a buffer in a particular area of the window after converting the buffer to element values.
PlotXY | Displays a plot of a curve in the window given the X and Y values in two arrays.
Point | Returns a two-dimensional point, or location, in a window.
Popup | (Alarm Manager module) Causes an alarm pop-up dialog to display.
PrintDialogBox | Displays a threaded system common printer selection dialog box.
ProgressBar | Displays a horizontal progress bar.
RadialIndicator | (Meter Parts Library) Will draw a radial type indicator that sweeps from a minimum angle to a maximum angle in the same fashion that a real radial meter would.
RadialLegend | (Meter Parts Library) Draws a legend (i.e. the text labels) for a radial type meter. They are drawn at a constant radius from the center point of the drawing coordinates, beginning at a defined minimum angle and ending at a defined maximum angle.
RadioButtons | (System Library) Draws a set of labeled radio buttons with (optional) title and border.
RootTransform | Returns the object value that contains the root transform applied to the given module.
Rotate | Returns a Rotate value, which specifies a rotation about a point.
SaveImage | Takes an image handle and saves it to an image file on disk.
SectionControl | (System Library) Creates a control that displays a variable number of sections. Visually, a section consists of a header and content. The control manages the layout and geometry for the sections and runs a caller-supplied module to display the section content.
SelColor | Sets a color value from a dialog
SelectArea | Selects active graphics statements within a rectangular area in a window.
SelectCodePointer | Given a window object and a code pointer for an active graphics object within that window, this function adds the graphics object to the window's selection set.
SelectDAG | (i.e. Select Function) This function selects an active graphics DAG.
SelectGraphic | Selects an active graphics statement at a location in a window.
SelectHandle | Returns a pointer to a handle of selected graphics statements at a location in a window.
SelectHandleNum | Selects the given handle of selected graphics statements in a window.
SelectPath | Selects a path given its code pointer value.
SetCursor | Sets the mouse cursor type for the window.
SetHandle | Sets the position of graphics handles in a window.
SetModuleRefBox | Sets the reference box for a single instance of a module.
SetModuleRefBox | Sets the default reference box for a module.
SetRefRect | Sets the first four constant parameters of a layered graphic statement.
SetXLoc | Sets the X screen location of the locator (mouse).
SetYLoc | Sets the Y screen location of the locator (mouse).
ShowPage | When called with a Page Name, will cause that page to display in the caller's display session context
SimulateMouse | Sets the pointer location and sends a button press with modifiers such as Ctrl, Shift or Alt. (mouse)
SpinBox | (System Library) Draws a spinbox with (optional) label.
SplitList | (System Library) Draws a split list (listbox with two columns) with a scrollbar if required and indicates the selected item.
SplitListSelector | (System Library) Draws a split view comprising two GridLists separated by control buttons. Items listed on the left may be selected to be transferred to the right. Items on the right may be returned to the left so long as they were originally listed on the left. Scrollbars will be drawn if required.
SplitTagSelector | Draws a split view comprising two GridLists separated by control buttons. Tag names listed on the left may be selected to be transferred to the right. Each GridList will have two columns: the name and the description of each tag in the list. Scrollbars will be drawn if required.
StopPage | Subroutine to close all instances of a page.
Tag | Returns a Tag value, which works like (and in place of) a Normalize value.
TagIconMarker | Draws an "IconMarker" in the center of its transform area, and optionally shows a blank icon when in editing mode.
TextAttribs | Returns graphic-related information about a text, given a font.
TextBox | (System Library) Displays a text string, breaking it into multiple lines at space or CRLF.
ToolBar | (System Library) Draws and maintains a toolbar and its buttons.
Trajectory | Move a Layered Graphic and return a Trajectory value.
TreeControl | Implements a tree control similar to that used by the Microsoft Windows Explorer folder panel.
UnselectGraphics | Will deselect all of the graphics in the specified window.
UnselectObject | Will deselect a statement in the context supplied.
UnTransform | Will undo a previous transform so that the module instance and everything it has called will not be transformed.
UpdateCoordinates | Will update a graphic statement's coordinates to the document file in which it is specified.
Vertex | Returns a Vertex value, which is a collection of 3 points and a mode.
VScrollbar | (System Library) Draws a vertical scrollbar and returns its position.
WebBrowser | Displays a web browser at the given position in the current VTScada window
WebBrowserNavigate | Call this to cause a WebBrowser to change pages.
WinButton | Windows native button.
WinComboCtrl | Windows native "combo" control. A "combo" control is an enhanced form of drop list. Displays a child window containing a Windows combo control.
WinEditCtrl | Windows native edit control. This function returns a value indicating the status of an edit field.
WinTooltipCtrl | Windows native "tooltip" control. A "tooltip" is a pop-up text window that provides operational hints to users when the mouse pointer is rested over a tool or object.
WinYLoc | Returns the Y coordinate of the locator (mouse) in a window.
XLoc | Returns the X window coordinate of the locator (mouse).
YLoc | Returns the Y window coordinate of the locator (mouse).
ZBar | Draws a layered bar in a window.
ZBox | Draws a layered box in a window.
ZButton | Draws a layered button in a window and returns true when selected.
ZColorChange | Changes one color within a region to another color.
ZEditField | Deprecated. Draws a layered text edit field in a window and returns a status value.
ZGrid | Draws a layered point grid in a window.
ZLine | Draws a line between given x and y coordinates in a window.
ZPipe | Deprecated. Draws a layered three-dimensional pipe in a window.
ZText | Draws a layered text label in a window.
Closed Graphics P-Tools

A special sub-set of the Graphics tools, these are used only in tag configuration panels. All are members of the dialog library.

PAddressEntry | Used for Tag I/O address entry.
PAlmPriority | Draws a droplist of the currently available alarm priorities with an optional title and bevel.
PAreaSelect | Draws a droplist of area options with (optional) title and bevel.
PCheckBox | Parameter Setting check box. This module draws a check box with (optional) label.
PColorEdit | Wrapper module for the standard color editing parameters
PColorSelect | Draws a button that opens a color selection dialog and an area that displays the currently selected color.
PContributor | Draws a split list displaying all contributors to a specific tag.
PDroplist | Parameter Setting Droplist. This module draws a droplist with (optional) title and bevel.
PEditField | Parameter Setting Editfield. This module draws an editfield with (optional) title and bevel.
PEditName | Tag name setting editfield. This module draws an editfield that is to be connected to the name of a tag. Should be used by all tag ConfigFolder modules for setting the name parameter.
PFileChooser | Parameter setting file selection. Provides an edit box for specifying a file name, along with a label and a browse button.
PHSliderBar | Connects a horizontal slider bar to a given parameter number.
PHueSelect | Connects a hue selection tool to a given parameter number.
PImageSelect | Connects an image selection tool to a given parameter number.
PIPAddressList | Uses an IPAddressList to set a parameter with a semicolon-delimited IP address list.
PIPListenerGroup | Draws a droplist of all available IP Listener Groups.
PMultiCheckBox | Display the standard set of check boxes.
POverride | Tool used to override non-standard ConfigFolder controls for child tags.
PPageSelect | Draws a titled, beveled droplist of pages in the system.
PPhraseDroplist | Handles the complexity of parameter expressions by switching between display of a PhraseDroplist and regular Droplist control as is done in PPhraseEdit.
PPhraseEdit | Draws a language-sensitive editing field.
PRadioButtons | Draws a set of labeled radio buttons with optional title and border.
PSecBit | Draws a titled, [beveled] droplist of options for setting the security bit.
PSelectCertificate | Draws a drop-down for selecting a certificate from a list of available certificates, fields for displaying basic certificate information, and a button for accessing the Certificate Management UI.
PSelectObject | Draws a beveled, titled box showing the currently selected tag, a button to modify the connection in the hierarchy, and a new tag creation button.
PServerListName | Called graphic module that creates an editable droplist of Server List Names, available to the tag.
PSpinbox | Parameter Setting Spinbox. This module draws a spinbox with (optional) label.
PTimeZone | Parameter Setting Droplist. Tool used to display a list of timezones, as defined by the operating system.
PTypeToggle | Parameter Setting Type Toggled Field. This module draws a beveled droplist or editfield with title that sets a tag or numeric value.
SiteDispParms | Parameter setting tool for Site List display options. While not part of the dialog library, and not starting with the letter "p", this is still classified as one of the PTools.
Closed Help
EnableHelp | Enables you to enable or disable help file activation when the F1 key is pressed.
Help | Calls Windows™ help.
SetHelp | Sets the help file name and (optionally) the context identifier for the window containing the specified object.
Closed Keyboard
FocusID | Returns the focus ID of the object in a window that currently has the input focus.
KeyCount | Returns the number of keys pressed since the state became active, either edited or non-edited.
KeyFake | Places a string of characters in a window's keyboard buffer.
Keys | Returns the most recently pressed keys from either the edited or non-edited keystrokes.
MatchKeys | Returns true if the specified keyboard keys have been pressed in the sequence given.
NextFocusID | Moves the focus position to a specific ID number.
WinMatchKeys | Returns true if the specified keyboard keys have been pressed in the sequence given in another window.
WinShiftKeys | Deprecated. Returns a value which contains the current status of the Shift, Control and Alt control keys.
Closed Locator
Click | Returns an indication of whether the mouse pointer is within a specified screen area and a particular button combination is being pressed.
CurrentWindow | Returns the application window over which the mouse cursor currently rests.
LocCapture | Capture Locator Input. This statement captures all subsequent input from the locator device and routes it to a specific window.
LocSwitch | Returns the current status of the locator (mouse) buttons over the window which contains the LocSwitch statement.
Pick | Returns an indication of whether the locator (e.g. mouse) has had a specified change in its button status.
SetCursor | Sets the mouse cursor type for the window.
SetXLoc | Sets the X screen location of the locator (mouse).
SetYLoc | Sets the Y screen location of the locator (mouse).
Target | Returns an indication of whether the locator (e.g. mouse) is within a specified screen area.
WinLocSwitch | Returns the current status of the locator (mouse) buttons in a certain window and its ancestors.
WinTooltipCtrl | Windows native "tooltip" control. A "tooltip" is a pop-up text window that provides operational hints to users when the mouse pointer is rested over a tool or object.
WinYLoc | Returns the Y coordinate of the locator (mouse) in a window.
XLoc | Returns the X window coordinate of the locator (mouse).
YLoc | Returns the Y window coordinate of the locator (mouse).
Closed Log
AddNote | Add a note to the notebook
Get | Reads an array of historical data from a file (written by Save or SaveHistory) and returns the relative file position of the file entry following the last one read, or an error code.
GetHistory | Get History from a File written by Save or SaveHistory. This threaded function retrieves an array of data from a .DAT file for a certain time span. If the parameters to GetHistory are valid and an attempt is made to get the data, the return value is 0, otherwise, if no attempt is made to get the data, the return value is 1.
GetLog | This launched module returns an array of logged data. Marked for removal, but still in use as of VTScada 12.2. Use GetTagHistory instead for all new code.
GetLogInfo | Interrogates a historical data file, or a set of historical data files, and returns overall time, date, and record count information either for the entire file(set), or for a specified time range.
GetTagHistory | (Historian Manager Library) Launched module that retrieves historical data for a tag. Replaces GetLog.
HistorianConnect | Opens a logging connection and controls the lifetime of all resources associated with that connection.
LogNTEvent | Logs events to the system event log.
SaveHistory | This threaded function saves an array of data to a .DAT file for a certain time span.
TGet | This threaded function reads an array of historical data from a file (written by Save or SaveHistory) and returns an indication of parameter errors.
Closed Logic Control
Boolean | (System Library) Takes a valid Boolean test and returns the numeric equivalent.
Case | Selects one of a set of parameters for execution and returns its return value.
Cond | Returns one of two values depending upon the result of a conditional expression.
DoLoop | Executes a do-while loop in a script.
Execute | Executes a group of statements as a single entity in structures that would otherwise allow only one statement to be executed.
False | Evaluates to 0 or tests whether an optional parameter evaluates to 0.
ForceState | Sets the next state to start when the action script completes.
If | Trigger to perform an action. It changes the active state in a module instance or executes a script or does both.
IfElse | Executes one of its two parameters based upon a condition parameter.
IfOne | Check for an If One Condition. This function checks for a race condition in an action script and returns the value of the location.
IfThen | Conditionally Execute Statements. This statement executes a statement if the condition parameter is true.
Invalid | Return Invalid Value. This function always returns an invalid value.
PickValid | Attempts to return a valid value given a list of parameters.
True | Evaluates to 1 or tests whether an optional parameter evaluates to 1.
WhileLoop | Repeatedly executes a parameter while a condition is true.
Closed Math - Generic
Abs | Returns the absolute value of a numeric expression.
AMax | Array maximum. This function returns the maximum value in a sub-range of a numeric array.
AMin | Array minimum. This function returns the minimum value in a sub-range of a numeric array.
CommaFormat | Returns the text version of a number, formatted to use embedded commas.
Deriv | Returns the derivative (rate of change) of a value.
Edge | Performs a test for a rising or falling edge.
Exp | Returns the natural antilogarithm of a numeric expression.
FFT | Performs a fast Fourier transform between time and frequency domains.
FitOffset | Linear regression offset. This function returns the offset or Y intercept of the least square curve fit of data in a pair of arrays.
FitR2 | Returns the coefficient of determination (i.e. r2) for a linear curve fit. This number gives a measure of how correct the curve fit is.
FitSlope | Linear regression slope. This function returns the slope of the least square curve fit of data in a pair of arrays.
FormatInteger | Returns a text string which is a decimal value converted to one of binary, octal or hexadecimal formats.
Intgr | Time Integral. This function returns the time integral of a value.
Ln | Returns the natural logarithm (base e) of a value.
Log | Returns the common logarithm (base 10) of a number.
LValue | Left-hand Side Value. This function returns an indication of whether its argument can be used on the left-hand side of an assignment.
Max | Returns the maximum of a group of parameters.
Mean | Returns the mean (average) of a portion of a numerical array.
Min | Returns the minimum of a group of parameters.
PercentDifference | Returns the percentage difference between two numbers
Pow | Returns a number raised to a power.
Rand | Returns a random number between 0 and 1.
Scale | Returns a value that has been converted from one scale to another.
SDev | Returns the statistical sample standard deviation for a subsection of an array.
Sqrt | Returns the square root of a number.
Sum | Returns the arithmetic sum of all the valid array elements in a specified portion of a numeric array.
SumBuff | Returns the summation of bytes in a buffer.
Tag | Returns a Tag value, which works like (and in place of) a Normalize value.
Variance | Returns the statistical sample variance for a subsection of an array.
Closed Math - Rounding
Ceil | Returns the smallest integer greater than or equal to a number (the ceiling).
DeadBand | Returns the previous value of the first parameter until it changes by an amount specified by the second parameter.
Int | Integer Portion of Number. This function returns the portion of a number before the decimal point. Also used for rounding.
FormatNumber | Returns a compactly formatted version of a number, containing at least the specified number of significant digits.
Limit | Set Value Minimum and Maximum. This function returns a value that is limited both on the high and low ranges.
Step | Transforms a continuous value into discrete steps.
Closed Math - Trigonometric
ACos | Calculates the trigonometric arc cosine in radians.
ASin | Returns the trigonometric arc sine in radians.
ATan | Returns the trigonometric arc tangent in radians.
Cos | Returns the trigonometric cosine of an angle in radians.
Sin | Returns the trigonometric sine of an angle in radians.
Tan | Returns the trigonometric tangent of an angle in radians.
Closed Memory I/O
AddRead | Add a read request. This module is called by a tag to add a request to read a specific range of memory and set the resulting read data into the variable pointed to by the third parameter. The pointer may be a simple variable for one element read, or an array if more than one element is requested.
CopyIn | Copies data from an absolute RAM address and returns a buffer.
CopyOut | Copies data from a buffer to an absolute RAM address.
DelRead | Is called by a tag to delete an existing read request, as created by an AddRead.
In | Read I/O Byte. This function returns the byte read from an I/O port.
InWord | Read I/O Word. This function reads a 16 bit unsigned word from an I/O port.
MemIn | Returns a byte, word, or longword of RAM memory.
Memory | Returns the amount of memory that VTScada has acquired from the OS heap for internal use.
MemOut | Writes a byte, word, or longword of RAM memory.
MemTrace | Writes memory allocation information to a file.
New | Allocates memory for an array from RAM and returns a pointer to that array.
Out | Writes an 8 bit byte to an I/O port.
OutWord | Writes a 16 bit word to an I/O port.
Closed Modem
ModemCount | Returns the number of data modems configured and operational in the system.
ModemDev | Obtains the identifier for a modem sub-device. (In order to use the audio capabilities of a voice modem, the device identifier for the wave output device is required.)
ModemDial | Dials and attempts to connect to a remote modem and returns the modem stream or an error code.
ModemDigits | Controls the receipt of DTMF digits entered from the keypad of a telephone engaged on a voice call via a voice modem.
ModemList | Returns a list of the modems in the system. This function should be used to determine the correct parameter for the ModemStream or ModemDial functions.
ModemMedia | Enables you to determine the media mode of a serial stream open on a modem, and change it if necessary (for example, if you require the ability to be able to handle both incoming voice mode and data mode calls).
ModemStream | Open a serial stream on a modem and returns its status (prior to the connection being made), a modem stream (after the connection has been established), or an error code.
ModemTransfer | Transfers a modem call to another application and returns an indication of success.
PPPDial | Creates a PPP connection to a remote peer. The connection can be via a dial-up or direct device connection.
PPPHandles | Returns an array of all Point-to-Point Protocol handles on the local machine.
PPPDial | Describes the status of a PPP connection.
Closed Module - Advanced
ActiveCode | ActiveCode returns the code value of the currently active statement in the given module instance.
AddModule | Adds a new module to an existing module and returns the value of the newly created module.
AddParameter | Adds an existing variable as a module parameter and returns the number of parameters in the module.
AdjustCode | Adjusts the offsets and sizes of items stored in the .RUN file within the document file.
CalledInstances | Returns the object values of module instances that are called by a particular module.
CanEditDoc | Returns an indication as to whether the document for the given module can be edited.
ChildDocs | Gets the module values for the root and all descendent modules that match the conditions defined by the second parameter.
CleanModule | Removes the flag that marks when a module that has been changed programmatically and would therefore have its changes saved to disk were this flag not cleared.
ClearModule | Deletes the contents (all variables and states) of a module without removing the module itself.
CodeText | Returns the text (or other information) for a given Code Value.
ConstCount | Deprecated. Do not use in new code.
CoverageSnapshot | Captures the areas in a VTScada source file which have not executed along with summary statistic for each module in the file to extract code coverage information.
CreateModule | Creates a new module and returns a pointer to it.
CrossReference | Returns a linked list of structures representing all references to a specified variable or module.
DeleteModule | Deletes a module from the system.
FileRootModule | Parses the document file that contains the given module to find the root module in that file. Returns the module value of the root module.
FormalParms | Returns the number of formal parameters declared in a module.
GetModuleRefBox | Get Module Reference Box
GetModuleText | Returns information about a module's document file.
GetOneParmText | Returns the text for one parameter of a function.
GetOverrides | Returns an array of OpCodes and the module value that will run when each OpCode is executed
GetParameter | Returns the requested parameters as a constant, variable or code pointer.
GetParmText | Returns the text for all parameters of a function.
GetTagConfiguredParameters | To be used with OPChange or ModifyTags, this API makes it possible to revert a tag parameter to its default or remove an override by changing some configured parameters while keeping others.
GetTransitText | Get Transition Document Text. This function returns information about the documentation of an action.
GetXformRefBox | Get Transform Reference Box. This function returns the reference box for any transform of a module.
GUITransform | Applies a graphical transformation to all graphics in a module and returns an indication when selected by a mouse button or the <ENTER> key.
ImportAPI | Imports objects of class API from a given module, for use in the calling module.
LoadModule | Loads a module from its .RUN files and returns a pointer to that module.
MCSInstance | Module Calling Structure Instance. This function returns the object value of a module called by another module.
MCSMod | Module Calling Structure Module. This function returns the module value from a line of code that calls that particular module.
ModuleFileName | Returns the full path (including the drive letter) and file name of the document (.SRC) file of a module.
NParm | Returns the number of parameters listed in a module instance.
NumParms | Returns the number of parameters of a statement.
OwningModule | Returns the module which contains a certain variable.
Pack | Packs a set of module parameters or an array of values into a stream, and returns the number of items that were not packed.
ParentModule | Returns the parent module of a module.
ParentObject | Returns the parent object of a module.
ParmToBuff | Returns a buffer of formatted numeric parameter values.
PType | Returns the actual type of parameter at an index.
RemoveParameter | Removes a parameter from a module's parameter list.
ResetParm | Can reset parameters that become latched.
ResyncDoc | Synchronizes the time and date for the document and .RUN files.
RootTransform | Returns the object value that contains the root transform applied to the given module.
RUNFileName | Returns the name of the .RUN file for a module including the full drive and path.
RUNFileVersion | Returns the minimum version of VTScada that can read the .RUN files produced by the current version.
SaveModule | Saves a module definition to its *.RUN file.
SectionControl | (System Library) Creates a control that displays a variable number of sections. Visually, a section consists of a header and content. The control manages the layout and geometry for the sections and runs a caller-supplied module to display the section content.
SetCodeText | Will modify a source code file to replace the text for a given CodeValue with the new text.
SetModuleRefBox | Sets the reference box for a single instance of a module.
SetModuleRefBox | Sets the default reference box for a module.
SetModuleText | Sets the module's .SRC file information.
SetOneParmText | Sets the text for one parameter of a function.
SetOverride | Allows the overriding of OpCodes with a specified script module within a static module tree.
SetParameter | Sets a parameter in a statement.
SetParmText | Sets the text for the parameters of a function.
UnTransform | Will undo a previous transform so that the module instance and everything it has called will not be transformed.
UpdateCoordinates | Will update a graphic statement's coordinates to the document file in which it is specified.
Closed Module - Basic
AddLock | Creates a Control Lock on a selected tag.
CanAddLock | Finds whether the user has the privilege to add a Control Lock.
CanControl (Control Lock Manager) | Finds whether a tag is locked.
CanRemoveLock | Finds whether the user may remove a lock.
Call | Starts an instance of the module specified by its first parameter.
Caller | Takes a given object value for a module and returns the object value of the module by which it was called.
ChildInstances | Returns the object values of module instances that are children of a particular module instance (i.e. all objects whose parent is a specified object).
CriticalSection | Marks a section of a module as a critical section and will not allow interruption of its execution by other threads.
DoOperate | Used by tags that can be operated from the Tag Browser, this displays an input dialog where users can enter the new value to write. Should be overridden for use with tags other than those that write analog, digital or string values.
GetAllTagTypesInGroup | Returns an array of all Tag Types in a Tag Group.
GetInstance | Returns the object value of a module instance.
GetLockLevel | Returns the Lock Level of a given Control Lock.
GetModuleTimeStamp |
GetTagList | Returns an array of tags, starting at a given point in the tag tree and including all child tags below that point, subject to the filtering parameters.
GetTagMode | Returns text or a structure to identify what kind of tag a given instance is.
GetTagTypes | Returns an array of either the common names or the module names of all tag types.
GetReturnValue | Returns a module's return value.
HasReturnStatement | Examines a specified object to see if it is currently running a return statement in steady-state.
Instance | Limit Module Instances. This function limits the number of fixed module instances allowed to run simultaneously and returns the old limit
IsChild | Identify Child Module. This function returns an indication of whether one module is a child module of another.
IsTagOperable | Returns TRUE if the user is able to operate the selected tag from the Tag Browser using the right-click menu.
Launch | Runs a module instance and returns a pointer to it.
ListInstances | Returns a list of all instances of a module.
LocalScope | Equivalent to Scope(Obj, Name, TRUE). LocalScope is a useful shortcut where the second parameter is not a constant string.
LocalVariable | LocalVariable(Name) is a shortcut for Scope(Self, Name, TRUE).
NumInstances | Returns the number of module instances currently running.
Parameter | Returns the value of (or may assign a value to) a parameter of a module, specified by the index.
ParameterEdit | Draws an interface to allow the user to choose how to edit a parameter. Used in tag widgets.
ColorParameterEdit | ParameterEdit Wrapper - allow user to modify a color
DurationParameterEdit | ParameterEdit Wrapper - allow user to set a time duration
MultiCheckboxParameterEdit | Use this function to make any number of check boxes in a group.
NumericParameterEdit | ParameterEdit Wrapper - allow user to modify a numeric value
TagParameterEdit | ParameterEdit Wrapper - allow user to choose a tag
TextParameterEdit | ParameterEdit Wrapper - allow user to enter a text value
TimestampParameterEdit | ParameterEdit Wrapper - allow user to set a timestamp
UnTypedParameterEdit | ParameterEdit Wrapper. Add control to a panel without defining the type.
PointList | Returns an array of tag names within the current scope, given the name of a tag type or group.
Return | Sets the return value for the module in which it is executed.
RemoveLock | Removes a lock from a tag (assuming the current user has the privileges to do that.)
RootWindow | Returns the object value of the root (original) module displayed in the same window.
Scope | Performs a scope resolution and returns a reference to the requested member within a module or other object.
ScopeLocal | Deprecated. As above except that ScopeLocal will not look outside the given context.
Self | Returns the object value of the current module.
SetInstanceName | Set the name of an instance of a module.
SetReturnValue | Sets the return value of a specified object if the object is not currently running a Return() statement in steady state.
Slay | Stops a launched module, and possibly any parent modules.
SystemSelf | Returns the object value of the system module for the given application.
Thread | Launches a module in its own separate thread.
ThreadHistory | Returns in an array the history of execution for a specified thread.
ThreadIdle | Returns TRUE when the ToDo list for a given thread is empty.
ThreadList | Returns a two dimensional array containing the name and statement last executed by each VTScada thread.
ThreadName | Returns the name of a thread.
ThreadPriority | Allows advanced users to set a specified thread to one of six priorities, ranging from idle to time critical.
WCSubscribe | Working Copy Subscribe. After this function has been called, any configuration change will result in the specified callback subroutine being called.
Window | Opens a new window, starts a module inside, and eventually returns the module's value.
Closed Network & Workstation

See also: RPC Manager Functions.

CheckIPMask | Determines whether an IP Address is in the address ranges defined by MaskSet.
GetAdaptersInfo |
GetGUID | Creates a globally unique identifier or converts an existing GUID to another format.
GetHostByName | Calls the WinSock gethostbyname function and returns the host name, address(es) and alias names for the named computer.
GetPowerState | Returns a structure that describes the state of the power supply to the workstation. Relevant when the workstation is running on battery power.
IPMaskToText | Extracts an IP mask from MaskSet and converts it to text, returning the new text value.
LocalGroup | Returns an indication of whether the current Windows™ user is a member of the specified local group. LocalGroup interrogates only local groups, not domain groups.
MakeIPMask | Make an IP mask set by returning text holding the encoded binary IP address and mask. Works for IPv4 and IPv6.
OPCServer | Adds a new top-level branch to the VTScada OPC Server’s namespace hierarchy.
GetOPCServerRequestRate | Returns the total number of OPC Classic callbacks per second.
Platform | Returns a twelve element structure that indicates the platform under which VTScada is currently running.
Redirect | Redirects a local device to network resource.
Register (RPC Manager) | (RPC Manager Library) This subroutine registers a service for RPC and returns a pointer to the variable containing the current RPC status of the service.
RunPack | (RPC Manager Library) Is unpacks and executes a set of RPCs from a stream constructed with PackRPC.
Send | (RPC Manager Library) This subroutine sends a message by invoking a remote procedure call (RPC).
ServerList | Returns a pointer to an array of all available servers visible from this workstation.
ServerSocket | Returns a server WinSock socket stream given a handle returned by a SocketServerStart function or an integer error code.
SetAllBlocks | (RPCManager Library) This subroutine executes on the client. It accepts all of the blocks and data for a service.
SetOPCData | Sets an item value in the VTScada OPC Server.
TServerList | Executes in its own thread and creates a pointer to an array of all servers visible from this workstation. Returns a flag indicating its status upon completion.
WKSList | Generates a list of sub-paths from the query returned by the WKSPath function.
WKSPath | Given set of path components, generates a query path for use in the WKSStatus command.
WKSStatus | Sends a query to the Windows™ Performance Monitor interface (see image in WKSPath) and returns the result as a query handle.
WKStaInfo | Returns the characteristic information about this workstation.
Closed ODBC
AddConnection | (ODBC Manager Library) Called to get the object value of an ODBC connection. If the connection does not exist, then a new ODBC DSN connection will be created and explicitly added to the ODBC Manager's internal list of DSN's
ErrMessage | (ODBC Manager Library) Returns a text message for the error code handed to it as a parameter
ODBC | Performs an ODBC command and returns a (dynamically allocated) array if required.
ODBCBeginTrans | Indicates to a specified ODBC-compliant database that a transaction is to be started.
ODBCCommit | Indicates to a specified ODBC-compliant database that a transaction is to be committed.
ODBCConfigureData | Configures an ODBC data source and returns its error code.
ODBCConnect | Forms a connection to an ODBC-compliant database and returns the ODBC value associated with that database.
ODBCDisconnect | Stops a connection to the ODBC database.
ODBCRollback | Indicates to a specified ODBC-compliant database that a transaction is to be rolled back (discarded).
ODBCSources | Retrieves a list of ODBC data sources and returns it as a (dynamically allocated) array.
ODBCStatus | Returns the requested information about the last ODBC statement to execute.
ODBCTables | Retrieves a list of the tables present in an ODBC-compliant database and returns it as a dynamically allocated array.
ResultFormat | (ODBC Manager Library) Subroutine to convert 2-d array as returned from query in the form, Arr[Field][Rec], to a normalized format of Arr[Rec][Field].
SQLQuery | A launched module that executes an SQL query on data in a VTScada application.
TableSynch | (ODBC Manager Library) Synchronizes the fields matching a specified criteria within matching tables in two databases. Should be run as a called module, waiting for completion. Do not call as a subroutine.
TODBC | Performs an ODBC command. Similar to ODBC except that it runs in its own thread.
TODBCBeginTrans | Indicates to an ODBC-compliant database that a transaction is to be started. TODBCBeginTrans is similar to ODBCBeginTrans, except that it runs in its own thread.
TODBCCommit | Indicates to an ODBC-compliant database that a transaction is to be committed. TODBCCommit is similar to ODBCCommit, except that it runs in its own thread.
TODBCConnect | Forms a connection to an ODBC database. Similar to ODBCConnect except that it runs in its own thread.
TODBCDisconnect | Stops a connection to the ODBC database. Similar to ODBCDisconnect except that it runs in its own thread.
TODBCRollback | Indicates to an ODBC-compliant database that a transaction is to be discarded. TODBCRollback is similar to ODBCRollback, except that it runs in its own thread.
Transaction | (ODBC Manager Library) Launches a transaction in the specified database connection. The transaction takes care of its own shut-down process.
TransactionCached | (ODBC Manager Library) Launches a transaction in the specified database connection. The transaction will be cached locally if it fails and then sent to the database after the next successful transaction. This module is designed to provide logging of values that must not be lost.
Closed Oil and Gas
OilVolumeCorrectionFactor | Returns a coefficient to adjust a volume of oil to different temperature and pressure conditions.
OilVolumeCorrectionToBase | Wrapper for OilVolumeCorrectionFactor, used to determine the volume correction factor for shifting a fluid at alternate conditions to standard conditions (60°F, 0 psig).
ShellTemperatureCorrection | Returns a coefficient to adjust the calculation of volume within a tank.
TableInterpolation | Given a graph described by a CSV file containing X and Y values, this function will interpolate a Y value for any provided X value within the range of the graph.
Closed PTools (Properties Dialog Helper Functions)
ParameterEdit | Draws an interface to allow the user to choose how to edit a parameter. Used in tag widgets.
ColorParameterEdit | ParameterEdit Wrapper - allow user to modify a color
DurationParameterEdit | ParameterEdit Wrapper - allow user to set a time duration
MultiCheckboxParameterEdit | Use this function to make any number of check boxes in a group.
NumericParameterEdit | ParameterEdit Wrapper - allow user to modify a numeric value
TagParameterEdit | ParameterEdit Wrapper - allow user to choose a tag
TextParameterEdit | ParameterEdit Wrapper - allow user to enter a text value
TimestampParameterEdit | ParameterEdit Wrapper - allow user to set a timestamp
UnTypedParameterEdit | ParameterEdit Wrapper. Add control to a panel without defining the type.
PAddressEntry | To be used for Tag I/O address entry. Checks whether the attached driver has an AddressAssist module and uses that if available.
PAlmPriority | Draws a droplist of the currently available alarm priorities with an optional title and bevel.
PCheckBox | Parameter Setting check box. This module draws a check box with optional label.
PColorEdit | Wrapper module for the standard color editing parameters including hue, saturation, brightness, transparency, contrast, colorizing hue and intensity.
PColorSelect | Draws a button that opens a color selection dialog and an area that displays the currently selected color.
PContributor | Draws a split list displaying all contributors to a specific tag.
PDroplist | Parameter Setting Droplist. This module draws a droplist with (optional) title and bevel.
PEditField | Parameter Setting Editfield. This module draws an editfield with (optional) title and bevel.
PEditName | An edit field for setting tag names. This module draws an edit field that is to be connected to the name of a tag.
PFileChooser | Parameter setting file selection. Provides an edit box for specifying a file name, along with a label and a browse button.
PHSliderBar | Called graphic module that connects a horizontal slider bar to a given parameter number.
PHueSelect | Called graphic module that connects a hue selection tool to a given parameter number.
PImageSelect | Called graphic module that connects an image selection tool to a given parameter number.
PIPAddressList | Uses an IPAddressList to set a parameter with a semicolon-delimited IP address list.
PIPListenerGroup | Draws a droplist of all available IP Listener Groups.
PMultiCheckBox | Tool used to display the standard set of check boxes.
PPageSelect | Draws a titled, beveled droplist of pages in the system.
PPhraseDroplist | Handles the complexity of parameter expressions by switching between display of a PhraseDroplist and regular Droplist control as is done in PPhraseEdit.
PPhraseEdit | Language-sensitive, parameter-setting editfield. This module draws an editfield with (optional) title and bevel.
PRadioButtons | Parameter Setting Radio Buttons. This module draws a set of labeled radio buttons with optional title and border.
PSecBit | Parameter Setting Security Bit. This module draws a titled, [beveled] droplist of options for setting the security bit.
PSelectObject | Parameter Setting Select Tag Object Tool. This module draws a beveled, titled box showing the currently selected tag, a button to modify the connection in the hierarchy, and a new tag creation button.
PServerListName | Called graphic module that creates an editable droplist of Server List Names, available to the tag.
PSpinbox | Parameter Setting Spinbox. This module draws a spinbox with optional label.
PTimeZone | Tool used to display a list of timezones, as defined by the operating system.
PTypeToggle | Parameter Setting Type Toggled Field. This module draws a beveled, titled box showing the currently selected tag, numeric value or expression and buttons to modify the value as appropriate.
PWidgetSelect |
Closed Printer
DefaultPrinter | Returns the Windows® default printer.
Print | Allows text to be printed.
PrintDialogBox | Displays a threaded system common printer selection dialog box.
PrintLine | Allows text to be printed and is followed by a carriage return-line feed to the printer.
PrtScrn | Prints the image in a window on the default Windows® printer and returns an error code.
Redirect | Redirects a local device to network resource.
Closed Protobuf
ProtobufDecode | Decodes Protobuf serialized data.
ProtobufEncode | Creates a buffer for a given Protobuf file containing VTScada value data.
ProtobufInstantiate | Instantiates a message using default values.
ProtobufParse | Load a Protobuf specification from a file.
Closed Recipe Management
GetCurrentRecipe | Returns the name of the current recipe
GetCurrentVersion | Returns the current version of the current recipe
GetRecipes | Returns the current version of the current recipe
GetVersions | Returns an array of the versions found in the current or specified recipe
SetCurrentRecipe | Sets the current recipe and clears or updates the current version
SetCurrentVersion | Sets the version of the current recipe
Closed Report
GetOutputTypes | Returns a list of available report output type plugins.
GetReportTypes | This subroutine returns a list of available report type plugins.
Closed RPC Manager Functions
BinIP2Text | (RPC Manager Library) Returns a text representation of a specified binary IP in a printable format.
ConnectToMachine | (RPC Manager Library) This subroutine increments the usage count on the specified workstation and forces RPC Manager to attempt to establish a connection with the specified workstation if it is not already connected. Subroutine call only.
DisconnectFromMachine | (RPC Manager Library) This subroutine disconnects from a workstation by decrementing the usage count on the specified workstation and forcing the RPC Manager to attempt to establish a connection with the specified workstation if it is not already connected. Subroutine call only.
ForceServers | (RPC Manager Library) Sets the servership of an application service to a specific state.
GetAllWorkstationNames | (RPC Manager Library) Launched module that creates an alphabetically sorted list of all known workstation names. The list is not service specific.
GetClientDiverts | (RPC Manager Library) Returns a one-dimensional array of flags, indicating the divert status of each client.
GetClientGUIDs | (RPC Manager Library) Returns a one-dimensional array of the application GUIDs of the clients of the specified RPC service instance.
GetClientIPs | (RPC Manager Library) Returns a one-dimensional array of the IPs of the clients of the specified service instance.
GetClientList | (RPC Manager Library) Returns a one-dimensional array of the names of the clients of the specified service instance. Steady state or subroutine call.
GetClientMode | (RPC Manager Library) Returns a one-dimensional array of the modes of the clients of the specified service instance.
GetClientNodes | (RPC Manager Library) Returns a one-dimensional array of the object values of the MachineNodes of the clients of the specified service instance. Steady state or subroutine call.
GetInhibitedServiceList | (RPC Manager Library) Returns a one-dimensional array of the names of all services inhibited from RPCManager servership control.
GetInSyncServers | (RPC Manager Library) Returns a one-dimensional array of the names or IPs of the potential, synchronized servers for the given service.
GetIP | (RPC Manager Library) Returns an IP address for a workstation, given its name.
GetLastUsedSubnet | (RPC Manager Library) Returns the last CIDR representation of the subnet or remote IP used for communication with the specified machine.
GetLocalIP | (RPC Manager Library) Returns an IP address for the local workstation that is known to the specified remote workstation.
GetLocalNumber | (RPC Manager Library) Returns the index of the local workstation down the prioritized server list for the named service. Steady state or subroutine call.
GetMachineNode | (RPC Manager Library) Returns the object value of the MachineNode for the specified name or IP. Steady state or subroutine call.
GetMakeAltPtr | (RPC Manager Library) Returns a pointer to a variable containing the Alternate status for the local service instance in the calling application for the specified service. Steady state or subroutine call.
GetPreferredSubnet | Returns the highest priority CIDR representation of subnet for the given machine name.
GetRemoteVersion | (RPC Manager Library) Returns the version number of VTScada running on a specified workstation. Steady state or subroutine call.
GetServer | (RPC Manager Library) Returns the name of the currently active server for a specified service.
GetServerChanges | (RPC Manager Library) Launched by RPC Manager on a service server to obtain the service's synchronization data (i.e. called by RPC Manager during startup synchronization on a server to get the package of RPCs that create a synchronizable state on the client which is in step with the server).
GetServerMode | (RPC Manager Library) Returns the mode in which the current server for a specified service is running.
GetServerNumber | (RPC Manager Library) Returns the index down the prioritized server list of the current server for the specified service. Steady state or subroutine call.
GetServerSIDPtr | (RPC Manager Library) Returns a pointer to a variable that holds the session ID for the current server for the specified service.
GetServersListed | (RPC Manager Library) This subroutine returns a one-dimensional array of the names or IPs of the servers that has been derived from the "-Servers" section of the service configuration file.
GetServiceScope | (RPC Manager Library) Returns the service instance for a service.
GetSessionID | (RPC Manager Library) Returns the current session ID for a specified application on a workstation.
GetSocketStatus | (RPC Manager Library) Returns the connection status of either: 1) The machine node if the subnet is not valid, or 2) The socket that is on the specified subnet.
GetStatus | (RPC Manager Library) Returns a variable that holds the current service instance status for the specified service.
GetSubnetPriority | (RPC Manager Library) This module returns a full set of network priority values configured
IsClient | (RPC Manager Library) Is Client of a Service. This subroutine returns an indication of whether a particular workstation is a client connected to a service. Returns 1 for the specified service if the specified machine is currently a client to the machine on which the IsClient() call is made.
IsMatch | (RPC Manager Library) Determines whether two names or IPs indicate the same workstation. This subroutine returns a 1 if the two names or IPs (any combination) refer to the same workstation.
IsPotentialServer | (RPC Manager Library) Is Potential Server for a Service. This subroutine returns an indication of whether the local workstation is a potential server for a service. Returns 1 if the local workstation can be a server for the specified service. IsPotentialServer should not be called in steady state.
IsPrimaryServer | (RPC Manager Library) Returns 1 if the local machine is connected to the primary server for the specified service.
IsServiceReady | (RPC Manager Library) Is Primary Server Active for a Service. Only available in VTS 6. This module returns an indication of whether the specified server is in synchronization with the server instance. Returns 1 if the local instance is in synchronization with the server instance.
PackParms | (RPC Manager Library) This method packs supplied parameters into a stream. Subroutine call only.
PackRPC | (RPC Manager Library) Packs an RPC call and a set of parameters into a stream. Subroutine call only.
ReadLock | (RPC Manager Library) Attempts to acquire a Read lock for the specified service. Subroutine call only.
RecommendAlternate | (RPC Manager Library) Instructs RPC Manager that the local service instance does not consider itself a good server candidate.
RecommendPrimary | (RPC Manager Library) Instructs RPC Manager that the local service instance considers itself a good server candidate.
Register (RPC Manager) | Registers a service for RPC and returns a pointer to the variable containing the current RPC status of the service.
RunPack | (RPC Manager Library) Is unpacks and executes a set of RPCs from a stream constructed with PackRPC.
Send | (RPC Manager Library) This subroutine sends a message by invoking a remote procedure call.
SetDivert | (RPC Manager Library) Informs RPC Manager that the synchronization state of a service has been sampled during synchronization, and service RPCs for the specified client should be buffered until synchronization completes. Subroutine call only.
SetRemoteValue | (RPC Manager Library) This subroutine sets the specified variable within an application instance on a workstation to the specified value. Subroutine call only.
SetSubnetPriority | (RPC Manager Library) This module enables setting the network priority configuration during runtime.
SetSyncComplete | (RPC Manager Library) Informs RPC Manager that service synchronization is complete as far as the local service instance is concerned. Subroutine call only.
TextIP2Bin | (RPC Manager Library) Returns the Binary representation of the specified IP.
UnpackData | (RPC Manager Library) This method unpacks a stream into an array or set of module instance parameters. Subroutine call only.
UnpackParms | (RPC Manager Library) This method unpacks a stream into the supplied parameters. Subroutine call only.
WriteLock | (RPC Manager Library) This subroutine attempts to require a Write lock for the specified service. Subroutine call only.
Closed Security

Account Manipulation Methods

AddAccount | Creates a new account.
ModifyAccount | Modifies an existing account.
DeleteAccount | Removes an account.

Query Module

SecurityCheck | Examines the rules that apply to the current user or the named user to determine if the specified privilege has been granted.
BuildFullName | If a namespace and namespace delimiter are being used, returns the full, namespace-qualified name of the specified account.
GetFullName | Returns the full, namespace-qualified name of the caller's account.
GetGroupName | Returns the namespace of the caller's account.
GetUserName | Returns the user name of the caller's account.
GetAccountID | Returns the account ID of the named account.
GetAccountInfo | Returns one or more AccountData structures.
IsLoggedOn | Returns TRUE if the calling user is signed in, else FALSE.
IsSecured | Returns TRUE if the application has any user accounts defined, else FALSE.
IsSuspended | Returns TRUE if the user's account is suspended, else FALSE.
UIErrorToText | Returns a text string corresponding to the error code provided.

VTScada Authentication Module

AlternateLogon | Either creates, or attempts to sign in using an alternate ID value.
AlternateLogoff | Synonym for LogOff().
Authenticate | Authenticates the NameSpace, UserName and Password.
QuietLogon | Authenticates the authorization token (AuthToken) and, if successful logs the calling user session on as the user specified in the AuthToken.
LogOff | Logs the calling user session off.
UserCredChange | The return value will increment each time there is a change in the user session's logged-in user or their password.

Windows Authentication Module

AcceptSecurityContext | Accepts a Kerberos security context from a client and returns the user principal name (UPN) from the context, along with any output to be returned to the client for mutual authentication.
DefaultNamingContext | Returns the string value of the LDAP default naming context for the host machine domain.
GetLogonCredentialsFromSmartcard | Monitors the card reader for a smartcard and reads the certificate information from it
WindowsLogon | Authentication request to Windows Authentication services.

User Interface Module

UserLogonDialog Launches the Logon dialog.

Other

OkToWrite | Returns true if a user is permitted to control a particular tag on a particular workstation.
VICSmartcardMonitor | Enables and disables Smartcard monitoring on a VIC and outputs authentication information received from the VIC when a Smartcard is used.
VICSmartcardResponse | Returns the result of the Kerberos Security negotiation after processing a sign in attempt on the VIC.
Closed Serial Port
COMPort | Opens a serial port and handles all interrupts and asynchronous events for that serial port, including transmission, reception, and control. It returns its own error code. Please note that the SerialStream function is generally preferred in many situations, however, ComPort continues to be supported.
PPPDial | Creates a PPP connection to a remote peer. The connection can be via a dial-up or direct device connection.
SerBreak | Sends a break character to a serial port.
SerCheck | Check Serial Port. This function returns the immediate or cumulative serial port status.
SerialStream | Returns a serial stream that can be used in any of the serial port functions or with any of the stream functions. Please note that the ComPort function (which functions somewhat differently than the SerialPort function) may also be utilized.
SerIn | Get Serial Port Byte. This function returns the next byte in the receive buffer.
SerLen | Serial Port Buffer Length. This function returns the number of bytes currently in the receive or transmit buffers.
SerOut | Send Serial Port Byte. This statement sends a byte to the transmit buffer.
SerRcv | Serial Port Receive. This function returns a buffer containing a string read from the receive buffer.
SerRTS | Sets or clears the RTS line on a serial communication port.
SerSend | Serial Port Send. This function writes a string to the transmit buffer and returns the number of bytes written.
SerStrEsc | Serial Port Receive With Escape. This function reads the receive buffer until an escape code is encountered and returns the final offset in the buffer.
SerString | Serial Port String Receive. This function reads the receive buffer until a string is encountered and returns the final offset in the buffer.
Closed Software And Hardware
CommandLine | Returns any command line arguments as a text string.
DriveInfo | Returns information about a disk drive.
GetConfiguration | Returns the configuration parameters from the license key for this copy of VTScada.
IsRunning | Check if a Program is running. This function returns an indication of whether a certain program is currently running on the same computer.
LoadDLL | Loads a Microsoft Windows™ dynamic link library.
LoadMIB | Loads a specified MIB or set of MIBs and returns a dictionary describing the hierarchy of the MIBs.
MACID | Enumerates and returns the MAC IDs registered on a particular machine.
Platform | Returns a twelve element structure that indicates the platform under which VTScada is currently running.
ProcInfo | Returns basic information about the VTScada process.
Redirect | Redirects a local device to network resource.
SerialNum | Returns the serial number of the copy of VTScada running.
Spawn | Runs another Windows™ program.
Stop | Causes the immediate termination of VTScada, closing all windows.
ThreadList | Returns a two dimensional array containing the name and statement last executed by each VTScada thread.
ThreadName | Returns the name of a thread.
Version | Returns the version number of the copy of VTScada currently running.
VersionRequired | Returns the version number of VTScada that is required to execute any .RUN files loaded since the last execution of this statement.
VStatus | Returns the video board and screen characteristics for VTScada.
WKSPath | Given set of path components, generates a query path for use in the WKSStatus command.
WKSStatus | Sends a query to the Windows™ Performance Monitor interface (see image in WKSPath) and returns the result as a query handle.
WKStaInfo | Returns the characteristic information about this workstation.
Closed Speech And Sound
AudioFileLength | (System Library) Returns the length of a RIFF format Wave file in seconds.
Beep | Causes a tone to sound on the computer's internal speaker.
Configure | Is used to define how a speech stream will sound and where it will be heard.
GetDevices | Runs in the VoiceTalk thread and returns a list of devices available on a SAPI text-to-speech stream.
GetVoices | Runs in the VoiceTalk thread and returns a list of voices available on a SAPI text-to-speech stream.
MuteSound | (Alarm Manager module) This subroutine is used to turn off alarms sounds for all alarms, both current and future.
Play | Plays a multimedia sound file as installed in the operating system. It differs from Sound in that it is a steady-state statement and is supported by the VTScada Internet Client (VIC).
Reset | Immediately stops a speech stream and cancels any buffered speech.
ShowLexicon | Displays a SAPI text-to-speech engine lexicon dialog to permit modification of pronunciation. This function will return immediately, and the lexicon window will be managed in its own thread, preventing the calling thread from being blocked.
Sound | Plays a multimedia sound file as installed in the operating system.
Speak | Executes on the speech thread to speak the supplied text through a specified SAPI text-to-speech stream.
SpeakToFile | Executes on the speech thread to speak the supplied text to a .wav format audio file.
VoiceTalk | Opens and returns a handle to a SAPI text-to-speech stream.
Closed State
ActiveState | ActiveState returns the code value of the currently active state in the given module instance.
AddOptional | Adds a new statement to an action script and returns its own error code.
AddPageToApp (Obsolete) | Creates a new application page.
AddState | Adds a new state to an existing module and returns its state value.
AddStatement | Adds a new statement to an existing state and returns its own error code.
ClearState | Deletes all of the statements in a state.
DeleteOptional | Deletes a statement from an action script.
DeleteState | Deletes a state from a module.
DeleteStatement | Deletes a statement from a state.
FindAction | Returns an action from the list of actions in a state.
FirstState | Sets the first state in a module.
ForceState | Sets the next state to start when the action script completes.
GetState | Returns the code value for the specified state.
GetStatement | Returns the code value for the specified statement.
GetStatementNum | Returns the statement number for the specified statement.
GetStateText | Returns the text for the specified state.
ReplaceStatement | Replaces a statement with another statement.
SetStateText | Sets the information about the text of a state in a .SRC file.
SetTransfer | Sets the destination for an action.
StateList | Returns a list of states for a module.
StatementInstance | Takes a given code value and object and returns a code pointer value for that instance.
StateName | Returns the text name of the given state.
SubStatementIndex | Returns the index of a function within the statement where it is called.
Closed Stream And Socket
BlockWrite | Writes a block of data to a stream.
BuffStream | Returns an in-memory read/write (expanding) buffer stream.
ClientSocket | Opens a client WinSock-compliant socket stream and returns a stream value, or a numeric error code.
CloseStream | Closes and flushes any type of open stream and returns its own error code.
CommaFormat | Returns the text version of a number, formatted to use embedded commas.
DBGetStream | Executes in its own thread to convert a database to a stream, and returns an indication of parameter errors.
FileStream | Returns a stream attached to a disk file or printer, and is suitable for use in SWrite.
Flush | Pushes the data in all software caches associated with a FileStream directly to the physical media.
GetStreamLength | Returns the present length of a stream in bytes.
GetStreamType | Returns a type indication for a stream.
GetToken | Reads the next token from a stream and returns the token type.
HTTPSend | Sends HTTP requests to an HTTP server
In | Read I/O Byte. This function returns the byte read from an I/O port.
LargeSocketWrite | Paces the write speed to prevent exceeding the socket output buffer limit.
ListCertificates | Enumerates X.509 certificates in a certificate store resident on the local computer.
Pack | Packs a set of module parameters or an array of values into a stream, and returns the number of items that were not packed.
PackParms | (RPC Manager Library) This method packs supplied parameters into a stream. Subroutine call only.
PackRPC | (RPC Manager Library) Packs an RPC call and a set of parameters into a stream. Subroutine call only.
PeekStream | Returns a string of bytes from a stream without removing them from the stream.
PipeStream | Returns a stream based on an operating system named pipe.
Read | (VTSDriver Library) Used to create a request for a single read of a given driver address. (This is in contrast to the polled read request of the AddRead function).
ReadBlock | (VTSDriver Library) Is launched to read a block of data from the PLC. It maintains a linked list of pointers to tag values with their absolute offset into the PLC file being read by this instance.
RunPack | (RPC Manager Library) Is unpacks and executes a set of RPCs from a stream constructed with PackRPC.
Seek | Changes and returns the current position within a stream. The return value is the current stream position after the seek is done.
SerialStream | Returns a serial stream that can be used in any of the serial port functions or with any of the stream functions. Please note that the ComPort function (which functions somewhat differently than the SerialPort function) may also be utilized.
ServerSocket | Returns a server WinSock socket stream given a handle returned by a SocketServerStart function or an integer error code.
ShiftStream | Inserts or deletes characters from a stream and returns its own error code.
SocketAttribs | Returns information about a TCP/IP socket's attributes.
SocketPingSetup | Starts the transmission of automatic keep-alive "ping" messages through a socket stream.
SocketServerEnd | Ends a TCP/IP socket server.
SocketServerStart | Starts a TCP/IP or UDP socket server and returns a handle to it.
SocketServerManager\Register | Register a station with a group
SocketServerManager\UnRegister | Unregister a station from a group. The station must be unregistered whenever GroupName, or StationKey changes.
SocketWait | Wait for Socket Connect. This function returns true when a client connects to a socket offered by a socket server.
SRead | Reads values from a formatted stream and returns the number of values not read.
StreamEnd | Returns whether a stream is at the end.
SWrite | Performs a formatted write of ASCII or binary data to a pre-existing stream and returns the number of data items not written.
TempFileStream | Uses the OS tmpfile() function to create a temporary file on disk and to connect a stream to the temporary file. The temporary file is removed when the stream is closed or no longer referenced or if the VTScada process is terminated.
Unpack | Unpacks a set of values from a stream into a single dimensional array or a set of variables referenced by object parameters, and returns the number of items unpacked.
UnpackData | (RPC Manager Library) This method unpacks a stream into an array or set of module instance parameters. Subroutine call only.
UnpackParms | (RPC Manager Library) This method unpacks a stream into the supplied parameters. Subroutine call only.
Write | (VTSDriver Library) Used by a tag to create a write request to a driver address.
Zip | Generates a zip archive of a file stream.
Closed String And Buffer
ArrayToBuff | Returns a buffer containing the numeric data from an array.
BinaryToIP | Converts an IP address from binary notation to decimal.
BinIP2Text | (RPC Manager Library) Returns a text representation of a specified binary IP in a printable format.
BuffOrder | Reverses the order of groups of bytes in a buffer, and returns a new (rearranged) buffer.
BuffRead | Reads values from a formatted buffer and returns its own error code.
BuffStream | Returns an in-memory read/write (expanding) buffer stream.
BuffToArray | Reads an array from a formatted buffer containing numerical data and returns the number of elements read.
BuffToHex | Convert a buffer of numeric data to a hexadecimal value.
BuffToParm | Convert buffer of numeric data to parameters. This function reads module parameters from a formatted buffer containing numerical data and returns the number of data items read.
BuffToPointer | Converts a buffer of numeric data to array of pointers. This function reads from a formatted buffer containing numeric data, writes to locations specified by an array of pointers, and returns the number of elements read.
BuffWrite | Writes formatted values to a buffer and returns the number of values not written.
CharCount | Returns the number of bytes in a section of a buffer that matches a search character.
ClipboardGet | Returns the current contents of the system clipboard as a string. This function enables an application to perform text "paste" operations.
ClipboardPut | Set the current contents of the system clipboard to a string. This function enables an application to perform text "copy" or "cut" operations.
Concat | Returns the text value that is the concatenation of all the text parameters.
CRC | Returns the cyclic redundancy check (CRC) value for a buffer.
CRCTable | Returns a buffer containing a CRC table.
Deflate | Compresses/decompresses a buffer of data using the DEFLATE algorithm, and returns the compressed/decompressed data.
Diff | Compares two buffers and generates a third buffer containing formatted instructions describing how the first buffer can be modified so that it will match the second. This will perform a delimited difference unless the ChunkSize parameter is set to 1 or greater.
EncodeURIComponent | Encodes a string so that it can be embedded as part of a Uniform Resource Indicator.
Escape | Wrapper for EncodeURIComponent.
FileChooser | Provides an edit box for specifying a file name, along with a label and a browse button.
Format | Returns a text string corresponding to numbers in a specified format.
FormatInteger | Returns a text string which is a decimal value converted to one of binary, octal or hexadecimal formats.
FRead | Reads values from a formatted file and returns the number not read.
FWrite | Writes ASCII or binary data to a file and may also be used to create or delete a file. It returns the number of data items not written.
GetByte | Returns a single byte from a buffer.
GetDatePhrase | Returns a formatted date for the current user's locale
GetTimePhrase | Returns a formatted time for the current user's locale
GetParmPhrase | Returns parameterized text in the currently selected language for a given phrase identifier key.
GetParmPhraseForLang | Returns parameterized text in the specified language for a given phrase identifier key
GetPhrase | Returns text in the currently selected language for a given phrase identifier key
GetPhraseForLang | Returns text in the specified language for a given phrase identifier key
GetPhraseID | Returns the key matching a given phrase.
GetRawPhrase | Returns a phrase in the provided language, if it exists.
HexToBuff | Converts a hex string to a binary buffer.
IPAddressList | Displays a list of IP address which can be added to or removed from.
JoinStrings | Joins an array of string elements together into one string, with a given separator added between each element from the array.
JSON_Encode | Deprecated. Use JSONEncode instead.
JSONEncode | Converts any given VTScada value into a JSON string using UTF-8 encoding.
JSONParse | Parse JSON text, converting it to VTScada arrays, objects/structures, strings or other data types as appropriate.
KeyFake | Places a string of characters in a window's keyboard buffer.
Keys | Returns the most recently pressed keys from either the edited or non-edited keystrokes.
Locate | Locates a text string, returning the offset of the first matching string in a buffer.
MakeBuff | Creates a buffer and returns its address.
MakeValidFName | Create a file name that is guaranteed to contain only legal characters.
ParmToBuff | Returns a buffer of formatted numeric parameter values.
PatternMatch | Compares a string against a reference pattern and returns true if the string matches the pattern. Along with literal characters, PatternMatch currently supports the * and ? wildcard characters within the reference pattern.
PlotBuff | Displays a plot of a subsection of a buffer in a particular area of the window after converting the buffer to element values.
PointerToBuff | Returns a buffer containing the numeric data from the variables pointed at by each element of the array.
PrepStringForTemplate | Prepares text for use in an alarm template by escaping % symbols.
Replace | Performs a search and replace operation on a buffer and returns the resulting buffer.
Reverse | Returns its parameter with the byte order reversed.
SerLen | Serial Port Buffer Length. This function returns the number of bytes currently in the receive or transmit buffers.
SerOut | Send Serial Port Byte. This statement sends a byte to the transmit buffer.
SerString | Serial Port String Receive. This function reads the receive buffer until a string is encountered and returns the final offset in the buffer.
SetByte | Writes a single byte to a buffer.
SetUserLanguage | Changes the display to any of the languages currently enabled in the application.
SplitString | Splits a string into separate array elements using a given delimiter to mark the breaks between elements in the string.
StrCmp | Performs a case sensitive comparison of two text expressions and returns an indication of whether the first string is greater than, less than or equal to the second.
StrICmp | Case Insensitive Text Comparison
StrJustify | Reformats a string to have maximum line length.
StrLen | Returns the length of a text string.
SubStr | Returns a string that is a portion of another string.
SumBuff | Returns the summation of bytes in a buffer.
TextEncode | Takes text in the local code page and converts it into UTF-8 encoded text where a suitable conversion exists.
TextIP2Bin | (RPC Manager Library) Returns the Binary representation of the specified IP.
TextSearch | Returns the array index of the first occurrence of the given text key in an alphabetically ordered array.
TextSize | Returns the size in characters of the definition text of a desired item.
TrimSpaces | Returns text with leading and trailing spaces removed.
ToLower | Returns a text string with all the characters converted to lower case.
ToUpper | Returns a text string with all the characters converted to upper case..
UnEscape | Decodes a string that was URL-encoded by EncodeURIComponent.
WrapText | Breaks a text string based on given font and width and returns the text segments in an array.
Write | (VTSDriver Library) Used by a tag to create a write request to a driver address.
Closed Time And Date
AbsTime | Absolute time. This function returns true when a fixed time has been reached.
ConvertTimeStamp | Converts a timestamp from one time zone to another.
CurrentTime | Returns the number of seconds, in local or UTC time, since midnight of January 1, 1970 (where "midnight" is 00:00).
Date | Returns a text string giving the date that corresponds to the number of days since January 1, 1970.
DateNum | Returns the number of days since January 1, 1970 for a given date.
DateSelector | Displays a calendar, from which operators can select a date.
Day | Returns the day of the month for a given date number.
GetDatePhrase | Returns a formatted date for the current user's locale
GetISOTSfromTS | Convert ISO 8601 date & time format to a VTScada timestamp.
GetTimePhrase | Returns a formatted time for the current user's locale
GetTSfromISOTS | Convert a VTScada timestamp to ISO 8601 date & time format.
HoursEntry | Displays a time editing field.
Month | Returns the month for a given date number.
Now | Returns the current time in seconds since midnight.
RTimeOut | Cumulative Timer. This function returns true when the total time that an expression is true reaches the specified value.
Seconds | Returns the number of seconds since midnight of the current day.
SetClock | Sets the VTScada system clock and calendar.
Time | Returns a formatted string for a time of day.
TimeArrived | Indicates whether a given time has occurred.
TimeOut | Returns true when the uninterrupted time that an expression is true reaches the specified value.
TimeUtils | Library that exposes a dictionary of time periods and subroutine to calculate relative time periods.
TimeZone | Returns information on the current time zone setting of the machine.
TimeZoneList | Returns an array of names of time zones that are available on the system.
Today | Returns the current number of days since January 1, 1970.
UnEscape | Decodes a string that was URL-encoded by EncodeURIComponent.
Year | Returns the year for a given date number.
Closed Variable
Accumulate | Adds a tag and a value to be counted for that tag, to a named accumulator.
AddVariable | Adds a new variable to an existing module and returns its variable value.
Cast | Takes a value and returns a different type of value, if possible.
Change | Returns a true when the value of the first parameter changes by at least the value of the second parameter.
 | Changes the space allocated in the persistent value (.VAL) file for a variable.
CheckTagGroup | Returns TRUE or FALSE according to whether a tag is in the specified group.
DeleteVariable | Deletes a variable from a module.
Dictionary | Creates a database-like storage structure that provides efficient addition, retrieval and removal of information linked to key values.
DictionaryCopy | Create a new dictionary with contents identical to an existing dictionary. It is expected that this function will be used rarely, since in most cases it will be more efficient to hand off a reference to a dictionary rather than build a duplicate of it.
Edge | Performs a test for a rising or falling edge.
FindVariable | Searches for a variable by text name and returns a variable value.
GetDefaultValue | Returns a variable's default value.
GetReferencedValues | Collect all dynamically referenced values in the call tree rooted at the parameter and return them in an array.
GetSessionContainers | Returns an array of the names of tags that are "container" tags that exist at any level under the given context (parent) tag
GetSessionContainerTags | Returns a dictionary of tag items below a given context (parent) tag
GetStructInfo | Returns names and counts of all instantiated structures.
GetModuleContext | Returns the context of a given module-in-context.
GetRetainedValue | Given the name of a variable whose value was retained, this function will load the retained value from storage. The function also provides the option of deleting the files holding that value.
GetTagMode | Returns text or a structure to identify what kind of tag a given instance is.
GetValue | Returns the current count of the values within an accumulator dictionary.
GetVariableText | Returns information about the documentation of a variable.
GetVariableType | Returns the type, BASEVALUE, stored within a variable.
GetVarMetadata | Every variable object contains an embedded value. This function is used to retrieve those values.
HasMetaData | Tests whether a given variable is a dictionary. Because the default behavior of most operands and functions on dictionaries is to return just the value of the dictionary’s root, this function provides the only means to determine whether a variable contains a dictionary.
Invalid | Return Invalid Value. This function always returns an invalid value.
IsEqual | Will return TRUE if the parameter values are equivalent, or if both are invalid.
IsDictionary | A synonym for HasMetadata. Tests whether the parameter is a dictionary.
IsTagOperable | Returns TRUE if the user is able to operate the selected tag from the Tag Browser using the right-click menu.
Latch | Latch On or Off. This function allows a transient change of a variable to be captured. Its return value is determined by the rules listed in the comments section.
ListKeys | Returns an array of all keys used within a dictionary. It is expected that this function will be used primarily in the context of metadata (extended information attached to a variable). ListKeys also enables you to discover what is in a dictionary.
ListVars | Returns a list of variables.
LValue | Left-hand Side Value. This function returns an indication of whether its argument can be used on the left-hand side of an assignment.
MakeNonPersistent | Takes a variable and makes it not persistent.
MakeNonShared | Takes a shared variable and makes it not shared.
MakePersistent | Takes a variable and makes it persistent (static).
MakeShared | Takes a variable and makes it shared.
MetaData | If used with a variable which is not currently a dictionary, this command attached meta data to that variable, thereby creating a dictionary object. The primary purpose in this case is to provide a means of associating extended data with a variable.
NumSets | Returns the number of statements that are currently active in setting a particular variable.
NumVariables | Returns the number of variables in a module.
Parameter | Returns the value of (or may assign a value to) a parameter of a module, specified by the index.
ParameterEdit | Draws an interface to allow the user to choose how to edit a parameter. Used in tag widgets.
ColorParameterEdit | ParameterEdit Wrapper - allow user to modify a color
DurationParameterEdit | ParameterEdit Wrapper - allow user to set a time duration
MultiCheckboxParameterEdit | Use this function to make any number of check boxes in a group.
NumericParameterEdit | ParameterEdit Wrapper - allow user to modify a numeric value
TagParameterEdit | ParameterEdit Wrapper - allow user to choose a tag
TextParameterEdit | ParameterEdit Wrapper - allow user to enter a text value
TimestampParameterEdit | ParameterEdit Wrapper - allow user to set a timestamp
UnTypedParameterEdit | ParameterEdit Wrapper. Add control to a panel without defining the type.
PersistentSize | Returns the size in bytes of a variable's persistent value size in the persistent value (.VAL) file.
PID | Perform PID Controller Function. This function returns a control value to maintain a parameter at a given setpoint.
PType | Returns the actual type of parameter at an index.
PTypeToggle | (VTS Library) Parameter Setting Type Toggled Field. This module draws a beveled droplist or editfield with title that sets a tag or numeric value.
RootValue | Retrieves the root value from a dictionary. This function will always attempt to return a value that is not itself a dictionary. If the value stored as the root of the given dictionary is also a dictionary, this function will return the root value from that second dictionary. Should all root values be other dictionaries (which would imply that the dictionary at the end of the chain must actually be an earlier dictionary) then RootValue will traverse the chain until it finds a root value which is an earlier dictionary (i.e. the end of the chain before it loops back) and will return that root value. This is the only situation where the command will return a dictionary as the result.
SetDefault | Sets the default value for a variable.
SetVariableClass | Sets the class number of a variable and returns its previous class number.
SetVariableText | Sets the information about the documentation of a variable in the .SRC file.
SetVariableType | Sets the data type for the variable, so that only values of that data type can be stored in the variable.
StaticSize | Returns the size of a given variable, provided that the variable is static.
StrictlyEqual | Will return TRUE if the parameter values are of the same type and also are equivalent, or if both are invalid.
StrictlyNotEqual | Complement to StrictlyEqual.
Struct | Returns a dictionary, using the provided parameters as keys.
Tag | Returns a Tag value, which works like (and in place of) a Normalize value.
Toggle | Returns its previous status value except when its parameter changes from a false to a true, in which case it changes its value.
ToggleVal | Toggles between TRUE (1) and FALSE (0), once each given period.
TriggerCounter | Returns a count of zero-to-non zero transitions during the current session.
Valid | Returns true if the parameter is valid.
ValueType | Returns the type of value passed to it.
Variable | Accesses a variable by its text name. The return value is optional.
VariableClass | Returns the class of a variable.
Watch | Watches its parameters and returns true when any of their types or values change.
WatchArray | Watches an array and returns true if any of its elements' types or values change.
WatchForTagChanges | Watches for tag changes, either external or local. (Deprecated)
WatchTags | Watches for tag changes, either external or local. (Use instead of WatchForTagChanges)
WCSubscribe | Working Copy Subscribe. After this function has been called, any configuration change will result in the specified callback subroutine being called.
Closed VTScada Internet Client
IsVICSession | Returns TRUE to indicate that a call is being made from a VTScada Internet Client session.
NotifyVIC | Sends a message to the VTScada Internet Client (VIC). The message sent depends on the parameter given to the function.
SetVicParms | Sets parameters for the VTScada Internet Client.
VICInfo | Provides information about the currently connected VTScada Internet Clients.
VICMessage | Transmits a message to one or all currently connected VTScada Internet Client sessions. The message is displayed in a dialog box on the VIC computer.
Closed Window
ActiveWindow | ActiveWindow returns the object value of the root module instance in the current active window.
Click | Returns an indication of whether the mouse pointer is within a specified screen area and a particular button combination is being pressed.
Cls | Clears the screen and sets its background color.
Coordinates | Sets the VTScada screen coordinate limits (also called "world coordinates") used by the graphics functions.
CoordToPixel | Takes a specified coordinate pair within a given window and returns the overall, onscreen pixel location.
Crop | Modifies an existing image, producing a new one that displays a sub-section of the original.
CurrentWindow | Returns the application window over which the mouse cursor currently rests.
DelPageFromApp | Deletes a system page from an application.
FocusID | Returns the focus ID of the object in a window that currently has the input focus.
GetXformRefBox | Get Transform Reference Box. This function returns the reference box for any transform of a module.
LocCapture | Capture Locator Input. This statement captures all subsequent input from the locator device and routes it to a specific window.
MoveWindow | Will move a window to the specified coordinates.
ParentWindow | Returns the object value of the nearest non-child window.
RootWindow | Returns the object value of the root (original) module displayed in the same window.
SetCursor | Sets the mouse cursor type for the window.
SetEditMode | Sets the graphics edit mode for a window.
SizeWindow | Changes the visible size of a window on the screen.
UnselectGraphics | Will deselect all of the graphics in the specified window.
VStatus | Returns the video board and screen characteristics for VTScada.
WinButton | Windows native button.
WinComboCtrl | Windows native "combo" control. A "combo" control is an enhanced form of drop list. Displays a child window containing a Windows combo control.
Window | Opens a new window, starts a module inside, and eventually returns the module's value.
WindowClose | Returns true if an attempt to close the window is made.
WindowOptions | Alters the options on a window after it has been opened.
WindowSnapshot | Creates an image file containing a screen capture of the specified window.
WinLocSwitch | Returns the current status of the locator (mouse) buttons in a certain window and its ancestors.
WinLocWheel | Returns TRUE when the mouse wheel is rolled while the mouse is over the specified window with the specified modifier key held down.
WinYLoc | Returns the Y coordinate of the locator (mouse) in a window.
XLoc | Returns the X window coordinate of the locator (mouse).
YLoc | Returns the Y window coordinate of the locator (mouse).
Closed XML
GetXMLNodeArray | Searches the result returned from XMLParse and returns an array of XMLNode values of a given type.
RemWSDL | Disconnects a Realm from a WSDL file and the associated set of VTScada modules, cleaning up any resourced used by that web service.
SetWSDL | Connects a Realm with a WSDL file and a set of VTScada modules to enable a web service interface.
XMLAddSchema | Adds a schema to an XML Processor.
XMLCloneNode | Clones an existing XMLNode, optionally adding additional members.
XMLCreateNode | Creates a new XMLNode.
XMLDeleteMember | Deletes a member from an XMLNode in-place.
XMLGetNode | Returns an XMLNode from a tree.
XMLParse | Parses the supplied XML using the specified XML Processor.
XMLProcessor | Creates a new XML Processor.
XMLWrite | Converts the instance of a type, as specified by XMLNodeTreeIn, into XML.


Obsolete Functions

Functions that are obsolete in VTScada version 12.2 are listed here. In most cases, code containing these functions will continue to compile, but the function call will do nothing.

If your legacy application uses any of the these functions, please refer to the documentation matching your software for details. Otherwise, they should be removed from all code intended for the current release.

ActiveMonitor (Alarm Manager)

AddPageToApp

Alarm

AlarmCat

AlarmInst

AlarmSoundCheck

AlmAck

AlmAckID

AlmArray

AlmCatName

AlmColor

AlmEnable

AlmList

AlmTone

AnimateState

ChangePersistentSize

CollapseTree

CopyObjects

Cut

DeleteListItem

DoAcknowledge (Alarm Manager)

DragState

Freeze

GetClientsListed

GetLogHeader

GetSubGraphic

HighlightState

HighlightTree

InsertListItem

LastSelectedModule

LastSelectedState

Load

MakeFixedBuff

MakeTypeInstance

ModuleCollapsed

ModuleTree

ModuleTreeSize

MoveSelState

MoveState

NewPage

NumAlarm

OperationalChange

PackData

Palette

PickModule

PickState

Priority

PriorityWeight

ReadNum

ReadText

SelectStates

SetLogHeader

SetStateColor

ShadowTree

ShelvedEvent

SpeechEnum

SpeechLexiconDlg

SpeechReset

SpeechSelect

SpeechSpeak

SpeechStream

StartSound (Alarm Manager)

StateDiagram

StateHighlighted

Table

TCPIPReset

ValidateHistory

VarAttributes


4BtnDialog

(System Library)

Description: | Draws a message dialog with up to 4 buttons and 3 lines of text and returns the number of the button that was pressed.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Window
Format: | System.4BtnDialog(Icon, Btn1Label [, Btn2Label, Btn3Label, Btn4Label, Text1, Text2, Text3, Open, Modal, BoldFirst, Title, XPosPtr, YPosPtr, CloseButton, DefFocus, HelpFileName, HelpContextID])
Parameters: |
Icon
Optional. Any image value for the (41 x 41) icon to display in the dialog. Set to "Invalid" to display only text with no icon. predefined icons include: \System\Question_icon, \System\Error_icon, and \System\Warning_icon.
Btn1Label
Required. Any text expression for the label on the first button.
Btn2Label
An optional parameter giving any text expression for the label on the second button. If invalid, the button will be omitted.
Btn3Label
An optional parameter giving any text expression for the label on the third button. If invalid, the button will be omitted.
Btn4Label
An optional parameter giving any text expression for the label on the fourth button. If invalid, the button will be omitted.
Text1
An optional parameter giving any text expression for the first line of text to display.
Text2
An optional parameter giving any text expression for the second line of text to display.
Text3
A parameter giving any text expression for the third line of text to display. Must be given as Invalid if there is to be no third line.
Open
An optional parameter that is any logical expression. If TRUE (non-0) the dialog will be open. If FALSE (0), it will be closed. The default is TRUE.
Open will be set to FALSE after the dialog has been acknowledged.
Modal
An optional parameter that is any logical expression. If true (non-0), the dialog is modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window., if false (0) it is non-modal.
This parameter will override the System NoModal flag. If it is omitted, the NoModal flag will prevail. If the NoModal flag is also omitted, the dialog will default to being modal.
BoldFirst
An optional parameter that is any logical expression. If true (non-0) the first line of text in the dialog will appear in boldface type. If false (0), it will not be bolded. The default is false.
Title
An optional parameter that is any text expression that gives the title to appear in the window's title bar.
XPosPtr
Optional pointer to a variable that stores the x-coordinate of the upper left of the dialog, relative to the current monitor. This parameter affects the position when the dialog opens, after which it is used only to return the current position of the dialog as placed by the user.
YPosPtr
Optional pointer to a variable that stores the y-coordinate of the upper left of the dialog, relative to the current monitor. This parameter affects the position when the dialog opens, after which it is used only to return the current position of the dialog as placed by the user.
CloseButton
An optional parameter that is the index of the button to which the title bar close button should be mapped (from 1 to 4).
If CloseBtn is invalid, then the title bar close button is mapped to the first button with the same text as the CancelLabel or CloseLabel application properties.
If no buttons match these labels, then "0" is returned when the dialog is closed using the title bar close button.
DefFocus
An optional parameter that is the index of the button that should have the focus when the dialog opens (from 1 to 4). If DefFocus is invalid, the first button has the focus when the dialog opens.
HelpFileName
An optional parameter that is the name of the help file containing the help topic for this dialog (as identified in the HelpContextID parameter). If HelpFileName or HelpContextID are invalid, then the default is as per the Window function.
HelpContextID
An optional parameter that is the numeric context ID identifying the help topic for this dialog (within the help file identified in the HelpFileName parameter).
If HelpFileName or HelpContextID are invalid, then the default is as per the Window function.
Comments

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The return value for this module is in the range of 1 to 4 and identifies which button has been pressed. If one of the buttons is labeled "Cancel", pressing <ESC> will cause the number of the "Cancel" button to be returned.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Example:

  If Valid(FileName) && ! Valid(OK);
  [
    Size = FileFind(FileName, 8, 4);
    IfElse(Size[0], Execute(
      OpenErrDlg = 1,
      OK = 0
    ),
    { else }
      OK = 1
    );
  ]

  System.4BtnDialog(\System\Warning_Icon { Icon to use },
                     \GetPhrase("OKLabel"), \GetPhrase("CancelLabel"), Invalid, Invalid { 2 buttons },
                     "File exists !" {1st line of text},
                     "Replace it ?"  {2nd line of text},
                     Invalid         {3rd line of text},
                     OpenErrDlg { Opening trigger});

This example shows English text as the dialog message for the sake of clarity. In practice, phrases should be created and \GetPhrase used instead.

This code waits until a file name has been set, presumably from an edit field or some other method not shown here, and then checks to see if it already exists in the current directory. If it does exist, the variable OpenErrDlg is set TRUE and an error dialog with "OK" and "Cancel" buttons appears, warning of the existence of the file.


A Functions

The sections that follow identify all VTScada functions beginning with "A".


Abs

(Engine-Level Function)

Description: | Returns the absolute value of a numeric expression.
Returns: | A positive, numeric value
Usage: | Script or steady state.
Function Groups: | Generic Math
Format: | Abs(X)
Related to: | Min | Max | Step
Parameters: | X Required. Anything that can be cast to a floating point number.
Comments: | Given a valid numeric value, the returned value will be positive or zero (0)

Example:

  Angle = Abs(EncoderAngle);


AbsTime

(Engine-Level Function)

Description: | Absolute time. This function returns true when a multiple of a fixed time has been reached.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Time and Date
Related to: | DateNum | Day | Month | Now | RTimeOut | Seconds | SetClock | TimeOut | TimeArrived | Today | Year
Format: | AbsTime(Enable, Interval, Offset)
Parameters: |

Enable

Required Boolean. Any expression giving the condition that allows the timer to operate.

When this parameter is true (i.e. not 0), the timer is "running". When this parameter is false (i.e. 0), the timer stops and the function has a value of false.

Interval

Required. Any numeric expression giving the time in seconds between the absolute time periods. This parameter must be strictly greater than 0, otherwise the function value will be invalid.
Offset
Required. Offset is any numeric expression giving the time in seconds to shift the absolute time from multiples of the Interval time.
Comments:

The AbsTime function is designed to allow events to be scheduled at regular time intervals in real time. It is reset automatically when it appears in a true action trigger (IF), or when it appears in a function that resets its parameters.

The parameters are relative to local time. If attempting to schedule an event for the same time across servers in multiple time zones, the offset should be an expression relative to each time zone.

Note that the behavior will differ depending on whether you use this function in a script code module or in a tag expression. In script code, the function will be reset as described, and will wait for the next trigger to occur.
In a tag expression, this function will not be reset after triggering.

Because AbsTime is ultimately based on midnight January 1st, 1970 (a Thursday), it is possible in theory to use it for a weekly time interval, with an appropriate offset for the day of the week starting from Thursday. In practice, TimeArrived may be more appropriate for a weekly trigger.

VTScada includes an application property at the \Code level named SecondFlasher. The value of this property changes from 0 to 1 once a second, as near as possible to the change of the second. In most cases, it is better to watch for the change of \SecondFlasher than to burden the system with an additional function to calculate one-second intervals.

Example:

  If AbsTime(1, 86400 { 24 hrs }, 28800 { shifted 8 hrs });
  [
    ...
  ]

In the example above, the script will be executed every 86400 seconds (24 hours), offset by 28800 seconds (8 hours) from midnight. This means that the trigger will become true at 8:00 AM every morning when the script executes. The function will then be reset to wait until 8:00 AM the following day to execute again.

  If AbsTime(1, 3600 { 1 hr }, 0 { not shifted });
  [
    ...
  ]

The example displayed above enables a user to schedule an event to run on the hour, every hour.

Expression Example:

Latch(AbsTime(1, 10, 0), AbsTime(1, 10, 5))

In steady state, this expression will toggle between TRUE and FALSE every five seconds. If used for the opacity parameter of an object in the Idea Studio, this will make the object blink on a five-second cycle.

Related information:

Latching and Resetting Functions


AcceptSecurityContext

(Engine-Level Function)

Description: | Accepts a Kerberos security context from a client and returns the user principal name (UPN) from the context, along with any output to be returned to the client for mutual authentication.
Warning: | This function should be used only by advanced programmers.
Returns: | Boolean. TRUE if the security context was successfully accepted and a user name was extracted
Usage: | Script Only.
Function Groups: | Security
Related to: |
Format: | AcceptSecurityContext(InputBuffer, UserName, OutputBuffer)
Parameters: |
InputBuffer
Required. The security context from a client
UserName
Required. A variable that will receive the UPN format username of the user that created the context if the context is successfully validated.
OutputBuffer
Required. Any security context response to be returned to a client.
Comments:

Used to validate a security context from a VIC.

Example:

  If AuthRequired;
  [
    NegotiateTest = AcceptSecurityContext(AuthToken, AccountName, ContextBuffer);
    ...
  ]


Accumulate

(Hierarchical Accumulator module)

Description: | Adds a tag and a value to be counted for that tag, to a named accumulator.
Returns: | Invalid
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | GetValue | GetContainerNumActive | GetContainerNumUnacked
Format: | \HierarchicalAccumulator.Accumulate(TagObj, AccumulatorName, Value [,LocalUniqueID]);
Parameters: |
TagObj
Required. The tag object that is contributing to the count
AccumulatorName
Required. The name of the accumulator that the tag is contributing to. For example, two accumulator names in use by the Alarm Manager are, "AlarmUnacked" and "AlarmActive". If creating your own accumulator, you may use any name you wish.
Value
Required. The current value to count for the TagObj\LocalUniqueID. Commonly a 1 or 0.
LocalUniqueID
Optional. If one tag contains items to be accumulated, use this field to provide a locally unique identifier for each.
Example: for accumulation of active alarms in Analog Status tag, this parameter will be "Hi" or "Lo", depending on which built-in alarm is being counted.
Comments:

The Accumulate function always returns Invalid. It may be called in steady state (for concise code), or as a subroutine call in a script to save RAM.
This function is part of the HierarchicalAccumulator module, so must always be called as shown in the format. You will need this function if creating a new type of tag, which also contains its own built-in alarms. You may create an accumulator for any property of your tag.

The accumulator enables a fresh count to be generated at different levels in a tag tree, and as tags are moved or disabled.

Access to the accumulation of active and unacknowledged alarms is provided by the Alarm Manager's GetContainerNumUnacked and GetContainerNumActive functions.
To access accumulations of your own creation, use the \HierarchicalAccumulator.GetValue function.

Examples:

  If Watch(1, AlarmLoUnacked);
  [
    \HierarchicalAccumulator.Accumulate(Root, "AlarmUnacked", AlarmLoUnacked != 0, "Lo");
  ]


Ack

(Alarm Manager module)

Description: | Will acknowledge an alarm.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | AckAllAlarms | AckAllAlarmsPlusDlg
Format: | \AlarmManager.Ack(AlarmName[, EventTime, AccountID, Device, RecordGUID, Custom, MachineID, FromPLC]);
Parameters: |
AlarmName
Required.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

EventTime
Optional UTC timestamp of the value. Defaults to the current time.
AccountID
Optional text. The name of the operator who acknowledged the alarm.
If invalid, the logged-in user (according to the Security Manager) will be used.
Device
Optional text. Name of the client device that sent the acknowledgment.
RecordGUID
Optional text. Acknowledge only this specific record.
See: Alarm API Structure Definitions
Custom
Optional. A structure of custom fields to log.
MachineID
Optional. The machine ID of the workstation linked with this acknowledgement.
FromPLC
Optional. Used only with PLCAlarm tag. True when the Ack took place in the PLC.

Comments:

Example:

  If StrictlyNotEqual(IsUnAcked, OldIsUnAcked);
  [
    IfThen(!IsUnAcked,
       { If I have been Acked in the PLC, Ack me. }
      \AlarmManager.Ack(AlarmName { Alarm name  },
                        Invalid   { TimeStamp   },
                        Invalid   { AccountID   },
                        Invalid   { Device      },
                        Invalid   { RecordGUID  },
                        Invalid   { Custom      },
                        Invalid   { MachineID   },
                        TRUE      { FromPLC     });
    );

    OldIsUnAcked = IsUnAcked;
  ]


AckAllAlarms

(Alarm Manager module)

Description: | Will acknowledge all unacknowledged alarms available to the current user.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Ack | AckAllAlarmsPlusDlg
Format: | \AlarmManager.AckAllAlarms(IgnoreSession);
Parameters: |
IgnoreSession
Required Boolean. True to ignore any filtering based on the calling module's session.
Comments: To confirm the acknowledgment of alarms use AckAllAlarmsPlusDlg

Example:

  If MyCustomAckButtonWasPressed;
  [
    \AlarmManager.AckAllAlarms(FALSE{ Filtering is a good thing });
  ]


AckAllAlarmsPlusDlg

(Alarm Manager module)

Description: | Will acknowledge all unacknowledged alarms available to the current user after confirmation
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Ack | AckAllAlarms
Format: | \AlarmManager.AckAllAlarmsPlusDlg([TestButton]);
Parameters: |
TestButton
Optional Boolean. Should be valid only when you are calling this function from a test. A value of 0 simulates cancel. 1 simulates OK.
Comments: This does what AckAllAlarms does but it includes a call to ask the user, thus changing the behavior from a synchronous call to a asynchronous call.

Example:

  If WinButton(200, 200, 200 + \LgBtnWd, 200 + \BtnHt,
               0, "Ack All", 1, \_DialogFont);
  [
     { An asynchronous call that asks the user to confirm Ack All }
    \AlarmManager\AckAllAlarmsPlusDlg();
  ]


Acknowledge

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Will acknowledge an alarm.
Returns: | 0
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Ack | CurrentTime | Register (Alarm Manager)
Format: | \AlarmManager\Acknowledge(AlarmName[, EventTime, Operator]);
Parameters: |
AlarmName
Required. The name of the alarm (not the alarm object value that was passed to the Register subroutine) that will be acknowledged
EventTime
Optional. Timestamp to use when adding this event to the alarm lists. Defaults to CurrentTime()
Operator
Optional text. The name of the operator who acknowledged the alarm.
If invalid, the logged-in user (according to the Security Manager) will be used. If the Security Manger user is empty, then the application property, "LoggedOffLabel" will be used.
Comments: This subroutine's primary responsibility is to send RPC messages to other workstations. DoAcknowledge does the actual work of acknowledging. When an acknowledgment is done, the only field that will change is status. To change any other field, a custom DoAcknowledge that is aware of the structure of alarms within the application must be written.


ACos

(Engine-Level Function)

Description: | Calculates the trigonometric arc cosine in radians.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Trigonometric Math
Related to: | ASin | ATan | Cos | Sin | Tan
Format: | ACos(X)
Parameters: |
X
Required. Any numeric expression in the range -1 to +1.
Comments:

The returned angle is in radians. To convert an angle from radians to degrees, divide by \Pi / 180 or (approximately) 0.0174533.

\Pi is a defined constant in VTScada.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

  RadAngle = ACos(0);
  DegAngle = RadAngle / \Pi / 180;

In this example, the value of DegAngle will be 90.


AcquireLock

(System Library)

Description: | Subroutine to acquire an exclusive lock on reading / writing working copy files across all applications.
Warning: | This function should be used only by advanced programmers.
Returns: | Semaphore via the third parameter
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | ReleaseLock |
Format: | System.Acquirelock(WritePermission, Owner, SemaphorePtr[, WritingUserID])
Parameters: |
WritePermission
Required. Any BOOLEAN expression. Set TRUE if the owner intends to perform writes or FALSE for read-only access.
Owner
Required. The instance of the lock owner.
SemaphorePtr
Required. A pointer that will be set TRUE when the semaphore is granted.
WritingUserID
Optional. User ID for the user acquiring the lock. Should be used if the user is going to make working copy changes and not commit them within the lock, so that the correct User ID is assigned to the changes when they are committed.
Comments:

This function should be called before performing any modification of any application’s working copy. The output of this function is a semaphore that guarantees exclusive access to the working copy until it is released.

Note that the caller must wait for the semaphore to become TRUE (1), which indicates that the lock is held.

A lock gathered by AcquireLock should be released by calling ReleaseLock. It is automatically released when the variable used to collect the semaphore is released during calling object destruction. This module launches a destructor module so that if the caller to this module stops, the destructor will continue to run until ReleaseLock is called or one of the parameters becomes invalid.

Because this lock prevents any other access to the working copy, you should minimize the length of time it will be held.

Examples:

GetLayerLock [
  If 1 WaitForLock;
  [
    System.AcquireLock(1 {write}, Self, &LayerLock);
  ]
]

WaitForLock [
  If LayerLock;
  [
     { process files }
  ]
]


Active

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Tells the Alarm Manager to activate an alarm. This subroutine will activate an alarm and signal it as unacknowledged.
Returns: | 0
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) (Alarm Manager) | CurrentTime | Normal | IsActive
Format: | \AlarmManager\Active(AlarmObject[, EventTime]);
Parameters: |
AlarmObject
Required. Object Value for the alarm that was passed to the active Register subroutine.
EventTime
Optional, Timestamp to use when adding this event to the alarm lists. Defaults to CurrentTime()
Comments: The Active subroutine always returns "0".


ActiveCode

(Engine-Level Function)

Description: | ActiveCode returns the code value of the active statement in the given module instance.
Returns: | Code Value (See: VTScada Value Types)
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | ActiveState | ActiveWindow | CurrentWindow | StateName | ModuleFileName
Format: | ActiveCode(Object)
Parameters: |
Object
Required. Any object expression to be monitored in the module instance.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

A code value is a combination of module, state and statement that is the active statement in the given module instance (object value).

Example:

  Stmt = ActiveCode(ReadObj);


ActiveState

(Engine-Level Function)

Description: | ActiveState returns the code value of the active state in the given module instance.
Returns: | Code Value (See: VTScada Value Types)
Usage: | Script or steady state.
Function Groups: | Compilation and Online Modifications, States
Related to: | ActiveCode | ActiveWindow | CurrentWindow | StateName | ModuleFileName
Parameters: |
Object
Required. Any object expression to be monitored in the module instance.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

A code value is a combination of module and state that is the active statement in the given module instance (object value).

Example:

  State = ActiveState(Self());


ActiveWindow

(Engine-Level Function)

Description: ActiveWindow returns the object value of the root module instance in the current active window.
Returns: Object value (See: VTScada Value Types)
Usage: Script or steady state.
Function Groups: Window
Related to: ActiveCode | ActiveState | CurrentWindow | Window
Format: ActiveWindow( )
Parameters: None
Comments:

the ActiveWindow() function returns the active window for the UI where it is being called. For example, if it is being called in an object running on a thin client, then it will return the object of the active window on the thin client. Otherwise, it returns the active VTScada window on the machine running VTScada, across all applications.

Child windows (those with bit 9 set in their Window call) are not recognized as separate entities. Clicking on a child window returns the object value of the root module in its parent window. This is not true for owned windows (those with bit 15 set in their Window call), which return the object value of the root module instance in the window.

Example:

  Object = ActiveWindow();


ActiveX

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Instantiates an ActiveX object. An ActiveX object is treated as a COM client interface that requires a client window area in which to draw.
Usage: | Steady State only.
Warning: | This function should be used only by advanced programmers. It may interfere with VTScada graphics.
Function Groups: | COM
Related to: | COMClient | COMEvent | COMStatus
Format: | ActiveX(X0, Y0, X1, Y1, ObjectIdentifier[, EventSearchScope, EventParent, EventCaller, LicenseString])
Parameters: |
X0, Y0, X1, Y1
Required These are the numeric coordinates of the client window area in which the COM object is to draw itself.
ObjectIdentifier
Required. Specifies a unique identifier for the object that is to be instantiated. It may take one of the following forms:
• A text string representing a ProgID (e.g. "Excel.Application").
• A textual GUID in registry format (e.g. "{000208-0000-0000-C000-000000000046}"). Note that the curly braces are compulsory.
• A binary GUID (e.g. the result from "GetGUID(1, 00020812-0000-0000-C000-000000000046)").
EventSearchScope
Optional. May be any expression that yields a module value or object value. This parameter specifies the scope in which to search for event subroutines. Needed only if you wish to handle events from the COM object. If missing or invalid, the COM events will not be enabled.
EventParent
Optional Any expression yielding an object value. If present, specifies the context that is used to resolve scope for event subroutines. May be any expression that yields an object value.
Defaults to Self().
EventCaller
Optional. Any expression that yields an object value. If present, this specifies an "auxiliary" context for event subroutines. An event subroutine can retrieve this value using Caller(Self())
Defaults to Self().
LicenseString
Optional. Used to provide a license key that will be passed to the ActiveX control when instantiated, permitting the use of ActiveX controls that require license data for activation. This will work for both server-instantiated ActiveX controls and those that are remotely called by a VIC.
Comments:

If the statement succeeds, a COM client interface is returned, allowing subsequent access to the object. If it fails, Invalid is returned.

There are two significant parametric differences between an ActiveX function and a COMClient function. Firstly, the ActiveX function requires a client window in which to draw. Secondly, there is no ObjectContext parameter. ActiveX objects are only instantiated in process, as they require direct GDI access to process resources [such as the client window area].

A window in VTScada acts as a container for ActiveX objects, in the true OLE definitions of the OC96 specification. This architecture provides a container enumerator so that an ActiveX object can interact with other ActiveX objects in the same container.

Like the COMClient function, this function returns an opaque COM Client Interface handle, through which subsequent object manipulations are performed. Refer to the documentation for the ActiveX object you are creating for properties, methods, and events.

Unlike the COMClient function, this statement may be only be used as a steady-state statement.

The ActiveX object will only remain instantiated while the steady-state statement is still running (i.e. a change of state or destruction of the module instance which is running the statement will cause the ActiveX object to be destroyed). Any variables that hold a handle to the COM Client Interface will be invalidated at that time.

When an ActiveX control is running in a thin client session, numeric values are limited to double floating-point values, whereas an ActiveX control running on the server can use full 64-bit integers. Therefore numeric values with a magnitude over 9007199254740992 may lose precision when passed into or out of an ActiveX control.

Within an Anywhere Client session, this function does nothing.

Example:

[
  Loaded = 0;
  BrowserObj;
]
Main [
  BrowserObj = ActiveX(50, 150, 150, 120, "Shell.Explorer");
  If Timeout(Valid(BrowserObj) && !Loaded, 1);
  [
    BrowserObj.Navigate("VTScada.com");
    Loaded = 1;
  ]
]


AddAccount

Security Manager Module

Description | Creates a new account (either a user account or a role).
Returns | Object value
Usage | Script Only.
Related to: | ModifyAccount | DeleteAccount
Format | \SecurityManager.AddAccount (NewAccountData [, PtrReturnCode, HaveLock]);
Parameters |
NewAccountData
Required. An AccountData Structure, a single dimension array of AccountData structures or a dictionary of AccountData structures containing the data for the new account(s).
PtrReturnCode
Optional. A pointer to a value that will contain one of the defined result codes at the conclusion of the operation. (Security Manager Return Codes)
HaveLock
Optional. A Boolean value that indicates whether the working copy lock is held by the calling code. Default FALSE.
Comments

To use this API, the calling code must be running in a security session that has Manager privilege.

Adding an account is an asynchronous operation. If the asynchronous operation was not attempted, due to detection of an error, the return value will be Invalid. If the asynchronous operation is attempted, the return value will be an object value. The object value will become Invalid when the asynchronous operation completes. At that time (or when the method returns Invalid), the value addressed by PtrReturnCode can be examined to determine the status of the operation. The contents of the value addressed by PtrReturnCode are undefined until the method returns Invalid.

A single account can be added by supplying a single AccountData structure in NewAccountData. Multiple accounts can be added in one operation by providing a single dimension array or dictionary of AccountData structures in NewAccountData.

The result code returned in the value addressed by PtrReturnCode will be a scalar value if a single structure was supplied in NewAccountData. If an array of structures or a dictionary of structures was supplied, a single dimension array of the same size as NewAccountData will be returned in the value addressed by PtrReturnCode, each element containing the result code for the corresponding NewAccountData element.

Adding an account requires a working copy write lock. If such a lock is held by the calling code, the HaveLock parameter must be set to TRUE. Otherwise omit this parameter or set it to FALSE. If the calling code holds a read lock on the working copy, this must be released before AddAccount can complete its operation.

The AccountData structure(s) provided must have the Username member set to a unique name. If the account being added is a user account (as opposed to a role), a password meeting application password strength settings must be provided.

On return the AccountID member of each AccountData structure that was successfully processed will be set to a unique user ID that will not change for the life of the account. The Password member is not erased.

It is strongly recommended that calling code ensure that unencrypted passwords are destroyed as soon as possible after completion of this operation.

Example:

( {parms for a subroutine that generates a new operator account }
  NewName     { Name for the new account                };
  NewPword    { Temporary password for the new account  };
)
[
  PROTECTED NewAccount       { structure holding the new account being made     };
  PROTECTED WaitObj          { will be set Invalid on comletion                 };
  PROTECTED OperationResults { will hold the result of the AddAccount operation };
  PROTECTED NewID            { unique ID for the new account                    };
]
Main [
  If 1 Done;
  [
    NewID = \SecurityManager.CreateAccountID(NewName);
    NewAccount = \SecurityManager.AccountData(NewID, NewName, NewPword, { AccountID, AccountName, Password }
                              Invalid, Invalid, 0,         { AltID, AutoLogoff, Force password reset }
                              New(1),                      { Rules }
                              FALSE, FALSE,                { IsRole, Disable }
                              Invalid);                    { CustomData }
    NewAccount.Rules[0] = \SecurityManager.SecurityRule("Operator", Invalid, Invalid, FALSE);
    WaitObj = \SecurityManager.AddAccount(NewAccounts, &OperationResults);
  ]
]

Done [
  If !Valid(WaitObj);
  [
     { The account is added, so we're finished. You may want to check the contents of OperationResults. }
    Slay();
  ]
]


AddCertificate

(Engine-Level Function)

Description: | Returns a structure of information about a supplied X.509 certificate.
Returns: | Structure
Usage: | Script Only.
Function Groups: | Certificates
Related to: | CheckCertificateChain | FindCertificate | GetCertificateInfo | ListCertificates | MakeSelfSignedCertificate | RemoveCertificate | SetCertificateProperty
Format: | AddCertificate(MachineStore, StoreName [, CertificateBlob, isPFX, PFXPassword, FriendlyName, PrivateKey])
Parameters: |
MachineStore
Required Boolean. If TRUE (non-zero) attempts to add the certificates to a store in the Local Computer certificate hive. If FALSE (zero) attempts to add the certificate to a store in the Current User certificate hive.
StoreName
Required text. The name of the store to add the certificate to. If it does not exist, it will be created.

CertificateBLOB

Optional. A buffer holding a DER-binary encoded certificate BLOB (binary large object) of the certificate to add.
isPFX
Optional Boolean. TRUE (non-zero) if the certificate is in Personal Information Exchange (PFX) format. FALSE if it is in DER-binary format. Default FALSE.
PFXPassword
Optional text. Only required if the certificate is in PFX format and contains a private key. This is the password used to encrypt the private key when the PFX was created.
FriendlyName
Optional text. The friendly name to be assigned to the certificate.
PrivateKey
Optional. The private key to associate with the certificate. This is only required if you need to associate a private key with the certificate and one is not provided in a PFX format CertificateBlob.
Comments

The certificate blob may be obtained from a number of different sources. For example, it may be transmitted over a communication protocol, be the output of another certificate DAG or the contents of a certificate file (commonly .DER for DER-binary encoded certificates and .PFX for Personal Information Exchange certificates).

For .PFX encoded certificates, set the isPFX Boolean and, optionally, provide the password that was used to protect the private key when the PFX was created.

For DER-binary encoded certificates, you can provide a separate private key (stored in a VTScada crypto-key value - Cryptographic Keys) as the PrivateKey parameter. This must match the public key contained in the certificate blob, or the attempt to add the certificate will fail.

Using AddCertificate without a certificate will attempt to create the certificate store without adding a certificate.

Example:

    AddCertificate(FALSE, "NewStore");

This will create a new certificate store named "NewStore" in the local user’s certificate hive.

    Thumbprint = AddCertificate(TRUE, "My", FileStream("MyCert.pfx"), TRUE, Password);

This will attempt to add the certificate and private key contained within the "MyCert.pfx" file to the local computer’s Personal certificate store. The private key in the PFX file is secured using the supplied Password. If the statement succeeds, the SHA1 thumbprint of the certificate will be returned.


AddConnection

(ODBC Manager Library)

Description: | Called to get the object value of an ODBC connection. If the connection does not exist, then a new ODBC DSN connection will be created and explicitly added to the ODBC Manager's internal list of DSN's
Returns: | The object value of an ODBC connection
Usage: | Script or steady state.
Function Groups: | ODBC
Related to: | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.AddConnection(DSN[, UserName, Password, ConnectTimeout, ExecutionTimeout, IdleTime, CheckBackupTime, DisconnectOnError, HandleError, UseDriverTimeout, MirrorToDisk, DBType, PaceRecovery, PaceRecoveryRate, RollbackOnConnect, ReconnectDelay])
Parameters: |
DSN
Required. Text identifying the database to connect to. This can be a DSN (data source name) or it could be a connection string containing a fileDSN parameter such as: "filedsn = C:\VTScada\Access.dsn; dbq = c:\testdb1.mdb"
UserName
Optional. An optional parameter providing the user name for database access.
If both the Username and Password are missing from the function call, a dialog box will prompt the operator to provide values for these parameters.
Password
Optional parameter for providing the password, if required, for database access. See note for UserName.
ConnectTimeout
Optional numeric parameter specifying the length of time the module will wait for a valid database connection to be made.
Defaults to 30 if missing or invalid
ExecutionTimeout
Optional parameter specifying in seconds, the length of time the method will wait for a database command to execute. The parameter, UseDriverTimeout must be true for this parameter to have any effect.
Defaults to 60.
IdleTime
Optional parameter specifying in seconds, the length of time will wait with no database communication before closing the connection.
Defaults to 600 if missing or invalid
CheckBackupTime
Optional numeric parameter specifying the length of time between checks for cache files left behind failed log attempts.
Defaults to 300 if missing or invalid
DisconnectOnError
Optional Boolean parameter indicating whether the ODBC connection should be terminated after any execution error occurs.
Defaults to FALSE (0) if missing or invalid.
HandleError

Optional parameter that can be any of:
• an error handle object,
• an array of errors,
• a Boolean value. TRUE to disconnect or false to indicate no disconnect.
Defaults to false, meaning 'no disconnect'.

UseDriverTimeout
Optional Boolean value which may be set to true if ODBC driver in use supports timeouts.
If so, then the execution timeout limit (ExecutionTimeout) is handed to the ODBC functions. Defaults to FALSE (0) if missing or invalid.
MirrorToDisk
Optional Boolean value. If true, this specifies that every write should go to disk.
Defaults to FALSE (0) if missing or invalid.
DBType
Optional numeric value, indicating the type of this DB connection. Defaults to 0 if missing or invalid.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase
PaceRecovery
Optional, Boolean value. Set to TRUE (non-zero) to pace the recovery of logs using the value in the following parameter.
Defaults to TRUE (1) if missing or invalid.
PaceRecoveryRate
Optional. Any numeric expression that will set the time in seconds for recovery of logs. The preceding parameter, PaceRecovery must be set to true.
Defaults to 0.1 if missing or invalid.
RollbackOnConnect
Optional. Any Boolean expression. If set to TRUE (non-zero) a rollback will be done on connect.
Defaults to TRUE (1) if missing or invalid.
ReconnectDelay
Optional numeric expression to set the time to wait for reconnect on a failed connect.
Defaults to 5 if missing or invalid.
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.

The only way to ensure that a long running (or faulty) query does terminate is to set appropriate values for both the parameters ExecutionTimeout and UseDriverTimeout. Modules executing queries are designed to be run as launched modules and will remain active until complete.

Example:

( {Parms for a subroutine that will connect to a database }
  TargetDSN     { Data source name                        };
  UserName      { User name for the database (if req'd)   };
  Password      { Password                                };
  QueryTimeout  { Max time to wait                        };
  DBType        { What type of database                   };
  ODBCConn      { OBDC connection object                  };
)
[
  Err           { HandleError                             };
]
Main [
  If Watch(1);
  [
    ODBCConn = \ODBCManager.AddConnection(TargetDSN,
                                          UserName,
                                          Password,
                                          Invalid,
                                          QueryTimeout,
                                          Invalid,
                                          Invalid,
                                          1 { Disconnect on error },
                                          Err,
                                          Invalid,
                                          Invalid,
                                          DBType );
 ...


AddContributor

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Adds a contributor to a container.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Containers and Contributors
Related to: | DeleteContributor |GetContributors |PContributor |
Format: | \AddContributor(HandleName, ArrayName, CountName, ContainerObj, ContributorObj, IndexAddress, Value, CountIncrement, ContributorType);
Parameters: |
HandleName
Required. The name of the handle variable in the container module.
ArrayName
Required. The name of the variable in the ContainerObj parameter, that holds an array of values to which the contributor is to be added.
The ArrayName parameter may be invalid if there is no such array in the container.
CountName
Required. The name of the variable in the ContainerObj parameter, that holds a count of the current number of this type of contributor.
CountName may be invalid if no such variable exists in the ContainerObj. Not all contributors need to be counted.
Note that CountIncrement determines the initial change in the count and the contributor must maintain the count.
ContainerObj
Required. The object value of the container tag module.
ContributorObj
Required. The object value of the new contributor to add to the container.
IndexAddress
Required. The address pointer of the variable holding the contributor index.
Value
Required. May be Invalid. The current numeric value to set in the container's ArrayName array.
Value may be Invalid. Value may also be updated at any time by the contributor by scoping into the ArrayName array in the container, and setting the array element at the index that will be set in the variable pointed to by IndexAddress.
CountIncrement
Required. The numeric value that will be added to the variable in the container that has the same name as CountName.
CountIncrement's value is usually a "1" or a "0", indicating whether the contributor is actively contributing its value. The contributor will increment or decrement the value of the CountName variable as the corresponding state of the contributor changes.
ContributorType
Optional string identifier.
Using an alarm contributor as an example, this is might be "HH", "H", "LL", "L", etc.
Comments:

Used only when writing custom tags with code (as opposed to creating them from Context tags). See: Containers, Contributors and Site Tags

This function can be called from the contributor.

Example:

Refer to the tag template provided in the Examples sub-folder of your VTScada installation.


AddEditorText

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Inserts a text string into a text editor.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Editor
Related to: | WinEditCtrl
Format: | AddEditorText(Editor, Text)
Parameters: |
Editor
Required. Any expression that evaluates to an editor value that was created by the MakeEditor function.
If this is not an editor type value, then the function will do nothing.
Text
Required. The text to insert into the text editor.
Comments:

The text will be broken into lines based on carriage returns or line feeds or both.


AddEvent

There are two AddEvent functions. Both are documented in this topic to avoid confusion and to simplify searches.
* Use OperatorLog.AddEvent for creating custom records of operator activity related to tag values.
* Use AlarmManager.AddEvent for all other event recording.

OperatorLog.AddEvent

Description: | This module is used specifically for logging messages when a user has written a control value.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | nothing
Format: | \OperatorLog.AddEvent(TagName, NewValue[, User, Priority, Area, OperatorNameFlag, Reserved, EvtOldValue, Units, Device, Timestamp]);
Parameters: |
TagName

Required text. The name of the tag being affected.

NewValue
Required. The new value of the tag.
User
Optional text. The full username of the operator
Priority
Obsolete parameter. Use INVALID as a place holder.
Area
Optional text. The area property of the tag.
OperatorNameFlag
Optional Boolean. If TRUE and no user is specified, the current operator name is logged. Defaults to TRUE.
Reserved
Obsolete parameter. Use 1 as a placeholder.
EvtOldValue
Optional. The previous value of the tag.
Units
Optional text. Units of the new value.
Device
Optional. Name of client device or Publisher tag name.
Timestamp
Optional. Timestamp used for logging historical events.

Example:

  { Commit WriteValue when DoChange is TRUE }
  If DoChange;
  [
    DoChange = FALSE;
    \OperatorLog.AddEvent(\Name, WriteValue, Invalid, Invalid, Invalid, 1, 1, \Value, 1));
    \Set(WriteValue);
  ]

Related information:

OperatorLogTemplate

AlarmManager.AddEvent

Description: | Adds an event to the System Event database (or another Alarm Database if specified). The alarm does not need to be commissioned.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | nothing
Format: | \AlarmManager.AddEvent(Name, Area[, Description, UserID, Timestamp, Value, Units, MachineID, Device, Custom, AlarmDBName, MessageID, NoteRequired]);
Parameters: |
Name

Required text. A unique name for the source of this event.

Area
Required text. The area for this event. If INVALID the "System" area will be used.
Description
Optional text or PhraseID. The description for the source of this event.
UserID
Optional. Either the User ID to be logged with this event, or a Boolean.
If a Boolean is used, then if TRUE, the calling session's User ID will be logged.
If FALSE or INVALID (the default), no user ID will be logged.
Timestamp
Optional. The timestamp of the event in UTC. If not valid the current time will be used.
Value
Optional. A value to log.
Units

Optional. The value's units.

MachineID
Optional. The workstation's machine ID. If INVALID, the current workstation's ID will be obtained and used.
Device
Optional. Name of the client device.
Custom
Optional. An array or a structure of custom values to be recorded.
AlarmDBName
Optional. The AlarmDatabase tag to use. Defaults to SystemEventDB.
MessageID
Reserved. Use INVALID as a place holder.

NoteRequired

Optional Boolean. Set TRUE to prompt for a note before logging the event.

Example

  If ActionHappened;
  [
    { Log this event }
    \AlarmManager.AddEvent(Invalid, Invalid, { default name and area }
                           "CustomActionLabel", TRUE);
    ActionHappened = FALSE;
  ]


AddLock

(Control Lock Manager)

Description: | Adds a Control Lock to a tag.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | (Control Lock Manager)
Related to: | AddLock | CanAddLock | CanControl (Control Lock Manager) | CanRemoveLock | GetLockLevel | RemoveLock |
Format: | \ControlLockManager.AddLock(TagID, Level[, Note, Custom, Timestamp, SessionID, AccountID, MachineID, Device])
Parameters: |
TagID
Required text. The unique ID of tag to be locked. (TagObj.UniqueID)
Level
Required integer. The Lock Level (defaults to 1).
Note
Optional text. A note to log with the lock.
Custom

Optional. A structure of custom fields to log.

This is anything that can be packed by Pack(). That is, numerics or strings, or any simple data structures that contain numerics or strings such as arrays, structures and dictionaries.

Timestamp
Optional timestamp. UTC timestamp of this event.
SessionID
Optional text. The ID of the session adding the lock.
AccountID
Optional text. The AccountID of the user adding the lock.
MachineID
Optional text. The workstation's MachineID, from which the lock was created.
Device
Optional text. The name of the client device.
Comments:

In order to lock the entire tag tree, a fictitious ‘Root Tag’ is declared in ControlLockManager.

This option is accessible only through custom script using syntax similar to:

 \ControlLockManager.AddLock(\ControlLockManager.RootTagID, Level)

The fictitious root tag's name and area can be changed by adding ControlLockRootTagName and ControlLockRootTagArea properties. This changes the Name and Area of the root tag in the Alarm List (Control Lock List) widget.

Example:

None available.


AddModule

(Engine-Level Function)

Description: | Adds a new module to an existing module and returns the value of the newly created module.
Warning: | This function should be used only by advanced programmers.
Returns: | A new module value
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AddOptional | AddParameter | AddState | AddStatement | AddVariable | CreateModule | FirstState
Format: | AddModule(Parent, Name, Reserved, Attrib, Class, VarTextSize, DocFileName)
Parameters: |
Parent
Required Any expression that returns a module value. Specifies the parent object of the new module.
Name
Required. Any text expression providing a name for the new module.
Reserved
Reserved for future use. Should be set to 0.
Attrib

Required. Any numeric expression giving the module's attribute bits as follows:

Attrib | Bit No. | Attribute
0 | - | No special attributes
1 | 0 | Reserved - set to 0
2 | 1 | Queued
4 | 2 | Reserved - set to 0
8 | 3 | Reserved - set to 0
16 | 4 | Reserved - set to 0
32 | 5 | Reserved - set to 0
64 | 6 | Reserved - set to 0
128 | 7 | Reserved - set to 0
256 | 8 | Reserved - set to 0
512 | 9 | Protected

Class
Required. Any numeric expression in the range 0 to 65535, giving the class for the new module.
VarTextSize
Required. Any numeric expression giving the length of the variable declaration for the new module (i.e. NewMod MODULE { a new module }; ).
DocFileName
Required. Any text expression giving the file name of the new module's definition document.
Comments: Seldom (if ever) used when adding features to modern VTScada applications.


AddNote

(Engine-Level Function)

Description: | Adds a note to a notebook tag
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Log
Related to: |
Format: | NotebookTagObject.AddNote(TimeStamp, Operator, Note, [ResultPtr, AccountID, Parent, LegacyConvert])
Parameters: |
Timestamp
Required UTC timestamp of the note.
Operator
Deprecated text. Only use this when converting legacy notes. The name of the user who entered the note.
Note
Required. A text string containing the note or a NoteStruct structure.
ResultPtr
Optional. This pointer will be assigned TRUE if the note is added successfully, FALSE if it fails.
AccountID
Optional string. The AccountID of the user who entered the note. Defaults to the user who opened the dialog.
ParentNoteStruct
Optional structure. If the note is a comment for another note, this must be set to the NoteStruct structure of the other note.
LegacyConvert
Optional boolean. Set to TRUE when converting legacy notes. Defaults to FALSE.
Comments:

NotebookTagObject must be the object value of the Notebook tag you wish to add a note to.

This interface is not intended as a means of logging frequent string values. It was designed for occasional notes entered by people.

Example:

NotebookTagObject.AddNote(CurrentTime(1), Invalid, "Hello world", &Result);


AddOptional

(Engine-Level Function)

Description | Adds a new statement to an action script and returns its own error code.
Warning | This function should be used only by advanced programmers.
Returns | Numeric error code.
Usage | Script Only.
Function Groups | Compilation and Online Modifications, States
Related to: | AddVariable | GetStatement
Format | AddOptional(NewStatement, Destination, Location, TextSize)
Parameters |
NewStatement
Required. Any expression that returns a statement value. This is the value of the new script statement to be added.
Destination
Required. Any code value expression. Destination is the action that will receive NewStatement.
Location
Required. Any numeric expression giving the location of NewStatement within the script.
TextSize
Required. Any numeric expression giving the length of NewStatement's text in characters.
Comments

Seldom (if ever) used when adding features to modern VTScada applications.

The function returns "0" if successful and a non-0 value if it fails.


AddParameter

(Engine-Level Function)

Description: | Adds an existing variable as a module parameter and returns the number of parameters in the module.
Warning: | This function should be used only by advanced programmers.
Returns: | Numeric... the number of parameters in a module.
Usage: | Script Only.
Function Groups: | Compilation and Online Modifications, Advanced Module
Related to: | ConstCount | NumParms | SetOneParmText | SetParameter | SetParmText | AddVariable
Format: | AddParameter(Variable, Position)
Parameters: |
Variable
Required. Any expression that returns a variable value such as AddVariable(…).

This variable will become a parameter in the module where it is defined.
Position
Required. Any numeric expression giving the position in the parameter list where Variable will be inserted. Position 1 is the first parameter.
Inserting a variable past the end of the list will append the variable to the parameter list.
Comments

Seldom (if ever) used when adding features to modern VTScada applications.

The return value of AddParameter is the number of parameters in the module after the addition, or "-1" if it failed.
Caution: Attempting to insert a variable in the parameter list twice may result in undefined behavior.


AddRead

(VTSDriver Module)

Description: | Add a read request.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Memory I/O
Related to: | DelRead
Format: | VTSDriver\AddRead(Address, N, Value, Rate[, OriginalAddr, DisablePolling, DeadbandValue])
Parameters: |
Address
Required. Any expression for the address from which to get the data.
N
Required. Any expression for the number of elements to retrieve.
Value
Required. A pointer to the destination for the read data.
Rate
Required. Any numeric expression for the update rate, measured in seconds.
OriginalAddr
For use only by the Driver Multiplexer. Set Invalid in all other instances. The original address string specified in the I/O tag before being parsed into an value that is fit for the Address parameter of AddRead. For example, the original address may be {40001}{42001}, but the address given to the subordinate driver would be 40001.
DisablePolling
Primarily for use by the Driver Multiplexer. In general, should be set to Invalid for other drivers. Any numeric expression, setting a rate value for which Polling will be disabled. Polls will then only be performed by a call to Driver\PollAll() or by setting the Read module’s Trigger.
DeadbandValue

Optional numeric, applying to analog values only. Sets a minimum amount by which the unscaled values must change before a new value is reported to NewData.

Comments:

This module is called by a tag to add a request to read a specific range of memory and set the resulting read data into the variable pointed to by the third parameter.

If using this function in custom code, note that the AddRead must run on the current I/O server in order to retrieve data. An AddRead executing only on a client workstation will subscribe to the data but not cause a read.

The pointer (3rd parameter) may be a simple variable for one element read or an object reference.

Use of an object for the Value parameter allows a synchronous way of reporting new data. The object must be a module with a subroutine named NewData. NewData will have the following parameters:

Address
Required. The original address that AddRead was called with. Should be an array if Data is an array.
TimeStamp
Required. The timestamp of the data, in UTC. Should be an array if Data is an array.
Data
Required. The data value(s). May be an array of arbitrary size.
Attribute
Optional. Auxiliary data value - rarely used.
ServiceSync
Optional Boolean. TRUE when NewData is being called because the service is synchronizing, rather than when the driver reported new data.
Comments The NewData callback may only be called if RefreshData resulted in a value change (affected by PropagateOnlyOnDataChange). If Data is an array, and only element [i] changed, then the TimeStamp array is used to indicate changes. A valid TimeStamp[i] means that Value[i] and Attribute[i] are valid. Invalid TimeStamp[i] means that Value[i] and Attribute[i] will be invalid since they have not changed.

Example:

For an in-context example, refer to Template.SRC, provided in the Examples folder of your VTScada installation.

{ SetDefaultSetpoints } ( ) [ Var; ] Init [ If \PumpStationSimulator.Ready Main; [ \PumpStationSimulator.Driver.Addread(40001, 1, &Var, 1); ] ] Main [ If Watch(1, Var); [ ... ]


AddressEntry

(Dialog Library)

Description: | Checks whether the attached driver has an AddressAssist module and uses that if available. Otherwise, presents a standard edit field into which the I/O address may be entered.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAreaSelect | PCheckBox | PContributor | PDroplist | PEditField | PPageSelect | PRadioButtons | PSecBit | PSelectObject | PSpinbox | PTypeToggle
Format: | \DialogLibrary.AddressEntry(X1, Y1, X2, Y2, Var, IODevice, SupportedData, FunctionType, Title, FocusID[, Trigger, Visible, DrawBevel, BGColor, FGColor])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the object and its label. The smaller of X1 and X2 will always be to the left
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the object. The smaller of Y1 and Y2 will always be the top.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the object and its label opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the object, whichever is the opposite to Y1.
Var
Variable to be set by AddressEntry
IODevice
Any expression for the name of the I/O device driver being used.
SupportedData

A bitwise expression, indicating the data type.

(See: Bitwise Parameters & Operations)

Bit | Meaning when set
0 | Digital
1 | Analog
2 | Text
FunctionType
Any Boolean expression, indicating whether the function should be read (0) or write (1).
Title
Any text expression to use as the title for the field.
FocusID
Any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the field will display its current setting, but will not be able to be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
A parameter whose value is derived from ZEditField and can therefore be set to "0" (internal buffer changed), "1" ("Enter" key pressed), or "2" (focus lost). If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.
Visible
Boolean. Controls the visibility of the control.
DrawBevel
Any logical expression. If TRUE, a bevel is drawn around the graphic.
BGColor
Optional. Any numeric expression for the background VTScada Color Palette of the control. No default value.
FGColor
Placeholder for the foreground color of the control. Not currently implemented.
Comments: Similar to PAddressEntry.

Example:

  {***** History Address *****}
  AddressEntry(30, 200, WIDTH/2 - 5, 155,
               HistoryAddr                        { Variable to set         },
               Scope(\Root, Parms[\#SitePoint])   { IO Device               },
               0b001                              { SupportedData: Digital  },
               0                                  { FunctionType:  Read     },
               GetPhrase("HistoryAddressLabel")   { Title                   },
               EditOK ? 5 : 0                     { Focus ID                },
               Trigger1                           { trigger                 },
               UsingHist                          { Visible                 },
               Invalid                            { Bevel                   },
               HighlightColor1                    { BG Colour               });


AddState

(Engine-Level Function)

Description: | Adds a new state to an existing module and returns its state value.
Warning: | This function should be used only by advanced programmers.
Returns: | State value
Usage: | Script Only.
Function Groups: | Compilation and Online Modifications, States
Related to: | AddOptional | AddStatement | AddVariable | FirstState
Format: | AddState(Module, Name, Reserved, Size)
Parameters: |
Module
Required. Any expression that returns a module value.
Name
Required. Any text expression giving the name of the new state.
Reserved
Reserved for future use. Should be set to 0.
Size
Required. Any numeric expression giving the length of the state definition text, measured in characters.
Comments: Seldom (if ever) used when adding features to modern VTScada applications.


AddStatement

(Engine-Level Function)

Description: | Adds a new statement to an existing state and returns its own error code.
Warning: | This function should be used only by advanced programmers.
Returns: | Error code on failure or a #VTypeModStateStmnt code value on success.
Usage: | Script Only.
Function Groups: | Compilation and Online Modifications, States
Related to: | AddVariable | MakeDAG | Compile
Format: | AddStatement(Statement, Destination, TextSize)
Parameters: |
Statement
Required. Any expression that returns a statement value. Commonly generated with the Compile function.
Destination
Required. Any expression that returns a code value.
This indicates where to insert the new statement. If no statement is present in the code value, the new statement will be appended.
TextSize
Required. Any numeric expression giving the length of the statement text, measured in characters.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

AddStatement does not affect the .SRC file. It affects the expected location of items in the .SRC file. Both must be updated in unison.
The return value is a #VTypeModStateStmnt code value if successful and an error code if the function fails.
AddStatement is disabled in the run time version of VTScada where it will do nothing and return invalid.


AddToList

(Alarm Manager module)

Description: | Adds an alarm to the specified list in an Alarm Database, usually a custom list.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm Functions
Related to: | Commission | EvaluateAlarm | RemoveFromList
Format: | \AlarmManager.AddToList(AlarmName, ListName, Action[, Timestamp, AccountID, Device, HookName, MachineID, Custom, FromPLC, Description, Config])
Parameters: |
AlarmName
Required text. A unique name for the alarm. Typically, the unique ID obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm.
For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).
ListName
Required. The name of the list to add to, e.g. “Active”.
Action

A string or PhraseID that identifies the reason for the transaction.

For default options, see Alarm Action Codes in Alarm API Structure Definitions

Timestamp
Optional. UTC timestamp of the value. Defaults to the current time.
AccountID
Optional. AccountID of operator
Device
Optional. Name of client device.
HookName
Advanced Option. Name of the hook module to call before logging this transaction.
MachineID
Optional. Workstation MachineID. Defaults to local.
Custom
Optional. Structure of custom fields to be logged with the event.
FromPLC
Advanced Option. Set to FALSE.
Description
Optional. Customized description, used if it differs from the description given to Commission.
Config
An Alarm Configuration Structure. Not required if the alarm has been commissioned via a Commission() call.
Comments:

Advanced users only.

AddToList can be used to add an alarm to a custom list. The custom list can be displayed by specifying it in a <ListFormats><Format> section of AlarmListsFormats.XML as defined in Customize Columns in Alarm Displays

To add an alarm to the Active of Unacked lists based on an evaluation of a tag's Value compared to the alarm Setpoint, consider using EvaluateAlarm instead. (Although, AddToList can, technically, do this too.)

Example:

To add an alarm to a custom "Deferred" list:

\AlarmManager.AddToList(AlarmName, “Deferred”, “DeferLabel”);


AddVariable

(Engine-Level Function)

Description: | Adds a new variable to an existing module and returns its variable value.
Warning: | This function should be used only by advanced programmers.
Returns: | Variable
Usage: | Script Only.
Function Groups: | Compilation and Online Modifications, Variable
Related to: | DeleteVariable | MakeNonShared | MakeNonPersistent | MakePersistent | MakeShared | SetDefault | SetVariableClass | SetVariableText
Format: | AddVariable(Module, Name, Reserved, Attrib, Class, PersistentSize, VarTextSize, NumDimensions, ArrayElem, ArraySize)
Parameters: |
Module
Required. Any expression that returns a module value.
Name
Required. Any text expression that gives the name of the new variable.
Reserved
Reserved for future use. Set to 0.
Attrib

Required. Any numeric expression giving the variable attribute bits as follows:

(See: Bitwise Parameters & Operations)

Attrib | Bit No. | Attribute
1 | 0 | Array
2 | 1 | Shared
4 | 2 | Persistent
8 | 3 | Module
16 | 4 | Parameter
32 | 5 | Constant
64 | 6 | (Obsolete) Reserved - set to 0
128 | 7 | (Obsolete) Reserved - set to 0
256 | 8 | Temporary *
512 | 9 | Protected
1024 | 10 | Variable is an instance variable (see comments)

A variable cannot be both persistent and temporary, since a persistent variable is stored on disk, and a temporary variable exists only while VTScada is running or until the application is recompiled.

* Note: Temporary variables should be used only by advanced users, since recompiling the application destroys them.

Class
Required. Any numeric expression in the range 0 to 65535, giving the variable class number for the new variable.
PersistentSize
Required. Any numeric expression giving the number of bytes of storage allocated in the .VAL persistent variable file for this variable.
For array types, set this to the byte size of the largest array element (normally 8 bytes for numeric values).
For arrays containing text, enter the character length of the longest string element.
Use a valid 0 if this isn't a persistent variable.
VarTextSize
Required. Any numeric expression giving the length of the variable declaration text in characters.
This parameter is ignored for temporary variable types.
NumDimensions
Required. Any numeric expression that gives the number of array dimensions for the variable.
NumDimensions should be "0" for a simple variable.
ArrayElem
Required. Any array element giving the starting element in the array. The subscript for the array may be any numeric expression.
If NumDimensions is 0, ArrayElem is ignored.
If NumDimensions is 1, this specifies the starting index for the array.
If NumDimensions is greater than 1, this is element of an array of starting indices for each dimension of the multidimensional array.
ArraySize
Required. Any numeric expression specifying the size of the array.
If NumDimensions is 0, ArraySize is ignored.
If NumDimensions is 1, this specifies the number of elements in the array.
If NumDimensions is greater than 1, this is an array of sizes for each dimension of the array.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

This function doesn't affect the .SRC file; it affects the expected location of items in the .SRC file. Both must be updated in unison.
The return value is the new variable added. If the variable already existed, it will remain unchanged and the return value will be Invalid.
Bit 10 (1024) of the Attrib parameter specifies that the variable is an instance variable. An instance variable is a temporary variable that gets added to a single instance of a module, rather than all instances of a module. If you specify this bit, then you must have passed an object (module instance) into the first parameter. Instance variables cannot also have the attributes Shared, Persistent, Module, or Parameter.

Example:

  If 1 Main;
  [
    AddVariable(Self() { Create variable as part of this module },
                "MyObjectID" { Name of new variable },
                0 { Reserved },
                256 { Variable is temporary },
                0 { Class },
                0 { Variable not persistent },
                0 { no name },
                0 {  },
                0 { Array starting index },
                0 { Number of elements in array });
  ]

In this example, the statement creates a temporary variable with a hard-coded name.


AdHocAlarm

(Alarm Manager module)

Description: | Evaluates an ad hoc alarm
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | EvaluateAlarm
Format: | \AlarmManager\AdHocAlarm(AlarmObj, CfgStructure, Value[, Timestamp, AlarmDB])
Parameters: |
AlarmObj
Required. The object value of the tag this alarm is for. This is used to find the AlarmDatabase associated with the tag. If no AlarmDatabase is found within the scope of AlarmObj, it will default to using the SystemAlarmDB. Services may leave this parameter invalid.
CfgStructure
Required. A structure of alarm configuration parameters. Normally obtained by a call to \AlarmManager\GetAlarmConfiguration.
Value
Required. The new value to be checked against the alarm Setpoint.
Timestamp
Optional UTC timestamp of the value. Defaults to the current time.
AlarmDB
Optional name or object. The alarm database to be used for this alarm. Not necessary if the alarm object is valid. Defaults to the VTScada Alarm DB.
Comments:

You should not call Commission() or EvaluateAlarm() on an ad hoc alarm. You can call Ack() and SetShelved() on an ad hoc alarm.

To activate/trip an ad hoc alarm, call AdHocAlarm() with a value that meets the alarm condition as defined by its Setpoint and Function. If you activate a (non-trip) ad hoc alarm, you are responsible for clearing it by calling AdHocAlarm() with a value that doesn't meet the alarm condition. If there is no known Setpoint, a Setpoint of 1 is often used, where a Value of 1 and 0 will activate and clear the alarm respectively. (Assuming the Function is ==)

To activate, trip, clear and acknowledge a unique instance of an ad hoc alarm, you must refer to the alarm using the same Name.

At a minimum, you need to configure Name, Area, Description, Priority and Setpoint. Other alarm configuration options are available such as Function, Trip, OnDelay, Deadband, Units, Custom, etc. It is not necessary to set the AdHoc field since that is set by AdHocAlarm().

The Name field must be unique among all alarms, including ad hoc alarms. A FriendlyName should not be specified for an ad hoc alarm since it is not logged or distributed to other servers. If the Name is the UniqueID of a tag, the current name of the tag will be shown on the Alarm Page. Otherwise, only the Name field will be shown, not the FriendlyName.

Example:

Example of an ad hoc alarm with the minimum amount of configuration. It will activate when the value is equal to 1. To clear this alarm, call AdHocAlarm() again using the same Cfg but with a Value of 0.

    Cfg = \AlarmManager.GetAlarmConfiguration();
    Cfg.Name              = "My Ad Hoc Alarm";
    Cfg.Area              = "My Area";
    Cfg.DescPhraseID      = PickValid(Description, Cfg.DescPhraseID);
    Cfg.Priority       = 1;
    Cfg.Setpoint       = 1;
    \AlarmManager.AdHocAlarm(Self(), Cfg, 1 { value });

Related information:

Alarm API Structure Definitions - Alarm configuration structures


AdjustArray

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Changes the array information for a variable.
Warning: | This function removes existing information from the array.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Array, Compilation and On-Line Modifications
Related to: | ArrayOp1 | ArrayOp2 | New
Format: | AdjustArray(Variable, NumDimensions, Start, Size)
Parameters: |
Variable
Required. Variable is any expression for the array to adjust.
NumDimensions
Required. Any numeric expression that gives the number of dimensions for the variable's multidimensional array.
Start
Required. Can be either a numeric expression or an array specifying the start for each of the dimensions.
If Start is a numeric expression, each of the dimensions will start at that value.
If Start is an array, then the Nth element in the array will correspond to the start of the Nth dimension (i.e. dimension 2 will start at start[2] ).
Size
Required. Can be either a numeric expression or an array specifying the size of each of the dimensions.
If Size is a numeric expression, each of the dimensions will be the size of that value.
If Size is an array, then the Nth element in the array will correspond to the size of the Nth dimension (i.e. dimension 2 will have a size of Size[2] ).
Comments:

Will work only with static arrays.


AdjustCode

(Engine-Level Function)

Description: | Adjusts the offsets and sizes of items stored in the .RUN file within the document file.
Warning: | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Related to: | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Function Groups: | Compilation and Online Modifications, Advanced Module
Format: | AdjustCode(Value, Type, Offset, Size)
Parameters: |
Value
Required. The value must be a code value or a Variable. This identifies the module, state, statement, or variable to adjust.
Type
Required. Any numeric expression that explicitly specifies the VTScada Value Types.
Offset
Required. Any numeric expression that specifies the starting point for the code adjustment.
Size
Required. Any numeric expression giving the number of bytes by which to shift all offset values following this entry in the .RUN file.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

This statement enables you to adjust a .RUN file while VTScada is running. If a change is to be made to the .SRC file while the application is running, this code change must also be written into the .RUN file, so that the .RUN and .SRC files will remain synchronized. AdjustCode essentially creates a space into which the applicable information may be inserted. Offset is the point for the insertion, and Size is the size of the inserted block. All code offsets that follow the inserted block are increased by Size to allow for the new location of the old code, and all items that contain the newly inserted block have their size increased by Size. For example, if the newly inserted block was going to have a variable definition written to it, and it was contained inside of a module, the module's size would increase by Size.
Note that this function does not actually write any changes into the file. Rather, it makes room for the changes to be written by another function.


AlarmCondition

(Function Library)

Description: | Returns TRUE (1) if the monitored tag has an active alarm.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: | AlarmUnAckCondition
Format: | \FunctionLib.AlarmCondition(TagObject)
Parameters: |
TagObject
A selected tag that is to be monitored for active alarms.
Comments:

This module is a member of the Function Library, and must therefore be prefaced by \FunctionLib as shown in the "Format" section.

Monitors only for active alarms. Trip alarms will not be reported.

Example:

(Example shows an expression that could be added to an I/O or Calculations tag.)

  \FunctionLib.AlarmCondition([Pump 1\Fault])

Will return TRUE (1) when the Pump 1\Fault tag has an active alarm.


AlarmUnAckCondition

(Function Library)

Description: | Returns TRUE (1) if the monitored tag has an unacknowledged alarm.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: | AlarmCondition
Format: | \FunctionLib.AlarmUnAckCondition(TagObject)
Parameters: |
TagObject
A selected tag that is to be monitored for unacknowledged alarms.
Comments:

This module is a member of the Function Library, and must therefore be prefaced by \FunctionLib as shown in the "Format" section.

Monitors only for unacknowledged alarms. Trip alarms will be reported.

Example:

Example shows an expression that could be added to the user interface (such as within an I/O or Calculations tag) rather than a script code file.

\FunctionLib.AlarmUnAckCondition([Pump 1\Fault])

Will return TRUE (1) when the Pump 1\Fault tag has an unacknowledged alarm.


AlignSelected

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Aligns selected graphic objects.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics
Related to: | FindVariable | Self
Format: | AlignSelected(Object, Mode, Side)
Parameters: |
Object
Required. Any object expression giving the module instance where the selected objects are found. They will be aligned as specified by the Mode and Side parameters (defined below).
Mode

Required. Any numeric expression that specifies how the objects will be aligned. The possible values are provided in the following table:

Mode | Alignment Type
0 | Align
1 | Stretch
2 | Size
3 | Space
4 | Tile
5 | Equal space between
Side

Required. Any numeric expression that specifies what side will be used when aligning objects. This also specifies the direction for equal or even spacing.

Side | Meaning
0 | Left
1 | Aligns on vertical center line
2 | Right
3 | Top
4 | Aligns on horizontal center line
5 | Bottom
Comments: This statement is used by the GUI tool bar alignment buttons.


AlternateLogoff

Security Manager Module

Description | Synonym for LogOff().
Returns | Nothing
Usage | Script Only.
Related to: | AlternateLogon | Authenticate | LogOff | QuietLogon | UserCredChange | UserLogonDialog
Format | \SecurityManager.AlternateLogoff()
Parameters | None
Comments | None

Example:

  If 1;
  [
    IfThen(LoggedOn,
      \SecurityManager.AlternateLogoff();
    );
    Return();
  ]


AlternateLogon

Security Manager Module

Description | Either creates, or attempts to sign in using an alternate ID value. See comments.
Returns | Boolean
Usage | Script Only.
Related to: | AlternateLogoff | Authenticate | LogOff | QuietLogon | UserCredChange | UserLogonDialog
Format | \SecurityManager\AlternateLogon(AltID, Logon)
Parameters |
AltID
The plaintext alternate ID to use.
Logon
Flag, TRUE to stop set of AltID
Comments This module call has two modes of operation.

If the SecurityManager user modification dialog is open and Logon is invalid or FALSE, the AltID string is interpreted as the Alternate ID value for the new or existing user account being configured. The intent here is for devices such as swipe card readers to be used to provide the alternate ID.

If the SecurityManager user modification dialog is not open or if Logon is TRUE, attempts to sign in the user whose AltID string matches the supplied parameter.

Returns TRUE if the accept / attempt action was successful, otherwise returns FALSE.


AMax

(Engine-Level Function)

Description: | Array maximum. This function returns the maximum value in a sub-range of a numeric array.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array, Generic Math
Related to: | AMin| Array Functions
Format: | AMax(ArrayElem, N)
Parameters: |
ArrayElem
Required. A numeric array element. The subscript(s) for the array may be any numeric expression, specifying the starting point for the array maximum search.
N
Required. Any numeric expression giving the number of array elements to use starting at the element given by the first parameter.
If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0 until N elements have been processed.
Comments: AMax ignores invalid array entries. It only returns invalid if the array subscript is invalid, N is invalid, or if all of the array entries in the specified range are invalid. If processing a multidimensional array, only the right-most dimension is used.

Example:

  highVal = AMax(trendData[0] { Start at element 0 }, 100 { Search through 100 elements });

This example sets highVal to the highest value of trendData elements 0 to 99. Because this function ignores invalid array elements, highVal will be some valid value unless all elements 0 to 99 are invalid.


AMin

(Engine-Level Function)

Description: | Array minimum. This function returns the minimum value in a sub-range of a numeric array.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array, Generic Math
Related to: | AMax | Array Functions
Format: | AMin(ArrayElem, N)
Parameters: |
ArrayElem
Required A numeric array element. The subscript(s) for the array may be any numeric expression, specifying the starting point for the array minimum search.
N
Required Any numeric expression giving the number of array elements to use, starting at the element given by the first parameter.
If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0 until N elements have been processed.
Comments: AMin ignores invalid array entries. The function only returns invalid if the array subscript is invalid, N is invalid, or if all of the array entries in the specified range are invalid. If processing a multidimensional array, only the right-most dimension is used.

Example:

  low = AMin(trendData[0] { Start at element 0 }, 100 { Search through 100 elements });

The example above sets low to the lowest value of trendData elements 0 to 99. Because this function ignores invalid array elements, low will be some valid value unless all elements 0 to 99 are invalid.


And

(Engine-Level Function)

Description: | Returns the bit-wise AND of its parameters.
Returns: | Signed 64-bit integer
Usage: | Script or steady state.
Function Groups: | Bitwise Operation
Related to: | Or | Not | XOr
Format: | And(Parm1, Parm2[, Parm3...])
Parameters: |
Parm1, Parm2[, Parm3 ...])
Required. Any number of numeric expressions.
Comments:

This operation compares the bits of its parameters and returns a result where each bit is only 1 if that bit in every included parameter is 1. If a bit in one or more parameter is 0, that bit will be 0 in the result.

This function takes signed 64-bit integers values. If a number is passed outside the range of a signed 64-bit integer, then the function will return invalid. If Value is invalid, the return value is invalid.

When doing bitwise comparisons, always use AND rather than &&. The double-ampersand operator does not make bitwise comparisons.

(See: Bitwise Parameters & Operations)

Example:

  result = And(0b1010, 0b1100);

This example sets the variable result to 0b1000.


AppIsRunning

Description: | Reports whether the application has been started and the start-up process is complete. (All tags are running, etc.)
Returns: | Boolean
Usage: | Script or Steady State
Function Groups: | Configuration Management
Related to: | AppIsStarted | AppIsStarting | Start | IsAppEditable | GetAppInstance | GetLoadedAppInstance | GetOEMLayer
Format: | \AppLayer.AppIsRunning()
Parameters: | None
Comments: | The similar functions, AppIsStarting and AppIsStarted, will return TRUE before this function will. \AppLayer may be acquired using one of GetAppInstance, GetLoadedAppInstance or GetOEMLayer.

Examples:

  If \AppLayer.AppIsRunning() && !Initialized;
  [
   { All tags are loaded. Do initialization. }
   { ... }
   Initialized = TRUE;
  ]


AppIsStarted

Description: | Returns TRUE if the application has been started.
Returns: | Boolean
Usage: | Script or Steady State
Function Groups: | Configuration Management
Related to: | AppIsRunning | AppIsStarting | Start | GetAppInstance | GetLoadedAppInstance | GetOEMLayer
Format: | \AppLayer.AppIsStarted()
Parameters: | none
Comments: | "Started" is a different state than "Running". Use care when deciding whether to use this function or AppIsRunning. Like Start, this is typically called on another Layer, rather than one’s own layer, which is presumably running. The Layer object can be acquired using GetAppInstance, GetLoadedAppInstance or GetOEMLayer.

Examples:

  If \AppLayer.AppIsStarted() NextState;
  [
    IfThen( ),
      ...
    )
  ]


AppIsStarting

Description: | Returns TRUE if the application is in the process of starting.
Returns: | Boolean
Usage: | Script or Steady State
Function Groups: | Configuration Management
Related to: | AppIsStarted | Start | AppIsRunning | GetAppInstance | GetLoadedAppInstance | GetOEMLayer
Format: | \AppLayer.AppIsStarting
Parameters: | none
Comments: | Checks whether a call to Start() is being processed in the application specified by \AppLayer. The Layer object can be acquired using GetAppInstance, GetLoadedAppInstance or GetOEMLayer.

Examples:

  If \AppLayer.AppIsStarting() NextState;
  [

    ...

  ]


ApplyChangeSetFile

Description: | Apply a named ChangeSet to an application layer.
Warning: | This function should be used only by advanced programmers.
Returns: | Object that will become Invalid on completion.
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | DirectApply | GetAppInstance | GetLoadedAppInstance | GetOEMLayer
Format: | Layer.ApplyChangeSetFile(User, Comment, FileName, pError, SuppressError, RSema, Superior)
Parameters: |
User
Required. The account name, to which the changes will be attributed.
Comment
Required. A comment to be applied to the revision.
FileName
Required. The full path to the ChangeSet file.
pError

Required. A pointer to a value in which the status of the operation will be stored as a numeric value. Defined error codes are as follows:

Code | Meaning
0 | Success / No errors
1 | Unsupported file version
2 | Checksum error
3 | File truncated
SuppressError
Optional Boolean. Set to TRUE if the error dialogs are to be suppressed. Defaults to FALSE.
RSema
Optional repository semaphore.
Superior
Optional Boolean. Set to TRUE if the ChangeSet's changes should take precedence in the event of a conflict.
Comments: The act of applying a ChangeSet file may produce unexpected results. Use with caution.

The Layer object can be acquired using GetAppInstance, GetLoadedAppInstance or GetOEMLayer.

Examples:

none.


Arc

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draws an arc on the screen.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Circle | GUIArc | GUIPie
Format: | Arc(X, Y, Radius, Angle1, Angle2, Width, Color)
Parameters: |
X
Required. Any numeric expression giving the X coordinate of the center of the arc on the screen.
Y
Required. Any numeric expression giving the Y coordinate of the center of the arc on the screen.
Radius
Required. Any numeric expression giving the radius of the arc specified in units of X screen coordinates.
Angle1
Required. Any numeric expression giving the starting angle of the arc specified in radians. An angle of 0 lies on the X axis to the right of the center of the arc.
Angle2
Required. Any numeric expression giving the ending angle of the arc specified in radians.
Width
Required. Any numeric expression giving the line width for the arc. The width is specified in terms of X screen coordinates. Any width less than 1 screen pixel is treated as a 1 pixel arc.
Color
Required. Any numeric expression giving one of the reserved VTScada Color Palette values for the arc.
Comments: The Arc statement has been superseded by the GUIArc function and is maintained for backwards compatibility only.
The arc is drawn in a counterclockwise direction from the Angle1 to Angle2.
As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.

Example:

  Arc(500, 500 { X and Y coordinates },
      100 { Radius in screen coordinates },
      0 { Starting angle in radians - 3 o'clock },
      4.71 { Ending angle in radians - 6 o'clock },
      10 { Arc line thickness in screen coordinates },
      15 { Color is white });


ArrayDimensions

(Engine-Level Function)

Description: | Returns the number of dimensions in an array.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array
Related to: | ArraySize | ArrayStart| Array Functions
Format: | ArrayDimensions(Array)
Parameters: |
Array
Required Any array variable.
Comments: The ArrayDimensions function is useful for writing intelligent parameterized modules. The module can determine how many dimensions there are in an array that is passed to it.
Note that ArrayDimensions will not drill down into nested array structures; that is to say, if a 3 dimensional array is created, and a 2 dimensional array is stored in each of its elements, ArrayDimensions will return a value of 3, not 5. This is because the data stored in different array elements does not need to be of the same type - one element could contain an array while another element could contain a simple value.

An Invalid will be returned if a simple value is handed to ArrayDimensions().

Example:

  x[10][3];
  ...
  y = New(3, 0, 10);
  numDimX = ArrayDimensions(x);
  numDimY = ArrayDimensions(y);

In this example, numDimX will have a value of 2, while numDimY will have a value of 3.


ArrayOp1

(Engine-Level Function)

Description: | Performs a mathematical operation on an array with respect to a scalar value.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Array
Related to: | ArrayOp2 | ArraySize | FFT| Array Functions | WhileLoop | Array Functions
Format: | ArrayOp1(ArrayElem, N, Scalar, OpCode[, MaskElement])
Parameters: |
ArrayElem
Required. Any array element giving the starting point for the array operation. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most subscript is used.
N
Required. Any numeric expression giving the number of array elements to compute. N will be limited to the minimum of N and the array size.
If the starting point given by the first parameter is not the first element, and therefore N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at the first element. Because N is automatically limited by the smallest array dimension, no element will be processed twice.
Scalar
Required. Any numeric expression giving the scalar quantity used in the array computation.
OpCode

Required. Any numeric expression giving the operation number to perform as follows (note that A is the array element, and S is Scalar):

OpCode | Operation | OpCode | Operation
0 | A = S (S may be invalid) | 17 | A = XOR(A,S)
1 | A = A + S | 18* | A = Pow(S,A)
2 | A = A - S | 19* | A = Exp(S*A)
3 | A = S - A | 20* | A = S * Log(A)
4 | A = A * S | 21* | A = S * Ln(A)
5 | A = A / S | 22* | A = Sin(S * A)
6 | A = S / A | 23* | A = Cos(S*A)
7 | A = A % S | 24* | A = Tan (S*A)
8 | A = Min(A,S) | 25* | A = S * ASin(A)
9 | A = Max(A,S) | 26* | A = S * ACos(A)
10 | A = A < S | 27* | A = S * ATan(A)
11 | A = A <= S | 28* | A = S * Sqrt(A)
12 | A = A==S | 29 | A = S * Abs(A)
13 | A = A >= S | 30 | A = (Index of A) + S
14 | A = A > S | 31 | A = (Index of A) * S
15 | A = AND(A,S) | 32* | A = S * Round (A)
16 | A = OR(A,S) | 33 | Valid(A) != Valid(S) || PickValid(A != S, 0)
MaskElement
Optional. The starting element in an array of TRUE and FALSE values, specifying which elements in array, A will be operated upon. The ArrayOp function will only apply to element A[i] if Mask[starting element + i] is a valid TRUE.
Comments:

The ArrayOp1 statement is useful for large amounts of repetitive computation. While this can be done by executing a script repeatedly using WhileLoop, this ArrayOp1 statement is much faster. Complex computations may be broken down into a series of simple steps and handled by multiple ArrayOp1 and ArrayOp2 statements. If text arrays are used, each text value will be converted to a number before the numerical operations are performed. The resulting array is converted back to text.

All OpCodes support 64-bit integer and double precision floating point calculations *except for OpCodes 18 to 28 and Opcode 32. These operations only perform double precision floating point calculations.*

Mode 33 will compare for differences. It does a more thorough comparison than a simple A != B.

For a multi-dimensional array such as A[X][Y], only the right-most dimension is processed. ([Y] in this example.) You must resort to loops to process the other array dimensions.

Examples:

  If Watch(1);
  [
    SomeArray = New(10)                 { create an array };
    ArrayOp1(SomeArray[0], ArraySize(SomeArray), 0, 0 { Set all elements to zero });
  ]
  If 1 Main;
  [
    ArrayOp1(pumpTrend[10] { Starting element },
             50 { Number of elements to use },
             x + y { Number to use in computation },
             0 { Assign result to the element });
    ArrayOp1(sequentNums[0] { Starting element (beginning) },
             10 { Number of elements to use },
             1 { Number to use in computation },
             30 { Assign sequential numbers });
    ArrayOp1(evenNums[0] { Starting element (beginning) },
             101 { Number of elements to use },
             2 { Number to use in computation },
             31 { Assign multiples of number });
  ]

In this example, the first statement sets elements 10 through 59 of pumpTrend to the result of x + y, the second statement sets elements 0 through 9 of sequentNums to the numbers 1 through 10, and the third statement sets elements 0 through 100 of evenNums to the even numbers from 0 to 200.


ArrayOp2

(Engine-Level Function)

Description: | Performs a mathematical operation on an array with respect to another array.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Array
Related to: | ArrayOp1 | ArraySize | FFT| Array Functions | WhileLoop
Format: | ArrayOp2(DestinationElement, SourceElement, N, OpCode[, MaskElement])
Parameters: |
DestinationElement
Required. Any array element giving the starting point for the array operation in the destination array.
The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
SourceElement
Required. Any array element giving the starting point for the array operation in the source array.
The subscript for the array may be any numeric expression.
N
Required. Any numeric expression giving the number of array elements to compute. N will be limited to the minimum of (N, Source length, Destination length).
If the starting point given by the first parameter is not the first element, and therefore N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at the first element. Because N is automatically limited by the smallest array dimension, no element will be processed twice.
OpCode

Required. Any numeric expression giving the operation number to perform as follows (note that A is an element of Array1 and B is an element of Array2):

OpCode | Operation | OpCode | Operation
0 | A = B | 17 | A = XOR(A,B)
1 | A = A + B | 18* | A = Pow(B,A)
2 | A = A - B | 19* | A = Exp(B*A)
3 | A = B - A | 20* | A = B * Log(A)
4 | A = A * B | 21* | A = B * Ln(A)
5 | A = A / B | 22* | A = Sin(B * A)
6 | A = B / A | 23* | A = Cos(B * A)
7 | A = A % B | 24* | A = Tan (B * A)
8 | A = Min(A,B) | 25* | A = B * ASin(A)
9 | A = Max(A,B) | 26* | A = B * ACos(A)
10 | A = A < B | 27* | A = B * ATan(A)
11 | A = A <= B | 28* | A = B * Sqrt(A)
12 | A = A==B | 29 | A = B * Abs(A)
13 | A = A >= B | 30 | A = (Index of A) + B
14 | A = A > B | 31 | A = (Index of A) * B
15 | A = AND (A,B) | 32* | A = B * Round(A)
16 | A = OR(A,B) | 33 | Valid(A) != Valid(B) || PickValid(A != B, 0)
MaskElement

Optional. The starting element in an array of TRUE and FALSE values, specifying which elements in array, A will be operated upon. The ArrayOp function will only apply to element A[i] if Mask[starting element + i] is a valid TRUE.

Comments:

The ArrayOp2 statement is useful for large amounts of repetitive computation. While this can be done by executing a script repeatedly using WhileLoop, the ArrayOp2 statement is much faster. Complex computations may be broken down into a series of simple steps and handled by multiple ArrayOp1 and ArrayOp2 statements. If text arrays are used, each text value will be converted to a number before the numerical operations are performed. The resulting array is converted back to text.

All OpCodes support 64-bit integer and double precision floating point calculations *except for OpCodes 18 to 28 and Opcode 32. These operations only perform double precision floating point calculations.*

Mode 33 will compare for differences. It does a more thorough comparison than a simple A != B.

For a multi-dimensional array such as A[X][Y], only the right-most dimension is processed. ([Y] in this example.) You must resort to loops to process the other array dimensions.

Example:

  If 1 Main;
  [
    Destination = New(ArraySize(Source));
    ArrayOp2(Destination[0], Source[0], ArraySize(Source), 0 {copy});
  ]

This example creates a copy of the array, Source.


ArraySize

(Engine-Level Function)

Description: | Returns the number of elements in an array dimension.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array
Related to: | ArrayDimensions | ArrayStart | Array Functions
Format: | ArraySize(Array[, Dimension])
Parameters: |
Array
Required. Any array variable.
Dimension
Optional. Any numeric expression that gives the array dimension to measure starting at 0 (the left-most dimension in a multi-dimensional array). Defaults to zero.
Comments: If Array is a variable rather than an array, return value will be invalid.
This function is useful for writing intelligent parameterized modules. The module can determine how many elements there are in an array that is passed to it.

Example 1:

  MyArray = new[10];
  ...
  Size = ArraySize(MyArray);

In this example, Size will receive the value 10.

Example 2:

[
  A;
  X;
  Y;
  Z;
]
Init[
  If 1 Main;
  [
    A = New(2,3);
    ArrayOp1(A[0][0], 3, 0, 0);
    ArrayOp1(A[1][0], 3, 0, 0);
  ]
]
Main [
  X = ArraySize(A)
  Y = ArraySize(A,0);
  Z = ArraySize(A,1);
]

In this example, A will be as follows:

X will be 2

Y will be 2

Z will be 3


ArrayStart

(Engine-Level Function)

Description: | Returns the index of the first element in an array dimension.
Returns: | Numeric
Usage: | Script or steady state.
Related to: | ArrayDimensions | ArraySize| Array Functions
Function Groups: | Array
Format: | ArrayStart(Array, Dimension)
Parameters: |
Array
Required. Any array variable.
Dimension
Required. Any numeric expression that gives the array dimension to examine.
Comments:

When creating arrays, it is recommended to always start all dimensions at 0. which is the default, and is how all arrays produced by VTScada APIs are constructed. You will not normally need to use this function.

If dealing with code where you cannot be sure of that, the ArrayStart can help you discover the non-standard starting index.


ArrayToBuff

(Engine-Level Function)

Description: | Returns a buffer containing the numeric data from an array.
Returns: | Numeric Buffer
Usage: | Script or steady state.
Related to: | ArrayStart | ArraySize | BuffRead | BuffToArray | BuffToParm | BuffToPointer | BuffWrite | GetByte | MakeBuff | ParmToBuff | PointerToBuff | SetByte| Array Functions
Function Groups: | Array, String and Buffer.
Format: | ArrayToBuff(ArrayElem, N, Option, Size, Skip [,BadData])
Parameters: |
ArrayElem
Required. Any array element giving the starting point for the array conversion. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
Note: The array must contain numeric data only.
N
Required. Any numeric expression giving the number of array elements to convert starting at the element given by the first parameter. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.

Option

Required. Any numeric expression that specifies the format of the buffer write, using the following table of formats:
Note: For Options 7 and 9, the data is written as appropriate binary format.

(See: Bitwise Parameters & Operations)

Option | Buffer Format
0 | Unsigned binary (low byte first)
1 | Signed binary (low byte first)
2 | BCD (binary coded decimal - low byte first)
3 | ASCII octal (high byte first)See comment: *1*
4 | ASCII decimal (high byte first)See comment: *2*
5 | ASCII hex (high byte first)See comment: *1*
6 | ASCII floating point (high byte first)
7 | IEEE float/double (low byte first)
8 | <obsolete>
9 | Allen-Bradley PLC/3 floating point
10 | VAX single precision floating point

For Option 0, ArrayToBuff takes the signed bit-equivalent 64-bit integers as inputs. This only matters for integers larger than the largest 64-bit signed integer.

Size

Required. Any numeric expression giving the size that each element should consume in the output buffer, (not the size of the input). It has a different meaning for each option as follows:

Size | Size Meaning | Size Range
Binary types | Number of bits | The following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64
BCD | Number of 4-bit digits | 1 - 16 digits
ASCII types | Number of bytes | 1 - 64 bytes
Float types | Precision | 1 for single precision, 2 for double precision.

Skip

Required. Any numeric expression giving the number of buffer bits/digits/bytes to skip after writing each non-floating point element. In binary modes, the following values are supported: 8, 16, 32, and 64. For floating point types, this parameter must be set to 0.

BadData

Optional. A parameter that designates how invalid data is to be handled, according to the following table. Defaults to 0 if missing or invalid.

BadData | Invalid Data Type
0 | Output to buffer as valid 0s
1 | Causes buffer to be invalid
2 | Output to buffer as valid 0s
Comments:

This function may only be used with arrays containing numeric data. It is useful for writing I/O drivers and saving arrays of data in RAM efficiently.

In binary modes, for the Size parameter, the following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64. For the Skip parameter, the following values are supported: 8, 16, 32, and 64.

Size and Skip values not in those ranges will only work if their combined value is a multiple of 8. For instance, a Size of 12 and a Skip of 4 will work. A Size of 48 and a Skip of 0 will work. When Skip + Size is not a multiple of 8, the behavior of this function is undefined.

If your values are of Size 1 (i.e. a single bit), use unsigned mode. A Size of 1 is not supported for signed values.

Option 0 - 5 will write out values as 64-bit integers when the Size parameter is large enough to support a 64-bit value. Otherwise, they will be written as 32-bit values.

Format Type | Minimum Size for 64-bit Value
Binary | Greater than 32 bits
BCD | Greater than 8 digits
Octal | Greater than 11 digits
Hex | Greater than 8 digits.

If the size is large enough to suppoer a 64-bit output but 64 bits are not needed for the value (the value is less than the largest 64-bit integer) padding will be used to make up the difference. Decimal value interpretation is not affected by the size parameter.

Example 1:

In the following example, assume that array x is a one-dimensional array containing the values 4.5, invalid, and 200:

  If ! Valid(buff);
  [
    buff = ArrayToBuff(x[0] { Starting element },
                      3 { Number of elements to process  },
                      7  { Type - IEEE floating point },
                      1  { Single precision },
                      0  { Skip is ignored },
                      2  { Use 0 for each invalid value });
    BuffRead(buff   { Buffer to read },
             0 { Starting offset },
             "%3b%3b%3b" { Type IEEE floating point binary },
             a1, a2, a3 { Variables to hold the values });
  ]

This code produces a formatted buffer called buff that holds 3 float values (written in binary format), each corresponding to an element in the array. The second value in the array is invalid - in the buffer, it will be a valid 0. The values of a1, a2 and a3 then will be 4.5, 0 and 200 respectively.

Note 1: For ASCII octal and hex values, negative numbers are output as 32-bit, 2's complement values and hence need a size sufficient to accommodate that. (For example, 8 characters for hex.)

Note 2: For ASCII decimal values, undefined results will be returned when used with negative values

Example 2:

    ArrayOp1(Data[0], N, 0xFFFF, 15);
    Buff = ArrayToBuff(Data[0], N, 5, 4, 0);

If Data originally contains 16 bit signed integers, it will output them as 4-character ASCII hex representation of those signed values. Note that the contents of Data are modified by the first line such that they have been converted to 16 bit unsigned integers with the same hex representation, so if the original Data array is needed, this operation should be done with a copy.

Note: If Data contains any values outside the range of a 16 bit signed integer, it will write out the least significant 16 bits of those numbers. Therefore, this approach does not detect values out of the 16 bit signed integer range.


ArrayToDictionary

(System Library)

Description: | Returns a dictionary if given an array of key names and a matching array of values.
Returns: | Dictionary
Usage: | Script Only.
Function Groups: | Array, Dictionary
Related to: | Dictionary
Format: | System.ArrayToDictionary(KeyArray, Values[, CaseSensitive])
Parameters: |
KeyArray
A one-dimensional array of key names for the dictionary.
Values
A single value or a one-dimensional array of values matching the names in KeyArray.
CaseInsensitive
Optional Boolean. Set TRUE for a case sensitive dictionary. Defaults to TRUE.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Beware of the following edge cases:

  1. Behavior may be undefined if the same key is added twice.

For example, with the default setting (CaseInsensitive==FALSE), ArrayToDictionary(MakeArray("A", "a"), MakeArray(1, 2)) gives Dictionary(“A”:2). The later value overwrites the earlier value.

  2. Assigning certain special characters may break the whole dictionary.

For example, ArrayToDictionary(MakeArray("A", "a", “”), MakeArray(1, 2, 3)) returns a numeric value 3. A len(0) string is taken as Invalid, and is not allowed as key. As a result, the returned address is the dictionary itself instead of the dictionary[key], and the value is then stored in the dictionary itself. The Value that should be assigned to dictionary[key] is then assigned to the dictionary itself (in our example, it’s 3).

Dict[""] has the same behavior as RootValue(Dict). ArrayToDictionary should detect a "" key and either fail entirely or leave out that item, and the behavior should be documented.

Examples:

  D = System.ArrayToDictionary(MakeArray("a", "b"), TRUE)

is the same as

  D = Dictionary();
  D["a"] = TRUE;
  D["b"] = TRUE;

  D = ArrayToDictionary(MakeArray("a", "b"), MakeArray(Invalid, 123))

is the same as

  D = Dictionary()
  D["a"] = Invalid;
  D["b"] = 123;


ASin

(Engine-Level Function)

Description: | Returns the trigonometric arc sine in radians.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Trigonometric Math
Related to: | ACos | ATan | Cos | Sin | Tan
Format: | ASin(X)
Parameters: |
X
Required. Any numeric expression in the range -1 to +1.
Comments:

The returned angle is in radians. To convert an angle from radians to degrees, divide by \pi/ 180 or (approximately) 0.0174533.

(\pi is a defined constant in VTScada.)

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

  radAngle = ASin(1);
  degAngle = radAngle / \pi / 180;

The value of degAngle will be 90.


ATan

(Engine-Level Function)

Description: | Returns the trigonometric arc tangent in radians.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Trigonometric Math
Related to: | ACos | ASin | Cos | Sin | Tan
Format: | ATan(X)
Parameters: |
X
Required. Any numeric expression.
Comments:

The returned angle is in radians. To convert an angle from radians to degrees, divide by \Pi / 180 or (approximately) 0.0174533.

(\Pi is a defined constant in VTScada.)

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

  RadAngle = ATan(1);
  DegAngle = RadAngle / \Pi / 180;

The value of DegAngle will be 45.


AudioFileLength

(System Library)

Description: | Returns the length of a RIFF format Wave file in seconds.
Returns: | Numeric
Usage: | Script only.
Related to: |
Function Groups: | Speech and Sound
Format: | System.AudioFileLength(Filename)
Parameters: |
Filename
Required. Any expression for the full name of a .wav file for which you want to find the audio play length.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Returns invalid if the file does not exist, or if the length cannot be determined.

Example:

  PlayingTime = System.AudioFileLength("AlarmMessage.wav");


Authenticate

Security Manager Module

Description | Authenticates the UserName, Password and Namespace of a user.
Returns | Boolean
Usage | Script Only.
Function Groups: | Security
Related to: | AlternateLogoff | AlternateLogon | LogOff | QuietLogon | UserCredChange | UserLogonDialog
Format | \SecurityManager.Authenticate(UserName, Password [,Namespace, Privilege, Device, DontLog]);
Parameters |
UserName
The username with which to authenticate.
Password
The password to validate against the given UserName.
Namespace
Optional. The namespace of the user. Defaults to none.
Privilege
Optional. A privilege that the account must pass a SecurityCheck with. Defaults to none.
Device
Optional. Name of the device that is making the request. Defaults to none. Only used for security log messages.
DontLog
Optional. A Boolean. If TRUE, the result of the Authenticate request will not be logged in the security event log. Defaults to FALSE.
PtrAccountID
Optional. A pointer to a variable that the AccountID of the user will be stored in.
Comments

If the authentication fails, a failure event is recorded in the security event log and FALSE is returned.

If the authentication succeeds, TRUE is returned and the AccountID of the user is written into the variable addressed by the PtrAccountID parameter.

If Privilege is valid, the Privilege is used in a SecurityCheck and the result of the SecurityCheck is returned.


AValid

(Engine-Level Function)

Description: | Returns the number of valid elements in an array sub-range.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array.
Related to: | AMax | AMin | ArrayOp1 | ArrayOp2 | FiltHigh | FiltLow | FitOffset | FitSlope | Mean | SDev | Sum| Valid | Variance | Array Functions
Threaded: | No.
Format: | AValid(ArrayElem, N)
Parameters: |
ArrayElem
Required. An array element. The subscript(s) for the array may be any numeric expression and specify the starting point for the array search.
If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any positive numeric expression giving the number of array elements to use, starting at the element given by the first parameter. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Comments: AValid is not made invalid by invalid array entries. This function is useful in conjunction with the statistical array functions.

Example:

  numValid = AValid(data[0] { Starting element },
                    100 { Number of elements to search });

This example finds the number of array elements with valid values, by examining elements 0 to 99.


B Functions

The sections that follow identify all VTScada functions beginning with "B".


Ball

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draws a filled circle on the screen.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Circle | Ellipse | GUIEllipse
Format: | Ball(X, Y, Radius, Foreground, Pattern, Background)
Parameters:: |
X
Required. Any numeric expression giving the X coordinate of the center of the ball on the screen.
Y
Required. Any numeric expression giving the Y coordinate of the center of the ball on the screen.
Radius
Required. Any numeric expression giving the radius of the ball specified in units of X screen coordinates.
Foreground
Required. Any numeric expression giving the foreground VTScada Color Palette of the ball.
Pattern
Required. Any numeric expression giving the hatch pattern to use to fill the ball. The valid hatch style numbers are from 1 to 25 inclusive. A Pattern of 1 is a solid ball (for other patterns, please refer to Fill Patterns).
Background
Required. Any numeric expression giving the background VTScada Color Palette for the hatch pattern used to fill the ball.
This value is only significant if the Pattern parameter is not equal to 1 (solid).

Comments:

This statement has been superseded by the GUIEllipse function and is maintained for backwards compatibility only.
As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.


Bar

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draws a filled bar on the screen.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Box | GUIRectangle | ZBox | Scale
Format: | Bar(X1, Y1, X2, Y2, Foreground, Pattern, Background)
Parameters: |
X1
Required. Any numeric expression giving the X coordinate one side of the bar on the screen (either left or right).
Y1
Required. Any numeric expression giving the Y coordinate of either the top or bottom of the bar on the screen.
X2
Required. Any numeric expression giving the X coordinate of the side of the bar opposite to X1 on the screen (either left or right).
Y2
Required. Any numeric expression giving the Y coordinate of either the top or bottom of the bar, whichever is the opposite to Y1.
Foreground
Required. Any numeric expression giving the foreground VTScada Color Palette of the bar.
Pattern
Required. Any numeric expression giving the hatch pattern to use to fill the bar. The valid hatch style numbers are from 1 to 25 inclusive. A Pattern of 1 is a solid bar. For valid pattern numbers, please refer to Fill Patterns).
Background
Required. Any numeric expression giving the background color for the hatch pattern used to fill the bar. This value is only significant if the Pattern parameter is not equal to 1 (solid).

Comments

This statement has been superseded by the GUIRectangle and ZBar statements, and is maintained for backwards compatibility only.

As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.

It is recommended that you use bars without hatch patterns for animation, as solid bars are drawn faster.


Base64Decode

(System Library)

Description: | Performs a Base64 decode of a buffer. If neither of the optional parameters are present, this function is treated as a wrapper for Base64Decoder.
Returns: | Buffer
Usage: | Script Only.
Function Groups: | Encryption
Related to: | Base64Decoder | Base64Encode | Hash
Format: | \System.Base64Decode(Buffer[, Offset, isMIME, URLSafe]);
Parameters: |
Buffer
Required. The encoded value.
Offset
Optional numeric. Offset into the buffer, at which to start decoding. Defaults to zero if invalid.
isMIME
Optional Boolean. If TRUE, relaxes the constraint regarding characters that aren't in the base64 alphabet, per RFC2045. Defaults to FALSE if invalid.
URLSafe
Optional Boolean. If TRUE, an alphabet that is URL and filename safe will be used.
Comments:

This function complies with IETF RFC4648 and RFC2045 .

Returns Invalid if the input buffer is invalid, or if IsMime is TRUE and the buffer contains invalid characters as per RFC2045. Whitespace characters will be ignored rather than cause failure.

Example:

  If Valid(EncodedValue);
  [
    DecodedValue = \System.Base64Decode(EncodedValue);
    EncodedValue = Invalid;
  ]


Base64Decoder

(Engine-Level Function)

Description: | Performs a Base64 decode of a buffer.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | Encryption
Related to: | Base64Encoder | Hash
Format: | Base64Decoder(Buffer);
Parameters: |
Buffer
Required. The encoded value.
Comments:

This function complies with IETF RFC4648 and RFC2045 .

Returns Invalid if the input buffer is invalid. Whitespace characters will be ignored rather than cause failure.

Example:

  If Valid(EncodedValue);
  [
    DecodedValue = Base64Decoder(EncodedValue);
    EncodedValue = Invalid;
  ]


Base64Encode

(System Library)

Description: | Performs a Base64 encode of a buffer. If the optional parameter is not present, this function is treated as a wrapper for Base64Encoder.
Returns: | Text
Usage: | Script Only.
Function Groups: | Encryption
Related to: | Base64Decode | Hash | Base64Encoder
Format: | System.Base64Encode(Buffer[, URLSafe]);
Parameters: |
Buffer
Required. The information to be encoded.
URLSafe
Optional Boolean. If TRUE, an alphabet that is URL and filename safe will be used.
Comments: none.

Example:

 If Valid(SomeBuffer);
  [
    EncodedResult = System.Base64Encode(SomeBuffer);
    SomeBuffer = Invalid;
  ]


Base64Encoder

(Engine-Level Function)

Description: | Performs a Base64 encode of a buffer.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | Encryption
Related to: | Base64Encode | Base64Decoder| Hash
Format: | Base64Encoder(Buffer);
Parameters: |
Buffer
Required. The information to be encoded.
Comments:

Whitespace characters will be ignored rather than cause failure.

Examples:

 If Valid(SomeBuffer);
  [
    EncodedResult = Base64Encoder(SomeBuffer);
    SomeBuffer = Invalid;
  ]


Beep

(Engine-Level Function)

Description: | Causes a tone to sound on the computer's internal speaker.
Returns: | Nothing
Usage | Script or steady state.
Function Groups: | Speech and Sound
Related to: | Sound
Format: | Beep(Frequency)
Parameters:: |
Frequency
Required. Any numeric expression giving the frequency to be output to the speaker.

Comments:

The minimum frequency is 1190000 / 65535 ~= 18.16. If the frequency is set below the minimum frequency or invalid, the speaker will turn off.

Within an Anywhere Client session, this function does nothing.

Example:

  If MatchKeys(2, "on");
  [
    Beep(2000) { A 2kHz tone };
  ]
  If MatchKeys(2, "off");
  [
    Beep(0) { No tone };
  ]

The example above results in a 2000 Hz sustained beep sounding when the user types "on" until the user types "off".


Bevel

(System Library)

Description: | Draws a titled beveled box.
Returns: | Nothing
Usage | Steady State only.
Function Groups: | Graphics
Related to: | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | TextBox | ToolBar | VScrollbar
Format: | System.Bevel(X1,Y1, X2, Y2 [,Title, AlignTitle, TitleBGColor, TitleFGColor, BevelColor])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the bevel. The smaller of X1 or X2 will always be the left side.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the bevel. The smaller of Y1 or Y2 will always be the top edge.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the bevel opposite to X1.
Y2
Any numeric expression giving the Y coordinate on the screen of the top or bottom of the bevel, whichever is the opposite to Y1.
Title
Optional. Any text expression to be used as a title embedded in the bevel. The default value is a null text string.
AlignTitle
Optional. Any logical expression. If true (non-0) the top of the title will be aligned with the top of the defined area, if false (0) the bevel will be aligned with the top of the area and the title will protrude past the top.
The default value is true.
TitleBGColor

Optional. Any numeric expression giving the index of the VTScada Color Palette to display under the title.

Note that this will affect the area immediately under the title (i.e. it does not affect the area inside the bevel). No default value is provided.

TitleFGColor
Optional. Foreground (text) color for the title.
BevelColor
Optional. Color of the bevel line.

Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Example:

  System.Bevel(10, 10, 110, 40, \GetPhrase("DescriptionLabel");


BinaryToIP

(Function Library)

Description: | Converts an IP address from binary notation to decimal.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | String
Related to: | BinIP2Text
Format: | \FunctionLib.BinaryToIP(Value)
Parameters: |
Value
An internet protocol (IP) address, written as a four-byte binary buffer.
Comments:

This module is a member of the Function Library, and must therefore be prefaced by \FunctionLib as shown in the "Format" section.

Note that each group in the IP address output of BinaryToIP is padded with zeroes.

Example:

  \FunctionLib.BinaryToIP(Concat(MakeBuff(1, 204), MakeBuff(1, 132), MakeBuff(1, 40), MakeBuff(1, 155)))

Will return "204.132.040.155"


BinIP2Text

Deprecated. Maintained for backward compatibility. Do not use in new code.

(RPC Manager Library)

Description: | Returns a text representation of a specified binary IP in a printable format.
Returns: | Text
Usage: | Script Only.
Function Groups: | Network, String and Buffer
Related to: | TextIP2Bin
Format: | \RPCManager\BinIP2Text(BinIP)
Parameters: |
BinIP
Required. The Binary representation of the IP to be converted to a printable format.

Comments:

This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

Subroutine call.


Bit

(Engine-Level Function)

Description: | Returns the on/off status of a bit in a number.
Returns: | Boolean
Usage | Script or steady state.
Function Groups: | Bitwise Operation
Related to: | And | SetBit | Ones
Format: | Bit(Value, BitNumber)
Parameters: |
Value
Required. Any numeric expression giving the number containing the bit to be tested.
BitNumber

Required. Any numeric expression in the range of 0 to 31 giving the bit number to be tested within the number specified by the Value parameter.

Bit 0 is the least significant bit. Any value outside the range of 0 to 31 will result in a false result for Bit.

Comments:

Bit returns true (1) if the indicated bit is 1, and false (0) if the indicated bit is 0.

(See: Bitwise Parameters & Operations)

Example:

  MotorFault = Bit(MotorStatus, 0);

The example sets motorFault to TRUE if the right-most (least-significant) bit of motorStatus is set. to 1


BitmapInfo

(Engine-Level Function)

Description: | Returns information about an image.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | Crop | MakeBitmap
Format: | BitmapInfo(BitmapVal, Attribute)
Parameters: |
BitmapVal
Required. Any expression that returns an image value such as MakeBitmap()
Attribute
Required. Any numeric expression that identifies the information to be returned by this function, as per the following table:
Attribute | Information returned
0 | Bitmap width in pixels
1 | Bitmap height in pixels

Comments:

BitmapInfo can be used to automate a module that displays images in response to a change in the image.

Example:

  pumpWidth = BitmapInfo(pumpBitmap, 0);

The example displayed above sets pumpWidth to the width of the image value pumpBitmap.


Blend

(System Library)

Description: | Returns an aRGB color value that is a given percentage between two specified colors.
Returns: | aRGB color string
Usage: | Steady State only.
Function Groups: | Color
Related to: |
Format: | System.ColorTools.Blend(Color1, Color2, Ratio)
Parameters: |

Color1

Required. Any text expression giving the aRGB value of the first color.

Color2

Required. Any text expression giving the aRGB value of the second color.
Ratio
Optional. Any numeric expression for a value between 0 and 1. The larger the Ratio, the closer the resulting color will be to Color1. Default = 0.5
Comments:

Returns an aRGB value for a color that is a blend of Color1 and Color2. By default, the values will be averaged, but any ratio between the two colors can be specified. Blend is especially useful for creating accent colors in dialog boxes.

Example:

  LineColor = PickValid(\System.ColorTools.Blend(TextColor, BGColor, 0.1), TextColor);

Sets the color of an accent line to be similar to a preset background color but with 10% of the preset text color.


BlockDecrypt

(System Library)

Description: | Decrypts a value that was encrypted using the BlockEncrypt function.
Returns: | String
Usage: | Script Only.
Function Groups: | Encryption
Related to: | BlockEncrypt |Decrypt | Hash
Format: | System.BlockDecrypt(CipherValue, Key);
Parameters: |
CipherValue
Required. The string that was encrypted using the BlockEncrypt function
Key
Required string. The key value that was used for encryption.
Comments:

Examples:

  DecodedResult = System.BlockDecrypt(SomeEncryptedValue, SameKey);


BlockEncrypt

(System Library)

Description: | Uses encryption to encode a VTScada value into a Base64 string.
Returns: | String
Usage: | Script Only.
Function Groups: | Encryption
Related to: | BlockDecrypt | Encode | Base64Encode | Hash
Format: | System.BlockEncrypt(PlainValue, Key[, Salt]);
Parameters: |
PlainValue
Required. The information to be encoded.
Key
Required string. The key value to be used for encryption.
Salt
Optional text. Defaults to a random GUID, but can be specified by the caller if required. Best practice is to use a per-record salt
Comments:

The resulting string will be different each time it is encoded, even if the same key is used.

Examples:

  EncodedResult = System.BlockEncrypt(SomeValue, SomeKey);


BlockWrite

(Engine-Level Function)

Description: | Writes a block of data to a stream.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | FWrite | PipeStream | SWrite
Format: | BlockWrite(DestinationStream, SourceData [, ByteLimit ])
Parameters: |
DestinationStream
Required. Any expression that returns a stream value.
SourceData
Required. Any text or stream expression that specifies the block of data to write to Stream.
ByteLimit
Optional Any numeric expression giving the maximum number of bytes copied from a stream.

Comments:

BlockWrite is more efficient than writing a block of data character-by-character. It is especially useful for named pipe streams when the intent is to send a block of bytes as a single message, rather than as a series of single-character messages (which is the result of using SWrite with the "%s" format option). If the second parameter is a stream value, the entire stream will be written to the first stream value.

Returns TRUE on success and FALSE on failure.

Example:

  If 1 NextState;
  [
    Stream = BuffStream("") { Open the first stream };
    SWrite(Stream { Write to first stream },
          "%s %d %s" { Format for the data },
          "Test number: ", TestNum, "is complete" { The data to write });
    File = FileStream("TestStatus" { Open second stream });
    Seek(Stream, 0, 0 { Rewind the stream });
    BlockWrite(File, Stream { Write from stream to file });
    CloseStream(Stream);
  ]

The BlockWrite function can be used to copy files as shown in the following example:

  BlockWrite(FileStream ("File2.ext"), FileStream ("File1.ext"));

When used in a manner similar to the example shown above, the BlockWrite statement is particularly useful in copying files (the DOS equivalent of "copy file1.ext file2.ext"), except in cases where File2 is larger than File1. In cases where File2 is larger than File1, the result (File2) will be its original size. All the data from File1 will overwrite the beginning portion of the data in File2, with the remainder of the data originally contained in File2 remaining untouched.

If you require an exact copy of File1 (rather than the File1 data appended with the remaining File2 data), you can use an FWrite command to delete the destination file before calling BlockWrite.


Boolean

(System Library)

Description: | Takes a valid Boolean test and returns the numeric equivalent.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Logic Control
Related to: | Boolean Logic Operators | Case | Cond | If | IfElse| IfOne | IfThen | PickValid
Format: | System.Boolean(Variable)
Parameters: |
Variable
Required. The variable whose value is to be converted.

Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The return value from this module is 1 if Variable contains a valid Boolean true of any case ("true", "t", "yes", "y", "on") and 0 otherwise.

Example:

  Var = PickValid(\System.Boolean(Var), 0);


Box

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draws an empty box on the screen.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Box | GUIRectangle | ZBox | ZBar
Format: | Box(X1, Y1, X2, Y2, Style, Width, Color)
Parameters: |
X
Required. Any numeric expression giving the X coordinate of one side of the box on the screen. The smaller of X1 and X2 will always be the left side.
Y1
Required. Any numeric expression giving the Y coordinate of either the top or bottom of the box on the screen. The smaller of Y1 and Y2 will always be the top edge.
X2
Required. Any numeric expression giving the X coordinate of the side of the box opposite to X1 on the screen (either left or right)..
Y2
Required. Any numeric expression giving the Y coordinate of either the top or bottom of the box, whichever is the opposite to Y1.
Style
Required. Any numeric expression giving the line style for the box wall. Valid line styles are from 1 to 10 inclusive. A line style of 1 is a solid line.
Width
Required. Any numeric expression giving the width of the box wall in units of X screen coordinates. The width is always rounded to result in an odd number of pixels on the screen. The minimum width displayed will be 1 pixel.
Color
Required. Any numeric expression giving the VTScada Color Palette of the box.

Comments:

Box has been superseded by the GUIRectangle and ZBox statements, and is maintained for backwards compatibility only.

As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.


Brush

(Engine-Level Function)

Description: | Returns a brush value.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Color, Graphics
Related to: | Pen | GUIPie | GUIEllipse
Format: | Brush(Foreground, Background, Pattern)
Parameters: |
Foreground

Required. Any numeric expression giving the foreground color of the brush pattern. Any of the following may be used:

  • a palette index color
  • a system color
  • -1 (transparent)
  • an RGB string in the format, "<RRGGBB>"
Background
Required. Any numeric expression giving the background color of the brush pattern. If there is a solid pattern, this parameter is ignored.

Any of the following may be used:

  • a palette index color
  • a system color
  • -1 (transparent)
  • an RGB string in the format, "<RRGGBB>"
Pattern

Required. Any numeric expression giving the hatch Fill Patterns to use.

A 0 is an invisible pattern, and a 1 is a solid pattern. The maximum style value is 25.

Comments:

Brush values are used in layered graphics statements that paint areas (such as GUIPie or GUIEllipse).

This function may not appear in a script.

Example:

  NewStyle = Brush(12 { Red },
                   14 { Yellow },
                   25 { Brick pattern });

The example above creates a brush composed of red bricks outlined in yellow.


Bubble

(Engine-Level Function)

Description: | Starts a new child bubble and launches the given module into a new script thread in that bubble.
Returns: | Bubble handle to the started child bubble.
Usage: | Script Only.
Function Groups: | Bubble and Thread
Related to: | BubbleList | BubbleQueueLength | BubbleReceive | BubbleSend | RunInBubble |
Format: | Bubble(BubbleName, Module [, ImportDictionary, RetainedPath])
Parameters: |
BubbleName

Required text. The name that is to be associated with the bubble as well as the name given to the script thread that is started in the bubble.

Displayed in the user interface of debugging tools.

ModuleOrObject
Required object. This is the root module that is loaded and launched into the bubble. It is always loaded and launched with no parent or caller.
ImportDictionary

Optional dictionary. May be used to specify a subset of variables or modules from the ModuleOrObject parameter that will be loaded, launched, or both, into the child bubble rather than loading and launching the entire module. This is of use when you want to share the same code between modules running inside and outside of the child bubble.

When an ImportDictionary is provided, the entire Module is not loaded into the bubble to be run. Instead, a copy of ModuleOrObject is reconstructed in the bubble with none of its states and with only the subset of variables specified in the ImportDictionary. This is then launched in the bubble.

In this situation, the root module is like a library of modules and objects that you want to selectively import into the bubble, with the actual bubble worker module being one of the modules imported.

The keys to the dictionary are the names of variables in ModuleOrObject, and the values can be any one of the following:

  • If the key specifies a variable containing a module or object, then setting the value to FALSE means that the module will be fully loaded into the bubble and placed in the corresponding variable, but it will not be launched.
  • If the key specifies a variable containing a module or object, then setting the value to TRUE means that the module will be fully loaded into the bubble and launched, with the object being placed in the corresponding variable.
  • If the key specifies a variable containing a module or object, then you can set the value to a nested ImportDictionary. A nested ImportDictionary is the same as the top-level one, except that it operates on the module or object specified in the dictionary key. The resulting reconstructed object is placed in the corresponding variable.
  • If the dictionary value is Invalid, then any packable value is imported into the bubble and placed in the corresponding variable. Note that static arrays are converted to dynamic arrays as a part of the import process.

Any local variable in the object or module can be imported, regardless of whether it is protected.

It is typical to have one fully loaded and launched module that will perform the work that the bubble has been created for. The other imported modules and variables would be common code that the bubble worker module uses and which is also used outside the bubble.

Imported variables are populated inside the bubble in the order that they were added to the import dictionary. Therefore, if (for example) an imported and launched module has a Constructor that references another imported module, you will need to add the other module to the import dictionary first so that it is ready to be used when the Constructor runs.

RetainedPath

Optional path to store retained values for all modules loaded in the bubble. By default, the retained path of the imported root module is used.

Caution: If bubble is using retained values, RetainedPath must be unique or the file may get corrupted if accessed inside and outside the bubble.

Comments:

The Bubble function only loads and launches modules into the new bubble. It will often be necessary to provide input data values to the new bubble. These can be sent after the Bubble call using the BubbleSend function.

Modules that are loaded into a child bubble are loaded independently, and therefore do not share "Shared" variables with the copy of the module that exists in the parent object. Bubbles must refrain from setting retained values that could be set in another bubble. They must use SetInstanceName to give their object a unique name before setting any instance variables. At the same time, parent bubbles should refrain from writing to the retained variable using the default instance name in a module that could be loaded inside a child bubble. Otherwise, they risk corrupting the retained value, or loading a partially-written retained value

The bubble will continue to exist for as long as there are objects running within the bubble. After the last object within the bubble in slain and all outstanding related work within the bubble is finished, the bubble will tear itself down. Note that slaying the object that started the bubble will not stop the bubble. The bubble must tear itself down, either on its own or upon receipt of a message from its parent bubble telling it to do so.

The bubble handle returned by this function is not invalidated when the bubble tears itself down. If a parent bubble needs to know when a child bubble is finished, then the child bubble should send the parent bubble a message before terminating. A parent bubble does not need to retrieve that message before the child bubble terminates. This is a reason why the bubble handle is not invalidated when the child bubble finishes, as the parent bubble may still need to retrieve one or more messages via the child bubble handle.

When ImportDictionary is not provided, ModuleOrObject will only be successfully loaded into the bubble if it has no static references to external variables since it is loaded with no parent. When ImportDictionary is provided, any modules that it fully imports (dictionary value TRUE or FALSE) cannot statically reference any external variables that are not also being imported, or else they will fail to load in the bubble. So, if you are importing ModuleA and it contains a reference to ModuleB, you’ll need to import ModuleB. In order to do that, you’ll also need to import all variables that ModuleB references. Hence, even if your bubble only needs to call one external module directly, you may need to import a number of modules and variables in order to be able to use that one module.

Example:

{ A simple single-module bubble: }
<
RunMyProcessInBubble
(
  Input                       { Input to a CPU-intensive process           };
  pResult                     { Result of CPU-intensive process            };
)
[
  MyProcessModule Module;
  BubbleHandle;
]

Init [
  If 1 WaitForResult;
  [
    BubbleHandle = Bubble("MyProcess", \MyProcessModule {use backslash to avoid implicit launch});
     { Send the input data to the bubble. Since MyProcessModule is running in its own bubble,
       it doesn't have direct access to any variables in this module - all data communication
       must be via the BubbleSend function. }
    BubbleSend(BubbleHandle, Input);
  ]
]

WaitForResult [
  If BubbleQueueLength(BubbleHandle) > 0;
  [
    *pResult = BubbleReceive(BubbleHandle);
    Slay();
  ]
]

<
MyProcessModule
[
  ReceivedInput;
  Result;
]

Main [
   { Receive the input data that the parent immediately sends after bubble creation. }
  If BubbleQueueLength() > 0;
  [
     ReceivedInput = BubbleReceive();
    { ... Perform a long CPU-intensive process using ReceivedInput, computing Result ... }

     { Send the parent bubble the result. }
    BubbleSend(Result);
     { This is the only object running within the bubble, so the bubble will tear itself down
       shortly after this Slay. }
    Slay();
  ]
]
{ End of RunMyProcessInBubble\MyProcessModule }
>
{ End of RunMyProcessInBubble }
>

{An example that uses ImportsDictionary, where the bubble is managed by a
 service and wants to use other module/variables in Code: }

MyService
[
  Destructor   Module;
  HelperModule Module;
  BubbleWorker Module;
  Imports;
  BubbleHandle;
]

Init [
  If 1 WaitForResult;
  [
    Imports = Dictionary();
    Imports["CodeLevelHelperModule"] = FALSE     { Module defined in AppRoot.SRC, used by BubbleWorker };
    Imports["MyService"] = Dictionary();
    Imports["MyService"]["HelperModule"] = FALSE { Module used by BubbleWorker };
    Imports["MyService"]["BubbleWorker"] = TRUE;
    BubbleHandle = Bubble("MyServiceBubble", \Code, Imports);
  ]
]

Main [
   { Send/receive messages to/from bubble. }
]

<
Destructor

Main [
  If 1;
  [
    IfThen(Valid(BubbleHandle),
       { Inform the bubble that it must destroy itself. The value we send doesn't
         matter as the only message that the bubble expects on the "DestroyBubble"
         named queue is the self-destruct message. }
      BubbleSend(Invalid, BubbleHandle, "DestroyBubble");
    );
    Return();
  ]
]
{ End of MyService\Destructor }
>

<
BubbleWorker

Main [
   { Send/receive messages to/from parent bubble. The code makes static references
     to CodeLevelHelperModule and HelperModule. }

   { Listen for the parent bubble telling us to self-destruct. }
  If BubbleQueueLength(Invalid, "DestroyBubble) > 0;
  [  {  No need to receive the message. The only message we receive on the
     "DestroyBubble" named queue is the message to destroy the bubble, so the
     message content doesn't matter. }
    Slay(Self, 1 {must slay parent objects to stop bubble});
  ]
]
{ End of MyService\BubbleWorker }
>
{ End of MyService }


BubbleList

(Engine-Level Function)

Description: | Lists the running child bubbles of the current bubble.
Returns: | Array of bubble handles
Usage: | Script Only.
Function Groups: | Bubble and Thread
Related to: | Bubble | BubbleQueueLength | BubbleReceive |BubbleSend | RunInBubble
Format: | BubbleList()
Parameters: | none
Comments:

It is possible for a parent bubble to be holding on to a bubble handle for a child bubble that has since stopped. (Refer to comments within the Bubble function.) That bubble handle will not be included in the set of results returned by BubbleList.


BubbleQueueLength

(Engine-Level Function)

Description: | Reports the length of the queue of messages from the current bubble's parent bubble or one of its children.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Bubble and Thread
Related to: | Bubble | BubbleList | BubbleReceive | BubbleSend | RunInBubble
Format: | BubbleQueueLength([BubbleHandle, QueueName])
Parameters: |
BubbleHandle
Optional bubble handle as returned by the Bubble and BubbleList functions. Specifies the bubble where the message is being received from. If Invalid or not provided, the message is being received from the parent bubble.
QueueName
Optional text. The name of the queue that the message was queued on. If not provided, it defaults to the empty string, “”. Any time you specify a new string, a new queue will be created internally.

Example:

Refer to the example in the Bubble function description.


BubbleReceive

(Engine-Level Function)

Description: | Receives a message from the given bubble.
Returns: | Variable
Usage: | Script Only.
Function Groups: | Bubble and Thread
Related to: | Bubble |BubbleList | BubbleQueueLength | BubbleSend | RunInBubble
Format: | BubbleRecieve([BubbleHandle, QueueName])
Parameters: |
BubbleHandle
Optional bubble handle as returned by the Bubble and BubbleList functions. Specifies the bubble where the message is being received from. If Invalid or not provided, the message is being received from the parent bubble.
QueueName
Optional text. The name of the queue that the message was queued on. If not provided, it defaults to the empty string, “”. Any time you specify a new string, a new queue will be created internally.
Comments:

Messages on a particular queue are received in the order that they were sent.

This function is intended to be used in combination with BubbleQueueLength as follows:

If BubbleQueueLength(ChildBubble, "MyQueueName") > 0;
[
  Message = BubbleReceive(ChildBubble, "MyQueueName");
  { do something with Message }
]

Example:

Refer to the example in the Bubble function description.


BubbleSend

(Engine-Level Function)

Description: | Sends a message to the given bubble.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Bubble and Thread
Related to: | Bubble |BubbleList | BubbleQueueLength | BubbleReceive | RunInBubble
Format: | BubbleSend([Message, BubbleHandle, QueueName])
Parameters: |
Message
Optional. Any packable value (including an array, dictionary, or structure) that will be sent to the destination bubble. If not provided, an Invalid will be sent.
BubbleHandle
Optional bubble handle as returned by the Bubble and BubbleList functions. Specifies the bubble where the message will be sent. If Invalid or not provided, the message will be sent to the parent bubble.
QueueName
Optional text. The name of the queue that the message will be queued on. If not provided, it defaults to the empty string “”. Any time you specify a new string, a new queue will be created internally.
Comments:

Message contents are always deep-copied when they are sent. Therefore, changes to streams and data structures that have already been sent to another bubble will not be reflected in the copy in the other bubble.

Messages on a particular queue will be received in the order that they are sent.

Note that message queues live for the lifetime of a bubble, so it is best not to continually generate and subsequently discard queue names, as that will cause growing memory consumption.

Example:

Refer to the example in the Bubble function description.


BuffOrder

(Engine-Level Function)

Description: | Reverses the order of groups of bytes in a buffer, and returns a new (rearranged) buffer.
Returns: | Buffer
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | BuffRead | BuffWrite | Replace | Reverse | ParmToBuff | BuffToParm
Format: | BuffOrder(Buffer, Offset, Size, Increment, N)
Parameters: |
Buffer
Required. Any text or buffer expression to be reordered.
Offset
Required. Any numeric expression giving the initial position within the buffer for the ordering, starting at 0. Offset must be greater than or equal to 0.
Size
Required. Any numeric expression greater than 0, giving the size of each group of bytes. Bytes within a group will remain in their original order. The portion of the original buffer that will be re-ordered must be evenly divisible into groups of Size.
Increment
Required. Any numeric expression greater than 0, giving the number of groups of Size bytes to be reordered. Re-ordering is done to the Size-groups within Increments, not across Increments.
N
Required. Any numeric expression giving the total number of Increment-groups to reverse.

Comments:

BuffOrder is part of the driver toolkit. The return value is a buffer containing all bytes specified in the Buffer parameter with groups of bytes reversed. Offset + Size * Increment * N must be no greater than the length of Buffer. Returns Invalid if any parameter does not meet its requirements.

BuffOrder is useful for altering buffers for use with the ParmToBuff or BuffToParm functions.

Example:

  Buff1 = BuffOrder("0123456789" { Buffer },
                    0 { Starting offset },
                    1 { Size of group },
                    10 { groups in shuffle },
                    1 { Number of repetitions });

In this example, Buff1 will be equal to "9876543210".

  Buff2 = BuffOrder("0123456789" { Buffer },
                    2 { Starting offset },
                    1 { Size of group },
                    2 { Groups in shuffle },
                    4 { Number of repetitions });

In this example, Buff2 will be equal to "0132547698".


BuffRead

(Engine-Level Function)

Description: | Reads values from a formatted buffer and returns the number of values not read.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | BuffOrder | BuffWrite | FRead | GetByte | SRead | SubStr
Format: | BuffRead( Buffer, Offset, Format, V1, V2, V3, …)
Parameters: |
Buffer
Required. Any text or buffer expression to read.
Offset
Required. Any numeric expression giving the initial buffer position for the read, starting at 0.
Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be read.
This format is similar, but not identical, to the C language format string for the scanf function, whereby each of the % format specifications assigns a value to one of the Vn parameters in the statement in the order in which each appears in the list.
Note that like a standard text string, these format specifiers must also be enclosed by double quotes. If a format specification appears for which there are no remaining V parameters, the format specification value is read and discarded.

For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[*][width]type

Where…

%

Is a mandatory character

*

The optional asterisk causes the read to occur as per the format specification, but suppresses any assignment to the Vn parameters.

width

Width is optional, specifying the maximum number of characters to read.

type

The specifications for type are listed in the following table:

Format strings are case insensitive. Additionally, specifying a character for a type that is not in this list results in all the characters following the % up to that point to be read exactly as they appear in the Format string and discarded.

Type | Meaning
Nb | Binary format, where n is a number indicating the type of value (see below)
c | Single ASCII character (byte)
d | Signed decimal 64-bit integer
e | Signed exponential
f | Signed floating point
g | e or f formats
i | Signed decimal integer
l | Line of characters terminated by a carriage return, line feed, or both
n | Present offset in the buffer
o | Signed octal, 32-bit default*
s | Text string
t | Counted string
u | Unsigned decimal 64-bit integer
x | Signed hex integer using "abcdef", 32-bit default*
znnn | Escape character where nnn is the 3-digit ASCII code

%x and %o will treat values as 32-bit integers by default unless the %ll modifier is used. %llx and %llo will read values in 64-bit.

for %u, when reading an unsigned 64bit integer greater than 9223372036854775807 (the largest signed 64bit integer), the value will be read in as the bit-equivalent signed 64bit integer. (eg. 9223372036854775808 is read in as -9223372036854775808.)

nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.

n value | Type
0 | Byte
1 | Short integer (2 bytes, low byte first)
2 | Long integer (4 bytes, low bytes first)
3 | IEEE single precision float (4 bytes)
4 | <obsolete>
5 | IEEE double precision float (8 bytes)
6 | <obsolete>
7 | Binary unsigned short (2 bytes, low byte first)
8 | Unsigned 32-bit integer
9 | 64-bit FileTime. This reads or writes a 64 bit time value in the Microsoft FileTime format. When reading, the value is converted from the FileTime epoch and units (100 nanosecond intervals since Jan 1, 1601) to the VTS epoch and units (seconds since 1/1/1970) any times earlier than this will result in a value of 0. When writing, the value is converted from the VTS epoch and units to the FileTime epoch and units.

c, ASCII character type: Unlike BuffWrite this type deals with characters in a string; each character being equal to one byte. Unlike the %s option, which reads only up to the first white-space character, the %c option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, a single character is read.

d, Signed decimal integer

e, Signed exponential

f, Signed floating point

g, e or f formats

i, Signed decimal integer type: This option normally reads a decimal integer; however, if a leading "0b" is encountered, the number will be interpreted as binary. If a leading "0" (zero only) is encountered, the number will be interpreted as octal. If a leading "0x" is encountered, the number will be interpreted as hexadecimal. For decimal, values will be read as 64-bit integers, but hex, octal and binary will be treated as 32-bit integers unless the %lli modifier is used, which will cause the %i format to treat hex, octal and binary as 64-bit.

l, Line of characters: This option reads a line of characters terminated by a carriage return, a line feed, or both (in either order). The carriage return and line feed will be discarded, and the next character read will be the first character on the next line. The maximum number of characters read is 2GiB (2^30 bytes) or less if the width option is used.

n, Buffer offset: This option does not read a value, but returns the present offset in Buffer and can be useful in subsequent reads.

o, Unsigned Octal

s, Text string type: Text in the string is read up until a white-space character is encountered, or the specified width has been read, whichever is smaller. Square brackets enclosing a character, group of characters, or a caret and a group of characters used in the format string reads strings not delimited by spaces. This is a substitute for the %s format specification. The input is read up to the first character that does not appear inside the square brackets (note that this is case-sensitive). A dash may be used to specify a range of characters. For example, the following format specifier:

% [A-Fa-f]

will read a string up to the first which is not an A, B, C, D, E, or F both upper and lower case.

t, Counted string type A counted string is encoded as a sequence of UTF-8 characters without a null terminator and preceded by the length in bytes.

The length in bytes is encoded as Int32, i.e. a "%2b". A value of −1 is used to indicate an invalid string, a value of 0 indicates a null ("") string.

Do not apply width or precision modifiers to a "%t" counted string.

The caret symbol ^. If the first character inside the square brackets is a caret ( ^ ), the read progresses up to, but not including, the first character that appears inside the square brackets:

%[^X-Z]

This would read a string up to, but not including, the first X, Y or Z (upper-case only); if the string were terminated by an X, the next character read would be that X. Inside the square brackets, the backslash is used as an escape character - any character following a backslash (such as a caret, dash, or backslash) is taken as that character without special meaning. For example:

%[^X-Z\^]

would behave as described previously, except that the string would now be read up to but not including the first X, Y, Z, or ^.

Because format specifications for the Vn parameters are indicated by a percentage sign, to read (and discard) an actual percentage sign as part of the text string, precede it with a backslash character (i.e. \%). Also, since the backslash character is used in this manner, as well as with special control characters such as line feed, carriage return and form feed, to read and discard a backslash, use two backslash characters (i.e. \\).

x, Hexadecimal characters: the %x option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, it will continue reading all bytes that can be recognized as hexadecimal characters. For example, given the string "…= 3D", %[^=]=%2x would read the hedadecimal value, 3D (decimal value, 61).

znnn, Escape characters: This specifies an escape character that will be thrown away when read, where nnn is a 3-digit number giving the ASCII character code of the escape character. This option is generally used as the sole format specifier that reads an entire string, spaces included, discarding every single occurrence of an escape character, or the first occurrence of every pair of escape characters. For example, if the string to be read looked like:

abXc dXXfghiXXXjXXXXkl mX Xn o

and the format specifier indicated that the ASCII code for 'X' (88) was to be the escape code:

%25z088

then the variable that this was read into would contain:

abc dXfghiXjXXkl m n o

Notice that for each occurrence of X, the character immediately following it is saved, even if it is itself an escape character. Then the next occurrence of the escape character is discarded, with the character following it being saved, regardless of what it is, and so on. The width field specifies the maximum number of bytes to place in the output string; if this number is smaller than the input string (less the offending escape characters), the string will be truncated. If no width is specified, a single character will be read.

Control characters: In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result. Please note that the letters must be lower case.

Code | Meaning
\b | Backspace
\f | Form Feed
\n | Line Feed
\r | Carriage Return
\t | Horizontal Tab
\v | Vertical Tab

In addition to the predefined codes, an alternate form may be used:

\nnn: where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

V1, V2, …
Required. Are the variables to be read in the form described by the Format parameter. Expressions are not allowed. Each of the Vn parameters is read in the order in which each appears in the parameter list. V1 has the format given by the first % sequence in the Format parameter, V2 has the second, and so on.

Comments:

In early versions of VTScada (WEB), there was a numeric leading parameter, N. This should not be included in any new code.

The strings read by this function may be part of an I/O driver (such as a message packet), or entered from the keyboard (such as a command-line-interpreter interface). The return value is optional and is the number of Vn parameters not read, which can be used as an error flag.

Example:

  If ! Valid(WellLevel);
  [
    BuffRead(FileData { Source buffer to read from },
             0 { Starting offset, in characters },
             "%f%d/%d/%d" { Format string },
             WellLevel { First variable - read by %f },
             SampleDay { Second variable - read by %d },
             SampleMonth { Third variable - read by %d },
             SampleYear { Fourth variable - read by %d });
  ]

The example shown above reads a floating point variable and 3 integers. The slash characters "/" must be present in the FileData buffer. If the slash characters "/" are missing, reading will be terminated when one is missed. All variables after that point will be set invalid. If FileData contained:

"12.3 28/09/92"

... WellLevel would be set to 12.3, SampleDay to 28, SampleMonth to 9, and SampleYear to 92. If it is desired to skip a single character, use the "%*c" option (read character and discard).


BuffStream

(Engine-Level Function)

Description: | Returns an in-memory read/write (expanding) buffer stream.
Returns: | Buffer
Usage: | Script Only.
Function Groups: | Stream and Socket, String and Buffer
Related to: | BuffRead | BuffWrite | CloseStream | GetStreamLength | PeekStream | Seek | ShiftStream | SRead | StreamEnd | SWrite
Format: | BuffStream(Buffer)
Parameters: |
Buffer
Required. Any text or buffer expression. This serves as the initial content of the stream.

Comments:

This function returns a stream with the contents of Buffer. The pointer at which an action (read or write) begins will be at the start of the stream. Writing to this stream can overwrite or expand (or both,) the size of this initial stream. In-memory stream can be considerably faster to work with than disk-based streams. Streams can be easier to work with than their older text-buffer counterparts.

Example

    Stream = BuffStream("0123456789");

In this example, the variable Stream would contain "0123456789".


BuffToArray

(Engine-Level Function)

Description: | Reads an array from a formatted buffer containing numerical data and returns the number of elements read.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array, String and Buffer
Related to: | ArrayToBuff | BuffToParm | BuffToPointer
Format: | BuffToArray(ArrayElem, N, Buffer, Offset, Option, Size, Skip)
Parameters: |
ArrayElem
Required. Any array element giving the starting point in the destination array where the data is to be stored. The subscript for the array may be any numeric expression.
N
Required. Any numeric expression giving the number of array elements to read, starting at the element given by the first parameter. If N extends past the upper bound of the array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Buffer
Required. Any text or buffer expression to read. The data stored in the buffer must be numeric.
Offset
Required. Any numeric expression giving the starting buffer position for the read in characters (bytes), starting at 0.
Option

Required. Any numeric expression that specifies the format of the buffer read. This can be one of:

Option | Buffer format
0 | Unsigned binary (low byte first)*
1 | Signed binary (low byte first)
2 | BCD (binary coded decimal) (low byte first)
3 | ASCII octal (high byte first)
4 | ASCII decimal (high byte first)
5 | ASCII hex (high byte first)
6 | ASCII floating point (high byte first)
7 | IEEE float/double (low byte first)
8 | <obsolete>
9 | Allen-Bradley® PLC/3 floating point
10 | VAX single precision floating point

For Option 0, BuffToArray reads 64-bit unsigned integers from buffers and represents them in VTScada values as their signed 64-bit equivalents. This only matters for integers larger than the largest 64-bit signed integer.

For Options 7 and 9, the data is read as appropriate binary format.

Size

Required. Any numeric expression giving the number of digits in each datum. It has a different meaning for each option, as indicated below.

Size | Size Meaning | Size Range
Binary types | Number of bits | The following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64
BCD | Number of 4-bit digits | 1 - 16 digits
ASCII types | Number of bytes | 1 - 64 bytes
Float types | Precision | 1 for single precision, 2 for double precision.
Skip
Required. Any numeric expression giving the number of buffer units to skip after each element is read. In binary modes, the following values are supported: 8, 16, 32, and 64. Units are bits for Options 0 and 1, BCD digits for type 2, and characters or bytes for all others.

Comments:

BuffToArray may only be used with buffers containing numeric data.

Illegal characters embedded in the ASCII string stop further interpretation and are ignored. If an illegal character or the end of a buffer is encountered before a valid number, the remaining array elements are set to invalid.

The return value is the number of array elements read.

In binary modes, for the Size parameter, the following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64. For the Skip parameter, the following values are supported: 8, 16, 32, and 64.

Size and Skip values not in those ranges will only work if their combined value is a multiple of 8. For instance, a Size of 12 and a Skip of 4 will work. A Size of 48 and a Skip of 0 will work. When Skip + Size is not a multiple of 8, the behavior of this function is undefined.

If your values are of Size 1 (i.e. a single bit), use unsigned mode. A Size of 1 is not supported for signed values.

Option 0 - 5 will interpret read-in values as 64-bit integers when the Size parameter is large enough to support a 64-bit value. Otherwise, they will be read as 32-bit values.

Format Type | Minimum Size for 64-bit Value
Binary | Greater than 32 bits
BCD | Greater than 8 digits
Octal | Greater than 11 digits
Hex | Greater than 8 digits.

To force 64-bit interpretation for small hex values, padding can be used, e.g. “00000000FFFFFFFF” will be read in as 4294967295, whereas “FFFFFFFF” will be read as –1. When that is not an option, post-processing can be done to convert a negative signed 32bit integer into its unsigned equivalent (i.e. add 4294967296)

Example:

  BuffToArray(Data[0] { Starting array element },
              100 { No. of elements to read from buffer },
              Response { Text expression to read },
              0 { Starting offset in buffer, in chars },
              2 { Read BCD format },
              4 { 4 BCD characters is 2 bytes },
              0 { Don't skip anything });

This example reads 100 BCD format numbers into array elements 0 to 99. Each BCD number has 4 digits, which occupy 2 buffer bytes.


BuffToHex

(System Library)

Description: | Given a text buffer, this function will treat the content as an arbitrary sequence of bytes and convert it to a readable text buffer containing the sequence of hex numbers representing the bytes in the text buffer.
Returns: | Text
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | HexToBuff | MakeBuff
Format: | System.BuffToHex(BinaryBuffer)
Parameters: |
BinaryBuffer
Required. The buffer that is to be converted to a hexadecimal string.

Comments

VTScada uses UTF-8 encoding for text. Bytes with values from 0 to 127 are valid characters. If a byte larger than 127 appears in a valid UTF-8 string, then it is only part of a multi-byte character and must be preceded by or followed by (or both), certain other bytes in a particular pattern or else it will be flagged as an invalid character

Examples:

    System.BuffToHex("ABCD");

…will return "41424344"

    System.BuffToHex(10);

…will return "3031". 10 is interpreted as the string "10", not the numeric, decimal value.

    System.BuffToHex(Concat(MakeBuff(1, 0xFF),
                      MakeBuff(1, 0x00),
                      MakeBuff(1, 0xAA)));

…will return "FF00AA"

    MachineIDString = System.BuffToHex(WkStaInfo(3));

…will return a hexadecimal representation of the workstation's unique identifier.


BuffToParm

(Engine-Level Function)

Description | Convert buffer of numeric data to parameters. This function reads module parameters from a formatted buffer containing numerical data and returns the number of data items read.
Returns | Numeric
Usage | Script Only.
Function Groups | String and Buffer, Compilation and On-Line Modifications
Related to: | BuffToArray | Parameter | ParmToBuff
Format | BuffToParm(Object, Index, Buffer, Offset, N, Option, Size, Skip)
Parameters |
Object
Required. The object value of the module containing the destination parameters.
Index
Required. Any numeric expression giving the first parameter to read, starting at 1.
Buffer
Required. Any text or buffer expression to read.
Offset
Required. Any numeric expression giving the starting buffer position for the read in characters (bytes), starting at 0.
N
Required. Any numeric expression giving the number of parameters to read from the buffer. If there are fewer actual parameters than N specifies, this function continues to the last parameter and then stops.
Option

Required. Any numeric expression that specifies the format of the buffer read. This can be one of:

Option | Buffer format
0 | Unsigned binary (low byte first)
1 | Signed binary (low byte first)
2 | BCD (binary coded decimal) (low byte first)
3 | ASCII octal (high byte first)
4 | ASCII decimal (high byte first)
5 | ASCII hex (high byte first)
6 | ASCII floating point (high byte first)
7 | IEEE float/double (low byte first)
8 | <obsolete>
9 | Allen-Bradley® PLC/3 floating point
10 | VAX single precision floating point
For Options 7 and 9, the data is read as appropriate binary format.
Size

Required. Any numeric expression giving the number of digits in each datum. Size is measured in different ways for each format option (specified in previous parameter), as indicated in the following table:

Option | Size Meaning | Size Range
Binary types | Number of bits | The following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64
BCD | Number of 4-bit digits | 1 - 16 digits
ASCII types | Number of bytes | 1 - 64 bytes
Float types | Precision | 1 for single precision 2 for double precision
Skip
Required. Any numeric expression giving the number of buffer units to skip after each element is read. The following values are supported: 8, 16, 32, and 64.
Units are bits for Options 0 and 1, BCD digits for type 2, and characters or bytes for all others.

Comments:

This function may only be used with buffers containing formatted numeric data. It reads the buffer, and places the data into module parameters. Normally, the module parameters will be variables. If a parameter is not a variable, then nothing will be assigned to that parameter, and this statement reads the next datum and continues on to the next parameter (if any). Illegal characters that are imbedded in the ASCII string stop further interpretation and are ignored. If an illegal character or the end of a buffer is encountered before a valid number, the remaining parameters are set to invalid.

The return value is the number of data read and can be used as an error check (non-zero indicates an error).

This function is typically used in an I/O driver module to convert serial port or shared RAM data to VTScada variables.

In binary modes, for the Size parameter, the following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64. For the Skip parameter, the following values are supported: 8, 16, 32, and 64.

Size and Skip values not in those ranges will only work if their combined value is a multiple of 8. For instance, a Size of 12 and a Skip of 4 will work. A Size of 48 and a Skip of 0 will work. When Skip + Size is not a multiple of 8, the behavior of this function is undefined.

If your values are of Size 1 (i.e. a single bit), use unsigned mode. A Size of 1 is not supported for signed values.

Option 0 - 5 will interpret read-in values as 64-bit integers when the Size parameter is large enough to support a 64-bit value. Otherwise, they will be read as 32-bit values.

Format Type | Minimum Size for 64-bit Value
Binary | Greater than 32 bits
BCD | Greater than 8 digits
Octal | Greater than 11 digits
Hex | Greater than 8 digits.

To force 64-bit interpretation for small hex values, padding can be used, e.g. “00000000FFFFFFFF” will be read in as 4294967295, whereas “FFFFFFFF” will be read as –1. When that is not an option, post-processing can be done to convert a negative signed 32bit integer into its unsigned equivalent (i.e. add 4294967296)

Example:

In this example, suppose that a module is started with the statement (a.k.a. module call):

  ReadIEEE(1, "PLC", 2, x, y, z);

and that the module ReadIEEE contains the following script:

  If 1 Main;
  [
    BuffToParm(Self() { Data goes in this module's parms },
               4 { Start at parm 4 (skip first 3 ) },
               Response { Formatted buffer to be read },
               12 { Skip first 12 characters, 0 to 11 },
               NParm(Self()) - 3
               { Compute number of parms to read },
               7 { Format is IEEE floating point },
               2 { Double precision },
               1 { Skip 1 byte between each double });
  ]

This example reads IEEE double precision numbers from a buffer and places them in the module ReadIEE's parameters. The bytes 0 to 11 of response are skipped. Bytes 12 to 19 are converted from IEEE format and placed in x. Byte 20 is skipped (the skip parameter indicates 1 byte). Bytes 21 to 28 are converted and placed in y. Byte 29 is skipped. Bytes 30 to 37 are converted and placed in z. Reading ceases, (NParm(Self) - 3 equals 3, or three parameters have been read).


BuffToPointer

(Engine-Level Function)

Description | Converts a buffer of numeric data to array of pointers. This function reads from a formatted buffer containing numeric data, writes to locations specified by an array of pointers, and returns the number of elements read.
Returns | Pointer array
Usage | Script Only.
Function Groups | Array, String and Buffer
Related to: | BuffToArray | BuffToParm | New | PointerToBuff
Format | BuffToPointer(ArrayElem, N, Buffer, Offset, Option, Size, Skip)
Parameters |
ArrayElem
Required. Any array element giving the starting point in the pointer array. The subscript for the array may be any numeric expression.
N
Required. Any numeric expression giving the number of items to read. If N extends past the upper bound of the array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Buffer
Required. Any text or buffer expression to read.
Offset
Required. Any numeric expression giving the starting buffer position for the read in characters (bytes), starting at 0.
Option

Required. Any numeric expression that specifies the format of the buffer read. This can be one of:

Option | Buffer Format
0 | Unsigned binary (low byte first)
1 | Signed binary (low byte first)
2 | BCD (binary coded decimal) (low byte first)
3 | ASCII octal (high byte first)
4 | ASCII decimal (high byte first)
5 | ASCII hex (high byte first)
6 | ASCII floating point (high byte first)
7 | IEEE float/double (low byte first)
8 | <obsolete>
9 | Allen-Bradley® PLC/3 floating point
10 | VAX single precision floating point

For Options 7 and 9, the data is read as appropriate binary format.

Size

Required. Any numeric expression giving the number of digits in each datum. Size is measured in different ways for each format option (specified in previous parameter), as indicated in the following table:

Option | Size Meaning | Size Range
Binary types | Number of bits | The following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64
BCD | Number of 4-bit digits | 1 - 16 digits
ASCII types | Number of bytes | 1 - 64 bytes
Float types | Precision | 1 for single precision, 2 for double precision.

Skip

Required. Any numeric expression giving the number of buffer units to skip after each element is read. In binary modes, the following values are supported: 8, 16, 32, and 64.
Units are bits for Options 0 and 1, BCD digits for type 2, and characters or bytes for all others.

Comments:

This function may only be used with buffers containing formatted numeric data. Illegal characters that are imbedded in the ASCII string stop further interpretation and are ignored. If an illegal character or the end of a buffer is encountered before a valid number, the remaining elements are set to invalid. As each item is read from the buffer, the result is stored to the location pointed to by the element of the array. If an element is invalid, or doesn't contain a pointer, then nothing happens and processing continues with the next item/element.

The return value is the number of array elements read. This may be used as an error check - if the return value is not zero, then one or more array elements were not read.

In binary modes, for the Size parameter, the following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64. For the Skip parameter, the following values are supported: 8, 16, 32, and 64.

Size and Skip values not in those ranges will only work if their combined value is a multiple of 8. For instance, a Size of 12 and a Skip of 4 will work. A Size of 48 and a Skip of 0 will work. When Skip + Size is not a multiple of 8, the behavior of this function is undefined.

If your values are of Size 1 (i.e. a single bit), use unsigned mode. A Size of 1 is not supported for signed values.

Option 0 - 5 will interpret read-in values as 64-bit integers when the Size parameter is large enough to support a 64-bit value. Otherwise, they will be read as 32-bit values.

Format Type | Minimum Size for 64-bit Value
Binary | Greater than 32 bits
BCD | Greater than 8 digits
Octal | Greater than 11 digits
Hex | Greater than 8 digits.

To force 64-bit interpretation for small hex values, padding can be used, e.g. “00000000FFFFFFFF” will be read in as 4294967295, whereas “FFFFFFFF” will be read as –1. When that is not an option, post-processing can be done to convert a negative signed 32bit integer into its unsigned equivalent (i.e. add 4294967296)

Example:

Assume that the pointer array has been initialized as shown:

  Destination[0] = &StationFlow;
  Destination[1] = &StationPower;
  Destination[2] = &StationIntruder;
  Destination[3] = &StationOK;
  Destination[4] = &StationPressure;

Now execute the statement:

    BuffToPointer(Destination[0] { Starting element },
                  5 { No. of elements to read },
                  Response { Text expression to read },
                  0 { Starting offset in buffer },
                  2 { Read BCD format },
                  4 { 4 BCD characters is 2 bytes },
                  0 { Don't skip anything });

This reads 5 BCD format numbers into variables pointed to by elements 0 to 4. Each BCD number has 4 digits, which occupy 2 buffer bytes. This will set the variables StationFlow, StationPower, StationIntruder, StationOK, and StationPressure to the values read from the buffer.


BuffWrite

(Engine-Level Function)

Description: | Writes formatted values to a buffer and returns the number of values not written.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | BuffRead | FWrite | SetByte | SWrite | ArrayToBuff | MakeBuff
Format: | BuffWrite( [N,] Buffer, Offset, Format, V1, V2, V3, …)
Parameters: |
Buffer
Required. Any text or buffer expression to be written. The buffer must already exist.
Buffers are created by certain functions, such as ArrayToBuff or MakeBuff, or by assignment of a text string such as "Hello." BuffWrite writes to an existing buffer, which is faster than creating a new buffer.
Writing to an empty buffer has no effect.
Offset
Required. Any numeric expression giving the starting buffer position in characters or bytes for the write, starting at 0.
Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be written. This format is similar, but not identical, to the C language format string for the printf function, whereby each of the Vn parameters in the statement is assigned to a % format specification in the order in which each appears in the list.

Note that like a standard text string, these format specifiers must also be enclosed by double quotes.

If a format specification appears for which there are no remaining V parameters, the format specification characters themselves are output to the stream exactly as they appear in the Format.

For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[-][+][SPACE][#][width][.precision]type

where

% (percent sign) is mandatory;

- (minus sign) (optional) causes the data to be left justified within the field (for binary types b and ASCII character types c, this option is ignored);

+ (plus sign) (optional) causes positive numbers to be prefaced with a + sign (negative numbers are unaffected). This allows easy alignment of positive and negative numbers in a printed column of numbers. For binary types b and non-numerical types, this option is ignored;

space represents the single space character, and is similar to the [ + ] option but places a single space rather than a plus sign in front of positive numbers (negative numbers are still unaffected). This allows alignment of a column of numbers without having to show all signs. For binary types b and non-numerical types, this option is ignored;

# (hash mark) When used with the o , x , or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.

width is a number that specifies the minimum number of characters to output. Numbers that require more characters than specified by the width value are truncated on output. If the number of characters in the number or string is less than width, blanks will be added to the left or right, depending upon whether the output is left or right justified (i.e. whether the [ - ] option has been specified) until the width is reached. For binary types b and ASCII character types c, this option is ignored;

precision has a different meaning for each of the type options as follows:

  • Integer types d, l, u, o, x, and X precision specifies the minimum number of digits to output. If the number contains fewer digits, leading zeroes will be added to the left of the number. If precision is 0, omitted, or if the decimal point appears without a number following it, the precision defaults to 1. The number is not truncated.
  • Floating point types e and E precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision in this case is 6. If the precision is 0 or if the decimal point appears without a number following it, no decimal point appears in the output.
  • Floating point type f precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision is 0. If the precision is explicitly 0, no decimal point is output. If a decimal point is output, at least one digit will be placed before the decimal point.
  • Floating point types g and G precision specifies the maximum number of significant digits to be output. If no precision is specified, all significant digits are written.
  • String type s precision specifies the maximum number of characters of the string to be output. If the string contains more characters than specified by the precision, the string is truncated and only the first characters are written. If the precision is not specified, all of the string characters are output.
  • Byte type c The precision option is ignored.
  • Binary type b The precision option is ignored.

type is mandatory. The type specification must be one of those listed below.

Note: The case of the letter is important. Specifying a character for the type that is not in this list will result in all the characters following the % up to that point to be output exactly as they appear in the Format string.

Type | Meaning
nb | Binary format; where n is a number indicating the type of value (see below).
c | Single character (byte values from 0 to 255)
d | Signed decimal 64-bit integer, 64-bit output by default
e | Signed exponential; exponent key is "e".
E | Signed exponential; exponent key is "E".
f | Signed floating point.
g | e or f format, whichever is shorter.
G | E or f format, whichever is shorter.
h | Handle to a window.
i | Signed decimal 64-bit integer, 64-bit output by default
o | Unsigned octal integer. Default 32-bit integer. Use %llo to output 64-bit value.
p | Pointer to a buffer.
s | Text string.
t | Writes a utf-8 string as used by OPC UA binary TCP: a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string
u | Unsigned decimal 64-bit integer, 64-bit output by default
x | Unsigned hex integer using "abcdef". Default 32-bit integer. (See following note.)
X | Unsigned hex integer using "ABCDEF". Default 32-bit integer. (See following note.)

When writing negative values using either x or X format codes, the output will use a minimum of 32 bits because that is the smallest possible size to display the full information. Defining a format string such as "%4X" will not reduce this to 16 bit output for negative values. To output 64-bit values, use the modifier ll. %llx and %llX output 64-bit values.

nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.

n | Value Type
0 | Byte, unsigned
1 | Signed short integer (2 bytes)
2 | Signed long integer (4 bytes)
3 | IEEE single precision float (4 bytes)
4 | <obsolete>
5 | IEEE double precision float (8 bytes)
6 | <obsolete>
7 | Unsigned short integer (2 bytes)
8 | Unsigned long integer (4 bytes)
9 | Writes a time in Microsoft FILETIME format, which contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).
10 | Outputs signed 64-bit integers in binary form.

Note: Other options such as width and precision do not apply to the b type.

c, Byte type: This type is not representative of a single character in a string, but rather, represents single bytes. Input values (the Vn parameter to which this format specification applies) must be integers in the range of 0 to 255. Strings are not acceptable input values. Note that the %c format specifier behaves differently when used in an output statement such as BuffWrite than when used in an input statement, such as BuffRead. Some UTF-8 characters can require multiple bytes. Values from 0-127 are consistent between the traditional ASCII encoding and the UTF-8 encoding.

d, Signed decimal 64-bit integer:

e, Signed exponential: Exponent key is "e"

E, Signed exponential: Exponent key is "E"

f, Signed floating point

g, e or f formats: Whichever is shorter

G, E or F formats: Whichever is shorter

h, Window handle type: This type is used for building structures to be handed to DLLs and should be used by advanced users only.

p, Buffer pointer type: This type is also used for building structures to be handed to DLLs and should be used by advanced users only.

s, Text string type:

t, Writes a utf-8 string as used by OPC UA binary TCP:
a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string

u, Unsigned decimal 64-bit integer,

x, Unsigned hex integer using "abcdef": 32-bit value by default. Use modifier %llx for 64-bit value output.

X, Unsigned hex integer using "ABCDEF": 32-bit value by default. Use modifier %llX for 64-bit value output.

SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Plain text Text in the Format parameter is written exactly as it appears, with three exceptions:

  • Percentage sign (%) Because format specifications for the Vn parameters are indicated by a percentage sign, to include an actual percentage sign as part of the Format parameter, precede it with a backslash character (i.e. \%).
  • Backslash character (\) Because this is used to indicate special control characters such as line feed, carriage return, and form feed, to write a backslash as part of the Format parameter, use two backslash characters (i.e. \\).
  • Quotation marks (") The entire test string is delimited by quotation marks, so to include a set of quotation marks as part of the Format parameter, use a set of quotations marks (i.e. "").

Control characters In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result (notice that the letters must be lower case):

Code | Meaning
\b | Backspace
\f | Form feed
\n | Line feed
\r | Carriage return
\t | Horizontal tab
\v | Vertical tab

\nnn In addition to the above predefined codes, \nnn may be used, where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

znnn Escape character where nnn is the 3-digit ASCII code
For example: SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Offset is any numeric expression giving the starting buffer position in bytes for the write, starting at 0.

Comments:

In early versions of VTS (WEB), there was a numeric leading parameter, N. This should not be included in any new code.

If one of the values to be written is outside of the range of the type indicated by the format specifier, a 0 is written. If the value to be written is invalid, nothing is written for most format specifiers, except for %nb, which will write a 0 in the place of the invalid. Invalidity of the output values does not preclude execution of this function.

This function returns the number of Vn parameters not written to the buffer. A 0 return value indicates success. Variables that contain invalid values that were not written due to their invalidity do not increment this count. An invalid return value indicates an error with one of the parameters.

This function can be used to format strings for display, or for message packets as part of the driver toolkit.

As of version 12.0, VTScada expects all strings to be encoded using UTF-8.

Do not attempt to access a buffer while it is being written. During that time, its contents are undefined.

Example:

  If ! Valid(Buff);
  [
    buff = MakeBuff(100, 0) { Create the buffer };
    BuffWrite(Buff { Buffer },
              0 { Starting offset },
              "A=%3.2d\r\nB=%6.2f\r\n%8.3s\r\n%c\r\n\033"  { Format string },
              2, 2/3, "finished", 33 { Values to be written });
]

This would set Buff as follows :

A= 02
B= 0.67
fin
!
!


BuildDelete

(ODBC Manager Library)

Description: | Builds SQL Delete statements based on arrays of field names and values. Made to be called as a subroutine only.
Returns: | Text (the SQL statement)
Usage: | Script Only.
Related to: | AddConnection | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.BuildDelete( TableName, WhereFields, WhereOperators, WhereValues, WhereSQLDataTypes, WhereAND, dbType)
Parameters: |
TableName
Required. Any text expression for the table name to delete records from.
WhereFields
Required. May be a simple value or a one-dimensional array. Provides the field names for the WHERE selection clause
WhereOperators
Required. May be a simple value or a one-dimensional array. Provides the operators for the WHERE selection clause
WhereValues
Required. Any SQL data type. May be a simple value or a one-dimensional array. Values for the WHERE selection clause
WhereSQLDataTypes
Required. Values indicating the data type of the insert values. Should be a simple value or an array matching the WhereFields parameter. Refer to Data Type Codes used in the ODBC Manager for a list of the value codes.
WhereAND
Required. Any expression that evaluates to a Boolean true or false.
If set to true (non-zero) then the components of the WHERE clauses are to be ANDed together.
If false (0) an OR is used between the sub clauses.
dbType
Required numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase

Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

If the WhereFields parameter is invalid, the SQL statement returned will be "DELETE FROM [Tablename]". The ExecuteQuery function includes a check that will prevent a delete statement without a where clause from running.

Example:

    Query = \ODBCManager.BuildDelete("TestTable", "RecordName", "=", "rec2", \ODBCManager\#SQL_VARCHAR, 1,
                                         \ODBCManager\#dbType_MSAccess);
    Err    = Invalid;
    Result = Invalid;
    Attrib = Invalid;
    ErrorMsg = Invalid;
    SQLState = Invalid;
    ErrorCode = Invalid;
    \ODBCManager.ExecuteQuery(&Err, Query, Conn1DSN, Invalid, Invalid, &Result, &Attrib, &ErrorMsg, &SQLState,
                                  &ErrorCode, 0, Trans2, 0, \ODBCManager\#dbType_MSAccess);


BuildFullName

Security Manager Module

Description | If a namespace and namespace delimiter are being used, returns the full, namespace-qualified name of the specified account.
Returns | String
Usage | Script Only.
Related to: | GetAccountID | GetAccountInfo | GetGroupName | GetFullName | GetUserName | IsLoggedOn | IsSecured | IsSuspended | SecurityCheck | UIErrorToText | Security NameSpaces
Format | \SecurityManager.BuildFullName(AccountName [, GroupName]);
Parameters |
AccountName
The name of an account to generate the full name for.
GroupName
The name of a namespace (group) to use when building the full name.
Comments If the configuration setting NameSpaceDelimiter is valid, returns the full, namespace-qualified name of the specified account.
If the GroupName parameter is Invalid or not specified, or if the account is a member of the root namespace, or the configuration setting NameSpaceDelimiter is Invalid, the return value is the account name, as passed in.

Example:

    IfThen(StrICmp(Username, \SecurityManager.GetShortUserName(Username, &Realm)) == 0,
       { No realm was provided in the username. As a convenience, prepend it to the username. }
      Username = \SecurityManager.BuildFullName(UserName, \SecurityManager.GetGroupName());
    );


BuildInsert

(ODBC Manager Library)

Description: | Builds SQL Insert statements based on arrays of field names and values. Made to be called as a subroutine only.
Returns: | Text or ODBCQuery structure.
Usage: | Script Only.
Related to: | AddConnection | BuildDelete | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.BuildInsert( TableName, InsertFields, InsertValues, SQLDataTypes, dbType)
Parameters: |
TableName
Required. The name of the table into which data will be inserted.
InsertFields
Required. May be a simple value or a one-dimensional array. Field names matching the InsertValues array of data to be inserted
InsertValues
Required. Any SQL data type. May be a simple value or a one-dimensional array. Provides the new value(s) for the fields in the matching InsertFields parameter.
SQLDataTypes
Required. Values indicating the data type of the insert values. Should be a simple value or an array matching the InsertFields parameter. Refer to Data Type Codes used in the ODBC Manager for a list of the codes.
dbType
Required numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase

Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

The only way to ensure that a long running (or faulty) query does terminate is to set appropriate values for both the parameters ExecutionTimeout and UseDriverTimeout. Modules executing queries are designed to be run as launched modules and will remain active until complete.

Returns the SQL INSERT statement as a text string, unless long binary data is involved, in which case an ODBCQuery structure is returned. The format of the structure is as follows:

  ODBCQuery STRUCT [
    QueryString;
    Parameters;
  ];

Example:

InsertRecord [
  If 1 NextRecord;
  [
    Names  = New(4);
    Types  = New(4);
    Values = New(4);
    Nnames[0] = "RecordName";
    Names[1] = "TextVal";
    Names[2] = "NumberVal";
    Names[3] = "BoolVal";
    Types[0] = \ODBCManager\#SQL_VARCHAR;
    Types[1] = \ODBCManager\#SQL_VARCHAR;
    Types[2] = \ODBCManager\#SQL_NUMERIC;
    Types[3] = \ODBCManager\#SQL_BINARY;
    Values[0] = "rec1";
    Values[1] = "string1";
    Values[2] = 11;
    Values[3] = 1;
    Query = \ODBCManager.BuildInsert("TestTable", Names, Values, Types,
                                     \ODBCManager\#dbType_MSAccess);
    Err    = Invalid;
    Result = Invalid;
    Attrib = Invalid;
    ErrorMsg = Invalid;
    SQLState = Invalid;
    ErrorCode = Invalid;
    \ODBCManager.ExecuteQuery(&Err, Query, Conn1DSN, Invalid, Invalid, &Result, &Attrib, &ErrorMsg, &SQLState,
                              &ErrorCode, 0, Invalid, 0, \ODBCManager\#dbType_MSAccess);
  ]
]
NextRecord [ ...


BuildSelect

(ODBC Manager Library)

Description: | Builds SQL selection queries using supplied field names and values. Made to be called as a subroutine only.
Returns: | Text (the SQL query)
Usage: | Script Only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.BuildSelect( SelectFields, TableName, WhereFields, WhereOperators, WhereValues, WhereSQLDataTypes, WhereAND, OrderFields, Qualifier)
Parameters: |
SelectFields
Required. Text array of field Names to read
TableName
Required. May be a simple value or a one-dimensional array. The name(s) of the table(s) that will be queried.
WhereFields
Required. May be a simple value or a one-dimensional array. Field names for WHERE clause
WhereOperators
Required. May be a simple value or a one-dimensional array. Operators for WHERE clause
WhereValues
Required. Any SQL data type. May be a simple value or a one-dimensional array. Values for WHERE clause
WhereSQLDataTypes
Required. Values indicating the data type of the insert values. Should be a simple value or an array matching the WhereFields parameter.

Refer to Data Type Codes used in the ODBC Manager for a list of the codes.
WhereAND
Required. Can be any expression that evaluates to a Boolean true or false.
If set to true (non-zero) then the components of the WHERE clauses are to be ANDed together.
If false (0) an OR is used between the sub clauses.
OrderFields
Required. May be a simple value or a one-dimensional array. Provides the field names for ORDER BY clause
Qualifier
Required. SQL Qualifier such as "top 100", "unique", etc

Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

Example:

CheckRecord[
  If 1 CheckIfExists;
  [
    { Build select query to check if a specified tag/variable exists }

    WhereFields[0] = "TagName";
    WhereFields[1] = "TagVariable";
    WhereOperators[0] = "=";
    WhereOperators[1] = "=";
    WhereValues[0] = TagName;
    WhereValues[1] = TagVariable;
    WhereSQLDataTypes[0] = \ODBCManager\#SQL_VARCHAR;
    WhereSQLDataTypes[1] = \ODBCManager\#SQL_VARCHAR;

    GetTagIDQuery = \ODBCManager\BuildSelect("ID", TagIDTableName,
                                           &WhereFields, &WhereOperators, &WhereValues, &WhereSQLDataTypes, 1);
    { Execute Query }
    LocExecQueryErr = Invalid();
    \ODBCManager\ExecuteQuery(&LocExecQueryErr, GetTagIDQuery, LoggerDSN,
                            Invalid, Invalid, &RawODBCData, &LocODBCAttribPtr,
                            &LocODBCErrMsgPtr, &LocODBCSQLStateErr, &LocODBCError,
                            1 { format into [Row][Field] });
  ]
]

CheckIfExists[...


BuildUpdate

(ODBC Manager Library)

Description: | Builds SQL UPDATE statements using supplied field names and values. Made to be called as a subroutine, but will function as a called module.
Returns: | Text
Usage: | Script Only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.BuildUpdate( TableName, UpdateFields, UpdateValues, SQLDataTypes, WhereFields, WhereOperators, WhereValues, WhereSQLDataTypes, WhereAND, dbType)
Parameters: |
TableName
Required. Any expression for the name of the table to be updated.
UpdateFields
Required. May be a simple value or a one-dimensional array. Provides the field names to be updated
UpdateValues
Required. Any SQL data type. May be a simple value or a one-dimensional array. Provides the new values for the fields
SQLDataTypes
Required. Values indicating the data type of the update values. Should be a simple value or an array matching the UpdateFields parameter. Refer to Data Type Codes used in the ODBC Manager for a list of the numeric codes.
WhereFields
Required. Any expression or array of the field names for WHERE clause
WhereOperators
Required. May be a simple value or a one-dimensional array. Operators for WHERE clause
WhereValues
Required. May be a simple text value or a one-dimensional array of text. Values for WHERE clause
WhereSQLDataTypes
Required. Values indicating the data type of the insert values. Should be a simple value or an array matching the WhereFields parameter. Refer to Data Type Codes used in the ODBC Manager for a list of the numeric codes.
WhereAND
Required. Can be any expression that evaluates to a Boolean true or false. If set to true (non-zero) then the components of the WHERE clause are to be ANDed together. If false (0) an OR is used between the sub clauses.
dbType
Required numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase

Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above. Returns the SQL UPDATE statement as a text string unless binary parameters are involved, in which case an ODBCQuery structure is returned. The format of the structure is as follows:

  ODBCQuery STRUCT [
    QueryString;
    Parameters;
  ];

Example:

UpdateRecord [
  If 1 GetUpdatedRecord;
  [
    SubNames  = New(2);
    SubValues = New(2);
    SubTypes  = New(2);

    SubNames[0] = "TextVal";
    SubNames[1] = "NumberVal";
    SubTypes[0] = \ODBCManager\#SQL_VARCHAR;
    SubTypes[1] = \ODBCManager\#SQL_NUMERIC;
    SubValues[0] = "changed";
    SubValues[1] = 110;
    Query = \ODBCManager.BuildUpdate("TestTable", SubNames, SubValues, SubTypes,
                                     "RecordName", "=", "rec1", \ODBCManager\#SQL_VARCHAR, 1,
                                     \ODBCManager\#dbType_MSAccess);
    Err    = Invalid;
    Result = Invalid;
    Attrib = Invalid;
    ErrorMsg = Invalid;
    SQLState = Invalid;
    ErrorCode = Invalid;
    \ODBCManager.ExecuteQuery(&Err, Query, Conn1DSN, Invalid, Invalid, &Result, &Attrib, &ErrorMsg, &SQLState,
                              &ErrorCode, 0, Invalid, 0, \ODBCManager\#dbType_MSAccess);
  ]
]

GetUpdatedRecord [...


C Functions

The sections that follow identify all VTScada functions beginning with "C".


Call

(Engine-Level Function)

Description: | Starts an instance of the module specified by its first parameter.
Returns: | The Return value of the instance of the module started.
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Basic Module
Related to: | FindVariable | Self
Format: | Call(Module [,Parm1, Parm2, Parm3, …])
Parameters: |
Module
Required. Any expression for the module that is to be started.
Parm1, Parm2, Parm3, …
Optional. Expressions to be passed to the module that is being started.
Comments: The additional parameters that are specified are passed to the started module as parameters to the call.

Example:

  ZEditField(10, 40, 110, 10, Mod, 32, 0, 1);
  If Valid(Mod) && ! Valid(X);
  [
    X = FindVariable(Mod, Self(), 0, 1);
  ]
...
  Call(X);

This section of code enables the user to enter a module name into the edit field, which will then be located by the script and started by the Call statement. Notice that in this particular example, no parameters are passed to the module, however, more edit fields could be created to accept variables or values to use as parameters to the module by entering them in the Call statement.


CalledInstances

(Engine-Level Function)

Description: | Returns the object values of module instances that are called by a particular module.
Returns: | Object(s)
Usage: | Script Only.
Function Groups: | Advanced Module, Compilation and On-Line Modifications
Related to: | ChildInstances | Self | GetInstance | Instance | NumInstances | Valid
Format: | CalledInstances(Object[, Options])
Parameters: |
Object
Required. An object value of the module instance for which to get the number of called instances.
Options

Optional. Any numeric expression that defines which modules are to be included in the returned set.
The value for this parameter is formed by adding together the values from the following table:

(See: Bitwise Parameters & Operations)

Options | Bit Number | Description
1 | 0 | Include all modules, even if they are in the same window as their caller. Set false to include only (root) modules for modules in separate windows.
2 | 1 | Recurse into called modules of called modules. Set false to include only modules directly called by the Object parameter.
4 | 2 | Group all instances of the same module into an array and store that array of object values in the element of the returned array, instead of the object value.
Comments: The return value is an array of objects which are called from Object. If no instances are called from Object, Invalid is returned.

Example:

  i = -1;
 ... If i == -1;
  [
    NumCalled = CalledInstances(Self());
    i++;
  ] If Valid(NumCalled[i]);
  [
    Slay(NumCalled[i], 0);
    i++;
  ]

The first If statement and script creates an array of object values to all instances called by the current module. The second If and script slays all of these instances. Notice that in the case of the first script, the action trigger must be based on i rather than on a Valid test of NumCalled. If this were not the case and ! Valid(NumCalled) was used instead, then if there were no instances called from this module, CalledInstances would return Invalid, and an "if one" (infinite loop) condition would occur.


Caller

(Engine-Level Function)

Description: | Takes a given object value for a module and returns the object value of the module by which it was called.
Returns: | Object
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Basic Module
Related to: | FindVariable | Self
Format: | Caller(Object)
Parameters: |
Object
Required. An object value that specifies the instance whose caller is desired.

Example:

  Obj = Caller(Self());

This assigns the pointer to the caller of the current module to variable Obj.


CanAddLock

(Control Lock Manager)

Description: | Returns TRUE if the user has lock adding privileges for a given tag.
Returns: | Boolean
Usage: | Script or Steady State
Function Groups: | (Control Lock Manager)
Related to: | AddLock | CanAddLock | CanControl (Control Lock Manager) | CanRemoveLock | GetLockLevel | RemoveLock |
Format: | \ControlLockManager.CanAddLock(TagID)
Parameters: |
TagID
Required text. The unique ID of tag being examined.
Comments:

None

Example:

None available.


CancelCall

Modem Manager

Description: | This subroutine removes a queued call or abandons a call that is in-progress.
Usage: | Script Only.
Related to: | MakeCall
Format: | \ModemManager.CancelCall(Tag [, HangUp, NoCancel, Silent]);
Parameters: |
Tag
Any text expression that identifies the tag that originally requested the call.
HangUp
An optional Boolean parameter that specifies whether to hang-up on an active call. The default is to allow an active call to proceed.
NoCancel
An optional Boolean parameter that, if set, will remove the call from the internal queue, but not terminate the call.
Silent
An optional Boolean parameter indicating the logging is not required if set TRUE.
Comments: As described under MakeCall, after a tag has requested that a call be made, the Modem Manager takes responsibility for the control of the call, and indicates progress in the tag's DataPort variable. If the tag decides at any point before the Modem Manager has completed (or abandoned) the call that it no longer requires the call, then the tag must call CancelCall.


CanControl (Control Lock Manager)

(Control Lock Manager)

See also: CanControl (Control Token Manager)

Description: | Returns true if there are no locks preventing the control of a given tag. Always returns true if ControlLocksEnabled is set to false.
Returns: | Boolean
Usage: | Script or Steady State
Function Groups: | (Control Lock Manager)
Related to: | AddLock | CanAddLock | CanControl (Control Lock Manager) | CanRemoveLock | GetLockLevel | RemoveLock |
Format: | \ControlLockManager.CanControl(TagObj)
Parameters: |
TagObj
Required object. Tag instance of tag being examined
Comments:

None

Example:

None available.


CanControl (Control Token Manager)

(Control Token Manager)

See also: CanControl (Control Lock Manager)

Description: | Returns true if there is a token allowing the control of a given tag.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | \ControlTokenManager.CanControl(TagObj)
Parameters: |
TagObj
An object reference to the tag you wish to check for a Control Token.
Comments:

Returns true if there is a token allowing the control of the specified tag.

Always returns true if the nearest instance of the property, ControlTokensEnabled, is set to 0 (FALSE), meaning that the Control Token system is disabled for this workstation.


CanDenyTokenRequest

(Control Token Manager)

Description: | Returns TRUE if the user is allowed to deny a token request.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | \ControlTokenManager.CanDenyTokenRequest(TagID, TokenRequestRecord[, SessionID, AccountID, MachineID])
Parameters: |
TagID
Required text. The GUID of the tag for which a token request should be denied.
TokenRequestRecord

something

SessionID
Optional text. Defaults to the current Session ID if not specified. Used when checking whether a control token is already held.
AccountID
Optional text. Defaults to the current user Account ID. Used when checking whether a control token is already held.
MachineID
Optional text. Defaults to the current user Machine ID. Used when checking whether a control token is already held.
Comments:

The user must either own the existing token, own the request, or have the token admin privilege. Returns FALSE otherwise.


CanEditDoc

(Engine-Level Function)

Description: | Returns an indication as to whether the document for the given module can be edited.
Warning: | This function should be used only by advanced programmers.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | ResyncDoc
Format: | CanEditDoc(Module [, ErrCode])
Parameters: |
Module
Required. Any module value that specifies the document that you wish to modify.
ErrCode

Optional. Is set to a non-zero value when CanEditDoc returns a 1. The return value is a collection of 3 bits:

(See: Bitwise Parameters & Operations)

ErrCode | Bit No. | Description
1 | 0 | TRUE if not available (001)
2 | 1 | TRUE if read only (010)
3 | 2 | TRUE if file is out of sync (100)
Comments: This function returns true if the document for the given module can be modified. The function will check to see if the date and time for the document file match that of the run file. It will return false if the document does not exist, if the dates and times are out of sync, or if the document is "Read Only".

Example:

  If Watch(1, CurrentWindow());
  [
    EditFlag = CanEditDoc(CurrentWindow());
  ]

This script will be executed as soon as its state becomes active, and then every time the mouse moves over a new window, EditFlag will indicate whether editing can be done in that window.


CanGrantTokenRequest

(Control Token Manager)

Description: | Returns TRUE if the user is allowed to grant a token request.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | \ControlTokenManager.CanGrantTokenRequest(TagID[, SessionID, AccountID, MachineID])
Parameters: |
TagID
Required text. The UniqueIDof the tag for which a token request should be granted.
SessionID
Optional text. Defaults to the current Session ID if not specified. Used when checking whether a control token is already held.
AccountID
Optional text. Defaults to the current user Account ID. Used when checking whether a control token is already held.
MachineID
Optional text. Defaults to the current user Machine ID. Used when checking whether a control token is already held.
Comments:

The person granting the request must own the existing token, or have control over the tag for which the request is being made, or have token admin privileges. Returns FALSE otherwise.


CanReleaseToken

(Control Token Manager)

Description: | Returns true if the user has token releasing privileges and appropriate token ownership.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | \ControlTokenManager.CanReleaseToken(TagID, TokenInfo[, SessionID, AccountID, MachineID])
Parameters: |
TagID
Required text. The GUID of the tag, from which a token should be released.
TokenInfo
Required text. The token record or the token record's GUID to release. The token record can be Obtained by calling GetToken.
SessionID
Optional text. Defaults to the current Session ID if not specified. Used when checking whether a control token is already held.
AccountID
Optional text. Defaults to the current user Account ID. Used when checking whether a control token is already held.
MachineID
Optional text. Defaults to the current user Machine ID. Used when checking whether a control token is already held.
Comments:

Returns TRUE if the user has token releasing privileges and appropriate token ownership. Returns FALSE otherwise.


CanRemoveLock

(Control Lock Manager)

Description: | Returns true if the user has lock removing privileges and appropriate lock ownership.
Returns: | Boolean
Usage: | Script or Steady State
Function Groups: | (Control Lock Manager)
Related to: | AddLock | CanAddLock | CanControl (Control Lock Manager) | CanRemoveLock | GetLockLevel | RemoveLock |
Format: | \ControlLockManager.CanRemoveLock(TagID, LockInfo[, SessionID, AccountID, MachineID] )
Parameters: |
TagID
Required text. The unique ID of tag being examined.
LockInfo
Required text or structure. May be the lock record (a structure) or a GUID (text).
SessionID
Optional text. The ID of the session where this function was called. Defaults to the current security session.
AccountID
Optional text. The AccountID of the user removing the lock. Defaults to the user signed in at the station where this function is called.
MachineID
Optional text. The workstation's MachineID. Defaults to the workstation from which this function is called.
Comments:

None

Example:

None available.


CanRequestToken

(Control Token Manager)

Description: | Returns TRUE if the user is allowed to request a token.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | \ControlTokenManager.CanRequestToken(TagID[, SessionID, AccountID, MachineID])
Parameters: |
TagID
Required text. The GUID of the tag to examine.
SessionID
Optional text. Defaults to the current Session ID if not specified. Used when checking whether a control token is already held.
AccountID
Optional text. Defaults to the current user Account ID. Used when checking whether a control token is already held.
MachineID
Optional text. Defaults to the current user Machine ID. Used when checking whether a control token is already held.
Comments:

The user must have the Token Request/Release privilege and must not currently own a token applying to the tag.


CaptureImage

(Engine-Level Function)

Description: | Creates an image handle from a GUIStretch operation
Returns: | Bitmap handle
Usage: | Script Only.
Function Groups: | Graphics
Related to: | SaveImage |
Format: | CaptureImage(Object, Left, Bottom, Right, Top);
Parameters: |
Object
The object whose image is being captured
Left
The left coordinate of the capture.
Bottom
The bottom coordinate of the capture.
Right
The right coordinate of the capture.
Top
The top coordinate of the capture.
Comments: Creates an image capture of anything drawn by the object or its children within the provided (optional) coordinates. This image is stored in a bitmap handle identical to the output of the MakeBitmap function, meaning that it can be modified, displayed or saved.

Examples:

{ GUIStretch calling a module }
  GUITransform(296, 736, 469, 563,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 2          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Obj = MyModule("GUIStretch of MyModule"));

  { Capture an image of the module every second }
  If TimeOut(1, 1);
  [
     CapturedImage = CaptureImage(Obj);
  ]


CaptureSettings

Code Layer

Description: | Gathers a single property value or an accumulated section and returns the result in a tabular format.
Returns: | Object (Results are returned via a parameter)
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | GetINIProperty |
Format: | \CaptureSettings(Section, ValueName, pResult[, CallerHasLock])
Parameters: |
Section
Required. The name of the section where the property will be found.
ValueName
Required. The name of the property to return. Set to Invalid to retrieve the entire section.
pResult
Required. A pointer to a variable, in which the retrieved property or properties will be returned. See comments.
CallerHasLock

Optional Boolean. Set to TRUE if the caller holds the semaphore.

If you did not set a lock using AcquireLock or are not launching this module that is know to have a lock, set to FALSE or omit.

Comments:

A launched module, this function's return value is a reference to itself which becomes invalid when the operation completes. The caller must not slay itself while this object is valid. The check is performed in a critical section to prevent result corruption due to settings changes on other threads.
Comments are not included in the output, but hidden values are.

pResult can be any of the following:

  • If ValueName was provided and there is only one setting in the section with that name, it will be that one value (not an array).

  • If ValueName was provided and the setting appears multiple times in the section, then it will be a 1-dimensional array of those values.

  • If ValueName was not provided, then it will be a 2d array of all of the setting names+values in the section. For example, pResult[0][0] will contain the first setting name and pResult[1][0] will return its value.

If the property is found in more than one settings file, the returned result will be the one from the file with the highest priority. In order from lowest to highest priority, these are: SETUP.INI, Settings.Startup, Settings,Dynamic, Workstation.Startup, Workstation.Dynamic

Examples:

Init [
  If 1 WaitingForCaptureSettings;
  [
    CaptureObj = \CaptureSettings("Section", "ValueName", &Result);
  ]
]
WaitingForCaptureSettings [
  If !Valid(CaptureObj);
  [
    { Do something with Result }
  ]
]


Case

(Engine-Level Function)

Description: | In script, this selects one of a set of parameters for execution and returns its return value. In steady state all parameters are executed, but only the value of the one matching the case condition is returned.
Returns: | Numeric
Usage: | Script or Steady State
Function Groups: | Logic Control
Related to: | ?: (If Else) | Cond | Execute | IfElse | IfThen
Format: | Case(Index, P0, P1, P2)
Parameters: |
Index
Required. Any numerical expression giving the parameter number result to return. If this value is 0, the value of parameter Parm 0 is returned.
Parm 0, Parm 1, Parm 2, …
Required. The statements to be selected by the index. Only the selected statement value will be returned. The statement in each parameter could be an expression or a value.
Comments:

The return value of this function is the return value of the parameter selected by Index, or invalid if index does not correspond to a parameter.

When used in steady state, all cases will execute on parameter change even if they are not the selected parameter statement. When used in script, only the selected parameter statement will execute.

Example:

Note that the format varies depending on whether you are writing script code or an expression. A scripting version comes first, with an expression version later.

  If 1 Main;
  [
    Case(PumpNum { Number varies from 0 to 3 },
      { 0 } PumpDesc = "Pump 0";
      { 1 } Execute(PumpDesc = "Pump 1", Diesel = TRUE);
      { 2 } PumpDesc = "Pump 2";
      { 3 } PumpDesc = "Pump 3";
    );
  ]

This sets the PumpDesc variable according to PumpNum and in the second case, uses the Execute function to accomplish more than one task based on the value of PumpNum. If setting PumpDesc was all that was needed to be done, the statement could have been shortened to use simple values rather than expressions.

  If 1 Main;
  [
    PumpDesc = Case(PumpNum,
                 { 0 } "Pump 0";
                 { 1 } "Pump 1";
                 { 2 } "Pump 2";
                 { 3 } "Pump 3";
               );
  ]

Note that this example is written as English-only for clarity. For a multilingual application, each possible description should be phrase key.

Example: (Used in a steady-state expression within a text widget - this example will not compile in a .SRC module.)

Used in a steady-state expression, the IF statement is removed, commas are used between each case, and there is no ending semicolon.

  Case([PumpSelection],
    { 0 } "Pump 0",
    { 1 } "Pump 1",
    { 2 } "Pump 2",
    { 3 } "Pump 3")

Example: Replacing a nested IfElse block

Instead of writing the following set of in-line IfElse's (where the various modes are enumerated constants)...

  Value = \DataMode == \#AVG_MODE
           ? AverageData[RowNumber]
           : \DataMode == \#MIN_MODE
             ? MinData[RowNumber]
             : \DataMode == \#MAX_MODE
               ? MaxData[RowNumber]
               : \DataMode == \#RAW_MODE
                 ? RawValue
                 : Invalid;

...use a Case statement:

  Value = Case(\DataMode,
            { 0 } AverageData[RowNumber];
            { 1 } MinData[RowNumber];
            { 2 } MaxData[RowNumber];
            { 3 } RawValue;
          );


Cast

Viewing: Reference > Function Reference > C Functions > Cast

Concepts:

Value Types

Parameter and Variable Type Checking

Reference:

VTScada Value Types

Variable Class Definitions

Variable Storage, Retention, Access

Cast

(Engine-Level Function)

Description | Takes a value and returns a different type of value, if possible.
Returns | Numeric
Usage | Script or steady state.
Function Groups | Compilation and On-Line Modifications, Variable
Related to: | ValueType
Format | Cast(Val, Type)
Parameters |
Val
Required. Any variable name.
Type
Required. A VTScada Value Types indicating what type of value should be returned.
Comments This function performs a type-cast, changing one type of value to another. Note that values that are converted to integers are truncated, rather than rounded.
If a stream longer than 65,523 characters is cast to a text string, it will be truncated at 65,523 characters.
Example:
  VarFloat = 2.61;
  VarInt = Cast(VarFloat, 1);

The value of VarInt will be set to 2.


Ceil

(Engine-Level Function)

Description: | Returns the smallest integer greater than or equal to a number (the ceiling).
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Rounding Math
Related to: | Int | Step
Format: | Ceil(X)
Parameters: |
X
Required. Any numeric expression for which the ceiling should be determined.
Comments: This function performs function similar to that of the Int function, except that it goes to the next highest number.

Example:

  A = Ceil(1.00);
  B = Ceil(1.01);
  C = Ceil(1.99);

The values of A, B and C will be 1, 2 and 2 respectively.


Change

(Engine-Level Function)

Description: | Returns a true when the value of the first parameter changes by at least the value of the second parameter.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Variable
Related to: | DeadBand | Edge | Latch | Toggle | Save
Format: | Change(Value, MaxLimit)
Parameters: |
Value
Required. Any numeric expression giving the value to check for the change.
MaxLimit
Required. Any numeric expression giving the amount by which Value must change for the function to be true. The change in Value must be strictly greater than MaxLimit for the Change function to be true.
If MaxLimit is less than zero, the function will always be true.
Comments:

The change specified by MaxLimit is the absolute value of the change so the Value is checked for an increase or decrease by this amount.
The initial value used in the comparison for the change is the value when the function is first executed upon entering a state or when the parameters become valid. This initial value is reset by functions that reset their parameters (i.e. Latch, Toggle, and Save) and by action triggers.

Value must change from a valid value to another valid value. Changing to or from an invalid value does not trigger a Change.

Example:

  Save(0, 0, 0, 0, 1, 0, 0 { Save 1 float value to disk },
       1000 { Number of records },
       50 { Buffer 50 records },
       "G:\DATA\SETPT.DAT" { file name },
       Change(sp, 0) { Trigger - any changes in sp },
       Sp { Setpoint value to log });

This shows how to use a Change function as a trigger for a Save statement to log data whenever the datum changes. Notice that by using a 0 as the MaxLimit value, all changes no matter how small are registered. When the Save statement is triggered (when data are logged), the Change statement is reset to wait for another change.

An example of how Change is used is as an action trigger follows:

  If Change(X, 0.5);
  [
  ...
  ]

The script will execute once every time x changes by more than 0.5. The Change function is reset when it is used in a action trigger and it becomes true. Suppose the following happens to x:

X (initial value) = 3.4
X (changes to) = 3.5 -> Nothing happens yet
X (changes to) = 3.9 -> Action triggers, script executes,
Change is reset

Change now waits for X < 3.4 or X > 4.4

X (initial value) = 4.1
X (changes to) = 4.2 -> Nothing happens yet
X (changes to) = 5.1 -> Action triggers, script executes,
Change is reset

Change now waits for x < 4.6 or x > 5.6

Related information:

Latching and Resetting Functions


CharCount

(Engine-Level Function)

Description: | Returns the number of bytes in a section of a buffer that matches a search character.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | Locate | Replace
Format: | CharCount(Buffer, Offset, N, Match)
Parameters: |
Buffer
Required. Any text expression giving the buffer to search.
Offset
Required. Any numeric expression giving the starting buffer position for the CharCount, starting at 0.
N
Required. Any numeric expression giving the number of bytes to include in the search.
Match
Required. Any numeric expression giving the byte (usually an ASCII code) for which to search. Match must be in the range of 0 to 255.
Comments: Offset + N must be less than or equal to the buffer length, or the return value will be invalid.

Example:

  Num = CharCount("abcdefABCDEFc" { Search buffer },
                  0 { Start of the buffer },
                  13 { Search the entire buffer },
                  0x63 { Find the character "c" });

Num is set to 2 (the two lower case "c"s match but the upper case "C" doesn't).


CheckBox

(System Library)

Description: | Draws a check box with an optional label.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | TextBox | ToolBar | VScrollbar
Format: | System.CheckBox(X1, Y1, X2, Y2, Variable [, Label, BoxOnLeft, Alignment, FocusID, BGColor, FGColor, CheckColorParm, ThreeState])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the check box and its label. The smaller of X1 and X2 will always be to the left.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the check box. The smaller of Y1 and Y2 will always be the top.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the check box and its label opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the check box, whichever is the opposite to Y1.
Variable
Required. The variable whose value is toggled by the check box.
Label
Optional. Any text expression to be used as a label with the check box. The default value is a blank label.
BoxOnLeft
Optional. Any logical expression. If true (non-0) the check box will appear to the left of the label.
If false (0) it will be to the right.
The default value is true.
Alignment

Optional. Any numeric expression that sets the alignment of the check box and its label according to one of the following options:
The default value is 0.

Value | Horizontal Alignment | Vertical Alignment
0 | Left | Top
1 | Right | Top
2 | Full | Top
3 | Left | Centered
4 | Right | Centered
5 | Full | Centered
6 | Left | Bottom
7 | Right | Bottom
8 | Full | Bottom
FocusID
Optional. Any numeric expression from 0 to 32767 for the focus number of this graphic.
If this value is 0, the check box will display its current setting, but will not be able to be set and will appear grayed out. The default value is 1.
BGColor
Optional. Any expression for the background color of the control. No default value.
FGColor
Optional. Any expression for the color of the check box label text. No default value.
CheckColorParm
Optional color to use for the check mark
ThreeState

Optional Boolean flag. If ThreeState is TRUE, then the box is shown as "filled" if Value is anything other than 0 or 1. (Invalid counts as being other than 0 or 1).

If Value is Valid and the box is filled, the next click will clear (deselect) the box.

If Value is Invalid and the box is filled, the next click will select the box. (place a check mark)

Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

If not using ThreeState, the variable must be initialized to 0 or 1.

If using ThreeState, you must force the variable to a value other than 0 or 1 in order to achieve the third "filled box" state. Clicking can only transition between selected or deselected.

The size of the check box is constant, with X1, Y1and X2, Y2 defining the position of the check box and its label.

Examples:

  System.CheckBox(90, 220, 160, 205 { Location of check box },
                   Visibility { Variable to change },
                   "Visible Switch" { Label },
                   0 { Box not on left },
                   5 { Full, center align },
                   4 { Focus ID });

or

  System.CheckBox(90, 220, 160, 205 {  Location of  check box },
                   Transparency { Variable to change },
                   "Transparent" { Label },
                   Invalid { Use default },
                   0 { Left, top align });
    { Use default focus ID }


CheckCertificateChain

Description: | Checks the chain of trust of a certificate.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Certificates
Related to: | AddCertificate | FindCertificate | GetCertificateInfo | ListCertificates | MakeSelfSignedCertificate | RemoveCertificate | SetCertificateProperty
Format: | CheckCertificateChain(CertificateBlob)
Parameters: |

CertificateBLOB

Required. A buffer holding a DER-binary encoded certificate BLOB (binary large object) of the certificate to add.
Comments

This statement verifies that the supplied certificate BLOB has a chain of trust to a trusted root certificate installed on the local computer, that the certificate has not been revoked and that it is otherwise valid.

Example:

  CertIsTrusted = CheckCertificateChain(ServerCertBlob);

This will verify that ServerCertBlob is a trusted certificate or has a valid chain of trust to a trusted root certificate. CertIsTrusted will be set TRUE if it is trusted, FALSE if it is not and Invalid if the parameter is not a valid certificate BLOB.


CheckFileExist

(System Library)

Description: | This subroutine checks for the existence of the specified file.
Returns: | Boolean
Usage: | Script only.
Function Groups: | File I/O
Related to: | CheckPathExist | CopyDir
Format: | System.CheckFileExist(FileName)
Parameters: |
FileName
Required. Any expression for the name of the file whose existence you wish to verify.
Comments: This subroutine checks for the existence of the file specified by FileName. It returns 1 if the specified file exists, or 0 if the specified file does not exist.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

 If Watch(1);
  [
    { check whether the file exists... }
    IfThen(System.CheckFileExist(SomeFile),
           ...


CheckIPMask

(Engine-Level Function)

Description: | Determines whether an IP Address is in the address ranges defined by MaskSet.
Returns: | Varies. See comments.
Usage: | Script Only.
Function Groups: | Network and Workstation
Related to: | IPMaskToText | MakeIPMask
Format: | CheckIPMask(IPAddress, MaskSet)
Parameters: |

IPAddress

Required. Any single legal IP address.

MaskSet

Required. A MaskSet constructed by one or more calls to MakeIPMask
Comments:

For advanced use only.

Returns Invalid for a bad parameter and where the specified IP address is not in the IP address range described by the MaskSet.

Otherwise, returns the index into MaskSet of the matching subnet entry. This index can be used as an input parameter to IPMaskToText to obtain the subnet address as text.


CheckPathExist

(System Library)

Description: | This subroutine checks for the existence of the specified path.
Returns: | Boolean
Usage: | Script only.
Function Groups: | File I/O
Related to: | CheckFileExist | CopyDir
Format: | System.CheckPathExist(Path)
Parameters: |
Path
Required. Any expression for the path whose existence you wish to verify.
Comments: This subroutine checks for the existence of the path specified in Path. It returns 1 if the specified path exists, or 0 if the specified path does not exist.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

 If Watch(1);
  [
    { check whether the path exists... }
    IfThen(System.CheckPathExist(SomePath),
           ...


CheckSignature

(Engine-Level Function)

Description: | Checks a digital signature with a key given a handle returned from Hash().
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | GenerateSignature
Format: | CheckSignature(HashHandle, Signature, Key)
Parameters: |
HashHandle

Required. Handle returned from a call to Hash()

Signature
Required text. The signature to be checked.
Key
Required handle to the public key, with which to check the signature. Previously obtained from any of GenerateKey(), ImportKey(), DeriveKey(). This must be an asymmetric public key
PaddingType

Optional integer. Can be one of the following values:

Value~Meaning

0~No padding is to added to the plaintext data before signing.

1~Padding is added to the data before signing in accordance with the RSASSA-PKCS1-v1_5 scheme.

2~Padding is added to the data before signing in accordance with the RSASSA-PSS scheme.

PadHashAlgorithm

Optional text value. The algorithm to be used for padding the data. The hash is then signed.
SaltLength
Optional integer. Only required for RSASSA-PSS padding. This is the length of the salt used by that scheme.
Comments none.

Example:

<
{============================ CheckSignatureSample ===========================}
{ Sample code using CheckSignature().                                         }
{=============================================================================}
CheckSignatureSample
(
  Message                     { Message to check                              };
  Signature                   { Signature for message                         };
  KeyBlob                     { Public key to check with                      };
)
[
  Protected Constant PROV_RSA_AES  = 24      { Enhanced RSA/AES provider      };
  Protected Constant KEY_SIZE      = 2048    { 2048 bit keys                  };
  Protected Constant PUBLICKEYBLOB = 6       { PUBLICKEYBLOB                  };
  Protected Constant CRYPT_VERIFYCONTEXT = 0xF0000000 { CRYPT_VERIFYCONTEXT   };

  Protected CSP               { Cryptographic context                         };
  Protected HashObj           { Intermediate handle returned from Hash()      };
  Protected Key               { Handle to signing key pair                    };
  Protected SignatureOK       { True if the signature is correct              };
]

Sign [
  If 1;
  [
    { Get cryptographic context }
    CSP = GetCryptoProvider(PROV_RSA_AES, Invalid, Invalid, CRYPT_VERIFYCONTEXT);

    { Import the public key }
    Key = ImportKey(CSP, PUBLICKEYBLOB, KeyBlob);

    { Compute a SHA-256 hash of the message }
    Hash(Message, 2 {SHA-256}, Invalid, HashObj, CSP);

    { Check signature }
    SignatureOK = CheckSignature(HashObj, Signature, Key);

    Return(SignatureOK);
  ]
]

{ End of CheckSignatureSample }
>


CheckTagGroup

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns TRUE or FALSE according to whether a tag is in the specified group.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Variable
Related to: | GetTagMode
Format: | \CheckTagGroup(TagModule, TagGroup)
Parameters: |
TagModule
Required. A tag type module or instance.
TagGroup
Required. The name of the tag group to check.
Comments:

If the tag is a member of the group, the function will return, TRUE. A list of groups can be found in the topic, Type Characteristics.

This function can be useful in Linked Tag Widgets, where you may need to check the group membership of the linked tag. There, the TagModule may be referenced as "\Root", which is the linked tag.

Examples:

    IfThen(\CheckTagGroup(TagObj, "Analogs"),
   ...
    );


ChildDocs

(Engine-Level Function)

Description: | Gets the module values for the root and all descendent modules that match the conditions defined by the second parameter. May also be called as "Child_Docs".
Returns: | Pointer to a one dimensional array
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | ModuleFileName | RUNFileName
Format: | ChildDocs(Module [, Filter])
Parameters: |
Module
Required. The module to search.
Filter

Optional. Any numeric expression that defines which modules are to be included in the returned set. Filter is formed by adding together the values from the following table. Defaults to 2 if missing or invalid.

(See: Bitwise Parameters & Operations)

Filter | Bit No. | Description
1 | 0 | Include all modules, even if they are in the same file as their parent. False to only include modules with external files (subject to bits 2 and 5).
2 | 1 | Recurse into submodules. False to include only immediate children.
4 | 2 | Include only modules whose .RUN files are out of sync with their .SRC files.
8 | 3 | Include the root module in the list, subject to bits 2 and 5.
16 | 4 | Don't recurse if the module is added to the list.
32 | 5 | Include only modules whose .SRC file exists (i.e. not just a .RUN file).
Comments: This function is used by the compiler subsystem. It returns a pointer to a single dimensioned array.

Example:

  If 1 Main;
  [
     AllList = ChildDocs(Scope(Self(), "Graphics"), 1 + 2 + 8);
  ]

The variable AllList will be set to an array containing all module values that are ancestors of module Graphics, including Graphics itself.


ChildInstances

(Engine-Level Function)

Description | Returns the object values of module instances that are children of a particular module instance (i.e. all objects whose parent is a specified object).
Returns | Object array
Usage | Script Only.
Function Groups | Basic Module
Related to: | CalledInstances | GetInstance | Instance | NumInstances | Self | Valid
Format | ChildInstances(Object [, Options])
Parameters |
Object
Required. An object value of the module instance for which to get the number of child instances.
Options

Required. Any numeric expression that defines which modules are to be included in the returned set. Options is formed by adding together the values from the following table:

(See: Bitwise Parameters & Operations)

Options | Bit Number | Description
1 | 0 | Include all modules, even if they are in the same window as their caller. False to include only (root) modules for modules in separate windows.
2 | 1 | Recurse into child module instances of children. False to include only modules whose immediate parent is the module instance referenced by the Object parameter.
4 | 2 | Group all instances of the same module into an array and store that array of object values in the element of the returned array, instead of the object value.
Comments The return value is an array of objects that are called from Object. If no instances are called from Object, Invalid is returned.

Example:

  i = -1;
...
  If i == -1;
  [
    NumKids = ChildInstances(Self());
    i++;
  ]
  If Valid(NumKids [i]);
  [
    Slay(NumKids[i], 0);
    i++;
  ]

The first If statement and script creates an array of object values to all instances that are children of the current module. The second If and script slays all of these instances. Notice that in the case of the first script, the action trigger must be based on i rather than on a Valid test of numKids. If this were not the case and !Valid(numKids) was used instead, then, if there were in fact no child instances of this module, ChildInstances would return invalid, and an "if one" (infinite loop) condition would occur.


Circle

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Draws a circle on the screen.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Arc | Ball | Box | Ellipse | GUIEllipse
Format: | Circle(X, Y, Radius, Color, Width)
Parameters: |
X
Required. Any numeric expression giving the X coordinate for the center of the circle on the screen.
Y
Required. Any numeric expression giving the Y coordinate for the centre of the circle on the screen.
Radius
Required. Any numeric expression giving the radius of the circle specified in units of X screen coordinates.
Color
Required. Any numeric expression giving the color of the circle.
Width
Required. Any numeric expression giving the width of the circle wall in units of X screen coordinates. The width is always rounded to result in an odd number of pixels on the screen. The minimum width displayed will be 1 pixel.
Comments: This statement has been superseded by the GUIEllipse function and is maintained for backwards compatibility only.
As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.


CleanModule

(Engine-Level Function)

Description: | Removes the flag that marks when a module that has been changed programmatically and would therefore have its changes saved to disk were this flag not cleared.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Advanced Module
Related to: |
Format: | CleanModule(Module)
Parameters: |
Module
Required. Any expression giving a module to clean.
Comments: When a module's code is changed through VTScada script (for example, by using a function such as AddVariable) a flag is set in the engine to indicate that the associated script file must be updated before shutdown. This function clears that flag, preventing the update.
This function can be used to make transitory code changes (such as, by the Expression Manager) or to reverse code changes that have been undone (page editing).

This function requires a module handle as its sole parameter such as the return value of a LoadModule function.

Example:

    X = LoadModule(…);
    { … module is modified by code … }
    CleanModule(X);


ClearModule

(Engine-Level Function)

Description | Deletes the contents (all variables and states) of a module without removing the module itself.
Warning | This function should be used only by advanced programmers.
Returns | Nothing
Usage | Script Only.
Function Groups | Compilation and On-Line Modifications, Advanced Module
Related to: | ClearState | DeleteModule
Format | ClearModule(Module)
Parameters |
Module
Required. Any expression giving a module to clear.
Comments If there are any instances of the module running, ClearModule does nothing and returns.


ClearState

(Engine-Level Function)

Description: | Deletes all of the statements in a state.
Warning | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, States
Related to: | ClearModule | DeleteState
Format: | ClearState(State)
Parameters: |
State
Required. Any expression giving the code value of the state to delete.
Comments: This statement is used to delete the contents of a state without removing the state itself or altering the document file.


ClearVarMetaData

(Engine-Level Function)

Description: | The opposite of SetVarMetaData, this statement removes all metadata associated with a variable.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Dictionary
Related to: | GetVarMetadata | SetVarMetadata
Format: | ClearVarMetadata(Var)
Parameters: |
Var
Required. Any expression giving the variable whose metadata base value is to be removed.
Comments: none


Click

(Engine-Level Function)

Description: | The Click function returns a Boolean TRUE if the click happens within a target area and the click is done with specified button combination.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Graphics, Locator, Window
Related to: | LocSwitch | Pick | SetXLoc | SetYLoc | Target | WinLocSwitch | WinXLoc | WinYLoc | XLoc | YLoc
Format: | Click(X1, Y1, X2, Y2, Button)
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the screen area ("target").
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the screen area ("target").
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the "target" opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the "target", whichever is the opposite to Y1.
Button

Required. Any numeric expression giving the locator button combination that will cause the Click function to return a true value when the locator cursor is within the "target" screen area. The codes for this parameter are as follows:

Button | Button Locator
0 | No buttons
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the value is:

  • multiplied by 8:

the meaning for multiple buttons pressed becomes "OR", rather than "AND". For example, to accept any button on a 2 or 3 button mouse, use 56 (8 * 7). To accept the left mouse button, regardless of whether the right button is pressed, use 32 (8 * 4).

  • increased by 64:

the function will become true when the mouse buttons are released, rather than when they are pressed.

  • increased by 128:

the buttons must be double-clicked

Comments:

This function returns true if the locator position is within the boundaries of the "target" as defined by (X1,Y1) - (X2,Y2), and the locator button value matches the Button parameter. If the locator is not installed, the function will return false (0).
The Click function is a level sensitive function, which means that the mouse button(s) must be pressed when the function is executed or it will return false. This means that a brief press of a mouse button with the cursor in the correct target area might not be picked up by the Click function if the system is heavily loaded. Use the Pick() function for action triggers, rather than Click().

If Click is used as an action trigger it will not reset. The action will continue to trigger as fast as possible as long as the Click is true. This is different from Pick, which would trigger once and be reset by the action trigger.

Example:

  Box(100, 500, 500, 100 { Coordinates for the box },
       1 { Solid style },
       5 { Width in screen coordinates },
       Cond(Click(100, 500, 500, 100, 56 { Color depends on click }),
            12 { Color is red when clicked     },
            7  { Color is light gray otherwise })
      );

This draws a blue box on the screen. If the mouse button is inside the square and any button combination is held down, the box will turn white. If the mouse should move outside the box, or if all buttons are released, the Box color will turn back to gray. Note that the Box coordinates and the coordinates for the Click function are the same by choice - they are not required to match. That is, the coordinates in the Box specify where to draw the box, and the coordinates in the Click specify where to look for a mouse click.


ClientSocket

(Engine-Level Function)

Description: | Opens a client WinSock-compliant socket stream and returns a stream value, or a numeric error code.
Returns: | Varies - see comments
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | CloseStream | ServerSocket | SocketAttribs | SocketServerEnd | SocketServerStart | SocketWait | SRead | SWrite | LargeSocketWrite
Format: | ClientSocket(Protocol, Host, Service, TransmitLen, ReceiveLen, Flush[,ProtocolFilters, InboundPortOrStream, IPOut, PortOut, MatchRemoteUDPSourcePort])
Parameters: |
Protocol
Required. Any numeric expression giving the protocol to be used. This must be a valid 0 for TCP/IP protocol or a valid 1 for a UDP protocol.
Host

Required. Any text expression giving the host name or TCP/IP address to connect.

For a ClientSocket where bi-directional UDP communication with a remote system is required and where the client socket defines InboundPortOrStream as a port, the Host parameter must be populated with the expected IP address.

To ensure reliability, you should acquire the IP address by using GetHostByName.

Service
Required. Either any text expression giving the service name to connect, or any numeric expression giving the port number with which to connect.
TransmitLen
Any numeric expression for the number of bytes to buffer when transmitting. The value must be a signed long integer, where only positive values are useful.
If the application is running on a operating system of Windows 7 / Server 2008 R2, or later, and the value is set to zero, then Windows will manage the appropriate buffer size for the link speed and latency.
If you set the buffer size, the value should match or be larger than the largest message that is expected.
A high bandwidth / high latency link will require a larger size to achieve optimum efficiency, but the exact size can be determined only by empirical testing.
ReceiveLen

Required. Any numeric expression for the maximum number of bytes to buffer by VTScada when receiving. Additional buffering will be handled by WinSock.
The value must be a signed long integer, where only positive values are useful (an error will be returned if the value is not greater than zero). The value should match or be larger than the largest message that is expected.
A high bandwidth / high latency link will require a larger size to achieve optimum efficiency, but the exact size can be determined only by empirical testing.

Note: Behavior of this parameter varies depending on ClientSocket is being used for UDP or TCP communications.

  • When used with UDP communications, the provided size is passed to the system to define the size of the Windows receive buffers as well as those within VTScada.
    The system receive buffer size will be set to the larger of the ReceiveLen parameter or the current default receive buffer size for the windows buffers. An upper limit of 4 MiB may be provided for the system level buffer. If the ReceiveLen parameter is greater than that, the Windows buffer will be restricted to 4 MiB.
  • When used with TCP communications, VTScada will use the Windows default receive buffer size.
Flush
Required. Any logical expression. If true, the transmit buffer will be flushed (transmitted) after each write to the stream.

This normally should be false to reduce network traffic by allowing the driver to group smaller packets into a single larger packet.
ProtocolFilters

An optional array that specifies what filtering should be applied to socket connections. The order in the ProtocolFilter array determines priority.

Each filter item consists of two elements where the first is the filter type ("TLS/SSL", "VIC", "NULL" and "PROXY") The second is a value dependent upon the filter type, noting that there is no second value for "VIC" and "NULL" types. The certificate subject name is not normally used on a client connection.

Examples:
For TLS/SSL the value is the subject name in the certificate, given as "CN=host.example.com".
For PROXY it is a string.

     PFilter = New(2);
     PFilter[0] = New(2);
     PFilter[0][0] = "SSL";
     PFilter[0][1] = "CN=host.example.com";
     PFilter[1] = New(2);
     PFilter[1][0] = "NULL";
     PFilter[1][1] = "";
InboundPortOrStream
Optional. Used only in connection with a UDP connection.

If set, this should be an existing UDP stream as returned from a ServerSocket, for the same remote IP as is being connected to.

Incoming UDP datagrams on the ServerSocket stream will continue to be received, but the stream can also be used for datagram transmission. If InboundPortOrStream is not a stream, it is interpreted as a local port number on which to listen for inbound datagrams.

The stream returned by ClientSocket can be used, in both cases, for datagram transmission and reception.
IPOut
Optional Used to identify the IP of the network interface card from which to transmit UDP datagrams. LocalIP s of use on multi-homed machines to identify the physical IP binding to use. No default is provided.
PortOut
Optional. Used to identify the local port from which to transmit UDP datagrams No default is provided.
MatchRemoteUDPSourcePort

When Invalid or FALSE (default) datagrams transmitted from any UDP port on the remote host to InboundPortOrStream on the local computer will be accepted and routed into the UDP stream returned from ClientSocket.

When TRUE, only datagrams from the remote host sent to InboundPortOrStream on the local computer and sent from the same port as that to which this UDP stream will transmit, will be routed into this UDP stream.

All other datagrams from the remote host sent to the UDP port this ClientSocket is listening on will cause a SocketWait trip, assuming you have an active ServerSocketStart monitoring the local UDP port. The intent of this is to provide a means whereby UDP datagrams from different ports on a remote device can be separated into different UDP streams. MatchRemoteUDPSourcePort provides a method to override this behavior when required.

Comments

This function will return the integer 32767(short) when the socket is created but not yet connected, a stream value when the connection is made, or a short integer error code. If the socket connection is lost (server shutdown ) the stream is closed and set invalid ( no error code returned).

Note that codes 804 through 808 are relevant only for ClientSockets that operate in TLS mutual authentication mode.

Client Socket Error Codes

Error Code | Description
-2 | Failed to open the certificate store. This is likely because the user account you are running VTScada under has insufficient privilege
-21 | Public/private key pair mismatch. The private key stored for a certificate does not match the private key. Reinstall your certificate and private key pair.
-87 | Insufficient private key permission. The user account you are running VTScada under has insufficient privilege to use the private key associated with the certificate.
-257 | Certificate expired. Renew it.
-271 | Failed to find certificate. Check the spelling of the certificate name if you typed it. Ensure that the certificate is installed in the correct Certificate Store.
-802 | Neither the Common Name (CN) or Subject Alternative Names (SAN) used in the X.509 certificate match the target device name.
-803 | There is no Local Security Authority (LSA) context for the operation
-804 | The clocks on the client and server machines are too far skewed.
-805 | Untrusted certificate, the server's certificate is untrusted by the client or vice-versa.
-806 | Bad TLS handshake. Often caused by failing to provide a client certificate when the server requires one.
-807 | The certificate given to the server is not yet valid.
-808 | The certificate given to the server has expired.
-1312 | Failed to load private key. Usually insufficient permission or missing private key.
-10051 | WSAENETUNREACH - No suitable source address can be found for the destination.
-10060 | WSAETIMEDOUT - No connection can be made.
-11001 | WSAHOST_NOT_FOUND - A bad name was supplied, such that no IP address can be found.
-10061 | Cannot connect to Host at port number specified
-11004 | Cannot find requested host

Other socket errors may return individual error codes, refer to the MSDN documentation for Windows Sockets Error Codes, currently found at: https://docs.microsoft.com/en-us/windows/desktop/winsock/windows-sockets-error-codes-2

The client socket function has a slightly different behavior, depending on whether the connection is made via TCP or UDP. The difference is explained in the following two diagrams.

Client Sockets on TCP:

  1. A ClientSocket statement runs and returns an integer value.
  2. An outbound connection is made.
  3. When the connection is established, the stream is triggered.
  4. The stream trigger causes the value returned from 1 to become a stream value.
  • If the connection attempt fails at any point, the value returned from 1 will become a negative integer, representing an error code

Client Sockets on UDP:

  1. A ClientSocket statement runs and returns a stream value.
  2. Stream writing statements are used to write data to the stream
  3. A UDP datagram is issued to the target device each time a write is done by script code.

Example:

Init [
  If 1 Main;
  [
    Client = ClientSocket(0 { TCP/IP protocol },
                          "WServer" { Host },
                          20000 { Port number },
                          1024, 1024 { Buffering },
                          1 { Flush after writes });
  ]
]
Main [
  { If stream connection lost, retry connection }
  If TimeOut(! Valid(Client), 2) Init;
  { Exit if return value valid and not a stream }
  If ValueType(client) != 8 Error;
  { Read stream data as received or on demand with "r" key }
  If GetStreamLength(Client) > 0 || MatchKeys(2, "r");
  [
    SRead(Client, Concat("%", Concat(GetStreamLength(Client),
          "c")), data);
  ]

  { Write stream data to server every second }
  If TimeOut(1, 1);
  [
    SWrite(Client, "%s", Concat(" Hello World ",
           Time(Seconds(), 3)));
  ]
  { Close stream if window closed, then stop }
  If WindowClose(Self());
  [
    CloseStream(client);
    Slay(Self(), 1) ;
  ]
  { Display received data and connection status }
  ZText(10, 150, Data, 2, 0);
  ZText(200, 100, Cond(ValueType(Client) == 8,
  "Connected", "Not Connected"), 10, 0);
]
Error [
  { Display error code }
  ZText(100, 130, Concat("Client error code : ", Client),
        10, 0);
]


ClipboardGet

(Engine-Level Function)

Description: Returns the current contents of the system clipboard as a string. This function enables an application to perform text "paste" operations.
Returns: Text
Usage: Script Only.
Function Groups: Clipboard, String and Buffer
Related to: ClipboardPut
Format: ClipboardGet()
Parameters: None
Comments:

This function can be used to obtain the current contents of the clipboard as a string. If the clipboard does not contain a textual value, then the function will return invalid.

Do not use a clipboard operation as a subroutine parameter if the application is accessed by thin clients.

Within an Anywhere Client session, this function does nothing.

Example:

  If 1 WaitDone;
  [
     { Get the clipboard text for processing. }
    Content = BuffStream(ClipBoardGet());
    ...
  ]
]
WaitDone [ ...


ClipboardPut

(Engine-Level Function)

Description: | Set the current contents of the system clipboard to a string. This function enables an application to perform text "copy" or "cut" operations.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Clipboard, String and Buffer
Related to: | ClipboardGet
Format: | ClipboardPut(String)
Parameters: |
String
Required. Any text expression that will be copied to the system clipboard.
Comments:

This function can be used to set the current contents of the clipboard. If the parameter is not a text expression, then the contents of the clipboard are left unchanged. Otherwise, the current contents of the clipboard are overwritten.

Do not use a clipboard operation as a subroutine parameter if the application is accessed by thin clients.

Within an Anywhere Client session, this function does nothing.

Example:

...
  { Having populated DataString with the relevant information, place it into the clipboard for the user }
    ClipboardPut(DataString);
    Return();
  ]
]


ClosePopUp

(Display Manager Library)

Description: | Close the windowed page, from within which this function is called.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics
Related to: | | ShowPage | StopPage |
Format: | \DisplayManager.ClosePopUp()
Parameters: | None
Comments:

This subroutine will close only the current pop-up window instance that issues the call, without closing any other instances of the same pop-up window.

It will close only pop-up pages and does nothing when called from non-windowed page.

Examples:

  If Cancel;
  [
    \DisplayManager.ClosePopUp();
  ]


CloseStream

(Engine-Level Function)

Description: | Closes and flushes any type of open stream and returns its own error code.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | BuffStream | FileStream | PipeStream | StreamEnd
Format: | CloseStream(Stream[, CloseType])
Parameters: |
Stream
Required. Any expression that returns a stream value.
CloseType

Optional. Short integer with the following definitions:

0 | STREAM_CLOSE_NORMAL, // Graceful shutdown - finish what you're doing first
1 | STREAM_CLOSE_HARD, // Abortive shutdown - throw away outstanding work. To be used only when there is a valid reason such as the detection of a malicious request.
2 | STREAM_TRANSACTION_END, // Flush the outgoing message and wait for the other end to close the connection.
Comments: The return value is true if the stream is successfully closed and invalid otherwise. This function closes the stream passed to it.
If the stream is invalid, or the stream is already closed, nothing happens.

Example:

  If GetStreamLength(Stream) == 0 && ! Valid(CloseOK);
  [
    CloseOK = CloseStream(Stream);
  ]

This example checks to see if the stream has any data in it, and if it is empty and has not already been closed, closes it, setting CloseOK to 1 if the stream were closed and invalid otherwise.


Cls

(Engine-Level Function)

Description: | Clears the screen and sets its background color.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Color, Graphics, Window
Related to: | GetSystemColor
Format: | Cls(Color)
Parameters: |
Color
Required. Any numeric expression giving the color to which the screen should be set.

You may use any of the following methods to specify the color:

  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.

Note that Cls will ignore the alpha channel if you provide the color as an <AARRGGBB> string, since the background color of a window cannot have an alpha value that is different from the window itself.

Comments:

This statement sets the background color for the window that the function is executed within. It will clear the screen but any layered graphics such as GUI or Z-graphic functions will be redrawn.

The description of the color parameter mentions that Cls will ignore alpha (transparency) values. Note also that you cannot set the background color of windows that use their background as a transparency mask (bit 18 set in the Style parameter).

Cls will work on both workstations and on thin clients.

Example:

  Cls(1);

This sets the window background color to dark blue.


CodeText

(Engine-Level Function)

Description: | Returns information (usually the source code text), matching the given code value.
Warning: | This function should be used only by advanced programmers.
Returns: | Varies (see 2nd parameter).
Usage: | Script Only.
Function Groups: | Advanced Module
Related to: | SetCodeText
Format: | CodeText(CodeVal[, Type])
Parameters: |
CodeVal
Required. Any code value giving the statement or function within a statement whose text to be read.
Type
Optional numeric expression. Controls what will be returned by the function according to the following table:
Type | Description
0 | default. Return the text for the expression.
1 | Return the offset in the file for the start of the expression.
2 | Return the size (number of bytes) of the expression.
Comments: Returns the source code text, offset or size for the provided code value. Typically followed by a SetCodeText call, which would then update the source code with new text.


ColorSelect

(System Library)

Description: | Color Selection Tool. This module draws a color selection button and its accompanying display area.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Color, Graphics
Related to: | Bevel | CheckBox | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | TextBox | ToolBar | VScrollbar
Format: | System.ColorSelect(X1, Y1, X2, Y2, Color [, BtnLabel, BtnOnLeft, Standard, VertAlign, FocusID, OpenDialog, NoTrans, BGColor, FGColor, ShowIndex])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the button or color display area. The smaller of values X1 and X2 will always be the left side.
Y1
Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the button and color display area. The smaller of values Y1 and Y2 will always be the top.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the button or color display area opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the button and color display area, whichever is the opposite to Y1.
Color
Required. The variable whose value is set to the index of the chosen color.
BtnLabel
Optional. Any text expression to be used as a label on the color selection button. No default if missing or Invalid.
BtnOnLeft
Optional Any logical expression. If true (non-0) the button will appear to the left of the color display area, If false (0) it will be to the right. The default value is true.
Standard
Optional Any logical expression, If true (non-0) the button and color display area will be standard system size. If false (0) they will be sized to fit their boundaries and VertAlign will be ignored. The default value is true.
VertAlign

Optional Any numeric expression that sets the vertical alignment of the button and display area according to one of the following options:

Value | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

If Standard is true, this parameter is ignored.

The default value is 0, top alignment.

FocusID
Optional Any numeric expression from 0 to 32767 for the focus number of the button. If this value is 0, the current value of Color will still be displayed, but it will not be able to be set because the button will appear grayed out. The default value is 1.
OpenDialog
Optional Any logical expression. If true (non-0) the dialog will be open. If false (0), it will be closed. The default is true.
NoTrans
Optional Enables you to turn off the transparent color option. If NoTrans is set to true (1), then the transparent color option will be turned off.
If NoTrans is set to false (0), then the transparent color option will be turned on. (The transparent color option is set within the color selection dialog using the "Transparent" (or "Transparent Brush" or "Transparent Pen") check box.)
No default value is provided.
BGColor
Optional. Any numeric expression for the background color of the control. No default value.
FGColor
Placeholder for the foreground color of the control. Not currently implemented.
ShowIndex
Optional. Color index is shown when TRUE. Defaults to TRUE if not specified.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

If the button and display area are set to be standard size, the button size will remain a constant size (101 x 31 pixels) regardless of the boundaries of the defined area, but the display area will vary between a minimum (square) size to a maximum length equal to the length of the button, depending on the size of the bounding area. After the maximum display area size has been reached, the button and area will be fully justified to cover the entire width of the defined area (the vertical alignment will be set by the value of VertAlign).

For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Examples:

  System.ColorSelect(10, 300, 210, 200 { Location of btn/display },
                      MyColor { Variable storing color },
                      "Set Pipe Color" { Button label   },
                      1                { Button on left },
                      1                { Standard sizing },
                      1                { Center btn/display },
                      3                { Focus ID of button });


Combine

Description: | Performs a Merge2 operation with automated conflict resolution and change priority.
Returns: | Merge buffer
Usage: | Script Only. (always called as a subroutine)
Function Groups: | Configuration Management
Related to: | Diff | Merge2 | Merge
Format: | \AppLayer.Combine(Source, Diff1, Diff2, SrcPath, pFail)
Parameters: |
Source
Required. The buffer or stream to be modified
Diff1
Required. High priority diff to merge to Source.
Diff2
Required. Low priority diff to merge to Source.
SRCPath
Required. Full file path for the origin of the Source buffer.
pFail
Required. Pointer to a variable in which an error message will be returned.
Comments:

This module must be called as a subroutine.

This function is guaranteed to return a result, however it will discard changes if unable to merge them without conflict. It is the recommended method for combining different change paths against standard VTScada file types (settings files, source files, tag files, etc.).
Changes from the high priority diff are treated preferentially to changes from the low priority diff when resolving conflicts. If the operation fails then the result will be the original buffer modified by the high priority diff only. Failure is indicated by the pFail parameter being set to a non-zero value that is typically a string detailing the type of failure.

Notes:

  • All Tag file conflicts are resolvable, Combine does not fails on tags.
  • Conflicts of Adjacency (where two change regions share an edge but do not overlap) are resolved for all non-tag files.
  • Simultaneous Addition Conflicts (where two pure addition changes coincide) are resolved for Page, Menu, Setting, and PageNote files.
  • Specific segments of AppRoot files are parsed and rebuilt allowing for all types of conflicts to be resolved, these are additionally checked for duplicate entries, which are removed.

The results of conflict resolution are passed to the Mend function to generate complete merged file buffers. This module returns a simple merge of the high priority diff and the source buffer should conflicts occur and conflict resolution fail. In this case *pFail is set to an error string that describes the failure in a human-readable form.


COMClient

(Engine-Level Function)

Description: | Instantiates COM objects that do not possess a user interface.
Returns: | COM client interface
Usage: | Script or steady state.
Function Groups: | COM
Related to: | ActiveX | COMEvent | COMStatus | Caller
Format: | COMClient(ObjectIdentifier, ObjectContext, EventSearchScope[, EventParent, EventCaller])
Parameters: |
ObjectIdentifier

Required. Specifies a unique identifier for the object to be instantiated. It may take one of the following forms:

  • a text string representing a ProgID (e.g. "Excel.Application").
  • a textual GUID, in registry format (e.g. "{00020812-0000-0000-C000-000000000046}").
  • a binary GUID (e.g. the result from "GetGUID(1, 00020812-0000-0000-C000-000000000046)").

ObjectContext

Required. If valid, this object specifies the contexts in which it is permissible to instantiate the COM object.

A subset of values taken from the CLSCTX enumeration is supported. Possible values are:

  • CLSCTX_INPROC_SERVER (1): The COM object is instantiated in the VTScada process (i.e. by a DLL).
  • CLSCTX_LOCAL_SERVER (4): The COM object is instantiated in a separate process (i.e. by an .exe, but only on the same machine upon which VTScada is running.
  • CLSCTX_SERVER (13): Any of the above. This is the default and permits the COM object to be instantiated wherever the "class factory" (which performs object instantiation) sees fit.

EventSearchScope

Required. May be any expression that yields a module value or object value. This parameter specifies the scope in which to search for event subroutines. If missing or invalid, the COM events will not be enabled.

EventParent

Optional. May be any expression that yields an object value. If present, specifies the context that is used to resolve scope for event subroutines.
If absent or Invalid, defaults to Self().

EventCaller

Optional. May be any expression that yields an object value. If present, specifies an "auxiliary" context for event subroutines. An event subroutine can retrieve this value using Caller(Self()).
If absent or Invalid, defaults to Self().
Comments:

COMClient instantiates a COM object. Generally this statement is used to instantiate COM objects that do not possess a user interface. If the object does display a user interface, then the user interface will appear in a window created and owned by the object. It is more usual to use the ActiveX statement to create a COM object that has a user interface.

If the statement succeeds, a COM client interface is returned, allowing subsequent access to the object. If the statement fails, Invalid is returned.

Arrays indexes are deliberately offset by -1 so that a 1-based array in the object becomes a 0-based array in script.

EventSearchScope specifies the location where the event subroutines for this COM object instance may be found. Each event subroutine is named after the corresponding event produced by the default outgoing interface for the COM object. If the COM object generates an event for which an event subroutine cannot be found, the COM object is informed that event handling for that event is not implemented.

When an event subroutine is run in response to an incoming event from the object, the parent and caller for the subroutine are as specified by EventParent and EventCaller. The event subroutine may update any of its parameters, and any that are defined as [in, out] or [out]. These will be returned to the COM object on completion of the event subroutine. The event subroutine should return an integer value, which is returned to the COM object as the result of the event. A value of 0 indicates the event completed successfully.

If the COM object to be instantiated is an inproc server object (i.e. it is a DLL) then it must be a 64-bit COM server for 64-bit VTScada and a 32-bit COM server for 32-bit VTScada. If it is instantiated out-of-process (i.e. it is an .EXE) then either 32-bit VTScada or 64-bit VTScada can work with either 32-bit or 64-bit COM servers.

If used in a script, the COM object will remain instantiated until the last reference to that object has been invalidated. You assign the return value of the COMClient script statement to a variable, and the COM object will remain instantiated as long as that variable or any other variable holds a copy of the COM Client Interface handle. Only when the last copy of the COM Client Interface handle has been destroyed will the COM object be destroyed.

If used in a steady-state statement, the COM object will only remain instantiated while the steady-state statement is still running. In other words, a change of state or destruction of the module instance that is running the statement will cause the COM object to be destroyed. Any variables that hold a handle to the COM Client Interface will be invalidated at that time.

Example:

{ If writing data to Excel, you will need an Excel COM object... }
Init [
  If 1 Main;
  [
    ExcelIF = ComClient("Excel.Application");
    { check the status: }
    ErrCode = ComStatus(ExcelIF);
  ]
]


COMEvent

(Engine-Level Function)

Description: | Sets an event subroutine context for an existing COM client interface.
Returns: | Text
Usage: | Script Only.
Function Groups: | COM
Related to: | ActiveX | COMClient | COMStatus
Format: | COMEvent(COMClientInterface [, EventSearchScope, EventParent, EventCaller])
Parameters: |
COMClientInterface
Required. A COM client interface handle returned from a COMClient or ActiveX statement.
EventSearchScope
Optional May be any expression that yields a Module or an object value. If present, specifies the scope in which to search for event subroutines. No default value is provided.
EventParent
Optional May be any expression that yields an object value. If present, specifies the context that is used to resolve scope for event subroutines. If absent or Invalid, defaults to Self().
EventCaller
Optional May be any expression that yields an object value. If present, specifies an "auxiliary" context for event subroutines. An event subroutine can retrieve this value using Caller(Self()). If absent or Invalid, defaults to Self().
Comments: The COM client interface specified as the first parameter may or may not already have an event subroutine context associated with it. This function supplies a new context that destructively replaces any existing context. Use of this function enables dynamic modification of the event subroutine context. The context may also be dynamically set if the COMClient or ActiveX function is being run in steady state, by simply changing the parameters of the steady-state statement. It is more usual to use this function for COM client interfaces that are created by a script statement.

EventSearchScope specifies the location where the event subroutines for this COM object instance may be found. When an event subroutine is run in response to an incoming event from the object, the parent and caller for the subroutine are as specified by EventParent and EventCaller.


CommaFormat

(System Library)

Description: | Returns a number as text with embedded commas.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Math - Generic Functions, String and Buffer
Related to: | FormatNumber | Format |
Format: | \System.CommaFormat(Value)
Parameters: |
Value
Required. Any integer expression giving the value to be formatted.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Note that the return value is a string, not a number. If used with an I/O and Calculations tag, ensure that the type is set to String, not Analog.

Example:

  System.CommaFormat(123456);

Returns "123,456".


CommandLine

(Engine-Level Function)

Description: | Returns any command line arguments as a text string.
Returns: | Text
Usage: | Script Only.
Function Groups: | Software and Hardware
Related to: | Version | SerialNum
Format: | CommandLine()
Parameters: | None
Comments: | None

Example:

If VTScada was started from the Windows Program Manager "Run" option with:

VTS User423 Stn62

then any application with the following line:

  ZText(10, 10, CommandLine(), 12, 0);

would print out in the upper left hand corner of the window:

User423 Stn62


Commission

(Alarm Manager module)

Description: | Commission the alarm by adding it to the Configured list, or modify an existing alarm's configuration.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Decommission | GetAlarmConfiguration | EvaluateAlarm | SetSuppressed
Format: | \AlarmManager\Commission(AlarmObj, CfgStructure[, Value, ValueTimestamp, SuppressConfigEvent, AlarmDB, MachineID, CustomDescription])
Parameters: |
AlarmObj
Required. The alarm object. Normally, the object pointer to the tag within which the alarm is being commissioned.
CfgStructure
Required. A structure of alarm configuration parameters (for example, Name, Area, Description...). Normally obtained by a call to \AlarmManager\GetAlarmConfiguration. See Alarm API Structure Definitions for more details.
Value
Optional numeric. Current value to evaluate, based on the new configuration.
ValueTimestamp
Optional UTC timestamp of the value. Defaults to the current time.
SuppressConfigEvent

Optional Boolean. If TRUE, no transaction record will be stored for this call to Commission. Should be used for alarm parameters that may be updated often due to being set by tag values or expressions rather than constants. Defaults to FALSE.

Note that configuration events (for example, "Modify") are automatically filtered from the History list. Operators must enable the display of these events with the "Show Configuration Events" tool of the Alarm List.

AlarmDB
Optional name or object. The alarm database to be used for this alarm. Not necessary if the alarm object is valid.
MachineID
Optional. The workstation ID to be associated with the alarm. Defaults to the current workstation.
CustomDescription
Optional. Used only if Value is provided and the alarm activates/clears/trips. Supercedes the Description from the CfgStructure.
Comments:

Commission should be used when creating an alarm, or when updating that alarm's configuration. It will always generate a new call to EvaluateAlarm with the given value of the trigger, evaluating that against the current setpoint and comparison function.

Commission will store the alarm's object and its Root value in a dictionary of alarm names. This gives an efficient look-up table to get an alarm object.

After an alarm has been commissioned, further calls to this function will update that record in the alarm database. A call to \AlarmManager\Evaluate is made automatically as part of each call to Commission.

Note: For the sake of creating efficient code, commission should never be used as a substitute for EvaluateAlarm. Use commission only when creating or changing alarm configuration, not when handing new values to the alarm to be evaluated against the setpoint.

Example:

The following would typically be found in a tag's Refresh state. This alarm will trigger when the tag's value becomes 1.

IfElse(Valid(Name), Execute( { create or obtain the configuration structure for this alarm }
                             Cfg          = \AlarmManager\GetAlarmConfiguration(Root.UniqueID);
                               { update the property values in that structure }
                             Cfg\Name     = Root.UniqueID;
                             Cfg\Area     = Area;
                             Cfg\Priority = PriorityValue;
                             Cfg\Setpoint = 1;
                             Cfg\Function = \AlarmManager\ALM_FUNC_EQUAL;
                             { ... other configuration properties as required ... }
                               { commission, or update the commission of, the alarm }
                             \AlarmManager\Commission(Root, Cfg, Value);
                          );
);


CommitEditedFiles

Description: | This function compiles and commits edited files if the compile succeeds.
Returns: | Object (which becomes Invalid upon completion)
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | EditFile | DirectApply
Format: | \AppLayer\CommitEditedFiles(User, Comment, AlreadyHasLock[, ReloadOnFailure, pFail, RSema, SuppressAudit])
Parameters: |
User
Required. The user performing work on the repository's working copy.
Comment
Required. Text that will be stores with the repository commit.
AlreadyHasLock
Required. Boolean indicating whether we already have a working copy lock.
ReloadOnFailure
Optional Boolean. If set TRUE, then if the files cannot be integrated into a running system, the files are reverted and no reloading of the reverted files is performed.
If set FALSE, then the reverted files are reloaded.
This can be set to false when you are sure that none of the changes being committed have been integrated into a running application.
Defaults to TRUE.
pFail
Optional pointer to a Boolean. Set TRUE upon failure.
RSema
Optional repository semaphore. If provided, it is essential that you also have the working copy lock.
SuppressAudit
Optional Boolean. Set TRUE to suppress the audit the commit. This is typically done because you are guaranteed to do another commit before you give up the WC lock.
Defaults to FALSE.
Comments:

This helper function manages the Working Copy files by applying a set of file changes indicated in prior EditFile calls.
Typically the caller will have the working copy lock and this call is made using only the first three parameters, with the third parameter set TRUE. This operation returns an object that becomes invalid upon completion.

If the compile does not succeed, this function will revert the compilation changes. By the time this launched module terminates, the Modified dictionary is always emptied.

This module launches a worker module into the Layer so that the operation is not interrupted by this module's caller being slain.


CommitFocused

Description: | This function causes any edit field, while being edited, to output the value currently found in that field.
Usage: | Script Only.
Related to: | NextFocusID
Format: | CommitFocused(contextToCommit);
Parameters: |
contextToCommit
Required. The object that contains the edit control to commit, or it's caller within the same window.
Comments:

This function causes any edit field that the user is currently editing to output what the user has written prior to the function call. Here, "edit fields", includes those created by \Sytem.Edit, WinEditCtrl, or an editable System.DropList or WinComboCtrl.

This call will cause that control's trigger value to transition to 2 as if the control has lost the focus, but does not actually cause the control to lose the focus.

An edit field will automatically output its changes when the user changes focus away from the edit field, therefore this function is not necessary most of the time. It becomes useful if you want to commit what the user has typed without the field necessarily losing focus, for example if when the user clicks something that does not take the focus, as is the case with many controls within the context of the VTScada Internet Client (VIC). If your UI has a focusable button that the user must click after making changes, then there is no need to call CommitFocused.

CommitFocused will only have an effect on a focused graphic if it is within the call tree under the object identified by the sole required parameter. That object must be the one that contains the WinEditCtrl function, or it must be that object's caller, or its caller's caller, etc....

Example:

Illustrates that you must wait for triggers to resolve after calling CommitFocused:

 { Automatically close dialog after 5 minutes, committing what the user has done so far. }
  If TimeOut(1, 60 * 5);
  [
    CommitFocused(Self());
    ForceCloseWindow = TRUE;
  ]

  If (WindowClose(Self()) || ForceCloseWindow) && PickValid(Trigger, 1);
  [
    ForceCloseWindow = FALSE;
    ShowWindow = FALSE;
  ]


Compile

(Engine-Level Function)

Description: | Compiles text and creates a new function. The type of return value is determined by the input parameters.
Warning: | This function should be used only by advanced programmers.
Returns: | Varies
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications
Related to: |
Format: | Compile(FuncNames, OpCodes, Number, Module, Script, Sense, Stream, ClassBuffer, NumClass, TStateBuffer, TActionBuffer, NumTokens, CStateBuffer, CActionBuffer, CDataBuffer, Error, ParserStack, LineCount, Column, Count)
Parameters: |
FuncNames
Required. Any array expression for the function names list.
OpCodes
Required. Any array expression for the Operational Codes that correspond to the names in FuncNames.
Number
Required. Any numeric expression for the number of FuncNames/OpCodes pairs.
Module
Required. Any expression that returns a module value. This is the context where the compile takes place.
Script
Required. Any logical expression. If true, the text will be compiled as a script statement. If false, it will be compiled as a normal statement.
Sense
Required. Any logical expression. If true, this statement will be compiled as case-sensitive, otherwise, this will be case-insensitive.
Stream
Required. Any expression for the input stream to read.
ClassBuffer
Required. Any text expression that provides the tokenizer look-up table.
NumClass
Required. Any numeric expression for the number of character classes in the tokenizer state table.
TStateBuffer
Required. Any expression for the tokenizer state table. The tokenizer begins in state 0.
TActionBuffer
Required. Any two-dimensional array expression for the tokenizer action table.
NumTokens
Required. Any numeric expression for the number of tokens in the compiler table.
CStateBuffer
Required. Any text expression for the compiler state table. The compiler begins in state 0.
CActionBuffer
Required. Any text expression for the compiler action table.
CDataBuffer
Required. Any two-dimensional array expression for the compiler data table.
Error

Required. Must be a variable into which the resulting error code will be stored. The error code may be any of the following:

Error | Description
0 | No error.
-1 | Operation code in OpCode table is not defined.
-2 | Parameter must be a constant.
-3 | Too many parameters.
-4 | Compiler table index past the end of the table.
-5 | Token type is < 0 or > max_token.
-6 | illegal attempt to add op code from built-in function.
-7 | Op code array entry is invalid.
-8 | Illegal attempt to add variable parameter.
-9 | Too many parameters.
-10 | Illegal radix in compiler data table.
-11 | Illegal digit in integer.
-12 | Illegal action in CActionBuffer.
-13 | No function specified.
-14 | Not enough parameters.
-15 | Does not have a single parameter.
-16 | Compiler stack is too deep (> 1000)
-17 | Infinite loop detected.
-18 | Suspending and exiting at the same time.
ParserStack
Required. Any stack used to govern the compile.
LineCount
Required. Must be a variable. The current line (number of carriage returns) will be stored here.
Column
Required. Must be a variable. The current column will be stored here.
Count
Required. Must be a variable. The number of characters processed is stored here.
Comments: This function is used when compiling text statements. The syntax of the statements is described by the table parameters that are not fully described here. This function compiles text to create a new function, but doesn't add the new function.


COMPort

(Engine-Level Function)

Description: | Opens a serial port and handles all interrupts and asynchronous events for that serial port, including transmission, reception, and control. It returns its own error code. Note that the SerialStream function is generally preferred in many situations.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Serial Port
Related to: | ActiveX | SerCheck | SerialStream | SerIn | StrLen | SerOut | SerRcv | SerRTS | SerSend | SerString | SerStrEsc | SerWait
Format: | ComPort(Port, ReceiveLen, TransmitLen, Baud, DataBits, StopBits, Parity, RTS, XOnXOff, Obsolete, Obsolete, Control, 0, 0, 0, 0, 0, 0, 0, 0, 0)
Parameters: |
Port
Required. Any numeric expression giving the serial port number to be used.
For COM1, Port = 1
For COM2, Port = 2
The valid range for Port is 1 to MaxComPorts (a variable storing the maximum number of Windows serial ports available. As of the release date of VTS 9.1, this is 4096).
ReceiveLen
Required. Any numeric expression giving the size of the receive buffer in bytes. ReceiveLen must be in the range 2 to 32 766.

If more bytes are received than can fit in the receive buffer before your application removes them using SerRcv or a similar WEB function, the additional data will be lost.
TransmitLen
Required. Any numeric expression giving the size of the transmit buffer in bytes. TransmitLen must be in the range 2 to 32 766.

The buffer must be large enough to hold the maximum number of bytes pending transmission at any instance.
Baud
Required. Any numeric expression giving the baud rate. Baud must be in the range 10 to 115 200, and must divide evenly into 115 200 with no more than 2.5% error.
DataBits
Required. Any numeric expression giving the number of data bits per character. DataBits must be 5, 6, 7, or 8.
StopBits
Required. Any numeric expression giving the number of stop bits per character. StopBits must be 1 or 2.
Parity
Required. Any numeric expression giving the parity checking to use (as follows)
Value | Parity
0 | No parity
1 | Odd parity
2 | Even parity
3 | 0 Stick (space parity)
4 | 1 Stick (mark parity)
RTS
Any numeric expression that gives the RTS buffer control method.
RTS is on while transmitting. When a transmission is complete, RTS is off. This is usually used to control the transmitters on RS-422/485 ports.
This parameter has no effect if the automatic RTS control is selected in the Control parameter.
Acceptable values of the RTS parameter are as follows:
Value | RTS Method
0 | Force RTS off
1 | Force RTS on
2 | Half-duplex operation (Windows NT only)
3 | Controlled by SerRTS function

If this parameter is 2, the SerRTS function can set its value, however, regardless of SerRTS, the RTS control line will be asserted when data is sent.
If the SerRTS is called to change the RTS line while data is being transmitted, the RTS line will not change when the last byte is sent.
If SerRTS is not executed while the data is transmitted, the RTS line will be cleared after the last byte is transmitted.

XOnXOff
Required. Any logical expression. If true (non-0), software flow control is to be used. If false (0), flow control software is not used.
Obsolete
No longer used, but is maintained for backward compatibility with previous versions of VTScada. Set to 0.
Obsolete
No longer used, but is maintained for backward compatibility with previous versions of VTScada. Set to 0.
Control

Any numeric expression that specifies the handling procedure for the clear to send (CTS), carrier detect (CD), and data set ready (DSR) input lines, and the data terminal ready (DTR) output line on the serial port. The value must be in the range 0 to 63. The desired action is the sum of the following values:

(See: Bitwise Parameters & Operations)

Value | Bit No. | Control
1 | 0 | DTR on (otherwise DTR is off)
2 | 1 | Enable CTS control
4 | 2 | Enable CD control
8 | 3 | Enable DSR control
16 | 4 | Enable RTS/CTS control
32 | 5 | Enable DTR/DSR control
  • If bit 1, CTS control, is set data will only be transmitted if the CTS signal is on. If CTS control is disabled, the CTS line is ignored.
  • If bit 2, CD control, is set data will only be transmitted when the CD signal is on. If CD control is disabled, the CD line is ignored.
  • If bit 3, DSR control, is set data will only be transmitted when the DSR signal is on. If DSR control is disabled, the DSR line is ignored.
  • If bit 4, RTS/CTS control, is set the CTS control behaves as described above, and the RTS line will be held high until the receive buffer reaches 75% full. It will then go low, indicating to the other device to stop transmitting data. The RTS line will go high again when the receive data buffer drops below 25% full. This is known as hardware flow control. RTS/CTS control enabled overrides the RTS parameter.
  • If bit 5, DTR/DSR control, is set the DSR control behaves as described above, and the DTR line will be held high until the receive buffer reaches 75% full. It will then go low, indicating to the other device to stop transmitting data. The DTR line will go high again when the receive data buffer drops below 25% full. This is known as hardware flow control. DTR/DSR control enabled overrides bit 0, DTR on option.
  • bits 6 through 14: Obsolete. No longer used, but maintained for backward compatibility with previous versions of VTScada. Set to 0.
Obsolete x 9
Required. Nine parameters following Control are obsolete, but must be included for the function to compile. Normally set to 0's.
Comments:

This statement has been superseded by the SerialStream function and is maintained for backwards compatibility only.

This function is part of the driver toolkit and must be active to control its serial port. The ComPort is activated upon entering the state, and deactivated upon leaving the state. Standard VTScada drivers that use the serial port use this statement. Typically, all parameters are public member variables of I/O driver modules which are set to default values in a script, and may be altered using the scope resolution operator, (a backslash ( \ )) (see the section on the driver in question).
The return value is an error code having one of the following meanings:

Value | Meaning
0 | No error
1 | Out-of-range error in one of the parameters
2 | Port already in use or not available
5 | Access denied
31 | General failure
87 | Invalid parameter

A ComPort function must be active for serial port communications. None of the driver toolkit functions (anything beginning with Ser... , such as SerSend) will work without a ComPort function.

Make sure that VTScada's mouse (if it is serial) is on a different port, because the mouse and ComPort can interfere. Also make sure that no other hardware or software is interfering with the serial port hardware interrupts (IRQ4 for COM1:, IRQ3 for COM2:). Network cards often use IRQ4, which will cause a problem with a mouse or ComPort on COM1.

Before writing a communications driver for VTScada, it is important to understand some general data communications concepts (such as headers, checksums, packets, etc.) as well as the particular protocol you wish to use. It is a good idea to understand how fixed modules may be used to provide semaphores and queues (so that modules designed to read packets can queue up for their turns to use the serial port, and prevent collisions).

Example:

  ComPort(2 { COM2: },
          1024 { Buffer 1024 bytes of received data },
          1024 { Buffer 1024 bytes of transmitted data },
          9600 { Baud rate },
          8 { Data bits per byte },
          1 { Stop bit per byte },
          0 { No parity bit },
          1 { Force RTS on },
          0, 0, 0 { Obsolete parameters },
          3 { Control: DTR On, CTS control enabled },
          0, 0, 0, 0, 0, 0, 0, 0, 0 { Obsolete parameters });

This example opens COM2: for use with serial port functions. These functions should use 2 as their Port parameter.


Compress

(Engine-Level Function)

Description: | Eliminate invalid array entries.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Array
Related to: | ArrayOp1 | ArrayOp2 | AValid | Filter
Purpose: | This statement moves all of the valid array entries to the first part of the array, maintaining the order of the valid elements.
Format: | Compress(ArrayElem, N)
Parameters: |
ArrayElem
Required. Any array element giving the starting point for the array search. The subscript for the array may be any numeric expression.If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to use starting at the element given by the first parameter.
If N extends past the upper bound of the array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Comments: None

Example:

Init [
  If 1 Main;
  [
    X[0] = 4;
    X[1] = Invalid;
    X[2] = 5;
    X[3] = 6;
    X[4] = Invalid;
    X[5] = 3;
    Compress(X[0], 6);
  ]
]

This will result in the first 4 elements of array X being set to 4, 5, 6 and 3 respectively, with the last 2 elements being set invalid.


COMStatus

(Engine-Level Function)

Description | Returns the last status information that occurred for a specified COM client interface.
Returns | Varies
Usage | Script Only.
Function Groups | COM
Related to: | ActiveX | COMClient | COMEvent
Format | ComStatus(COMClientInterface [, Options])
Parameters |
COMClientInterface
Required. A COM client interface handle returned from a COMClient or ActiveX statement.
Options
Optional. Any numeric expression. Set to 0 to return the Windows API error code.
Set to 1 to return a text message representation of the Windows API error code.
Defaults to 0 if missing or Invalid.
Comments The value returned indicates the success or failure of the last operation attempted through the specified COM client interface.
Depending on the Options parameter, this function returns either the Windows API error code or a text value containing an ASCII representation of the error code. There is no guarantee that all error codes can successfully be translated into a text representation.

Example:

See: COMClient


Concat

(Engine-Level Function)

With a small number of exceptions, all VTScada text is stored as phrase keys. The text that you see comes from the language file matching your current language. To view the phrase that matches a key you must use \GetPhrase("KeyName").
For example, an expression in an I/O and Calculations tag that looks like Concat(ShortName, " ", Description) will return text that looks like This Tag 04Q/a+8
To view the text of the description instead of the stored key, you must write \GetPhrase(Description)
See: Multilingual Expressions

Description: | Returns the text value that is the concatenation of all the text parameters.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | GetParmPhrase | StrCmp | StrICmp | StrLen | GetPhrase
Format: | Concat(String1, String2[, String3, ... ])
Parameters: |
String1, String2, String3
A minimum of two parameters are required May be any expressions that give the text values to add to the resulting string.
Comments:

This function takes all of the characters of the first parameter and appends all of the characters of the second parameter to the end of this string. It will then take all of the characters of the next parameter and append them to the result. This will continue until there are no more parameters.

The result cannot exceed 2,147,483,647 characters. INVALID will be returned instead.

Because the text strings are delimited by quotation marks, to include a set of quotation marks as part of the resulting string, you must use two sets of quotation marks (see example).

For multilingual user interfaces, you are encouraged to use \GetParmPhrase rather than Concat.

Example:

  ZText(10, 10, Concat("The maximum is ", MaxValue,
                       " and the minimum is ", MinValue),
        2, 0);

This statement displays the 2 strings and 2 values as a single line of (white) text in the window.

  ZText(10, 10, Concat("""Hello"", said the ", Animal), 12, 0);
  ZText(10, 10, Concat("""", "Hello", """", ", said the ", Animal), 12, 0);

These two statements will display the exact same line of text on the screen. If Animal is the string "cat", the text that they display will be:

"Hello", said the cat


Cond

(Engine-Level Function)

Description: | Returns the result of one of two expressions depending upon the result of a conditional expression.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | Logic Control
Related to: | Case | IfElse | IfThen
Format: | Cond(Condition, Value1, Value2)
Parameters: |
Condition
Required. Any numeric expression giving the conditional value to use for the test. If Condition is true (i.e. not equal to zero), the value of the Value1 parameter is returned.
If Condition is false (i.e. equal to zero), the value of the Value2 parameter is returned.
If Condition is invalid, the return value is invalid.
Value1
Required. Any expression whose value is returned if the Condition parameter is true.
Value2
Required. Any expression whose value is returned if the Condition parameter is false.
Comments:

This function will return either Value1 or Value2 based on the truth of Condition. This means that the function may return a valid result even if one of the Value parameters is invalid (i.e. the one not selected).

  • If Cond is executed in a script, and the Condition parameter selects one of the parameters, the other is not evaluated (unless Condition is invalid, and then neither parameter is evaluated).
  • If Cond is executed in steady state, both Value1 and Value2 are evaluated, but only one result is returned.

Cond may be used on the left side of an assignment, in which case Value1 and Value2 may be variables, and one of Value1 and Value2 will receive the assignment (depending on the Condition parameter).

This function is used extensively to change screen images based upon variable values. For example, it can be used to change a color of a bar if it is used within the Bar statement in the Foreground color parameter.
The return value is optional.

Example:

  Y = Cond(X == 3, 4, 5);

Y will be set invalid if x is invalid. If x is 3, y will be 4. Otherwise Y will be 5.

  Cond(X == 3, A, B) = 6;

If X is invalid, nothing happens. If X is 3, A will be set to 6, otherwise B will be set to 6.


Configure

(VoiceTalk Module)

Description | Is used to define how a speech stream will sound and where it will be heard.
Returns | Numeric
Usage | Script Only.
Function Groups | Speech and Sound
Related to: | GetDevices | GetVoices | Reset | ShowLexicon | Speak | SpeakToFile | VoiceTalk
Format | VoiceTalk.Configure([VoiceTalkStream, Device, Rate, Volume])
Parameters |
VoiceTalkStream
Required. A speech stream returned from VoiceTalk.
Voice
Optional Specifies the name of the voice in which to speak. This should be one of the voice names returned from a VoiceTalk\GetVoices call, or Invalid to not change the voice.
Device
Optional Specifies where to play back the voice. This can either be a system device ID (), or the name of a device (such as returned from a call to VoiceTalk.GetDevices()).
-1 is the default - usually speaker audio
Rate
Optional Specifies the speed at which the voice is to speak. Normal speed is "0". Valid values are from -10 (very slow) to 10 (very fast). The default is "0".
Volume
Optional Specifies the volume at which the voice is to speak. Valid values are from 0 (silent), to 100 (full speaker volume). The default is 100.
Comments A speech stream can be configured to sound differently by changing the rate and volume parameters. To configure output to go to another device, such as a modem, change the Device parameter.
If a voice or device is specified which is not valid for this stream, or a problem is encountered while trying to change the stream configuration, the stream will be left unchanged.
"VTSFileOutput" is a valid device name. When used, the Speak() module will no longer work, but the SpeakToFile() module can be used to speak a phrase into a .wav file.
This return value is the Windows error code for the problem encountered, or zero if there was no problem.

Will compile and work once if called from Steady State - this is not recommended practice.

Example:

  ...
  SpeechFileObj = \VoiceTalk();

  If !Configured && SpeechFileObj\Ready);
  [
    SpeechFileObj\Configure(Invalid, "VTSFileOutput", -1 {Rate}, 100 {Volume} );
    Configured = TRUE;
  ]


ConnectToMachine

(RPC Manager Library)

Description: | This subroutine increments the usage count on the specified workstation and forces RPC Manager to attempt to establish a connection with the specified workstation if it is not already connected. Subroutine call only.
Returns: | Socket node (warning - see note in comments)
Usage: | Script Only.
Function Groups: | Network
Related to: | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | Send | SetRemoteValue
Format: | \RPCManager\ConnectToMachine(Workstation)
Parameters: |
Workstation
Required. Any text expression giving the name or IP address of the workstation to which the connection is to be made.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
While the usage count of the workstation is non-zero, RPC Manager will continue to attempt to establish a connection to the remote workstation.
It is critical that each ConnectToMachine call should be paired with a DisconnectFromMachine call. If the number of ConnectToMachine calls exceeds the number of DisconnectFromMachine calls, the RPC Manager will not behave as expected and disconnection from the remote workstation may be impeded. An unexpectedly positive value for the Srv value in the socket's entry in the RPC Diagnostics Window may be an indication of a ConnectToMachine/DisconnectFromMachine mismatch.
This subroutine doesn't return a (reliable) socket node (i.e. may go invalid). Also, it isn't a socket, it is a socket node instance.

Example:

  If ! TryToOpen;
  [
     TryToOpen = 1;
     SNode = \RPCManager\ConnectToMachine("TestMachine");
  ]
  If SNode.SocketOpen Continue;

This code snippet opens a socket to the workstation called TestMachine and waits until the connection has been established before continuing.

Related Functions:

Refer to RPC Manager Service for a listing of Service Control Methods, RPC Methods, and Deprecated RPC Methods.


ConstCount

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Returns the number of constant parameters in a function.
Warning: | This function should be used only by advanced programmers.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modification, Advanced Module
Related to: | Compile | FWrite | Save
Format: | ConstCount(OpCode)
Parameters: |
OpCode
Required Any numeric expression for the opcode of the function.
Comments: No longer in use.


ConvertTimeStamp

(Engine-Level Function)

Description: | Converts a time stamp from one time zone to another.
Returns: | Numeric (double)
Usage: | Script only.
Function Groups: | Time and Date
Related to: | TimeZone | TimeZoneList
Format: | ConvertTimeStamp(Timestamp, SourceTZ, InDST, DestTZ)
Parameters: |
Timestamp
Required The timestamp (in seconds) to be converted since midnight of January 1, 1970. The timestamp parameter is limited to a minimum of 0, and a maximum of 34359738367. Values outside this range will cause Invalid to be returned.
SourceTZ

Required. The name, in English, of the time zone from which Timestamp originated. The name must be a name in the list returned by the TimeZoneList function. May also be a structure - see Comments.
If Invalid, or not a valid time zone name, then UTC is used as the source time zone. If set to "0", the local server's time zone is used.

InDST

Required. A flag that indicates whether daylight savings time (DST) was in use in the source time zone at the moment defined by Timestamp. This flag is used only for the period at the end of DST where a local time may appear twice. You must write your own expressions to determine this for your region
If true (non-0), DST is in effect. If false (0), DST is not in effect.
If INVALID, the default value is false. INVALID is recommended for most situations.

If the source time zone does not observe DST (as is the case with values stored using UTC, which is everything that the Historian saves), then this flag has no effect.

DestTZ
Required The name, in English, of the time zone to which Timestamp is to be converted. The name must be a name in the list returned by the TimeZoneList function. May also be a structure - see comments.
If invalid, or not a valid time zone name, then UTC is used as the destination time zone. If set to "0", the local server's time zone is used.
Comments:

The function returns the converted timestamp as a number indicating the number of seconds since midnight of January 1, 1970. The SourceTZ and DestTZ parameters must use names as returned by the TimeZoneList function.
The function uses the time zone information in the registry to determine local time zone bias, DST bias, and starting and ending dates of DST. If the information in the registry is incorrect, then it may be updated using the TZEdit tool available from Microsoft.

Be aware that the local server's time zone may differ from the geographic time zone. Client workstations (and thin clients) may have time zones that differ from the local server's configuration. Timezone(3) is a thin client safe approach to converting to or from the local time. Timezone is thin client aware, and adjusts the returned timezone as appropriate for converting for the session under which it is run.

Timezone names must be provided only in English, using the same names as reported by TimeZone(2), TimeZone(3), and TimeZoneList().

Both the SourceTZ and DestTZ parameters may be provided as structures. These structures will have two members

  • StdTimeZone - a string that represents the standard name for the time zone
  • ObservesDST - a Boolean, where 0 indicates that the time zone does not observe daylight savings time and a 1 indicates that it does

The purpose of this structure is to handle systems that are set to a time zone that does normally observe DST, but the users have configured Windows™ to not adjust for daylight savings time. This structure is the same as that used by option 3 of the TimeZone function.

Example:

Init [
  If 1 Main;
  [
    { Convert from UK to Atlantic Standard Time }
    Timestamp = ConvertTimeStamp(CurrentTime(),
                                 "GMT Standard Time" { Specify source TZ    },
                                 0                   { Not daylight savings },
                                 "Atlantic Standard Time" { Destination TZ  });
  ]
]

To convert the timestamp stored in SomeStartTime to GMT time:

  TimeStamp = ConvertTimeStamp(SomeStartTime, TimeZone(3), 0, Invalid);

Converting from server timezone to the client session specified timezone:

  ConvertTimestamp(ServerTime, "0" { Server local time },
                   Invalid,
                   Timezone(3) { Thin client aware local time });


ConvertToDbDate

(ODBC Manager Library)
Description | Provides a conversion of a date value into the format used by the indicated database.
Returns | The date value, converted to the specified database format
Usage | Script only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format | \ODBCManager.ConvertToDbDate( dbType, ValueIn[, NoDelimiters])
Parameters |
dbType
Required numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase
ValueIn
Required. Numeric time value expressed in days since January 1, 1970
NoDelimiters
Optional. Any Boolean expression. If this parameter evaluates to true (non-zero), then text delimiters will be suppressed in the output value.
Defaults to true
Comments This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

Example:

...
   { Convert time & date seperately }
    DbDateStr = \ODBCManager.ConvertToDbDate(DbType, Int(GivenTimeStamp / \#SecPerDay), 1 {No delimiters});
    DbTimeStr = \ODBCManager.ConvertToDbTime(DbType, GivenTimeStamp % \#SecPerDay, 1 {No delimiters });


ConvertToDbTime

(ODBC Manager Library)
Description: | Provides a conversion of a time value into the format used by the indicated database.
Returns: | The time value, converted to the specified database format
Usage: | Script only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.ConvertToDbTime( dbType, ValueIn[, NoDelimiters])
Parameters: |
dbType
Required numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase
ValueIn
Required. Numeric time value expressed in seconds since midnight
NoDelimiters
Optional. If this parameter evaluates to true (non-zero), then text delimiters will be suppressed in the output value. Defaults to true
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

Example:

...
   { Convert time & date seperately }
    DbDateStr = \ODBCManager.ConvertToDbDate(DbType, Int(GivenTimeStamp / \#SecPerDay), 1 {No delimiters});
    DbTimeStr = \ODBCManager.ConvertToDbTime(DbType, GivenTimeStamp % \#SecPerDay, 1 {No delimiters });


ConvertToDbTimeStamp

(ODBC Manager Library)
Description: | Provides a conversion of a timestamp value into the format used by the indicated database.
Returns: | The time value, converted to the specified database format
Usage: | Script only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.ConvertToDbTime(dbType, ValueIn[, NoDelimiters])
Parameters: |
dbType
Required numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase
ValueIn
Required. Numeric value expressed as a VTScada timestamp
NoDelimiters
Optional. If TRUE (non-zero), then text delimiters will be suppressed in the output value. Defaults to true
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

Example:

This will set DBTime to the time when the module opened, formatted as a MS Access timestamp.

[
  RightNow  { Timestamp in seconds, set when the page opens. };
  DBTime    { The same timestamp formatted for MS Access     };
]
Init[
  RightNow = Now(1); If 1 Main;
  [
    DBTime = \ODBCManager.ConvertToDbTime(1, RightNow);
  ]
]


ConvertToVTSDate

(ODBC Manager Library)
Description: | Provides a format conversion of a date value from that used by the indicated database to the format used by VTScada.
Returns: | The date value, converted to the standard VTScada format
Usage: | Script only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.ConvertToVTSDate(dbType, ValueIn)
Parameters: |
dbType
Required numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase
ValueIn
Required. Date value as used by the indicated database.
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

Example:

[
  VTDate;
  RightNow;
]
Init[
  RightNow = "2022-09-27"; If 1 Main;
  [
    VTDate = \ODBCManager.ConvertToVTSDate(3, RightNow);
  ]
]

In this example, VTDate is set to 19262.


ConvertToVTSTime

(ODBC Manager Library)
Description: | Provides a format conversion of a time value, from that used by the indicated database, to that used by VTScada
Returns: | The time value, converted to the standard VTScada format
Usage: | Script only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.ConvertToVTSTime( dbType, ValueIn)
Parameters: |
dbType
Required numeric value, indicating the type of this DB connection. At present, only MS SQL and Oracle are supported.
DBType | Meaning
0 | MS SQL
2 | Oracle
ValueIn
Required. Time value as used by the indicated database.
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

Example:

[
  VTTime;
  RightNow;
]

Init[
  RightNow = "14:25:01"; If 1 Main;
  [
    VTTime = \ODBCManager.ConvertToVTSTime(0, RightNow);
  ]
]

This example will return VTTime as 51901.


ConvertToVTSTimeStamp

(ODBC Manager Library)
Description: | Provides a format conversion of a time value from that used by the indicated database into a VTScada time stamp format
Returns: | The time and date value, converted to a VTScada timestamp
Usage: | Script only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.ConvertToVTSTime( dbType, ValueIn[, FormatStr])
Parameters: |
dbType
Required numeric value, indicating the type of this DB connection. At present, only MS SQL and Oracle are supported.
DBType | Meaning
0 | MS SQL
2 | Oracle
ValueIn
Required. Time and date value as used by the indicated database.
FormatStr
Optional. Provides a format to use. Please refer to the BuffRead function for a description of the formatting options
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.


Coordinates

Deprecated. Do not use in new code.

Description: | Sets the VTScada screen coordinate limits (also called "world coordinates") used by the graphics functions.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics, Window
Related to: | CoordToPixel | Window
Format: | Coordinates(Left, Bottom, Right, Top)
Parameters: |
Left
Required. Any numeric expression giving the x screen coordinate of the left side of the window.
Bottom
Required. Any numeric expression giving the y screen coordinate of the Bottom side of the window.
Right
Required. Any numeric expression giving the x screen coordinate of the Right side of the window.
Top
Required. Any numeric expression giving the y screen coordinate of the Top of the window.
Comments: Left cannot equal Right, and Top cannot equal Bottom. Left, Right, Top, and Bottom can be any floating point values including fractions. When this statement changes coordinate limits, all active graphics statements are automatically redrawn. It may be useful for setting screen coordinates to match device coordinates, or to ensure the screen coordinates are set correctly when working with different video modes.
If you wish to set to pixel coordinates you may do so using this statement or it may be simpler to set the window option to pixel.

Example:

Coordinates(0, 349, 639, 0);

This sets the screen coordinates such that (320,175) is the center of the screen. If VTScada is running in EGA resolution (640 x 350) then one screen coordinate is the same as one pixel.


CoordToPixel

(Engine-Level Function)

Description: | Takes a specified coordinate pair within a given window and returns the overall, onscreen pixel location.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Graphics, Window
Related to: | Coordinates
Format: | CoordToPixel(Object, CoordX, CoordY, Option)
Parameters: |
Object
Required. The window context that the coordinates are taken from.
CoordX
Required. Any numeric expression giving the x-coordinate to convert.
CoordY
Required. Any numeric expression giving the y-coordinate to convert.
Option
Required. Any numeric expression specifying the converted coordinate to return, where 0 returns the converted x-coordinate, and 1 returns the converted y-coordinate.
Comments: This function's return value is determined by the Option parameter.

Example:

  If 1 Main;
  [
    xPixel = CoordToPixel(Self(), xCoord, yCoord, 0);
    yPixel = CoordToPixel(Self(), xCoord, yCoord, 1);
  ]

This converts the point specified by the user coordinates (xCoord, yCoord) in the current module to screen coordinates (pixel location).


CopyDir

(System Library)

Description: | This subroutine recursively copies a directory's files and sub-directories down through the entire directory tree.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | File I/O
Related to: | CheckFileExist | CheckPathExist | GridList
Format: | System.CopyDir(Destination, Source)
Parameters: |
Destination
Required. Any text expression giving the directory into which the source directory is to be copied. This directory must already exist.
Source
Required. Any text expression giving the directory to be copied.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

    System.CopyDir("C:\OEMApp", "App1");


CopyIn

(Engine-Level Function)

Deprecated. This function relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.

Description: | Copies data from an absolute RAM address and returns a buffer.
Returns: | Buffer
Usage: | Script Only.
Function Groups: | Memory I/O
Related to: | CopyOut | MemIn | MemOut
Format: | CopyIn(Address, Length)
Parameters: |
Address
Required. Any numeric expression giving the absolute RAM address to start to copy. Typically the address is specified using the colon ( : ) operator.
Length
Required. Any numeric expression giving the number of bytes to copy.
Comments:

This function requires that the VTSIO driver be installed, which will not be true in new installations.

A buffer is returned that is a copy of RAM at Address.


CopyOut

(Engine-Level Function)

Deprecated. This function relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.

Description: | Copies data from a buffer to an absolute RAM address.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Memory I/O
Related to: | CopyIn | MemIn | MemOut
Format: | CopyOut(Buffer, Address, Length)
Parameters: |
Buffer
Required. Any text or buffer expression containing data bytes to copy.
Address
Required. Any numeric expression giving the absolute RAM address to start to copy.
Length
Required. Any numeric expression giving the number of bytes to copy.
Comments:

This function requires that the VTSIO driver be installed, which will not be true for new applications.

A buffer is written to RAM at Address. If fewer than Length bytes are in the buffer, the copy will stop when the end of the buffer is reached.


CopyRecords

(ODBC Manager Library)
Description:

Copy record(s) from a database and inserts the values back into the same table with the desired change to one field.

It will destroy any existing records with the same name. Should be run as a called module, waiting for completion. Do not call as a subroutine.

Usage: Script Only.
Returns: An error code if one results from the action, otherwise 0.
Related to: AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: \ODBCManager.CopyRecords( DSN, TableName, KeyField, OrgKeyValue, CopiedKeyValue, Username, Password [, TransactionObj])
Parameters:
DSN
Required. Data source name of the database to use
TableName
Required. Table name to read and write in both databases
KeyField
Required. Field name to use for the SQL WHERE clause
OrgKeyValue
Required. Key values of the records when complete
CopiedKeyValue
Required. Key values of the records to copy
Username
Required. User name for database access
Pass
Required. Password for database access
TransObj
Required. Value of transaction object
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.


Cos

(Engine-Level Function)

Description: | Returns the trigonometric cosine of an angle in radians.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Trigonometric Math
Related to: | ACos | ASin | ATan | Sin | Tan
Format: | Cos(Angle)
Parameters: |
Angle
Required. Any numeric expression giving the angle in radians.
Comments:

The returned value is a number in the range of -1.00 to +1.00. To convert an angle from degrees to radians multiply by \pi / 180 or (approximately) 0.0174533.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

  X = Cos(180 * \Pi / 180);

The value of x will be - 1.


CoverageSnapshot

(Engine-Level Function)

Description: | Captures the areas in a VTScada source file which have not executed along with summary statistic for each module in the file to extract code coverage information.
Warning | This function should be used only by advanced programmers.
Returns: | Structure
Usage: | Script Only.
Function Groups: | Advanced Module
Related to: |
Format: | CoverageSnapshot(Module, [ Reset ])
Parameters: |
Module
Required. A VTScada module. The data returned will be for the source file which contains that module. Information for all of the modules in the same source file will be included in the returned value. The module need not be the root module of the source file.
Reset
Optional Tells the function to reset all of the code coverage counters to 0 immediately after the statistics are collected.
A true value indicates that the reset should be done and a false (0) indicates that it should not be done. The default value is 1.
Comments:

This function exists for purposes of internal testing by Trihedral. It is unlikely to be useful elsewhere.

The VTScada interpreter engine keeps counters for every module, variable, state, statement and function parameter. All of these counters start at 0 whenever VTScada starts. Every time one of these internal structures is executed, its corresponding counter is incremented.
The CoverageSnapshot function searches through the code for a given VTScada script source file and locates all of the counters which are still 0. These represent the areas of the code that have not executed since VTScada started or at least since the last reset.
CoverageSnapshot returns a list of all these areas of the code that haven’t executed. The list is in the form of starting and ending byte offsets in the source file. The list excludes constants the declaration of TEST modules and FIXTURES.
The structure returned is

FileCoverage Struct [
  Children  { Dictionary of child module names. The values are
              either a pointer to Child Struct or a file name.
              File name is used if not in the same source file.
             File names are relative to VTScada installation directory.};
  List      { Pointer to an UncoveredList Struct       };
  FileSize { Number of bytes in the file. Will be invalid if the
             first parameter of the  function refers to a module
             which is not the root module in the file and the
             parent of the module is invalid. };
  TimeStamp { File time for the file       };
  Class     { Variable class defined for the root module
              In the file. };
];

The referenced structures are:

Child Struct [
  Begin    { Byte offset from the beginning of the source file for
              module definition };
  End      { Last byte offset for the module definition      };
  Children { Dictionary as defined in FileCoverage Struct    };
  Class    { Variable class defined for the module           };
];

UncoveredList Struct [
  Begin     { Offset to start of uncovered code in source file  };
  End       { Offset to last byte of uncovered code in range    };
  Mode      { 0 for code, 1 for variables                       };
  Next      { Pointer to next UncoveredList for the file        };
]

The UncoverList is ordered in increasing Begin offsets with none of the Begin/End areas overlapping in the list.


CRC

(Engine-Level Function)

Description: | Returns the cyclic redundancy check (CRC) value for a buffer.
Returns: | Numeric As of 12.2, the CRC function returns positive values rather than negative. The bit sequences are unchanged. This is a side effect of the switch to 64-bit values in version 12.2. Versions from 12.1.60 onwards that included the pre-release version of that feature are also affected.
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | CRCTable
Format: | CRC(Buffer, Offset, Length, Table, Start)
Parameters: |
Buffer
Required. Any text expression for which to generate a CRC.
Offset
Required. Any numeric expression giving the offset from 0 in the buffer where the CRC calculation will start.
Length
Required. Any numeric expression giving the number of buffer bytes to include in the CRC. Length must not be greater than 65500.
Table
Required. A text expression giving a CRC look-up table buffer. The length of the table buffer must be a multiple of 256 plus 1.

A table can be generated automatically with the CRCTable function.
Start
Required. Any numeric expression giving the initial value for the register used in the CRC calculation.
For most drivers this is 0 or 0xFFFF.
Comments: CRC is a driver toolkit function.

Example:

  CheckSum = CRC(response { Text buffer },
                 0 { Start of the buffer },
                 20 { Number of bytes },
                 CheckTable { Look-up table buffer },
                 0 { Use Allen-Bradley™ protocols });

This gets the checksum for bytes 0 to 19 of the text buffer response, using the CheckTable CRC look-up table, and an initial accumulator value of 0.


CRCTable

(Engine-Level Function)

Description | Returns a buffer containing a CRC table.
Returns | Buffer
Usage | Script or steady state.
Function Groups | String and Buffer
Related to: | CRC
Format | CRCTable(Polynomial, Length, Shift)
Parameters |
Polynomial
Required. A long expression that gives the bit pattern of the generating polynomial. For Allen-Bradley® and Modicon®, Polynomial = 0b1000000000000101, which corresponds to the expression:

x^16 + x^15 + x^2 + 1

To determine the value of Polynomial for a given generator expression, drop the highest order term, and represent each term present by a 1 in the bit position equal to its exponent.

For example, x^16 + x^12 + x^5 + 1 would have a Polynomial value of 0b0001000000100001. The first 1 corresponds to x^12, the second to x^5, and the last to 1 (which is x^0). This polynomial is used by the XMODEM protocol.
Length
Required. Any numeric expression giving the byte length of the CRC accumulator register (usually 2 or 4). The CRCTable buffer returned is 256 * Length + 1 bytes long.
Shift
Any numeric expression that is 0 for right-shifted CRC calculations (such as Allen-Bradley® or Modicon®), and 1 for left-shifted CRC calculations (such as XMODEM).
Comments

This function is part of the driver toolkit.

(See: Bitwise Parameters & Operations)

Example:

  CheckTable = CRCTable(0b1000000000000101
                        { Polynomial: x^16 + x^15 + x^2 + 1 },
                        2 { 16 bit CRC register },
                        0 { Right-shifted CRC calculations });

This generates a CRC look-up table for use with the CRC function.


CreateModule

(Engine-Level Function)

Description: | Creates a new module and returns a pointer to it.
Warning: | This function should be used only by advanced programmers.
Returns: | Pointer
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AddModule | DeleteModule
Format: | CreateModule(FileName)
Parameters: |
FileName
Required. Any text expression giving the name of the .SRC file that contains this module's definition.
Comments:

This function creates a module that has no parent.

Seldom (if ever) used when adding features to modern VTScada applications.

Example:

  If 1 Main;
  [
     MyMod = CreateModule("pump.SRC");
  ]


CriticalSection

(Engine-Level Function)

Description: | Marks a section of a module as a critical section and will not allow interruption of its execution by other threads.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Basic Module
Related to: | Execute
Format: | CriticalSection(Statement1, Statement2, [Statement3, …])
Parameters: |
Statement1, Statement2, Statement3, …
Required. Any expressions to be executed. Any number of parameters may be used.
Comments: This statement works in a manner similar to Execute, but on the threaded level.

Example:

  If 1 Main;
  [
    IfThen(Valid(level),
           CriticalSection(temp = a,
                           a = b,
                           b = temp ) );
  ]


Crop

(Engine-Level Function)

Description: | Modifies an existing image, producing a new one that displays a sub-section of the original.
Returns: | Image handle
Usage: | Script or steady state.
Function Groups: | Graphics, Window
Related to: | BitmapInfo | GUIBitmap | GUIButton | ImageArray | ImageSweep | MakeBitmap | ModifyBitmap
Format: | Crop(OrigBMP, Left, Top, Width, Height)
Parameters: |
OrigBMP
Required. The original image to be cropped. This must be a valid image object, created with the MakeBitmap statement.
Left
Required. Any expression for the number of pixels from the left side of the original image to set to be the left side of the new image. "0" will start at the same place as the original image.
Top
Required. Any expression for the number of pixels from the top of the original image to set to be the top of the new image. "0" will start at the top of the original image.
Width
Required. Any expression for the number of pixels wide the new image will be. The new image will be enforced to be at least 1 pixel wide, even if Width is set to less than 1 pixel.
Height
Required. Any expression for the number of pixels high the new image will be. The new image will always be at least 1 pixel height, even if Height is set to less than 1 pixel.
Comments: This function allows for the enlargement of parts of an original image, without requiring that the entire image be drawn. It also uses very little memory, and is very fast, as compared to calls to creating a file from a disk file each time.
There are no restrictions on how large the new image may be, so it can be larger (in any dimension) than the original. If this is the case, the extra space will be filled with black pixels. Values for Left and Top that are less than zero (0) are therefore permitted. Width and Height should be given a value of at least one "1", but may be as large as desired. Any transparency in the original image is preserved in the cropped image.
Cropping can be cumulative, so that you can take the output of one crop function and use that as input to another. The result is that the left and top of the new transform are equivalent to the sum of the values in each of the original transforms. However, since width and height are in pixels, the number of pixels specified each time is exactly how large the resulting image will be.
The image resulting from a call to Crop() can be used any place that an image may be used, such as in a call to GUIBitmap or GUIButton.

Example:

  Img = Crop(MakeBitmap("TANKS.BMP", 0), 10, 10, 50, 50);
             GUIBitmap(250, 150, 350, 50 { position },
             1, 1, 1, 1, 1 { scaling },
             0, 0 { trajectory, rotation },
             1, 0   { visibility },
             0, 1, 1   { selectability },
             Img { image });

This example displays a 50x50 pixel subsection beginning 10 pixels from the left and 10 pixels from the top of the original image, "TANKS.BMP". It is then displayed in a 100x100 pixel square on the screen. Any place the color was black (index 0) in the image will be shown as transparent.

  If Watch(1, BitmapFile);
  [
    Img = MakeBitmap(BitmapFile);
    ImgWidth = BitmapInfo(Img, 0);
    ImgHeight = BitmapInfo(Img, 1);
  ]
  Img2 = Crop(Img, ImgWidth*0.25, ImgHeight*0.25,
              ImgWidth*0.5, ImgHeight*0.5);

This example creates and stores an image in Img2 which is the middle section of the original image.


CrossReference

(Engine-Level Function)

Description: | Returns a linked list of structures representing all references to a specified variable or module.
Returns: | Linked list of structures
Usage: | Script Only.
Function Groups: | Advanced Module
Related to: |
Format: | CrossReference(ModuleToSearch [, WhatToFind, Context])
Parameters: |
ModuleToSearch
Required. Module value which is the root of the static module tree to search. May also be an array of module values.
If the next parameter (ModuleToFind) is invalid, then only the variable references which are not within the scope of this module are returned, i.e. external references.
WhatToFind
Optional. May be either a module or a variable to search for. If invalid, all references to all variables (whether they may contain modules or otherwise) outside the specified scope tree are returned.
Context
Optional. Instance of a module that indicates what scope ModuleToSearch would run in, were it to run. (Note that ModuleToSearch does not need to be running when CrossReference is called.)
If invalid, only the static scope will be searched.
Comments: Context must be valid where scoping needs to be resolved as shown in the example. In this example, it is necessary to determine if the Draw module referred to is the correct one based up on the module value of the actual Draw variable stored in Tag23’s module.

Example:

Assume that there is page named MyPage whose only line is the following:

Variable("Tag23")\Draw(Variable("Flow")\Value * 10, 57);

Further, assume that Tag23 is of type MyTagType

Then, to look for all references to MyTagType's Draw method inside a particular page, use:

CrossRefData = CrossReference(\MyPage, \ MyTagType \Draw, \Code);

You could then expect the following to be true.

CrossRefData.Reference == FindVariable("Draw", \MyTagType, 0, 0)

CrossRefData.DAG == the code value for the Call to the Draw method
CrossRefData.Begin == the number of bytes from the beginning of the
                      Function to the beginning of the text "Draw".
CrossRefData.End == the number of bytes from the beginning of the
                      Function to the end of the text "Draw".
CrossRefData.Next = Invalid, assuming there are no other references
                   to MyTagType’s Draw method on the page.

If you wanted to find all the external references in a section of code (i.e. all references to values that aren’t actually declared in the MyPage module), then you could use the function like so:

CrossRefData = CrossReference(\MyPage, Invalid, \Code);

You would expect the linked list in CrossRefData to have nodes for each of the following: Tag23, Draw, Flow, and Value since they are all variables that were not declared in MyPage.

If, for example, the CrossReference code was not able to find a variable called Flow in Code, then the Reference value for that node in the CrossRefData would be the text "Flow" rather than a variable value for Flow. This is because there simply wasn’t a variable named Flow declared in the app. The node for Value would also have the text "Value" instead of a variable value, because if it cannot find the variable for Flow, it follows that it won't find Flow\Value.

The linked list of structures, as returned by this function, are ordered such that the Begin fields are in strictly descending order for each unique file. This is because, if the list is processed in the order returned then multiple search and replace processes done within the same file will not interfere with each other .

All structures for a given file are consecutive in the linked list. In other words, the last reference in the source file will be the first one on the list.

The following tasks can be facilitated without the need to run the code being examined:

  • Changing the name of a variable or module
  • Moving a variable or module to a different scope
  • Removing references to a deleted variable or module
  • Giving a cross-reference to locations where a variable or module is referenced
  • Re-ordering the parameters to a module
  • Locating all variable or module references in a higher scope


CryptRandom

Description: | Returns a buffer of random byte values.
Returns: | Text
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | GenerateHMAC | Hash |DeriveKey |Encrypt |Decrypt |
Format: | CryptRandom(Length)
Parameters: |
Length
Required. Any numeric expression giving the number of bytes to create.
Comments The randomness complies with NIST SP800-90.

Example:

[
  RandomText;
]
Init[
  If 1 Main;
  [
    RandomText = CryptRandom(16);
  ]
]
Main [ ...

RandomText will contain a buffer with 16 bytes of random values.


CurrentLine

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Returns the text string that is the current line in an editor.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Editor
Related to: | WinEditCtrl
Format: | CurrentLine(Editor)
Parameters: |
Editor
Required. Any expression that returns an editor value that was created by the MakeEditor function. If this isn't an editor type value, or if it is invalid, nothing happens.


CurrentTime

(Engine-Level Function)

Description: | Returns the number of seconds, in local or UTC time, since midnight of January 1, 1970 (where "midnight" is 00:00).
Returns: | Numeric (double)
Usage: | Script only.
Function Groups: | Time and Date
Related to: | Now | Seconds | Today | TimeArrived
Format: | CurrentTime([TimeType] )
Parameters: |
TimeType
Any expression that evaluates to a 0 or 1. When 0, it indicates that time returned should be local time.
If set to 1, indicates that the current UTC time should be returned.
Defaults to 0 if missing or Invalid.
Comments:

This function solves the problem encountered when using Seconds together with Today to determine the current date and time, when the time is within a fraction of a second of midnight.
This function assumes that "midnight" on January 1, 1970 is 00:00, rather than 24:00 on a 24-hour clock.
The returned value is accurate to three decimal points (milliseconds).

Refer to the notes at the end of Working in Steady State for an example of how to use this (and similar) functions in a Steady State context.

Example 1:

  If ! Valid(RightNow);
  [
    RightNow = CurrentTime();
  ]

This assigns the current time in seconds since midnight on January 1, 1970 to the double variable RightNow.

Example 2:

You may have a need to format a CurrentTime value for display to a user.

Given that there are 86400 seconds in a day, you can format the timestamp as follows:

  If ! Valid(LocalNow);
  [
    LocalNow = CurrentTime(0);
    DisplayNow = concat(Date(LocalNow / 86400, 4), " - ",
                             Time(LocalNow % 86400, 2));
  ]


CurrentWindow

(Engine-Level Function)

Description: | Returns the application window over which the mouse cursor rests.
Returns: | Object Value
Usage: | Steady State only.
Function Groups: | Locator, Window
Related to: | ActiveWindow | WinLocSwitch | WinXLoc | WinYLoc | Window
Format: | CurrentWindow( )
Parameters: | None
Comments: | The return value is the object value of the module instance running in the window that the mouse cursor is over. This is not necessarily the active window. If more than one module instance is running in that window, the return value will be the highest scope module instance running in that window, which should either call or be the parent or ancestor of all other module instances in that window. Unlike the ActiveWindow function, CurrentWindow will recognize and return the object value of the root module instance in child windows when the mouse passes over them. This function is useful for things like status lines, or help windows. It works only on windows that belong to VTScada.

Example:

  Obj = CurrentWindow();
  WinX = WinXLoc(obj);
  WinY = WinYLoc(obj);
  WinB = WinLocSwitch(obj);

This shows how to get information about the mouse in another window. This window is determined to be the window the mouse is passing over. WinX and WinY have the mouse location (which works like XLoc and YLoc), and WinB has the current mouse button combination (like LocSwitch).


D Functions

The sections that follow identify all VTScada functions beginning with "D".


Date

(Engine-Level Function)

Description: | Returns a text string giving the date that corresponds to the number of days since January 1, 1970.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | DateNum | Day | Month | Now | Time | Today | Year
Format: | Date(Day, DateForm [, Flags, Locale])
Parameters: |
Day
Required. Any numeric expression giving the number of days since January 1, 1970. This is a "Julian" style date. The function, Today() is commonly used.
DateForm

Required. Any numeric or text expression selecting the format for the date format. Will also accept a date locale such as "us-en", matching the Windows locale. If DateForm is numeric, the format for the date will be interpreted according to the standard Date Formatting Codes.
If DateForm is a text value, it is interpreted as a date formatting string. Please refer to the Date Formatting Strings in the appendix. Note that these key strings are case sensitive.

In the event that the DateForm parameter does not resolve to either a numeric or text value, the system-configured date format, as specified through the Windows Control Panel, is used. In this case, the Flags parameter is used to select from a number of options for the date.

Flags

An optional parameter that is only used in the event that the DateForm parameter does not resolve to a numeric or a text value. The Flags parameter may be set as follows to adjust the format of the date.

Flags | Description
1 | Generate the configured short form of the date (e.g. "29/03/04").
2 | Generate the configured long form of the date (e.g. "29 March 2004").
8 | Generate the configured year/month format (e.g. March 2004). Please note that this option is only available on Windows 2000/XP
Locale
Optional text. May be used to specify a locale for which to format the date. Use Windows-standard locale strings, such as "en-us".
Comments:

This function is primarily used to convert dates from historical data files to a format that is more easily readable. The Julian style date is used since it gives an easy method of calculating the time between dates and it is compact for historical records.

If Date is used with a predefined date code, then the result will always be in English, regardless of any system settings.

If Date is used with a format string, such as "dd MMMM yyyy", then the result will be in the user's locale. For example, "25 Febrero 2014"

Script Example:

  ZText(10, 590, Date(Today(), 4), 15, 0);

This displays today's date in the lower left of the screen.

Expression Example:

Date(Today(), 4)

This returns today's date as text in the form "Aug 13, 2012"


DateNum

(Engine-Level Function)

Description: | Returns the number of days since January 1, 1970 for a given date.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | Date | Day | Month | Today | Year
Format: | DateNum(Day, Month, Year[, ValidateInputRanges])
Parameters: |
Day
Required. Any numeric expression giving the day of the month for the date.
Month
Required. Any numeric expression giving the month number for the date. January is month 1.
Year
Required. Any numeric expression giving the year of the date. The full four-digit date must be used.
ValidateInputRanges

Optional Boolean. If set to TRUE, this function will validate the Day and Month parameters to be in their valid range.

If both Day and Month are legal values for the given year, DateNum will return days since January 1, 1970, for a given date. Otherwise, this will return Invalid.

Defaults to FALSE, meaning that a value will be calculated without verification that the Day and Month parameters are within a valid range.

Comments: This function performs the inverse function of the Day, Month, and Year functions.

Example:

  NumDays = DateNum(14, 11, 1986);

NumDays is set to 6161, which is the number of days between 1 January 1970 and 14 November 1986.


DateSelector

(System Library)

Description: | Displays a calendar, from which operators can select a date.
Returns: | Timestamp (within a parameter).
Usage: | Steady State only.
Function Groups: | Time and Date, Graphics
Related to: | Date | DateNum | Today
Format: | \DateSelector(ShowSelector, LeftParm, TopParm, PSelTimestamp[, HelpID, MinTimestamp, MaxTimestamp, pWidth, pHeight, DisabledDays, BackColorParm, TextColorParm, FontSizeParm, HighlightToday, FirstDayofWeek])
Parameters: |
ShowSelector
Sets the display mode. 1 to temporarily open the popup DateSelector. 2 to permanently show an embedded DateSelector.
Also used as a return value: 0 indicates that a date was selected, -1 indicates that the operator closed the popup without selecting a date.
LeftParm
Any numeric expression specifying the location of the left edge of the calendar.
TopParm
Any numeric expression specifying the location of the top edge of the calendar.
pSelTimestamp
Output. A pointer to a variable holding a timestamp value. The returned date from the calendar will be found here. You may also use this to hand an initial date to the calendar, to display when ShowSelector becomes true. If the initial date is not in range and no other date is selected, then the parameter will return invalid. No timestamp is returned if no date is selected.
HelpID
(Optional) Specific HelpID for this use of the DateSelector.
MinTimestamp
(Optional) Minimum selectable date. (the number of seconds, in local or UTC time, since midnight of January 1, 1970 (where "midnight" is 00:00) to the minimum selectable date.)
MaxTimestamp
(Optional) Maximum selectable date. (the number of seconds, in local or UTC time, since midnight of January 1, 1970 (where "midnight" is 00:00) to the maximum selectable date.)
pWidth
(Optional) Returns pointer set to width of the calendar.
pHeight
(Optional) Returns pointer set to height of the calendar.
DisabledDays
(Optional) Bitwise. Days of the week that are disabled: 0bSFTWTMS, read right-to-left. eg. 0b1110001 disables Sunday, Thursday, Friday. Saturday.
BackColorParm
(Optional) Background color. Default <FFFFFFFF> (white).
TextColorParm
(Optional) Text color. Default <FF000000> (black).
FontSizeParm
(Optional) Selected font size.
0 = small (default)
1 = medium
2 = large
3 = X-large
4 = XX - large
HighlightToday
(Optional) Boolean. TRUE to highlight today's date. Default TRUE.
FirstDayOfWeek
(Optional) The weekday considered first (Sunday = 0).
Comments: The function returns an object variable of itself upon starting, in case the calling module requires it.
You can monitor the value of ShowSelector to know whether the operator selected a date (ShowSelector becomes 0). If the calendar is shown as a popup, ShowSelector becomes -1 if the calendar is closed without choosing a new date.

Examples:

[
  ShowPopup;
  PopupLeft = 700;
  PopupTop = 550;
  Timestamp;

  MinTimestamp;
  MaxTimestamp;

  Width;
  Height;

  DisabledDays;
  BackColor;
  TextColor;
  FontSize;
  HighlightToday;
  FirstDayOfWeek;
]

Main [
  System.DateSelector(2, 0, 0, &Timestamp, Invalid,
                      MinTimestamp, MaxTimestamp,
                      &Width, &Height,
                      DisabledDays, BackColor, TextColor,
                      FontSize, HighlightToday, FirstDayOfWeek);
  System.DateSelector(2, Width + 10, 0, &Timestamp);
  System.DateSelector(ShowPopup, PopupLeft, PopupTop, &Timestamp, Invalid,
                      MinTimestamp, MaxTimestamp,
                      Invalid, Invalid,
                      DisabledDays, BackColor, TextColor,
                      FontSize, HighlightToday, FirstDayOfWeek);

  If ZButton(PopupLeft, PopupTop, PopupLeft + 100, PopupTop + 50, "Popup Calendar", 1);
  [
    ShowPopup = 1;
  ]
]


Day

(Engine-Level Function)

Description: | Returns the day of the month for a given date number.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | Date | DateNum | Month | Today | Year
Format: | Day(Date)
Parameters: |
Date
Required. Any numeric expression giving the number of days since January 1, 1970.
Comments: This function works in conjunction with the Month and Year functions to decompose a date into the corresponding day, month and year.

Example:

  DayOfMonth = Day(Today());

This causes DayOfMonth to be set to today's day of the month.


DBAdd

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: Executes in its own thread to add a record to a VTScada database and returns an indication of parameter errors.
Returns: Numeric
Usage: Script Only.
Function Groups: Database and Data Source
Related to: DBAdd | DBGetStream | DBListGet | DBListSize | DBRemove | DBSystem | DBTransaction | DBUpdate | DBValue
Threaded: Yes
Format: DBAdd(DBSysVal, IDKey, DefaultEvent, EventCode [, FieldVal])

Or

DBAdd(DBSysVal, IDKey, DefaultEvent, EventCode [, FieldVal1, FieldVal2, FieldVal3, …])
Parameters:
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
IDKey
Required. Any text expression that uniquely identifies the record to be created.
DefaultEvent

Required. Any text expression containing one byte for each list in the system. Any missing bytes or bytes with values not included in the list provided, default to "do nothing to the list". Note that there is one byte for each list in the system.

Text Value | Default Event
+ | Add to list
<space> | Do nothing to list
EventCode

Required. Any variable in which the event code for the function is returned. This parameter may be used to indicate completion of the function, as it will not be set to a valid value until execution is complete. It has one of the following meanings:

EventCode | Meaning
0 | New record added
1 | Record already existed. it was updated
2 | Error occurred - record not added

EventCode may be replaced by a constant or Invalid if it is not required. This parameter will not be set if there is a parameter error (see comments)

FieldVal
(or FieldVal1, FieldVal2, FieldVal3, … )
One or more parameters that are an array or a list of values for each field. FieldVal (or FieldVal1, FieldVal2, FieldVal3, … ) will be set to Invalid if not specified, if insufficient parameters are specified to fill each field in the new database record, or if the parameter is an array with insufficient entries to fill each field in the database.
Comments:

This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for EventCode becoming valid (marking that the statement has finished executing) is unpredictable and should therefore be checked for validity prior to executing other statements that rely on this statement's results.

The return value for this function indicates if any of its key parameters (DBSysVal, IDKey, DefaultEvent, or any required FieldVal) are illegal. It will immediately return a value of false (0) unless a key parameter was illegal, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it.

If the record that is to be added already exists (i.e. its IDKey duplicates one already in the system), the field values of the pre-existing record are updated by those defined in the FieldVal parameter(s).
If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

  AlarmDB = DBSystem("", "", 0, 0, 32 { key }, -3 { pressure },
                     3 { level }, -3 { temperature });
  If Valid(AlarmDB) && !added;
  [
    Added = TRUE;
    DBAdd(AlarmDB { Database to use },
          "Tank_697" { ID key },
          "+" { Add to list },
          event { Var to get event code },
          pressure, level, temperature
    { Field values }));
  ]


DBDropList

(ODBC Manager Library)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: | Populates a droplist using the results of an SQL query on a given database.
Format: | \ODBCManager\DBDropList( X1, Y1, X2, Y2, DSN, UserName, Password, SQLQuery, Title, LocFocusID, Init, Var[, DrawBevel, AlignTitle, AddInvalid, InvalidText])
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Database and Data Source
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Parameters: |
X1
Required. Screen coordinates of the left side of drop list
Y1
Required. Screen coordinates of the top of list
X2
Required. Screen coordinates of the right side of the list
Y2
Required. Screen coordinates of the bottom of list
DSN
Required. DSN of the database to query
UserName
Required. The user name in the database for authentication.
Password
Required. The password in the database for authentication.
SQLQuery
Required. An SQL query that returns either one or two columns. The first column is used for droplist display, the second (if it exists) provides the matching value for each entry in the list.
Title
Required. The title for the drop list
LocFocusID
Required. Numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the droplist will display its current setting, but will not be able to be opened (i.e. its value cannot be changed) and will appear grayed out. The default value is 1.
Init
Required. Any expression for the initial value displayed in the field
Var
Required. A variable whose value will be set by this droplist
DrawBevel
Optional. If true (non-0) a bevel is drawn around the droplist. If false (0) no bevel is drawn. The default value is false
AlignTitle
Optional. If true (non-0) the title is included in the calculation for vertical alignment. If false(0) it is added to the droplist after it (and its bevel if one exists) has been vertically aligned. The default is true
AddInvalid
Required. If true an entry with an invalid value will be added at the top of list.
InvalidText
Required. Used with AddInvalid to provide the text to display for the item at the top of the list.
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.


DBGetStream

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: | Converts a database to a stream, and returns an indication of parameter errors.
Returns: | Numeric
Usage: | Script
Function Groups: | Database and Data Source, Stream and Socket
Related to: | DBAdd | DBInsert | DBListGet | DBListSize | DBRemove | DBSystem | DBTransaction | DBUpdate | DBValue
Threaded: | Yes
Format: | DBGetStream(DBSysVal, Stream [, Timestamp])
Parameters: |
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
Stream
Required. Any variable in which the stream containing the database will be returned.
Timestamp
Optional. An optional parameter that is any numeric expression indicating the earliest timestamp to include in the stream. Only database records with date/time values greater than or equal to this parameter will be returned.
Comments: The return value for this function indicates if its key parameter (DBSysVal) is invalid

If DBSysVal is valid, DBGetStream will immediately return a value of false (0).
If DBSysVal is invalid, DBGetStream will not perform the required operation, and will instead immediately return a value of 1.

Note that the return value only signals completion of the function's execution if it is true.
Because the value of the Stream parameter is created from a database's file, the DBSystem function that created the database had to have a valid first parameter (the file name in which the database contents are stored).
If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

  Db = DBSystem("", "", 0, 0, 32 { key }, -3 { pressure },
                  3 { level }, -3 { temperature });
  If Valid(Db) && ! Done;
  [
    Done = 1;
    DBGetStream(Db { Database to use },
                Result { Returned stream value });
  ]


DBGridList

(ODBC Manager Library)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: | Populates a grid list using the results of a database query
Format: | \ODBCManager\DBGridList( DSN, UserName, Password, SelectQualifier, Fields, Tables, WhereFields, WhereOperators, WhereValues, WhereAndFlag, UserQuery, ColName, ColFormat, ColCellWidth, RowHeight, TitleHeight, ExtDisplayRef, AutoResizeWidths, OrderBy, LockFirstColParm, SortParm, SelectedRowParm, SelectedColParm, Horiz, Vert, Refresh, DataPtr)
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Database and Data Source
Related to: | GridList | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Parameters: |
DSN
Required. Datasource name to query.
UserName
Required. The user name in the database for authentication.
Password
Required. The user name in the database for authentication.
SelectQualifier
Required. SQL selection qualifier, such as "top 100" etc.
Fields
Required. An array of field names to query for
Tables
Required. An array of tables to query from
WhereFields
Required. An array of fields named for SQL WHERE clause
WhereOperators
Required. An array of Operators for the SQL WHERE clause
WhereValues
Required. An array of Array of values for the SQL WHERE clause
WhereAndFlag
Required. Set 1 for AND of where fields, reset for OR
UserQuery
Required. Overrides Fields, Tables, & Where when defined
ColName
Required. Text array of titles for displaying data
ColFormat
Required. Text array of format qualifiers for each of the values.
ColCellWidth
Required. Array giving the size to use for the cells columns
RowHeight
Required. Height of the data rows. Set to invalid to use the defaults.
TitleHeight
Required. Height of the column titles. Set to invalid to use the defaults.
ExtDisplayRef
Required. Object value of where ColFormat modules located
AutoResizeWidths
Required. Automatically resize the widths to fit the available space
OrderBy
Required. Field names for ORDER BY clause only used
LockFirstColParm
Required. TRUE to lock column 0 while horizontal scrolling
SortParm
Required. Enables grid list sorting
SelectedRowParm
Required. 0 - based value of row of selected item
SelectedColParm
Required. 0 - based value of column of selected item
Horz
Required. Horizontal scroll position
Vert
Required. Vertical scroll position
Refresh
Required. Set flag to re-query data
DataPtr
Required. Pointer to data read from db in [Col][Row] format
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.


DBInsert

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: Identical to DBAdd, except that it will not modify an existing record. Executes in its own thread to add a record to a VTScada database and returns an indication of parameter errors.
Returns: Numeric
Usage: Script Only.
Function Groups: Database and Data Source
Related to: DBAdd | DBGetStream | DBListGet | DBListSize | DBRemove | DBSystem | DBTransaction | DBUpdate | DBValue
Threaded: Yes
Format: DBInsert(DBSysVal, IDKey, DefaultEvent, EventCode [, FieldVal])
Or
DBInsert(DBSysVal, IDKey, DefaultEvent, EventCode [, FieldVal1, FieldVal2, FieldVal3, …])
Parameters:
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
IDKey
Required. Any text expression that uniquely identifies the record to be created.
DefaultEvent

Required. Any text expression containing one byte for each list in the system. Any missing bytes or bytes with values not included in the list provided, default to "do nothing to the list". Note that there is one byte for each list in the system.

Text Value | Default Event
+ | Add to list
<space> | Do nothing to list
TimeStamp
Required. The time to be used for all lists that the new record is a member of. Current time will be used if this field is invalid.
EventCode

Required. Any variable in which the event code for the function is returned. This parameter may be used to indicate completion of the function, as it will not be set to a valid value until execution is complete. It has one of the following meanings:

EventCode | Meaning
0 | New record added
2 | Error occurred - record not added

EventCode may be replaced by a constant or Invalid if it is not required. This parameter will not be set if there is a parameter error (see comments)

FieldVal
(or FieldVal1, FieldVal2, FieldVal3, … )
One or more parameters that are an array or a list of values for each field. FieldVal (or FieldVal1, FieldVal2, FieldVal3, … ) will be set to Invalid if not specified, if insufficient parameters are specified to fill each field in the new database record, or if the parameter is an array with insufficient entries to fill each field in the database.
Comments: This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for EventCode becoming valid (marking that the statement has finished executing) is unpredictable and should therefore be checked for validity prior to executing other statements that rely on this statement's results.
The return value for this function indicates if any of its key parameters (DBSysVal, IDKey, DefaultEvent, or any required FieldVal) are illegal. It will immediately return a value of false (0) unless a key parameter was illegal, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it.

If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

  AlarmDB = DBSystem("", "", 0, 0, 32 { key }, -3 { pressure },
                     3 { level }, -3 { temperature });
  If Valid(AlarmDB) && ! Added;
  [
    Added = 1;
    DBInsert(AlarmDB { Database to use },
             "Tank_697" { ID key },
             "+" { Add to list },
             Event { Var to get event code },
             Pressure, Level, Temperature { Field values }));
  ]


DBListGet

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: | Executes in its own thread to retrieve certain records from a list in a VTScada database and returns an indication of parameter errors.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Database and Data Source
Related to: | DBAdd | DBInsert | DBGetStream | DBListSize | DBRemove | DBSystem | DBTransaction | DBUpdate | DBValue
Threaded: | Yes
Format: | DBListGet(DBSysVal, Result, Orientation, List, Start, Number, Method [, Events, IDKey, Filters, Sort, StartTime, StopTime, FieldVals]) (Note that FieldVals may be an array or a series of parameters: Field1, Field2, etc.)
Parameters: |
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
Result
Required. A variable in which the resulting array will be stored. The dimension of the array will match the number of fields requested.
Orientation
Required. Any logical expression that denotes the orientation of the resultant array. If true (non-0) each record retrieved forms its own row, with each column representing a field. If false (0), the reverse holds true. This means that with Orientation set to 1, if 5 fields were requested in the FieldVals parameter(s), the resultant array would be R[n][5], where n is the number of matching records found.
List

Required. Any numeric value or array of numeric values that define(s) the list(s) to search.

(See: Bitwise Parameters & Operations)

Value | List
-1 | Entire database
0 | Transaction log
Number, starting at 1 | The specific list number

The database and transaction log cannot be combined with other lists.

Start
Required. Any numeric expression for the first match to include, beginning at 0.
Number
Required. Any numeric expression for the maximum number of matches to return.
Method

Required. Any numeric expression that determines what elements to include in the list. This parameter is one or a combination of the following values

Method | Bit No. | Method Description
0 | - | No filtering (include everything)
1 | 0 | Event filtering
2 | 1 | ID key filtering
4 | 2 | Record value filtering
8 | 3 | Sort as per the Sort parameter
16 | 4 | Limits the records returned to the times supplied in the StartTime and StopTime parameters
32 | 5 | Pull records starting from the current offset or record position in the file. Applies only to VTScada database log files and only if they are not sorted.

The filtering/sorting parameters follow (in the specified order), with only those that are applicable being included. If the bit for a certain type of filtering has been set, a parameter corresponding to that option must exist. If a bit is not set, the parameter corresponding to that option should not be included. Setting it to invalid is not acceptable. If a Sort is requested, but the Sort Options parameter is passed in as invalid, then the function will behave as if a sort had not been requested.

Notes for bit 5: do not use a number of matches to skip, even though this would work properly. (That is, starting from the existing position in the log file, n matches would be skipped.) Care must be taken, since if something else changes the current position in the file (a transaction or another DBListGet), then you may not get the records you are expecting. After the initial DBListGet, subsequent DBListGet calls can set bit 5, adding a value of 32 to the method, to use the offset as it was left by the last pull.

Events

Optional. Used for filtering the records in the list and should only be included if Method designates event filtering (1). This value is a text string containing one byte for each list in the system. Any missing bytes default to all for that list, while bytes with values not included in the following list default to no matches (i.e. nothing will be found).
Note that there is one byte for each list in the system, not for each list that has been selected by the List parameter.
If the transaction log is being used (List = 0), the following codes are compared with the Event field of each record

Events | Added to List | Removed from List | No Changes
0 | none (nothing is ever selected) |  |
1 or + | √ |  |
2 or - |  | √ |
3 | √ | √ |
4 or <Space> |  |  | √
5 | √ |  | √
6 |  | √ | √
7 or * | √ | √ | √

If one of the lists is being used (List > 0), the following codes are used:

Value | Added to List
0 or 4 | None (nothing is ever selected)
1, 5, or + | On the list
2, 6, or - | Not on the list
3, 7, or * | All (everything is selected)
IDKey
Optional. Used for designating the record(s) to use and should only be included if Method designated ID key filtering. It is any text expression and can contain the wildcard characters "*" and "?".
Filters

Optional. Designates the record(s) to use to filter the resulting list by using logical ANDing and ORing and checking for field matches. It should be included only if Method designated record value filtering.
At its simplest, this parameter may hold a 1-dimensional array with 2 or 3 numeric elements.

Element | Description
0 | Field to use (-1 filters on date/time values. -2 filters on ID key)
1 | Limiting value
2 | Comparison value

If (and only if) you are creating an alarm filter that is specifically for use only with the alarm name field (\AlarmNameField -2), then two additional parameters are required, having the following values. This allows the translation of the alarm UniqueID, which is held in the record, to the friendly name used in the search string.

Element | Value
3 | VTSDB
4 | \AlarmSeparatorString

The comparison value is a numeric value or expression that indicates the type of comparison to be made, and may be omitted if desired. In this case, the comparison will be taken to mean "is equal to". Valid values for this third element are as follows:

Comparison Value | Comparison | Case Sensitive
0 | Equal to | no
1 | Greater than | no
2 | Less than | no
3 | Specified by wildcard (field value is text) | no
4 | Not equal to | no
5 | Less than or equal to | no
6 | Greater than or equal to | no
7 | Opposite of wildcard specification (field value is text) | no
8 | Equal to | yes
9 | Greater than | yes
10 | Less than | yes
11 | Specified by wildcard (field value is text) | yes
12 | Not equal to | yes
13 | Less than or equal to | yes
14 | Greater than or equal to | yes
15 | Opposite of wildcard specification (field value is text) yes |
16 | Is the specified bit set? 20 (16 + 4) for not-set. | no

Note that the comparison values of 3, 7, 11, and 15 are only useful when the field value is a text string. For example, if you want to get only those entries whose value starts with "d", the field value should be "d*", and the comparison value should be 3. If you want all entries that don't start with "d", the field value should still be "d*", with a comparison value of 7.

If a more detailed filtering criterion is required, a 2-dimensional array may be used, where additional rows are added, each with the same elements as the first ([n][0] is field number, [n][1] is limiting value, [n][2] is comparison type). All rows will then be ANDed together to form the filtering statement. Once again, the third column may be omitted entirely, however, if it exists it must have valid values in all rows.

The most detailed filtering array occurs when an ORing of field specifications is also required. In this case, this parameter is a 1-dimensional array, where each element contains a pointer to an array as described previously. The elements in each AND array will be ANDed together, then the results from these ANDed arrays will be ORed.

VTScada differentiates between the various options for this parameter by checking its first element. If it is not a pointer, then the parameter is assumed to contain a single AND array directly (i.e. no OR is performed). It should only be included if Method designated record value filtering.

Sort

Optional. Used for defining the type of sort to be done. Currently, only the bin type of sort is supported where, in a single pass through the array, records are grouped together based on having the same value in the specified field. Sorting may only be performed on numeric data.
This parameter is a 1-dimensional array (not one that is created via a New function call), whose elements have the following meanings

Element | Description
0 | Method of sorting (1) for bin sort
1 | Field number to sort on
2 | Flag indicating descending order sort
3 | Number of values (bins) to use. Valid range is 1 to 1024
4 | Lower limit (start) of range

In the case of elements 3 and 4, if the third element is 6, for example, and the fourth element is 5, all records whose specified field has a value from 5 (lower limit) through to 10 (includes 6 elements) will be sorted, while all others will be discarded.

StartTime
Optional. Specifies the oldest record in the file to be used, in the case that bit 4 is set in Method.
StopTime
Optional. Specifyies the newest record in the file to be used, in the case that bit 4 is set in Method.
FieldVals / FieldValN

Optional. A parameter or series of parameters that is either an array or a list of values that indicate which field(s) for which data is requested. If omitted, all fields are returned in their default order. Field numbers range from 1 to 255. The valid values for this parameter are

FieldVals | Field Type Attribute
-2 | ID key
-1 | Date/time value
0 | Event/status for record
1 | or more Field value

Note: In the case of an array, it must be a static array - a dynamically declared array (one that is created via a New function call), it will not work here.

Comments:

This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for Result becoming valid is unpredictable and should therefore be checked for validity prior to being used.

The return value for this function indicates if any of its key parameters (DBSysVal, Orientation, List, Start, Number or Method) are invalid.

If all of the key parameters are valid, DBListGet will immediately return a value of false (0).
If any of the key parameters are invalid, DBListGet will not perform the required operation, and will instead immediately return a value of 1.
If the database uses lists then the list parameter may be greater than 0 to select values that appear on that list. For example, when retrieving alarms from their db instance, the following values can be used

Value | List
1 | Active alarm list
2 | Unacknowledged alarm list
3 | Disabled alarm list

For information about the standard alarm lists in VTScada see "Alarm Manager Service".

Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it.

The dimension of Result will depend on the number of fields requested.

If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

  DbVal = DBSystem("c:\vts5\app6\equip.db", "", 0, 0, 64 { key },
                   3 { field 1 }, -2 { field 2 }, -3 { field 3 });
  If Valid(DbVal) && ! Retrieved;
  [
    Retrieved = 1;
    DBListGet(DbVal { Database value },
              Final { Resultant array },
              0 { Orientation },
              1 { Use entire database },
              0 { Include from first match on },
              20 { Number of matches to get },
              2 { Method - filter by ID key },
              { Events parameter not required }
              "Motor*" { Match with ID key },
              { Filters/Sort parameters not required }
              2 { Get ID key field },
              2 { Get field 2 also });
  ]

If there is any doubt as to the validity of the parameters and further statements rely on final becoming valid, the following version of the script might be more appropriate.

  If Valid(DbVal) && ! Retrieved;
  [
    Retrieved = 1;
    IfThen(DBListGet(DbVal, Final, 0, -1, 0, 20, 2, "Motor*", -2, 2),
           Final = 0;
    );
  ]


DBListSize

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: | Executes in its own thread to retrieve the size of a certain list in a VTScada database and returns an indication of parameter errors.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Database and Data Source
Related to: | DBAdd | DBInsert | DBGetStream | DBListGet | DBRemove | DBSystem | DBTransaction | DBUpdate | DBValue
Threaded: | Yes
Format: | DBListSize(DBSysVal, Result, List, Method [, remaining parameters vary according to Method value])
Parameters: |
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
Result
Required. A variable in which the resulting 1 or 2 dimensional array will be stored.
List

Required. Any numeric value or array of numeric values that define(s) the list(s) to search

List | List Description
-1 | Entire database
0 | Transaction log
Number, starting at 1 | The specific list number

The database and transaction log cannot be combined with other lists.

Method

Required. Any numeric expression that determines how filtering is done. This parameter is one or a combination of the following values

Method | Bit No. | Method Description
0 | - | No filtering (include everything)
1 | 0 | Event filtering
2 | 1 | ID key filtering
4 | 2 | Record value filtering
8 | 3 | Place holder for future use
16 | 4 | A supplied date range should be used for filtering. .

Note that the ability to filter for a supplied date range applies only to VTScada database log files. An example of the format of the supplied date range can be found in the Examples section of this topic.

The filtering parameters follow (in the specified order), with only those that are applicable being included.

Events

Optional. Used for filtering the records in the list and should only be included if Method designated event filtering. This value is a text string containing one byte for each list in the system. Any missing bytes default to all for that list, while bytes with values not included in the following list default to no matches (i.e. nothing will be found). Note that there is one byte for each list in the system, not for each list that has been selected by the List parameter.
If the transaction log is being used (List = 0), the following codes are compared with the Event field of each record

Value | Added to List | Removed from List | No Changes
0 | none (nothing is ever selected) |  |
1 or + | Ö |  |
2 or - |  | Ö |
3 | Ö | Ö |
4 or <Space> |  |  | Ö
5 | Ö |  | Ö
6 |  | Ö | Ö
7 or * | Ö | Ö | Ö

If one of the lists is being used (List > 0), the following codes are used:

Value | Added to List
0 or 4 | None (nothing is ever selected)
1, 5, or + | On the list
2, 6, or - | Not on the list
3, 7, or * | All (everything is selected)
IDKey
Optional. Used for designating the record(s) to use and should only be included if the parameter Method designates ID key filtering. This is any text expression and can contain the wildcard characters "*" and "?".
Filters

Optional. Designates the record(s) to use to filter the resulting list by using logical AND or, OR and checking for field matches. It should only be included if the parameter Method designates record value filtering.
At its simplest, this parameter may hold a 1-dimensional array with 2 or 3 numeric elements

Filters | Description
0 | Field to use (-1 filters on date/time values)
1 | Limiting value
2 | Comparison value

If (and only if) you are creating an alarm filter that is specifically for use only with the alarm name field (\AlarmNameField -2), then two additional parameters are required, having the following values. This allows the translation of the alarm UniqueID, which is held in the record, to the friendly name used in the search string.

Element | Value
3 | VTSDB
4 | \AlarmSeparatorString

The comparison value is a numeric value or expression that indicates the type of comparison to be made, and may be omitted if desired. In this case, the comparison will be taken to mean "is equal to". Valid values for this third element are as follows:

Value | Comparison | Case Sensitive
0 | Equal to | no
1 | Greater than | no
2 | Less than | no
3 | Specified by wildcard (field value is text) | no
4 | Not equal to | no
5 | Less than or equal to | no
6 | Greater than or equal to | no
7 | Opposite of wildcard specification (field value is text) | no
8 | Equal to | yes
9 | Greater than | yes
10 | Less than | yes
11 | Specified by wildcard (field value is text) | yes
12 | Not equal to | yes
13 | Less than or equal to | yes
14 | Greater than or equal to | yes
15 | Opposite of wildcard specification (field value is text) yes |
16 | Is the specified bit set? 20 (16 + 4) for not-set. | no

Note that the comparison values of 3, 7, 11, and 15 are only useful when the field value is a text string. For example, if you want to get only those entries whose value starts with "d", the field value should be "d*", and the comparison value should be 3. If however, you want all entries that don't start with "d", the field value should still be "d*", with a comparison value of 7.

If a more detailed filtering criterion is required, a 2-dimensional array may be used, where additional rows are added, each with the same elements as the first ([n][0] is field number, [n][1] is limiting value, [n][2] is comparison type). All rows will then be ANDed together to form the filtering statement. Once again, the third column may be omitted entirely, however, if it exists it must have valid values in all rows.

The most detailed filtering array occurs when an ORing of field specifications is also required. In this case, this parameter is a 1-dimensional array, where each element contains a pointer to an array as described previously. The elements in each AND array will be ANDed together, then the results from these ANDed arrays will be ORed.

VTScada differentiates between the various options for this parameter by checking its first element. If it is not a pointer, then the parameter is assumed to contain a single AND array directly (i.e. no ORing is performed). It should only be included if Method designated record value filtering.

Comments: This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for Result becoming valid is unpredictable and should therefore be checked for validity prior to being used.
The return value for this function indicates if any of its key parameters (DBSysVal, List, or Method) are invalid.
If all of the key parameters are valid, DBListSize will immediately return a value of false (0).
If any of the key parameters are invalid, DBListSize will not perform the required operation, and will instead immediately return a value of 1.
If no filter being used at all, the function reports the number of records stored in the header of the underlying formatted file class, rather than counting records one by one.
Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it.
If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.
For information about the standard alarm lists in VTScada see "Alarm Manager Service".

Example:

  Db = DBSystemDBSystem(DbFile, "", 0, 0, 64 { key }, -3 { field 1 });
  If Valid(db) && ! GotSize;
  [
    GotSize = 1;
    DBListSize(Db { Database to use },
    Size { Resultant value },
    2 { List number to use },
    0 { Method - include everything }
      { Events parameter not required }
      { IDKey parameter not required }
      { Filters parameter not required });
  ]

If there is any doubt as to the validity of the parameters and further statements rely on size becoming valid, the following version of the script might be more appropriate.

  If Valid(Db) && ! GotSize;
  [
    GotSize = 1;
    IfThen(DBListSize(db , size, 2, 0 ),
           size = 0;
    );
  ]

If filtering for a supplied date range:

  DBListSize(DBLogVal, MatchingRecords, 0 { Log list },
             16 { date range method}, ClientTime, ServerTime)


DBRemove

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: | Executes in its own thread to remove a record from a VTScada database and returns an indication of parameter errors.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Database and Data Source
Related to: | DBAdd | DBInsert |DBGetStream | DBListGet | DBListSize | DBSystem | DBTransaction | DBUpdate | DBValue
Threaded: | Yes
Format: | DBRemove(DBSysVal, IDKey [, EventCode])
Parameters: |
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
IDKey
Required. Any text expression used for designating the record(s) to delete. Can contain the wildcard characters "*" and "?".
EventCode

Optional. Any variable in which the event code for the function is returned. This parameter may be used to indicate completion of the function, as it will not be set to a valid value until execution is complete. It has one of the following meanings

EventCode | Meaning
0 | Record(s) deleted
1 | Error occurred - record(s) not deleted

EventCode will not be set if there is a parameter error (see comments).

Comments: This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for EventCode becoming valid (marking that the statement has finished executing) is unpredictable and should therefore be checked for validity prior to executing other statements that rely on this statement's results.
The return value for this function indicates if any of its key parameters (DBSysVal or IDKey) are invalid. It will immediately return a value of false (0) unless a key parameter was invalid, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it.
If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

  MyDB = DBSystem(DbFile, "", 0, 0, 64 { key }, 10 { field 1 });
  If Valid(MyDB) && ! Killed;
  [
    Killed = 1;
    DBRemove(MyDB { Database to use },
             "Digital*" { ID key },
             eCode { Event code returned });
  ]


DBSystem

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: Creates a VTScada database and returns its value. The maximum field length is 65,523 characters. If the field length is longer than 65,523 characters, the DBSystem call will return invalid.
Returns Numeric
Usage: Steady State only.
Function Groups: Database and Data Source
Related to: DBAdd | DBInsert | DBGetStream | DBListGet | DBListSize | DBRemove | DBTransaction | DBUpdate | DBValue
Format: DBSystem(DBFile, DBTransFile, MaxTrans, NumLists, IDKeySize, FieldAttribs)

Or

DBSystem(DBFile, DBTransFile, MaxTrans, NumLists, IDKeySize, FieldAttrib1, FieldAttrib2, FieldAttrib3)
Parameters:
DBFile
Required. A text expression giving the file in which to store the database information. If this parameter is invalid or is a null text string (""), no file is created and the database is reconstructed every time the system starts. DBFile can be an array containing 1 or 2 file names or streams. On startup, the second stream will be brought into sync with the first. The first is only read to initialize the database system. Both streams are maintained while the system is running.

Note that the value for this parameter may not be changed while the DBSystem call is active (i.e. the file cannot change) - any changes will be ignored.
DBTransFile
Required. A text expression giving the file in which transactions are logged. If this parameter is invalid or is a null text string (""), no file is created and no transaction logging is done. Unlike the DBFile parameter, the value of this parameter may be changed even while the DBSystem function is active (i.e. the file is dynamic).
MaxTrans
Required. Any numeric expression giving the maximum number of transactions to be stored in the transaction log file.
NumLists
Required. Any numeric expression giving the number of memory lists to be maintained. The valid range is from 0 to 255.
IDKeySize
Required. Any expression that designates the maximum length for the ID key. This affects the size of the files and the database stored in memory.
FieldAttribs
Required. Either an array or a series of parameters that defines what type and size the fields are. The number of parameters or array entries determines how many fields there are. The valid field types are
FieldAttribs | Field Type | Attribute
-4 | Indicates a VTScada value field. | Any VTScada value may be written, but will only go into the in-memory copy of the database. The disk record will have a zero length field.
-3 | Double precision float | (8 bytes)
-2 | Long integer | (4 bytes)
-1 | Short integer | (2 bytes)
0 | Indicates a Status field | .
1 or more | Text | (number defines length)
Comments: This function is not threaded, however, it creates a thread inside of which the database value referring to the database system requested is accessed. All other database functions (those beginning with "DB"), except for DBValue, do not create their own thread, but will execute in the thread created by this function. This thread will exist for as long as the DBSystem statement remains active (i.e. until a state change occurs). For this reason, the state containing the DBSystem call must remain active until all other database statements have finished executing. The statement responsible for a state change should therefore trigger only when all results from all statements accessing this database are valid.

WARNING: There must only be one DBSystem function acting on a file at any given time, whether the file is used as the DBFile or the DBTransFile parameter. If more than one DBSystem function is affecting the same file, it may become corrupted, even if one of the database handles is only used to read information from the database.

The database system produced by this function consists of three primary parts

  • A memory database
  • A transaction log file
  • From 0 - 255 user specified lists

The memory database, as the name implies, is stored only in memory, and is created at the exact moment when the DBSystem function is first executed. The database value returned by this function remains valid as long as the statement is active.

The records in the database have three or more fields as follows:

  • The IDKey field - a unique text identifier for the record.
  • The Status field - a series of bytes, one for each of the user specified lists, that indicates which lists the record is part of.
  • Any other additional fields which have been designated to exist by the user.

For each ID key there is only one record in the database. This is not the case with the transaction log (discussed later in this topic). In the case of the database that is used to maintain the VTScada alarm system, each alarm has a single record in the database.

Although the database is not considered to be a list, it is loosely described as one in such statements as DBListGet, where a value of -1 for the List parameter will use the database rather than one of the user specified lists.

The transaction log is a log file that is saved to disk. For this reason, the larger it becomes the longer it takes to access records from the transaction log. The fields of the transaction log's records are similar to those stored in the database:

  • The IDKey field - a unique text identifier for the point associated with the record.
  • The Event field - a series of bytes, one for each of the user specified lists, that indicates the event or transaction that has just occurred.
  • The Time field - a float value that gives the time of the event, or a user written time value.
  • Any other additional fields which have been designated to exist by the user.

Like the database, it is not really considered a list, however in the DBListGet statement, a value of 0 in the List parameter will use the transaction log rather than one of the user specified lists.

The log file differs from the memory database in that for each ID key, there may exist none, one or many records that use the same key. This is because every transaction done by means of the DBTransaction statement is stored in a record in the transaction log.

The lists used by the database system are virtual lists, which means that they do not exist as actual entities of the system, but rather are composed of the records belonging to the database. The Status field of each record in the database will have exactly the same number of bytes as there are lists. This field will designate which list or lists the record is a member of. In the case of the VTScada alarm system, there are three lists, the active, unacknowledged and disabled alarm lists.

If the user wishes to use this database system simply as a storage device, rather than in a complicated series of lists and transactions like the VTScada alarm system, the NumLists parameter in this function may be set to 0 - no lists will be created. Also, the DBTransFile parameter may be set to invalid, thus disabling transaction logging and causing the transaction log file to not be created.

If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by the function becoming active.

Example:

  DbSysVal = DBSystem(dbFile { Name of database file },
                      "" { No transaction log },
                      0, 0 { No log, no lists },
                      65 { No. of chars in key },
                      16, 1 { No. of chars in fields 1, 2 },
                      3 { Field 3 is float },
                      1 { Field 4 is short (integer) });


DBTransaction

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: Executes in its own thread to perform a transaction on a VTScada database and returns an indication of parameter errors.
Returns: Numeric
Usage: Script Only.
Function Groups: Database and Data Source
Related to: DBAdd | DBInsert | DBGetStream | DBListGet | DBListSize | DBRemove | DBSystem | DBUpdate | DBValue
Threaded: Yes
Format: DBTransaction(DBSysVal, IDKey, Event, EventCode [, Timestamp, FieldVals])

Or

DBTransaction(DBSysVal, IDKey, Event, EventCode [, Timestamp, FieldVal1, FieldVal2, FieldVal3, …])
Parameters:
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
IDKey
Required. Any text expression that designates the record to use. It can contain the wildcard characters "*" and "?".
Event
Required. Any text expression containing on byte for each list in the system. Any missing bytes or bytes with values not included in the following list default to "do nothing to list". Note that there is one byte for each list in the system, not for each list that has been selected by the List parameter.
Text Value | Event
+ | Add to list
- | Remove from list
<space> | Do nothing to list
EventCode
Required. Any variable in which the event code for the function is returned. This parameter may be used to indicate completion of the function, as it will not be set to a valid value until execution is complete. It has the following meaning
Value | Meaning
0 | Record exists and was updated
1 | Record did not exist and was added
2 | Error occurred

EventCode may be replaced by a constant or Invalid if it is not required.
This parameter will not be set if there is a parameter error (see comments)

Timestamp
Optional. Defines the time to record for the event. If this value is invalid or omitted, the transaction time defaults to the current time. If it is negative, the database file will be updated with the absolute value of this parameter and the transaction log will not be updated.
FieldVals
Required when adding a new record, otherwise, optional. This takes the form of either an array or a list of values. In either case, this is data that is to be written to the database.
When writing to an existing record, the values provided will over-write the values in matching fields. When creating a new record, all fields must be defined.
Comments: This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for EventCode becoming valid (marking that the statement has finished executing) is unpredictable and should therefore be checked for validity prior to executing other statements that rely on this statement's results.
The return value for this function indicates if any of its key parameters (DBSysVal, IDKey or Event) are invalid. It will immediately return a value of false (0) unless a key parameter was invalid, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it.
If the user attempts to add a record to a list on which it already exists, that record's time and position on the list will be updated unless the new time is 0, in which case no change will occur.
If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

  Db1 = DBSystemDBSystem(DbFile, "", 0, 0, 64 { key }, 10 { field 1 }, 1 { field 2 }, -3 { field 3 });
  If ValidValid(Db1) && ! Done;
  [
    Done = 1;
    DBTransaction(Db1 { Database to use },
                  "Motor_425" { ID key },
                  "--+" { Subtract from lists 1 and 2, add to list 3 },
                  ECode { Event code },
                  CurrentTime() { Time of the event },
                  FieldValues { Array of values for fields });
  ]


DBUpdate

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

(Engine-Level Function)

Description: | Executes in its own thread to update a VTScada database from a given stream and returns an indication of parameter errors.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Database and Data Source
Related to: | DBAdd | DBInsert | DBListGet | DBGetStream | DBListSize | DBRemove | DBSystem | DBTransaction | DBValue
Threaded: | Yes
Format: | DBUpdate(DBSysVal, Stream [, EventCode])
Parameters: |
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
Stream
Required. Any stream value created from the contents of a database. This results from a DBGetStream statement.
EventCode
Required. An optional variable in which the event code for the function is returned. This parameter may be used to indicate completion of the function, as it will not be set to a valid value until finished executing. It has the following meaning
Value | Meaning
0 | Database successfully updated
1 | Update failed

EventCode may be replaced by a constant or Invalid if it is not required.
This parameter will not be set if there is a parameter error (see comments)

Comments: This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for EventCode becoming valid (marking that the statement has finished executing) is unpredictable and should therefore be checked for validity prior to executing other statements that rely on this statement's results.

The return value for this function indicates if any of its key parameters (DBSysVal or Stream) are invalid. It will immediately return a value of false (0) unless a key parameter was invalid, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it.

Because the value of the Stream parameter is created from a database, the DBSystem statement that created the database had to have a valid first parameter (the file name in which the database contents are stored). Do not attempt to access the database file directly via a FileStream statement if any DBSystem functions referencing this file are active, since the results may be unpredictable.

This function is useful to synchronize the database setup on two machines over a network. It allows a secondary machine to load the file from the first, thus duplicating its attributes precisely.
If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

  OldDB = DBSystem(OldFile, "", 0, 0, 32 { key }, 2 { field 1 }, 3 { field 2 });
  NewDB = DBSystem(NewFile, "", 0, 0, 32 { key }, 2 { field 1 }, 3 { field 2 });
  If Valid(NewDB) && ! GotStream;
  [
    GotStream = 1;
    DBGetstream(NewDB, Stream);
  ]
  If Valid(OldDB) && Valid(Stream) && ! Updated;
  [
    Updated = 1;
    DBUpdate(OldDB { Database to update },
             Stream { Database from which to update },
             Code { Event code holder });
  ]


DBValue

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: | Returns a certain value retrieved from a VTScada database.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Database and Data Source
Related to: | DBAdd | DBInsert | DBListGet | DBListSize | DBRemove | DBSystem | DBTransaction | DBValue
Format: | DBValue(DBSysVal, IDKey, FieldNumber[, ListNum])
Parameters: |
DBSysVal
Required. The database value to use. This is the return value from a DBSystem call.
IDKey
Required. Any text expression that designates the record to use. It can contain the wildcard characters "*" and "?".
FieldNumber
Required. Any numeric expression that indicates the field for which data is requested. Valid values for FieldNumber are as follows
Value | Meaning
-1 | A timestamp is required. A ListNum parameter must be supplied, specifying which list the timestamp is to be retrieved from.
0 | Event code for the record
1 to 255 | Indicates which piece of the record's data you wish to retrieve.
ListNum

Optional numeric. When FieldNumber is -1, specifying that a timestamp is required, then that timestamp will be taken from the numbered list in the DB system matching this parameter. The numbered lists start at zero.
See: DBSystem for related information.

Comments: Unlike most of the other database statements, this function is not threaded. Execution of all other statements will wait until this statement has completed execution and returned its result.
If no records matching IDKey are found, the return value will be Invalid.
If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

  MyDB = DBSystem(DbFile, "", 0, 0, 16 { key }, 2 { field 1 }, 3 { field 2 });
  If Valid(DBValue(MyDB { Database to use },
           "Motor_67" { ID key },
           1 { Field to get value from }) Next;
  [
    ...
  ]


DDE

(Engine-Level Function)

Description: | Returns the value of the data for a specific item from a DDE server program. This function is a DDE client.
Returns: | Varies
Usage: | Steady State only.
Function Groups: | DDE
Related to: | DDEPoke | DDEShareAdd | DDEShareDel | SetDDEServer
Format: | DDE(Program, Topic, Item[, Error, Trigger, pollTimeOut])
Parameters: |
Program

Required. Any text expression giving the name of the program which is the DDE server. This does not contain the .EXE extension. This is usually the same as the root file name of the executable file, but may be different as in the case of Microsoft Word for Windows 6.0 which uses the name "MSWord".

Topic

Required. Any text expression giving the DDE topic name within the server. For a VTScada server the topic name is usually the name of the window. For Microsoft Excel, the topic is the spreadsheet name.

Item
Required. Any text expression giving the location or name of the value to retrieve.
Error
Optional. A variable that will be set when an error occurs. Values may be as follows: 0=OK, -1=DDE is stopping, -2=FAILED
Trigger
Optional. If present, this indicates a "COLD" link as opposed to a "HOT" link (i.e. you have to poll the server to get an update, rather than it pushing updates to you).

When set to 1, this triggers a poll. The trigger is then reset.
pollTimeOut
Optional. If this is a COLD link (see Trigger) then pollTimeOut is the value in seconds of the time out for the poll.
Comments:

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.

This sets up a DDE client. After the link is established, the return value of the function will change whenever the value in the DDE server changes.

Example:

  cellValue = DDE("Excel", "Sheet1", "R1C1");

Upon execution of this statement, cellValue will contain the value of the cell in row 1, column 1 of the Excel spreadsheet called "Sheet1".


DDEPoke

(Engine-Level Function)

Description: | Sends a value for a specific item to a DDE server program.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | DDE
Related to: | DDE | DDEShareAdd | DDEShareDel | SetDDEServer
Format: | DDEPoke(Program, Topic, Item, Value)
Parameters: |
Program

Required. Any text expression giving the name of the program which is the DDE server. This does not contain the .EXE extension. This is usually the same as the root file name of the executable file, but may be different as in the case of Microsoft Word for Windows 6.0 which uses the name "MSWord".

Topic

Required. Any text expression giving the DDE topic name within the server. For a VTScada server the topic name is usually the name of the window. For Microsoft Excel, the topic is the spreadsheet name.

Item
Required. Any text expression giving the name or location of the value to send.
Value
Required. Any expression for the value to be sent, up to a maximum of 255 characters.
If this value is invalid, a null value (null text string) will be sent to the DDE server program.
Comments:

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.

After the link is established, new data will be sent to the server whenever Value changes. The return value is true (1) if successful and false (0) otherwise.

Example:

  success = DDEPoke("Excel", "Sheet1", "R1C1", "Connected");

Upon successful execution of this statement, the Excel spreadsheet called "Sheet1" will contain the word Connected in row 1, column 1, and success will have a value of 1. If the DDEPoke is not successful, success will be 0 and the Excel cell will retain its previous contents.


DDEShareAdd

(Engine-Level Function)

Description: | Adds a new DDE share name to the SYSTEM.INI file or the registry and returns its own error code.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | DDE
Related to: | DDE | DDEPoke | DDEShareDel | SetDDEServer
Format: | DDEShareAdd(Object, ShareName, Password)
Parameters: |
Object
Required. Any object expression giving the module instance whose variables' value will be shared.
ShareName
Required. Any text expression that gives the DDE share name other DDE enabled programs use to access the variables in Object.
Password
Required. Any text expression that gives the password required to access this DDE share name. If this is invalid, no password is required.
Comments:

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.

The return value of this function is true if successful, false if unsuccessful, and invalid if not attempted (i.e. invalid parameters).


DDEShareDel

(Engine-Level Function)

Description | Deletes a DDE share name from the SYSTEM.ini file or the registry and returns its own error code.
Returns | Boolean
Usage | Script Only.
Function Groups | DDE
Related to: | DDE | DDEPoke | DDEShareAdd | SetDDEServer
Format | DDEShareDel(ShareName)
Parameters |
ShareName
Required. Any text expression that gives the DDE share name.
Comments

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.

The return value of this function is true if successful, false if unsuccessful, and invalid if not attempted (i.e. invalid parameters).


DeadBand

(Engine-Level Function)

Description: | Returns the previous value of the first parameter until it changes by an amount specified by the second parameter.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Rounding Math
Related to: | Change | PID
Format: | Deadband(Value, Delta)
Parameters: |
Value
Required. Any numeric expression giving the value whose changes are to be limited to amounts no less than Delta.
Delta
Required. Any numeric expression giving the lower limit of the change in Value that will allow the function value to change. If Delta is less than or equal to 0, the function will always return Value.
Comments: When the function is first called, its value will be that of its first parameter Value. After that, the value will remain at this initial value until the difference between Value and the function value is greater than or equal to Delta. At this point, the function value will assume the new value of Value. This has the effect of ignoring all changes in Value which are less than Delta. This is useful for ignoring "noise" in values such as analog inputs. Because VTScada performs calculations based upon changes in values, this function may be used in certain situations to minimize the number of irrelevant value changes and thereby reduce the frequency of calculations and improve performance. This function may also be used by PID to eliminate noise in the process value parameter and therefore avoid making frequent minor output changes which are irrelevant.

The change specified by Delta is the absolute value of the change so a positive or negative change in Value will be treated equally. Delta should be always greater than zero.

Example:

...
  If Watch(1, Deadband(InletPressure, 0.5));
  [ ...

This triggers a script on startup and then again whenever the value of InletPressure changes by at least 0.5 units.

Related information:

Latching and Resetting Functions


Debugger

(System Library)

Description: | Starts the VTScada Debugger utility. (Not the Source Debugger)
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications
Related to: |
Threaded: | Yes
Format: | System.Debugger([Status, ViewModule, TxtAppName, MtSdView, Restrict])
Parameters: |
Status
Optional. Any numeric expression giving the enabled status of the window in which the debugger is displayed, as follows. The default value is 1 - Enabled.
Status | Meaning
0 | Disabled
1 | Enabled
2 | Enabled, bring to front
3 | Enabled, reload ViewModule, then bring to front
ViewModule
Optional. An object value selecting the current module or object to debug. No default value.
TxtAppName
Optional. Any text expression to be appended to the title bar of the debugger window. No default value.
MtSdView
Optional. Any logical expression. If true (non-0) the module tree and state diagram buttons are displayed on the debugger, if false (0), neither will be displayed. The default is false.
Restrict
Optional. Any logical expression. If true (non-0) VTScada system windows may not be selected for debugging, if false (0) any window may be selected by the debugger, including itself. The default is true.
Comments:

The utility that starts is the older Debugger, not the newer Source Debugger. It does not need to be loaded into the VAM in order to run when called by this function.

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Example:

  System.Debugger(1, Invalid, Invalid, 0, FALSE);


Decode

(System Library)

Description: | Returns the plain value of a cipher that is the result of the Encode function.
Returns: | String
Usage: | Script Only.
Function Groups: | Encryption
Related to: | Encode | BlockDecrypt | Base64Decode | Hash | Unpack
Format: | \System.Decode(CipherValue[, UnpackDictionary, Key, HashKey, pError]);
Parameters: |
CipherValue
Required. The information to be decoded.
UnpackDictionary
If a dictionary was used to pack the information as part of the encoding, the mirror of that dictionary must be provided to unpack the information.
See notes and example in the Unpack function.
Key
Optional string. Must be included if the CipherValue was encrypted using a key, in which case this value must match the key that was used in the Encode function.
HashKey
Optional string. Must be included if the CipherValue was protected from tampering with a Hash value, in which case this value must match the Hash that was used in the Encode function.
pError

Optional. If present, will return a numeric value from the module providing extra information if the decode operation fails. Possible values and meanings for pError follow:

0 | No error
1 | Invalid Opcode
2 | Hashed CipherText, missing HashKey parameter
3 | Encrypted CipherText, missing Key parameter
4 | Error in Salt Length
5 | Error in Decompressed Length
6 | Error in Base64 Encoding
7 | Error in Salt Length
8 | Hash does not match payload
9 | Error when Decrypting payload
10 | Error when Decompressing payload
Comments:

Decode will check for errors at every step in the operation and will skip subsequent steps should an error occur.

Examples:

  If Watch(1);
  [
    Secret = \System.Encode("Hello");
    NotSecret = \System.Decode(Secret);
  ]


DecodeParms

These notes are written for the benefit of customers who want more control over a MenuItem tag for a parameterized page.

Description: | Takes a string of page parameters for a MenuItem tag and returns the values assigned for those parameters.
Returns: | Array
Usage: | Script Only.
Function Groups: | Graphics
Related to: | ShowPage
Format: | \MenuManager.DecodeParms(Data, Reserved)
Parameters: |
Data

Required text. A string of parameters to decode.

You can obtain this automatically via TagObj.Parameters, where TagObj is the MenuItem tag you are examining.

Reserved

Boolean. Set to TRUE to return an array of parameter values.

Comments:

If you know which MenuItem tag you want to get the parameters from, use the following to get an array of its parameter values:

Parameters = \MenuManager.DecodeParms(TagObj.Parameters, TRUE);

You must always pass TRUE into the second parameter.

The name of the page to go with those parameters can be found in: TagObj.CodeReference


Decommission

(Alarm Manager module)

Description: | Decommission an alarm by name.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Commission
Format: | \AlarmManager\Decommission(AlarmName)
Parameters: |
AlarmName
Required text.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Comments:

An alarm tag that is deleted without being decommissioned is referred to as an orphaned alarm. VTScada will removed orphaned alarms automatically, but it is better practice to specifically decommission the alarm

Example:

The following would typically be found in a tag's Refresh state.

    IfElse(Valid(Name), Execute(
                      { ... Alarm commissioning code ... }
                    );
       { Else }
       IfThen(Valid(Parm[#Name]),
               \AlarmManager\Decommission(Root\UniqueID);
             );
    );


Decrypt

(Engine-Level Function)

Description: | The Decrypt function decrypts data previously encrypted using the Encrypt function. It is the VTScada analog of the CryptoAPI CryptDecrypt call. Decrypt fully supports asymmetric and symmetric keys via CNG (Cryptography New Generation)
Returns: | Text
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | DeriveKey | Encrypt | ExportKey | GenerateKey | GetCryptoProvider | GetKeyParam | ImportKey | SetKeyParam
Format: | Decrypt(Key, CipherText, Final [, Reserved, Flags, Error])
Parameters: |
Key
Required. The handle to the key to use to decrypt the data.
CipherText
Required. A text string that contains the cipher text to be decrypted.
Final
Required. A parameter that specifies whether this is the last section in a series being decrypted. Final is set TRUE for the last or only block and FALSE if there are more blocks to be decrypted
Reserved n/a
An optional parameter which should be set to 0. If omitted or invalid, then the value 0 is used.
Flags

Optional. An optional parameter specifying the flags to be passed to CryptDecrypt. If omitted or invalid then the value 0 is used.

When using a CNG key, the Flags parameter can take the same values as for Encrypt.

Error
Required. An optional variable in which the error code for the function is returned. It can have the following meanings:
Value | Meaning
0 | Key successfully imported.
1 | Key, CipherText or Final parameters invalid.
x | Any other value is an error from CryptDecrypt.
Comments: The plain text is returned as a text string. If an error occurs, the return value is invalid.

Example:

[
  PlainText2;
]
Init [
  If 1 Main;
  [
    PlainText2 = Decrypt(Key4, CipherText1, 1, 0, 0);
  ]
]


DefaultNamingContext

(Engine-Level Function)

Description: Returns the string value of the LDAP default naming context for the host machine domain.
Returns: Text
Usage: Steady State only.
Function Groups: Security
Related to:
Format: DefaultNamingContext()
Parameters: None
Comments:

If the host machine is unable to contact the domain controller invalid is returned, otherwise a string of the form "DC=example,DC=com" is returned

This function is useful only for Active Directory operations.

This function may take some time to complete and will block the caller until it does. Other threads in the VTScada system will continue to run while this function is executing.

Example:

...
  If 1 Main;
  [
    MyContext = DefaultNamingContext();
    ...

In this example, MyContext will contain text similar to "DC=example,DC=com"


DefaultPrinter

(Engine-Level Function)

Description: | Returns the Windows™ default printer.
Returns: | Handle
Usage: | Script Only.
Function Groups: | Printer
Related to: | Redirect
Format: | DefaultPrinter()
Parameters: | None
Comments: | This function is used primarily in conjunction with the Redirect statement, which permanently redirects the resources of the system. The only way to return to the original default printer without knowing its source in advance is by using this function as illustrated in the "Example" section.

Example:

  If MatchKeys(2, "p") { When letter "p" is pressed };
  [
    Str1 = DefaultPrinter() { Store the default printer };
    Redirect("DEF:", newPrinter) { Select different printer };
    PrtScrn() { Output screen to printer };
    Redirect("DEF:", Str1) { Restore original printer };
  ]

In this script, the default printer is saved before redirecting printing to another printer. This allows the original printer to be restored as the default when the custom printing is concluded.


Deflate

(Engine-Level Function)

Description: | Compresses or decompresses a buffer of data using the DEFLATE algorithm, and returns the compressed / decompressed data.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: |
Format: | Deflate(InputBuffer, Decompress [, DeflateHandle, MaxDecompressedLength, FlushMode, CompressionLevel, Format])
Parameters: |
InputBuffer
Required. Any expression that will yield a buffer of data to be compressed or decompressed. This can be a string, a buffer, or a stream.
Decompress
Required. A Boolean value. If set to true (non-zero), the data in the InputBuffer is decompressed. If set to false (zero), the data in InputBuffer is compressed.
DeflateHandle
Optional. A variable that holds an existing deflate handle or is to receive a new deflate handle (see the "Comments" section for further details).
MaxDecompressedLength
Optional. Specifies the maximum length of the decompressed output (see the "Comments" section for further details).
FlushMode
Optional. Indicates the type of flushing that the encoder should use when processing the data. Values are
FlushMode | ZLib Value
0 | Z_NO_FLUSH
2 | Z_SYNC_FLUSH
3 | Z_FULL_FLUSH
4 | Z_FINISH

Effective use of this parameter requires an understanding of the ZLib library (www.gzip.org/zlib). The default value is Z_SYNC_FLUSH which is appropriate for continuous, stream mode type operations. For a single encoding, as in a file or a web page, then Z_FINISH is likely to be more appropriate. It is not normally necessary to specify a flush value for decompress but, if one is specified, it will be used.

CompressionLevel
Optional. Indicates the level of aggressiveness of the encoder. Values range between 0 and 9 with typical values being
CompressionLevel | ZLib Value
0 | Z_NO_COMPRESSION
1 | Z_BEST_SPEED
9 | Z_BEST_COMPRESSION
-1 | Z_DEFAULT_COMPRESSION

The default value used by VTScada is Z_BEST_COMPRESSION which should be fine for most applications. Z_DEFAULT_COMPRESSION requests a default compromise between speed and compression ( equivalent to level 6). Again, it is not necessary to specify this on decompression as the decoder can determine the encoding scheme used.

Format
Optional. Indicates the type of compression to use. ZLib is more intended for streams, while GZip for files. Both are simply wrappers around the actual deflated data. Raw Deflate can be used to obtain or process just the deflated data without the ZLib or GZip overhead. Values are
Format | Compression Type
0 | ZLib (default)
1 | GZip
2 | Raw Deflate
Comments: Compression/decompression is performed using an implementation of the DEFLATE algorithm (RFC 1951).
The DEFLATE algorithm is a dictionary-based compression technique, suitable for many types of data. A dictionary-based algorithm needs to include dictionary tokens in the output buffer, so compression of small buffers can give poor results.

The DeflateHandle parameter is an opaque quantity that identifies an existing dictionary, or, if the variable it identifies does not hold an existing deflate handle, is set to a new deflate handle on return from the statement. Supplying the same deflate handle for successive calls to Deflate results in the existing dictionary being used and augmented on successive calls. This usually improves compression significantly.

If you make a series of calls to Deflate, using the same deflate handle to decompress, then you must make a series of calls in the same sequence, with the initial call obtaining a new deflate handle, and subsequent calls using the newly-acquired deflate handle (see the "Example" section for further details).
MaxDecompressedLength is useful when you already know the size of the decompressed data (usually because you recorded it before compression was performed). While this parameter is not necessary, its use reduces the memory required to decompress the data.

The default size of MaxDecompressedLength is 65536 bytes. Expanding data larger than this size will cause the output to be clipped unless a larger value is provided in this parameter.

Example:

  If 1 Done;
  [
    CompressedData = Deflate("Mary had a little lamb", 0{compress});
    OriginalData = Deflate(CompressedData, 1{decompress});
  ]

In the above example, OriginalData will hold "Mary had a little lamb", after the second call to Deflate.

  If 1 Done;
  [
    CompressHandle = DecompressHandle = Invalid;
    CompressedData = Deflate("Mary had a little lamb", 0{compress}, CompressHandle);
    OriginalData = Deflate(CompressedData, 1{decompress}, DecompressHandle);
    CompressedData = Deflate("Mary had a little lamb", 0{compress}, CompressHandle);
    OriginalData = Deflate(CompressedData, 1{decompress}, DecompressHandle);
    CompressedData = Deflate("Mary had a little lamb", 0{compress}, CompressHandle);
    OriginalData = Deflate(CompressedData, 1{decompress}, DecompressHandle);
]

In this example, OriginalData will still hold "Mary had a little lamb" after each call to Deflate, however successive use of the same dictionary will result in later compressions of the string being more efficient (i.e. smaller). This is because the second and third compressions do not need to send dictionary tokens in the output stream, as the tokens are "remembered" in DecompressHandle. This technique allows highly efficient "stream-oriented" continuous compression, so long as the compressed data is fed into Deflate in exactly the same order as it was compressed. Note that separate handles need to be used for both compression and decompression, and that these handles will both be initialized on the first call to Deflate in which they are used.


DeleteAccount

Security Manager Module

Description | Removes an account.
Returns | Object value
Usage | Script Only.
Related to: | AddAccount | ModifyAccount
Format | \SecurityManager\DeleteAccount (NewAccountData [, PtrReturnCode, HaveLock]);
Parameters |
NewAccountData
Required. An AccountData structure, a single dimension array of AccountData structures or a dictionary of AccountData structures identifying the account(s) to delete.
PtrReturnCode
Optional. A pointer to a value that will contain one of the defined result codes at the conclusion of the operation.
HaveLock
Optional. A Boolean value that indicates whether the working copy lock is held by the calling code. Default FALSE.
Comments

To use this API, the calling code must be running in a security session that has Manager privilege.
Deleting an account is an asynchronous operation. If the asynchronous operation was not attempted, due to detection of an error, the return value will be Invalid. If the asynchronous operation is attempted, the return value will be an object value. The object value will become Invalid when the asynchronous operation completes. At that time (or when the method returns Invalid), the value addressed by PtrReturnCode can be examined to determine the status of the operation. The contents of the value addressed by PtrReturnCode is undefined until the method returns Invalid.

A single account can be deleted by supplying a single AccountData structure in NewAccountData. Multiple accounts can be deleted in one operation by providing a single dimension array or dictionary of AccountData structures in NewAccountData.

The result code returned in the value addressed by PtrReturnCode will be a scalar value if a single structure was supplied in NewAccountData. If an array of structures or a dictionary of structures was supplied, a single dimension array of the same size as NewAccountData will be returned in the value addressed by PtrReturnCode, each element containing the result code for the corresponding NewAccountData element.

Deleting an account requires a working copy write lock. If such a lock is held by the calling code, the HaveLock parameter must be set to TRUE. Otherwise omit this parameter or set it to FALSE. If the calling code holds a read lock on the working copy, this must be released before DeleteAccount can complete its operation.

The AccountData structure(s) provided must have the AccountID member set to an existing account ID. All other members are ignored.


DeleteArrayItem

(Engine-Level Function)

Description: | Deletes an element from a single-dimension, dynamically-allocated array and returns the modified array.
Returns: | Array
Usage: | Script Only.
Function Groups: | Array
Related to: | InsertArrayItem | New
Format: | DeleteArrayItem(Array, Index)
Parameters: |
Array
Required. Any array variable that has been created via a New function call. This should be a single dimension array or unexpected results may occur.
Index
Required. Any numeric expression giving the element in the array to delete. If out of range, then the original array will be returned.
Comments: This function supersedes the System Library's DeleteListItem.
This function is intended for use on dynamically allocated arrays; that is, arrays that have been created via the New function. If used with an array that has been statically declared, unless otherwise specified in the Array parameter, the first element of the array will be used. If this element contains a dynamically allocated array, the deletion of the specified element will be performed on this array.

Example:

  If 1 Next;
  [
    Data = DeleteArrayItem(Data, ArraySize(Data, 0) - 1);
  ]

This statement deletes the last element in the array called Data.


DeleteContributor

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Removes a contributor from a container.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Containers and Contributor
Related to: | AddContributor |GetContributors |PContributor
Format: | \DeleteContributor(HandleName, ArrayName, CountName, ContainerObj, ContributorObj, CountIncrement);
Parameters: |
HandleName
Required. The name of the handle variable in the container module.
ArrayName
Required. The name of the variable in the ContainerObj that holds an array of values from which to delete the contributor. This parameter may be invalid if there is no such array in the container.
CountName
Required. The name of the variable in the ContainerObj that holds a count of the current number of this type of contributor. This parameter may be invalid if no such variable exists in the ContainerObj. Not all contributors need to be counted. The CountIncrement determines the initial change in the count and the contributor must maintain the count.
ContainerObj
Required. The object value of the container tag module.
ContributorObj
Required. The object value of the contributor to delete.
CountIncrement
Required. This value will be subtracted from the variable in the container that has the name of CountName. This value is usually a "1" or a "0", indicating whether the contributor is actively contributing its value now. The contributor will increment or decrement the value of the CountName variable as the corresponding state of the contributor changes.
Comments:

Used only when writing custom tags with code (as opposed to creating them from Context tags). See: Containers, Contributors and Site Tags

This function can be called from the contributor.

Example:

Refer to the tag template .SRC file, provided in the Examples folder of your VTScada installation.


DeleteModule

(Engine-Level Function)

Description: | Deletes a module from the system.
Warning: | This function should be used only by advanced programmers.
Returns: | Numeric (see table in comments)
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | ClearModule | DeleteOptional | DeleteState | DeleteStatement | DeleteVariable
Format: | DeleteModule(Module[, IgnoreSource])
Parameters: |
Module
Required. Any expression that gives the module value of the module to delete.
IgnoreSource
If true, the function will not modify any source file. Also, will not check that .SRC and .RUN files are in sync and therefore will not return a value of 3.
Defaults to FALSE if invalid or not specified.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

This statement deletes a module from the system, as well as removing its code from the document file, if certain conditions hold. There must not be any running instances of this module. All of the variables in the module must only be referenced within that module. That is, none of the variables can be referenced outside of the module which they are in. Module itself must not be referenced in any other module at all.
This function returns values as follows

Return Value | Meaning
0 | Module successfully deleted.
1 | Module not deleted, there are instances of it running.
2 | Module not deleted, module is externally referenced.
3 | Module not deleted, run files are out of sync.


DeleteOptional

(Engine-Level Function)

Description: | Deletes a statement from an action script.
Warning: | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, States
Related to: | DeleteModule | DeleteState | DeleteStatement | DeleteVariable
Format: | DeleteOptional(Action, Position)
Parameters: |
Action
Required. Any expression that gives the VTScada Value Types of the action.
Position
Required. Any numeric expression giving the statement number in the script to delete, beginning with 1.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

The corresponding text for the deleted statement is removed from the document file.
This statement is disabled in the run time version of VTScada. It will do nothing.


DeletePrivFromUser

(Security Manager Library)

Description: | Removes a privilege from the specified username.
Returns: | Numeric (via the first parameter)
Usage: | Script Only.
Function Groups: | Security
Related to: | ModifyUserPrivilege
Format: | \SecurityManager\DeletePrivFromUser(PtrReturnCode, Username, Privilege[, HaveLock])
Parameters: |
PtrReturnCode
Required. A pointer to a variable that will be used for the return code.
PtrReturnCode | Meaning
1 | Privilege deleted.
2 | Denied. The calling context does not have the Manager general privilege.
3 | The privilege is not valid - no action taken.
4 | The specified user does not exist - no action taken.
6 | The application cannot be edited.
UserName
Required. Any expression for the name of the user account to modify.
Privilege
Required. Any numeric expression for the privilege to be denied. Use a negative value for a general privilege and a positive value for a custom privilege.
HaveLock
Optional Boolean expression. Set to true if we have the WC lock. Defaults to 0 or FALSE.
Comments: May only be called from a user-context that has the Manager privilege. The return value of the function is the object value of the launched worker module. This will be set to Invalid when the operation has completed and may be used to discover when that occurs.
Use of this function requires an understanding of the VTScada security system and the general privileges. Please refer to System Privileges in the chapter Security Manager Service.


DeleteState

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Exists only for backward compatibility. Deletes a state from a module.
Warning: | This function should be used by advanced users only. Irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, States
Related to: | ClearState | DeleteModule | DeleteOptional | DeleteStatement | DeleteVariable
Format: | DeleteState(State)
Parameters: |
State
Required. Any expression that gives the code value of the state.
Comments: The corresponding text for the deleted state is removed from the document file.


DeleteStatement

(Engine-Level Function)

Description: | Deletes a statement from a state.
Warning: | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, States
Related to: | DeleteModule | DeleteOptional | DeleteState | DeleteVariable
Format: | DeleteStatement(Statement)
Parameters: |
Statement
Required. Any expression that gives the code value of the statement.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

The corresponding text for the deleted statement is removed from the document file.
This statement is disabled in the run time version of VTScada. It will do nothing.


DeleteUser

(Security Manager Library)

Description: | Removes a specified user name from the system.
Returns: | Numeric (via the first parameter)
Usage: | Script Only.
Function Groups: | Security
Related to: | ModifyAccount
Format: | \SecurityManager\DeleteUser(PtrReturnCode, Username[, HaveLock])
Parameters: |
PtrReturnCode
Required. A pointer to a variable that will be used for the return code.
PtrReturnCode | Meaning
0 | User does not exist. No action taken.
1 | User deleted.
2 | Denied. The calling context does not have the Manager general privilege.
6 | The application cannot be edited.
UserName:
Required. Any expression for the name of the user account to delete.
HaveLock:
Optional Boolean expression. Set to true if we have the WC lock. Defaults to 0 or FALSE.
Comments: May only be called from a user-context that has the Manager general privilege. The return value of the function is the object value of the launched worker module. This will be set to Invalid when the operation has completed and may be used to discover when that occurs.
Use of this function requires an understanding of the VTScada security system and the general privileges. Please refer to System Privileges in the chapter Security Manager Service.


DeleteVariable

(Engine-Level Function)

Description: | Deletes a variable from a module.
Warning: | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | DeleteModule| DeleteOptional| DeleteState | DeleteStatement
Format: | DeleteVariable(Variable[, IgnoreSource])
Parameters: |
Variable
Required. Any expression that gives the variable value to delete.
IgnoreSource
An optional Boolean expression. If true, the function will ignore out-of-sync source files and not attempt to make any source file changes. The result is convenient deletion of non-temporary variables without having the function modify the corresponding source code. Defaults to FALSE.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

If IgnoreSource is FALSE or not provided then the corresponding text for the deleted variable is removed from the source file. However, this is only true if the variable is not a temporary variable, and only if the files are in sync. DeleteVariable will fail if there are any references to the variable to be deleted.


DelPageFromApp

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Deletes a system page from an application.
Warning: | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Window
Related to: |
Format: | \DelPageFromApp(PageName);
Parameters: |
PageName
Required. The text name of the page to delete.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

In versions of VTS prior to 8.1, this subroutine was a part of the page manager and therefore was called using the format \PageManager\DelPageFromApp(…). With version 8.1, the page manager is no longer a part of VTScada and the function can simply be called using \DelPageFromApp() as shown in the "Format" section above.


DelRead

(VTSDriver Module)

Description: | Is called by a tag to delete an existing read request, as created by an AddRead.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Memory I/O
Related to: | AddRead
Format: | VTSDriver.DelRead(Address, Value, Rate, OriginalAddress)
Parameters: |
Address
Required. The address from which to get the data.
Value
Required. A pointer to the destination for the read data.
Rate
Required. The update rate in seconds.
OriginalAddress
Original Address string from I/O tag.
Comments: DelRead() can only delete a single item. The module searches ReadList (a linked list of ReadBlocks) for the node whose info vars match those of the item to be deleted. It then looks for the matching rate, then the specific request as identified by Value (the address of the tag's RawValue) and removes it from the list.

Example:

For an in-context example, refer to Template.SRC, provided in the Examples folder of your VTScada installation.


DenyTokenRequest

(Control Token Manager)

Description: | Denies a control token request
Returns: | Nothing
Usage: | Script Only.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | ControlTokenManager.DenyTokenRequest(TagID, TokenRequestRecord[, Custom, Timestamp, SessionID, AccountID, MachineID, Device])
Parameters: |
TagID
Required string. The UniqueID of the tag for which the token request is to be denied.
TokenRequestRecord
Required. The record of the token request to deny.
Custom
Optional. A structure of custom fields to log
Timestamp
Optional The UTC timestamp of this event. Defaults to current time
SessionID
Optional. The ID of session denying the request.
AccountID
Optional. The Account ID of user denying the request. Defaults to the currently signed-in user.
MachineID
Optional. The MachineID of the workstation where this action originated. Defaults to the current machine.
Device
Optional. Name of client device
Comments:

Denying a pending token request removes it from the Token Request list. See also: Custom Ownership Mode for Control Tokens


Deriv

(Engine-Level Function)

Description: | Returns the derivative (rate of change) of a value.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Generic Math
Related to: | Intgr | PID
Format: | Deriv(Value, Time)
Parameters: |
Value
Required. Normally, the name of a variable holding a numeric value for which the derivative will be taken.
Time
Required. Any numeric expression giving the time in seconds between derivative function updates.
Comments:

This function takes the change in the Value parameter between two successive evaluations and divides by the elapsed time interval between these evaluations. If the Value changes from invalid to valid, it will take two evaluations before the function's result becomes valid. This function is the inverse of Intgr.
The time parameter is necessary because of VTScada's evaluation method of not doing any calculations unless necessitated by a change in a parameter. This means that if the Value remains unchanged, the Deriv function will be recalculated after the time interval specified by the Time parameter and return 0.
This function is often used in control functions such as PID loops where it makes up the "D" in the "PID".

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

  LevelROC = Deriv(Level, 0.1);

Assuming that Level is updated to show a changing value, this will set LevelROC to the rate of change of that level.


DeriveKey

(Engine-Level Function)

Description: | Generates a cryptographic session key from a seed value.
Returns: | Handle
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | Decrypt | Encrypt | ExportKey | GenerateKey | GetKeyParam | ImportKey | SetKeyParam
Format: | DeriveKey(CSPHandle, AlgID, Seed [, Flags, Error])
Parameters: |
CSPHandle
Required. The handle of a CSP Closed critical security parameter to use to generate the key.
AlgID
Required. Identifies the algorithm for which the key is to be generated. Values for this parameter vary depending on the CSP used, and are defined in WinCrypt.h
Seed
Required. A text string to use as a seed.
Flags
Optional. Specifies the flags to be passed to CryptGenKey. If omitted or invalid, then the value "0" is used.
Error
Optional. A variable in which the error code for the function is returned. The error codes are as follows
Error | Meaning
0 | Key successfully generated
1 | CSPHandle or AlgID parameters invalid
X | Any other value is an error from CryptGenKey.
Comments:

DeriveKey guarantees that when the same CSP and algorithms are used, the keys generated from the same seed are identical. The base data can be a password or any other user data. A handle to the key or key pair is returned. This handle can then be used as needed with any Crypto API function requiring a key handle. It is the VTScada analog of the Crypto API CryptDeriveKey call.

The return value for this function is a handle to the Key. If an error occurs, then the return value is Invalid. A key has a value type of 37. If cast to text, then the hexadecimal value of the algorithm ID will be returned.

Does not support CNG (Cryptography New Generation).

Example:

[
  Key1;
  Constant CALG_RC4 = 0x6801;
  Constant KEY_SIZE = 40;
  Constant Password = "A secret password";
]
Init [
  If 1 Main;
  [
    { Make a key }
    Key1 = DeriveKey(CSP, CALG_RC4, Password, KEY_SIZE << 16);
  ]
]


DetectFlatline

(Function Library)

Description: | Returns TRUE if the monitored numeric value stays the same for a specified length of time.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Function Library
Related to: |
Format: | \FunctionLib.MonitorFlatline(InputValue, Delay[, Deadband, Enable])
Parameters: |
InputValue
Required. Value to monitor.
Delay
Required. Check interval (seconds).
Deadband
Optional. Deadband for change detection (default = 0)
Enable
Optional. TRUE to Enable monitoring. FALSE to Disable monitoring. (Default = TRUE)
Comments:

You can use DetectFlatline only with numeric value tags.


DialogInitPos

(System Library)

Description: | Attempts to position a dialog so that it is not started beyond the left, right, top, or bottom of the visible screen.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics
Related to: |
Format: | System.DialogInitPos(XPosPtr, YPosPtr [, XOffset, YOffset, Width, Height, SuppressCentering, WinOptions, RefWindow])
Parameters: |
XPosPtr
Required. A pointer to the dialog's X-position. The X-position will be modified by this function if the dialog is beyond the left or right edge of the screen.
YPosPtr
Required. A pointer to the dialog's Y-position variable. The Y-position will be modified by this function if the dialog is beyond the top or bottom edge of the screen.
XOffset
Optional. Any numeric expression giving the default X-position to use if the value of the XPosPtr is Invalid. It is also the X-position that will be used if the dialog is beyond the right edge of the screen and Width is Invalid. Default is 0.
YOffset
Optional. Any numeric expression giving the default Y-position to use if the value of the YPosPtr is Invalid. It is also the Y-position that will be used if the dialog is beyond the bottom edge of the screen and Height is Invalid. Default is 0.
Width
Optional. Any numeric expression giving the width of the dialog.
Height
Optional. Any numeric expression giving the height of the dialog.
SuppressCentering
Optional Boolean. If TRUE, this function won't center off-screen windows, instead shifting windows on-screen. Note that when this is true and *pXPosition and *pYPosition are valid, then XOffset and YOffset are not used because VTScada will always shift the positions given in the pointers on-screen rather than falling back on XOffset/YOffset.
WinOptions

Optional structure, defined as follows:

Struct [
    BorderWidth    { Width of left or right border (each), if any  };
    BorderHeight   { Height of top or bottom border (each) , if any};
    TitleBarHeight { Height of titlebar (not including top
                     BorderHeight), if any                         };
  ];

Defaults to a window with a titlebar and thick borders

RefWindow
Optional Window object. If provided, and if the values of pXPosition and pYPosition are not preset or would cause the dialog to appear outside of the screen, the module will try to center the dialog to this window instead of the screen.
Comments: This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section. If your application predates version 11.2, use the backslash notation rather than dot: \System\

XPosPtr and YPosPtr are absolute coordinate positions of the Windows desktop.

XOffset and YOffset are suggested to be used for calculating the new coordinates for the top left corner, and are relative to the current monitor. If they are left invalid, they will be calculated to attempt to center the window on the current monitor.

Width and Height are used to help center the window on the current monitor. If they are invalid, they are assumed to be one third the size of the current monitor.

AllowVirtualDisplay - This setting can be added to SETUP.INI and set to 1 in order to force the DialogInitPos constraint rectangle to be the entire virtual display, i.e. the Windows desktop.

Calling this function before starting a Window() call will reposition a dialog's starting position so it will not be drawn entirely off-screen. This is only necessary if the dialog's X- or Y-coordinates are retained. The width and height of the dialog are optional. If provided, the dialog will be prevented from being drawn partially beyond the bottom/right edge of the screen. Otherwise only the top/left corner of the dialog will be guaranteed to be drawn on-screen. There is no return value.

Example:

[
  Width                       { Dialog width                                };
  Height                      { Dialog height                               };
  Retained XPos               { Window X Location                           };
  Retained YPos               { Window Y Location                           };
...
]
Init [ If 1 Main;
  [
  ...
    Width =  { calculation or constant to set width  };
    Height = { calculation or constant to set height };

       { Determine the X and Y position of the dialog }
    \System\DialogInitPos(&XPos, &YPos, 100, 100, Width, Height);
  ]
]


Dictionary

(Engine-Level Function)

Description: | Creates a database-like storage structure that provides efficient addition, retrieval and removal of information linked to key values. Keys can be any data type although integers and strings are recommended. Values can be any data type including another dictionary.
Returns: | Dictionary
Usage: | Script Only.
Function Groups: | Dictionary, Variable
Related to: | MetaData | MakeDictionary | ArrayToDictionary | DictionaryCopy | DictionaryRemove | GetNextKey | GetKeyCount | HasMetaData | IsDictionary | ListKeys | RootValue
Format: | Dictionary([CaseInsensitive, RootValue])
Parameters: |
CaseInsensitive
Optional. A Boolean indicating whether the keys in the dictionary are to be case sensitive.
TRUE == Not Case Sensitive (default)
FALSE == Case Sensitive
RootValue

Optional text value, almost never used. Numeric values will be cast to text.
If not provided, the dictionary will have no root value. (default: Invalid)

In practice, root values are only ever assigned to dictionaries to create nested dictionaries. If the script cannot find a specific key in a dictionary it will then search the nested dictionary.

A[0] has a unique relationship with Root Values.
If A[0] is first used as a typical key with an assigned value it will behave like a key with a value forever. The value can be changed by assigning a new value to A[0] and is unaffected by anything else.
If A[0] is first assigned a Root Value it's behavior will change. A[0] becomes a variable with Meta Data. The value can be changed by assigning a new value to A[0] OR A[""] OR by using RootValue().

The order of operations matters.
If you set
A[0] = 7
A[""]= 6
and then
A[0]= 5
then A[0] AND A[""] will both equal 5.

However if you first set
A[""] = 6
and then A[0] = 5
then A[""] = 6 and A[0] = 5

Example:

    X = Dictionary();
    X["A"] = 42;
    X["B"] = 86;
    X["C"] = 99;

Related information:

Dictionaries


DictionaryCopy

(Engine-Level Function)

Description:

Create a new dictionary with contents identical to an existing dictionary. It is expected that this function will be used rarely, since in most cases it will be more efficient to hand off a reference to a dictionary rather than build a duplicate of it.

In the case of a complex dictionary that contains other dictionaries within it, the optional Boolean parameter, deep, controls whether the copy should also contain the sub dictionaries, as does the original, or if it should contain copies of those dictionaries.

Returns: Dictionary
Usage: Script Only.
Function Groups: Dictionary, Variable
Related to: Dictionary | MetaData | DictionaryRemove | GetNextKey | GetKeyCount | HasMetaData | IsDictionary | ListKeys | RootValue
Format: NewDictionary = DictionaryCopy(dictionary[, deep, acyclic, lock] );
Parameters:
Dictionary
Required. The name of the dictionary.
Deep
Optional. A Boolean that causes all linked dictionaries, if any, to be copied as well. Defaults to FALSE
Acyclic
Optional. A Boolean indicating that cyclic links within the dictionary structure should not be included in the copy. Defaults to FALSE
Lock
Optional. A Boolean indicating that the contents of the dictionary copy are to be constant. Defaults to FALSE


DictionaryRemove

(Engine-Level Function)

Description: | Removes a key / value pair from a dictionary, providing a means to regain memory space and remove data that is no longer needed.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Dictionary
Related to: | Dictionary | MetaData | DictionaryCopy | GetNextKey | GetKeyCount | HasMetaData | IsDictionary | ListKeys | RootValue
Format: | DictionaryRemove ( dictionary, key );
Parameters: |
Dictionary
Required. The name of the dictionary.
Key
Required. The name of the key to be removed.

Example:

Given a dictionary created as follows:

    X = Dictionary();
    X["A"] = 42;
    X["B"] = 86;
    X["C"] = 99;

The following will remove the key "C" and its value:

    DictionaryRemove(X, "C");


Diff

(Engine-Level Function)

Description: | Compares two buffers and generates a third buffer containing formatted instructions describing how the first buffer can be modified so that it will match the second. This will perform a delimited difference unless the ChunkSize parameter is set to 1 or greater.
Returns: | Invalid (result returned in second parameter)
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: |
Threaded: | Yes
Format: | Diff(ResultBuffer, CompletionCounter, Buffer1, Buffer2, [Delimiter, Chunk Size, Clip Length, Edge Length, MaxVariance, PointCap])
Parameters: |
ResultBuffer
Required. Any expression that resolves to the variable to be set to the output buffer. This buffer is created asynchronously and should be checked for valid data before use.

The content of this buffer will be an instruction set for transforming the contents of Buffer1 into a duplicate of the contents of Buffer2. A detailed description of this instruction set is provided in the Comments section.
Completion Counter
Required. Any expression that resolves to a variable containing a numeric value or Invalid.

If a numeric variable, the value will be incremented at the instant that Diff is called. It will then be decremented after the Result Buffer has been populated. The same variable can be used to monitor any number of simultaneous, asynchronous Diff operations.

If this parameter is set to Invalid then the Diff operation will be performed synchronously. The function won't return until the Result Buffer is populated.
Buffer1
Required. Any expression that returns the first buffer. This is the buffer that is intended to be modified by the instructions returned.
Buffer2
Required. Any expression for the second buffer. This is the buffer that the first buffer would resemble were the returned instructions applied.
Delimiter
Optional. The bytes used to delimit lines in text buffers (or records in any sort of delimited buffer). Multiple delimiters can be specified by passing an array of text strings.

If not otherwise specified, the default is an array containing typical text file line endings (newline, carriage return or a combination of the two characters in either order).

Can accept either a single string or an array of strings
ChunkSize
Optional. The number of bytes to compare as a unit in a binary buffer. Must be set to 1 or greater to enable a binary diff (a delimited diff is performed by default).

Unless the contents of the buffers are guaranteed to align to a given number of bytes it is recommended that this be set to 1 to enable binary diffs. Defaults to 0.
ClipLength
Optional. This numeric value is an optimization. It indicates how long a string of matches (i.e. both buffers having identical contents) will become before the function decides that it has found an optimal instruction set and will discard competing sets.
If Diff returns sub-optimal instructions you should increase this value. Lower values will reduce the execution time of the function at the cost of the quality of the output. Higher values increase output quality but decrease speed.
Sub-optimal instruction sets will result if strings of matches having the given length can occur randomly within the two buffers. Defaults to 20.
EdgeLength
Optional. Another numeric optimization, best set to twice the ClipLength. Causes the elimination of instruction sets that are estimated to require at least EdgeLength more instructions than the best set at any point during the search.
Sub-optimal instruction sets will result if the estimate is inaccurate by an amount greater than this value.
Lower EdgeLength values will reduce the execution time of the function at the cost of the quality of the output. Higher values will increase output quality but decrease speed. Defaults to 40.
MaxVariance
Optional. Sets a maximum variance, as measured by the number of items changes in the same way. If the DIFF strays from an exact match by MaxVariance by a given number of data adds or deletes, execution will stop.

A mixture of adds and deletes will cancel each other out. When set to a value smaller than the default, files with lots of small modified areas will pass while files with a single modification, larger than this variance, will fail.

Defaults to 1,000,000.
PointCap
Optional. Sets a cap on the number of points that will be searched within the buffers. In effect, this value serves to cause a timeout when comparing extremely large buffers that are almost completely different. Defaults to 1,000,000,000.
Comments:

This function will return Invalid on failure. Otherwise, the return value is a buffer of zero or more binary records. Each record will consist of at least two 32-bit words, containing instructions in the following form:

The highest bit of the first word indicates whether this is a delete instruction or an add instruction. 0 means "delete" while 1 means "add". The remaining 31 bits of the first word (taken as a 31-bit unsigned integer) contain the number of bits to be affected by this operation.

The second word, taken as a 32-bit unsigned integer, indicates the offset of the operation. That is the location of the bytes affected.

If the operation is to add bytes, there will be a binary string following the second word. These are the bytes to be added at the specified location.
Because the diff function uses a searching algorithm, and in particular an incomplete search (that is it tries to find a solution without exploring all of the possibilities), it will at any time only have a partial collection of all the possible solutions to the problem. Each solution is defined as a set of instructions that modify the source buffer, and each of these sets requires a different number of instructions to convert a different region of that buffer. The "best set" is the one that converts the largest portion of the buffer while requiring the fewest changes to it, selected from the solutions that have been discovered so far.

The optimization works by eliminating solutions which appear to be so much worse than the current best set that they are unlikely to recover, as judged by how many more changes they require to convert a similar region. The problem is that a solution which works poorly in one region may perform much better in the others, so the optimization may cause the "real" best set (the one that's optimal for the entire buffer) to be overlooked.

The return value will be an empty buffer if Buffer1 and Buffer2 are identical.

Example:

The following generates a set of undo instructions required to change a "new" file back to an "old" file.

... If 1 NextState;
  [
  ...
    NewFileStream = FileStream(NewFileVersion);
    OldFileStream = FileStream(OldFileVersion);
    Diff(DiffForUndo, Invalid, NewFileStream, OldFileStream);
 ...


Dir

(Engine-Level Function)

You are advised not to use this function on network paths. Response time can be very slow.

Description: | Performs a search in the given directory and returns an array of matching file names.
Returns: | Array
Usage: | Script only.
Function Groups: | File I/O
Related to: | DriveInfo | FileFind | FileDialogBox | GetFileAttribs
Format: | Dir(Path, Attributes, Option)
Parameters: |
Path
Required. Any text expression that indicates the full path name for the directory to list. The search is non-recursive (i.e. it considers only the specified directory, not any of its sub-directories). Path may include a wildcard, such as "*.DAT". A known path alias for File-Related Functions may be provided in the form, :{KnownPathAlias}.
Attributes
Required. Any numeric expression that gives the attributes to match on each file listed. Files that don't match these attributes won't be listed. The Attribute parameter may be set as one of the following:
Attribute | Bit No. | Meaning
0 | - | Files without attributes
8 | 3 | All files (regardless of attributes)

... or, it may be constructed by adding together the numbers from the following table :

Attribute | Bit No. | Meaning
1 | 0 | Read only
2 | 1 | Hidden
4 | 2 | System
16 | 4 | Sub-directory
32 | 5 | Archive
Option
Required. Any numeric expression giving the type of text information to generate. All information is placed in a single text string (which will be stored in an element of the array that is created). The information is written from left to right, with lowest option numbers first.
Option | Bit No. | Description
1 | 0 | Short file name
2 | 1 | Full path and file name
4 | 2 | File size
8 | 3 | File last modified date (in text)
16 | 4 | File last modified time (in text)
32 | 5 | File attributes (ADHRS)
64 | 6 | File last modified date/time combination (in seconds since January 1, 1970)
128 | 7 | File creation date (in text)
256 | 8 | File creation time (in text)
512 | 9 | File creation date/time combination (in seconds since January 1, 1970)

The attributes returned as a result of bit 5 being set are printed as the capital letters A (archive) D (subdirectory), H (hidden), R (read-only), and S (system).

Comments:

This function returns an array of text values, where each element contains the information specified by Option for each file that matches both Path and Attributes.

If no files are found, the return value will be set to invalid. Notice that the only difference between this function and the FileFind function is that FileFind searches down through the whole directory tree, while this function looks in the immediate directory only.

If you are looking for a "browse for folder" dialog box, please refer to the FileDialogBox function.

(See: Bitwise Parameters & Operations)

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  If ! ValidValid(datFiles);
  [
    DatFiles = Dir("G:\Research\*.DAT" { Path },
                   0 { All normal files },
                   1 { Retrieve file name });
  ]

To display the first entry, try:

  ZText(10, 10, DatFiles[0], 15, 0);

The result might be something like:

"TEST.DAT"


DirectApply

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Applies a set of changes directly to the repository, without disturbing existing (non-conflicting) changes already on either branch.
Warning: | This function should be used only by advanced programmers.
Returns: | Module
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | CommitEditedFiles
Format: | LayerModule\DirectApply(AlreadyHasLock, LocalChangeSet, RSema, pComment)
Parameters: |
AlreadyHasLock
Required Boolean. Set TRUE when we already have the working copy lock.
RSema
Required. Repository semaphore, if already held by the caller.
CallBack
Required. Module name of the caller performing the changes.
FileSet
The set of files to be changed, identified using a path relative to the working-copy.
User
The user ID that is to be applied to the change.
Comment
Any text value that is the comment to be stored in the version log for this change.
pFail
A pointer to a Boolean. This will be set TRUE on failure.
Comments:

This function uses a callback system to acquire a set of changes against the repository tip versions of a file or group of files (both the local and deployed versions) and then applies those changes directly to the local and deployed repository tips without altering the working copy.

The changes are then applied to the working copy as a result of the repository update. The primary purpose of this operation is to allow changes to a file to be deployed without also deploying any existing local changes to the same file. The local version must also be updated such that the file is updated correctly when the current local and deployed tips differ - otherwise conflicts could result when the repository attempts to rationalize the two.

DirectApply is used to distribute operation changes, notes, security information, and other data for which it is not appropriate that one machine may be configured differently than its peers. It should not be used for normal configuration changes. To make all configuration changes deploy immediately set the "Automatically Deploy" flag in the CM Information panel.

The callback definition follows:

Callback (
   DeployChangeSet   { Set of deploy buffers, make changes to these  };
   LocalChangeSet    { Set of local buffers, make changes to these   };
   RSema             { Repo semaphore                                };
   pComment          { Comment pointer allowing late editing         };
)

This module launches a worker module into the Layer so that the operation is not interrupted by this module's caller being slain. In the case that the current machine is not supporting an open local branch the LocalChangeSet callback parameter will be invalid.

Examples:

none provided


Disable

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Use AlarmManager\EvaluateAlarm in all new code. Told the Alarm Manager to disable an alarm. Disable will also clear any active or unacknowledged state that might exist.
Returns: | 0
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | CurrentTime
Format: | \AlarmManager\Disable(AlarmObject[, EventTime]);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine that will be disabled.
EventTime
Optional. The time stamp to use when adding this event to the alarm lists. If invalid or not defined, the default is CurrentTime().
Comments: The Disable subroutine always returns "0".


DisconnectFromMachine

(RPC Manager Library)

Description: | This subroutine disconnects from a workstation by decrementing the usage count on the specified workstation and forcing the RPC Manager to attempt to establish a connection with the specified workstation if it is not already connected. Subroutine call only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Network
Related to: | ConnectToMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | Send| SetRemoteValue
Format: | \RPCManager\DisconnectFromMachine(Workstation)
Parameters: |
Workstation
Required. Any of the name or IPs that can be used to connect to the workstation.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
When the usage count of the workstation reaches "0", the RPC Manager will not attempt to re-establish a connection to the workstation after the current connection is lost.

It is critical that each DisconnectFromMachine call should be paired with a ConnectToMachine call. If the number of DisconnectFromMachine calls exceeds the number of ConnectToMachine calls, the RPC Manager will not behave as expected and connection with the remote workstation may be impeded. A negative value for the Srv value in the socket's entry in the RPC Diagnostics Window may be an indication of a DisconnectFromMachine/ConnectToMachine mismatch.

Example:

  If Valid(SNode) Done;
  [
    \RPCManager\DisconnectFromMachine(sNode);
  ]

This closes an existing socket by using its socket value.

Related information:

RPC Manager Service


DLL

(Engine-Level Function)

Description: | Returns a value of a type specified by its parameter from a call to Microsoft Windows™ dynamic link library using the C calling convention.
Warning: | For use by advanced users only. Great care must be taken that all parameter values are correct when using this statement, since incorrect usage may cause a system crash.
Returns: | varies (see table under ReturnType)
Usage: | Script Only.
Function Groups: | DLL
Related to: | LoadDLL
Format: | DLL(DLLName, FuncName, ReturnType, BuffLen, Type1, Val1, Type2, Val2, …)
Parameters: |
DLLName
Required. Any text expression that gives the full path, file name, and extension of the DLL to load, or the handle returned from a LoadDLL statement.
FuncName
Required. Any text expression that gives the name of the function to call in the DLL.
ReturnType
Required. The return type of the DLL function, as shown in the following table
ReturnType | Attribute
0 | Void (return value only)
1 | 16-bit Integer
2 | 32-bit Integer
3 | 64-bit Double
4 | Pointer to a buffer (*)
5 | HWnd value of VTScada Object
6 | Reserved
7 | 64-bit Integer
8 | Pointer-width Integer*

*The pointer-width integer is the size of a pointer in the host environment. Therefore, in 32-bit VTScada, it is a 32-bit integer, and in 64-bit VTScada, it is a 64-bit integer.

BuffLen
Required. Any numeric expression that gives the length of the returned buffer, if ReturnType is 4.
Type1, Val1, Type2, Val2, …
Required. Are any expressions that determine the type of parameter passed to the DLL function, as shown in the table for the ReturnType parameter. The corresponding ValN parameter will be cast as this type before it is passed to the DLL function.
Comments:

This statement allows a wide variety of other routines and code to be used in an application.

(*) If a DLL function takes a parameter of type 4 (buffer), then it should only read/write that buffer while the DLL's function is running - it should not store it for later. The pointer that gets passed into the DLL function points to a buffer that only exists for the lifetime of the DLL function call.

64-bit VTScada can load only 64-bit DLLs. 32-bit VTScada can load only 32-bit DLLs.

VTScada Internet Clients (VICs) can load only 32-bit DLLs regardless of whether the VTScada server is 32-bit or 64-bit.

Example:

You have a DLL that has:

  • A function named decrypt(), which returns a length of the decrypted file.
  • A function named getDecryptedFile()

The DLL calls from VTScada script would look like so:

  DllHandle = LoadDLL("C:\Path\To\mydll.dll");
  If Valid(DllHandle) Done;
  [
    decryptedFileLength = DLL(dllHandle, "decrypt", 2, ...);
    decryptedFile = DLL(dllHandle, "getDecryptedFile",  4, decryptedFileLength, ...);
  ]

An array of C# objects cannot be transferred directly via DLL(). Multiple files (as per the above example) could be passed in several ways. For example:

  • Your DLL's decrypt() function could be written to return the number of files. Then in a loop, another call is made to the DLL to determine the length of the n-th file and finally retrieve that file from the DLL
  • Serialize the array. For example, "<32 bit length of first decrypted file><contents of first file><32 bit length of second decrypted file>...", and then convert that into an array in VTScada via SRead().


DoLoop

(Engine-Level Function)

Description: | Executes a do-while loop in a script.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Logic Control
Related to: | Case | Cond | IfElse | IfThen | WhileLoop
Format: | DoLoop(Function1, Function2, …, Condition)
Parameters: |
Function1, Function2, …
Required. Any expression or statement. This is the body of the loop. All of the Function parameters are executed in order prior to testing the Condition parameter.
Condition
Required. Any logical expression for the loop control. As long as this is true, the loop will repeat.
Comments: The Function parameters are executed at least once, then Condition is checked. If Condition is true, the Function parameters are executed and Condition is executed again. This repeats until Condition is false or Invalid.

While the DoLoop statement has its place in VTScada programming, it should be noted that if working with arrays, speed can be enhanced by a factor of approximately 5 through the use of array processing functions. Refer to Array Functions for further details.

Example:

  ...
  If 1 Main;
  [
    I = 0;
    DoLoop(
      X[I] = Concat("Pump ", I);
      I++;
    { while I is less than 10 }
      I < 10;
    );
  ]

This loop executes 10 times, assigning a text string to the next element of the array "x" on each iteration.


DoOperate

Description: | Used by tags that can be operated from the Tag Browser, this displays an input dialog where users can enter the new value to write. Should be overridden for use with tags other than those that write analog, digital or string values.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | IsTagOperable
Format: | \DoOperate(TagObj)
Parameters: |
TagObj
Required object value. The tag to be examined.
Comments:

For typical I/O tags that are operable, this will display a predefined dialog containing a widget that is appropriate for the tag instance.

If the tag in question contains its own DoOperate() submodule, that will be called instead.

Example

<
{============================= Report.DoOperate ==============================}
{ This is an override for the DoOperate window. The Report Tag doesn't fit    }
{ into the general set of output widgets so this module has its own custom    }
{ method to "Operate" this tag type.                                          }
{=============================================================================}
DoOperate

[
  PROTECTED ConfirmMsg        { Are you sure message for this tag             };
  PROTECTED WhichBtn          { Which button was chosen                       };
]

Main [
   { Get the output message, keeping up to date with current language }
  If Watch(1, GetUserLanguage());
  [
    ConfirmMsg = GetTagOutputConfirmMsg(Root, 1);
  ]

   { Ask the user if they are sure they want to do this }
  WhichBtn = \System\4BtnDialog(\System\Question_Icon { Icon },
                                GetPhrase("OKLabel"), GetPhrase("CancelLabel"), Invalid, Invalid { Buttons },
                                Name, ConfirmMsg, Invalid {Text},
                                1 { Open }, ! \NoModal { Modal },
                                0 { No Bold }, GetPhrase("AreYouSureLabel") { Title },
                                &MsgDlgXPos, &MsgDlgYPos,
                                2 { cancel btn }, 1 { def focus },
                                \DlgHelpFile, Invalid { No help });

   { A choice was made }
  If Valid(WhichBtn);
  [
     { They chose yes }
    IfThen(WhichBtn == 1,
       { Add the entry to the operator log }
      \OperatorLog\AddEvent(Name, 1);
       { Tell the tag to run the report }
      \Set(1);
    );

    Slay(Self);
  ]
]

{ End of Report.DoOperate }
>


DragHandle

(Engine-Level Function)

Description: | Drags a graphic object's selected handle.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DragState (Obsolete)
Format: | DragHandle(Object, X, Y, KeepRatio)
Parameters: |
Object
Required. Any expression that gives the object value that defines the selected graphic list to drag.
X
Required. Any numeric expression that is the new X coordinate of the selected handle(s).
Y
Required. Any numeric expression that is the new Y coordinate of the selected handle(s).
KeepRatio
Required. Any logical expression. If true (non-zero), the aspect ratio of the graphic will be preserved during stretching (online). If false (0), it will not.


DrawArcPath

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draws an arc in any window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DrawChordPath | DrawEllipticalPath | DrawPath | DrawPiePath
Format: | DrawArcPath(Left, Bottom, Right, Top, RotateAngle, Object, StartX, StartY, EndX, EndY)
Parameters: |
Left
Required. Any numeric expression for the left side of the arc's bounding box.
Bottom
Required. Any numeric expression for the bottom side of the arc's bounding box.
Right
Required. Any numeric expression for the right side of the arc's bounding box.
Top
Required. Any numeric expression for the top side of the arc's bounding box.
RotateAngle
Required. Any numeric expression for the angle of rotation of the arc in degrees. This represents a rotation about the center of the bounding box. If it is greater than 0, the arc's shape will still be defined by the proportions of the bounding box, but will no longer be within its (un-rotated) screen coordinates. Note that although the arc itself will rotate RotateAngle degrees, neither of the endpoints for the lines defined by StartX, StartY, and EndX, EndY will be affected (i.e. the arc will not 'line up' with the angled lines).
Object
Required. Any expression for the object value that defines the window in which to draw the arc.
StartX
Required. Any numeric expression for the X coordinate of an endpoint of a line that defines the starting angle. The other endpoint is the center of the arc's bounding box.
StartY
Required. Any numeric expression for the Y coordinate of an endpoint of a line that defines the starting angle. The other endpoint is the center of the arc's bounding box.
EndX
Required. Any numeric expression for the X coordinate of an endpoint of a line that defines the ending angle. The other endpoint is the center of the arc's bounding box.
EndY
Required. Any numeric expression for the Y coordinate of an endpoint of a line that defines the ending angle. The other endpoint is the center of the arc's bounding box.
Comments: This statement is intended for building drawing tools. The arc is drawn in white and is exclusive OR'ed onto the screen.

Example:

  DrawArcPath(0, 500, 700, 0 { Bounding box for the arc },
              0 { No rotation occurs },
              Self() { Draw in this module's window },
              XLoc(), YLoc() { One angled line follows mouse },
              750, 300 { Other line of angle });

This draws an arc on the screen that has a horizontal line at its 0 degree position and whose second line of its open angle follows the mouse. As the mouse moves and changes the angle of the two lines, the arc will follow its path, and more or less of it will appear.


DrawChordPath

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draws a chord in any window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DrawArcPath | DrawEllipticalPath | DrawPath | DrawPiePath
Format: | DrawChordPath(Left, Bottom, Right, Top, RotateAngle, Object, StartX, StartY, EndX, EndY)
Parameters: |
Left
Required. Any numeric expression for the left side of the bounding box.
Bottom
Required. Any numeric expression for the bottom side of the bounding box.
Right
Required. Any numeric expression for the right side of the bounding box.
Top
Required. Any numeric expression for the top side of the bounding box.
RotateAngle
Required. Any numeric expression for the angle of rotation of the chord in degrees. This represents a rotation about the center of the bounding box. If it is greater than 0, the chord's shape will still be defined by the proportions of the bounding box, but will no longer be within its (un-rotated) screen coordinates. Note that although the chord itself will rotate RotateAngle degrees, neither of the endpoints for the lines defined by StartX, StartY, and EndX, EndY will be affected (i.e. the chord will not 'line up' with the angled lines).
Object
Required. Any expression for the object value that defines the window in which to draw the chord.
StartX
Required. Any numeric expression for the X coordinate of an endpoint of a line that defines the starting angle. The other endpoint is the center of the bounding box.
StartY
Required. Any numeric expression for the Y coordinate of an endpoint of a line that defines the starting angle. The other endpoint is the center of the bounding box.
EndX
Required. Any numeric expression for the X coordinate of an endpoint of a line that defines the ending angle. The other endpoint is the center of the bounding box.
EndY
Required. Any numeric expression for the Y coordinate of an endpoint of a line that defines the ending angle. The other endpoint is the center of the bounding box.
Comments: This statement is intended for building drawing tools. The chord shape is drawn in white and is exclusive OR'ed onto the screen. The shape of the object is such that the angle defined by the two lines forms a flattened side to an ellipse (if the angle between the lines is less than 180 degrees), or a sliver that has been cut from the ellipse (if the angle is greater than 180 degrees).

Example:

  DrawChordPath(0, 500, 700, 0 { Bounding box for the chord },
                90 { Rotate 90 degrees clockwise },
                Self()  { Draw in this module's window },
                550, 470 { One line of angle },
                750, 300 { Other line of angle });

This draws an small chord in the upper right hand corner of the screen, with its defining angle 90 degrees out of phase in the lower right hand corner.


DrawEllipticalPath

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draw an ellipse in any window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DrawArcPath | DrawChordPath | DrawPath | DrawPiePath
Purpose: | This statement draws an ellipse in any window.
Format: | DrawEllipticalPath(Left, Bottom, Right, Top, RotateAngle, Object)
Parameters: |
Left
Required. Any numeric expression for the left side of the bounding box.
Bottom
Required. Any numeric expression for the bottom side of the bounding box.
Right
Required. Any numeric expression for the right side of the bounding box.
Top
Required. Any numeric expression for the top side of the bounding box.
RotateAngle
Required. Any numeric expression for the angle of rotation of the ellipse in degrees. This represents a rotation about the center of the bounding box. If it is greater than 0, the ellipse's shape will still be defined by the proportions of the bounding box, but will no longer be within its (un-rotated) screen coordinates.
Object
Required. Any expression for the object value that defines the window in which to draw the ellipse.
Comments: This statement is intended for building drawing tools. The ellipse is drawn in white and is exclusive OR'ed onto the screen.

Example:

  DrawEllipticalPath(200, 300, 640, 190 { Bounding box for the ellipse },
                     65 { Rotate 65 degrees clockwise },
                     Self() { Draw in this module's window });

This draws a stubby, cigar-shaped ellipse in the center of the screen. It is situated in a NE-SW orientation.


DrawPath

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draws a polygon in any window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DrawArcPath | DrawChordPath | DrawEllipticalPath | DrawPiePath | PathDraw
Format: | DrawPath(XArray, YArray, N, Object)
Parameters: |
XArray
Required. An array element expression. This array specifies the X coordinates of the path to draw, beginning with the element specified.
YArray
Required. An array element expression. This array specifies the Y coordinates of the path to draw, beginning with the element specified.
N
Required. Any numeric expression for the number of points (number of array elements) in the path.
Object
Required. Any expression for the object value that defines the window.
Comments:

This statement is intended for building drawing tools. The polygon is drawn in white and is exclusive OR'ed onto the screen.

Do not confuse DrawPath with the function, PathDraw()

Example:

  DrawPath(xValues[0], yValues[0] { Starting coordinates that define polygon },
           11 { Figure has 11 vertices },
           Self() { Draw in this module's window });

This will draw a 10 sided polygon as defined by the coordinates in the two arrays.


DrawPiePath

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Draws a pie in any window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DrawArcPath | DrawChordPath | DrawPath | DrawPiePath
Format: | DrawPiePath(Left, Bottom, Right, Top, RotateAngle, Object, StartX, StartY, EndX, EndY)
Parameters: |
Left
Required. Any numeric expression for the left side of the bounding box.
Bottom
Required. Any numeric expression for the bottom side of the bounding box.
Right
Required. Any numeric expression for the right side of the bounding box.
Top
Required. Any numeric expression for the top side of the bounding box.
RotateAngle
Required. Any numeric expression for the angle of rotation of the pie, in degrees. This represents a rotation about the center of the bounding box. If it is greater than 0, the pie's shape will still be defined by the proportions of the bounding box, but will no longer be within its (un-rotated) screen coordinates. Note that although the pie itself will rotate RotateAngle degrees, neither of the endpoints for the lines defined by StartX, StartY and EndX, EndY will be affected (i.e. the pie will not 'line up' with the angled lines).
Object
Required. Any expression for the object value that defines the window.
StartX
Required. Any numeric expression for the X coordinate of an endpoint of a line that defines the starting angle. The other endpoint is the center of the bounding box.
StartY
Required. Any numeric expression for the Y coordinate of an endpoint of a line that defines the starting angle. The other endpoint is the center of the bounding box.
EndX
Required. Any numeric expression for the X coordinate of an endpoint of a line that defines the ending angle. The other endpoint is the center of the bounding box.
EndY
Required. Any numeric expression for the Y coordinate of an endpoint of a line that defines the ending angle. The other endpoint is the center of the bounding box.
Comments: This statement is intended for building drawing tools. The pie is drawn in white and is exclusive OR'ed onto the screen.

Example:

  DrawPiePath(10, 325, 430, 75
             { Bounding box for the pie },
              90 { Rotate 90 deg. counter-clockwise },
              Self() { Draw in this module's window },
              550, 470 { One line of angle },
              750, 300 { Other line of angle });

This draws a wedge of pie on the left side of the screen, point upward.


DrawScale

(Meter Parts Library)

Description: | Will draw a scale (i.e. tick marks) for a linear or radial type meter. These marks are images (normally lines) indicating the major and minor divisions of the entire scale. This function must be called inside a GUITransform to work properly.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: |
Format: | \MeterParts\DrawScale(MajorTickImage, MinorTickImage, MajorDivisions, MinorDivisions, RelativeSize, LinearScale, Orientation, MinAngle, MaxAngle, Hue, Saturation, Brightness, Transparency, Contrast, ColorizeHue, ColorizeIntensity)
Parameters: |
MajorTickImage
Required. The full path to an image file to use as a major tick mark.
MinorTickImage
Required. The full path to an image file to use as a minor tick mark.
MajorDivisions
Optional. The number of major divisions in the scale. The default is 1 major division.
MinorDivisions
Optional. The number of Minor divisions between the major divisions in the scale. The default is 5 minor divisions.
RelativeSize
Optional. The relative size of the tick marks. If set, the tick marks will resize independently from the automatic sizing that is done when you resize the transform. Typically the range for this parameter is from 0 to 2, where 2 is double the default size and 0.5 is half the default size. The default is 1 which is the native size as scaled with the transform size.
LinearScale
Optional. A flag that, when set to true causes a linear scale to be drawn. When set to false, a Radial scale will be created. The default is true.
Orientation
Optional. A flag that is relevant only when drawing a linear type scale. When set to true the scale will be oriented vertically. When set to false, the scale will be oriented horizontally. The default is false.
MinAngle
Optional. The angle for the starting position of a radial type scale. 0 is defined as up or the 12 o’clock position. This parameter is relevant only when drawing a radial type scale. The default is 0.
MaxAngle
Optional. The angle for the ending position of a Radial type scale. . 0 is defined as up or the 12 o’clock position. This parameter is relevant only when drawing a radial type scale. The default is 90.
Hue
Optional. The Hue translation to perform on the tick mark image. The image must have color in it already to perform a hue translation. If there is no color to start with, then changing this value does nothing. You can add color by setting a value for the ColorizeHue parameter, described later.
The default is 0, indicating that no hue translation is done and the indicator is in its native color.
Saturation
Optional. The amount of saturation of the colors in the tick mark image. A value of 0 will make the image black and white (no color saturation). A value of 2 produces a brightly colored (saturated) indicator. The default is 1 which corresponds to the native saturation of the indicator image.
Brightness
Optional. An adjustment of the brightness of the tick mark image. Higher numbers produce a brighter image. A 0 produces a black image. The default is 1 which corresponds to the native brightness of the tick mark image.
Transparency
Optional. An adjustment of the opacity of the tick mark image where 1 means 100% opacity and 0 means %100 transparent. The default is 1.
Contrast
Optional. An adjustment of the contrast of the colors in the tick mark image. A value of 0 produces a flat looking image and a value of 2 gives a high contrast image. The default is 1 which corresponds to the native contrast of the image.
ColorizeHue
Optional. A value that works in conjunction with ColorizeIntensity. This is the hue of the color that is introduced by colorizing an image. Colorizing an image will introduce color into an image that previously was black and white or grayscale. The default value is 0.
ColorizeIntensity
Optional. A value to define how much color to introduce into the image. The default is 0, meaning not to introduce any color at all into the image.
Comments: This function must be called from within a GUITransform statement in order for it to work correctly.
The Tick Marks are scaled according to the size of the transform and the RelativeSize parameter.

Example:

  GUITransform(254, 229, 404, 79,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "MeterParts", TRUE)\DrawScale("Bitmaps\Meter Parts\Tick Marks\Large_Thin.png",
               "Bitmaps\Meter Parts\Tick Marks\Small_Thin.png",
               7, 5, 1, 0, 0, 0, 225, 135, 0, 1, 1, 1, 1, 0, 0, "<FFFFFFFF>", 0));


DriveInfo

(Engine-Level Function)

Description: | Returns information about a disk drive.
Returns: | Pointer (see comments)
Usage: | Script Only.
Function Groups: | Software and Hardware
Related to: | Dir | FileFind
Format: | DriveInfo(Attributes, Option)
Parameters: |
Attributes

Required. Any numeric expression which gives the attributes to match for each drive. Drives that don't match these attributes won't be listed. The Attributes parameter is constructed by adding together the numbers from the table below

(See: Bitwise Parameters & Operations)

Attribute | Bit No. | Drive Type
1 | 0 | Removable drive (floppy disk)
2 | 1 | Fixed drive (hard disk)
4 | 2 | Remote drive (network disk)
8 | 3 | CD-ROM drive
Option
Required. Any numeric expression giving the type of text information to generate. All information is placed in a single text string (which will be stored in an element of the array that is created). The information is written from left to right, with lowest option numbers first.
Option | Bit No. | Information Type
1 | 0 | Drive type
2 | 1 | Drive letter and colon (e.g. C:)
4 | 2 | Volume name
8 | 3 | Total volume space (in bytes)
16 | 4 | Volume space available (in bytes) for consumption
Comments: This function will only return information on network drives that have been assigned drive letters (i.e. those having been used in a Windows™ command prompt "net use" statement or VTScada Redirect statement).

This function returns a single-dimension array of text values (one element per drive). Each text value contains the information specified by Option for each drive that matches Attributes. The size information is expressed as a text string of a decimal number of the requested value concatenated with the other information. The drive type is returned as a number, as shown in the following table.
Value | Drive Type
0 | Removable drive (floppy disk)
1 | Fixed drive (hard disk)
2 | Remote drive (network disk)
3 | CD-ROM drive

Example:

[
  Title = "OverviewLabel";
  Color;
  Drives;
  Titles;
]
Init [
  If ! Valid(Drives) Main;
  [
    Drives = DriveInfo(6 { All hard and network disks },
                       6 { Drive letter and volume name });
    Titles = New(1);
    Titles[0] = "Drive List";
  ]
]

Main [
  Return(Self);
  GUITransform(0, 1, 1, 0,
               1 - 100, 500, 500, 1 - (100), 1,
               0, 0, 1, 0,
               0, 0, 0,
               \System\GridList(Titles { Column Titles Array },
                                Drives { Data Array          },
                                "%s"   { Format for Text     }));
]

This would list the drive letters and volume names, both fixed and remote, available on the system in table form on the Overview page.


DropList

(System Library)

Description: | Draws a droplist with (optional) title or bevel or both.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | ToolBar | VScrollbar
Format: | System.DropList(X1, Y1, X2, Y2, Data, Title, Index, FocusID, Trigger, NoEdit, Init, Variable [, DrawBevel, VertAlign, AlignTitle, Style, BGColor, FGColor, FontParm, Title])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the droplist.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the (opened) droplist.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the droplist opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the (opened) droplist, whichever is the opposite to Y1.
Data
Required. An array of data to display in the droplist.
Title
Required. Any text expression to be used as a title for the droplist.
Index
Required. A variable whose value indicates the array index of the highlighted item in the list. Index can be set invalid to reset the droplist.
FocusID
Required. Any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the droplist will display its current setting, but will not be able to be opened (i.e. its value cannot be changed) and will appear grayed out. The default value is 1.
Trigger
Required. If the droplist is editable, Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero; 1 if enter is pressed, 2 otherwise.
If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.
NoEdit

Required. Any logical expression. If TRUE (non-0) the text displayed in the droplist cannot be edited directly, if FALSE (0) it can be edited in the same manner as an editfield.

Options of the Style parameter may conflict with this parameter, if configured. In this case, the Style parameter will be used and the NoEdit parameter will be ignored.

If a variable is used to specify the NoEdit parameter value and this variable is set to invalid, NoEdit will default to TRUE.
If Invalid is used directly as the value of the NoEdit parameter, NoEdit will default to FALSE.

Init
Required. Any expression for the initial value displayed in the field if Index is set to invalid. If NoEdit is true, then Init must be an element of the data array.
Variable

Required. The variable whose value is set by the droplist.

The maximum number of characters that a user can provide is 65535.

DrawBevel
An optional parameter that is any logical expression. If true (non-0) a bevel is drawn around the droplist, if false (0) no bevel is drawn. The default value is false.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the editfield according to one of the following options
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
An optional parameter that is any logical expression. If true (non-0) the title is included in the calculation for vertical alignment, if false(0) it is added to the droplist after it (and its bevel if one exists) has been vertically aligned. The default is true.
Style

Comprised of a combination of bit values to yield the desired effects.

(See: Bitwise Parameters & Operations)

Bits 0 and 1 set the type of list that will be presented.

Value | Definition
neither set | No droplist, rather a listbox with the selected item above
1 | Droplist and editable selection
2 | Droplist with non-editable selection
3 | Undefined. Bits 0 and 1 are mutually exclusive.

Bits 2 and 3 define input character handling. If neither is set, input is passed to script code as typed.

Value | Definition
neither set | Input is passed as typed
4 | Input is converted to all uppercase.
8 | Input is converted to all lowercase.
12 | Undefined. Bits 2 and 3 are mutually exclusive.

Bit 4 controls list sorting.

Value | Definition
16 | The list is presented in sorted order to the user.

Bit 5 (value 32) List uses extended UI mode: No F4, Down Arrow Drops List, No Mouse Wheel

Bit 6 Undefined

Bit 7 Undefined

Bit 8 (value 256) enables Windows visual styles.

Bit 9 (value 512) defines and enables exact use of application-defined geometry. The default is to perform auto-geometry modification to give the best fit.

BGColor
Optional. Any numeric expression for the background color of the control. No default value.
FGColor
Optional. Any numeric expression for the foreground color of the control. No default value.
FontParm
Optional font value.
TitleBGColor
Optional. Background color under the title.
TitleFGColor
Optional. Foreground (text) color for the title.
BevelColor
Optional. Color of the bevel line.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The height of the (unopened) droplist is constant, with X1 and X2 defining its width, and Y1 and Y2 defining its opened height, which may or may not include the added height of a title and bevel, depending on the alignment used and if they exist. Note that if the entire list can be displayed in a smaller area than indicated by Y1 and Y2, the dropped list height will be decreased accordingly. Droplist enforces a minimum dropped list size of four rows, unless the list is smaller in size.

Droplist may not be wrapped in a GUITransform.

Example:

Init [
If 1 Main;
  [
    Choices = New(4);
    Index = 0;
    Choices[0] = "Open";
    Choices[1] = "Close";
    Choices[2] = "On";
    Choices[3] = "Off";
  ]
]
Main [
  System.DropList(10, 210, 210, 390 { Boundaries of list },
                   Choices { Data displayed },
                   "Match String" { Title },
                   Index { Highlighted index },
                   1, 1 { Focus ID, trigger },
                   0 { Editable field },
                   "Cancel" { Starting value },
                   Val { Variable to set },
                   0 { No bevel },
                   0 { Align top of list });
]

This shows an editable droplist without a bevel, with the top of the droplist itself at Y = 210. The title "Pick a String" is above it (i.e. beyond the top of the defined area). The initial value in the field, and thus the initial value of Val will be "Cancel". When the list is first opened, the first array entry (element 0) will be highlighted. The trigger variable is not used.


DropTree

(System Library)

Description: | Draws a control similar to a Droplist, but rather than a flat list, a tree of possible selections is displayed.
Returns: | Object reference.
Usage: | Script Only.
Function Groups: | System
Related to: | Bevel | CheckBox | ColorSelect | DropList | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | TextBox | ToolBar | VScrollbar | TreeControl
Format: | System.DropTree(Left, Bottom, Right, Top, TreeData, Title, SelectedKey, FocusID, FTrigger[, DrawBevel, AlignTitle, DlgRoot, Trigger, BGcolor])
Parameters: |
Left
Any numeric expression for the left coordinate of the tool.
Bottom
Any numeric expression for the bottom coordinate of the tool.
Right
Any numeric expression for the right coordinate of the tool.
Top
Any numeric expression for the top coordinate of the tool.
TreeData
The data to display, in Node array format. The format is the same as for a call to TreeControl
Title
Any text expression to be used as a title.
SelectedKey
The key of the selected item. Must be a variable, and may specify initial selection.
FocusID
Any numeric expression from 0 to 32767 for the FocusID.
FTrigger
The Focus Trigger of the DropTree.
DrawBevel
Optional Boolean. If TRUE (non-0) a bevel is drawn. Defaults to FALSE.
AlignTitle
An optional parameter that is any logical expression. If TRUE (non-0) the title is included in the calculation for vertical alignment. The default is FALSE.
DlgRoot
Optional. The object value of the root dialog. Used for alignment of the DropTree.
Defaults to the caller if not specified.
Trigger
An optional numeric expression. Initially set to zero (0) when the DropTree opens.
If the user presses the Escape key or closes the extended window, then Trigger becomes 1.
BGColor
Optional background color of the control.
Comments:

This function allows the use of disabled options - grayed in appearance and unselectable.
The following set of helper functions is available. These may be added to the caller of DropTree to add special handling of certain events.

  • OnLeftClick(NodeArray)

- Subroutine: The left mouse button was released over a tree node.

  • OnRightClick(NodeArray, X, Y)

- Subroutine: The right mouse button was released over a node. X and Y are the coordinates of the mouse.

  • OnDoubleClick(NodeArray, X, Y)

- Subroutine: The left mouse button was double-clicked over a node. X and Y are the coordinates of the mouse.

  • CreateSubTree(NodeKey)

-

  • ExpandTreeToNode(NodeKey)

- Recursive Subroutine: Used for SetSelected call, expands to given node

  • Collapse()

- Will traverse the whole tree starting from the leaves, working towards the root, calling CollapseNodes() on each node.


DurationParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper for ParameterEdit, used when adding a duration parameter to a control.
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | ParameterEdit| ColorParameterEdit | TagParameterEdit |TextParameterEdit | NumericParameterEdit
Format: | \DurationParameterEdit(DurationVal, ParmDef, Enable, Left, Bottom, Right, Top, LabelWidth, HideTitle, PtrWaitClose, DlgRoot, ID[, DefaultMultiplier, DefaultUnit, SingleValueParm, AllowInvalidParm, MaxFiveYears])
Parameters: |
DurationVal
Required. Parameter Value - See comments
ParmDef
Required. Parameter Definition structure
Enable
Required. Show the Graphics for Editing the Parm Val
Left
Required. Any numeric expression for the left edge of the object.
Bottom
Required. Any numeric expression for the bottom edge of the object.
Right
Required. Any numeric expression for the right edge of the object.
Top
Required. Any numeric expression for the top edge of the object.
LabelWidth
Number of pixels allotted for the width of the label
HideTitle
Set to TRUE to hide the title of the control.
PtrWaitClose
Wait to close.
The parameter edit module will set the value of this pointer to true when the caller should wait to close. For example, if the parameter edit is displaying a dialog, or completing a calculation.
DlgRoot
Root of the edit dialog
ID
Focus ID
DefaultMultiplier
(Optional) Initial multiplier to display
DefaultUnit
(Optional) Initial unit to display
SingleValue
(Optional) TRUE to display a "Single Value" option. Default = TRUE
AllowInvalid
(Optional) TRUE to allow an invalid entry (no duration entered, "Set Duration" button will be displayed). Default = FALSE
MaxFiveYears
(Optional) TRUE to limit duration values to five years. Default = TRUE
Comments:

Duration consists of a multiplier and a unit. The units are as follows:

  • S = Seconds
  • M = Minutes
  • H = Hours
  • D = Days
  • W = Weeks
  • C = (Calendar) Months
  • Q = Quarters
  • Y = Years
  • V = Single Value

For example, a duration of one hour would be denoted as 1H. Two weeks would be denoted as 2W.

Single Value (1V) is for the special case where the duration is equal to the entire available period.

For example, If you use DurationParameterEdit while configuring a table in a report and chose a single value TPP, your table will have only a single record covering the entirety of the report period.

When Single Value is chosen, the only valid multiplier is 1.

Example:

  PEObj[1] = DurationParameterEdit(Space                        { Left coordinate         },
                                   PEBot[0] + 2*EditHt + Space  { Bottom coordinate       },
                                   PanelWd - Space              { Right coordinate        },
                                   PEBot[0] + Space             { Top coordinate          },
                                   Parms[#DurationValue]        { Parameter value         },
                                   ParmDefs[#DurationValue]     { Parameter definition    },
                                   "Duration"                   { Title                   },
                                   TitleWd, FALSE               { TitleWd, hide title     },
                                   DurationType                 { Type index              },
                                   &SubWaitClose[1]             { Wait close pointer      },
                                   DialogRoot, 1                { Root, ID                },
                                   1, "D"                       { Default values (1 day)  },
                                   Invalid, Invalid             { Tooltip, description    },
                                   TRUE, FALSE                  { Use expr, single value  },
                                   Invalid, TRUE                { Var name, allow invalid },
                                   FALSE                        { Max five years          });


E Functions

The sections that follow identify all VTScada functions beginning with "E".


Edge

(Engine-Level Function)

Description: | Performs a test for a rising or falling edge.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Generic Math, Variable
Related to: | Change
Format: | Edge(Value, Mode)
Parameters: |
Value
Required. Any expression giving a numeric status value to be tested. It is interpreted as true if it is non-zero, and false if it is zero.
Mode

Required. Dictates whether the change from false to true or true to false is tested.

If it is 0, a true to false (a falling edge) is tested.

If it is 1, a false to true (a rising edge) is tested.

Comments: Edge is one of the Latching and Resetting functions. Use accordingly.

Example 1: Monitor for a value reaching a setpoint.

  If Edge(Var1 > 2, 1) RisingState;

Jump to RisingState when Var1 changes from less than 2 to greater than 2.

  If Edge(Var1 > 2, 0) FallingState;

Jump to FallingState when Var1 changes from greater than 2 to less than 2.

Example 2: Monitor for a left mouse click release

  If Edge(LocSwitch() == 4, 0) {Left mouse button released } &&
     Target(10, 25, 110, 225)  {Mouse in target area       };
  [
    ...
  ]

When the operator releases the left mouse button within a target area, do what is in the script block.

Related information:

Latching and Resetting Functions


Edit

(System Library)

Description: | Draws an edit field with (optional) title or bevel or both.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | FileChooser | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | ToolBar | VScrollbar
Format: | System.Edit(X1, Y1, X2, Y2, Title, Variable [, FocusID, Trigger, View, DataType, DrawBevel, VertAlign, AlignTitle, LowLimit, HighLimit, Style, PrefixValue, SuffixValue, BGColor, FGColor, FontParm, TitleBGColor, TitleFGColor, BevelColor, PlaceHolder, HeightOut])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the edit field.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the edit field.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the edit field opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the edit field, whichever is the opposite of Y1.
Title
Required. Any text expression to be used as a title for the field.
Variable
Required. A variable whose value is set by the edit field.
FocusID
Optional. Any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the edit field will display its current setting, but its value will not be able to be changed and it will appear grayed out. The default value is 1.
Trigger
Optional. Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero: 1 if enter is pressed, 2 otherwise.
View
Optional. Indicates how to display the edit field, as follows
View | Display Mode
0 | Invisible
1 | Normal (normal color scheme - never grayed-out)
2 | Deprecated.
3 | Grayed-out background when disabled (FocusID is 0)
4 | Grayed-out background when disabled (FocusID is 0). Clicks are detected by a Pick(). Disables the Multiline style (Style=5).

This parameter may be used to force an edit field with a FocusID of 0 to display normally, rather than allowing it to default to its grayed color. Note that if the FocusID is not 0, setting this value as 2 will not force the field to gray out.

The default value is 2 if FocusID is 0, otherwise it's 1.

DataType
Optional. Any numeric expression giving the type of data accepted by the edit field as follows
DataType | Description
0 | Byte (unsigned)
1 | Short (2 byte signed)
2 | 64-bit integer (8 byte signed)
3 | Double precision floating point (8 byte signed)
4 | Text
5 | Octal (4 byte unsigned)
6 | Hexadecimal (4 byte unsigned)

For types 0 - 2, if the number entered into the field is prefaced by a "0x" the value is taken to be hexadecimal format, and if it is prefaced by a "0" it is considered to be octal. In either case, the value is converted to decimal format when return is pressed or the focus is lost.

For type 5, regardless of whether the number entered into the field is prefaced by a "0" the value is taken to be octal and will be displayed as such. The actual type of Variable will be text.

Type 6, like type 5 will be kept in its declared format of hexadecimal regardless of whether the number entered into the field is prefaced by a "0x". The actual type of Variable will be text

For types 0 - 2, 5 and 6 (hex and octal formats), the number will be interpreted as 4-byte signed interger. (ie. "0xFFFFFFFF" will be treated as -1.)

The default value is 4 - text.

DrawBevel
Optional. Any logical expression. If true (non-0) a bevel is drawn around the edit field, if false (0) no bevel is drawn.
If the edit field is beveled, its size will become fixed and will be the same as that for a droplist. The default value is false.
VertAlign
Optional. Any numeric expression that sets the vertical alignment of the edit field according to one of the following options
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
Optional. Any logical expression. If true (non-0) the title is included in the calculation for vertical alignment. If false(0) it is added to the edit field after it (and its bevel if one exists) has been vertically aligned. The default is true.
LowLimit
Optional. Any expression giving the minimum value or minimum number of characters to be accepted by the edit field (depending on the data type).
This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value less than LowLimit is entered in the field (or there are too few characters, in the case of text value), the variable set by the field will revert to the previous value. No default.
HighLimit

Optional. Any numeric expression giving the maximum value or maximum number of characters to be accepted by the edit field (depending on the data type).
• If used for numbers, the default is 255 characters.
• If used for text, the default is 32767 characters.
The only valid lengths for text are from 0 to 65535. If you try to set a length outside that range, 32767 will be used as the maximum length.

For numeric values, the user may provide a decimal, octal or hexadecimal value. If this parameter is valid and the user enters a value greater than HighLimit in the field then the variable set by the field will revert to the previous value. No default is set. For text, users simply cannot type past the maximum character length.

Style

Optional. Default 0. Comprised of a combination of bit values to yield the desired effects. Note that some combinations should not be used as they could be mutually exclusive. For example converting input to all uppercase and to all lowercase (bits 2 and 3 both set).

Bits 0 and 1 are reserved for bit compatibility with WinComboCtrl, and should be set to "0".

Bits 2, 3 and 4 define input character handling. It is reasonable to set bit 2 and 4 or 3 and 4, but not bits 2 and 3. If not set, input is used exactly as typed.

(See: Bitwise Parameters & Operations)

Bit Number

Definition

0 | Reserved for compatibility with WinComboCtrl, and should be set to "0"
1 | Reserved for compatibility with WinComboCtrl, and should be set to "0"

2

Input is converted to all uppercase

3

Input is converted to all lowercase

4

Input is masked. Any characters typed will appear as asterisks. (useful for password fields)

5

Multiline editing. When set, this bit causes a typed Enter key to be interpreted as "move to the start of the next line".

Text that contains carriage-return & line-feed characters has a line break inserted at each set.

Not supported by View = 4.

6 | Reserved (Always gray when disabled, differing from WinEditCtrl)
7 | Not used
8 | Reserved
9 | Reserved
10

Bits 10 and 11 control horizontal alignment as follows:

Bit 10 | Bit 11 | Alignment
0 | 0 | Left (default)
1 | 0 | Center
0 | 1 | Right
1 | 1 | Do not use
11
PrefixValue
Optional. Indicates the text expression that should be displayed immediately before (i.e. to the left of) the editable part of the control. No default.
SuffixValue
Optional. Indicates the text expression that should be displayed immediately after (i.e. to the right of) the editable part of the control. No default.
BGColor
Optional. Any numeric expression for the background color of the control. No default value.
FGColor
Optional. Any numeric expression for the foreground color of the control. No default value.
FontParm

Optional. A Font value, or the number zero. Set as "0" to use the default system font.

TitleBGColor
Optional. Background color under the title.
TitleFGColor
Optional. Foreground (text) color for the title.
BevelColor
Optional. Color of the bevel line.
PlaceHolder
Optional text. Information to display in place of invalid entry. Typically a phrase describing how the field is to be used.
HeightOut
Output. Finds the height of the field in pixels, including title and bevel if applicable.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The height of the edit field is constant, with X1 and X2 defining its width, and Y1 and Y2 defining the boundaries in which it is to be confined vertically, which may or may not include the added height of a title and bevel, depending on the alignment used and if they exist.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Examples:

Examples often use English text in labels so that you can make a copy as a starting point when building your own version.
Better practice is to replace the text with phrase keys, and the \GetPhrase() function.

  System.Edit(10, 50 { Top left corner - fixed },
              110, 20 { Bottom right corner  },
              "Description" { Title },
              Desc { Var to update }
              { Remainder of parameters not used, so omitted });
  System.Edit(20, 110, 120, 70 { Outline of field },
              "Name", Name { Title; var to update },
              2, DoneFlag { Focus ID, trigger },
              Invalid { Default display },
              2 { Long integer values },
              Invalid { Default of no bevel },
              1 { Center the editfield },
              1 { Include title in alignment },
              Invalid { No minimum value },
              100 { Maximum acceptable value });


EditFile

Description: | Informs the configuration management system that a file has been modified in the working copy, typically before making a call to CommitEditedFiles.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | CommitEditedFiles
Format: | \AppLayer.EditFile(ModItem[, JustInformSubscribers])
Parameters: |
ModItem

Required. A file name, a dictionary of file names, or an array of names of modified files.
File paths relative to the working copy are recommended. Files outside the working copy cannot be added.

If invalid, all the working copy files are used.

If a dictionary, then the keys are the files to use. If the values are FileMetadata, then the structures are expected to be fully populated including the deltas. If the values are streams, then the stream contains the new copy of the file to commit. The stream may contain a Time metadata value for the time stamp. If the metadata is not there, CurrentTime will be used.

Otherwise the dictionary values contain a numeric value with options as follows:

  • 0 means the file is added, modified or deleted based on the working copy file
  • 1 mean the file is deleted from working copy
  • 2 mean ignore the file in the working copy

The default for this value is 0

JustInformSubscribers
Optional Boolean. Set TRUE to not mark the file as modified. This is useful when switching between repository revisions.Defaults to FALSE.
Comments:

This function must be called only if the caller has the semaphore (working copy lock). The files will be added to the Modified dictionary so that it is distributed to all subscribers when the transaction is closed.

If a set of files is passed, then the values will also be passed to the repository. The primary purpose of this is that it allows for files to be marked as ignored.


EditINI

(VTScada Library)

Description: | Draws an edit field from which a value of an application property in Settings.Dynamic may be set.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | EditINICheckBox | ReadINI | ReadSectINI | WriteSectINI
Format: | \Library.EditINI(Section, VarName [, Title, DataType, FocusID, View, DrawBevel, VertAlign, AlignTitle, UpdateVar, LowLimit, HighLimit])
Parameters: |
Section
Required. Any text expression giving the name of the section in the file. This should not include the square brackets delimiting the section.
VarName
Required. Any text expression giving the name of the variable for which the value is to be set.
Title
Optional. Any text expression to be used as a title for the field. No default.
DataType
Optional. Any numeric expression giving the type of data accepted by the edit field as follows. No default.
DataType | Type
0 | Byte (unsigned)
1 | Short (2 byte signed)
2 | Long (4 byte signed)
3 | Double precision floating point (8 byte signed)
4 | Text

Note that for types 1 and 2, if the number entered into the field is prefaced by a "0x", the value is taken to be a hexadecimal value and is converted to a decimal value when return is pressed. The default value is 4.

FocusID
Optional. Any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the edit field will display its current setting, but its value will not be able to be changed and it will appear grayed out. The default value is 1.
View
Optional. Indicates how to display the edit field, as follows:
View | Display
0 | Invisible
1 | Normal (color scheme - no graying)
2 | Grayed out (only if FocusID is 0)

This parameter may be used to force an editfield with a FocusID of 0 to display normally, rather than allowing it to default to its grayed color. Note that if the FocusID is not 0, setting this value as 2 will not force the field to gray out.
The default value is 2 if FocusID is 0 and 1 otherwise.

DrawBevel
Optional. Any logical expression. If true (non-0) a bevel is drawn around the editfield, if false (0) no bevel is drawn. If the editfield is beveled, its size will become fixed and will be the same as that for a droplist. The default value is true.
VertAlign
Optional. Any numeric expression that sets the vertical alignment of the editfield according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
Optional. Any logical expression. If true (non-0) the title is included in the calculation for vertical alignment. If false (0) it is added to the editfield after it (and its bevel if one exists) has been vertically aligned. The default is true.
UpdateVar
Obsolete. The running system is always updated.
LowLimit
Optional. Any expression giving the minimum value or minimum number of characters to be accepted by the editfield (depending on the data type).

This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value less than LowLimit is entered in the field (or there are too few characters, in the case of text value), the variable set by the field will revert to the previous value. no default:
HighLimit
Optional. Any numeric expression giving the maximum value or maximum number of characters to be accepted by the editfield (depending on the data type).
This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value greater than HighLimit is entered in the field (or there are too many characters, in the case of text value), the variable set by the field will revert to the previous value.
Comments: This module is a member of the VTS Library and must therefore be called from within a GUITransform and prefaced by \Library.
The height of the edit field is constant, with the horizontal boundaries of its calling transform defining its width, and the vertical boundaries of its calling transform defining its height (to a minimum size). The height will include the height of the bevel, but may or may not include the title, depending on the alignment used.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Example:

  GUITransform(136, 175, 236, 145,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "Library", TRUE)\EditIni("System", GiveUpCallTimeout",
                                              "Give up", 2, 1, 2, 1, 1, 1,
                                               Invalid, 0, 2000));

This causes an edit box to display with the title "Give up". The operator may use it to change the value of GiveUpCallTimeout between the range of 0 and 2000.


EditINICheckBox

(VTScada Library)

Description: | Draws an edit field check box, with which a value of an application property in Settings.Dynamic may toggled between true and false.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | EditINI | ReadINI | ReadSectINI | WriteSectINI
Format: | \Library\EditINIcheck box(Section, VarName [, Title, BoxOnLeft, Align, FocusID, UpdateVar, EnableIfEditing])
Parameters: |
Section
Required. Any text expression giving the name of the section in the file. This should not include the square brackets delimiting the section.
VarName
Required. Any text expression giving the name of the variable for which the value is to be set.
Title
Optional. Any text expression to be used as a title for the field. No default:
BoxOnLeft
Optional. A Boolean, indicating whether the check box should be to the left or right of the label. Defaults to TRUE (box to the left of the label).
Align
Optional. Any numeric expression controlling the alignment of the label and the box. Defaults to 3 - Left, vertically centered.
Value | Meaning
0 | Left, top.
1 | Right, top.
2 | Full, top.
3 | Left, vertically centered.
4 | Right, vertically centered.
5 | Full, vertically centered.
6 | Left, bottom.
7 | Right, bottom.
8 | Full, bottom.
FocusID
Optional. Any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the check box will display its current setting, but its value will not be able to be changed and it will appear grayed out. The default value is 1.
UpdateVar
Obsolete. The running system is always updated.
EnableIfEditing

Obsolete. Will always evaluate to FALSE.

Within the Idea Studio, EditINICheckbox will always be disabled. Everywhere else, it will be enabled.

Comments: This module is a member of the VTScada Library and must therefore be called from within a GUITransform and prefaced by \Library\.

Example:

GUITransform(495, 375, 595, 345,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
              \Library\EditIniCheckBox("System", "AlarmPopupsEnable", "Alarm Popups",
               TRUE, 3, 1, Invalid, FALSE));

This draws a check box that operators may use to enable or disable the Alarm Popups application property.


Editor

Deprecated. Do not use in new code.

(Engine-Level Function)

Description | Displays an editor on the screen.
Returns | Nothing
Usage | Steady State only.
Function Groups | Editor, Graphics
Related to: | WinEditCtrl
Format | Editor(Left, Bottom, Right, Top, EditorValue, FocusID, Font [, Info])
Parameters |
Left
Required. Any numeric expression that defines the left hand side of the square area where the editor will operate.
Bottom
Required. Any numeric expression that defines the bottom of the square area where the editor will operate.
Right
Required. Any numeric expression that defines the right hand side of the square area where the editor will operate.
Top
Required. Any numeric expression that defines the top of the square area where the editor will operate.
EditorValue
Required. An editor value that has been created by MakeEditor which contains the text contents for the editor.
FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of the graphic. If FocusID is zero, this graphic cannot receive the input focus.
Font
Required. Any expression that returns a (fixed pitch) font value. If the font supplied is not fixed pitch, the system font is used.
Info
Optional. A one-dimensional array where information on the editor will be recorded, as follows: (no default)
Info | Information
0 | Current line number
1 | Current column number
2 | Total number of lines in editor
3 | Number of lines in view mode
4 | Current block mode (1 - line mode, 2 - column mode)
Comments If this statement has the focus it will allow you to enter text into the editor. Initial text can be added to the editor by the use of AddEditorText. The text can be read out of the editor by using stream functions. The editor can be forced to do certain actions by the use of ForceEvent. The default key map is as follows
Action | Default Keys
Cursor left | Cursor left
Cursor right | Cursor right
Cursor up | Cursor up
Cursor down | Cursor down
Enter | Enter
Delete the next character | Del
Delete the previous character | Backspace
Move to start of line | Home
Move up one page | Page up
Move down one page | Page down
Move to start of the editor | Shift-Home
Move to end of the editor | Shift-End
Move the selection block left one character | Shift-Cursor-Left
Move the selection block right one character | Shift-Cursor-Right
Move the selection block up one line | Shift-Cursor-Up
Move the selection block down one line | Shift-Cursor-Down
Cut the selection block to the clipboard | Ctrl-Del or Ctrl-X
Copy the selection block to the clipboard | Ctrl-Ins or Ctrl-C
Insert text from the clipboard | Shift-Ins or Ctrl-V
Toggle selection line, column mode | Ctrl-B

In the case of the optional Info parameter, the variable must be an array. However, it need not have all 5 elements - any information that is normally stored in an element beyond the upper limit of the array will be ignored.


Ellipse

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Draws an ellipse on the screen.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Arc | Ball | Circle | GUIArc | GUIChord | GUIEllipse | GUIPie
Format: | Ellipse(X, Y, XRadius, YRadius, Color, Width)
Parameters: |
X
Required. Any numeric expression giving the X coordinate of the center of the ellipse on the screen.
Y
Required. Any numeric expression giving the Y coordinate of the center of the ellipse on the screen.
XRadius
Required. Any numeric expression giving the radius of the ellipse along the X axis specified in units of X screen coordinates.
YRadius
Required. Any numeric expression giving the radius of the ellipse along the Y axis specified in units of Y screen coordinates.
Color
Required. A numeric expression giving the color of the ellipse.
Width
Required. Any numeric expression giving the width of the ellipse wall in units of X screen coordinates. The Width is always rounded to result in an odd number of pixels on the screen. The minimum width displayed will be 1 pixel.
Comments: This statement has been superseded by the GUIEllipse function and is maintained for backwards compatibility only.
As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.

Example:

Ellipse(400, 300 { Screen coordinates of ellipse center },
        200 { X radius in screen coordinates },
        100 { Y radius in screen coordinates },
        6 { Brown color },
        20 { Width of elliptical line in pixels });

This displays a brown ellipse in the middle of the screen.


Enable

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Tell the Alarm Manager to enable an alarm. Use the SetEnable function for new code.
Returns: | 0
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | CurrentTime | SetEnable
Format: | \AlarmManager\Enable(AlarmObject[, EventTime]);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine that will be enabled.
EventTime
Optional. The time stamp to use when adding this event to the alarm lists. If invalid or not defined, the default is CurrentTime().
Comments: The Enable subroutine always returns "0".


EnableHelp

(Engine-Level Function)

Description: | Enables you to enable or disable help file activation when the F1 key is pressed.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Help
Related to: | Window | SetHelp
Format: | EnableHelp(Enable, DefaultFileName)
Parameters: |
Enable
Required. Controls whether F1 help is activated. If Enable is set to zero, F1 help activation is disabled. If Enable is set to 1, F1 help activation is enabled.
DefaultFileName
Required. The name of the Windows help file to be launched when the user presses the F1 key (if F1 help is activated using the Enable parameter above), and if no other help context can be found.
This Windows help file is also the default help file that will be used when the user presses the Help button on the VTScada Application Manager (VAM).
Comments: VTScada calls EnableHelp during startup using the settings of the Setup.ini configuration file variables "F1DisableHelp" and "WEBHelp" respectively.

Example:

    EnableHelp(PickValid(!F1DisableHelp, 1), WEBHelp);

Specify whether F1 help activation is enabled and the name of the default help file by setting the values of these variables in the Setup.ini configuration file.


Encode

(System Library)

Description: | Processes a VTScada string using a configurable selection of compression, encryption, encoding and secure hashing.
Returns: | String
Usage: | Script Only.
Function Groups: | Encryption
Related to: | Decode | BlockEncrypt | Base64Encode | Hash |Pack
Format: | System.Encode(PlainValue[, PackDictionary, Compressed, Key, SaltLength, HashKey, Base64Encoded]);
Parameters: |
PlainValue
Required. The information to be encoded. May be any VTScada value that can be packed.
PackDictionary
Optional dictionary. If present, the information will be packed. Refer to notes for the Pack function for further details about this parameter.

Compressed

Optional Boolean. Set TRUE if the value is to be compressed before possible encryption. No compression is done unless this value is specified as TRUE.
Key
Optional. Key to be used as a seed for encryption.
SaltLength
Optional numeric. Length of salt in bytes to use for encryption ( 0-64 ) Not relevant unless the Key parameter is also valid. Defaults to zero.
HashKey
Optional text. If valid, an SHA2-256 hash will be added to the end of the result to prevent tampering. This string is used to seed/salt the hash.
Base64Encoded
Optional Boolean. Set true if the result is to be Base64 encoded.
Comments:

Note that if Base64 encoding is selected, the time required to encode and also to decode the information will increase by a factor of approximately ten.

Examples:

 If Watch(1);
  [
    Secret = \System.Encode("Hello");
    NotSecret = \System.Decode(Secret);
  ]


EncodeURIComponent

(System Library)

Description: | Encodes a string so that it can be embedded as part of a Uniform Resource Indicator. (URL-encoded)
Returns: | Text
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | UnEscape | Escape
Format: | System.HTTPServerInst.EncodeURIComponent(Input[, DontEscape])
Parameters: |
Input
Required text. The string to be encoded.
DontEscape

Optional text. The set of characters that should not be escaped in the result.

Defaults to -_.!~*'() if invalid.

Comments:

The input string must be UTF-8 encoded. Any character that is not a letter, a number, or included in the set of DontEscape symbols will be percent-encoded.

If you are content with the default set of DontEscape characters, you can use the wrapper:

 System.HTTPServerInst.Escape(Input)

Example:

  IF Watch(1);
  [
    InStr = "Hello(there) And.<testing>";
    OutStr = System.HTTPServerInst.EncodeURIComponent(InStr);
  ]

OutStr will contain "Hello(there)%20And.%3Ctesting%3E".


Encrypt

(Engine-Level Function)

Description: | The Encrypt function encrypts data. The algorithm used to encrypt the data is designated by the Key parameter. It is the VTScada analog of the Windows CryptoAPI CryptEncrypt call. Encrypt fully supports asymmetric and symmetric keys via CNG (Cryptography New Generation).
Returns: | Text
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | DeriveKey | Decrypt | Encrypt | ExportKey | GenerateKey | GetCryptoProvider | GetKeyParam | ImportKey | SetKeyParam
Format: | Encrypt(Key, PlainText, Final [, Reserved, Flags, Error])
Parameters: |
Key
Required. The handle to the key to use to encrypt the data.
PlainText
Required. A text string that contains the plain text to be encrypted.
Final
Required. A parameter that specifies whether this is the last section in a series being encrypted.
Final is set TRUE for the last or only block and FALSE if there are more blocks to be encrypted
Reserved
An optional parameter that should be set to 0. If omitted or invalid, then the value 0 is used.
Flags

Optional. Specifies the flags to be passed to CryptEncrypt. If omitted or invalid then the value 0 is used. Refer to the Crypto API Encrypt function for the flag list if using CAPI.

If using a CNG key, the following may be used (separate tables provided for asymmetric and symmetric keys)

If the encryption key is an asymmetric key:

Value | Meaning
0 | No padding is to added to the plaintext data before encryption.
1 | Padding is added to the plaintext data before encryption in accordance with the RSAES-PKCS1-v1_5 scheme.
2 | Padding is added to the plaintext data before encryption in accordance with the RSAES-OEAP scheme, using SHA1 for padding generation.
3 | Padding is added to the plaintext data before encryption in accordance with the RSAES-OEAP scheme, using SHA256 for padding generation.

If the encryption key is a symmetric key:

Value | Meaning
0 | No padding is to added to the plaintext data before encryption.
1 | Padding is added to the plaintext data before encryption.
Error
Optional. A variable in which the error code for the function is returned. It has the following meaning: (no default)
Error | Meaning
0 | Key successfully imported.
1 | Key, PlainText or Final parameters invalid.
x | Any other value is an error from CryptEncrypt.
Comments:

The cipher text is returned as a text string. If an error occurs, the return value is invalid.

When using CNG keys, the data supplied to Encrypt must be an integer multiple of the symmetric key block size UNLESS Flags is set to one of the padding options, when the algorithm will automatically pad the plaintext as required.

Note that the size of a block can be obtained using the GetKeyParam function and specifying the "BlockLength" property.

Example:

[
  PlainText1 = "abcdefghijklmnopqrstuvwxyz0123456789";
  CipherText1;
]
Init [
If 1 Main;
  [
    CipherText1 = Encrypt(Key3, PlainText1, 1, 0, 0);
  ]
]


ErrMessage

(ODBC Manager Library)

Description: | Returns a text message for the error code handed to it as a parameter
Returns: | Text message for the code provided.
Usage: | Script or steady state.
Function Groups: | ODBC
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.ErrMessage(ErrCode)
Parameters: |
ErrCode
Required. A numeric error code for which you want to obtain the appropriate message.
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

The error message / code is passed to \GetPhrase and will return the message in the current language if other than English and if available.

Example:

...
    MsgToReturn = ODBCManager.ErrMessage(ReturnedCode);
...


Escape

(System Library)

Description: | Performs URL-encoding of a given string.
Returns: | A URL-encoded version of the given string
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | UnEscape | EncodeURIComponent
Format: | Escape(PlainText)
Parameters: |
Input
Required text. The string to be encoded.
Comments:

Escape() is a wrapper for EncodeURIComponent.

When using this function, there is no option to specify characters that should not be escaped, therefore the default set will be used: "-_.!~*'()"


EvaluateAlarm

(Alarm Manager module)

Description: | Passes a new value to an alarm, to be compared to the setpoint.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Commission | SetSuppressed
Format: | \AlarmManager.EvaluateAlarm(AlarmName, Value[, TimeStamp, Custom, Description])
Parameters: |
AlarmName
Required text.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Value
Required. The new value to be checked against the alarm setpoint.
TimeStamp
Optional UTC timestamp of the value. Defaults to the current time.
Custom
Optional structure of custom fields to be logged with the event.
Description
Optional. If used, it supersedes the Description that is typically retrieved from the config struct (CfgStructure) of Commission.
Comments:

EvaluateAlarm should be called every time your tag's Value changes.

Example:

Every tag that has commissioned an alarm should include the following line of code within its Refresh state:

 { Evaluate alarm condition }
    \AlarmManager.EvaluateAlarm(AlarmName, Value, Timestamp);


Event

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Now a wrapper for AddEvent
Returns: | 0
Usage: | Script only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) (Alarm manager) | CurrentTime
Format: | \AlarmManager\Event(AlarmObject[, EventTime]);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine that will be enabled.
EventTime
Optional. The time stamp to use when adding this event to the alarm lists. If invalid or not defined, the default is CurrentTime().
Comments: The Event subroutine always returns "0".


Execute

(Engine-Level Function)

Description: | Executes a group of statements as a single entity in structures that would otherwise allow only one statement to be executed.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Logic Control
Related to: | Window | SetHelp
Format: | Execute(Statement1 [, Statement2])
Parameters: |
Statement1, Statement2, … }
Required. Are any expression(s) to be executed. Any number of parameters may be used. Commas or semi-colons must separate the parameters.
Comments: This statement is typically used with a Case or IfElse statement..

Example:

  If ZButton(10, 50, 110, 80, "Grid On", 1);
  [
    { If module is not already launched, launch it },
    IfElse(! Valid(ModPtr),
           Execute( { Do a series of tasks }
                   modPtr = ShowGrid(){Launched because of script},
                   ySpace = ySpace,
                   gridOn = 1
                   ),
    { If module already launched, stop it }
  { else } Execute( { Do a different series of tasks },
                   Slay(modPtr, 0),
                   gridOn = 0
          ));
  ]

When this particular button is pressed, modPtr's validity is checked and if it is not valid, module ShowGrid is launched and some variables set, otherwise, ShowGrid is slain via modPtr and variable gridOn is set to 0. Notice how the use of the Execute function allows a whole series of tasks to be performed with only one condition check.


ExecuteQuery

(ODBC Manager Library)

Description: | Called to send an SQL SELECT command to the server and get a reply back. This function is used as a general query tool and does not provide for the guaranteed eventual execution that the ExecuteQueryCached() function does.
Returns: | 0 upon query execution starting. See the following comments.
Usage: | Script Only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager\ExecuteQuery(ErrPtr, CmdStr, DSN, UserName, Password, ResultPtr [, AttribPtr, ErrorMsgPtr, SQLStatePtr, ErrorCodePtr, ReFormat, TransObj, FormatBitField, dbType])
Parameters: |
ErrPtr
Required. Pointer to an error. Always valid on completion. Set to 0 if the command succeeds.
CmdStr
Required. The SQL command to send to the database
DSN
Required. The name of the ODBC database in which to execute the command.
UserName
Required. The user name in the database for authentication. A null provided in this field will be passed to the database as a null string.
Password
Required. The password in the database for authentication. A null provided in this field will be passed to the database as a null string.
ResultPtr
Required. A pointer to the ODBC result data being passed back as the result of the query.
AttribPtr
Optional. A pointer to the ODBC attribute array being passed back from the result of the query. no default:
ErrorMsgPtr
Optional. A pointer to the ODBC error message being passed back. Will contain invalid if the command succeeds. no default:
SQLStatePtr
Optional. A pointer to the ODBC error state being passed back. Will contain invalid if the command succeeds. no default:
ErrorCodePtr
Optional. A pointer to ODBC error code being passed back. Will contain invalid if the command succeeds. no default:
ReFormat
Optional. A flag which, if set to true, causes the result set from the query to be reformatted from a Result[Column][Row] to Result[Row][Column]. This is potentially useful for reformatting multi-record "Select" queries to match your application requirements. no default:
TransObj
Optional. An transaction object (as returned from the "Transaction()" function) to execute this query within. If a transaction is opened on this DSN and this value is not set, then the query will wait until the transaction has completed before being executed. If set, the query will be executed after all other outstanding ExecuteQuery() functions for the transaction on the DSN have executed. no default:
FormatBitField
Optional. Bitfield indicating whether values coming back from the query will be converted to their corresponding VTScada data types. Can be set on a type by type basis according to the following flags: (no default)
Value | Meaning
0 | Convert numerics
1 | Convert dates
2 | Convert times
3 | Convert timestamps
dbTyp
Optional numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.
This module MUST be called as a subroutine in a script. This function acts as a shell to launch a query within the DSN within the ODBCManager library. Upon completion of the execution of the function, the query is still active. Completed execution of the query is indicated by a valid value set in the variable pointed to by parameter "ErrPtr". For this reason the variable referenced by "ErrPtr" MUST be invalidated before calling the function.

Numeric values retrieved from an ODBC data source are restricted to double precision floating point values. There is no support for receiving full-precision 64-bit integers.

Example

Init [
  If 1 Wait Execution;
  [
    ErrPtr = Invalid();
    \ODBCManager\ExecuteQuery(&Err, "Select ID, TimeStamp, Data1 From
     Log_Table Order By TimeStamp", "MAIN LOGGER", User, Pass)
  ]
]

WaitExecution [
  If Err DisplayError;
  If !Err DisplayData;
]


ExecuteQueryCached

(ODBC Manager Library)

Description: | Called to send an SQL data modification command to the server. This module will cache the query locally if it fails and send it to the database after the next successful transaction with the db. This module was designed to be used for logging values that cannot be lost.
Returns: | 0 upon query execution starting. See the following comments.
Usage: | Script Only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.ExecuteQueryCached(ErrPtr, CmdStr, DSN, UserName, Password[, BatchSize])
Parameters: |
ErrPtr
Required. Pointer to an error. Always valid on completion. Set to 0 if the command succeeds.
CmdStr
Required. The SQL command to send to the database
DSN
Required. The name of the ODBC database in which to execute the command.
UserName
Required. The user name in the database for authentication. A null provided in this field will be passed to the database as a null string.
Password
Required. The password in the database for authentication. A null provided in this field will be passed to the database as a null string.
BatchSize
Optional. The number of array entries to send in one batch no default. Returns 0 upon query execution starting. See the following comments.
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.
This module MUST be called as a subroutine in a script. Completed execution of the query is indicated by a valid value set in the variable pointed to by parameter "ErrPtr". For this reason the variable referenced by "ErrPtr" MUST be invalidated before calling the function.

Example:

InsertRecord [
  If 1 NextRecord;
  [
    Names  = New(4);
    Types  = New(4);
    Values = New(4);
    Names[0] = "RecordName";
    Names[1] = "TextVal";
    Names[2] = "NumberVal";
    Names[3] = "BoolVal";
    Types[0] = \ODBCManager\#SQL_VARCHAR;
    Types[1] = \ODBCManager\#SQL_VARCHAR;
    Types[2] = \ODBCManager\#SQL_NUMERIC;
    Types[3] = \ODBCManager\#SQL_BINARY;
    Values[0] = "rec1";
    Values[1] = "string1";
    Values[2] = 11;
    Values[3] = 1;
    Query = \ODBCManager.BuildInsert("TestTable", Names, Values, Types,
                                     \ODBCManager\#dbType_MSAccess);
    Err    = Invalid;
    Result = Invalid;
    Attrib = Invalid;
    ErrorMsg = Invalid;
    SQLState = Invalid;
    ErrorCode = Invalid;
    \ODBCManager.ExecuteQueryCached(&Err, Query, Conn1DSN, Invalid, Invalid);
  ]
]
NextRecord [ ...


Exp

(Engine-Level Function)

Description: | Returns the natural antilogarithm of a numeric expression.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | Ln | Log | Pow
Format: | Exp(X)
Parameters: |
X
Required. Any numeric expression. The value must not be negative or the result will be invalid.
Comments: The function raises the constant e to the power of the parameter X. It is the complement of the Ln function.

Example:

  A = Ln(78);
  B = Exp(A);

In this example, B will be equal to 78.


ExportKey

(Engine-Level Function)

Description: | The ExportKey function exports a cryptographic key or a key pair from a CSP in a secure manner as a Key BLOB. It is the VTScada analog of the Crypto API ExportKey call.
Returns: | Text
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | DeriveKey | Decrypt | Encrypt | GenerateKey | GetCryptoProvider | GetKeyParam | ImportKey | SetKeyParam
Format: | ExportKey(Key, BlobType [, EncryptKey, Flags, Error])
Parameters: |
Key
Required. The handle to the key which is to be exported.
BlobType
Required. A parameter specifying the type of key BLOB to be exported. Values are defined in WinCrypt.h
EncryptKey
Required. An optional parameter containing a Key handle for a key to be used to encrypt the exported key so that it may only be encrypted by the destination user. If omitted or invalid, then the value NULL is used.
Flags
Required. An optional parameter specifying the flags to be passed to CryptExportKey. If omitted or invalid then the value 0 is used. Flags values are defined in WinCrypt.h.
Error
Required. An optional variable in which the error code for the function is returned. It has the following meaning:
Error | Meaning
0 | Key successfully exported.
1 | Key or BlobType parameters invalid.
x | Any other value is an error from CryptExportKey.
Comments:

The exported key is returned as a text string. If an error occurs, the return value is invalid.
EncryptKey is not required if BlobType is PUBLICKEYBLOB.

Does not support CNG (Cryptography New Generation).

Example:

[
  PubKey1;
  Constant PUBLICKEYBLOB = 0x6;
]
Init [
  If 1 Main;
  [
    { Export the public key }
    PubKey1 = ExportKey(Key1, PUBLICKEYBLOB);
  ]
]


F Functions

The sections that follow identify all VTScada functions beginning with "F".


Fail

(Modem Manager)

Description: | This subroutine advises the Modem Manager to abort and retry an established, outgoing call.
Returns | Invalid
Usage: | Script Only.
Related to: | FindModem
Format: | \ModemManager.Fail(Tag);
Parameters: |
Tag
Any text expression that identifies the tag that originally requested the call.
Comments: The call is treated as a fail connection attempt. This is usually called as the result of a driver deciding that the quality of the data connection is too poor and declares this connection to have failed. Since the connection succeeded by phone company standards, the call can be attempted again without delay.

Example:

...
    \ModemManager.Fail(ModemTag);
...


False

(Engine-Level Function)

Description: | For use in expressions that perform Boolean logic. Using "FALSE" will make your code easier to read than using "0".
Returns: | With no parameters, returns the value, 0. If given a parameter, this function will return a 1 or 0 depending on whether the parameter evaluates to FALSE or TRUE. Always returns 0 if the parameter is Invalid.
Usage: | Script or steady state.
Function Groups: | Logic Control
Related to: | True
Format: | False[(TestExpr)]
Parameters: |
TestExpr
Optional. Any expression that evaluates to a 1 or 0 value. If no parameter is provided, then there is no need to include the parentheses.
Comments:

This function exists to make your code more readable. It is equivalent to

PickValid(Cast(Parameter, 0) == 0, 0);

For compatibility with the VTScada style guide, use all caps (TRUE and FALSE) when used as a constant. Capitalize only the first letter when used as a function call: True(test expression) and False(test expression).

Examples:

Used as a function:

  If False(TestVariable); ...

Used as a constant:

   { Initialize error variable to FALSE }
  Error = FALSE;

Used as a function parameter:

   { Get list of immediate tag children }
  \GetTagList("MyParentTag", FALSE);


FFT

(Engine-Level Function)

Description: | Performs a fast Fourier transform between time and frequency domains.
Returns: | Numeric
Usage: | Script only.
Function Groups: | Generic Math
Related to: | ArrayOp1 | ArrayOp2
Format: | FFT(Array, N, Operation)
Parameters: |
Array
Required. The starting array element. Array may contain time domain samples, complex frequency samples, or amplitude/phase pair samples. Any data passed to FFT in Array will be overwritten by the resulting transform. Arrays may be copied using ArrayOp2 if it is necessary to retain an original. There must be at least N elements in Array (partial transforms are not possible).
N
Required. Any numeric expression giving the number of elements in Array to transform. N must be a positive power of 2 in the range 4 to 4096.
Operation
Required. Any numeric expression giving the type of transform as follows:
Operation | Transform Type
0 | Time samples to frequency complex
1 | Time samples to frequency amplitude/phase
2 | Time samples to frequency amplitude only
3 | Frequency complex to time samples
4 | Frequency amplitude/phase to time samples

Note that Operation 2 will set all phase elements to 0 to indicate a loss of phase information. This transform is not reversible because of this loss of phase information.

Comments:

This statement is useful for performing frequency analysis on analog signals (such as motor frequency). In the time domain equal sampling intervals are required, equal frequency spacing in the frequency domain is required. The order of the time domain samples is in chronological order.
The order of complex frequency data is...

real 0, real N/2, real 1, imaginary 1, real 2, imaginary 2, ..., real N/2-1, imaginary N/2-1

Real 0 is the average (D.C.) component in the signal. The second element, real N/2, is the last real component because real 0 and real N/2 are always real (no imaginary component). Real 1 is the real amplitude of the lowest frequency, and imaginary 1 is the imaginary amplitude of the lowest frequency. Real N/2-1 and imaginary N/2-1 are the real and imaginary components of the second highest frequency.

The order of amplitude/phase pairs in Array is:

amplitude 0, amplitude 1, ..., amplitude N/2, phase 1, phase 2, ..., phase N/2 - 1

Amplitude 0 is the average (D.C.) component in the signal. Amplitude 1 is the amplitude of the lowest frequency, amplitude N/2 is the amplitude of the highest frequency. Phase 1 is the phase angle (in radians) of the lowest frequency (the average doesn't have a phase, its frequency is 0). Phase N/2-1 is the phase angle of the second highest frequency.

Note that neither the average (D.C.) component nor the highest frequency have a phase angle or imaginary component. The highest frequency and the sampling is:

fc = 1/2Δ

Where fc is the critical (highest) frequency in Hertz, and Δ is the sampling interval in seconds. The lowest frequency, the number of samples, and the sampling interval are related by the following equation:

fL = 1/NΔ

Where fL is the lowest frequency in Hertz, N is the number of samples, and Δ is the sampling interval in seconds.

All other frequencies are multiplies of the lowest frequency fL.

Caution should be taken, as when VTScada executes a script, no other statements are updated. The FFT statement may take several seconds to execute, depending on the computer and the number of samples. The computation time goes up by N * log2N.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

  If 1 Main;
  [
    FFT(samples[0], 512, 1);
  ]

Before this statement executes, samples[0] to samples[511] contain the equally spaced time samples of a signal, which will be overwritten by their amplitude/phase transform. After this statement executes, samples[0] will contain the average (D.C.) component of the signal. Samples[1] is the amplitude of fL, the lowest frequency component. Samples[256] is the amplitude of fc, the highest frequency component. Samples[257] will be the phase angle (in radians) of fL. Samples[511] will be the phase angle of fc.


FileChooser

(System Library)

Description: | Provides an edit box for specifying a file name, along with a label and a browse button.
Returns: | Text
Usage: | Steady State only.
Function Groups: | File I/O, String and Buffer
Related to: | Edit|
Format: | System.FileChooser(X1, Y1, X2, Y2, Title, ButtonLabel, OutVar, ID, Trigger, View, Save, FilterPattern, FilterDesc, DialogTitle, ExtensionToUse, [DrawBevel, VertAlign, AlignTitle, BGColor, FGColor, FontParm, TitleBGColor, TitleFGColor, BevelColor, PlaceholderText])
Parameters: |
X1
Left or right side of area
Y1
Top or bottom of area
X2
Opposite side to X1
Y2
Opposite side to Y1
Title
Text. Any text expression to be used as a title for the field. Defaults to "" if invalid.
ButtonLabel
Required text. The label to use on the browse button. Defaults to "..." if invalid.
OutVar
Required text. A variable whose value is set by the edit field.
ID
Optional. Any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the edit field will display its current setting, but its value will not be able to be changed and it will appear grayed out. The default value is 1.
Trigger
Numeric. Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero: 1 if enter is pressed, 2 otherwise.

View

Numeric. Indicates how to display the edit field, as follows
View | Display Mode
0 | Invisible
1 | Normal (color scheme - no graying)
2 | Grayed-out (only if FocusID is 0)
3 | Non-grayed text on a shaded background

This parameter may be used to force an edit field with a FocusID of 0 to display normally, rather than allowing it to default to its grayed color. Note that if the FocusID is not 0, setting this value as 2 will not force the field to gray out.

The default value is 2 if FocusID is 0 and 1 otherwise.

Save
Save | Save Mode
0 | Open dialog
1 | Save dialog
-1 | Browse for folder
-2 | Browser for folder + add trailing "\"
FilterPattern
Required text. An array or a semicolon-separated list of wildcard file patterns for the types that will appear. Defaults to "" if invalid.
FilterDesc
Required text. An array or a semicolon-separated list of text values describing the corresponding FilterPatterns. Defaults to "" if invalid.
DialogTitle
Required text. The title to apply to the file dialog. Defaults to "" if invalid.
ExtensionToUse
Required text. For save dialogs (Save parameter == 1) the file extension to use if not specified by the user. Defaults to "" if invalid.
DrawBevel
OptionalBoolean. If TRUE, the bevel is drawn. The Default value is FALSE.
VertAlign
Optional. Any numeric expression that sets the vertical alignment of the edit field according to one of the following options
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
Optional Boolean. TRUE if title affects alignment
BGColor
Optional. Background color of the edit box
FGColor
Optional. Foreground color of the edit box
FontParm
Optional. Font value
TitleBGColor
Optional. Background color under title
TitleFGColor
Optional. Foreground (text) color for the title
BevelColor
Optional. Color of the bevel line
PlaceholderText
Optional. Text to display in place of invalid entry
Comments:

This module is a member of the System Library, and must therefore be prefaced by System. as shown in the "Format" section.

The height of the edit field is constant, with X1 and X2 defining its width, and Y1 and Y2 defining the boundaries in which it is to be confined vertically, which may or may not include the added height of a title and bevel, depending on the alignment used and if they exist.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  System.FileChooser(LHS, TOP, RHS, TOP,
                     GetPhrase("PathLabel"), GetPhrase("BrowseLabel"), FoundPath,
                     1 {ID}, EditTrig, 2, -1 {folder}, "", "", GetPhrase("SelectExistingAppsLabel"),
                     Invalid, FALSE, 0, TRUE);


FileDialogBox

(Engine-Level Function)

Description: | Displays a threaded system common file dialog box.
Returns: | Numeric (1 = failure, 0 = success) In addition, see the Result parameter.
Usage: | Script Only.
Function Groups: | File I/O, Graphics
Related to: | FontDialog | PrintDialogBox | Dir
Threaded: | Yes
Format: | FileDialogBox(Save, FilterPattern, FilterDesc, File, Directory, Title, Extension, Result)
Parameters: |
Save
Required. Any expression that evaluates to one of the following values
Save | Meaning
0 | indicates that an "Open" dialog box is desired
Non-zero (positive) | indicates that a "Save" dialog box is required
-1 | indicates that a "Browse for Folder" dialog is required

(please read Comments below if you require a "Browse for Folder" dialog).

FilterPattern
Required. Either a statically-declared array, or a semi-colon separated list of wildcard file patterns for the file types that will be offered to the user. Defaults to an empty string if invalid.
FilterDesc
Required. Either a statically-declared array, or a semi-colon separated list of text values that are the descriptions corresponding to the FilePattern values (e.g. "Text Files"). Defaults to an empty string if invalid.
File
Required. Any text expression giving the initial file name for the dialog box.
In any 'Save' mode, an initial directory may be included as part of the file name. If the path is valid, the Directory parameter will be ignored. A known path alias may be provided in the form, {KnownPathAlias}.
Defaults to "" if invalid.
Directory
Required. Any text expression giving the initial directory for the dialog box. A known path alias may be provided in the form, :{KnownPathAlias} . (A table of known path aliases is provided in the Reference chapter).
Defaults to "" if invalid. See comments for more detail.
Title
Required. Any text expression giving the title of the window containing the dialog box. Defaults to "" if invalid.
Extension
Required. Any text expression giving the default file extension to use if the user does not specify one. Defaults to "" if invalid.
Result
Required. A variable where the resulting file name, including its path, will be returned.
Comments: This statement displays a threaded system dialog box for opening or saving a file, depending on the value of the Save parameter, however, it does not actually perform the requested action, but simply displays the dialog. If successful, the Result parameter will be set to the full path and file name of the chosen file, or 0 if it fails or is canceled. It is the user's responsibility to act upon the value of Result and save or open the file by using such commands as FWrite or FRead.
In addition to the Result parameter, the function itself will return an error code to indicate whether the dialog was successfully opened. A "1" indicates failure to open while a "0" indicates success.
The Directory parameter is ignored for Open and Save operations if the File parameter contains a path. You can use this feature to define the initial directory, but return to the selected file if the user re-opens the dialog.

For example:

FileDialogBox(1, "", "", SelectedFile, InitialDirectory, ....);

SelectedFile can be initialized to "SomeFile.txt", in which case the InitialDirectory will be used. After the user has selected a file ("C:\AnotherFile.txt") , and reopens the dialog, then it will reopen to the path in SelectedFile. This avoids having to parse a user selection result (SelectedFile) into a filename and path to achieve the same effect.

For Save -1 (directory browser mode) the Directory parameter means something different. Directory defines the root of the selectable directories. For example, you can use this feature to restrict the user from selecting a directory outside their VTScada application folder. Passing the VTScada application path as Directory, means that operators would only be able to select that folder, or any sub-folders. This option can be used in conjunction with 'File' to restrict the selectable path and also have an initial selection.

If either the FilterPattern or FilterDesc parameters use dynamically allocated arrays (i.e. created using the New function), the dialog box will not open - these two parameters must use statically declared arrays. If using a single text value instead, you may specify as many wildcard patterns as needed by adding a semi-colon separator between each: "*.BMP;*.JPG;*.PNG;*.TIF".

If the Save parameter is a negative value, indicating that a "Browse for Folder" dialog is required, the Directory and Title parameters must be set. Title will be displayed above the tree view control in the dialog box. This string can be used to specify instructions to the user. Directory can either be a string containing the starting root directory to begin browsing, or a CSIDL value to specify a special folder (a CSIDL is a number, the definitions of which can be found in the Platform SDK). The remaining parameters may be set to any valid value, including empty strings ("").

FTP sites may not be browsed depending if the server is running an older Windows operating system.

Within an Anywhere Client session, this function does nothing.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  If ZButton(100, 176, 200, 146, "Browse", 1);
  [
    FileDialogBox(0 { An "Open File" dialog box },
                  "*.*" { All files is only option },
                  \GetPhrase("AllFilesLabel") { Option label },
                  "APPROOT.SRC" { Default file name },
                  "C:\VTScada\APP" { Default path },
                  \GetPhrase("FindLabel") { Window title },
                  ".SRC" { Default extension },
                  selectedApp { Chosen file });
  ]

When the button is pressed a file dialog box that shows all files (and directories) in the C:\VTScada\App folder will open. When a file is chosen, its path and name will be stored in selectedApp.


FileFind

(Engine-Level Function)

Description: | Performs a recursive search down through the directory tree structure and returns an array of matching file names.
Returns: | Array
Usage: | Script only.
Function Groups: | File I/O
Related to: | FindFile | Dir | DriveInfo | FileDialogBox | GetFileAttribs
Format: | FileFind(Path, Attributes, Option)
Parameters: | .
Path
Required. Any text expression that indicates the full path name where the search begins. This may include a wildcard spec, such as "*.DAT". The search progresses recursively down each sub-directory (depth-first).
Attributes
Required. Any numeric expression that gives the attributes to match on each file listed (files not matching these attributes won't be listed).
Attribute | Bit No. | Meaning
0 | - | Files without attributes
8 | 3 | All files (regardless of attributes)

Alternatively, the parameter may be constructed by adding together the numbers from the table below:

Attribute | Bit No. | Meaning
1 | 0 | Read only
2 | 1 | Hidden
4 | 2 | System
16 | 4 | Sub-directory
32 | 5 | Archive
Option
Required. Any numeric expression giving the type of text information to generate. The options are chosen by adding together all of the option numbers required.
All information is placed in a single text string, separated by spaces. It will be stored in an element of the array that is created. The information is written from left to right, with lowest option numbers first.
Option | Bit No. | Generates
1 | 0 | Short file name
2 | 1 | Full path and file name
4 | 2 | File size
8 | 3 | File last modified date (in text)
16 | 4 | File last modified time (in text)
32 | 5 | File attributes (ADHRS)
64 | 6 | File last modified date/time combination (in secs since Jan. 1, 1970)
128 | 7 | File creation date (in text)
256 | 8 | File creation time (in text)
512 | 9 | File creation date/time combination (in secs since Jan. 1, 1970)

The attributes returned as a result of bit 5 being set are printed as the capital letters A (archive), D (subdirectory), H (hidden), R (read-only), and S (system).

Comments:

This function returns an array of text values. As the function does a recursive search through the directory tree, the contents of each sub-directory are added to the array in reverse-alphabetic order before the function moves on to the next directory.
Each text value contains the information specified by Option for each file which matches both Path and Attributes. If no files are found, the return value will be set to invalid. Notice that the only difference between this function and the Dir function is that Dir searches in the immediate directory only, while this function looks down through the whole directory tree.

(See: Bitwise Parameters & Operations)

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  If 1 Main;
  [
    FileData = FileFind("C:\VTScada\App\*.DAT", 8, 8);
  ]

This statement will find all files with the extension "*.DAT" in the given directory regardless of their attributes. The array fileData will contain each file's full path and file name as well as its size and date.


FileRootModule

(Engine-Level Function)

Description: | Parses the document file that contains the given module to find the root module in that file. Returns the module value of the root module.
Returns: | Pointer
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module, File I/O
Related to: | SystemSelf
Format: | FileRootModule(Module)
Parameters: |
Module
Required. Any expression for the module.
Comments: The returned module value from this statement may be the parent or some ancestor of Module.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

    ModRoot = FileRootModule(Self());

This function returns a pointer to the root module of the current module.


FileSize

(Engine-Level Function)

Description: | Returns the size of a disk file in bytes.
Returns: | Numeric
Usage: | Script only.
Function Groups: | File I/O
Related to: | FRead | FWrite | GetStreamLength
Format: | FileSize(FileName)
Parameters: |
FileName
Required. Any text expression that gives the path, file name, and extension of the file. A Known Path Aliases for File-Related Functions may be provided in the form, :{KnownPathAlias}.
Comments: This function returns the size of the file in bytes. If the return value is invalid, the file could not be found.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  If ! Valid(size);
  [
    Size = FileSize("C:\Log\Samples.DAT")
  ]

Size is set to the size in bytes of the file indicated.


FileStream

(Engine-Level Function)

Description: | Returns a stream attached to a disk file or printer, and is suitable for use in SWrite.
Returns: | Stream
Usage: | Script Only.
Function Groups: | File I/O, Stream and Socket
Related to: | BlockWrite | BuffStream | ClientSocket | CloseStream | GetStreamLength | PipeStream | PrintDialogBox | ServerSocket | SRead | StreamEnd | SWrite
Format: | FileStream(FileName [, PrintFlag, CompletionVar, Flags])
Parameters: |
FileName
Required. Any text specification for a file or printer SWrite. A known path alias may be provided in the form, :{KnownPathAlias}.
PrintFlag
An optional parameter that is any logical expression and must be set to true (non-0) if the stream is printer-based so that special handling and error checking for printer output will be provided.

If this parameter is omitted, the default value of false (0) is used (i.e. a file-based stream is assumed).
CompletionVar
An optional variable that will be initially set Invalid. When the stream is closed it will be incrementally set to an integer in the range 0 to 100. This integer indicates the percentage completion of writing the session-aware stream contents to the VIC.

When the value of this variable is set to exactly 100, the stream has been completely written to the VIC file system. This can be used by the programmer to indicate the progress in writing large files to a VIC over a relatively slow communication link.

This variable can also be provided on non-session-aware FileStreams, where it will remain untouched by any file operations. Its presence does not mark the FileStream as being session-aware.
Flags
An optional parameter that may take one of three values.
If absent or Invalid, the FileStream will not be session-aware (i.e. all operations will be on the local file system).
If valid, the FileStream is session-aware, and if the file does not exist on the VIC file system, a zero-length file will be created and opened for read-write access.
If the file on the VIC exists, setting this parameter to zero will cause it to be initially opened for read-only access. Read-write access is only obtained when you make the first write to the stream.
If the file exists on the VIC, setting Flags to 1 will cause the file to be opened for read-write access, and truncated to zero length.
Comments: If the file designated by FileName does not exist, it will be created when it is written to (by SWrite/BlockWrite for example). The file pointer returned by the function will still be valid. If the file exists but has its read-only attribute set, the stream may only be read from, not written to.
If you want to be certain that the file exists, then manually use FWrite(File, 2, 0, ""); before opening the stream with FileStream.
If the PrintFlag parameter is set, even though a printer is not being used (i.e. FileName indicates a certain file), it will not have any effect overall except that it may impose a slight performance penalty.
Session-aware Streams:

Session-aware streams can be defined simply as streams opened or created by a FileStream statement that can refer to files system resources on the server, or on a VIC. In the latter case, the stream is referred to as a "remote" stream. Not all FileStream statements are session-aware. As the programmer, you must decide whether to make a FileStream session-aware.
To make a FileStream session-aware, you supply the additional, optional parameters, CompletionVar and Flags, to indicate that the stream is a session-aware stream. Without these additional parameters (or with the additional parameters set to certain values), the FileStream is treated just as a regular FileStream.
Having marked a FileStream statement as session-aware, the FileStream will be a remote stream only if it is running in the context of a VIC session. In other words, the module instance running the FileStream statement has an ultimate caller module instance that is the root instance for a VIC session.

A VIC session differs from a DisplayManager session. A DisplayManager session may be running in the singleton server session, or it may be running in one of N VIC sessions. The concept of VIC session is something that the VTScada engine understands, whereas the concept of a DisplayManager session is something that the VTScada layer understands.

When a FileStream is remote, the FileName parameter is provided relative to the VIC. For example, "C:\Temp\XX.txt" refers to a file on the C drive of the VIC. The FileDialogBox statement may be used to allow the VIC user to identify a resource accessible to the VIC, and provide a suitable text string to pump into FileStream's FileName parameter.

If used in an Anywhere Client, calling FileStream with the Flags set so as to be session-aware causes FileStream to do nothing and return Invalid.

Blocking: It is necessary to block the execution of VTScada script code at clearly defined points when using a remote FileStream. Blocking script execution blocks only the executing interpreter thread (i.e. it does not cause VTScada to stop executing statements in other threads).
The points at which VTScada script code execution will be blocked are...
  • During execution of a FileStream statement that refers to a remote stream. Execution will block until the VIC can tell the server whether the specified FileName parameter is legal, and if it is, the size of the file. This allows a GetStreamLength statement immediately following the FileStream statement to return the size without blocking. It also allows the engine to initialize a cache for the remote stream.
  • On the first write to the remote stream, if the remote stream is open as read-only. This can be a result of a number of statements, such as BlockWrite or SWrite. The block is obtained simply to learn whether read-write access can be obtained, and get a "write-lock" on the remote stream. This lock prevents other processes from accessing the stream content until VTScada closes it.
  • On all writes to a remote stream when the write overwrites the content in the remote stream, and the remote stream content for that file offset is not cached locally on the server. This is not strictly necessary, and is a product of the current caching algorithm that operates on fixed size blocks. If this becomes restrictive, a smarter caching algorithm can avoid this block.
  • On all reads to a remote stream when the content for the specified file offset is not cached locally on the server.
File Content Transfer: Remote stream content is cached on the server in fixed size blocks. Only those blocks that have been read or written are held on the server. Any changed blocks are only written to the remote stream when the stream is closed, either explicitly with a CloseStream statement, or implicitly by invalidating the last reference to the remote stream.
The engine does not block interpreter threads while this operation is performed.
All transfer to the VIC is performed on the "low-priority" channel within the VIC connection to the server. Graphics, user-input and control actions are all performed using the "high-priority" channel. Presently the only other transfer that takes place over the low-priority channel is image transfer. This means that operator actions and graphical representations are largely unaffected by stream transfer operations. Because only one channel is used for stream transfer, all stream transactions are serialized within that channel, meaning that an attempt to open a stream that the server has just closed will be queued behind the last write to the stream, ensuring that you cannot read stale data from the remote stream.
The CompletionVar parameter to the session-aware FileStream statement may be used to monitor the progress of large transfers, and provide operator feedback. It is important to remember that because graphics use a higher priority channel than the stream, the operator will be able to see any progress notification that you display.
Caching Considerations: The present implementation of remote streams uses a fixed block size cache (4 kb) on the server. If an attempt is made either to write a partial file block that is not in the server cache, but is existent in the remote stream. Or, to read from a block that is not in the server cache but is existent in the remote stream, the calling script code will be blocked until the server has recovered the stream data for that block from the VIC. Dependent upon the connection speed and quality, this may take a long time (in computer terms).
Writes of an entire block that is not cached does not cause the server to read data from the VIC.
After a block has been cached on the server, it is not re-read from the VIC.
This algorithm provides a balance between complexity and performance, principally designed to give good performance when creating a file from scratch and writing it to the VIC, while providing some caching benefit for random access use of the remote stream.

Example:

  If ! Valid(stream);
  [
    Stream = FileStream("C:\Recipe\Glue.DAT");
  ]

This statement will set Stream to the stream of the file indicated.

  If MatchKeys(1, "p");
  [
    PrintStream = FileStream("\\ServerName\PName", 1);
  ]

This will cause PrintStream to be created as a printer based stream pointing to the printer called PName on the server called ServerName.


Filter

(Engine-Level Function)

Description: | Sets the value of one array element to invalid if the corresponding value in another array element is invalid.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Array
Related to: | ArrayOp1 | ArrayOp2 | FiltHigh | FiltLow
Format: | Filter(Array1Elem, Array2Elem, N)
Parameters: |
Array1Elem
Required. Any array element giving the starting point for the array conversion in the destination array. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
Array2Elem
Required. Any array element giving the starting point in the reference array (this array is not altered in any way). The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to process starting at the element given by the first parameters. If this parameter is greater than either dimension of the arrays, the number of points used will be the smaller array dimension.
Comments: This statement is useful together with either the FiltLow or FiltHigh statements which would typically be executed on the first array before Filter is executed.

Example:

Assume that there exists 2 arrays both of whom have subscripts starting at 0, such that x = { 1, 2, Invalid, 4 } and Y = { 2.3, Invalid, 2.4, Invalid }

  If ChangeArray;
  [
    Filter(x[0] { Start of array to be changed },
           y[0] { Start of reference array },
           4 { Number of elements to process });
    ChangeArray = 0;
  ]

If the variable changeArray is set to true, this will result in array y remaining unchanged and array x being changed to x = {1, Invalid, Invalid, Invalid }

Example 2:

 If Watch(1);
  [
    ArTest = new(3,3);
    ArTest2 = new(3,3);

    ArTest[0][0] = 1;
    ArTest[0][1] = 2;
    ArTest[0][2] = 3;
    ArTest[1][0] = 50;
    ArTest[1][1] = 60;
    ArTest[1][2] = 70;
    ArTest[2][0] = 900;
    ArTest[2][1] = 910;
    ArTest[2][2] = 920;

    ArTest2[0][0] = 1;
    ArTest2[0][2] = 3;
    ArTest2[1][0] = 50;

    Filter(ArTest[1], ArTest2[1], 3);
]

After filtering, ArTest will look like:


FiltHigh

(Engine-Level Function)

Description: | Sets the values in an array sub-range that fall above a specified upper limit to a new value.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Array
Related to: | ArrayOp1 | ArrayOp2 | Filter | FiltLow
Format: | FiltHigh(ArrayElem, N, Limit, Value)
Parameters: |
ArrayElem
Required. Any array element giving the starting point in the array for the search. The subscript for the array may be any numeric expression. If processing a multidimensional, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to use, starting at the element given by the first parameter. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Limit
Required. Any numeric expression giving the upper cutoff value for the array elements. Any array elements in the range that are strictly greater than this value are set to the Value parameter.
Value
Required. Any numeric expression giving the new value to set the array elements that fall above the Limit parameter. The function still continues if this parameter is invalid, in which case the new values become invalid.
Comments: The statement is useful for setting array elements above a limit to a maximum value or to invalid.

Example:

Assume that there exists an array whose subscripts start at 0, such that x = { 2, 1, invalid, 10 }

  If ChangeArray;
  [
    FiltHigh(X[0] { Start of array },
             4 { Number of elements to process },
             2 { Max value in the array },
             Invalid { Default value if over the limit });
    ChangeArray = 0;
  ]

If the variable ChangeArray is set to true, x will be changed to x = {2, 1, Invalid, Invalid }


FiltLow

(Engine-Level Function)

Description: | Sets the values in an array sub-range that fall below a specified lower limit to a new value.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Array
Related to: | ArrayOp1 | ArrayOp2 | Filter | FiltHigh
Format: | FiltLow(ArrayElem, N, Limit, Value)
Parameters: |
ArrayElem
Required. Any array element giving the starting point in the array for the search. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to use, starting at the element given by the first parameter. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Limit
Required. Any numeric expression giving the lower cutoff value for the array elements. Any array elements in the range that are strictly less than this value are set to the Value parameter.
Value
Required. Any numeric expression giving the new value to set the array elements that fall below the Limit parameter. The function still continues if this parameter is invalid, in which case the new values become invalid.
Comments: The statement is useful for setting array elements below a limit to a minimum value or to invalid.

Example:

Assume that there exists an array whose subscripts start at 0, such that x = { 2, 1, Invalid, 10 }

  If changeArray;
  [
    FiltLow(X[0] { Start of array },
            4 { Number of elements to process },
            2 { Min value in the array },
            Invalid { Default value if under the limit });
    ChangeArray = 0;
  ]

If the variable ChangeArray is set to true, X will be changed to X = [2, Invalid, Invalid, 10 ]


FindAction

(Engine-Level Function)

Description: | Returns an action from the list of actions in a state.
Warning | This function should be used only by advanced programmers.
Returns: | Pointer
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, State
Related to: |
Format: | FindAction(Action, Mode)
Parameters: |
Action
Required. Any expression that gives a code value. If the code value represents a module and state, the first action will be returned.
If the code value represents an action or statement, the action returned will depend on Mode.
Mode
Required. Any numeric expression for the mode. The mode is described by the following table:
Value | Mode
-1 | Previous action
0 | Return Action parameter
1 | Next action

If Mode is 1, and Action is the last action in the state, or if Mode is -1, and Action is the first predicate in the state, the return value is invalid.

Comments: This function is used to step through the actions in a state. Seldom (if ever) used when adding features to modern VTScada applications.


FindCertificate

(Engine-Level Function)

Description: | Locates a certificate in a certificate store.
Returns: | Structure
Usage: | Script Only.
Function Groups: | Certificates
Related to: | AddCertificate | CheckCertificateChain | GetCertificateInfo | ListCertificates | MakeSelfSignedCertificate | RemoveCertificate | SetCertificateProperty
Format: | FindCertificate(MachineStore, StoreName, Thumbprint)
Parameters: |

MachineStore

Required Boolean. If TRUE (non-zero), attempts to find the certificate in a store in the Local Computer certificate hive. If FALSE (zero) attempts to find the certificate in a store in the Current User certificate hive.
StoreName
Required text. The name of the store in which to find the certificate.
Thumbprint
Required. A binary buffer holding the SHA1 thumbprint of the certificate to find.
Comments

This is a useful way of locating a certificate that corresponds to a thumbprint obtained earlier and obtaining a certificate structure for it.

Thumbprints are convenient, compact values that can be persisted and used again later.

Refer to ListCertificates for a description of the returned structure.

Example:

    CertificateInfo = FindCertificate(FALSE, "My", SavedThumbprint);

This will attempt to locate a certificate corresponding to SavedThumbprint in the current user’s Personal certificate store.


FindFile

Code level

You are advised not to use this function on network paths. Response time can be very slow.

Description: | Takes a file name a returns the full path of the a file by that name that exists in the "nearest" directory.
Returns: | Text
Usage: | Script Only.
Function Groups: | File I/O
Related to: | FileFind | Dir | DriveInfo | FileDialogBox | GetFileAttribs
Format: | \FindFile(File, ProtectedFile, StopOnFailure, Silent)
Parameters: |
File
Required text. The name of the file to search for. It may contain an absolute or relative path.
ProtectedFile
Optional Boolean. Set TRUE to indicate that the file must be verified. Defaults to FALSE.
StopOnFailure

Optional numeric. If ProtectedFile is TRUE, this sets the action to take if protected file can't be loaded.

Set to 1 to stop the application.
Set to 2 to stop the VAM.

Silent

Optional numeric. If ProtectedFile is TRUE, this can suppress file protection errors as follows:

Set to 1 to silence all errors.
Set to 2 to silence only 'missing file' errors.

Comments:

The nearest directory is the one which is the lowest index in the DirList array.

For relative file names, all the working copies will be searched first, followed by the Data directories.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

Init [
  If 1 Main;
  [
    BubbleImage = MakeBitmap(\FindFile("\Bitmaps\Tree.png"));
  ]
]

Main [
  Return(Self);
  GUIBitmap(20, 149, 119, 50,
            1, 1, 1, 1, 1 { Scaling              },
            0, 0          { Movement             },
            1, 0          { Visibility, Reserved },
            0, 0, 0       { Selectability        },
            BubbleImage);

]


FindModem

(Modem Manager)

Description | This subroutine returns a pointer to one of the Modem Manager's own internal modem objects. This pointer may then be used to access public, read-only properties for display purposes.
Usage | Script or Steady State
Related to: | Fail
Format | \ModemManager.FindModem(ModemName);
Parameters |
ModemName
Any text expression that identifies the required modem. This will be the name property of a modem tag.
Comments

FindModem will return an object pointer for a given modem tag name. This object refers to a Modem Manager internal object, which provides access to several read-only properties. These are:

Property | Description
Workstation | Name of the workstation where the modem exists
FriendlyName | Modem name as displayed in the Windows Control Panel's Phone and Modems option (or Modems option)
Failed | Refer to Call Progress and Error Codes. in the VTScada Programmer's Guide.
OffHook | TRUE while a call or call setup is in progress
Connecting | TRUE while call setup is in progress

Example:

Main [
  ModemObj = \ModemManager\FindModem(\UniqueID);
...


FindVariable

(Engine-Level Function)

Description: | Searches for a variable by text name and returns a value that is of the type 'Variable'.
Returns: | Varies
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | AddVariable | DeleteVariable | MakeNonShared | MakeNonPersistent | MakePersistent | MakeShared | SetDefault | SetVariableClass | SetVariableText | ListVars
Format: | FindVariable(Name, Module, Reserved, Global)
Parameters: |
Name
Required. Any text expression that gives the name of the variable.
Module
Required. Any expression for the module where the search begins.
Reserved n/a
Reserved for future use, set to 0.
Global
Required. Any logical expression. If true (non-0), the search will continue to parent objects if they exist and the variable isn't found. If false (0), only Module will be searched.
Comments:

The type of value this function returns (Variable) can be cast into text, which gives the name of the variable, or if the original variable is a Module, it can also be cast into the Module itself.

Note that it provides no way to retrieve the actual value stored in a variable that is not a Module.

The Variable type value can also be passed into the SetDefault, GetDefaultValue, orDeleteVariable functions as the Variable parameter

This function returns invalid if the variable is not found.

FindVariable can be used on the left side of an equals sign (=) to allow shared variables to be set when there are no instances of a module running.

Example:

  If ! Valid(Ptr);
  [
    Ptr = Launch(FindVariable("Grid", Self(), 0, 1 { Launchee }),
                 FindVariable("Draw", Self(), 0, 1 { Parent }),
                 FindVariable("Draw", Self(), 0, 1 { Caller }),
                 Xspace, YSpace { Parms });
  ]

This statement launches module Grid with its parameters xSpace and ySpace as if it were a child of module Draw and had been called by Draw. If Draw had been assigned an object pointer at the time it was called, the second and third FindVariable statements would be unnecessary.

  If Valid(CheckVar);
  [
    IfThen(!Valid(FindVariable(CheckVar { Var to look for },
                               Self() { Check this module },
                               0 { Reserved },
                               0 { Only this module })),
            Message = "Variable does not exist!");
  ]

This statement checks to see if a certain variable exists by looking for it by name in the current module only. If it does not exist, an error message is set.


FirstState

(Engine-Level Function)

Description: | Sets the first state in a module.
Warning | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, State
Related to: |
Format: | FirstState(State)
Parameters: |
State
Required. Any expression for the code value of the new first state.
Comments: Given that a module starts in its first state, this function will set which state within a module will considered to be first.
Seldom (if ever) used when adding features to modern VTScada applications.


FitOffset

(Engine-Level Function)

Description | Linear regression offset. This function returns the offset or Y intercept of the least square curve fit of data in a pair of arrays.
Returns | Numeric
Usage | Script or steady state.
Function Groups | Generic Math
Related to: | FitR2 | FitSlope
Format | FitOffset(XArrayElem, YArrayElem, N)
Parameters |
XArrayElem
Required. Any array element giving the starting point in the array of X coordinates of the input data set. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
YArrayElem
Required. Any array element giving the starting point in the array of Y coordinates of the input data set. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of data points to use from the arrays given by the first two parameters.
If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Comments

If an element of either array is invalid, then that X-Y pair is not included in the computation. If the number of valid data points is less than 2, the function returns an invalid value. Note that XarrayElem and YarrayElem are not necessarily the same array element number. This function is used in conjunction with the FitSlope function.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

Assume that 2 arrays exist such that X = {0, 1, 2, 3} and Y = {1, 3, 5, 7 }, and both arrays' subscripts start at 0

  Intercept = FitOffset(X[0] { Starting X element },
                        Y[0] { Starting Y element },
                        4 { Number of elements to process });

The variable intercept will be set to 1.


FitR2

(Engine-Level Function)

Description: | Returns the coefficient of determination (i.e. r2) for a linear curve fit. This number gives a measure of how accurate the curve fit is.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | FitOffset | FitSlope
Format: | FitR2(XarrayElem, YarrayElem, N)
Parameters: |
XArrayElem
Required. Any array element giving the starting point in the array of X coordinates of the input data set. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
YArrayElem
Required. Any array element giving the starting point in the array of Y coordinates of the input data set. The subscript for the array may be any numeric expression.
If processing a multidimensional, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of data points to use from the arrays given by the first two parameters.
If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Comments:

This function returns a number indicating how close a fit the data are to a line. If an element of either array is invalid, then that X-Y pair is not included in the computation. If the result is 0, there is no linear relationship at all between the array of X values and the array of Y values. If the result is 1, the fit is perfect. The result may be any value in the range of 0 to 1.
This function can be used in conjunction with the other linear regression functions.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

Assume that 2 arrays exist such that X = {0, 1, 2, 3} and Y = {1, 3, 5, 7 }, and both arrays' subscripts start at 0

  Determination = FitR2(X[0] { Starting X element },
                        Y[0] { Starting Y element },
                        4 { Number of elements to process });

The value of determination will be set to 1 (a perfect fit).


FitSlope

(Engine-Level Function)

Description: | Linear regression slope. This function returns the slope of the least square curve fit of data in a pair of arrays.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | FitOffset | FitSlope
Format: | FitSlope(XarrayElem, YarrayElem, N)
Parameters: |
XArrayElem
Required. Any array element giving the starting point in the array of X coordinates of the input data set. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
YArrayElem
Required. Any array element giving the starting point in the array of Y coordinates of the input data set. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of data points to use from the arrays given by the first two parameters.
If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Comments:

If an element of either array is invalid, then that X-Y pair is not included in the computation. If the number of valid data points is less than 2, the function returns an invalid value. Note that XArrayElem and YArrayElem are not necessarily the same array element number. This function is used in conjunction with the FitOffset function.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

Assume that 2 arrays exist such that X = {0, 1, 2, 3} and Y = {1, 3, 5, 7 }, and both arrays' subscripts start at 0.

  Slope = FitSlope(X[0] { Starting X element },
                   Y[0] { Starting Y element },
                   4 { Number of elements to process });

The variable slope will be set to 2.


Flush

(Engine-Level Function)

Description: | Pushes the data in all software caches associated with a FileStream directly to the physical media.
Returns: | Nothing (see parameters)
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | Diff | CloseStream
Threaded: | Yes
Format: | Flush(Stream, CompletionCounter, Success);
Parameters: |
Stream

Required FileStream. Any expression that resolves to the stream that is to be persisted to the physical media.

This must be a FileStream. Other stream types do nothing in response to a Flush call.

CompletionCounter
Required numeric. Any expression that resolves to a variable containing a numeric value or Invalid. If a numeric variable, the value will be incremented at the instant that Flush is called. It will then be decremented after the stream has been flushed. The same variable can be used to monitor any number of simultaneous, asynchronous Flush operations.
If this parameter is set to Invalid then the Flush operation will be performed synchronously and the function won't return until the stream is flushed.
Success
Required Boolean. Any expression that resolves to a variable containing a numeric value or Invalid. If a numeric value, that value will be set after the stream has been flushed to indicate the success of the operation. A value of TRUE (1) indicates success while FALSE (0) indicates failure. If set to invalid then the success of the operation is not reported.
Comments:

The operation is bound to the speed of the physical media and can be slow.

This function is used to ensure that all preceding operations on a FileStream have been completed on the physical media before the operation completes. All file operations in VTScada are subject to the mediation of the file cache (a part of the Operating System that serves to speed up file access) which can have a reliability cost when the cache or the media are disrupted.
This function allows the caller to momentarily opt out of the file cache, ensuring that a file is in the expected state while exposing the caller to the performance limitations of the physical device. As this can be a very slow operation it is performed asynchronously, with the caller being informed after the operation completes. Note that an asynchronous flush can be prevented by the CloseStream function if that results in the file being closed before the flush completes.

There are two types of asynchronous operation available, depending upon whether the CompletionCounter value has been set to a variable containing a valid or invalid value. If invalid, the thread upon which the call was made is blocked until the operation completes, but other threads are allowed to run.
CompletionCounter should not be set invalid if Flush is called in a CriticalSection as this will cause all threads to await the flush operation.
If CompletionCounter is set to a valid numeric value then the flush operation will occur independently of the calling thread, which will continue executing immediately. This mechanism is identical to that used by the Diff function, and the CompletionCounter parameters of the two operations can be shared.

If the Success parameter is provided and has not been set to 1 by the time the operation completes then it should be assumed that the file has not been persisted, and in fact may not be persist-able. This can happen if there is something wrong with the Stream parameter, or if either the OS file cache or the physical media are damaged. Flushing a file that has nothing to write will set this parameter to TRUE (1).

Example:

...
    IfThen(GetStreamLength(FStream) > 0 && True(Flushing),
           Flush(FStream, Invalid, Invalid);
    );


FlushCache

(ODBC Manager Library)

Description: | Forces a flush of a log file for a specified DSN.
Returns: | Numeric
Usage: | Script Only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.FlushCache(DSN, UserName, Password, ErrPtr)
Parameters: |
DSN
Required. The data source name of the ODBC database for which to flush the cache.
UserName
Required The user name in the database for authentication. A null provided in this field will be passed to the database as a null string.
Password
Required. The password in the database for authentication. A null provided in this field will be passed to the database as a null string.
ErrPtr
Required. Pointer to an error. Always valid on completion. Set to 0 if the command succeeds.
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.

Returns 0 on completion.


FocusID

(Engine-Level Function)

Description: | Returns the focus ID of the object in a window that has the input focus.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Window, Graphics, Keyboard
Related to: | NextFocusID
Format: | FocusID(Window[, Local])
Parameters: |
Window
Required. Any object value that will specify the instance of a window.
Local
Optional Boolean. If True then focus calls are module-specific (i.e. local to the module calling Focus.)
Comments:

If the window is inactive, this function will return the focus ID of the object that will receive the input focus when the window becomes active.

FocusID values have a valid range of 0 to 32767. Values outside this range are likely to cause the object to vanish.

Example:

  ZButton(10, 100, 110, 130, "OK", 1);
  If LocSwitch() == 4 { Left mouse button pressed };
  [
    IfThen(FocusID(Self()) != 1 { Focus leaves the OK button },
          NextFocusID(Self(), 1) { Return focus to OK button });
  ]

This set of statements ensures that after any input by the mouse (i.e. clicking of the left mouse button), the focus will return to the "OK" button.


Folder

(System Library)

Description: | Draws a tabbed folder dialog.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DialogInitPos
Format: | System.Folder(X1, Y1, X2, Y2, Labels, Selected)
Parameters: |
X1
Required. The coordinate of the left side of the folder.
Y1
Required. The coordinate of the bottom of the folder.
X2
Required. The coordinate of the right side of the folder.
Y2
Required. The coordinate of the top of the folder.
Labels
Required. A one dimensional array of labels to be assigned as the labels for each of the folder's tabs.
Selected
Required. The selected tab. Selected defaults to 0 (indicating the first tab).
TabHeight
Numeric feedback parameter, telling the caller the height of the tabs, or the total height when there are multiple rows of tabs.
Comments: This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section. If your application predates version 11.2, use the backslash notation rather than dot: \System\

Example:

Draws a folder with two tabs on the Overview page of an application.

[
  Title = "OverviewLabel";
  Color;
  ViewLabels;
  SelViewOptTab;
  TabHeight;
]
Init [ If 1 Main;
  [
    ViewLabels = new(2);
    ViewLabels[0] = \GetPhrase("LeftLabel");
    ViewLabels[1] = \GetPhrase("RightLabel");
    SelViewOptTab = 0;
  ]
]

Main [
  Return(Self);
  \System\Folder(100, 600, 500, 100,
                 ViewLabels, SelViewOptTab, TabHeight);
]


Font

(Engine-Level Function)

Description: | Returns a font value.
Returns: | Font
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | FontDialog | GUIText | ZText
Format: | Font(Name, CharSet, Height, Rotation, Weight, Decoration, Fixed)
Parameters: |
Name
Required. Any text expression that gives the name of the font. This must be the same as the Microsoft Windows™ name for the font. For example, "ARIAL".
CharSet (Deprecated)

Deprecated. Use DEFAULT_CHARSET in all cases. Other values, used by legacy applications, are now ignored.

Height
Required. Any numeric expression giving the height of the font in points.
Rotation
Required. Any numeric expression giving the rotation of each character in degrees.
Weight
Required. Any numeric expression giving the weight of the font. Larger numbers give a more bold appearance. The range is 0 to 9.
Decoration

Required bit-wise flag

(See: Bitwise Parameters & Operations)

0 | Normal
0b01 | Italic
0b10 | Underline
charFixed
Required. Any logical expression. If true (non-0), all of the characters used by the font will be the same width and height, that of the largest character. If false (0), and the font is a proportional or a true type font, then the characters may have different sizes.
Comments:

This function is for use in layered graphics statements that display text. A good idea is to use variables for font parameters in the layered graphics statements. If it is desired to change the font later, it need only be changed at one place - where the assignment is made to the variable. This also promotes a consistent use of fonts.

Parameters are suggestions. Substitutions will be made if the parameters describe a font that cannot be found.
Supported font types include TRUEType, OpenType and PostScript CFF.

Example:

  InputFont = Font("ARIAL" { Font name },
                   0 { Character set },
                   14 { Height in points },
                   0 { Rotation },
                   5 { Weight - somewhat bold },
                   0 { Not italic },
                   0 { Non-fixed });


FontDialog

(Engine-Level Function)

Description: | Displays a threaded system common font dialog box.
Returns: | Error code
Usage: | Script Only.
Function Groups: | Graphics
Related to: | Font | PrintDialogBox
Threaded: | Yes
Format: | FontDialog(Name, CharSet, Height, Rotation, Weight, Italic, Fixed [, Display, Result])
Parameters: |
Name
Required. Any text expression which gives the name of the font. This must be the same as the Microsoft Windows™ name for the font. For example, "MS Sans Serif".
CharSet
Required. Any numeric expression giving the Font Character Sets for this font.
If you are uncertain as to a valid value, set CharSet to 0, thereby obtaining English characters.
The keyword, DEFAULT_CHARSET may be used, auto-selecting the character set based on the configured Windows locale. OEM_CHARSET will do the same, but will use the DOS equivalent.
Height
Required. Any numeric expression giving the height of the font in points.
Rotation
Required. Any numeric expression giving the rotation of each character in degrees.
Weight
Required. Any numeric expression giving the weight of the font. Larger numbers give a more bold appearance. The range is 0 to 9.
Italic
Required. Any logical expression. If true (non-0), the italicized version of the font is used. If false (0), the normal version is used.
Fixed
Required. Any logical expression. If true (non-0), all of the characters used by the font will be the same width and height, that of the largest character. If false (0), and the font is a proportional or a true type font they may have different sized characters.
Display
An optional parameter that gives a list of fonts to display. Display can be set to one of the following values.
Display | Font List
0 | All fonts
1 | Screen fonts only
2 | Printer fonts only

If the value is invalid, all fonts will be displayed. If out of range, then the function call is not valid.

Result
An optional parameter that is a variable whose value will be set to 1 if the OK button on the font dialog is clicked, and 0 if the Cancel button on the font dialog is clicked.
Comments:

The first seven parameters are originally read in to set the default values for the dialog box and if they are VTScada variables, they will be set to the attributes for the font chosen by the user in the dialog box.
In addition to the Result parameter, the function itself will return an error code to indicate whether the dialog was successfully opened. A "1" indicates failure to open while a "0" indicates success.

Within an Anywhere Client session, this function does nothing.

Example:

[
  Title = "OverviewLabel";
  Color;

  NewFont;
  Name      = "Century Gothic";
  CharSet   = 0;
  Ht        = 14;
  Rotate    = 0;
  Wt        = 5;
  Italic    = 1;
  CharFixed = 1;
  WasSet    = 0;
]

Main [
  { Display the chosen font }
  ZText(100, 100, Concat("A ", Name, " Font"), 12, NewFont);
  NewFont = Font(Name, CharSet, Ht, Rotate, Wt, Italic, CharFixed);
  { Set the font }
  If ZButton(200, 130, 300, 110, "Set Font", 1) && Valid(WasSet);
  [
    WasSet = Invalid;
    FontDialog(Name { Font name },
               CharSet { Character set },
               Wt { Height in points },
               Rotate { Rotation in degrees },
               Wt { Weight 0 - 10 },
               Italic { Italics flag },
               CharFixed { Fixed pitch flag },
               0 { All font options },
               WasSet { Set when dlg closes });
  ]
]


ForceEvent

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Forces the editor to perform an action based on the information provided.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Editor
Related to: | WinEditCtrl
Format: | ForceEvent(EditorValue, EventType, Parm1, Parm2, Parm3)
Parameters: |
EditorValue
Required. An editor value that has been created by MakeEditor.
EventType
Required. Any numeric expression that gives the type of event for the editor to perform.
EventType | Type of event
-1 | Tab
0 | Cursor left
1 | Cursor right
2 | Cursor up
3 | Cursor down
4 | Enter
5 | Delete next character
6 | Delete previous character
7 | Move cursor to beginning of line
8 | Move cursor to end of line
9 | Move cursor up one page
10 | Move cursor down one page
11 | Move cursor to start of the Editor
12 | Move cursor to end of the Editor
13 | Move the selection block left one character
14 | Move the selection block right one character
15 | Move the selection block up one line
16 | Move the selection block down one line
17 | Cut the selection block from the editor to the clipboard
18 | Copy the selection block from the editor to the clipboard
19 | Insert the text from the clipboard into the editor
20 | Toggle block line, column selection mode
21 | Turn the selection block off
22 | Delete the current line
23 | Scroll down one line
24 | Scroll up one line
25 | Move the editor to the given byte offset
26 | Move cursor to the given pixel coordinates if they lie within the editor's defined region
27 | Insert the supplied text at the current cursor position
Parm1
Required. An expression that has a different meaning based on the event type being forced.
EventType | Parm1 Meaning | Parm1 Value
0 - 24 | No meaning | 0
25 | Offset to which to move the cursor | Byte offset
26 | Location to which to move the cursor | X pixel location
27 | Text to insert | Text string
Parm2
Required. An expression that has a different meaning based on the event type being forced.
EventType | Parm2 Meaning | Parm2 Value
0 - 24 | No meaning | 0
25 | Highlight characters at new location 1 |
?? | Don't select any characters 0 |
26 | Location to which to move the cursor | Y pixel location
27 | No meaning | 0
Parm3
Required. An expression that has a different meaning based on the event type being forced.
EventType | Parm3 Meaning | Parm3 Value
0 - 24 | No meaning | 0
25 | Characters to highlight | Number of chars
26, 27 | No meaning | 0


ForceServers

(RPC Manager Library)

Description: | Sets the servership of an application service to a specific state.
Returns: | Invalid
Usage: | Script Only. (Subroutine call)
Function Groups: | Network
Related to: | GetServersListed
Format: | \RPCManager.ForceServers(Service, ServerStates, [OptGUID])
Parameters: |
Service
Name by which the service is known.
ServerStates
A 2D array of servers and their states.
OptGUID
The GUID of the application in which the service instance is located. Optional, the default is the application to which the caller belongs.
Comments: The server states are defined by a 2D array, with row[0] listing the servers and row[1] listing the states.
The servers MUST appear in the same order as returned from GetServersListed for the service. The state values are zero (undetermined), #RPCClient or #RPCServer. These values then get reflected in the RPCStatus to that service.

Related information:

RPC Manager Service


ForceState

(Engine-Level Function)

Description: | Sets the next state to start when the action script completes.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Logic Control, State
Related to: | FirstState
Format: | ForceState(State)
Parameters: |
State
Required. Any text expression giving the name of the state to start upon completion of the script.
Comments:

A script may contain more than one ForceState statement, but it is only the last one executed that sets the state to which the module will switch.

This statement does not act as an immediate exit point from the script - the script will still run in its entirety. That said, the first ForceState will cause the current state to end and any reference to objects in that state will fail.
If the script trigger statement did not specify a destination state to transfer to, this function will stop the current state as if one had been specified.

IF statements are the standard tool for specifying the next state. Use ForceState rarely and only when significant effort would be required otherwise to control the flow from one state to another.

Example:

  If TimeOut(1, 1) Main;
  [
    IfThen(Level < 10, ForceState("Exit"));
  ]

After one second this statement will cause a state transfer to Main. However, if level is less than 10 at that time, the next state will become Exit rather than Main.


FormalParms

(Engine-Level Function)

Description: | Returns the number of formal parameters declared in a module.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | NParm | NumParms | Parameter
Format: | FormalParms(Module)
Parameters: |
Module
Required. Any expression that returns an object or module type value.
Comments: This function's result may seem obvious, but this function can help automate some of the work in building a parameterized module, just in case the number of parameters declared in a module is changed.

Example:

<
TinyModule
(
  A;
  B;
)
[
  NumParms;
]
Main [
  NumParms = FormalParms(Self());
]
>

The variable NumParms will have a value of 2.


Format

(Engine-Level Function)

Description: | Returns a text string corresponding to numbers in a specified format.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | BuffWrite | CommaFormat | FWrite | Output | Print | PrintLine
Format: | Format(Width, Precision, Value)
Parameters: |
Width
Required. Any numeric expression giving the minimum number of characters to use. If fewer characters are required to produce the output, the area is filled with blank spaces on the left to make up the required number of characters. This is useful for aligning numbers on the right.

If more characters are required than the Width parameter specifies, the extra characters are extended to the right. By making Width 0, the output will be aligned on the left.

If the Width parameter is greater than or equal to 100, the format of the floating point number used is in the most compact form which may be in exponential form if the exponent is less than -4 or is greater than the specified Precision parameter.

The actual width used in this mode is 100 less than the specified Width. Trailing 0s are not displayed in this mode. Values for Width outside the range of 0 to 255 inclusive are invalid.
Precision
Required. Any numeric expression giving the precision of the output (with rounding). It gives the number of digits to appear after the decimal point, if Width is less than 100, or the maximum number of significant digits to appear, if Width is greater than or equal to 100.

Values for Precision outside the range of 0 to 255 inclusive are invalid.
Value
Required. Any numeric parameter giving the number to be formatted.
Comments: This function is useful in conjunction with the Print statement to produce numbers in a printed report. Note that if a text expression is expected as an argument by any VTScada function, and a numeric argument is used, VTScada performs an automatic Format on the value.

Example:

  Number = 123.5692;
  TextVal = Format(7 { Minimum number of characters },
                   2 { Number of digits after decimal point },
                   Number);

The variable TextVal will be equal to " 123.57"


FormatBatchQuery

(ODBC Manager Library)

Description: | When given an array of SQL queries, this module will re-format them into a single query, suitable for a batch call to the specified database.
Returns: | Text
Usage: | Script Only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager.FormatBatchQuery( dbType, QueryArray, StartingElement, NumberOfElements)
Parameters: |
dbType
Required numeric value, indicating the type of this DB connection.
DBType | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase
QueryArray
Required. SQL queries to be executed in a batch.
StartingElement
Required. Sets the element in the array at which to begin.
NumberOfElements
Required. Sets the number of elements of the array that should be processed.
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager, as shown in "Format" above.
The return value is the batch query as a text string. If the database type is unknown, this function will return only one element from the array, as indicated by the StartingElement. Batch queries cannot be created without knowing which separator string to use.

The only way to ensure that a long running (or faulty) query does terminate is to set appropriate values for both the parameters ExecutionTimeout and UseDriverTimeout when running AddConnection. Modules executing queries are designed to be run as launched modules and will remain active until complete.


FormatInteger

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Given a numeric value, returns that value converted to Hex, Octal or Binary as specified.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Math - Generic Functions, String and Buffer
Related to: | Format | FormatNumber
Format: | \FormatInteger(Value, OutputFormat, Size, LeadingZeros)
Parameters: |
Value
Required. Any numeric expression giving the original decimal value to be converted.
OutputFormat
Required. The format to convert to. Constants are used as follows: (Note the leading backslash in each case.)

\#HEX

\#OCTAL

\#BINARY
Size
Required. The size of the result to return. May be one of:

\#DATA_BYTE

\#DATA_WORD

\#DATA_DWORD

\#DATA_QWORD
LeadingZeros
Optional. A Boolean. If TRUE, the output will be padded with leading zeros according to the size specified. Defaults to FALSE.
Comments: Must be preceded by a backslash. Useful for formatting a numeric value into one of the three available representations.

Example:

  Result = \FormatInteger(25, \#OCTAL, \#DATA_WORD, 0);

The variable Result will be "31".


FormatNumber

(System Library)

Description: | Given a numeric value, returns a compactly formatted version of this number containing at least the specified number of significant digits.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Math - Rounding Functions
Related to: | Format | FormatInteger
Format: | System.FormatNumber(Value, Digits[, IntegerFlag])
Parameters: |
Value
Required. Any numeric expression giving the original value to be formatted.
Digits
Required. Any numeric expression giving the number of significant digits to be returned from Value.
IntegerFlag
Optional. Any Boolean expression. If FALSE, integers are returned without modification. Defaults to FALSE.
Comments Must be preceded by System. This is primarily a significant digits function, but will also return an exponential value if the number of leading or trailing zeros is greater than three.
If the number is a non-integer, its significant digits are limited (to four digits by default). If the number can be shown with fewer characters using scientific notation, that notation is used. Integers are left untouched unless otherwise directed by an optional parameter.

Example:

  Number = 0.0054321;
  Result = System.FormatNumber(Number,2);

The variable result will be 0.00054

  Number = 0.000054321;
  Result = System.FormatNumber(Number,2);

The variable result will be 5.4e-005

  Number = 0.00455321;
  Result = System.FormatNumber(Number,2);

The variable result will be 0.0046

  Number = 0.00454321;
  Result = System.FormatNumber(Number,2);

The variable result will be 0.0045

  Number = 12345.54321;
  Result = System.FormatNumber(Number,3);

The variable result will be 12300

  Number = 12345;
  Result = System.FormatNumber(Number,2);

The variable result will be 12345

  Number = 12345;
  Result = System.FormatNumber(Number,2, 1);

The variable result will be 12000


FRead

(Engine-Level Function)

Description: | Reads values from a formatted file and returns the number not read.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | File I/O, String and Buffer
Related to: | BuffRead | BuffWrite | FileSize | FWrite | SRead | SWrite
Format: | FRead([N], File, Offset, Format, V1[, V2, V3, ...])
Parameters: |
File
Any text expression specifying the path, file name, and extension to read. A known path alias may be provided in the form, :{KnownPathAlias}.
Offset
Any numeric expression giving the starting file position for the read in bytes, starting at 0.
Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be read.
This format is similar, but not identical, to the C language format string for the scanf function, whereby each of the % format specifications assigns a value to one of the Vn parameters in the statement in the order in which each appears in the list.
Note that like a standard text string, these format specifiers must also be enclosed by double quotes. If a format specification appears for which there are no remaining V parameters, the format specification value is read and discarded.

For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[*][width]type

Where…

%

Is a mandatory character

*

The optional asterisk causes the read to occur as per the format specification, but suppresses any assignment to the Vn parameters.

width

Width is optional, specifying the maximum number of characters to read.

type

The specifications for type are listed in the following table:

Format strings are case insensitive. Additionally, specifying a character for a type that is not in this list results in all the characters following the % up to that point to be read exactly as they appear in the Format string and discarded.

Type | Meaning
Nb | Binary format, where n is a number indicating the type of value (see below)
c | Single ASCII character (byte)
d | Signed decimal 64-bit integer
e | Signed exponential
f | Signed floating point
g | e or f formats
i | Signed decimal integer
l | Line of characters terminated by a carriage return, line feed, or both
n | Present offset in the buffer
o | Signed octal, 32-bit default*
s | Text string
t | Counted string
u | Unsigned decimal 64-bit integer
x | Signed hex integer using "abcdef", 32-bit default*
znnn | Escape character where nnn is the 3-digit ASCII code

%x and %o will treat values as 32-bit integers by default unless the %ll modifier is used. %llx and %llo will read values in 64-bit.

for %u, when reading an unsigned 64bit integer greater than 9223372036854775807 (the largest signed 64bit integer), the value will be read in as the bit-equivalent signed 64bit integer. (eg. 9223372036854775808 is read in as -9223372036854775808.)

nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.

n value | Type
0 | Byte
1 | Short integer (2 bytes, low byte first)
2 | Long integer (4 bytes, low bytes first)
3 | IEEE single precision float (4 bytes)
4 | <obsolete>
5 | IEEE double precision float (8 bytes)
6 | <obsolete>
7 | Binary unsigned short (2 bytes, low byte first)
8 | Unsigned 32-bit integer
9 | 64-bit FileTime. This reads or writes a 64 bit time value in the Microsoft FileTime format. When reading, the value is converted from the FileTime epoch and units (100 nanosecond intervals since Jan 1, 1601) to the VTS epoch and units (seconds since 1/1/1970) any times earlier than this will result in a value of 0. When writing, the value is converted from the VTS epoch and units to the FileTime epoch and units.

c, ASCII character type: Unlike BuffWrite this type deals with characters in a string; each character being equal to one byte. Unlike the %s option, which reads only up to the first white-space character, the %c option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, a single character is read.

d, Signed decimal integer

e, Signed exponential

f, Signed floating point

g, e or f formats

i, Signed decimal integer type: This option normally reads a decimal integer; however, if a leading "0b" is encountered, the number will be interpreted as binary. If a leading "0" (zero only) is encountered, the number will be interpreted as octal. If a leading "0x" is encountered, the number will be interpreted as hexadecimal. For decimal, values will be read as 64-bit integers, but hex, octal and binary will be treated as 32-bit integers unless the %lli modifier is used, which will cause the %i format to treat hex, octal and binary as 64-bit.

l, Line of characters: This option reads a line of characters terminated by a carriage return, a line feed, or both (in either order). The carriage return and line feed will be discarded, and the next character read will be the first character on the next line. The maximum number of characters read is 2GiB (2^30 bytes) or less if the width option is used.

n, Buffer offset: This option does not read a value, but returns the present offset in Buffer and can be useful in subsequent reads.

o, Unsigned Octal

s, Text string type: Text in the string is read up until a white-space character is encountered, or the specified width has been read, whichever is smaller. Square brackets enclosing a character, group of characters, or a caret and a group of characters used in the format string reads strings not delimited by spaces. This is a substitute for the %s format specification. The input is read up to the first character that does not appear inside the square brackets (note that this is case-sensitive). A dash may be used to specify a range of characters. For example, the following format specifier:

% [A-Fa-f]

will read a string up to the first which is not an A, B, C, D, E, or F both upper and lower case.

t, Counted string type A counted string is encoded as a sequence of UTF-8 characters without a null terminator and preceded by the length in bytes.

The length in bytes is encoded as Int32, i.e. a "%2b". A value of −1 is used to indicate an invalid string, a value of 0 indicates a null ("") string.

Do not apply width or precision modifiers to a "%t" counted string.

The caret symbol ^. If the first character inside the square brackets is a caret ( ^ ), the read progresses up to, but not including, the first character that appears inside the square brackets:

%[^X-Z]

This would read a string up to, but not including, the first X, Y or Z (upper-case only); if the string were terminated by an X, the next character read would be that X. Inside the square brackets, the backslash is used as an escape character - any character following a backslash (such as a caret, dash, or backslash) is taken as that character without special meaning. For example:

%[^X-Z\^]

would behave as described previously, except that the string would now be read up to but not including the first X, Y, Z, or ^.

Because format specifications for the Vn parameters are indicated by a percentage sign, to read (and discard) an actual percentage sign as part of the text string, precede it with a backslash character (i.e. \%). Also, since the backslash character is used in this manner, as well as with special control characters such as line feed, carriage return and form feed, to read and discard a backslash, use two backslash characters (i.e. \\).

x, Hexadecimal characters: the %x option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, it will continue reading all bytes that can be recognized as hexadecimal characters. For example, given the string "…= 3D", %[^=]=%2x would read the hedadecimal value, 3D (decimal value, 61).

znnn, Escape characters: This specifies an escape character that will be thrown away when read, where nnn is a 3-digit number giving the ASCII character code of the escape character. This option is generally used as the sole format specifier that reads an entire string, spaces included, discarding every single occurrence of an escape character, or the first occurrence of every pair of escape characters. For example, if the string to be read looked like:

abXc dXXfghiXXXjXXXXkl mX Xn o

and the format specifier indicated that the ASCII code for 'X' (88) was to be the escape code:

%25z088

then the variable that this was read into would contain:

abc dXfghiXjXXkl m n o

Notice that for each occurrence of X, the character immediately following it is saved, even if it is itself an escape character. Then the next occurrence of the escape character is discarded, with the character following it being saved, regardless of what it is, and so on. The width field specifies the maximum number of bytes to place in the output string; if this number is smaller than the input string (less the offending escape characters), the string will be truncated. If no width is specified, a single character will be read.

Control characters: In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result. Please note that the letters must be lower case.

Code | Meaning
\b | Backspace
\f | Form Feed
\n | Line Feed
\r | Carriage Return
\t | Horizontal Tab
\v | Vertical Tab

In addition to the predefined codes, an alternate form may be used:

\nnn: where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

V1, V2, …
Required. Are the variables to be set in the form described by the Format parameter. Expressions are not allowed. Each of the Vn parameters is set in the order in which each appears in the parameter list. V1 has the format given by the first % sequence in the Format parameter, V2 has the second, and so on.
Comments

In early versions of VTS (WEB), there was a numeric leading parameter, N. This should not be included in any new code.

Data exchange between many file formats is possible if the file formats are known. The return value is optional and is the number of Vn parameters NOT read. This can be used as an error flag.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  If ! Valid(err)
  [
    Err = FRead("G:\RECIPES\GLUE.DAT" { File to read from },
                0 { Starting point },
                "%f%f%n" { Format },
                CompoundA, Resin, Offset { Parameters });
  ]

This reads two ASCII format floating-point numbers, starting at the beginning of G:\RECIPES\GLUE.DAT and places them in compoundA and resin, respectively. After the read is complete, the ending file position is stored in offset. If the read were successful, err is 0. Otherwise it is the number of items which were not read.


FWrite

(Engine-Level Function)

Description: | Writes text or binary data to a file and may also be used to create or delete a file. It returns the number of data items not written.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | File I/O, String and Buffer
Related to: | BuffRead | BuffWrite | FileSize | Format | FRead | Print | PrintLine | Redirect | Save
Format: | FWrite([N, ] FileSpec, Mode, Position, Format, V1[, V2, V3, ...])
Parameters: |
FileSpec

Required. Specifies any output file or printer as the destination to which to write. A known path alias may be provided in the form, :{KnownPathAlias}.

When specifying a printer, FileSpec will accept any of the following:

  • Local Printer:
  • Port name (including virtual ports) with or without a trailing colon (e.g. DEF or DEF:. COM1 or COM1:; USB001 or USB001:; etc.)
  • Windows printer share (e.g. "XYZ Laser Printer")
  • Windows share name (if the printer is shared) (e.g. "XYZLaser")
  • Local or Remote Printer:
  • UNC share name (which includes the host and share name (e.g. "\\localhost\XYlaser" or "\\lab1\NetPrinter")

If FileSpec is Invalid, FWrite will do nothing and execution will continue with the next statement.

Mode
Required. Any numeric expression giving the method of opening the file as shown: (further detail follows the table)
Mode | Method of opening
0 | Overwrite old data at specified position (other data unaffected)
1 | Clear existing data before using file (all data lost)
2 | Append data to end of file (other data unaffected)
3 | Delete file (all data lost)
4 | Open specifically for printer output
5 | Print mode, DC-based

If the file does not exist, it will be created if a mode of 0, 1, or 2 is used.
In the case of Mode 2, the Position parameter is ignored. If a position past the end of file is specified, the file will be extended to include the new information. If the file is extended, any information not specified by the Fwrite (such as a gap between the old end of file and the present Fwrite position) will be a string of unknown, random characters (bytes).
In the case of Mode 3, the remaining parameters in Fwrite are ignored, but must be present and valid.
In the case of Mode 4, special handling and error checking for printer output will be provided.

Position
Required. Any numeric expression giving the byte offset (number of characters) from the start of the file, where data is to be written.
This parameter is ignored for Modes 1 - 3 but must be a valid value for all modes. It must be greater than or equal to 0. The start of the file is at Position 0.
Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be written. This format is similar, but not identical, to the C language format string for the printf function, whereby each of the Vn parameters in the statement is assigned to a % format specification in the order in which each appears in the list.

Note that like a standard text string, these format specifiers must also be enclosed by double quotes.

If a format specification appears for which there are no remaining V parameters, the format specification characters themselves are output to the stream exactly as they appear in the Format.

For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[-][+][SPACE][#][width][.precision]type

where

% (percent sign) is mandatory;

- (minus sign) (optional) causes the data to be left justified within the field (for binary types b and ASCII character types c, this option is ignored);

+ (plus sign) (optional) causes positive numbers to be prefaced with a + sign (negative numbers are unaffected). This allows easy alignment of positive and negative numbers in a printed column of numbers. For binary types b and non-numerical types, this option is ignored;

space represents the single space character, and is similar to the [ + ] option but places a single space rather than a plus sign in front of positive numbers (negative numbers are still unaffected). This allows alignment of a column of numbers without having to show all signs. For binary types b and non-numerical types, this option is ignored;

# (hash mark) When used with the o , x , or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.

width is a number that specifies the minimum number of characters to output. Numbers that require more characters than specified by the width value are truncated on output. If the number of characters in the number or string is less than width, blanks will be added to the left or right, depending upon whether the output is left or right justified (i.e. whether the [ - ] option has been specified) until the width is reached. For binary types b and ASCII character types c, this option is ignored;

precision has a different meaning for each of the type options as follows:

  • Integer types d, l, u, o, x, and X precision specifies the minimum number of digits to output. If the number contains fewer digits, leading zeroes will be added to the left of the number. If precision is 0, omitted, or if the decimal point appears without a number following it, the precision defaults to 1. The number is not truncated.
  • Floating point types e and E precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision in this case is 6. If the precision is 0 or if the decimal point appears without a number following it, no decimal point appears in the output.
  • Floating point type f precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision is 0. If the precision is explicitly 0, no decimal point is output. If a decimal point is output, at least one digit will be placed before the decimal point.
  • Floating point types g and G precision specifies the maximum number of significant digits to be output. If no precision is specified, all significant digits are written.
  • String type s precision specifies the maximum number of characters of the string to be output. If the string contains more characters than specified by the precision, the string is truncated and only the first characters are written. If the precision is not specified, all of the string characters are output.
  • Byte type c The precision option is ignored.
  • Binary type b The precision option is ignored.

type is mandatory. The type specification must be one of those listed below.

Note: The case of the letter is important. Specifying a character for the type that is not in this list will result in all the characters following the % up to that point to be output exactly as they appear in the Format string.

Type | Meaning
nb | Binary format; where n is a number indicating the type of value (see below).
c | Single character (byte values from 0 to 255)
d | Signed decimal 64-bit integer, 64-bit output by default
e | Signed exponential; exponent key is "e".
E | Signed exponential; exponent key is "E".
f | Signed floating point.
g | e or f format, whichever is shorter.
G | E or f format, whichever is shorter.
h | Handle to a window.
i | Signed decimal 64-bit integer, 64-bit output by default
o | Unsigned octal integer. Default 32-bit integer. Use %llo to output 64-bit value.
p | Pointer to a buffer.
s | Text string.
t | Writes a utf-8 string as used by OPC UA binary TCP: a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string
u | Unsigned decimal 64-bit integer, 64-bit output by default
x | Unsigned hex integer using "abcdef". Default 32-bit integer. (See following note.)
X | Unsigned hex integer using "ABCDEF". Default 32-bit integer. (See following note.)

When writing negative values using either x or X format codes, the output will use a minimum of 32 bits because that is the smallest possible size to display the full information. Defining a format string such as "%4X" will not reduce this to 16 bit output for negative values. To output 64-bit values, use the modifier ll. %llx and %llX output 64-bit values.

nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.

n | Value Type
0 | Byte, unsigned
1 | Signed short integer (2 bytes)
2 | Signed long integer (4 bytes)
3 | IEEE single precision float (4 bytes)
4 | <obsolete>
5 | IEEE double precision float (8 bytes)
6 | <obsolete>
7 | Unsigned short integer (2 bytes)
8 | Unsigned long integer (4 bytes)
9 | Writes a time in Microsoft FILETIME format, which contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).
10 | Outputs signed 64-bit integers in binary form.

Note: Other options such as width and precision do not apply to the b type.

c, Byte type: This type is not representative of a single character in a string, but rather, represents single bytes. Input values (the Vn parameter to which this format specification applies) must be integers in the range of 0 to 255. Strings are not acceptable input values. Note that the %c format specifier behaves differently when used in an output statement such as BuffWrite than when used in an input statement, such as BuffRead. Some UTF-8 characters can require multiple bytes. Values from 0-127 are consistent between the traditional ASCII encoding and the UTF-8 encoding.

d, Signed decimal 64-bit integer:

e, Signed exponential: Exponent key is "e"

E, Signed exponential: Exponent key is "E"

f, Signed floating point

g, e or f formats: Whichever is shorter

G, E or F formats: Whichever is shorter

h, Window handle type: This type is used for building structures to be handed to DLLs and should be used by advanced users only.

p, Buffer pointer type: This type is also used for building structures to be handed to DLLs and should be used by advanced users only.

s, Text string type:

t, Writes a utf-8 string as used by OPC UA binary TCP:
a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string

u, Unsigned decimal 64-bit integer,

x, Unsigned hex integer using "abcdef": 32-bit value by default. Use modifier %llx for 64-bit value output.

X, Unsigned hex integer using "ABCDEF": 32-bit value by default. Use modifier %llX for 64-bit value output.

SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Plain text Text in the Format parameter is written exactly as it appears, with three exceptions:

  • Percentage sign (%) Because format specifications for the Vn parameters are indicated by a percentage sign, to include an actual percentage sign as part of the Format parameter, precede it with a backslash character (i.e. \%).
  • Backslash character (\) Because this is used to indicate special control characters such as line feed, carriage return, and form feed, to write a backslash as part of the Format parameter, use two backslash characters (i.e. \\).
  • Quotation marks (") The entire test string is delimited by quotation marks, so to include a set of quotation marks as part of the Format parameter, use a set of quotations marks (i.e. "").

Control characters In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result (notice that the letters must be lower case):

Code | Meaning
\b | Backspace
\f | Form feed
\n | Line feed
\r | Carriage return
\t | Horizontal tab
\v | Vertical tab

\nnn In addition to the above predefined codes, \nnn may be used, where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

znnn Escape character where nnn is the 3-digit ASCII code
For example: SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Offset is any numeric expression giving the starting buffer position in bytes for the write, starting at 0.

V1, V2, …
Required. Are any expressions giving the values to be output in the form described by the Format parameter. Each of the Vn parameters is evaluated and written in the order in which each appears in the parameter list. The way in which they are formatted is dictated by the % format specifications.
V1 is formatted by the first % sequence in the Format parameter, V2 by the second, and so on. If there are more V parameters than % sequences in the Format string, the remainder are ignored. If there are fewer V parameters than % sequences in the Format string, the remaining % sequences are written literally without any translation.
Comments:

In early versions of VTS (WEB), there was a numeric leading parameter, N. This should not be included in any new code.

You cannot write to a read-only file. You may use GetFileAttribs and SetFileAttribs to get/set the read-only attribute.
If one of the values to be written is outside of the range of the type indicated by the format specifier, a 0 is written. If the value to be written is invalid, nothing is written for most format specifiers, except for %nb, which will write a 0 in the place of the invalid. Invalidity of the output values does not preclude execution of this function.

This function returns the number of Vn parameters not written to the file. A return value of zero indicates success. Variables that contain invalid values that were not written due to their invalidity do not increment this count. An invalid return value indicates an error with one of the parameters. For Mode 3, a 0 indicates success and a 1 (true) indicates a problem deleting the file.

FWrite cannot be used to open COM 1 or COM 2 for direct writing, however, FWrite can connect to a printer on either COM1 or COM2.
All print functions are compatible with the values returned in either of the first two parameters of the PrintDialogBox function.

As of version 12.0, VTScada expects all strings to be encoded using UTF-8.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

If TimeToWrite;
[
  FWrite("ASCII.DAT" { File to write to },
         1 { Clear data  in file },
         0 { Starting point },
         "A=%d\r\nB=%3.2d\r\nC=%6.2f\r\n%8.3s\r\n%c"
         { Format string },
         100.8, 2, 2/3, "finished", 33
         { Values to be written });
  TimeToWrite = 0;
]

If the variable TimeToWrite is true, the FWrite statement would produce a file called ASCII.DAT with five lines of text as follows:

A=100
B= 02
C=  0.67
     fin
!


G Functions

The sections that follow identify all VTScada functions beginning with "G".


GenerateHMAC

(Engine-Level Function)

Description: | Calculates the hash-based message authentication code (HMAC) for a given key and input message. Supports incremental HMAC generation.
Returns: | Text
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | CryptRandom
Format: | GenerateHMAC(Algorithm, Key, Message)
Parameters: |
Algorithm

Required text. The hash algorithm to use. Any of the Microsoft CNG hashing algorithms may be used, including "SHA1", "SHA256", "SHA384", "SHA512" and others. A list is available at https://msdn.microsoft.com/en-us/library/windows/desktop/aa375534(v=vs.85).aspx

Key
Required text. The text string key to use for the HMAC.
Message
Required text. The text string to use as the input message
HashHandle

Optional. If the parameter is Invalid or omitted, GenerateHMAC simply generates the HMAC for the supplied buffer.

If the parameter is present, it must be a variable that will be set to a hash handle holding the current hash value. This can then be passed in as the 4th parameter to a further call to GenerateHMAC to add the contents of another buffer to the HMAC

Comments HMAC stands for keyed-Hash Message Authentication Code.

Example:

  CurrentHMAC = Invalid;
  GenerateHMAC("SHA256", SigningKey, FirstBuffer, CurrentHMAC);
  GenerateHMAC("SHA256", "", FirstBuffer, CurrentHMAC);
  FinalHMAC = GenerateHMAC("SHA256", "", Invalid, CurrentHMAC);

Note that the first 3 parameters must be valid. In this example, SigningKey is a text string used to "seed" the HMAC. To continue an incremental HMAC, the Key parameter must be an empty string to indicate that the omission of a signing key is intentional. Passing Invalid for the Message (3rd) parameter completes the HMAC and returns the generated HMAC. Completing the HMAC invalidates the incremental HMAC value.


GenerateKey

(Engine-Level Function)

Description: | The GenerateKey function generates a random cryptographic session key or a public/private key pair. A handle to the key or key pair is returned. This handle can then be used as needed with any CryptoAPI function requiring a key handle. It is the VTScada analog of the CryptoAPI’s CryptGenKey call.
Returns: | Handle
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | DeriveKey | Decrypt | Encrypt | ExportKey | GenerateKey| GetKeyParam | ImportKey | SetKeyParam | Data Encryption and Decryption
Format: | GenerateKey(CSPHandle, AlgID [, Flags, Error])
Parameters: |
CSPHandle
Required. The handle of a CSP (cryptographic service provider) to use to generate the key.
AlgID
Required. Identifies the algorithm for which the key is to be generated. Values for this parameter vary depending on the CSP used and are defined in WinCrypt.h
Flags
An optional parameter specifying the flags to be passed to CryptGenKey. If omitted or invalid then the value 0 is used.
Error
An optional variable in which the error code for the function is returned. It can have the following values.
Error | Definition
0 | Key successfully generated.
1 | CSPHandle or AlgID parameters invalid.
x | Any other value is an error from CryptGenKey.
Comments:

The return value for this function is a handle to the Key. If an error occurs, then the return value is invalid. A key has a value type of 37. If cast to text, then the hexadecimal value of the algorithm ID will be returned.

Does not support CNG (Cryptography New Generation).

Example:

[
  Key1;
  Key2;
  Constant CALG_DH_EPHEM = 0xAA02;
  Constant KEY_SIZE = 512;
  Constant CRYPT_EXPORTABLE = 0x00000001;
]
Init [
  If 1 Main;
  [
    { Make a key }
    Key1 = GenerateKey(CSP, CALG_DH_EPHEM,
                        KEY_SIZE << 16 || CRYPT_EXPORTABLE );
  ]
]


GenerateSignature

(Engine-Level Function)

Description: | Generates a digital signature of a handle returned from Hash().
Returns: | Text
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | CheckSignature | Hash
Format: | GenerateSignature(HashObj [, Key, PaddingType, PadHashAlgorithm, SaltLength)
Parameters: |
HashObj

Required. Handle returned from a call to Hash()

Key
Optional. CNG (Cryptography New Generation) only. The cryptographic key to be used to sign the data. This must be an asymmetric private key.
PaddingType

Optional integer. Can be one of the following values:

Value~Meaning

0~No padding is to added to the plaintext data before signing.

1~Padding is added to the data before signing in accordance with the RSASSA-PKCS1-v1_5 scheme.

2~Padding is added to the data before signing in accordance with the RSASSA-PSS scheme.

PadHashAlgorithm

Optional text value. The algorithm to be used for padding the data. The hash is then signed.
SaltLength
Optional integer. Only required for RSASSA-PSS padding. This is the length of the salt used by that scheme.
Comments Using an asymmetric key for signing is quite expensive compared to an HMAC with a symmetric key. For this reason, the data itself is not signed, but hashed and then the hash signed. This is much more efficient.

Examples

<
{========================== GenerateSignatureSample ==========================}
{ Sample code using GenerateSignature().                                      }
{=============================================================================}
GenerateSignatureSample
(
  Message                     { Message to sign                               };
  pPublicKeyBlob              { Output, set to exported public key blob       };
)
[
  Protected Constant CALG_RSA_SIGN = 0x2400  { Key type                       };
  Protected Constant PROV_RSA_AES  = 24      { Enhanced RSA/AES provider      };
  Protected Constant KEY_SIZE      = 2048    { 2048 bit keys                  };
  Protected Constant PUBLICKEYBLOB = 6       { PUBLICKEYBLOB                  };
  Protected Constant CRYPT_VERIFYCONTEXT = 0xF0000000 { CRYPT_VERIFYCONTEXT   };

  Protected CSP               { Cryptographic context                         };
  Protected HashObj           { Intermediate handle returned from Hash()      };
  Protected Key               { Handle to signing key pair                    };
  Protected Signature         { RSASSA-PKCS1-v1_5 signature                   };
]

Sign [
  If 1;
  [
    { Get cryptographic context }
    CSP = GetCryptoProvider(PROV_RSA_AES, Invalid, Invalid, CRYPT_VERIFYCONTEXT);

    { Generate a RSA key pair for signing }
    Key = GenerateKey(CSP, CALG_RSA_SIGN, (KEY_SIZE << 16));

    { Export the public key }
    *pPublicKeyBlob = ExportKey(Key, PUBLICKEYBLOB);

    { Compute a SHA-256 hash of the message }
    Hash(Message, 2 {SHA-256}, Invalid, HashObj, CSP);

    { Generate RSASSA-PKCS1-v1_5 signature }
    Signature = GenerateSignature(HashObj);

    Return(Signature);
  ]
]

{ End of GenerateSignatureSample }
>

  Hash(HeaderBuffer, 2, Invalid, HashHandle);   { Hash the header }
  Hash(PayloadBuffer, 2, Invalid, HashHandle);  { then the payload }
  Signature = GenerateSignature(HashHandle,             { Hash to sign }
                                Certificate.PrivateKey, { Private key to use }
                                2,                      { Use PSS padding }
                                "SHA256",               { Padding algorithm }
                                32);                    { PSS salt length }


Get

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Reads an array of historical data from a file (written by Save or SaveHistory) and returns the relative file position of the file entry following the last one read, or an error code.
Returns: | Array or Error code
Usage: | Script Only.
Function Groups: | File I/O, Log
Related to: | | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords | GetHistory | GetLogInfo | Save | SaveHistory | TGet
Format: | Get(ArrayElem, N, File, FieldNum, StartDate, StartTime, TPP, Mode [, StaleTime, PathPrefix])
Parameters: |
ArrayElem
Required. Any array element giving the starting point in the array in which data read from the file will be stored. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array entries to use. If this value is greater than the dimension of the array, then the array dimension is used for N.

If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
File
Required. Any text expression giving the file name for the historical data file. The file extension should not be added to the name since the default of ".DAT" is automatically added.

If the file name is prefixed with a period, the path will be to the directory that the module is contained in.
FieldNum
Required. Any numeric expression giving the field number to be read from the file. The value number for the actual data starts at 0 and corresponds to the columns specified in Save or SaveHistory.
It is also possible to retrieve time data associated with each record by setting this parameter to a negative value.
Time options are:
FieldNum | Time Option
-1 | Time of day only
-2 | Date only
-3 | Time since January 1, 1970

It is possible to retrieve more than one field in a single Get statement. To do this, pass an array of values in as the FieldNum parameter

StartDate
Required. Any numeric expression for the date (expressed as the number of days since January 1, 1970) to search for in the file as the starting date for the data.
If less than 0, this indicates the relative file position to read rather than the date. A -1 indicates the last entry in the file, a -2 the second last, and so on.
If more points are requested than exist, Invalid values will be retrieved. For example, if this parameter is -20, and there are only 5 data points, the resultant array will contain 15 Invalid values followed by 5 valid values.
Note: If the Save was used with a non-negative Buffers parameter, the last entry in the file will be an Invalid value - the last valid entry will be indicated by -2, the second last by -3 and so on.
StartTime
Required. Any numeric expression giving the time of day (in number of seconds since midnight) on StartDate to search for in the file as the starting time for the data. This may be greater than one day. It may also be negative, where data will start the previous day at (86400 - StartTime) seconds after midnight.
If StartDate is less than 0, StartTime is ignored.
TPP
Required. Any numeric expression giving the time span in seconds for each array entry. Each array element will contain the data that corresponds exactly to this time period, which corresponds to 0 or more data points in the file.
If TPP is positive and FieldNum selects a text value, the first entry which falls in a time is read and Mode is ignored.
If TPP is equal to 0, the data is read from the file and placed in the array on a one-to-one basis. If TPP is less than 0, the data is read on a one-to-one basis from the StartDate and StartTime for (negative) TPP seconds - TPP places an upper limit on the time span to read.
In both of these cases the Mode parameter is ignored.
Mode
Required. Any numeric expression giving the method of handling the data. If TPP is greater than 0, the values that fall in each time span will be represented as follows:
Mode | Representation
0 | Time weighted average
1 | Minimum in range
2 | Maximum in range
3 | Change in value over the range
4 | Value at start of range
5 | Time of minimum in range (in seconds since Jan. 1, 1970)
6 | Time of maximum in range (in seconds since Jan. 1, 1970)
7 | Count the total number of zero to non-zero transitions within each TPP period.
8 | Totalizes, for each TPP, the amount of time when the value is non-zero (Invalid is counted as zero).
9 | Totalizes, for each TPP, the arithmetic sum of the recorded values.
10 | Interpolates between values.
11 | Totalizes, allowing for value rollover.

In the case of modes 5 and 6, FieldNum should still be set to indicate the field number on which the mode is to act. The return values will be times indicating the minimum or maximum in that field for each time span.

In the case of mode 10, the result interpolates between values. This is primarily intended for the case where there are several TPPs per recorded value, as the time-weighted average returns a stepped curve in this case. The interpolate mode returns a smoother curve.
In the case of mode 11, each value in the time range is compared against the previous value, and if it is less, it is assumed to have rolled over some limit and that limit is then added to the accumulated value. The rollover limit is specified in the StaleTime parameter.

If FieldNum is less than 0 (i.e. a time/date value is being requested), the modes listed above are still valid, although not particularly practical. A time/date will be retrieved for every time span containing a data point, even if that point is Invalid, as in the case of a Save statement whose Buffers parameter is 0 (causing an Invalid value to be written).

If TPP is less than or equal to 0, Mode is ignored. If the data is text, the first entry in a given time range is used for the array entry, and Mode is ignored.
It is possible to retrieve more than one mode in a single Get statement. To do this, pass an array of values in as the Mode parameter.

StaleTime
An optional parameter that sets a maximum validity duration for data elements that are being TPP processed. Normally, every data point is treated as remaining valid until the next data point. If a valid StaleTime parameter is given, then any data point will be treated as invalid StaleTime seconds after the recorded time. If TPP is less than or equal to 0, StaleTime is ignored. If StaleTime is not required, but PathPrefix is, then StaleTime should be given as either an Invalid value, or a constant zero. If Mode is 11, then StaleTime is the accumulator rollover value.
It is possible to specify more than one stale time in a single Get statement. To do this, pass an array of values in as the StaleTime parameter.
PathPrefix
An optional text expression parameter that enables and controls the retrieval of data from across a set of files.
Comments: This function will return either the relative file position of the file entry following the last entry read, or an error code. If the return value is negative, it is the file position. If it is 0, the end of the file was reached before all the data was read. If the return value is positive, one of the following errors occurred.
Error Code | Error
1 | Parameter values out of described range
2 | File could not be opened
3 | Corrupted .DAT file
4 | Field requested could not be found

If StartDate is given a negative value, indicating that a particular entry is to be retrieved, it must be stressed that the file being read by the Get may or may not contain an Invalid record at the end of the file. If the Save that created the file was given a negative number for its Buffers parameter, the Invalid record would not have been written to the file, however, a zero or positive value for Buffers will mean that the last record of the file will be one whose fields are all Invalid and whose time and date stamp reflect the cessation of writing to the file by the Save.

If FieldNum is an array with more than one element, then Get will retrieve multiple fields from the file. In this case, ArrayElem must represent an array with at least two dimensions. The requested values will be returned in a manner analogous to GetHistory. That is, with the data for a column in the rightmost dimension, and the column index in the previous dimension.

When FieldNum is specified as an array, Mode or StaleTime, or both, may be specified as either a single value or an array of values. If a single value is specified, that value will be used for each of the fields specified in FieldNum. If an array of values is specified, the first element in the array will be applied to the first element of FieldNum, and so on.

If PathPrefix is specified, then this changes the interpretation of the File parameter. In this case, the referenced file is not the source of the data, but a file containing references to other files that are data sources. This file should be in standard VTScada LogFile format and should contain a file reference as the first text value of each record (other values are ignored). The records should be in the correct time order with respect to the data files. The value of the PathPrefix is a string, which when prefixed to one of the file references, will yield a full pathname to the target file. If no prefix is required, but expansion of the dataset is required, then PathPrefix should be an empty string.

  • If a filename entry does NOT begin with a "\" or "<drive letter>:\", then the PathPrefix will be prepended to the filename.
  • If a filename entry DOES begin with "<drive letter>:\", then the PathPrefix will NOT be prepended to the filename.
  • If a filename entry does begin with a "\", then the "<drive letter>:\" from the PathPrefix will be prepended to the filename. If there is no "<drive letter>:\" in the PathPrefix then the "<drive letter>:\" from the path of the File parameter will be used instead.

PathPrefix would normally be Invalid or the application path.

If a Get is executed while a Save is still active, the save buffer will immediately be flushed to disk. That is to say, data in the buffer that may have been otherwise overlooked by this particular Get will be written to disk so that the current data set is available to the Get in its entirety.

Care must be exercised when using the result from a Get function in further Get functions. This is the normal use for the return value, however, if a Save statement updates the file between Get functions, the return value will be shifted by one from its original file position. The solution to this problem is to either ensure that the Save statement is not executed by disabling the Trigger, or to keep the successive Get functions in a single script.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

If ! Valid(Exists);
[
  Exists = FileFind("G:\Mixer\Trend.DAT"
  { Path and files to search },
  0 { Normal file attributes },
  2 { Return full path and name });
]
If Valid(exists[0]) && exists[0] == "G:\Mixer\Trend.DAT";
[
  Get(Trend[0] { Destination array },
      100 { Get 100 array elements from file },
      "G:\Mixer\Trend" { path and file name },
      0 { Read first 'column' from file },
      Today() { Starting today },
      Seconds() - 3600 { Starting 1 hour ago },
      18 { Each element represents 18 seconds },
      0 { Time weighted avg over 18 secs });
]

This tests to make sure that the file exists, and then reads a half hour of data from a file, starting 1 hour (3600 seconds) ago. Note that just after midnight, the expression Seconds( ) - 3600 may be negative. The Get statement interprets this as before midnight on the previous day (which is correct). X is set to the record following the last record read from the file. Note also that a full path name may be specified, including network drives. Also note that it is irrelevant when data were logged to the file. The Save statement trigger could have been a regular timer (such as AbsTime), or an event (such as Change as applied to a variable).

If ! Valid(FilePos);
[
  FilePos = Get(array1[10]{ Start at element 10 },
               25 { Read 25 array elements },
               "trips" { File trips.dat (in current dir) },
               1 { Read time stamp, not data },
               25 { Read 25 items before EOF },
               0 { Start time is ignored },
               0 { Read on a point-by-point basis },
               0 { Mode is ignored });
]

This reads the time stamps of the 25 most recently logged entries into elements 10 through 34 of array1. FilePos is set to the item past the last item read (in this case, the oldest record).


GetAccountID

(Security Manager Module

Description: | Returns the account ID of the named account.
Returns: | String
Usage: | Script or steady state.
Related to: | GetAccountInfo | GetFullName | GetGroupName | GetUserName | IsLoggedOn | IsSecured | IsSuspended | SecurityCheck | UIErrorToText
Format: | \SecurityManager.GetAccountID([AccountName])
Parameters: |
AccountName
Optional. The name of the account to obtain the account ID for.
Comments:

If AccountName is Invalid or not specified, returns the account ID of the caller’s account.

A common use is to store a retained instance of a module, which is linked to the current user. See: SetInstanceName for more information and an example.

Example:

  SecureID = \SecurityManager.GetAccountID();

SecureID is set to the ID of the user currently signed in for this session / workstation.


GetAccountInfo

(Security Manager Module

Description: | Returns one or more AccountData structures.
Returns: | Dictionary
Usage: | Script Only.
Related to: | BuildFullName | GetAccountID | GetFullName | GetGroupName | GetUserName | IsLoggedOn | IsSecured | IsSuspended | SecurityCheck | UIErrorToText
Format: | \SecurityManager.GetAccountInfo([AccountID, IndexByID]);
Parameters: |
AccountName
Optional. The account ID for which information is to be obtained.
IndexByID
Optional. A Boolean. If TRUE the returned dictionary will use account IDs as the dictionary key. If FALSE (default) the returned dictionary will use the account names as the dictionary key.
Comments:

To use this API, the calling code must be running in a security session that has the Manager privilege.

If AccountID is valid, a single AccountData Structure is returned for the specified account.

If Account ID is Invalid, a dictionary of AccountData structures for every account and role is returned. The dictionary uses either account names or account IDs as the dictionary key, depending on the value of the IndexByID parameter.

The AccountData structures returned here can be modified in situ and passed back into ModifyAccount or DeleteAccount to effect changes to the account records.
The Password and AltID fields of the returned structure are always Invalid.

Example:

...
  If Watch(1);
  [
    CurrentUserInfo = \SecurityManager.GetAccountInfo();
    ...

The variable CurrentUserInfo will be populated with an AccountData structure for the currently signed-in account.


GetAdaptersInfo

(Engine-Level Function)

Description: | Returns TRUE whenever the network interface configuration of the local computer changes. (For example, turning off WiFi or plugging in a network adapter.) Current network configuration is returned in the parameter.
Returns: | Boolean.
Usage: | Steady State only.
Function Groups: | Network and Workstation
Related to: |
Format: | GetAdaptersInfo(Info)
Parameters: |
Info
Optional. A variable that will be assigned a dictionary describing the current networking configuration of the local computer.
Comments:

The dictionary maintained in variable Info, has 3 members. Each of the members holds an array of equal size, with one element per network interface.

"InterfaceID"

Holds the interface ID number that Windows has assigned to the network interface.

"Name"

Holds the textual name of the interface.

"UniqueID"

Holds a UUID assigned to the interface by Windows.

"Addresses"

Holds an array of IP address structures, one element for each IP address configured on the interface.

Each structure has the following members:

"Address" - a buffer holding the configured binary address. Note that IPv4 addresses are held in IPv4-mapped IPv6 address format.

"Mask" - a buffer holding the configured binary mask for "Address" (IPv4 only).

The binary address buffers can be used as input to IP Mask statements, such as IPMaskToText.

Example:

  If GetAdaptersInfo(AdaptersInfo);
  [
    InterfaceInfo = "";
     { All the members of AdaptersInfo contain parallel arrays }
    I = 0;
    WhileLoop(I < ArraySize(AdaptersInfo["UniqueID"]),
      InterfaceInfo = Concat(InterfaceInfo, "ID: ", AdaptersInfo["InterfaceID"][I], " Name: ", AdaptersInfo["Name"][I], " UniqueID: ", AdaptersInfo["UniqueID"][I]);
       { The Addresses member's array elements contain an array of IP address
         structures. Remember you can have multiple addresses per adapter. }
      IPAddresses = AdaptersInfo["Addresses"][I];
      IfThen(ArraySize(IPAddresses) > 0,
        InterfaceInfo = Concat(InterfaceInfo, "Addresses:");
        J = 0;
        WhileLoop(J < ArraySize(IPAddresses),
          InterfaceInfo = Concat(InterfaceInfo, " ",
                                 IPMaskToText(Concat(IPAddresses[J]\Address, MakeBuff(16, 0xFF))), " : ",
                                 IPMaskToText(Concat(IPAddresses[J]\Mask, MakeBuff(16, 0xFF))));
          J++;
        );
      );
      I++;
    );
  ]

This will set InterfaceInfo to a string describing each network interface in turn.


GetAlarmActionLabel

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns an action label for an alarm / event record
Returns: | Text
Usage: | Script or Steady State
Function Groups: | Alarm
Related to: |
Format: | \GetAlarmActionLabel(IsHistory, Record, Action)
Parameters: |
IsHistory
Required Boolean. Set TRUE if you want the label for a historical event or FALSE for the current status
Record
Optional. The alarm record, for which to obtain the action label.
Action
Optional action code, for use if Record is invalid and IsHistory is true.
Comments:

This function is a user-interface helper module, useful for converting the Action field of an AlarmRecord into a displayable event or status label.

Displayed values are those stored in the application properties, AlarmEventDesc0-21 (IsHistory==TRUE) or AlarmStatusDesc0-5(IsHistory==FALSE).

Example:

  If Watch(1);
  [
    Info = \GetPhrase(\GetAlarmActionLabel(TRUE, Invalid, "Active"));
...

This basic example simply returns the assigned label for "Active" in the current language. (Which in English, is "Active".)

Related information:

AlarmEventDesc0 - AlarmEventDesc21

AlarmStatusDesc0 - AlarmStatusDesc5


GetAlarmConfiguration

(Alarm Manager module)

Description: | Returns a copy of an alarm's configuration structure, returning an unpopulated structure if it does not already exist.
Returns: | Structure (see comments)
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Commission | GetAlarmStatus
Format: | \AlarmManager.GetAlarmConfiguration(AlarmName)
Parameters: |
AlarmName
Required text.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Comments:

GetAlarmConfiguration should be called before commissioning an alarm. This will create an alarm structure that can be populated for the call to \AlarmManager.Commission().

An alarm has the following configuration structure:

ConfigurationStruct { All Boolean flags default to FALSE }
Name

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

FriendlyName | Display name of the alarm's source. This is only needed for alarms that are not associated with a tag, such as service alarms. Tag alarms will always show the tag's Name as the display name.
Area | Area
Description | Description. See also: NoLegacyAlarmDesc
Priority | Priority. Must be valid to be commissioned. Must be an integer corresponding to the Alarm Priority tag values. A priority of 0 will be treated as an event and will not go on either the Active or Current lists.
Reserved
Disable | TRUE to disable the alarm.
DisableParmName | Name of the tag's disable parameter. Allows you to get the operator name who made the configuration change.
OnDelay | Seconds to delay before activating.
OffDelay | Seconds to delay before clearing.
RearmDelay | Seconds to delay before rearming after acknowledgment.
Setpoint | Setpoint of alarm evaluation. The value is compared against the setpoint.
ValueLabels | Array of labels to display instead of Value or Setpoint. Rarely used by tags other than digitals.
Units | Phrase Key of the setpoint units.
Function | Enumerated function for alarm evaluation. See: Alarm Manager Function Constants
AlarmType | String identifying the type of alarm. Used for display purposes only, in accordance with the ISA18.2 standard. Examples include "Low", "High", "Test".
Trip | TRUE if alarm only becomes unacked not active.
NormalTrip | TRUE if alarm becomes unacked when it clears.
OffNormal | TRUE if alarm only becomes active not unacked.
Deadband | Setpoint deadband.
PopupEnable | TRUE to enable popup display of active alarm.
SoundFile | Filename relative to app path of custom sound.
Custom | Number/String/Array/Dictionary/Structure containing custom data. This information is not shown anywhere on the AlarmPage by default, but could be displayed using a custom column.
AdHoc | TRUE if alarm is ad hoc.
ReactivateOnValueChange | If TRUE, the alarm will reactivate whenever the reported value changes.
DescPhraseID | PhraseID or a ParmPhrase structure to translate the description to current language.
NormalAck | TRUE to auto-ack the alarm when it clears.
Hook

The name of a module you supply, which will be called whenever any alarm event occurs for the given alarm, including events such as active / normal / acknowledge / shelve / disable / commission / etc.

VTScada will look for the callback module starting in the AlarmObject that is provided in the call to Commission(), and will search upwards until it reaches Code level. This gives you flexibility to specify your callback module in your custom alarm tag, or in a custom ancestor tag, or in the application (AppRoot).

The callback module must take a TransactionInfo structure as its only parameter. It is expected to return TRUE or Invalid to allow the transaction to be logged, or FALSE to prevent it.

Example:

The following would typically be found in a tag's Refresh state.

    IfElse(Valid(Name),
           Execute( { create or obtain the configuration structure for this alarm }
                   Cfg          = \AlarmManager.GetAlarmConfiguration(UniqueID);
                    { update the property values in that structure }
                   Cfg\Name     = Root\UniqueID;
                   Cfg\Area     = AreaValue;
                   Cfg\Priority = PriorityValue;
                   Cfg\Setpoint = 1;
                   Cfg\Function = \AlarmManager\ALM_FUNC_EQUAL;
                    { commission (or update the commission of) the alarm }
                   \AlarmManager.Commission(Root, Cfg, Value);
                  );
    );

Related information:

(1)Function constants are documented in: Alarm Manager Function Constants


GetAlarmList

(Alarm Manager module)

Description: | Returns filtered and sorted lists of records from alarm databases.
Returns: | See descriptions in the parameter list.
Usage: | Script Only.
Function Groups: | Alarm
Related to: |
Format: | \AlarmManager\GetAlarmList(ListPtr, LengthPtr, ListNames[, Snapshot, IncludeShelved, IncludeConfig, FilterExpr, CalculatedFields, CalculatedFieldsScope, SortOrder, BeginTime, EndTime, MaxHistory, PtrDone, PtrHistoryProgress, PtrChangeStats, DBTags, RefreshInterval, Realm, Area, IncludeSubordinates, InitDeferTimeout, ApplyRealmUserFiltering, IncludeSuppressed, IncludeDisabled, CallbackScope])
Parameters: |
ListPtr

Required. This pointer will be assigned the array of records being returned. The array may be longer than the number of records, see LengthPtr for the valid length.

If there is no sort order, the most recent record is in array index 0.

LengthPtr
Required. Pointer to a variable which will be assigned the number of elements in the ListPtr array that are to be used.
ListNames

Required. Provide a text string or an array of strings identifying the lists to which the alarm will subscribe. Valid list names include:

  • History
  • Active
  • Unacked
  • Shelved
  • Disabled
  • Configured

To obtain the Current list, include Active and Unacked in your array.

Snapshot
Optional Boolean. If TRUE, then this function will take a snapshot of the list(s) and terminate. If FALSE, then the function will build the list while also keeping it updated.
A snapshot of live list(s) acts as a subroutine, all other uses must launch a worker process.
(Default = FALSE).
IncludeShelved
Optional Boolean. Set TRUE to include shelved alarms. (Default = FALSE).
IncludeConfig
Optional Boolean. Set TRUE to include alarm configuration events in History. (Default = FALSE).
FilterExpr

Optional text string that is the expression to evaluate if a record is to be included.
Standard realm-area filtering is handled automatically so should not be included in this expression.

Note that text must be surrounded in quotation marks if being used in the filter. For example:

Concat("Record\Area == """, pArea, """")
CalculatedFields

Optional array. May be used to create additional record fields or modify existing records. A callback subroutine allows record field values to be replaced, for example swapping AccountID for an operator name.
If specified, this parameter must be an array that defines the extra record fields.
For example:

CalculatedFields = New(4);
CalculatedFields[0] = "FriendlyName";
CalculatedFields[1] = "IsActive";
CalculatedFields[2] = "IsUnacked";
CalculatedFields[3] = "IsDisabled";
CalculatedFieldsScope
Optional. Scope in which to find calculated field values. Often, Self()
SortOrder

Optional. For live lists this is sorting information for SortArray.
For example:

{ Sort by friendly name }
SortInfo = SortKeys("FriendlyName", 1 { text }, #SortAscending);

For history set TRUE for forward chronological, and FALSE for reverse (default).

BeginTime
Optional UTC timestamp. Oldest time. May be used when filtering history.
EndTime
Optional UTC timestamp. Newest time. May be used when filtering history.
MaxHistory
Optional numeric, except required when querying the History list. Limits the number of history records retrieved. No default.
PtrDone
Optional pointer. Will be set TRUE when history search completes.
PtrHistoryProgress
Optional pointer. Will be set to a structure instance containing progress stats (HistoryProgressDef)
PtrChangeStats

Optional pointer. Allows the caller to detect changes. Set to a structure as follows:

  • Additions { Set to cumulative number of records added };
  • Modifications { Set to cumulative number of records modified};
  • Deletions { Set to cumulative number of records deleted };
DBTags
Optional array of AlarmDatabase tag names (UniqueIDs or Friendly Names). If a simple text value, then it is the single tag to access. If Invalid then all AlarmDatabase tags are included. Realm filtering is automatically detected and used.
RefreshInterval
Optional numeric. Minimum time in seconds between sorted array updates. Defaults to a half-second.
May also be set by adding an application property, AlarmListRefreshDelayTime.
Realm
Optional text. Realm to use for realm filtering. This will be detected automatically for the logged-on account if not otherwise specified.
Area
Optional text. Area to use for filtering. May use wildcard characters.
IncludeSubordinates
Optional Boolean. When TRUE, alarm databases from subordinate applications are included. (Defaults = TRUE).
InitDeferTimeout
Optional numeric. Sets a time to wait before initializing. Setting this value to .1 will allow other objects on a page to load before the alarm list is populated, resulting in a smoother user experience. (Default = 0).
ApplyRealmUserFiltering
Optional. 0 to disable, 1 to apply realm and user filtering (default), 2 to apply only realm filtering.
IncludeSuppressed
Optional. TRUE to include suppressed alarms. (Default = FALSE)
IncludeDisabled
Optional. TRUE to include disabled alarms. (Default = FALSE)
CallbackScope
Optional. When valid, if an UpdateRecord submodule is defined in the CallbackScope it will be called on every record change in the subscribed alarm list(s).
Comments:

An alarm database contains a history of alarm transactions / event records. Event records are included only in a queries for a history list.

Filtering - Only records that pass filtering will be displayed. Filtering may be:

  • Area filtering (Realms, etc..) [automatic]
  • Shelved alarm suppression
  • Custom filter expression

For efficiency reasons the filtering is done on the base record rather than the calculated version.

History - Unlike the live lists, the history is unbounded and must be accessed from storage. The process can take time so search progress is reported via PtrHistoryProgress.

When working with a live list, the system will automatically rerun filtering and recalculate fields if an alarm is changes on any list, allowing filtering and calculated fields based on other list state.

CallbackScope

Enable CallbackScope by passing a reference to the desired callback scope (typically self()) into the parameter. The module whose reference is passed to CallbackScope must define an UpdateRecord submodule to receive record updates (see example).

A call to the UpdateRecord module defined in the CallbackScope will be made for every new record added to one of the subscribed lists.

All other GetAlarmList filtering parameters still apply (i.e. the record must pass the supplied filtering for UpdateRecord to be called.)

UpdateRecord takes the following parameters:

UpdateRecord(NewRecord, Action, Name, AlarmDBObj)

This subscription model can be helpful when you want to be made aware of the most recent record received, instead of just being aware of all of the records on the given list(s).

It is possible to do both by passing the ListPtr and LengthPtr parameters as well as the CallbackScope. In this case CallbackScope.UpdateRecord will be called with every new record and the ListPtr and LengthPtr variables will be kept up to date.

If you have no need for the ListPtr or LengthPtr you can leave both invalid. When both are left Invalid we will skip the work of keeping these pointers up to date (reducing the processing load) and only call CallbackScope.UpdateRecord when a new record comes in.

Examples:

GetAlarmList Example

[
  NRecords;
  Records;
  Done;
  Progress;
  LastAckBy;
]
Init [
  If 1 WaitResults;
  [
    \AlarmManager.GetAlarmList(&Records, &NRecords, "History" { History list },
                               TRUE { Snapshot and done }, TRUE { Include shelved },
                               FALSE { No configuration records },
                               "Record\Action == ""Ack""" { Filter for Ack events },
                               Invalid, Invalid, FALSE { No calculated fields },
                               CurrentTime(1) - 7200, CurrentTime(1) { Records for the last two hours },
                               100 { Limit to 100 records } , &Done, &Progress);
  ]
]
WaitResults [
  If Done Main;
  [
    { Process the results...}

CallbackScope examples

No subscription, just ListPtr and LengthPtr:

    \AlarmManager.GetAlarmList(&Records, &NRecords, "History" { History list },
                               TRUE { Snapshot and done }, TRUE { Include shelved },
                               FALSE { No configuration records },
                               "Record\Action == ""Ack""" { Filter for Ack events },
                               Invalid, Invalid, FALSE { No calculated fields },
                               CurrentTime(1) - 7200, CurrentTime(1) { Records for the last two hours },
                               100 { Limit to 100 records } , &Done, &Progress);

Subscription and ListPtr and LengthPtr:

    \AlarmManager\GetAlarmList(&Records, &NRecords, "History" { History list },
                               TRUE { Snapshot and done }, TRUE { Include shelved },
                               FALSE { No configuration records },
                               "Record\Action == ""Ack""" { Filter for Ack events },
                               Invalid, Invalid, FALSE { No calculated fields },
                               CurrentTime(1) - 7200, CurrentTime(1) { Records for the last two hours },
                               100 { Limit to 100 records } , &Done, &Progress, &ChangeStats,
                               Invalid { All AlarmDB's }, Invalid { RefreshInterval }, Invalid { Auto-detect realm },
                               Invalid { Area }, Invalid { IncludeSubordinates }, Invalid { InitDeferTimeout },
                               Invalid { ApplyRealmUserFiltering }, Invalid { IncludeSuppressed },
                               Invalid { IncludeDisabled }, SubRecorderObj.LiveListScope { CallbackScope });

Subscription only:

    \AlarmManager\GetAlarmList(Invalid, Invalid, "History" { History list },
                               TRUE { Snapshot and done }, TRUE { Include shelved },
                               FALSE { No configuration records },
                               "Record\Action == ""Ack""" { Filter for Ack events },
                               Invalid, Invalid, FALSE { No calculated fields },
                               CurrentTime(1) - 7200, CurrentTime(1) { Records for the last two hours },
                               100 { Limit to 100 records } , &Done, &Progress, &ChangeStats,
                               Invalid { All AlarmDB's }, Invalid { RefreshInterval }, Invalid { Auto-detect realm },
                               Invalid { Area }, Invalid { IncludeSubordinates }, Invalid { InitDeferTimeout },
                               Invalid { ApplyRealmUserFiltering }, Invalid { IncludeSuppressed },
                               Invalid { IncludeDisabled }, SubRecorderObj.LiveListScope { CallbackScope });

UpdateRecord example:

<
{=============================== UpdateRecord ==============================}
{===========================================================================}
UpdateRecord
(
  NewRecord                   { Record being added or removed from the list };
  Action                      { 0 = delete, 1 = add, 2 = modify             };
  Name                        { Name of the list that the record is on
                               (ignored)                                    };
  AlarmDBObj                  { AlarmDatabase that owns RawRecord. Only
                                provided when the record needs its names
                                translated to this app's namespace (ie not
                                provided when handling results of
                                AlarmDatabase\GetFilteredHistory)           };
)

UpdateRecord [
  If 1;
  [
    SomeList[Name] = NewRecord;
  ]
]

{ End of UpdateRecord }
>


GetAlarmName

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns the name of a given alarm within a tag for use with the AlarmManager's inquiry functions.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | Alarms
Related to: | GetAlarmConfiguration | GetAlarmObject | GetAlarmStatus | IsActive | IsDisabled | IsShelved |IsUnacked
Format: | \GetAlarmName(TagObj[, Key])
Parameters: |
TagObj
Required. A reference to a tag that contains an alarm.
Key

Optional text. Identifies which alarm to query within the tag. Typically, this will be any of "LowLow", "Low", "High", "HighHigh", or "Digital"

Key is not case-sensitive. If set to a word other than those listed here, GetAlarmName will return Invalid.

Comments:

For tags that do not have a range of alarm types (PLC alarm, Alarm Point, Digital Status, Network Status, Pump Status, Selector Switch), do not provide a Key.

Example:

    \AlarmManager.IsActive(\GetAlarmName(\Root, "Low"));


GetAlarmObject

(Alarm Manager module)

Description: | Returns an alarm object value given an alarm name.
Returns: | Object reference.
Usage: | Script Only.
Function Groups: | Alarm
Related to: | GetAlarmList | GetUserNameOfRecord
Format: | \AlarmManager.GetAlarmObject(AlarmName[, ptrRoot])
Parameters: |
AlarmName
Required text.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

ptrRoot
Optional pointer. If valid, and if the alarm is a tag or a submodule of a tag, that tag's object value will be returned in this parameter.
Comments:

This function can also provide the alarm's Root tag value, returned through the optional second parameter.

Example:

 { Given an array of alarm records, get the tag object from the alarm name whenever the array index, SelRecord, changes.  }
  If Watch(1, Records[SelRecord]\GUID);
  [
    \AlarmManager.GetAlarmObject(Records[SelRecord]\Name, &Root);
    ShortName = \AlarmManager.GetNameOfRecord(Records[SelRecord]);
  ]


GetAlarmStat

(Function Library)

Description: | Returns the number of alarms in the given tag and its descendents, where those alarms match the specified statistic.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: | AlarmCondition |AlarmUnAckCondition
Format: | \FunctionLib.GetAlarmStat(TagObj, Statistic[, Priority])
Parameters: |
TagObj
Tag object to be checked for alarm statistics. Typically a parent tag, such as a station.
Typically provided in the form, [TagName]\Root
Statistic
Required Text. Specifies which alarm types or states to count. See comments.
Priority
Optional Numeric. Specify only if querying statistics for a given priority value.
Comments:

This module is a member of the Function Library, and must therefore be prefaced by \FunctionLib. as shown in the "Format" section.

The Statistic parameter must be provided as text using one of the following keywords. Counts include alarms in descendents where appropriate, such as with suppressed alarms.

ActiveCount | Total active alarms
ActivePriorities | Counts of active alarms for the given priority
DisabledCount | Total disabled alarms
HighestActivePriority | Highest priority of active alarms
HighestUnackedPriority | Highest priority of unacknowledged alarms
ShelvedCount | Total shelved alarms
SuppressedCount | Total suppressed alarms
UnackedCount | Total unacknowledged alarms
UnackedPriorities | Count of the unacknowledged alarms for the given priority

Example:

Example shows an expression that could be added to the user interface (such as within an I/O or Calculations tag) rather than a script code file.

\FunctionLib.GetAlarmStat([Station 1]\Root, "ActiveCount")

Will return 5 if there are five active alarms in Station 1 and its descendants.


GetAlarmStateStats

(Alarm Manager module)

Description:

Returns a structure containing the cumulative alarm state statistics for the specified tag. (See following notes.)

If the tag is the ancestor of multiple alarm tags, the stats will be the accumulation of all descendent alarms.

Returns: Structure
Usage: Script or steady state.
Function Groups: Alarm
Related to: GetAlarmObject
Format: \AlarmManager.GetAlarmStateStats(TagInstance)
Parameters:
TagName
Required object reference. The tag for which statistics are to be gathered.
Comments:

TagName may be a context or other parent, in which case statistics will be gathered for all of the child tags.

It may also be Code, in order to retrieve statistics about the whole application.

Information returned by this function is not limited by realm-area filtering.

The return structure includes the following elements:

ActiveCount { Total Active alarms including descendents };
UnackedCount { Total Unacked alarms including descendents };
ShelvedCount { Total Shelved alarms including descendents };
DisabledCount { Total Disabled alarms including descendents };
SuppressedCount { Total Suppressed alarms including descendents };
HighestActivePriority { Highest priority of active alarms including descendents };
HighestUnackedPriority { Highest priority of unacked alarms including descendents };
ActivePriorities { Dictionary of counts of active alarms for each priority, including descendents };
UnackedPriorities { Dictionary of counts of unacked alarms for each priority, including descendents }

The dictionaries, ActivePriorities and UnackedPriorities are keyed by alarm priority numbers, which are padded with zeros. For example, the key to access the count of Critical active alarms is "0001".

These dictionaries will return an invalid if there are no alarms that match your query. A valid value will not be returned until a specified alarm has been generated. To protect against an invalid return from the expression, especially if value returned is to be included in reports or displayed on a screen, the expression should be wrapped in a PickValid() so a valid value will always be returned. For example: PickValid(\AlarmManager.GetAlarmStateStats(\Root).ActivePriorities["0001"], 0)

Example 1:

  TotalStats           = \AlarmManager.GetAlarmStateStats(MyContextTagName);
  TotalUnackedPriority = TotalStats.HighestUnackedPriority;

If there are two active critical alarms and three active high alarms, then...

  \AlarmManager.GetAlarmStateStats(\Root).ActiveCount

returns 5

  \AlarmManager.GetAlarmStateStats(\Root).HighestActivePriority

returns 1

  \AlarmManager.GetAlarmStateStats(\Root).ActivePriorities["0001"]

returns 2

(Refer to the note in the comments: Invalid will be returned until there are alarms that match the query.)

Example 2:

Given an application where the only current alarm is from a Roster Alarm Test, the following statement:

  AlmStats = \AlarmManager.GetAlarmStateStats(\Code);

will set AlmStats to:


GetAlarmStatus

(Alarm Manager module)

Description: | Returns a reference to an alarm's status structure, providing access to the alarm's current state without having to make function calls.
Returns: | Structure (see comments)
Usage: | Script Only.
Function Groups: | Alarm
Related to: | IsActive |IsDisabled | IsShelved |IsUnacked
Format: | \AlarmManager\GetAlarmStatus(AlarmName)
Parameters: |
AlarmName
Required text.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Comments:

Use this when writing code that will monitor the status of an alarm. It is typically used in a tag's refresh module after calling Commission.

In older versions of VTScada, function calls were used for the same task. For the sake of backward-compatibility, those functions will continue to work, but should not be used in new code.

AlarmStatus Struct
IsActive | TRUE if alarm is on the Active list
IsUnacked | TRUE if alarm is on the Unacked list
IsShelved | TRUE if alarm is on the Shelved list
IsDisabled | TRUE if alarm is on the Disabled list
IsSuppressed | TRUE if alarm is on the Suppressed list
IsSilentlySuppressed | TRUE if alarm is suppressed but not on the Suppressed list

Variables within the structure may be accessed using either the dot notation or the backslash.

Example:

Monitor for when the alarm is active and unacknowledged, possibly to display a message.

 If Watch(1) Main;
  [
    AlmStatus = \AlarmManager\GetAlarmStatus(AlarmName);
  ]
...
Main [
  IfElse(AlmStatus.IsActive && AlmStatus.IsUnacked,
       ... { TRUE case  },
       ... { FALSE case });
]


GetAllTagTypesInGroup

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns an array of all Tag Types in a Tag Group.
Returns: | Array
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | CheckTagGroup|GetTagList|GetTagTypes
Format: | \GetAllTagTypesInGroup(Group)
Parameters: |
Group
Required. The string name of the queried Tag Group.
Comments:

The function returns the array of Tag Types sorted alphabetically by their names in code, see Tag Names in Code.

The list of Tag Group names included with VTScada is found in the topic Type Characteristics. The function can also query Custom Tag Groups.

Returned Tag Types may be members of more than one group. For example, queries for the Tag Groups "Digitals", "Analogs", and "Strings" will all return the I/O and Calculations Tag Type in their arrays.

Note: The Tag Browser's Select Type dialog only lists Legacy Tags Types under the [Legacy Drivers] and [Legacy I/O and Calculations] groups. However, this function returns Legacy Tag Types in all relevant groups. For example, The Legacy Strings I/O Tag Type does not appear under the "Strings" Tag Group in the Select New dialog but \GetAllTagTypesInGroup("Strings").

Example:

To retrieve an array of all tag types that are part of the numeric group

LocalSubTypeList = \GetAllTagTypesInGroup("Numeric")


GetAllWorkstationNames

(RPC Manager Library)

Description: | Launched module that creates an alphabetically sorted list of all known workstation names. The list is not service specific.
Returns: | Nothing. List available in first parameter.
Usage: | Script Only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetAllWorkstationNames(pList[, Layer]);
Parameters: |
pList
Required. Pointer which will be set to the resulting server list of workstation names.
Layer
Optional. Layer for which a server list should be obtained.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

This subroutine is only called by the service instance that is server during synchronization.

Example:

...
  If Watch(1);
  [
    \RPCManager.GetAllWorkstationNames(&NameList);
...

NameList will contain an array of all the workstation names in the server list.

Related information:

RPC Manager Service


GetAppInstance

(System Library)

Description: | Retrieves the Layer object (\AppLayer) for a particular application specified by GUID.
Returns: | Object (Layer object returned via a parameter)
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | GetLoadedAppInstance | GetCodeObj | GetGUID
Format: | System.GetAppInstance(GUID, pAppInstance)
Parameters: |
GUID
Required text. The 36-byte GUID of the application to be retrieved.
pAppInstance
A pointer to a variable. The Layer object matching the GUID will be returned via this pointer.
Comments:

The return value of this function will be an object that becomes invalid upon completion. If the Layer has not finished loading, this function will wait until it does so before returning. This is an asynchronous operation.

If the GUID does not match any known application, then Invalid will be assigned to the second parameter.

Examples:

Init [
  If 1 WorkState;
  [
    WaitObj = System.GetAppIntance(MyGUID, &TargetLayer);
  ]
]

When the function finishes, WaitObj will become Invalid.


GetByte

(Engine-Level Function)

Description: | Returns a single byte from a buffer.
Returns: | Byte
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | SetByte
Format: | GetByte(Buffer, Offset)
Parameters: |
Buffer
Required. Any buffer expression giving the buffer to get the byte from.
Offset
Required. Any numeric expression giving the offset from the start of the buffer in bytes, starting from 0.
Comments: This function is useful for manipulating text on a byte-by-byte level. For example, examining serial I/O driver response packets.

Example:

  oneByte = GetByte(response, 0);

The variable oneByte is set to the character value of the first byte in the text variable response.

If response is Invalid, then oneByte will be Invalid. If oneByte is valid, its value will always be in the range 0 to 255.


GetCertificateInfo

(Engine-Level Function)

Description: | Returns a structure of information about a supplied X.509 certificate.
Returns: | Structure
Usage: | Script Only.
Function Groups: | Certificates
Related to: | AddCertificate | CheckCertificateChain | FindCertificate | ListCertificates | MakeSelfSignedCertificate | RemoveCertificate | SetCertificateProperty
Format: | GetCertificateInfo(CertificateBLOB)
Parameters: |

CertificateBLOB

Required. A buffer holding a DER-binary encoded certificate BLOB (binary large object) of the certificate from which information is required.
Comments

The certificate blob may be obtained from a number of different sources. For example, it may be transmitted over a communication protocol or be the output of another certificate DAG.

The structure returned is of the same format as that returned from ListCertificates.

Example:

  ServerCertStruct = GetCertificateInfo(ServerCertBlob);


GetClientDiverts

(RPC Manager Library)

Description: | Returns a one-dimensional array of flags, indicating the divert status of each client.
Returns: | Array
Usage: | Steady State only.
Function Groups: | Network
Related to: | SetDivert | GetClientGUIDs
Format: | \RPCManager.GetClientDiverts(Service [, OptGUID])
Parameters: |
Service
Required. Any text expression giving the name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

Each client that has service RPCs diverted to an auxiliary holding queue (as a result of the SetDivert function) has its array element in the returned array set to one.
If the 16-byte binary format of the GUID for the application in which the service instance is located is not known, the GetClientGUIDs function may be used to obtain it.

Related information:

RPC Manager Service


GetClientGUIDs

(RPC Manager Library)

Description: | Returns a one-dimensional array of the application GUIDs of the clients of the specified RPC service instance.
Returns: | Array
Usage: | Steady State only.
Function Groups: | Network
Related to: | GetClientIPs | GetClientList
Format: | \RPCManager.GetClientGUIDs(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

The returned array elements will all be the same, unless cross-application RPC is being used.

Related information:

RPC Manager Service


GetClientIPs

(RPC Manager Library)

Description: | Returns a one-dimensional array of the IP addresses of the clients of the specified service instance.
Returns: | Array
Usage: | Steady State only.
Function Groups: | Network
Related to: | GetClientGUIDs | GetClientList | GetClientNodes
Format: | \RPCManager.GetClientIPs(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

On a multi-homed system, any of the possible IPs may be returned for each client.

Related information:

RPC Manager Service


GetClientList

(RPC Manager Library)

Description: | Returns a one-dimensional array of the names of the clients of the specified service instance.
Returns: | Array
Usage: | Steady State only.
Function Groups: | Network
Related to: | GetClientGUIDs | GetClientIPs
Format: | \RPCManager.GetClientList(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

On a multi-homed system, any of the possible alias names may be returned for each client.

Related information:

RPC Manager Service


GetClientMode

(RPC Manager Library)

Description: | Returns a one-dimensional array of the modes of the clients of the specified service instance.
Returns: | Array
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetClientMode(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUI
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

The mode value represents the current synchronization state of the client, with respect to the local service instance. Presently, one of the following values may be returned in each array element

\RPC_ACCEPT_ALL - the client is fully synchronized.
\RPC_SYNC_MODE - the client is being synchronized.
\RPC_LINKCONTROL_ONLY - client requires synchronization.

Related information:

RPC Manager Service


GetClientNodes

(RPC Manager Library)

Description: | Returns a one-dimensional array of the object values of the Machine Nodes of the clients of the specified service instance.
Returns: | Array
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetClientNodes(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

Related information:

RPC Manager Service


GetCodeObj

Description: | Retrieves the "Code" object associated with the layer.
Returns: | Object
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | GetLoadedAppInstance |
Format: | \AppLayer.GetCodeObj()
Parameters: | none
Comments: | This function is useful when there is a need to work with the code object of a layer other than the current application.

Examples:

  ...
    Layer      = \GetLoadedAppInstance(\LocalGUID) ;
     { \LocalGUID is a defined constant holding the GUID of the current application }
    AppCodeObj = Layer\GetCodeObj();
    PageParmNames = ListVars(Scope(AppCodeObj, SessionData), "*", 0, 0, 4 {parms}, 0, 0, 0, 0);
...


GetColorInfo

(Engine-Level Function)

Description: | Returns the brush and pen information for a given graphic statement.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Graphics, Color
Related to: | Brush | Pen
Format: | GetColorInfo(\Code, PenBrushNum, Attribute)
Parameters: |
Code
Required. Any statement that gives the code pointer of the object whose color information is desired.
PenBrushNum
Required. Any numeric expression which gives the number of the pen or brush which the color information is desired for. The first pen or brush is numbered 1.
Attribute
Required. Any numeric expression which gives the desired color attribute.
Attribute | Color Attribute
0 | Type of the PenBrushNum supplied. Return value is 19 (brush) or 20 (pen)
1 | The foreground color of the brush or pen specified
2 | For a brush, the background color, for a pen, the width
3 | For a brush, the pattern number, for a pen, the style
Comments: The return value of this function is determined by Attribute.


GetConfiguration

(Engine-Level Function)

Description: | Returns the configuration parameters from the license key for this copy of VTScada.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Software and Hardware
Related to: | SerialNum
Format: | GetConfiguration(Option)
Parameters: |
Option
Required. Selects the configuration item for which information is required. See the following table:
(GetConfiguration returns Invalid for any value outside the range shown. )
Option | Configuration Item
0 | Serial number of this copy of VTS
1 | Number of hours for restricted run time (0 if unrestricted)
2 | Expiry date for free updates. (Must be handed to the Date function for a human-readable format.)
3 | Number of tags permitted (or 0 if no limit)
4 | Number of browser clients permitted
5 | Run mode (0 = Full. 1 = Run Time. 2 = Configuration. 3 = View Mode)
6 | Reserved
7 | Returns the number of days remaining in the evaluation period. If this is not an evaluation license, then this option returns Invalid.
8 | Returns the Client Connection Restriction. If TRUE (1). VTScada client systems installed with this license may only connect to servers with the same serial number. If FALSE (0), VTScada client systems installed with this license may connect to any server.
9 | The VTScada Alarm Notification System is an option controlled by the installation key in VTScada versions 7.1 and later. Option 9 returns the status of this enable - TRUE if the Alarm Notification System is supported. FALSE if the Alarm Notification System is not supported.
10 | Returns the copyright statement built into VTScada. The format of the returned text string is: "Copyright © 1988-2022 Trihedral Engineering Ltd"
11 | Not used.
12 | Returns 1 if Remote Data Access is enabled. 0 if not
13 | Not used.
14 | Returns 1 if the OPC server is enabled. 0 if not
15 | Returns 1 if this installation is licensed to run 64-bit VTScada. 0 if not
16 | Returns 1 if the key enables the Show Version Control option in the Application Properties Dialog
17 | Returns 1 if Synchronized Configuration is enabled
18 | Returns 1 if Application RPC Services are enabled
19 | Returns 1 if machine is an RPC Server
20 | Reserved
21 | IVONA (Deprecated)
22 | Reserved
23 | Returns the installation key evaluation period type, as follows: 0 - unlimited 1 - 30 days from install 2 - 90 days from install 3 - same as maintenance expiration
24 | Reserved
25 | Returns the location of the VTScada executable
26 | Returns TRUE if the Remote Idea Studio is enabled. (VIC use only)
Comments:

If the license key information fails certain consistency checks, then this function returns Invalid for all values of Option.

This function can be used to determine license restrictions pertaining to the current copy of VTScada. GetConfiguration(0) is identical to the function SerialNum() and is preferred for all new code.

Example:

The following could be added to an administrative page in an application. While the example shows English text, a phrase key should be used in practice.

  GUIText(57, 126, 245, 106,
          1, 1, 1, 1, 1 { Scaling              },
          0, 0          { Movement             },
          1, PickValid(\ScaleDisplayContent, 0) { Visibility, Font Scaling },
          0, 0, 0       { Selectability        },
          Brush("<00000000>", 0, 1), Pen("<FF000000>", 1, 1),
          Scope(VTSDB, "LabelFont", TRUE)\Value,
          0, 4,
          "%s",
          Concat("Remember to renew by ", Date(GetConfiguration(2), 4)));


GetConnList

(ODBC Manager Library)

Description: | Called to obtain a list of the available connections. The list will be returned in the form of two pointers: one for an array of the connection objects and the other for an array of the connection names.
Returns: | Numeric. The connection list will be passed back in the parameters.
Usage: | Script or steady state.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList ResultFormat | StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager\GetConnList(ObjPtr, NamePtr)
Parameters: |
ObjPtr
Required. The list of object values to return.
NamePtr
Required. The list of names to return.
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.
Returns 0 upon completion.

The module may be called as a subroutine in a script or as a called function in a state. When called in a state, there is no automatic updating of the connection list as it changes.


GetContainerNumActive

(Alarm Manager module)

Description: | Returns the number of active alarms within a hierarchy of tags.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Alarm Manager
Related to: | Accumulate | GetContainerNumUnacked
Format: | GetContainerNumUnacked(ContainerObj);
Parameters: |
ContainerObj
Required. The container tag to query.
Comments: In earlier versions of VTScada, if you had written a custom tag with a built-in alarm, you had to ensure that it contributed its active alarms to the count maintained by a hierarchical accumulator module. This is no longer true.

Example:

  TotalNumActive  = \AlarmManager\GetContainerNumActive(MyTagObject);

Where, "MyTagObject" represents the container tag object.

Example 2:

Given a Context-derived tag at the top level of the tag hierarchy named "Station 1", suppose that you want an expression in a calculation tag that will return the total number of active alarms in that context. The expression would be:

  \AlarmManager\GetContainerNumActive([<Station 1>]\Root)


GetContainerNumUnacked

(Alarm Manager module)

Description: | Returns the number of unacknowledged alarms within a hierarchy of tags.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Alarm Manager
Related to: | Accumulate | GetContainerNumActive
Format: | GetContainerNumUnacked(ContainerObj);
Parameters: |
ContainerObj
Required. The container tag to query.
Comments: In earlier versions of VTScada, if you had written a custom tag with a built-in alarm, you had to ensure that it contributed its unacknowledged alarms to the count maintained by a hierarchical accumulator module. This is no longer true.

Example:

  TotalNumUnacked   = \AlarmManager\GetContainerNumUnacked(MyTagName);

Example 2:

Given a Context-derived tag at the top level of the tag hierarchy named "Station 1", suppose that you want an expression in a calculation tag that will return the total number of unacknowledged alarms in that context. The expression would be:

  \AlarmManager\GetContainerNumUnacked([<Station 1>]\Root)


GetContributors

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns a copy of an array of object values of contributors for a given container.
Returns: | Array
Usage: | Script Only.
Function Groups: | Containers and Contributors
Related to: |
Format: | \GetContributors(HandleName, ContainerObj);
Parameters: |
HandleName
Required text. The name of the handle variable in the container module.
ContainerObj
Required. The object VTScada Value Types of the container tag module.
Comments:

Used only when writing custom tags with code (as opposed to creating them from Context tags). See: Containers, Contributors and Site Tags

This function can be called from the contributor.

Example:

    AlarmObjs = \GetContributors("AlarmContributors", \Root);


GetCryptoProvider

(Engine-Level Function)

Description: | The GetCryptoProvider function is used to acquire a handle to a particular key container within a particular cryptographic service provider (CSP). This returned handle can then be used to make calls to the selected CSP. It is the VTScada analog of the CryptoAPI CryptAcquireContext call.
Returns: | Handle
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | DeriveKey | Decrypt | Encrypt | ExportKey | GenerateKey | GetKeyParam | ImportKey | SetKeyParam
Format: | GetCryptoProvider(CSPType [, CSPName, ContainerName, Flags, Error])
Parameters: |
CSPType

Required text or numeric. The type of CSP required. .

CAPI (Cryptography API) providers are specified using numeric identifiers. Values are defined in WinCrypt.h

CNG (Cryptography New Generation) algorithm providers are specified using text identifiers.

CSPName
An optional parameter that holds the name of the required CSP. If omitted or invalid, then a handle to the default CSP of the specified type will be acquired.
ContainerName
An optional parameter that holds the name of the key container. If omitted or invalid, then the default key container for the CSP is used.
Flags
An optional parameter specifying the flags to be passed to CryptAcquireContext. If omitted or invalid then the value 0 is used.
Error
An optional variable in which the error code for the function is returned. It has the following meaning
Error | Meaning
0 | CSP handle successfully returned.
1 | CSPType parameter invalid.
x | Any other value is an error from CryptAcquireContext.
Comments: The return value for this function is a handle to the CSP. If an error occurs, then the return value is invalid. A CSP handle has a value type of 36. If cast to text then the name of the CSP will be returned.
If ContainerName is omitted or invalid then a default key container name is used. For example, the Microsoft Base Cryptographic Provider uses the account name of the user signed in as the key container name. Other CSPs can also have default key containers that can be acquired in this way.

Examples:

[
  CSP;
  Constant PROV_DSS_DH = 13;
]
Init [
  If 1 Main;
  [
    CSP = GetCryptoProvider(PROV_DSS_DH);
...

Would obtain a handle to a CAPI cryptographic provider.

    CSP = GetCryptoProvider("AES", …);

Would obtain a handle to a CNG algorithm provider. The algorithm provider is typically used as an input parameter to ImportKey. For example:

    ImportKey(GetCryptoProvider("AES"), Invalid, KeyMaterial);

[
  CSP;
  CSPFail;
  Container = "VTS";
  Constant PROV_DSS_DH = 13;
  Constant CRYPT_NEWKEYSET = 8;
  Constant NTE_BAD_KEYSET = 0x80090016;
]
Init [
  If 1 Main;
  [
    CSP = GetCryptoProvider(PROV_DSS_DH, Invalid,
                            Container, Invalid, CSPFail);
    IfThen(CSPFail == NTE_BAD_KEYSET,
       { Not used this container before, make a new one }
       CSP = GetCryptoProvider(PROV_DSS_DH, Invalid,
                            Container, CRYPT_NEWKEYSET, CSPFail);
    );
  ]
]


GetCurrentRecipe

Description: | Returns the name of the current recipe
Returns: | Text
Usage: | Script Only.
Function Groups: | Recipe Book
Related to: | GetRecipes | GetVersions | GetCurrentVersion | SetCurrentRecipe | SetCurrentVersion |
Format: | RecipeBook.GetCurrentRecipe([GetFromTag])
Parameters: |
GetFromTag

Optional Boolean. If FALSE (default), the name of the selected recipe is returned.

If TRUE, the name of the recipe as read out of the PLC is returned if the PLC supports this and if the Recipe Name parameter tag has been given an address for reading this value.

Comments:

"RecipeBook" must be a reference to a Recipe Book tag object, not the name of the tag.


GetCurrentSubordinate

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Retrieves the current subordinate driver value of the Driver Multiplexer tag.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Configuration Management
Related to: | GetSubordinateDriver
Format: | GetCurrentSubordinate()
Parameters: |
Comments:

0 indicates the primary subordinate driver.

1 indicates the secondary subordinate driver.

2 indicates that the Driver Multiplexer tag is on a client (remote) and the mode tab is configured with the Selection in Automatic and the Sequence in either Parallel or Alternating mode. Or the Driver Multiplexer tag is on a server with the selection in Automatic and the Sequence in Parallel mode.

See DriverMUX properties Modes tab for more information.


GetCurrentVersion

(Recipe Book module)

Description: | Returns the current version of the current recipe
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Recipe Book
Related to: | GetRecipes | GetVersions | GetCurrentRecipe | SetCurrentRecipe | SetCurrentVersion |
Format: | RecipeBook.GetCurrentVersion([GetFromTag])
Parameters: |
GetFromTag

Optional Boolean. If FALSE (default), the name of the selected recipe is returned.

If TRUE, the name of the recipe as read out of the PLC is returned if the PLC supports this and if the Recipe Version parameter tag has been given an address for reading this value.

Comments:

"RecipeBook" must be a reference to a Recipe Book tag object, not the name of the tag.


GetDatePhrase

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns a formatted date for the current user's locale
Returns: | Text
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: | GetTimePhrase | GetParmPhrase
Format: | \GetDatePhrase(Day, FormatID)
Parameters: |
Day
Required numeric. The number of days since January 1, 1970.
FormatID
Required text. The phrase identifier key specifying the date format.
See: Date and Time Phrase Keys
Comments:

The Language property in the caller's scope is used to specify the language name (e.g. en). Defaults to the Windows system's language.

Example:

  \GetDatePhrase(Today(), "DateFmtFullWritten")

returns "Apr 12, 2019", assuming that the current language is English.


GetDefaultValue

(Engine-Level Function)

Description: | Returns a variable's default value.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | SetDefault | FindVariable
Format: | GetDefaultValue(Variable)
Parameters: |
Variable
Required. Any expression for the variable value.
Comments: If the given variable does not have a default value this function will return Invalid. The current value of Variable does not affect the return value of this function.

Example:

  If ! Valid(defValue);
  [
    defValue = GetDefaultValue(FindVariable("originalVal", Self(), 0, 1));
  ]

The above statement will assign the default value of original to defValue. The reason that the statement is inside a script is because FindVariable may only appear inside a script.


GetDevices

(VoiceTalk Module)

Description: | Runs in the VoiceTalk thread and returns a list of devices available on a SAPI text-to-speech stream.
Returns: | Array
Usage: | Script Only.
Function Groups: | Speech and Sound
Related to: | Configure | GetVoices | Reset | ShowLexicon | Speak | VoiceTalk
Format: | VoiceTalkStream\GetDevices()
Parameters: |
VoiceTalkStream
Required. A speech stream returned from VoiceTalk.
Comments: This function will immediately return a 1-dimensional list of output device names available for the text-to-speech stream. The strings in this array are suitable to pass as devices to the VoiceTalk\Configure module.

Example:

  SHandle = \VoiceTalk();
  If Valid(SHandle) && ! GetDevices;
  [
    GetDevices = 1;
    SDevices = SHandle\GetDevices();
  ]

This will return an array of all available text-to-speech output devices in the array SDevices.


GetDisplayIndex

(Display Manager Library)

Description: | Returns the index of the caller's display instance.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Graphics
Related to: |
Format: | \DisplayManager.GetDisplayIndex([Context])
Parameters: |
Context
Optional. Module instance whose display instance’s index needs to be returned. If not provided, it represents the module instance which is calling this API.
Comments:

In a multi-monitor setup, the layout of the monitor indexes is straightforward. For example, a 3x2 grid of monitors is indexed as:

[1][2][3]

[4][5][6]

The primary purpose of using this API is to get the index of the display instance belonging to the specific monitor when the application is running in a multi-monitor setup. If this API is called from a single-monitor setup(not a multi-monitor), then it will always return index number 1 as there will always be a single display instance. If called by a popup page, the display index of the popup page's root page will be returned.

Example:

To fetch the index of the current module's display instance

DisplayIndex = \DisplayManager.GetDisplayIndex(Self);

or

DisplayIndex = \DisplayManager.GetDisplayIndex();


GetDisplayRoot

(System Library)

Description: | Climbs the call tree looking for the best display context.
Returns: | Window reference
Usage: | Script Only.
Function Groups: | Graphics
Related to: | VStatus
Format: | System.GetDisplayRoot(StartContext)
Parameters: |
StartContext
Optional. Local window reference for where to start looking for DisplayRoot. Defaults to Self().
Comments:

"DisplayRoot" is used as a standard variable name to identify the best context for the monitor (as defined by VStatus(DisplayRoot, 35) to use.

Any running object in an unexpected context (i.e. launched with a caller that might be in a different monitor than expected) should have its own DisplayRoot variable or parameter which is set to a context in a window on the expected monitor.

For example, the tag browser has a DisplayRoot parameter, because the tag browser is launched from many different locations with many callers. The DisplayRoot parameter allows us to specify the most natural context to use as the originating display.


GetDisplayValue

(Function Library)

Description: | Returns the value of an IO tag in a displayable format.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Function Library
Related to: | GetEquipmentColor| GetEquipmentLabel|GetParmPhrase|GetPhrase|GetPhraseID|Concat
Format: | \FunctionLib.GetDisplayValue(TagObj)
Parameters: |
TagObj
The tag whose value is formatted and returned.
Comments:

GetDisplayValue is accessible in the Function Selector. It has one parameter, (TagObj), the tag whose value you want to display.

The function returns the tag's value in a displayable format.

Analog values will show the correct number of decimal places and comma separated thousands.

Digital and discrete values will show their text according to the configuration in its Display tab settings or Style Settings tag and, optionally, their Equipment Type.

Text boxes and some widgets do not use a Style Settings tag for formatting and will override the returned values settings with their own formatting.

Expression Example:

\FunctionLib.GetDisplayValue([<Context\Tag>]\Root)

This expression fetches the value of the Tag. It the value this Tag is 1 and its display settings are set to show one decimal place, it will return "1.0" as a displayable text.

To include text together with returned value, use the concat() function:

concat("Water Level ",
\FunctionLib.GetDisplayValue([<Context\Tag>]\Root)
)

If "Tag" has the same value as before, this expression returns "Water Level 1.0".


GetEquipmentColor

(Function Library)

Description: | Returns a defined equipment color as set in a Style tag.
Returns: | Text defining a color. "<AARRGGBB>"
Usage: | Script or steady state.
Function Groups: | Color, Function Library
Related to: | GetEquipmentLabel
Format: | \FunctionLib.GetEquipmentColor( IOTagObject[, FlashNotRequired, SelectSecondary, StyleTagObject, Value])
Parameters: |
IOTagObject
Required. An I/O tag object whose Equipment parameter contains the equipment type to examine.
FlashNotRequired
Optional Boolean. Set TRUE for flash to be disabled.
SelectSecondary

Optional Boolean. Relevant only if FlashNotRequired is set TRUE or if FlashNotRequired is set FALSE and Flash is disabled in the StyleTag for the specified state of the EquipmentType.

If SelectSecondary is also set TRUE then the flash off color (secondary color) is returned.

StyleTagObject
Optional tag object. A Style tag with the desired equipment type. Defaults to the style tag used by the indicated I/O tag (which in turn defaults to System Style).
Value
Optional numeric. If the equipment style has a set of values, each with a different color, use this to select which should be returned.
Comments:

If flash is enabled in the style and not suppressed by the second parameter of this function, GetEquipmentColor will cycle between the flash-on and flash-off colors.


GetEquipmentLabel

(Function Library)

Description: | Returns a defined equipment label as set in a Style tag.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Function Library
Related to: | GetEquipmentColor
Format: | \FunctionLib.GetEquipmentLabel( IOTagObject[, StyleTagObject, Value])
Parameters: |
IOTagObject
Required. An I/O tag object whose Equipment parameter contains the equipment type to examine.
StyleTagObject
Optional tag object. A Style tag with the desired equipment type. Defaults to the style tag used by the indicated I/O tag (which in turn defaults to System Style).
Value
Optional numeric. If the equipment style has a set of values, each with a different label, use this to select which should be returned.
Comments:

None


GetFileAttribs

(Engine-Level Function)

Description: | Returns information about the specified file.
Returns: | Numeric
Usage: | Script only.
Function Groups: | File I/O
Related to: | SetFileAttribs |FileFind | Dir
Format: | GetFileAttribs(FileName[, Mode] )
Parameters: |
FileName
Required. Any text expression giving the name of the file. A known path Known Path Aliases for File-Related Functions may be provided in the form, :{KnownPathAlias}.
Mode

Optional numeric value that controls what information is returned by this function. Defaults to 0 if missing or invalid.

(See: Bitwise Parameters & Operations)

Mode:

Function Returns:

0

File attributes in the form of a value set to the sum of the following values:

Value | Bit No. | Attribute
0 | - | Normal
1 | 0 | Read only
2 | 1 | Hidden
4 | 2 | System
8 | 3 | Archive
16 | 4 | Directory

1

Timestamp showing the date modified (local)

2

File access and status flags as follows:

Value | Bit No. | Attribute
1 | 0 | Open access (i.e. the file exists and is not open-locked)
2 | 1 | Read access (i.e. the file can be read)
4 | 2 | Write access (i.e. the file can be written)
3 Timestamp showing the date modified (UTC)
Comments: The return value will vary according to Mode. See tables above.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  If StrictlyNotEqual(NewFile, OldFile);
  [
    Attribs = GetFileAttribs(Concat(MyPath, NewFile));
    OldFile = NewFile;
  ]

The above statement will cause Attribs to be set to the file attribute value of NewFile every time its name changes.


GetFullName

Security Manager Module

Description | Returns the full, namespace-qualified name of the caller’s account
Returns | String
Usage | Script or steady state.
Related to: | BuildFullName | GetAccountID | GetAccountInfo | GetGroupName | GetUserName | IsLoggedOn | IsSecured | IsSuspended | SecurityCheck | UIErrorToText | Security NameSpaces
Format | \SecurityManager.GetFullName()
Parameters | None
Comments | None


GetGroupName

Security Manager Module

Description | Returns the namespace (realm) of the caller’s account.
Returns | String
Usage | Script or steady state.
Related to: | BuildFullName | GetAccountID | GetAccountInfo | GetFullName | GetUserName | IsLoggedOn | IsSecured | IsSuspended | SecurityCheck | UIErrorToText | Security NameSpaces
Format | \SecurityManager\GetGroupName()
Parameters | None
Comments | None

Example:

  SecureRealm = \SecurityManager.GetGroupName();

Assuming that security realms are in use, SecureRealm is set to the realm name of the user currently signed in for this session / workstation.


GetGUID

(Engine-Level Function)

Description: | Creates a globally unique identifier or converts an existing GUID between the binary format used by most RPC functions and the text format used otherwise.
Returns: | Text
Usage: | Script only.
Function Groups: | Network
Related to: |
Format: | GetGUID(Format [, ExistingGUID])
Parameters: |
Format
Required numeric. Defines the format of the return value as follows
Format | Format definition
0 | 36 byte text string
1 | 16 byte binary string
ExistingGUID
An optional parameter that is any text expression for the GUID to be converted from one format to another. No default value.
Comments:

Any generated GUID will be different from all others generated on this or any other machine now or in the future. It is particularly useful in generating unique variable or file names.

The current application's GUID is stored in \LocalGUID, using the 16-byte binary form. To use this in a function that requires the GUID in text format, use: GetGUID(0, \LocalGUID);

Example 1:

The following script will cause GUID1 to be set to a globally unique 16 bit binary string and GUID2 to convert GUID1 to its 36 byte ASCII string equivalent.

  If 1 Main;
  [
    GUID1 = GetGUID(1);
    GUID2 = GetGUID(0, GUID1);
  ]

Example 2:

Obtain the current application's existing GUID as a 32-character string.

  If 1 Main;
  [
    MyGUID = GetGUID(0,\LocalGUID);
  ]


GetHistory

Deprecated. Do not use in new code.

Description: | Get History from a File written by Save or SaveHistory. This threaded function retrieves an array of data from a .DAT file for a certain time span. If the parameters to GetHistory are valid and an attempt is made to get the data, the return value is 0, otherwise, if no attempt is made to get the data, the return value is 1.
Returns: | Numeric (see discussion of the first parameter)
Usage: | Script Only.
Function Groups: | File I/O, Log
Related to: | GetHistory | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords | Get | GetLog| GetLogInfo | Save | SaveHistory | TGet
Threaded: | Yes
Format: | GetHistory(Array, File, StartTime, EndTime [, Error, PathPrefix])
Parameters: |
Array
Required. A variable that will be set to an array upon completion of the data retrieval. The format of the array is [column][record]. Column 0 is the timestamp in seconds since January 1, 1970. Each subsequent column is the data for that record. Array is not set if there is no data for the requested period.
File
Required. Any text expression giving the file name for the historical data file. The file extension must be included. If the file name is prefixed with a period, the path will be to the directory in which the module is contained.
StartTime
Required. Any numeric expression giving the start time of the period for which data is requested in seconds since January 1, 1970.
EndTime
Required. Any numeric expression giving the end time of the period for which data is requested in seconds since January 1, 1970.
Error
An optional variable that will always be set to a valid value upon completion of the GetHistory. Its meaning is as follows:
Error | Error Description
0 | No error
1 | Parameter values out of described range
2 | File could not be opened
3 | Corrupted .DAT file
4 | Field requested could not be found

If Error is not required, but PathPrefix is, then Error should be given as an Invalid value.

PathPrefix
An optional text expression parameter that enables and controls the retrieval of data from across a set of files.
Comments:

This function is threaded - that is to say, it starts its own thread and VTScada will continue executing. When it is finished executing, it will set the data in Array. Note that Array will not be initially invalidated upon execution of this statement, so if Array already contained data when the GetHistory was executed, that data will remain untouched until all of the data requested by GetHistory has been amassed, at which time Array will be set to its new value.
Because Array could conceivably remain invalid indefinitely (i.e. there was no data in the requested time span), Error will always be set to a valid value to indicate completion of execution.

There is a return value for this function that indicates if any of its parameters are invalid. The function will immediately return a value of false (0) unless a parameter was invalid, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in its thread.

If PathPrefix is specified, then this changes the interpretation of the File parameter. In this case, the referenced file is not the source of the data, but a file containing references to other files which are the data sources. This file should be in standard VTScada log file format and should contain a file reference as the first text value of each record (other values are ignored). The records should be in the correct time order with respect to the data files. The value of the PathPrefix is a string, which when prefixed to one of the file references, will yield a full pathname to the target file. If no prefix is required, but expansion of the dataset is required, then PathPrefix should be an empty string.

  • If a filename entry does NOT begin with a "\" or "<drive letter>:\", then the PathPrefix will be prepended to the filename.
  • If a filename entry DOES begin with "<drive letter>:\", then the PathPrefix will NOT be prepended to the filename.
  • If a filename entry does begin with a "\", then the "<drive letter>:" from the PathPrefix will be prepended to the filename. If there is no "<drive letter>:" in the PathPrefix then the "<drive letter>:" from the path of the File parameter will be used instead.

PathPrefix would normally be Invalid or the application path.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


GetHostByName

(Engine-Level Function)

Description: | Calls the WinSock "gethostbyname" function and returns the host name, address(es) and alias names for the named computer. Also returns additional information identifying the network interface that will be used to make a connection from the local machine to an IP returned from GetHostByName. IP addresses returned from GetHostByName are ordered by decreasing preference of use.
Returns: | Array
Usage: | Script only.
Function Groups: | Network
Related to: | WkStaInfo
Format: | GetHostByName(Name)
Parameters: |
Name
Required. Any text expression giving the host name, alias, or IP address for which information is required.
Comments:

This function will return details of the TCP/IP interface to the named computer. The return value is an array with three elements comprising a structure as follows:

Element Information

Official host name of the requested computer as known to the system. If using DNS or a similar resolution system, it is the Fully Qualified Domain Name (FQDN) that caused the server to return a reply. If using a local "hosts" file, it is the first entry after the IP address.

An array of addresses.

Each address is a text string giving a "dotted quad" address (xx.xx.xx.xx). If the name being queried is a remote machine, then there will be only one address. If the name being queried is the local machine, then there will be one address for each network interface (including RAS), and no interpretation should be placed on the ordering of the returned addresses.

Invalid, or an array of alias names.

These are alternative names, defined in the local hosts file, by which the target computer may be referenced.

If the name passed to this function is irresolvable as belonging to a computer on the network, the reply will be invalid. Depending upon the network topology, it may be several seconds before this call returns, although other threads in the application will continue to run.


GetID

(Engine-Level Function)

Description: | This returns the ID (opcode) of a given function.
Warning: | This function should be used only by advanced programmers.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications
Related to: | Compile
Format: | GetID(Statement)
Parameters: |
Statement
Required. Any expression for the code value of the function.
Comments:

This function is used by the compiler. While documented, it is not for use application developers.


GetInhibitedServiceList

(RPC Manager Library)

Description: | Returns a one-dimensional array of the names of all services inhibited from RPCManager servership control.
Returns: | Array
Usage: | Script Only.
Function Groups: | Network
Related to: |
Format: | \RPCManager\GetInhibitedServiceList([OptGUID])
Parameters: |
OptGUID
The GUID of the application in which the service instance is located. Optional, the default is the application to which the caller belongs.
Comments: Requires that the application be running.


GetINIProperty

(System Library)

Description: | Given an array of INIProperty structures, returns the value of a given property from that array.
Returns: | Value
Usage: | Script Only.
Function Groups: | Configuration Management, Variable
Related to: | CaptureSettings | ReadPropertiesFile | SetINIProperty | WritePropertiesFile
Format: | System.GetINIProperty(InputArray, Name[, Comment, pFail])
Parameters: |
InputArray
Required. An array of INIProperty structures. See Comment section.
Name
Required. The name of the property whose value is to be returned.
Comment
Optional pointer to a text value. The comment associated with the property will be returned in this field.
pFail
Optional Boolean pointer. If the property is not found, TRUE will be returned to the calling module in this parameter.
Comments:

The INIProperty structure is as follows

INIProperty Struct [
    Name        { Variable name in the .startup/.dynamic file  };
    Value       { Simple value                                 };
    Comment     { Text comment if present in the file          };
    Hidden      { TRUE if not visible in Edit Properties GUI   };
  ];

Example:

  { Read Settings.Startup file }
Init [
  If 1 Main;
  [
    TempProperties = System.ReadPropertiesFile("C:\VTScada\MyApp\Settings.Startup");
    GUID = System.GetINIProperty(TempProperties\Sections["Application"], "GUID");
    OEMGUID = System.GetINIProperty(TempProperties\Sections["Application"], "OEMGUID");
  ]
]


GetInSyncServers

(RPC Manager Library)

Description: | Returns a one-dimensional array of the names or IPs of the potential, synchronized servers for the given service.
Returns: | Array
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetInSyncServers(Service[, OptGUID])
Parameters: |
Service
Name by which the service is known.
OptGUID
The GUID of the application in which the service instance is located. Optional, the default is the application to which the caller belongs.
Comments: None


GetInstance

(Engine-Level Function)

Description: | Returns the object value of a module instance.
Warning: | This function should be used only by advanced programmers.
Returns: | Object
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Basic Module
Related to: | FindVariable | CalledInstances | NumInstances | ListInstances
Format: | GetInstance(Module, Index)
Parameters: |
Module
Required. Any expression for the code value of the module.
Index
Required. Any numeric expression indicating which instance of Module to get. The most recently started instance is instance 0.
Comments: If the number requested is larger than the total number of instances for the module, the return value will be invalid.


GetIP

(RPC Manager Library)

Description: | Returns an IP address for a workstation, given its name.
Returns: | Text
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetIP(Name)
Parameters: |
Name
Required. Any of the names by which the remote workstation is known to the RPC Manager.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System.RPCManager., and the System variable must be declared in AppRoot.src.

Related information:

RPC Manager Service


GetISOTSfromTS

(System Library)

Description: | Convert a VTScada timestamp to the ISO 8601 date and time format.
Returns: | An ISO8601 Timestamp formatted string
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | GetTSfromISOTS
Format: | GetISOTSfromTS(Timestamp[, IsUTC])
Parameters: |
Timestamp
(Required) A VTScada timestamp (e.g. 482188850)
IsUTC
(Optional) Boolean value. If TRUE (Default) the timezone is UTC. If FALSE, then the timezone is local.
Comments:

VTScada uses UTC-based timestamps stored as seconds since midnight, January 1st, 1970. (ex 482188850)

ISO 8601-style timestamps follow the format, YYYY-MM-DDThh:mm:ss (ex. 1985-04-12T23:20:50.52)

If the timezone is local (IsUTC = FALSE), the input timestamp is first converted to UTC and then formatted as ISO8601. This ensures that, regardless of the input timezone, the output is always a UTC ISO8601 string.

Example:

\System.GetISOTSfromTS(482188850)


GetKeyCount

(Engine-Level Function)

Description: | Return a count of the number of keys stored by the given dictionary.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Dictionary
Related to: | ListKeys | GetNextKey
Format: | GetKeyCount (Dictionary)
Parameters: |
Dictionary
Required. Any dictionary for which you wish to retrieve the key count.
Comments: Generally used in combination with ListKeys. The single parameter is required and must contain a dictionary, otherwise INVALID will be returned.

Example:

This function is typically used to examine a dictionary that was passed to a module as a parameter. The following demonstrates a simpler case:

Init [
  If 1 Main;
  [
    X = Dictionary();
    X["A"] = 42;
    X["B"] = 86;
    X["C"] = 99;
  ]
]
Main [
  NumKeys = GetKeyCount(X);
...

NumKeys will have the value, 3.


GetKeyParam

(Engine-Level Function)

Description: | The CryptGetKeyParam function retrieves data that governs the operations of a key. It is the VTScada analog of the CryptoAPI’s CryptGetKeyParam call.
Returns: | Varies
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | DeriveKey | Decrypt | Encrypt | ExportKey | GenerateKey | GetCryptoProvider | ImportKey | SetKeyParam
Format: | GetKeyParam(Key, Param [, Flags, Error])
Parameters: |
Key
Required. The handle to the key being queried.
Param

Required. A parameter specifying the query being made.

CAPI (Cryptography API) providers are specified using numeric identifiers. Values are defined in WinCrypt.h

CNG (Cryptography New Generation) algorithm providers are specified using text identifiers.

Flags
An optional parameter specifying the flags to be passed to CryptGetKeyParam. If omitted or invalid then the value 0 is used.
Error
An optional variable in which the error code for the function is returned. It may have the following values
Error | Meaning
0 | Key parameter successfully returned.
1 | Key or Param parameters invalid.
x | Any other value is an error from CryptGetKeyParam.
Comments: The parameter for the key is returned. If an error occurs, the return value is invalid.
The allowable values for Param vary with the key type.

Example:

[
  KeyG;
  Constant KP_G = 12 { DSS/Diffie-Hellman G value };
]
Init [
If 1 Main;
  [
    { Get the key parameter }
    KeyG = GetKeyParam(Key1, KP_G);
  ]
]


GetLastUsedSubnet

(RPC Manager Library)

Description: | Returns the last CIDR representation of the subnet or remote IP used for communication with the specified machine.
Warning: | This statement should be used by advanced users only.
Returns: | A CIDR Closed Classless Inter-Domain Routing format subnet address, or IP address.
Usage: | Script or Steady State
Function Groups: | Network
Related to: | GetSubnetPriority | GetPreferredSubnet | SetSubnetPriority
Format: | SetSubnetPriority(MachineName)
Parameters: |
MachineName
Required Text. A single string machine name of the remote system.
Comments:

If a network priority is not configured, this return value will bounce between all available subnets following the round-robin handling of RPCManager.

(See: [RPCMANAGER-NETPRIORITY] Section)


GetLiveMJPEG

(Camera Tag Module)

Description: | This is a called module. It will return a reference to the current frame retrieved from the IP camera that is connected to the camera tag.
Returns: | Text
Usage: | Steady State only.
Function Groups: | Variable
Related to: | None
Format: | \MyCameraTag.GetLiveMJPEG();
Parameters: | None
Comments:

This function is an API that acts as a data access point. The feed from the camera is a motion JPEG. Each individual frame is a JPEG image. The raw data from each JPEG image is stored within a variable as text and updated concurrently as new frames are received by the camera tag. The reference returned by the module will also be refreshed when the IP camera URL or credential has been updated in the tag configuration.

See Camera Tag. If the URL or credentials configured in the camera tag are misconfigured or irretrievable or if the camera feed is down the reference value will be invalid.

Example:

 CurrentImage = \MyCameraTag.GetLiveMJPEG();


GetLoadedAppInstance

(System Library)

Description: | Retrieves the Layer object (LayerRoot) for a particular application specified by GUID
Returns: | Layer object
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | GetAppInstance | GetCodeObj
Format: | System.GetLoadedAppInstance(GUID)
Parameters: |
GUID
Required text. The 36-byte GUID of the application to be found.
Comments:

This function is similar to GetAppInstance, but is a synchronous operation, returning the Layer object directly rather than in a pointer parameter.

If the target application is not yet loaded, then this function will return Invalid rather than wait.


GetLocalIP

(RPC Manager Library)

Description: | Returns an IP address for the local workstation that is known to the specified remote workstation.
Returns: | Text
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetLocalIP(Name);
Parameters: |
Name
Required. Any of the names by which the remote workstation is known to the RPC Manager.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

...
    \RPCManager.GetLocalIP(RemoteWorkstationName);
...

Related information:

RPC Manager Service


GetLocalNumber

(RPC Manager Library)

Description: | Returns the index of the local workstation down the prioritized server list for the named service.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetLocalNumber(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

The machine at the top of the prioritized server list will return an index of zero. If the local machine cannot be a server for the specified service, -1 is returned.

Related information:

RPC Manager Service


GetLockLevel

(Control Lock Manager)

Description: | Returns the highest lock level priority (lowest number) applied to a tag.
Returns: | Numeric
Usage: | Script or Steady State
Function Groups: | (Control Lock Manager)
Related to: | AddLock | CanAddLock | CanControl (Control Lock Manager) | CanRemoveLock | GetLockLevel | RemoveLock |
Format: | \ControlLockManager.GetLockLevel(TagID[, Snapshot])
Parameters: |
TagID
Required text. The unique ID of tag being examined.
Snapshot
Optional Boolean. Set TRUE for subroutine calls.
Comments:

None

Example:

None available.


GetLog

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | This launched module returns an array of logged data. GetTagHistory should be considered for use in new code.
Returns: | An array, stored in the first parameter (see comments)
Usage: | Script Only.
Function Groups: | File I/O, Log
Related to: | GetTagHistory
Format: | \GetLog(&Result, Tag, Name, Start, End, TPP, Size, Mode, Obsolete [, StaleTime] [, TimeZoneBias] [, EnableDownTimeOverride])
Parameters: |
Result
Required. A pointer to the array retrieved from file. The array may be multidimensional as described in the Comments section. Please review the information carefully.
Tag
Required. The object value of the tag from which to get the logged data.
Name
Required. The name of the logged value in the tag. If Invalid or a valid empty string, a timestamp is used.
It is possible to retrieve more than one field in a single GetLog statement. To do this, pass an array of values in as the Name parameter.
Typically "Value" for most tag values, or "Value!" for tag attribute data. (Value! was introduced with VTScada version 12 and is not available in legacy data. It cannot be retrieved by SQL queries.)
Start
Required. The start time in seconds since January 1, 1970.
End
Required. The end time in seconds since January 1, 1970. If invalid, Size limits the number of tags retrieved.
TPP
Required. The time span per tag. If Invalid, Size limits the number of tags retrieved.
Size
Required. The maximum number of tags to get. If greater than 0, data is accessed one at a time from file, rather than at equal time intervals. If TPP is valid, Size is ignored.
Mode
Required. Indicates the mode of data collection.
Note: The mode is useful only when the TPP parameter is valid and greater than 0. Mode may be one of:

It is possible to retrieve more than one mode in a single GetLog statement. To do this, pass an array of values in as the Mode parameter.

Mode | Data Collection
0 | Time-weighted average
1 | Minimum in range
2 | Maximum in range
3 | Change in value over the range
4 | Value at start of range
5 | TimeOfMinInRange
6 | TimeOfMaxInRange
7 | SumOfZtoNZTransitions
8 | SumOfNonZeroTime
9 | Totalizer. (Invalid is counted as zero)
10 | Deprecated. Equivalent to mode 4.
11 | Difference between the start and end values of a range (see following note)
12 | Bitwise OR (see following note)
13 | Bitwise AND (see following note)
14 | Value at end of range

Mode 11:

This is for hardware that can count to a limited number, then rolls over to start a fresh count. For example, a tag that counts equipment starts, but which can only count from 0 to 15 before wrapping around to start again. This gives a value of sixteen per roll-over since there must be one more start after fifteen to have the roll-over occur. A graph of a very simple case where there is a start every second would look like the following:

(Each rollover must be followed by a fresh start, not a gradually declining value. If there are a series of declining values then, because each is less than the previous, each counts as another rollover.)

The formula used is (RolloverCount * RolloverValue) + (LastValidValue - FirstValidValue).

Where, for any given time interval:

  • Rollovers are counted when a new value is smaller than the last valid value.
  • The RolloverValue is passed to the function in the parameter StaleTime.
  • LastValidValue starts with the last valid value in the previous time interval (if any), and is updated with each new valid value within the time interval.
  • FirstValidValue starts with the last valid value in the previous time interval (if any), and is updated with only the first valid value found in the current time span.

Given this example, suppose that you want a count of starts in each thirty-second interval. In the first interval there is no previous valid value, one wrap-around and a last valid value of 12. (1*16) + (12 - 0) = 28.

This is an idealized case. Consider a more realistic case where not all values are logged. (This may be due to factors such as polling intervals, deadbands, hardware, etc.) The following graph shows the same data where the orange dots represent values obtained and logged and the gray line represents what really happened:

In the first 30 seconds there is one roll-over when the value drops from 13 to 2. The first value is 0 and the last is 11. The Historian will return 27: (1*16) + (11-0) = 27.

The Historian will return 30 for the period from 30 to 60. The first valid value (carried from the previous period) is 11. The last valid value is 9 and there are two roll-overs. (2*16) + (9-11) = 30.

Modes 12 and 13:

These are intended to provide a summary of the bit-wise Historian value attributes within a query. (Value attributes were added in VTScada version 11.5 / 12.0)

With mode 12, the first value is OR'd with zero, and each successive value in the time period is OR'd with result of the last comparison. From the result you will know whether any particular attribute bit was set on any values within the period.

With mode 13, the first value is AND'd with a value having all bits set to 1 and each successive value is AND'd with the result of the last comparison. From the result you will know whether any particular attribute bit was set on all values within the period.

Obsolete n/a
No longer used - maintained for backward compatibility.
StaleTime
The meaning of StaleTime depends on the selected Mode.
For all Modes but 11, StaleTime sets the maximum time to propagate an old value.
For Mode 11, this is the maximum value of a range. (See comments in the Mode parameter.)
It is possible to specify more than one stale time in a single GetLog statement. To do this, pass an array of values in as the StaleTime parameter.
TimeZoneBias
Used with time zone aware reports. If included, it should be the number of seconds that your time zone differs from UTC, specified in time stamps. This is the value that would be returned from TimeZone(0).
EnableDownTimeOverride
TRUE to return Invalid for down time. Defaults to the Historian's EnableDownTime value.
Comments:

When the value of the Result parameter becomes valid, all of the data has been retrieved.

If Name is an array with more than one element, then GetLog will retrieve multiple fields from the tag. In this case, Result will be a two-dimensional array. The requested values will be returned in a manner analogous to GetHistory. That is, with the data for a column in the rightmost dimension, and the column index in the previous dimension.

When Name is specified as an array, Mode or StaleTime, or both, may be specified as either a single value or an array of values. If a single value is specified, that value will be used for each of the fields specified in Name. If an array of values is specified, the first element in the array will be applied to the first element of Name, and so on.
When TimeZoneBias is included, GetLog will translate the start and end times for the requested range of data from the local time zone to that of the server before retrieving the data. Then, before returning the retrieved data, it will translate the timestamps back to the local time zone.

Querying Value Attributes

Version 12 of VTScada introduced value attributes. These can be queried using "Value!" rather than "Value" for the field name or array of field names. Value! stores bitwise values according the following table.

Attributes flagged with a star (*) apply only if the I/O tag is attached to a DNP3 driver or a custom driver supporting this feature.

Refer to the constant, #NUM_DATA_ATTR_BITS, to discover the number of bits in data attributes for your version of VTScada.

Bit Number | Defined Constant Name | Meaning
0 | #DATA_ATTR_MANUAL_DATA | The value was from the tag's ManualData parameter
1 | #DATA_ATTR_MANUAL_ENTRY | The value was manually entered
2 | #DATA_ATTR_EDITED_DATA | The historical value was manually edited
3 | #DATA_ATTR_QUESTIONABLE | The tag was marked as questionable
4 | #DATA_ATTR_STALE_DATA | The value was reported as stale by VTSDriver
5 | #DATA_ATTR_IMPORTED | The value was imported from a CSV file
6 | #DATA_ATTR_COMMFAIL | The driver experienced a comm failure
7 | #DATA_ATTR_QUALITY | The tag has marked the value as unreliable
8 | #DATA_ATTR_DRIVER_COMMFAIL | The PLC reported a downstream comm failure
9 | #DATA_ATTR_DRIVER_QUALITY | The PLC reported the value may be unreliable
10 | #DATA_ATTR_DRIVER_OVERRIDDEN | (*) The PLC reported the value was overridden
11 | #DATA_ATTR_DRIVER_NODATA | (*) The PLC reported there is no data available

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

This module executes in parallel to the launching code. Watch for the return array to be filled with valid data to determine when it has finished.

Example:

  If 1 Loop;
  [
     { Setup the TimeZone Bias }
    TZBias  = \IsTimeZoneAware ? TimeZone(0) : Invalid;

     { Set up the fieldnames, modes & staletime arrays for Getlog }
    FieldNames     = New(5);
    FieldNames[0]  = Invalid { Timestamps };
    FieldNames[1]  = "Quality";
    FieldNames[2]  = "SuccessCount";
    FieldNames[3]  = "ErrorValue";
    FieldNames[4]  = "ErrorAddress";

    Modes          = New(5);
    Modes[0]       =
    Modes[1]       =
    Modes[2]       =
    Modes[3]       =
    Modes[4]       = Invalid;

     { Retrieve Data for the first tag }
    \GetLog(&TagData,
            Scope(\Code, Tags[TagIndex]) { Point object value      },
            FieldNames                   { Read data               },
            Start                        { Start time              },
            End                          { End time                },
            Invalid                      { Time per point          },
            #NUMRECLIMIT                 { No max number of recs   },
            Modes                        { Modes                   },
            Invalid                      { Obsolete                },
            Invalid                      { Stale Time              },
            TZBias                       { TimeZone Bias           });


GetLogInfo

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Interrogates a historical data file, or a set of historical data files, and returns overall time, date, and record count information either for the entire file(set), or for a specified time range.
Returns: | Nothing (data returned in parameters)
Usage: | Script Only.
Function Groups: | File I/O, Log
Related to: | GetLogInfo | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords | Get | GetHistory | Save | SaveHistory | TGet
Format: | GetLogInfo(File, Earliest, Latest, NRecords [, PathPrefix, StartTime, EndTime]);
Parameters: |
File
Required. The historical data file (or index file for a file set) for which information is required.
Earliest
Required. Any variable in which will be returned the earliest time stamp from the file(set).
Latest
Required. Any variable in which will be returned the latest time stamp from the file(set).
NRecords
Required. Any variable in which will be returned the total number of records in the file(set).
PathPrefix
An optional text expression parameter that enables and controls the retrieval of data from across a set of files.
StartTime
An optional timestamp parameter that defines the start time of the range to be examined.
EndTime
An optional timestamp parameter which defines the end time of the range to be examined.
Comments:

For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be Invalid.
All timestamps are specified in seconds since January 1, 1970.
If the number of records found is zero, then Earliest and Latest are both set Invalid.
If PathPrefix is specified, then this changes the interpretation of the File parameter. In this case, the referenced file is not the source of the data, but a file containing references to other files which are the data sources. This file should be in standard VTScada logfile format and should contain a file reference as the first text value of each record (other values are ignored). The records should be in the correct time order with respect to the data files. The value of the PathPrefix is a string, which when prefixed to one of the file references, will yield a full pathname to the target file. If no prefix is required, but expansion of the dataset is required, then PathPrefix should be an empty string.

  • If a filename entry does NOT begin with a "\" or "<drive letter>:\", then the PathPrefix will be prepended to the filename.
  • If a filename entry DOES begin with "<drive letter>:\", then the PathPrefix will NOT be prepended to the filename.
  • If a filename entry does begin with a "\", then the "<drive letter>:" from the PathPrefix will be prepended to the filename. If there is no "<drive letter>:" in the PathPrefix then the "<drive letter>:" from the path of the File parameter will be used instead.

PathPrefix would normally be Invalid or the application path.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


GetLogonCredentialsFromSmartcard

(Engine-Level Function)

Description: | Monitors the card reader for a smartcard and reads the certificate information from it. If Multiple usable certificates are found (useable defined as the presence of subject alternate name field), It will spawn a windows certificate selector and use the certificate returned by that.
Warning: | This function should be used only by advanced programmers.
Returns: | Boolean. Set to TRUE if a card was present. Outputs the Marshalled credential of the certificate, the UPN, and the sha1 hash of the certificate in the parameters.
Usage: | Script Only.
Function Groups: | Security
Related to: | WindowsLogon
Format: | GetLogonCredentialsFromSmartcard(MarshalledCredential, Username, Sha1)
Parameters: |
MarshalledCredential
Required. The marshalled credential used with WindowsLogon
Username
Required text. A variable in which the username found in the certificate will be returned in UPN format (e.g. a.user@example.com). This is not a VTScada user name.
Sha1
Required. A variable in which the variable the Sha1 hash of the certificate will be returned.
Comments: Only one instance of the function should be run on a system at once. Having multiple instances of the function can result in multiple certificate dialogs spawning for a single card insertion event. The function monitors the card reader in its own thread, so it doesn’t cause any blocking.


GetMachineNode

(RPC Manager Library)

Description: | Returns the object value of the MachineNode for the specified name or IP.
Returns: | Object
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetMachineNode(Name);
Parameters: |
Name
Required. Any of the names or IPs by which the workstation is known to the RPC Manager.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

Related information:

RPC Manager Service


GetMakeAltPtr

(RPC Manager Library)

Description: | Returns a pointer to a variable containing the Alternate status for the local service instance in the calling application for the specified service. Steady state or subroutine call.
Returns: | Pointer
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetMakeAltPtr(Service);
Parameters: |
Service
Required. The name by which the service is known.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

Related information:

RPC Manager Service


GetModuleContext

(Engine-Level Function)

Description: | Given a module-in-context, this function returns the parent object of an instance of that module when it is launched or called.
Warning: | This function should be used only by advanced programmers.
Returns: | A reference to the context module where scope of the given module should be resolved.
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | GetInstance | GetModuleText
Format: | \GetModuleContext(ModuleInContext)
Parameters: |
ModuleInContext
Required. A module-in-context object.
Comments: A "module-in-context" is a reference to a module associated to a specific context, or module instance. Refer to value type 49 in VTScada Value Types.

Examples:

A somewhat contrived example...

[
  Me;
  ChildModuleObj;
  Context;
  MyModuleInContext;
  Graphics Module;
]

Main [
  If Watch(1);
  [
    Me = GetInstance(self(), 0);
    MyModuleInContext = Me.Graphics;
    Context = GetModuleContext(MyModuleInContext); { Context == ParentObject }
    ChildModuleObj = MyModuleInContext();  { Context == ParentObject(ChildModuleObj) }
  ]
]

<
Graphics
()
[ ]
Main [

]
>

"Me" will hold a reference to the module shown above, which in this in this case is Overview. (The overview page)

MyModuleInContext will hold a reference to the Graphics submodule

Context will be the same as Me.

ChildModuleObj will be the same as MyModuleInContext.


GetModuleRefBox

(Engine-Level Function)

Description: | Returns the outer reference box for any selectable (GUI) graphics in a module.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Advanced Module, Graphics
Related to: | GetXformRefBox | SetModuleRefBox
Format: | GetModuleRefBox(Module, Option)
Parameters: |
Module
Required. Any expression for the code value of the module.
Option
Required. Any expression that defines the return value as indicated by the following:
Option | Return Value
0 | left side
1 | bottom side
2 | right side
3 | top side
4 | width
5 | height
Comments:

A module's reference box defines an area that will exactly enclose all layered (GUI) graphics in the module regardless of state before any rotations and trajectories have been applied. A module reference box, or MRB as it is sometimes called, is not a clipping region and objects can and often will extend outside of their MRB as a result of applied rotations or trajectories.

When a module is transformed, the transform is based on the size of the module as determined by its reference box. The module's reference box will always exactly fill the reference box of the transform. In the case of graphics that have had a rotation or trajectory applied to them, the graphics will be transformed correctly, but the MRB may no longer contain the objects in their modified positions.

If a SetModuleRefBox has been done within the module in question, or its module reference box has been defined by following the module name with the four boundaries enclosed in parentheses, the return value will be based on these explicitly defined boundaries. Otherwise the return value will define the minimum reference box that will exactly enclose all (GUI) graphics in the module. This does not include any child graphics (i.e. graphics created by child modules of Module).
Module does not need to be running at the time that this statement is called to retrieve valid data.

Example:

  If ! Valid(rightSide);
  [
    rightSide = GetModuleRefBox(Self(), 2);
  ]

Variable rightSide will contain the X-coordinate for the graphic object drawn by this module that is the furthest right in the window.


GetModuleText

(Engine-Level Function)

Description: | Returns information about a module's document file.
Warning: | This function should be used only by advanced programmers.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AdjustCode | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize | GetModuleTimeStamp
Format: | GetModuleText(Module, Info)
Parameters: |
Module
Required. Any expression for the module.
Info
Required. Any numeric expression giving the information to return, as shown in the following table:
Info | Information to return
0 | File name which defines Module
1 | Character offset to beginning of Module
2 | Length of Module
3 | Character offset to beginning of parameter definitions
4 | Character offset to beginning of variable definitions
5 | Character offset to beginning of state definitions
6 | Character offset to beginning of child module definitions
7 | Character offset to first variable definition
8 | Length of variable definitions
9 | Character offset to first parameter definition
10 | Length of parameter definitions
Comments:

This function is used when automatically modifying modules.

The file name (Info == 0) will include the full path. and will refer to the version of the module within the .sync folders, not the version in the user-acessible folders.

Example:

  If Watch(1);
  [
    ModuleFilename = GetModuleText(Self(), 0);


GetModuleTimeStamp

(Engine-Level Function)

Description: | Returns the timestamp of the module's source file, showing the last time it was synchronized with the application.
Returns: | Numeric. (Timestamp as a double)
Usage: | Script Only.
Function Groups: | Modules - Basic
Related to: | GetModuleText
Format: | GetModuleTimestamp(Module)
Parameters: |
Module

Required. An object reference to the module whose source code file timestamp you are interested in obtaining.

Comments:

The return value is a double that is the timestamp of the module's source file the last time the ResyncDoc was called for the module in question.

ResyncDoc is called by the core product during compilation as well as during page / widget editing actions. This provides a quick way to get the timestamp of the module's SRC file at the time it was edited.


GetNameOfRecord

(Alarm Manager module)

Description: | Given an alarm record, returns the tag name.
Returns: | Text
Usage: | Script Only.
Function Groups: | Alarm
Related to: | GetAlarmObject
Format: | \AlarmManager.GetNameOfRecord(AlarmRecord[, ParentTag])
Parameters: |
AlarmRecord
Required record. A reference to the alarm, as returned by the function GetAlarmObject.
ParentTag
Optional. The parent tag's name. If valid, this value will be stripped from the result.
Comments:

This function is intended primarily for presentation purposes.

The function will return whichever of the following, in order, for which it can find a valid value: the relative tag name, the full name, or the unique ID (alarm name).

Example:

 { Given an array of alarm records, get the tag object from the alarm name whenever
   the array index, SelRecord, changes.  }
  If Watch(1, Records[SelRecord]\GUID);
  [
    \AlarmManager.GetAlarmObject(Records[SelRecord]\Name, &Root);
    ShortName = \AlarmManager.GetNameOfRecord(Records[SelRecord]);
  ]


GetNextKey

(Engine-Level Function)

Description: | Allows a linear search through a dictionary.
Returns: | Varies according to the stored values. (Returns values, not keys.)
Usage: | Script Only.
Function Groups: | Dictionary
Related to: | Dictionary | MetaData | DictionaryCopy | DictionaryRemove | ListKeys
Format: | GetNextKey(Dictionary[, StartKey, Order, KeyName ] )
Parameters: |
Dictionary
Required. Any dictionary you wish to search.
StartKey
Optional. The key, from which to start.
If this is invalid, or if the key is not found in the dictionary, then the first key in the given order will be returned.
Order
An optional numeric expression. Defines the search according to the following table of values. Defaults to 0 if missing. Setting this parameter to Invalid will result in the function returning Invalid.
Order | Meaning
0 | Forward alphabetic search
1 | Forward ordinal search. Returns the value associated with the next newer key. Begins at the oldest key if the parameter Key is invalid.
2 | Backward alphabetic search
3 | Backward ordinal search. Returns the value associated with the next older key. Begins at the newest key if the parameter Key is invalid.
KeyName
This parameter will receive the key of the record found, which matches with the value of that record returned by the function. If there are no further keys in the given order, this value will be set to INVALID.

Comments:

In spite of this function's name, the return value is not the key but the value associated with the key found, or INVALID if no key was found. The matching key can be obtained from the fourth parameter.

Example:

    Result_str = "";
    MyDict = Dictionary();
    MyDict["key4"] = "contents4";
    MyDict["key1"] = "contents1";
    MyDict["key3"] = "contents3";
    MyDict["key2"] = "contents2";
    CurVal = GetNextKey(myDict, Invalid, 0, curKey);
    WhileLoop(Valid(curKey),
      Result_str = Concat(Result_str, " """, CurVal, """");
      CurVal     = GetNextKey(MyDict, CurKey, 0, CurKey);
    );

Result_str will be: "contents1" "contents2" "contents3" "contents4"


GetNumUnacked

(Alarm Manager module)

Description: | Returns either the number of unacknowledged alarms or a Yes/No flag to indicate that the alarms exist. Note that this function will place a heavy load on computer resources while searching. Subject to the current user's Realm Filtering limitations.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | DBListGet | GetAlarmList
Format: | \AlarmManager.GetNumUnacked(UserFilter, ReturnYesNoFlag);
Parameters: |
UserFilter
Obsolete. Set to Invalid.
ReturnYesNoFlag
Required. A Boolean that controls the result returned by the function.
If true, only a 1 or a 0 will be returned, indicating whether unacknowledged alarms were found.
If false, the number of unacknowledged alarms will be returned.

Example:

  NumUnacked = \AlarmManager.GetNumUnacked(Invalid,  FALSE);

If filtering is required, use GetAlarmList.


GetOEMLayer

Description: | Retrieves the layer root module of the OEM layer (should one exist) of the layer this is called against.
Returns: | A pointer (within the parameter)
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | GetWCPath |
Format: | \AppLayer.GetOEMLayer(&OEMLayerPtr)
Parameters: |
OEMLayerPtr
Required. A variable, into which a pointer to the OEM layer's root module will be placed.
Comments: The return value of the function will be set to Invalid upon completion. A pointer to the OEM layer's module will be returned in the first parameter to this function.


GetOneParmText

(Engine-Level Function)

Description: | Returns the text for one parameter of a function.
Warning: | This function should be used only by advanced programmers.
Returns: | Text
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AdjustCode | GetModuleText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | GetOneParmText(Function, Parameter[, Type])
Parameters: |
Function
Required. Any expression for the code value of the function.
Parameter
Required. Any numeric expression indicating which parameter's text to return.
Type
Optional numeric expression. Controls what will be returned by the function according to the following table:
Type | Description
0 | default. Return the text for the parameter.
1 | Return the offset in the file for the start of the parameter.
2 | Return the size (number of bytes) of the parameter.


GetOPCServerRequestRate

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns the total number of OPC Classic callbacks per second.
Returns: | Numeric value
Usage: | Script or steady state.
Function Groups: | Network & Workstation
Related to: |
Format: | GetOPCServerRequestRate()
Parameters: |
Comments:

Related information:

OPCServerRequestRateThreshold

OPCServerRequestRefreshPeriod


GetOutputTypes

Description: | Returns a list of available report output type plugins.
Returns: | Array
Usage: | Script Only.
Function Groups: | Report
Related to: | GetReportTypes
Format: | \ReportPanel\GetOutputTypes(PtrTypeNames, PtrTypeMods)
Parameters: |
PtrTypeNames
Required. A pointer to a variable storing output names.
PtrTypeMods
Required. A pointer to a variable storing output module names.
Comments: This subroutine, declared in ReportPanel, is a plug-in to help with custom retrieval of output types. GetOutputTypes must be prefaced by \ReportPanel\, as shown in the "Format" section above.


GetOverrides

(Engine-Level Function)

Description | Returns an array of OpCodes and the module value that will run when each OpCode is executed
Warning | This function should be used only by advanced programmers.
Returns | 2-dimensional array
Usage | Script Only.
Function Groups | Compilation and On-Line Modifications, Advanced Module
Related to: | SetOverride
Format | GetOverrides(TargetModule)
Parameters |
TargetModule
Required. Any expression that can be resolved to a module value.
Comments

The target module will be queried for a list of overridden OpCodes. The return value is a 2 dimensional array where the first dimension is the override as set by SetOverride and second dimension will be [0] for the OpCode and [1] for the corresponding module that has been set to override that opcode.

Together with SetOverride, this provides the ability to override a built-in function in a module with a module call. It is used primarily for testing. See SetOverride for full details.


GetParameter

(Engine-Level Function)

Description: | Returns the requested parameters as a constant, variable or code pointer.
Warning: | This function should be used only by advanced programmers.
Returns: | Constant, variable or code value.
Usage: | Script Only.
Function Groups: | Advanced Module
Related to: |
Format: | GetParameter(\Code, Index)
Parameters: |
Code
Required. Any expression for the code value or code pointer of the function.
Index
Required. Parameter number to obtain. Starts with 0 for the first parameter.
Comments:

If the parameter being retrieved is a constant number, then GetParameter just returns that number. The same goes for a constant string parameter.

If the parameter is just a variable, then GetParameter returns the variable (a value of type \#VTypeVariable).

If the parameter is itself a function, then GetParameter returns a code value for it.


GetParmPhrase

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns parameterized text in the currently selected language for a given phrase identifier key.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: | GetPhrase | GetParmPhraseForLang | GetPhraseID
Format: | \GetParmPhrase(PhraseKey, P0[, P1, P2, P3, P4, P5, P6, P7, P8, P9])
Parameters: |
PhraseKey
Required. The identifying key for a phrase. May be a string ID that uniquely identifies given text.

P0, with optional parameters through P9

or

PhraseDictionary

In versions to 12.1.38 this could be any text that will be substituted into placeholders in the phrase matching the index of the parameter. (%0 through %9)

As of version 12.1.29 this could also be a single dictionary. See comments.

Comments:

The phrase need not have the %n placeholders in ascending numerical order, and parameters can to be used more than once. Some translations may not require a parameter at all while other parameters may occur multiple times. A maximum of 10 parameters are supported.

The Language property in the caller's scope is used to specify the language name (e.g. en). Defaults to the Windows system's language.

If using a phrase dictionary instead of one or more text phrases, the replaceable parameters can be named rather than numbered. For example:

This report for %[TagName] was created on %[RunTime] %[RunDate]

The matching dictionary would have the form:

PhraseDict = Dictionary();
PhraseDict["TagName"] = "Station 1";
PhraseDict["RunTime"] = "2:23 PM";
PhraseDict["RunDate"] = "Feb 26, 2024";

As a specialized use-case, GetParmPhrase also supports the use of translation dictionaries for the PhraseKey parameter. Use the following information only in the rare case that a standard .csv file of static translations is not suitable.

Translation dictionaries should take the following form, which is used in place of the PhraseKey parameter:

System.MakeDictionary("en", "hello", "fr", "bonjour", "es", "hola");

GetParmPhrase will then return the translation corresponding to the user's current language. If the dictionary does not include a translation for the user's current language but does for the default language, then the default will be returned. If that also does not exist, then return "Missing translation" (language dependent).

Note that the phrase may not update dynamically when the content for a given key in the dictionary changes.

Translation dictionaries should not be used in most applications.

Example:

Suppose that "TPPhrase" is the key for a phrase that has English and French definitions as follows:

English: Pump is %0

French: La pompe est %0

Suppose also that "Running" is a Boolean variable you are using to monitor the pump's status. Then...

\GetParmPhrase("TPPhrase", Running ? \GetPhrase("RunningLabel") : \GetPhrase("StoppedLabel"));

... will say that the pump is running or stopped in either French or English depending on the state of the pump at the time this runs.


GetParmPhraseForLang

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns parameterized text in the specified language for a given phrase identifier key or ParmPhrase structure.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: | GetParmPhrase | GetDatePhrase | GetTimePhrase
Format: | \GetParmPhraseForLang(PhraseKey, Language[, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9])
Parameters: |
PhraseKey
Required. The identifying key for a phrase. May be either a string ID that uniquely identifies given text or a ParmPhrase structure, which consists of a PhraseID and up to 10 parameters.
Language
Required text. Name of the language for which the phrase is to be found. For example "EN" for English.
P0 through P9
Any text that will be substituted into placeholders in the phrase matching the index of the parameter. (%0 through %9)
Comments:

For most purposes, \GetParmPhrase is preferred over \GetParmPhraseForLang, since \GetParmPhrase will use the currently logged-on user's selected language (or default to English).

Example:

  \GetParmPhraseForLang("FileMessageID", \ErrorLang, PickValid(SomeFileName, "")

returns the text for a hypothetical file message label using the language (assigned elsewhere) for error messages, and including the name of a file to which the message applies.


GetParmText

(Engine-Level Function)

Description: | Returns the text for all parameters of a function.
Warning: | This function should be used only by advanced programmers.
Returns: | Text array
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText| SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | GetParmText(Function)
Parameters: |
Function
Required. Any expression for the code value of the function.
Comments: This function may only appear in a script.


GetParserOffset

(Engine-Level Function)

Description: | Returns the offset before the last compiled statement.
Warning: | This function should be used only by advanced programmers.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications
Related to: | Compile
Format: | GetParserOffset(ParserStack)
Parameters: |
ParserStack
Required. Any expression for the parser stack value.
Comments: This is used by the compiler to give the location of an error.


GetPathBound

(Engine-Level Function)

Description: | Returns the bounding box coordinates for a path.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | GetModuleRefBox | Path
Format: | GetPathBound(Path, Object, Transform, Side)
Parameters: |
Path
Required. Any expression that returns a Path value.
Object
Required. Any object expression which defines the window where Path is drawn.
Transform
Required. Any expression for the transform value applied to Path.
Side
Required. Any numeric expression for the coordinate to return:
Side | Side to Return
0 | Left
1 | Bottom
2 | Right
3 | Top

Comments:

Seldom used in modern applications.


GetPhrase

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns text in the currently selected language for a given phrase identifier key or ParmPhrase structure.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: | GetParmPhrase | GetDatePhrase | GetTimePhrase | GetPhraseForLang |GetRawPhrase | GetPhraseID
Format: | \GetPhrase(PhraseKey)
Parameters: |
PhraseKey

Required. The identifying key for a phrase.

May be either a string that uniquely identifies given text or a ParmPhrase structure, which consists of a PhraseKey and up to 10 parameters.

Comments:

If the input is a ParmPhrase, \GetPhrase will recursively translate the phrase.

In the input is just text (not a phrase key) then it will be passed back unchanged. \GetPhrase("Hello World") returns "Hello World".

If working with parameterized phrases, \GetParmPhrase may be preferred in order to avoid the effort of assembling a ParmPhrase structure, which can be built only in Script.

When called in the context of a user session (e.g. from user-interface code such as a page), the phrase will be returned in the user's currently selected language. Otherwise, the phrase will be returned in the application's default language as specified in the Languages panel of the Application Configuration dialog.

As a specialized use-case, GetPhrase also supports the use of translation dictionaries. Use the following information only in the rare case that a standard .csv file of static translations is not suitable.

Translation dictionaries should take the following form, which is used in place of the PhraseKey parameter:

System.MakeDictionary("en", "hello", "fr", "bonjour", "es", "hola");

GetPhrase will then return the translation corresponding to the user's current language. If the dictionary does not include a translation for the user's current language but does for the default language, then the default will be returned. If that also does not exist, then return "Missing translation" (language dependent).

Note that the phrase may not update dynamically when the content for a given key in the dictionary changes.

Translation dictionaries should not be used in most applications.

Example:

  \GetPhrase("OKLabel")

returns "OK", assuming that the current language is English.


GetPhraseID

(Function Library)

Description: | Returns the key matching a given phrase.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | String
Related to: | GetPhrase | GetPhraseForLang | GetParmPhrase
Format: | \FunctionLib.GetPhraseID(Phrase[, Language, Index])
Parameters: |
Phrase
Text, for which you want to retrieve the key.
Language
Optional Text. The two-letter code specifying the language in which to look for the phrase. Defaults to the user's currently selected language.
Index
Optional Numeric. Some words may be present several times, each with a different meaning. (For example, "right" might be the opposite of "left", it might indicate that something is correct, or it may refer to an entitlement.)
Comments:

This module is a member of the Function Library, and must therefore be prefaced by \FunctionLib as shown in the "Format" section.

Searches only the application's language files, not those belonging to VTScada.

Example:

  \FunctionLib.GetPhraseID("Test description")

Will return the phrase key for "Test description", assuming that some tag was given that as a description.


GetPhraseForLang

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns text in the specified language for a given phrase identifier key or ParmPhrase structure.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: | GetPhrase | GetParmPhrase | GetDatePhrase | GetTimePhrase | GetRawPhrase |
Format: | \GetPhraseForLang(PhraseID, Language[, LMHolder])
Parameters: |
PhraseKey
Required. The identifying key for a phrase. May be either a string ID that uniquely identifies given text or a ParmPhrase structure, which consists of a PhraseKey and up to 10 parameters.
Language
Required text. Name of the language for which the phrase is to be found.
LMHolder
Optional. An instance of the user session where the current language is set. Defaults to the system’s root object. Useful only when a very large number of \GetPhraseForLang calls are issued consecutively.
Comments:

For most purposes, \GetPhrase is preferred over \GetPhraseForLang, since \GetPhrase will use the currently logged-on user's selected language (or default to English).

Example:

  \GetPhraseForLang("CloseLabel", ErrorLang)

returns the text for the file close label, in the language (assigned elsewhere) for error messages.


GetPlatformInfo

Description: | Gathers information about the current application and the workstation it is running on.
Returns: | Numeric status indicator. (Platform information is returned in the parameter)
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | Platform | WKStaInfo
Format: | \AppLayer.GetPlatformInfo(&Info)
Parameters: |
&Info
Required. Pointer to a variable. The information gathered will be returned in a structure that this variable points to.
Comments:

This utility function makes use of WkStaInfo and Platform to gather relevant information about the application. The structure returned has the following format:

INIFiles Struct [
  FileName    { file name and extension for the file                 };
  OEM         { TRUE if an OEM layer file                            };
  Workstation { Name of the workstation or invalid if global         };
  Layer       { Instance of application layer owning the file        };
  Dynamic     { TRUE if a dynamic property                           };
  Sections    { Dictionary of sections, each element of which
is an array of Property structures (see following)       };
  Changed     { User sets to true if the file has been changed,
initialized to false                                 };
]

The property structures have the following format:

INIProperty Struct [
  Name    { Variable name in the settings file                        };
  Value   { Simple value or an ordered array of values if the
variable occurs more than once in the section of the file };
  Comment { Text comment if present in the file                       };
  Hidden  { TRUE if not shown in the Edit Properties GUI              };
]


GetPowerState

(Engine-Level Function)

Description: | Returns a structure that holds details of the computer's power supply status.
Returns: | Structure containing four elements
Usage: | Steady State only.
Function Groups: | Network & Workstation
Related to: |
Format: | GetPowerState()
Parameters: | none

Comments:

This function is intended for use when the workstation is running on battery power, whether UPS or laptop battery. The return structure contains the following elements:

PowerStatus

Short. AC line status.

0 == Offline

1 == Online

255 == Unknown status.

BatteryState

Short. Indicates the battery charge status as follows:

1 == High

2 == Low

4 == Critical

8 == Charging

128 == No system battery

255 == Unknown status.

BatteryLevel

Short. The remaining charge in the battery, expressed as a percentage.

BatteryLifetime

Double. Estimated number of seconds of charge remaining in battery.

Examples:

  { Display selected page name on the title bar }
  PowerState = GetPowerState();


GetPreferredSubnet

(RPC Manager Library)

Description: | Returns the highest priority CIDR representation of subnet for the given machine name.
Warning: | This statement should be used by advanced users only.
Returns: | A CIDR Closed Classless Inter-Domain Routing format subnet address matching that provided in the NetPriority section or as provided to SetSubnetPriority
Usage: | Script or Steady State
Function Groups: | Network
Related to: | GetSubnetPriority |GetLastUsedSubnet | SetSubnetPriority
Format: | GetPreferredSubnet(RemoteMachine)
Parameters: |
RemoteMachine
Required text. A single string for the machine name of the remote system.
Comments:

Any setting done through this module is lost on restart of VTScada.

Returns a valid CIDR format string only if a priority is configured for the local system.

(See: [RPCMANAGER-NETPRIORITY] Section)


GetRawPhrase

Description: | Returns a phrase in the provided language, if it exists.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: | GetParmPhrase | GetDatePhrase | GetTimePhrase
Format: | \AppLayer.GetRawPhrase(PhraseID, Language)
Parameters: |
PhraseID
Required. The identifying key for a phrase. May be either a string ID that uniquely identifies given text or a ParmPhrase structure, which consists of a PhraseID and up to 10 parameters.
LanguageID
Required text. Name of the language for which the phrase is to be found.
Comments:

Unlike \GetPhrase there is no defaulting to the default language or the PhraseID itself.

Also, this will not look at strings provided by subordinate applications.

Example:

  Info = \AppLayer.GetRawPhrase("2Far18NearLabel", "EN");
  ZText(100,100,Info, 0, 0);


GetRecipes

(Recipe Book module)

Description: | Returns an array of the recipes found in the selected recipe book
Returns: | Array of text
Usage: | Script Only.
Function Groups: | Recipe Book
Related to: | |GetVersions | GetCurrentRecipe | GetCurrentVersion | SetCurrentRecipe | SetCurrentVersion |
Format: | RecipeBook.GetRecipes()
Parameters: | None
Comments:

"RecipeBook" must be a reference to a Recipe Book tag object, not the name of the tag.

Returns a sorted list of the recipe phrase keys (not names) in the recipe book. The keys will be returned in alphabetic order of the names as those would appear in the current user's language.


GetReferencedValues

(Engine-Level Function)

Description: | Collects all dynamically referenced values in the call tree rooted at the parameter and returns them in an array. Returns Invalid if none are found.
Warning | This function should be used only by advanced programmers.
Returns: | Array
Usage: | Script Only.
Function Groups: | Variable Functions
Related to: |
Format: | GetReferencedValues(Object)
Parameters: |
Object
Required. The object for which referenced values are to be found.
Comments:

Examples:

{ Get an array of pointers to all values scoped-to in the call tree rooted at PageObj. }
    ReferencedVals = GetReferencedValues(PageObj);


GetRetainedValue

(Engine-Level Function)

Description: | Given the name of a variable whose value was retained, this function will load the retained value from storage. The function also provides the option of deleting the files holding that value.
Returns: | Varies
Usage: | Script Only.
Function Groups: | Variable
Related to: | nothing
Format: | GetRetainedValue(Instance, VariableName[, SharedFlag, DeleteFlag]);
Parameters: |
Instance

Required object. The module instance for which we want to load the value.

VariableName
Required text. The name of the variable to load.
SharedFlag
Optional Boolean. Set TRUE to indicate that the variable was shared. Defaults to FALSE.
DeleteFlag
Optional Boolean. Set TRUE to delete the files storing the retained variable for the identified module.

Comments

This function is used to work with the storage files left behind after changing your code such that a variable that had been retained is no longer used or no longer retained. You are advised to avoid using this function with variables that continue to be retained.

If an operation is in progress elsewhere to set a new value for the variable, this function will not detect that operation nor wait for it. In this case, it is possible for the returned value to differ from the new current value.

The DeleteFlag will be ignored if the variable is still being retained. You can delete the stored value only after removing the variable from your code or re-declaring the variable without the Retained flag (and recompiling your module).

If the value is a static array, this function will return it as a dynamic array.

Example:

Given a retained variable, SaveValue, that was used for a set of operations, but that should not be left in existence between restarts, you can remove it as follows:

  If Valid(SaveValue);
  [
     { All machines should delete the Retained file to avoid this triggering
       on some future restart. }
    TempSaveValue = GetRetainedValue(Caller(Self), "SaveValue", FALSE { Shared }, TRUE { Delete });


GetRemoteVersion

(RPC Manager Library)

Description: | Returns the version number of VTScada running on a specified workstation. Steady state or subroutine call.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Network
Related to: | Version
Format: | \RPCManager.GetRemoteVersion(NameOrIP);
Parameters: |
NameOrIP
Required. Any of the names or IPs by which the workstation is known to the RPC Manager.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

Related information:

RPC Manager Service


GetReportTypes

Description: | This subroutine returns a list of available report type plugins.
Returns: | Array
Usage: | Script Only.
Function Groups: | Report
Related to: | GetOutputTypes
Format: | \ReportPanel.GetReportTypes(PtrTypeNames, PtrTypeMods)
Parameters: |
PtrTypeNames
Required. A pointer to a variable storing report names.
PtrTypeMods
Required. A pointer to a variable storing report module names.
Comments: This subroutine, declared in ReportPanel, is a plugin to help with custom retrieval of report types. GetReportTypes must be prefaced by \ReportPanel\, as shown in the "Format" section above.


GetReturnValue

(Engine-Level Function)

Description: | Returns a module's return value.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Basic Module
Related to: | Return | ResetParm
Format: | GetReturnValue(Object)
Parameters: |
Object
Required. An object expression for the module instance whose return value is required.
Comments: While the description seems redundant, this function is useful for obtaining a return value from a module that has been called as a parameter to another module, and whose return value has been or will be altered by a ResetParm statement.

Example:

A typical use:

SubReturn [
  If 1 Main;
  [
    Return(GetReturnValue(Self), FALSE);
  ]
]


GetSelected

(Engine-Level Function)

Description: | Returns a selected graphic item in a window.
Returns: | Object
Usage: | Script Only.
Function Groups: | Graphics
Related to: | GetSelectedInfo
Format: | GetSelected(Object)
Parameters: |
Object
Required. Any object expression for the window containing selected graphics.
Comments: This function may only appear in a script.


GetSelectedInfo

(Engine-Level Function)

Description: | Returns information about selected graphic item(s) in a window.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | CurrentWindow | GetSelected
Format: | GetSelectedInfo(Object, Mode)
Parameters: |
Object
Required. Any object expression for the window containing selected graphics.
Mode
Required. Any numeric expression that defines what information to return:
Mode | Information to return
0 | Minimum left side user coordinate
1 | Minimum bottom side user coordinate
2 | Maximum right side user coordinate
3 | Maximum top side user coordinate
Comments: If no graphic objects are selected, the return value will be meaningless.

Example:

  sel = GetSelectedInfo(CurrentWindow(), 0);

This statement will set sel to the minimum left side (user) coordinate out of all selected graphic objects that are in the VTScada window that the mouse is over.


GetServer

(RPC Manager Library)

Description: | Returns the name of the active server for a specified service.
Returns: | Text
Usage: | Steady State only.
Function Groups: | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetServersListed | GetStatus | IsClient | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | Send | SetRemoteValue | GetGUID
Format: | \RPCManager.GetServer(ServiceName [, OptGUID])
Parameters: |
ServiceName
Required. Any text expression giving the name of the service for which to get the active server's name.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
If the 16-byte binary format of the GUID is not known, the GetGUID function may be used to obtain it.

To obtain a list of service names for your application, open the Trace Viewer Application, connect to RPC Diagnostics, then open the Services Dialog

Example:

  SName = \RPCManager.GetServer("ModemManager");

Related information:

RPC Manager Service


GetServerChanges

(RPC Manager Library)

Description: | Launched by RPC Manager on a service server to obtain the service's synchronization data (i.e. called by RPC Manager during startup synchronization on a server to get the package of RPCs that create a synchronizable state on the client which is in step with the server).
Returns: | See comments
Usage: | Steady State only.
Function Groups: | Network
Related to: | Adding Server-Only Synchronization
Format: | GetServerChanges(RevisionInfo, PackStreamRef, Client)
Parameters: |
RevisionInfo
Required. The revision information from the GetClientRevision call made on the synchronizing client.
PackStreamRef
Required. A pointer to a variable to obtain changes.
ClientName
Required. The name of the client.
Comments:

This subroutine is expected to be found in the object value of the caller of RPCManager\Register. It should not be called as "\RPCManager\GetServerChanges", but it may be appropriate to call it within the scope of the relevant service "<service scope>\GetServerChanges".

GetServerChanges() should not be written as a subroutine, as it will run on the RPCManager thread, thereby suspending external machine communication during synchronization.
If your GetServerChanges() request takes a long time, this will lead to a reduction in RPC throughput during RPC service synchronization, which may have undesirable effects. If GetServerChanges() is instead written as a launched module that slays itself when complete, the RPC thread will continue to service other RPC requests while you are building your synchronization data package.

Further, if GetServerChanges() is written as a subroutine, the RPC thread can be suspended while running your GetServerChanges() script, allowing your service thread to get a time slice and modify the service data that you are attempting to sample. This may cause two PCs running the same service to end up with mismatching data.

You must write GetServerChanges() as a launched module and call \RPCManager.SetDivert() as soon as you have finished sampling the synchronizable data for your service. If there is any possibility that another execution thread in your application can modify the data that GetServerChanges() is sampling during building of the synchronization package, you must protect the acquisition of the synchronization package with a CriticalSection().


GetServerMode

(RPC Manager Library)

Description: | Returns the mode in which the current server for a specified service is running.
Returns: | See comments
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetServerMode(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section.

If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

The mode value represents the current synchronization state of the server for the specified service.

Presently, one of the following values may be returned

  • \RPC_ACCEPT_ALL - the server is not performing synchronization with any client.
  • \RPC_SYNC_MODE - the server is performing synchronization with a client.
  • \RPC_LINKCONTROL_ONLY - the server is starting synchronization with a client.

Related information:

RPC Manager Service


GetServerNumber

(RPC Manager Library)

Description: | Returns the index down the prioritized server list of the current server for the specified service. Steady state or subroutine call.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetServerNumber(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

The workstation at the top of the prioritized server list will return an index of zero.

Related information:

RPC Manager Service


GetServerSIDPtr

(RPC Manager Library)

Description: | Returns a pointer to a variable that holds the session ID for the current server for the specified service.
Returns: | Pointer
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetServerSIDPtr(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

If the server changes, the value referenced by the returned pointer will change. This could be used by clients as a trigger to cause them to synchronize to the new server.

Related information:

RPC Manager Service


GetServersListed

(RPC Manager Library)

Description: | This subroutine returns a one-dimensional array of the names or IPs of the servers that has been derived from the "-Servers" section of the service configuration file.
Returns: | Array
Usage: | Script or steady state.
Function Groups: | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetGUID | GetServer | GetStatus | IsClient | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | Send | SetRemoteValue
Format: | \RPCManager.GetServersListed(ServiceName [, OptGUID])
Parameters: |
ServiceName
Required. Any text expression giving the name of the service for which to get the list of servers.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
The return value from this subroutine is a list of the text names for all workstations listed as servers.
If the 16-byte binary format of the GUID is not known, the GetGUID function may be used to obtain it.

To obtain a list of service names for your application, open the Trace Viewer Application, connect to RPC Diagnostics, then open the Services Dialog

Example:

  If 1 Main;
  [
    sList = \RPCManager\GetServersListed("ModemManager");
  ]

Related information:

RPC Manager Service


GetServiceScope

(RPC Manager Library)

Description: | Returns the service instance for a service.
Returns: | See comments
Usage: | Steady State only.
Function Groups: | Compilation and On-Line Modifications, Network
Related to: |
Format: | \RPCManager.GetServiceScope(Service [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

Related information:

RPC Manager Service


GetSessionContainers

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns an array of the names of tags that are "container" tags that exist at any level under the given context (parent) tag.
Returns: | Array
Usage: | Script Only.
Function Groups: | Variable
Related to: | BuffOrder
Format: | \GetSessionContainers([Context, WithLocationOnly, ExcludeContextFromList]);
Parameters: |
Context
Optional. The name of the tag under which to look for containers. Defaults to VTSDB.
WithLocationOnly
Boolean. When true, only tags that have valid Latitude and Longitude parameters will be returned
ExcludeContextFromList
Boolean. When true, the returned list will not include the tag specified in Context.
Comments: Returns Invalid if nothing is found.

Example:

  If Watch(1);
  [
    AllContainers = \GetSessionContainers();
       { AllContainers contains all in the application }
    NorthSites = \GetSessionContainers("NorthStation", TRUE, FALSE);
      { NorthSites contains all mapped sites within the parent container, NorthStation. }


GetSessionContainerTags

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns a dictionary of tag items below a given context (parent) tag.
Returns: | Dictionary (see comments)
Usage: | Script Only.
Function Groups: | Variable
Related to: | GetSessionContainers
Format: | \ GetSessionContainerTags([Context, DoNotRecurseIntoContainer, NoContainersInTagsList, IncludeTagsInSubContainers, NavigationPath, PtrAutoDrilled]);
Parameters: |
Context
Optional. The name of the tag under which to look for containers. Defaults to VTSDB.
DoNotRecurseIntoContainer
Optional Boolean. Set TRUE to not recurse into container with details page (default is false).
NoContainersInTagsList
Optional Boolean. Set TRUE to prevent containers from appearing in the Tags list. Defaults to FALSE.
IncludeTagsInSubContainers
Optional Boolean. Dpecifies whether to filter out descendents of containers. Normally defaults to false. Defaults to true if Context is an array or if Context tag has contributors
NavigationPath
Optional array. Unique ID values of the tags that make up the path taken to get to our Context tag.
PtrAutoDrilled
Optional pointer to an array of the Unique ID values of tags that were skipped (drilled through) to arrive at the Context tag. These will be skipped by the "Go Up" button in the site list user interface.
Comments:

The returned dictionary will have the following structure:
["Title"] - The title to display for the returned data
["Tags"] - A list of tags that either exist under or contribute to the provided Context tag
["Containers"] - A list of Container tags that exist under the provided "Context" tag

Note that container tags use this function to obtain the list to display in a Sites page. If the container tag also includes a module named CustomSiteListGetSubTags or CustomSiteMapGetSubTags, (which must be a subroutine and must return an array of tag names) then GetSessionContainerTags will automatically call that module rather than GetTagList.

NavigationPath and PtrAutoDrilled are used only with Context tags that have an optional hook: CustomSiteListGetSubTags or CustomSiteMapGetSubTags.

Example:

To get all the tags in a site:

GetTags [
  If 1;
  [
    AllTags = GetTagList(\Root\Name   { Root Level    },
                         ShowChildren { DoRecursive   },
                         0            { Name Search   },
                         NameFilter   { Search String },
                         Invalid      { All Tag Types },
                         AreaFilter   { Area Filter   });

    TagDetailList = GetSessionContainerTags(AllTags { Tag List                      },
                                            TRUE    { Do not recurse into container },
                                            TRUE    { No containers in tag list     });

    GetSessionContainerTagLists(TagDetailList { Tag List   },
                                Invalid       { Containers },
                                Invalid       { IO Tags    },
                                Invalid       { AI Types   },
                                &Types        { AO Types   },
                                Invalid       { DI Types   },
                                Invalid       { DO Types   },
                                Invalid       { SO Types   },
                                Invalid       { AI Tags    },
                                &Tags         { AO Tags    },
                                Invalid       { DI Tags    },
                                Invalid       { DO Tags    },
                                Invalid       { SO Tags    });

    Return(Invalid);
  ]
]


GetSessionID

(RPC Manager Library)

Description: | Returns the current session ID for a specified application on a workstation.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetSessionID(NameOrIP [, OptGUID]);
Parameters: |
NameOrIP
Required. Any of the names or IPs by which the workstation is known to the RPC Manager.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

Related information:

RPC Manager Service


GetShapePath

(Engine-Level Function)

Description: | Returns the path value which defines the shape of a polygon.
Returns: | Object
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | GetModuleRefBox | GetPathBound
Format: | GetShapePath(CodePointer)
Parameters: |
CodePointer
Required. Any expression for the code pointer value that defines the graphic statement.

Example:

Start [
  If 1 Check;
  [
    DrawWin = CurrentWindow() { Set drawing window };
    SelObj = LastSelected(DrawWin) { Get which graphic };
    GraphicObj = GetShapePath(SelObj) { Get shape of object };
  ]
]
Check [
  If Valid(GraphicObj) EditGraphic;
  [
    UnselectGraphics(DrawWin) { Use only this object };
    SelectPath(Self(), GraphicObj) { Mark as selected };
  ]
]

The first state listed here retrieves the last selected graphic object and gets its shape in preparation for editing it. The next state then checks to make sure a valid graphic was chosen, then it releases all other chosen graphics in the window and selects the outline of the graphic as a precursor to editing it.


GetSocketStatus

(RPC Manager Library)

Description: | Returns a Boolean to indicate the connection status of either, 1) The machine node if the subnet is not valid, or 2) The specified interface.
Warning: | This function should be used only by advanced programmers.
Returns: | See comments
Usage: | Steady State only.
Function Groups: | Network
Related to: |
Format: | \RPCManager.GetSocketStatus(MachineName [,Subnet])
Parameters: |
MachineName
Required. The name of the machine for which you wish to get the Socket status.
Subnet
An optional parameter that specifies which an interface ID or GUID the socket, in which you are interested, is on.
Comments:

This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
This module returns the status of the connection between two PCs if no Subnet is specified. If the Subnet is specified, then the return value is that of the Socket’s status on the specified Subnet. If a Subnet is not specified and you are using a multi-homed PC, the return value will indicate how many sockets are connected to a particular PC.

In a network using multi-homed PCs, it is possible for two PCs to be connected multiple times under a given Subnet. In such a case, GetSocketStatus will return the status of the first applicable socket found.

Related information:

RPC Manager Service


GetState

(Engine-Level Function)

Description: | Returns the code value for the specified state.
Warning: | This function should be used only by advanced programmers.
Returns: | State code value
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, State
Format: | GetState(Module, Name, Case)
Parameters: |
Module
Required. Any expression for the code value that defines the module.
Name
Required. Any text expression which gives the text name of the state.
Case
Required. Any logical expression. If true, the name will be treated as case-sensitive. Otherwise the name will be treated as case-insensitive.
Comments: none

Related Functions:

GetInstance | GetStatement | GetStatementNum | GetStateText


GetStatement

(Engine-Level Function)

Description: | Returns the code value, statement offset or statement text size for the specified statement.
Returns: | Varies. See Option parameter.
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, State
Related to: | GetInstance | GetState | GetStatementNum | GetStateText
Format: | GetStatement(Location, Index[, Option])
Parameters: |
Location
Required. Any expression for the code value which defines the module and state.
Index
Required. Any numeric expression for the statement.
Option
Optional Boolean. If zero (the default) a suitable code value will be returned.
If set to 1, the statement offset in the source file will be returned.
If set to 2, the statement text size in the source file will be returned.
Comments: none

Example:

  If 1 Check;
  [
    dest = GetStatement(ActiveState(modPtr), 1);
  ]

This script gets the first statement in the active state of the module instance pointed to by modPtr.


GetStatementNum

(Engine-Level Function)

Description: | Returns the statement number for the specified statement.
Warning: | This function should be used only by advanced programmers.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, State
Related to: | GetInstance | GetState | GetStatement | GetStateText
Format: | GetStatementNum(Object, Statement)
Parameters: |
Object
Required. Any expression for the module instance where the statement is located.
Statement
Required. Any expression for the code value or code pointer value which defines the statement. If this is an object value, the executing statement is used.
Comments: none


GetStateText

(Engine-Level Function)

Description: | Returns the text for the specified state.
Warning: | This function should be used only by advanced programmers.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, State
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | GetStateText(State, Mode)
Parameters: |
State
Required. Any expression for the code value which defines the state.
Mode
Required. Any numeric expression for the desired information:
Mode | Desired information
0 | Character offset to beginning of state definition from start of module (includes state name and square brackets enclosing state code).
1 | Size of state in characters, including state name and square brackets.
2 | Character offset to beginning of first statement from start of state.
3 | Size of state code in characters, excluding state name and square brackets.
Comments: none

Example:

  If 1 Next;
  [
    { The module and file for which to get state code }
    ModVal = FindVariable("ConfigFolder", Scope(\Code,
                          "AnalogInput"), 0, 0);
    FStream = FileStream("C:\VTScada\VTS\AnalogInput.SRC");
    { Get the states and create an array in which to store their code   }
    SList = StateList(ModVal, 1);
    Num = ArraySize(SList, 0);
    CodeList = New(Num);
    I = 0;
    WhileLoop(I < Num,
              StateOffset = GetStateText(SList[I], 0) +
              GetStateText(SList[I], 2).
              StateLength = GetStateText(SList[I], 3);
      { Read in the code contained in that state - don't include the square brackets }
              Seek(FStream, GetModuleText(ModVal, 1) + StateOffset, 0);
              StateCode[I] = BuffStream("");
              BlockWrite(StateCode[I], FStream, StateLength);
              Seek(StateCode[I], 0, 0);
              I++;
            );
    CloseStream(FStream);
  ]


GetStatus

(RPC Manager Library)

Description: | Returns a variable that holds the current service instance status for the specified service.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Compilation and On-Line Modifications, Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetGUID | GetServer | GetServersListed | IsClient | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | Send | SetRemoteValue
Format: | \RPCManager.GetStatus(ServiceName [, OptGUID])
Parameters: |
ServiceName
Required. Any text expression giving the name of the service for which to get the connection status.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the module call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
The return value from this subroutine is the current status of a service on the local workstation. It is similar to the return value for the Register module, except that in that case it is a pointer to the value that is returned rather than the value itself.
If the 16-byte binary format of the GUID is not known, the GetGUID module may be used to obtain it.

To obtain a list of service names for your application, open the Trace Viewer Application, connect to RPC Diagnostics, then open the Services Dialog

Example:

  status = \RPCManager.GetStatus("ModemManager");

Related information:

RPC Manager Service


GetStreamLength

(Engine-Level Function)

Description: | Returns the present length of a stream in bytes.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Stream and Socket
Related to: | BuffStream | ClientSocket | FileSize | FileStream | PipeStream | Seek | ServerSocket | StreamEnd
Format: | GetStreamLength(Stream)
Parameters: |
Stream
Required. Any expression that returns a stream value.
Comments:

This function is useful in determining the size in bytes (not necessarily in characters) of an existing stream. It is not necessary to do a Seek prior to executing the GetStreamLength.

Note that, when running in steady-state and monitoring a SerialStream, GetStreamLength does not return an up-to-date stream length for that SerialStream.

Example:

  SLength = GetStreamLength(BuffStream("abcde"));

SLength will be set to 5.


GetStructInfo

(Engine-Level Function)

Description: | Returns names and counts of all instantiated structures.
Warning: | This statement should be used by advanced users only.
Returns: | Structure containing two fields. Refer to the comments.
Usage: | Script Only.
Function Groups: | Variable
Related to: |
Format: | GetStructInfo([MiniDumpHandle])
Parameters: |
MiniDumpHandle
Optional. A pointer to a data structure that holds information from a crash dump.
Comments:

This function returns a structure with two fields:

TotalInstances

The total cumulative count of structures allocated in the engine.

StructList

An nx2 array of structure names, and a count of how many instances of that structure exist.


GetStreamType

(Engine-Level Function)

Description: | Returns a type indication for a stream.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Stream and Socket
Related to: | GetStreamLength
Format: | GetStreamType(Stream)
Parameters: |
Stream
Required. Any expression that returns a stream value.
Comments: This returns the type of an existing stream. Possible valid return values are as follows
Return Value | Meaning
0 | file stream (temporary or persistent)
1 | pipe stream
2 | editor stream
3 | buffer stream
4 | TCP/IP socket stream
5 | serial port stream
6 | modem stream
7 | TCP control stream

Invalid is returned for all non-stream values.

Example:

  SType = GetStreamType(BuffStream("abcde"));

SType will be set to 3.


GetSubnetPriority

(RPC Manager Library)

Description: | This module returns a full set of network priority values configured
Warning: | This statement should be used by advanced users only.
Returns: | An array of strings containing the CIDR Closed Classless Inter-Domain Routing representation of the priority order of the subnets used for VTScada RPC
Usage: | Script or steady state.
Function Groups: | Network
Related to: | GetPreferredSubnet |GetLastUsedSubnet | SetSubnetPriority
Format: | GetSubnetPriority()
Parameters: | none
Comments:

If a NetPriority section is defined on the workstation, the returned array will represent this configuration. If no NetPriority section and no SetSubnetPriority calls defining a network priority have been made, this module will return Invalid.

(See: [RPCMANAGER-NETPRIORITY] Section)


GetSubordinateDriver

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns the subordinate driver object of the Driver Multiplexer tag based on the input parameter.
Returns: | Object
Usage: | Script or steady state.
Function Groups: | Configuration Management
Related to: | GetCurrentSubordinate
Format: | GetSubordinateDriver([Subordinate])
Parameters: |
Subordinate
Optional. Can be 0 (primary subordinate) or 1 (secondary subordinate) or Invalid.
Comments:

An Invalid return value indicates that the Driver Multiplexer tag is on a client (remote) and the mode tab is configured with the Selection in Automatic and the Sequence in either Parallel or Alternating mode. Or that the Driver Multiplexer tag is on the server and the mode tab is configured with the Selection in Automatic and the Sequence in Parallel mode.

See DriverMUX properties Modes tab for more information.


GetSystemColor

(Engine-Level Function)

Description: | Returns the colors for the user-configured Windows™ colors.
Returns: | Text (RGB color string)
Usage: | Script or steady state.
Function Groups: | Color, Graphics
Related to: | PalStatus
Format: | GetSystemColor(Option)
Parameters: |
Option
Required. Any numeric expression that determines which color to return, as indicated in the following table.
Option | Color
0 | Scroll bar
1 | Desk top
2 | Active window title bar
3 | Inactive window title bar
4 | Menu background
5 | Window background
6 | Window frame
7 | Text in menus
8 | Text in windows
9 | Active window title text, size button, scroll bar arrow button
10 | Active window border
11 | Inactive window border
12 | Background in MDI window
13 | Background of selected control item
14 | Text of selected item in control
15 | Button face
16 | Button shadow
17 | Grayed text
18 | Text on buttons
19 | Inactive text title
20 | Button highlight
Comments: This function is session aware. It will get VIC colors if called from within the VIC session.

Example:

  ZText(25, 25, "Standard text", GetSystemColor(8), 0);

This puts text in the upper left corner of the screen in the standard Windows™ text color.


GetTagConfiguredParameters

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Fetches a dictionary of tag parameters. If the Deployed parameter is TRUE, fetches the tag parameters in the database for the latest deployed revision. The latest deployed revision may not match the parameters on your workstation if your workstation has local changes to the tag.
Returns: | Dictionary
Usage: | Script Only.
Function Groups: | Module - Advanced
Related to: | |ModifyTags |OpChange |SimpleOpChange |
Format: | \Code.GetTagConfiguredParameters("TagName", &pParmsDict[, Deployed]);
Parameters: |
TagName
Required text. The name of the tag to retrieve changed/overridden parameters
pParmsDict
Required. Pointer to a value that will be set to the dictionary of configured tag parameters.
Deployed
Optional Boolean. TRUE to fetch deployed version of the given tag's parameters. Defaults to FALSE to get the current set of tag parameters on this workstation, regardless of whether or not they have been deployed.
Comments:

If the Deployed parameter is FALSE, fetches the tag parameters in the base cache for the latest application version.
If the given tag is declared in the database, fetches all parameters that have been explicitly set for that tag.
If the tag is declared in a type database, fetches all the overrides that are defined in the database for that tag. (returning an empty dictionary if there are none.)
If the given tag does not exist, the return is Invalid.

To be used with OpChange and ModifyTags when they are called with the Merge==FALSE parameter. This API makes it possible to revert a tag parameter to its default or remove an override and modify some configured parameters while keeping others.

Example:

[
  \Code.GetTagConfiguredParameters("MyTagName", &pParmsDict, TRUE);
]


GetTagHistory

(Historian Manager Library)

Description: | Launched module that retrieves historical data for a tag. Replaces GetLog.
Returns: | Nothing. (Data returned using the first two parameters.)
Usage: | Script Only.
Function Groups: | Log
Related to: | GetLog | WriteHistory
Format: | \HistorianManager.GetTagHistory(PtrReturnCode, PtrResult, TagObj, FieldNames, StartTime, EndTime, TPP, NumEntries[, Modes, StaleTime, EnableDownTimeOverride, UseRecordOverrides])
Parameters: |
PtrReturnCode

Required. A pointer to a return code. If launching GetTagHistory multiple times for a set of tags this should be an array with an index incrementing for each launch.

PtrReturnCode will be invalid until this launched function finishes. Watch for this value to become valid before attempting to process the results. In the case of an array, use AValid to watch for every instance to finish.

Defined error codes are provided in the reference chapter. See: Historian Error Codes

PtrResult
A pointer to the historical data that will be returned in this parameter. Always returns an array with at least two dimensions according to the parameter, Fields.
TagObj
Object value of the tag for which the history is to be retrieved.
FieldNames

Either the name or an array of names of the fields to retrieve.
Typically, the field in which you are interested is "Value" for most tag values, or "Value!" for tag attribute data (Value! was introduced with VTScada version 12 and is not available in legacy data. It cannot be retrieved by SQL queries.)

Note that TagData will still be a two-dimensional array even if FieldsNames is simply text. In most cases, it is better to specify this parameter as a one-dimensional array containing two elements: "Timestamp" and "Value". Both dimensions of TagData will then have data.

StartTime
UTC time stamp indicating the beginning of the data range to retrieve.
A local time value should be converted to UTC as follows. (LocalTimeZone should be 0 in almost all cases.)
UTCStartTime = ConvertTimestamp(Start, LocalTimeZone, FALSE, Invalid);
EndTime
UTC time stamp indicating the end of the data range to retrieve. (Selection is inclusive of this time.)
Ignored if TPP is non-zero.
TPP

Required. Any numeric expression giving the time span in seconds for each array entry. Each array element will contain the data which correspond exactly to this time period which corresponds to 0 or more data points.
If TPP is equal to 0, the data is read and placed in the array on a one to one basis.
If TPP is less than 0, an error will be returned.

If reading string values with TPP > 0 and Modes = 4 then valid text values are returned. Attempting to do the same with any Modes value other than 4 will return only Invalid.

NumEntries
The number of log entries to be returned in the array.
Use a negative value to retrieve values in reverse chronological order.
Modes

Optional numeric expression giving the method of handling the data. If TPP is greater than 0, the values that fall in each time span will be represented as follows:

Mode | Data Collection
0 | Time-weighted average
1 | Minimum in range
2 | Maximum in range
3 | Change in value over the range
4 | Value at start of range
5 | TimeOfMinInRange
6 | TimeOfMaxInRange
7 | SumOfZtoNZTransitions
8 | SumOfNonZeroTime
9 | Totalizer. (Invalid is counted as zero)
10 | Deprecated. Equivalent to mode 4.
11 | Difference between the start and end values of a range (see following note)
12 | Bitwise OR (see following note)
13 | Bitwise AND (see following note)
14 | Value at end of range

Mode 11:

This is for hardware that can count to a limited number, then rolls over to start a fresh count. For example, a tag that counts equipment starts, but which can only count from 0 to 15 before wrapping around to start again. This gives a value of sixteen per roll-over since there must be one more start after fifteen to have the roll-over occur. A graph of a very simple case where there is a start every second would look like the following:

(Each rollover must be followed by a fresh start, not a gradually declining value. If there are a series of declining values then, because each is less than the previous, each counts as another rollover.)

The formula used is (RolloverCount * RolloverValue) + (LastValidValue - FirstValidValue).

Where, for any given time interval:

  • Rollovers are counted when a new value is smaller than the last valid value.
  • The RolloverValue is passed to the function in the parameter StaleTime.
  • LastValidValue starts with the last valid value in the previous time interval (if any), and is updated with each new valid value within the time interval.
  • FirstValidValue starts with the last valid value in the previous time interval (if any), and is updated with only the first valid value found in the current time span.

Given this example, suppose that you want a count of starts in each thirty-second interval. In the first interval there is no previous valid value, one wrap-around and a last valid value of 12. (1*16) + (12 - 0) = 28.

This is an idealized case. Consider a more realistic case where not all values are logged. (This may be due to factors such as polling intervals, deadbands, hardware, etc.) The following graph shows the same data where the orange dots represent values obtained and logged and the gray line represents what really happened:

In the first 30 seconds there is one roll-over when the value drops from 13 to 2. The first value is 0 and the last is 11. The Historian will return 27: (1*16) + (11-0) = 27.

The Historian will return 30 for the period from 30 to 60. The first valid value (carried from the previous period) is 11. The last valid value is 9 and there are two roll-overs. (2*16) + (9-11) = 30.

Modes 12 and 13:

These are intended to provide a summary of the bit-wise Historian value attributes within a query. (Value attributes were added in VTScada version 11.5 / 12.0)

With mode 12, the first value is OR'd with zero, and each successive value in the time period is OR'd with result of the last comparison. From the result you will know whether any particular attribute bit was set on any values within the period.

With mode 13, the first value is AND'd with a value having all bits set to 1 and each successive value is AND'd with the result of the last comparison. From the result you will know whether any particular attribute bit was set on all values within the period.

In the case of modes 5 and 6, FieldName should still be set to indicate the field on which the mode is to act. The return values will be times indicating the maximum or minimum in that field for each time span.

If TPP is less than or equal to 0, Mode is ignored. If the data is text, the first entry in a given time range is used for the array entry and Mode is ignored.

It is possible to retrieve more than one mode in a single GetTagHistory statement. To do this, pass an array of values in as the Mode parameter.

StaleTime
The meaning of StaleTime depends on the selected Mode.
For all Modes but 11, this optional parameter sets a maximum validity duration for data elements that are being TPP processed.
For Mode 11, this is the maximum value of a range. (See comments in the Mode parameter.)
Normally, every data point is treated as remaining valid until the next data point. If a valid StaleTime parameter is given, then any data point will be treated as invalid, StaleTime seconds after the recorded time. If TPP is less than or equal to 0, StaleTime is ignored. If StaleTime is not required but EnableDowntimeOverride is, then StaleTime should be given as an Invalid value.
It is possible to specify more than one stale time in a single GetTagHistory statement. To do this, pass an array of values in as the StaleTime parameter.
EnableDownTimeOverride
An optional Boolean. Set TRUE to return INVALID for downtime. Set FALSE to not return INVALID for downtime. Defaults to the value from the Historian tag's "Represent system downtime as missing data" parameter.
UseRecordOverrides
An optional Boolean. Flag indicating if record overrides are in effect. Setting the UseRecordOverrides parameter to FALSE will cause all records in storage to be returned even if there are duplicate timestamps.
Typically, a new record with a timestamp matching an existing record would be considered to override the existing record. The parameter defaults to TRUE, returning only the most recently added record for each timestamp.
Comments:

This function is a replacement for GetLog. It has the following advantages over GetLog:

1) Works purely in UTC. Any conversion to local timestamps should be done by the caller only when absolutely necessary (only when they are about to display or be presented to an end-user).

2) Ambiguity removed from the StartTime, EndTime, TPP and NumEntries parameters: If TPP is non-zero, then EndTime is ignored and NumEntries explicitly specifies the number of periods to return.

3) Ambiguity removed from return values. There is an explicit return code set when the function is complete, rather than just returning a single-element array when an error occurs, which is ambiguous to whether it indicates an error or returned data. Moreover, the array returned is always a two-dimensional array.

Note: if multiple modes are being returned from the same field, the array size of fields needs to match that of mode.

This function forwards to GetLog if there is legacy history data involved in the query.

No downtime invalids are inserted when reading in the reverse order.

Querying Value Attributes

Version 12 of VTScada introduced value attributes. These can be queried using "Value!" rather than "Value" for the field name or array of field names. Value! stores bitwise values according the following table.

Attributes flagged with a star (*) apply only if the I/O tag is attached to a DNP3 driver or a custom driver supporting this feature.

Refer to the constant, #NUM_DATA_ATTR_BITS, to discover the number of bits in data attributes for your version of VTScada.

Bit Number | Defined Constant Name | Meaning
0 | #DATA_ATTR_MANUAL_DATA | The value was from the tag's ManualData parameter
1 | #DATA_ATTR_MANUAL_ENTRY | The value was manually entered
2 | #DATA_ATTR_EDITED_DATA | The historical value was manually edited
3 | #DATA_ATTR_QUESTIONABLE | The tag was marked as questionable
4 | #DATA_ATTR_STALE_DATA | The value was reported as stale by VTSDriver
5 | #DATA_ATTR_IMPORTED | The value was imported from a CSV file
6 | #DATA_ATTR_COMMFAIL | The driver experienced a comm failure
7 | #DATA_ATTR_QUALITY | The tag has marked the value as unreliable
8 | #DATA_ATTR_DRIVER_COMMFAIL | The PLC reported a downstream comm failure
9 | #DATA_ATTR_DRIVER_QUALITY | The PLC reported the value may be unreliable
10 | #DATA_ATTR_DRIVER_OVERRIDDEN | (*) The PLC reported the value was overridden
11 | #DATA_ATTR_DRIVER_NODATA | (*) The PLC reported there is no data available

See Also:

WriteHistory, ConvertTimeStamp

Examples

There are two distinct ways to retrieve historical data: (1) Raw history and (2) Statistically processed data ("TPP").

A raw history retrieval retrieves the actual records that were logged by the tag

    FieldNames = New(2);
    FieldNames[0] = "Timestamp";
    FieldNames[1] = "Value";
    \HistorianManager.GetTagHistory(&RetCode, &Results, AnalogStatus1,
                                  FieldNames, UTCStartTime, UTCEndTime,
                                  0 {TPP=0 indicates raw records requested},
                                  100 { Maximum number of records to return});

TPP-type query (average daily values for a 10-day period):

    Modes = New(2);
    Modes[0] = 4; { Timestamp at start of period }
    Modes[1] = 0; { Time-weighted average of Value over the period }
    \HistorianManager.GetTagHistory(&RetCode, &Results, AnalogStatus1,
                                    FieldNames, UTCStartTime, 0 {EndTime ignored},
                                    86400 { 1-day time periods },
                                    10    { 10 days requested  }, Modes);

Retrieve an average and a minimum:

    Modes = New(2);
    Modes[0] = 0 { Average };
    Modes[1] = 1 { Minimum };

    Fields = New(2);
    Fields[0] = "Value";
    Fields[1] = "Value";

    \HistorianManager.GetTagHistory(&ReturnCode, &Result, TagObj, Fields,
                                    StartTime, EndTime, EndTime - StartTime, 1, Modes);


GetTagList

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns an array of tags, starting at a given point in the tag tree and including all child tags below that point, subject to the filtering parameters.
Returns: | Array
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | PointList | GetTagTypes
Format: | \GetTagList([RootLevel, DoRecursive, SearchType, SearchString, TagType, AreaSearch, EnableRealmAreaFiltering, IncludeGhosts, ExcludeLeaves, ExcludeMenuItems, ExcludeSubordinateTags, EquipTypeSearch, ParmSearchString, AdditionalFilters, AddrSearchString])
Parameters: |
RootLevel
Optional text. The name of the tag to begin with. May be a unique id or a tag name. Defaults to VTSDB if not specified.
DoRecursive
Optional. A Boolean value which, when set TRUE, results in sub-tags being returned as well as tags at the current level of the tree. Defaults to false if Invalid.
SearchType
Optional flag. Set 0 for a name search or 1 to search all parameters. Defaults to 0, name search.
SearchString
Optional text. A value to filter for, using pattern matching.
TagType
Optional. The type of tag to be filtered for. Set to Invalid (not "*") for all tag types.
AreaSearch
Optional text - the area name to filter for using pattern matching.
EnableRealmAreaFiltering

Optional Numeric with possible values as follows:

0 => no realm or user filtering.

1 => apply realm & user filtering. (Default)

2 => apply only realm filtering.

IncludeGhosts
Optional Boolean. Set TRUE to include disabled tags. Defaults to FALSE.
ExcludeLeaves
Optional Boolean. Set TRUE to filter for only tags that have child tags. Defaults to FALSE.
ExcludeMenuItems
Optional Boolean. Set to TRUE to exclude Menu ItemTags. Defaults to FALSE
ExcludeSubordinateTags
Optional Boolean. Set to TRUE to exclude Subordinate tags and tags from subordinate applications. Defaults to FALSE.
EquipTypeSearch
Optional text. Provide an equipment type name to search for tags with that EquipmentType property. No default.
ParmSearchString
Optional text. Search string for full parameter search
AdditionalFilters

Optional structure. Array of structures of additional filters.

  AdditionalFiltersStruct Struct [
    VariableName { Variable to check                  };
    OperandID    { See table below for definitions          };
    Value        { Value to compare against           };
    IsText       { Flag - Do this comparison as text  };
  ];
OperandID | Meaning
0 | Valid
1 | True
2 | False
3 | Less Than
4 | Less Than Or Equal
5 | Equal (Case sensitive for text)
6 | Greater Than Or Equal
7 | Greater Than
8 | Pattern Match (Not case sensitive for text)

Use this to specify a parameter or variable name, the operand to use for the comparison, and a value to compare against. As an example, the Tag Browser uses this for the filter to show only tags with Questionable set.

AddrSearchString
Optional text. Search string for address search
Comments:

This function provides the search and filtering features seen in the Tag Browser. You should select this function over the older PointList, since GetTagList adds several options to control what will be returned.

The IsText option in AdditionalFilters causes the code to call GetPhrase on the Value.

When using text, the Equal option (5) is case sensitive. For case insensitive checks, use the Pattern Match option (8)

Examples:

Select all driver tags in application:

  If 1;
  [
     PList = \GetTagList(Invalid, TRUE, 0, "*", "Drivers", Invalid, FALSE);
  ]

Select all the Analog Status tags, in all areas, within a context named MyStationName:

  If 1;
  [
     PList = \GetTagList("MyStationName", TRUE, 0, "*", "AnalogStatus");
  ]


GetTagMode

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns text or a structure to identify what kind of tag a given instance is.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | CheckTagGroup
Format: | \GetTagMode(TagObj[, Specifier]);
Parameters: |
TagObj
Required. The tag instance being checked.
Specifier

Optional text. The name of the tag attribute to return. If this parameter is Invalid, a structure including all attributes will be returned. May be any of:

IsString

IsAnalog

IsDigital

IsDiscrete

IsInput

IsOutput

IsPump

IsDriver

EquipmentType

IsAnalytic

IsMemoryTag

IsContainer

Comments:

If a structure is returned, it will contain the following fields:

IsString - TRUE for string tags or non-string tags that are configured as text

IsAnalog - TRUE for analog tags

IsDigital - TRUE for digital tags

IsDiscrete - TRUE for discrete tags

IsInput - TRUE for input tags

IsOutput - TRUE for output tags

IsPump - TRUE for pumps

IsDriver - TRUE for drivers

EquipmentType - The tag's equipment type or default type

IsAnalytics - TRUE for calculation modes

IsMemoryTag - TRUE for tags with no address, excepting 2-bit digitals.

IsContainer - TRUE for tags that are containers.

Some Boolean attributes are mutually exclusive, such as IsAnalog and IsDigital. Others such as IsAnalog and IsDiscrete, are not.


GetTagTypes

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns an array of either the common names or the module names of all tag types. May optionally include the list of tag groups.
Returns: | Array
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | PointList | GetTagList
Format: | \GetTagTypes([GetGroups, GetModuleNames])
Parameters: |
GetGroups
Optional Boolean. If set TRUE, the list of tag groups will be retrieved and returned at the end of the list of types. Defaults to TRUE.
GetModuleNames

Optional Boolean. If set TRUE, this function will return module names rather than the display name for each type.

If set, Groups will be invalid. Defaults to FALSE.

Comments: This function is used to populate a selection list of types.

Examples:

Create a dictionary of tag types and how many running instances there are of each type

GetTagCounts [
  If 1;
  [
    TagTypes = GetTagTypes(FALSE, TRUE);
    Counts   = Dictionary();
    I        = 0;
    WhileLoop(I < ArraySize(TagTypes),
      Counts[TagTypes[I]] = NumInstances( LocalScope(\Code, TagTypes[I]));
      I++;
    );
    Return(Counts);
  ]
]


GetTimePhrase

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns a formatted time for the current user's locale
Returns: | Text
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: | GetDatePhrase | GetParmPhrase
Format: | \GetTimePhrase(Time, FormatID)
Parameters: |
Time
Required numeric. The number of seconds since midnight
FormatID
Required text. The phrase identifier key specifying the time format.
See: Date and Time Phrase Keys
Comments:

The Language property in the caller's scope is used to specify the language name (e.g. en). Defaults to the Windows system's language.

Example:

  \GetTimePhrase(Now(60), "TimeFmtHM24Hour")

returns "15:51", assuming that the current language is English and the time is 3:51pm.


GetToken

(Engine-Level Function)

This function works with streams. If you are interested in Control Tokens, refer to GetToken (Control Lock Module)

Description: | Reads the next token from a stream and returns the token type.
Warning: | This function should be used only by advanced programmers.
Returns: | Numeric (see table in comments)
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Stream and Socket
Related to: | Compile
Format: | GetToken(Stream, Token, ClassBuffer, NumClasses, StateBuffer, ActionBuffer, SkipWhite, LineCount, Column, CharCount)
Parameters: |
Stream
Required. Any stream expression for the input stream.
Token
Required. A variable into which the next token read will be stored.
ClassBuffer
Required. Any text expression for the character classifier table.
NumClasses
Required. Any numeric expression for the number of character classes.
StateBuffer
Required. Any text expression for the tokenizer state table.
ActionBuffer
Required. Any text expression for the tokenizer action table.
SkipWhite
Required. Any logical expression. If true, all white spaced is skipped. Otherwise all continuous white space is treated as a token.
LineCount
Required. Must be a variable. The number of lines read is stored here.
Column
Required. Must be a variable. The current column is stored here.
CharCount
Required. Must be a variable. The number of characters read is stored here.
Comments: The return value for this function is the token type. The tokens recognized by the Compile function are as follows (assuming the tables used by the compiler are those handed in to this function)
Return Value | Token Type
0 | End-of-file
1 | White space
2 | Identifier - variable


GetToken (Control Lock Module)

(Control Token Manager)

This function works with Control Tokens. If you are interested in stream handling refer to GetToken

Description: | Checks if a token is applied directly to a tag or (optionally) to a tag's ancestor. Can also search for token requests.
Returns: | An alarm record
Usage: | Script or steady state.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | \ControlTokenManager.GetToken(TagID[, IncludeAncestry, Snapshot, GetRequest, ReturnAll])
Parameters: |
TagID
Required text. The unique ID of the tag to check.
IncludeAncestry
Optional Boolean. Set TRUE to search the tag's ancestry. Defaults to TRUE.
Snapshot
Optional Boolean. Set TRUE if this function is called in script. Defaults to FALSE.
GetRequest
Optional Boolean. Set TRUE to search the TokenRequests list instead of the Tokens list. Defaults to FALSE.
ReturnAll
Optional Boolean. Set TRUE to return all matching records. Defaults to FALSE.
Comments:

For more information about alarm records and what an alarm record contains, see Alarm API Structure Definitions

Checking the validity of the returned value is sufficient to determine if the tag in question has a token.

Given a tag's unique ID, this module checks if a token is applied directly to the tag (IncludeAncestry = FALSE).

If IncludeAncestry = TRUE (default), this will search the tag's ancestry for the nearest token. Returns Invalid if no token is found.

Can optionally search the TokenRequests list instead if GetRequest = TRUE


GetTokenLevel

(Control Token Manager)

Description: | Checks if a token is applied directly to the tag or (optional) the tag's ancestors, and if so, returns the token's level.
Returns: | Numeric (Invalid if no token is found)
Usage: | Script or steady state.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | \ControlTokenManager.GetTokenLevel(TagID[, IncludeAncestry, Snapshot])
Parameters: |
TagID
Required text. The UniqueIDof the tag.
IncludeAncestry
Optional Boolean. Set TRUE to search the tag's ancestry. Defaults to TRUE.
Snapshot
Optional Boolean. Set TRUE if calling this function in script. Defaults to FALSE.
Comments:


GetTrajectoryPath

(Engine-Level Function)

Description: | Returns the Path value which defines the trajectory of a graphic object.
Returns: | Path
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | GetPathBound | Trajectory
Format: | GetTrajectoryPath(CodePointer)
Parameters: |
CodePointer
Required. Any expression for the code pointer value that defines the graphic statement.


GetTransform

(Engine-Level Function)

Description: | Returns the transform value applied to a graphic statement.
Returns: | Transform
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | GetXformRefBox | GUITransform | UnTransform
Format: | GetTransform(CodePointer)
Parameters: |
CodePointer
Required. Any expression for the code pointer value which defines the graphic statement.


GetTSfromISOTS

(System Library)

Description: | Convert an ISO 8601 formatted date and time to a VTScada timestamp
Returns: | A VTScada timestamp
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | GetISOTSfromTS
Format: | GetTSfromISOTS(ISO8601Timestamp)
Parameters: |
ISO8601Timestamp
(Required.) ISO 8601 Timestamp formatted string e.g: 1985-04-12T23:20:50.52+02:00
Comments:

VTScada uses UTC-based timestamps stored as seconds since midnight, January 1st, 1970. (ex 482188850)

ISO 8601-style timestamps follow the format, YYYY-MM-DDThh:mm:ss (ex. 1985-04-12T23:20:50.52)

Example:

\System.GetTSfromISOTS("1985-04-12T23:20:50.52+02:00")


GetTransitText

(Engine-Level Function)

Description: | Get Transition Document Text. This function returns information about the documentation of an action.
Warning: | This function should be used only by advanced programmers.
Returns: | Text
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | GetTransitText(Action, Mode)
Parameters: |
Action
Required. Any expression for the code value that defines the action.
Mode
Required. Any numeric expression which defines the information desired
Mode | Information desired
0 | Script size in characters
1 | Character offset to script
2 | Trigger size in characters
3 | Character offset to trigger
4 | Destination size in characters
5 | Character offset to destination
6 | Size of script excluding [ ] , in characters
7 | Character offset to first script statement
8 | Total size of action, in characters


GetUserName

(Security Manager Module

Description: | Returns the user name of the caller’s account.
Returns: | String
Usage: | Script or steady state.
Related to: | GetAccountID | GetAccountInfo | GetFullName | GetGroupName | IsLoggedOn | IsSecured | IsSuspended | SecurityCheck | UIErrorToText
Format: | \SecurityManager.GetUserName()
Parameters: | None
Comments: | This is not namespace-qualified.

Example:

  CurrentOperator = \SecurityManager.GetUserName();


GetUserNameOfRecord

(Alarm Manager module)

Description: | Given an alarm record, returns the user name associated with the transaction.
Returns: | Text
Usage: | Script Only.
Function Groups: | Alarm
Related to: | GetAlarmList | GetAlarmObject
Format: | \AlarmManager.GetUserNameOfRecord(AlarmRecord[, TrimRealm])
Parameters: |
AlarmName
Required record. A reference to the alarm, as returned by the function GetAlarmObject.
TrimRealm
Optional Boolean. If TRUE, and if the user is a member of a security group, the realm (group) will be trimmed from the result.
Comments:

This function is intended primarily for presentation purposes.

Example:

[
  NRecords;
  Records;
  Done;
  Progress;
  AlarmAckedBy;
]
Init [
  If 1 WaitResults;
  [
    \AlarmManager.GetAlarmList(&Records, &NRecords, "History" { History list },
                               TRUE { Snapshot and done }, TRUE { Include shelved },
                               FALSE { No configuration records },
                               "Record\Action == ""Ack""" { Filter for Ack events },
                               Invalid, Invalid, FALSE { No calculated fields },
                               CurrentTime(1) - 7200, CurrentTime(1) { Records for the last two hours },
                               100 { Limit to 100 records } , &Done, &Progress);
  ]
]
WaitResults [
  If Done Main;
  [
    { Starting with the most recent...}
    AlarmAckedBy = \AlarmManager.GetUserNameOfRecord(Records[0]);


GetUserSession

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | The module this function returns is useful for accessing session-specific variables. The function will traverse the call tree to find the session that called it.
Returns: | A session module instance.
Usage: | Script or steady state.
Function Groups: | Basic Module, Variable
Related to: | ParentWindow
Format: | \GetUserSession([DefaultToRootSession])[\QueryVariable]
Parameters: |
DefaultToRootSession
Optional Boolean. If TRUE (the default value) then if a valid session is not found, this function will return the Display Manager's root session. (That is, the one pertaining to the actual running application as opposed to any remotely established session.)
If set FALSE, then Invalid will be returned if a valid session is not found.
QueryVariable

Optional. The name of a variable to be queried. Examples include, but are not limited to:

\IsRootSession

\AppTitle

\CurrentWinInst\PageInstance

Comments:

This routine walks up the caller's call tree, looking for a variable named "_UserSession_", then returning the context containing that variable. If none is found, then the Display Manager's root session will be returned unless the optional parameter is set to FALSE.

GetUserSession is also useful for launching dialogs in the scope of a particular user session. This means that a tag or service that is not associated with any particular user can cause a dialog to open on a particular VIC session.

Note that the public variable, IsEditing, is obsolete. In place of GetUserSession\IsEditing, new code should use ParentWindow()\Editing.

Examples:

Launch a dialog in the scope of a session:

  If OpenDialog Idle;
  [
    Session = \GetUserSession();
    Launch("Dialog", Self() { Parent }, Session { Caller });
  ]


GetValue

(Hierarchical Accumulator module)

Description: | Returns the current count of the values within an accumulator dictionary.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | Accumulate
Format: | HierarchicalAccumulator\GetValue(TagObj, AccumulatorName);
Parameters: |
TagObj
Required. The tag object at the point in the hierarchy where you want to collect the accumulated values.
AccumulatorName
Required. The name of the accumulator, from which to retrieve the current count.
Comments: This function is part of the HierarchicalAccumulator module, so must always be called as shown in the format. You will need this function if you have created your own accumulator and wish to retrieve the value.
The accumulator allows a fresh count to be generated at different levels in a tag tree, and as tags are moved or disabled.

Examples:

Main [
   Return(\HierarchicalAccumulator\GetValue(ContainerObj, "AlarmUnacked"));
]


GetValueAttribute

GetValueAttribute is only supported by the IO & Calculations tag.

Description: | Returns the state of one bit from the bitwise value attributes of a tag.
Returns: | Boolean
Usage: | Script Only.
Related to: |
Format: | IO.GetValueAttribute(AttribNum)
Parameters: |
AttribNum
Attribute bit number to obtain.
Comments:

Querying Value Attributes

Version 12 of VTScada introduced value attributes. These can be queried using "Value!" rather than "Value" for the field name or array of field names. Value! stores bitwise values according the following table.

Attributes flagged with a star (*) apply only if the I/O tag is attached to a DNP3 driver or a custom driver supporting this feature.

Refer to the constant, #NUM_DATA_ATTR_BITS, to discover the number of bits in data attributes for your version of VTScada.

Bit Number | Defined Constant Name | Meaning
0 | #DATA_ATTR_MANUAL_DATA | The value was from the tag's ManualData parameter
1 | #DATA_ATTR_MANUAL_ENTRY | The value was manually entered
2 | #DATA_ATTR_EDITED_DATA | The historical value was manually edited
3 | #DATA_ATTR_QUESTIONABLE | The tag was marked as questionable
4 | #DATA_ATTR_STALE_DATA | The value was reported as stale by VTSDriver
5 | #DATA_ATTR_IMPORTED | The value was imported from a CSV file
6 | #DATA_ATTR_COMMFAIL | The driver experienced a comm failure
7 | #DATA_ATTR_QUALITY | The tag has marked the value as unreliable
8 | #DATA_ATTR_DRIVER_COMMFAIL | The PLC reported a downstream comm failure
9 | #DATA_ATTR_DRIVER_QUALITY | The PLC reported the value may be unreliable
10 | #DATA_ATTR_DRIVER_OVERRIDDEN | (*) The PLC reported the value was overridden
11 | #DATA_ATTR_DRIVER_NODATA | (*) The PLC reported there is no data available

Bit 7 - #DATA_ATTR_QUALITY is set via another tag in the IO configuration.

Bit 5 - #Data_ATTR_IMPORTED is set via another tag in the IO configuration when using the History Import tool.


GetVariableText

(Engine-Level Function)

Description: | Returns information about a variable.
Warning: | This function should be used only by advanced programmers.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | GetVariableText(Variable, Mode)
Parameters: |
Variable
Required. Any expression for a variable.
Mode

Required. Any numeric expression for the desired information. The character offset is to the right after the declared variable (i.e. the carriage return is not included, nor is the line feed that ends the line), and length includes the CR, LF(2).

Mode | Desired information
0 | Character offset to variable declaration
1 | Size of variable declaration in characters

In the case of the offset to the variable declaration, this is located immediately following the variable preceding this variable and will in fact include the carriage return and line feed from the previous variable. Likewise, the size of the variable declaration includes the leading carriage return and line feed, any spaces preceding the actual variable name and does not include the carriage return and line feed following the variable.

Example:

Assume that the following text is the entire document file for a module:

[
  x;
  y;
  [ (99)
    P1 Module "P1.SRC";
  ]
]
Main [
]

The offsets for the variables would be as follows:

Variable | Offset (Mode = 0) | Size (Mode = 1)
X | 1 | 6
Y | 7 | 6
P1 | 23 | 25


GetVariableType

(Engine-Level Function)

Description: | Returns the type, BASEVALUE, stored within a variable.
Warning: | This function should be used only by advanced programmers.
Returns: | Integer or Structure.
Usage: | Script Only.
Function Groups: | Variable
Related to: | SetVariableType
Format: | GetVariableType(Variable)
Parameters: |
Variable
Required. Any expression for a variable.
Comments: If a structure is returned, the first element will be an integer giving the data type. In the case where the variable is a module, the remaining elements will be text strings giving the names of modules within the scope.

Example:

    Var = FindVariable(ParmList[I], Mod, 0, 0);
   { Retrieve any typing information }
    ParmType = GetVariableType(Var);


GetVarMetadata

(Engine-Level Function)

Description: | Every variable object contains an embedded value. This function is used to retrieve those values.
Warning: | This function should be used only by advanced programmers.
Returns: | Varies
Usage: | Script Only.
Function Groups: | Dictionary, Variable
Related to: | SetVarMetadata | FindVariable | AddVariable
Format: | GetVarMetadata(Variable)
Parameters: |
Variable
Required. A variable handle, such as would be returned from the FindVariable or AddVariable functions.
Comments: Commonly used in conjunction with SetVarMetadata, FindVariable or AddVariable. Note that type data for each variable is stored within the variable using metadata.

Example:

<
TestMod
[
  X;
  Y;
  Var;
]
Main [
  If ! Valid(X);
  [
    X = "This is the value of X"
    Var = FindVariable("X", Self(), 0, 0);
    SetVarMetadata(Var, "This is the metadata in variable X");
    Y = GetVarMetadata(Var);
  ]
  ZText(50, 100, Concat("X: ", X), 14, 0);
  ZText(50, 120, Concat("Y: ", Y), 14, 0);
]
>


GetVersions

(Recipe Book module)

Description: | Returns an array of the versions found in the current or specified recipe
Returns: | Array of text
Usage: | Script Only.
Function Groups: | Recipe Book
Related to: | GetRecipes | GetCurrentRecipe | GetCurrentVersion | SetCurrentRecipe | SetCurrentVersion
Format: | RecipeBook.GetVersions([RecipeName, SortAscending])
Parameters: |
RecipeName
Optional text. The recipe, from which the version array should be retrieved.
SortAscending
Optional Boolean. If TRUE (the default), recipe versions are sorted in ascending order before being returned.
Comments:

"RecipeBook" must be a reference to a Recipe Book tag object, not the name of the tag.

Returns a sorted list of the recipe versions in the recipe book for the specified recipe.


GetVoices

(VoiceTalk Module)

Description: | Runs in the VoiceTalk thread and returns a list of voices available on a SAPI text-to-speech stream.
Returns: | Array
Usage: | Script Only.
Function Groups: | Speech and Sound
Related to: | Configure | GetDevices | Reset | ShowLexicon | Speak | VoiceTalk
Format: | VoiceTalkStream\GetVoices([Detailed])
Parameters: |
Detailed
Optional. A flag which, if set to a non-zero value, results in a detailed 2-dimensional array of information about the voices being returned. If this parameter is "0" or omitted, the return value will be a 1-dimensional list of voice names suitable for use in the VoiceTalk\Configure function.
If Detailed is specified, a 2-dimensional array containing the available speech voices will be returned. Each row in the array represents a speech module as follows:

[N][0] Text value that indicates the name of this voice This is a human readable string (such as "Microsoft Mary") that may be passed to the VoiceTalk\Configure function.

[N][1] Text value giving the language of the voice. For example, American English will be returned as "409,9", where 409 is the hexadecimal representation of standard English (decimal 1033), and 9 indicates American version of English.

[N][2] Text value giving the gender of the voice. Either "Male" or "Female"

[N][3] Text value giving the age of the voice (e.g., "Adult")

[N][4] Text value vendor providing the voice (e.g. "Microsoft")
Comments

VoiceTalkStream is a speech stream returned from VoiceTalk.

This function will return immediately. Using the array information returned from this call, it is possible to determine whether a particular SAPI text-to-speech mode exists on the system. If it does not, the array information can be used to select the voice that most closely matches the desired characteristics, or build and display a dialog to allow the user to choose.

Example:

  SHandle = \VoiceTalk();
  If Valid(SHandle) && ! GetVoices;
  [
    GetVoices = 1;
    SVoices = SHandle\GetVoices(1);
  ]

This will return a detailed 2-dimensional array of all available text-to-speech engine voices in the array, SVoices.


GetWCPath

Description: | Returns the file system path to the application's working copy folder.
Returns: | Text
Usage: | Steady State only.
Function Groups: | Configuration Management
Related to: | GetOEMLayer |
Format: | \AppLayer.GetWCPath
Parameters: | none
Comments: | The retrieved path includes the trailing backslash. For most programmers, it is extremely unlikely that you will need to work with files in the application's working copy.

Examples:

Obtain the working copy path for your application

[
  WC;
]
Init [
  If 1 Main;
  [
       WC = \AppLayer.GetWCPath();
  ]
]
Main [
  ZText(100, 100 { Lower left corner of text },
        WC { Text to display },
        0 { Text is black },
        0 { Use default font });
]


GetWCRevision

Description: | Returns the revision structure for the repository revision in use by the working copy.
Warning | This function should be used only by advanced programmers.
Returns: | Revision Node.
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | GetWCPath |
Format: | \AppLayer.GetWCRevision()
Parameters: | None
Comments: | None


GetXformRefBox

(Engine-Level Function)

Description: | Get Transform Reference Box. This function returns the reference box for any transform of a module.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Graphics, Advanced Module, Window
Related to: | GetModuleRefBox | GUITransform | UnTransform
Format: | GetXformRefBox(Object, Option)
Parameters: |
Object
Required. Any expression which gives the object value for the transformed module instance.
Option
Required. Any expression that defines the requested return value as indicated by the following:
Option | Return Value
0 | Left side
1 | Bottom side
2 | Right side
3 | Top side
Comments:

This function will only return the reference box of a transform immediately acting upon the module indicated by Object. It will not search for a transform that may be acting upon the module's parent or ancestors.

If the module indicated by Object is not under the influence of a transform, the return value will be Invalid.

This function is unaffected by the Untransform statement. Even if the module has been untransformed, it will still be able to retrieve the reference box of a transform that would be otherwise acting upon it.

Example:

Suppose that a module calls module Motor inside of a transform as follows:

  GUITransform(0, 100, 100, 0 { Bounding box for transform },
               1, 1, 1, 1, 1 { No scaling },
               0, 0 { No trajectory or rotation },
               1 { Module graphics are visible },
               0 { Reserved },
               0, 0, 0 { Cannot be focused/selected },
               Motor() { Module to transform });

Further suppose that Motor needs to know its exact location in the window - it is inside of the transform and is therefore unaware of its (the transform's) parameters. This can be done by the following:

  Right = GetXFormRefBox(Self(), 2);

The variable right will contain the X-coordinate for the right of the transform's reference box, which in this case will be 100. If the transform's position in the window were to change, the value of this variable would similarly change.


GetXMLNodeArray

(System Library)

Description: | Searches the result returned from XMLParse and returns an array of XMLNode values of a given type. Returns Invalid if no matches are found.
Returns: | Array of XMLNodes.
Usage: | Script Only.
Function Groups: | XML
Related to: | XMLProcessor | XMLAddSchema | XMLWrite | XMLCloneNode | XMLCreateNode | XMLDeleteMember | XMLGetNode | XMLParse
Format: | System.GetXMLNodeArray(XMLContainer, ElementType)
Parameters: |
XMLContainer
The XMLNode within which to search for element type name. Only the direct child nodes of this node are searched.
This is the equivalent of the first parameter of the Scope operator.
ElementType
The element type name to search for.
This is equivalent to the second parameter of the Scope operator.
Comments:

This helper function was created to work with the results of XMLParse.

GetXMLNodeArray searches the immediate children of a given XMLNode value (first parameter) for elements with the type name provided by the second parameter and returns those elements in an array of XMLNodes. This serves to simplify parsing of XMLNode trees, which may contain lists of repeating elements.

Elements in the returned array will be in the same order as in they were in the original XML document.

If no elements with the given name are found, then this function will return INVALID.

Examples:

  Source = "<X><Y>"Hello"</Y><Y>" "</Y><Y>"world"</Y><Y>"!"</Y></X>";
  XMLProc = XMLProcessor(INVALID);
  XMLParse(XMLProc, Source, Errors, Document);
  RootNode = XMLGetNode(Scope(Document, "X"));
  TextNodes = System.GetXMLNodeArray(RootNode, "Y");

At this point TextNodes will contain an array of four XMLNodes, containing "Hello", " ", "world", and "!" respectively.


GoToOffset

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Forces an editor to move to a location in its text.
Returns: | None
Usage: | Script or steady state.
Function Groups: | Editor
Related to: | WinEditCtrl
Format: | GoToOffset(Editor, Offset, Highlight, NumHighlight)
Parameters: |
Editor
Required. Any expression for the editor value.
Offset
Required. Any numeric expression for the character offset to display.
Highlight
Required. Any logical expression. If true, characters will automatically be highlighted, beginning at Offset.
NumHighlight
Required. Any numeric expression for the number of characters to highlight if Highlight is true.


GrantTokenRequest

(Control Token Manager)

Description: | Grants a control token request.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | ControlTokenManager.GrantTokenRequest(TagID, TokenRequestGUID[, Custom, Timestamp, SessionID, AccountID, MachineID, Device])
Parameters: |
TagID
Required string. The UniqueID of the tag for which the token request is to be granted.
TokenRequestGUID
Required string. The GUID of the token request to grant.
(Must be obtained via your script code. See: GetToken (Control Lock Module))
Custom
Optional. A structure of custom fields to log
Timestamp
Optional The UTC timestamp of this event. Defaults to current time
SessionID
Optional. The ID of session granting the request. Relevant only if the token ownership is tied to the session.
AccountID
Optional. The Account ID of user granting the request. Defaults to the currently signed-in user.
MachineID
Optional. The MachineID of the workstation where this action originated. Defaults to the current machine.
Device
Optional. Name of client device
Comments:

If someone currently has that same token, granting the request will release the current token and replace it with the one requested.

This function is intended for advanced users. The provided widgets should suffice in most instances.


Grid

(Engine-Level Function)

Description: | Places a (lined) grid pattern on the screen.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Box | GUIRectangle| Line | ZBox | ZGrid
Format: | Grid(X1, Y1, X2, Y2, Style, Color, Horizontal, Vertical)
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the grid area.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the grid area.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the grid area opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the grid area, whichever is the opposite to Y1.
Style
Required. Any numeric expression giving the line style for the grid lines. Valid line styles are from 1 to 10, where 1 is a solid line.
Color
Required. Any numeric expression giving the color of the grid lines. If the number is less than 10000, the grid lines are non-destructive. If greater than or equal to 10000, the grid lines are destructive and the actual color used is Color - 10000. RGB values and system color constants are not supported.
Horizontal
Required. Any numeric expression giving the number of horizontal lines in the grid. This value may be zero.
Vertical
Required. Any numeric expression giving the number of vertical lines in the grid. This value may be zero.
Comments This statement is non-destructive unless Color is explicitly set destructive. The outside perimeter of the grid area is not drawn.

Example:

  Grid(100, 100, 700, 500 { Bounding box for the grid },
       3 { Dotted line style },
       9 { Light blue color },
       3 { 3 horizontal lines divide 4 areas },
       5 { 5 vertical lines divide 6 areas });

This example divides an area into 6 blocks wide by 4 blocks high using 3 horizontal lines and 5 vertical lines.


GridList

(System Library)

Description: | Draws a list in the style of a spreadsheet.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | TextBox |ToolBar TreeControl | VScrollbar
Format: | System.GridList(Titles, Data, DataFormat, ColWidthsParm [, NumDataRowsParm, NumDataColsParm, GridListBGndParm, GridColorParm, GridLineWidthParm, GridStyleParm, RowHeightParm, TitleHeightParm, HCellPaddingParm, VCellPaddingParm, HScrollPosParm, VScrollPosParm, DisableVScroll, DisableHScroll, DisableColumnSizing, DisableSorting, DisableSelectedCell, DisableVGridLines, DisableHGridLines, LockFirstColumn , Sort, SelectedRow, SelectedColumn, GridFontParm, GetSortKeyScope, EnableBorderParm, CellTextColorParm, TitleTextColorParm, TitleBackColorParm, TitleGridColorParm, LockFirstColColorParm, CaseSortParm, DisableControlsParm, IsFocusableParm])
Parameters: |
Titles

Required. The array of the titles you wish to use for the grid column headings. The title bar for a grid can be disabled by setting the Titles array to Invalid, or by setting TitleHeightParm to 0. By default, users will be able to click each of your titles to sort the grid (up or down) by the contents of that column.

This (and all other) array parameters must use dynamic arrays.
Alternatively, you may provide the name of a callback module, which will provide the titles. If doing so, your module must provide its own code to enable sorting by title. Refer to the comments section and example 4.

Data
Required. The array of data with which to populate the grid.
Array elements match grid cells according to: Data[row][col].
DataFormat
Required. Usually an array of the data formats corresponding to the values specified in the Data array, in which case there must be one entry per column of data. Alternatively, this may be a single format that will be applied to all values, as shown in the example at the end of this topic.
Available format codes are listed in most text functions including GUIText
ColWidthsParm
Optional. The array of the widths of the columns in pixels.
Alternatively, a single value may be used to if all columns are to be the same width.
NumDataRowsParm
Optional. Specifies the number of data rows to display. Extra cells may be shown according to the height available to the grid, but no data will be displayed after the row set by this parameter.
NumDataColsParm
Optional. Specifies the number of data columns to display. No extra columns are shown if the Gridlist area is wider than the sum of the column widths.
GridListBGndParm
Optional. Sets the background color for the cells in the grid.
GridColorParm
Optional. Indicates the color of the grid lines.
GridLineWidthParm
Optional. Indicates the width of the grid lines.
GridStyleParm
Optional. Indicates the style of the grid lines.
RowHeightParm
Optional. Indicates the height of the rows in the grid.
TitleHeightParm
Optional. Indicates the height of the column headings row above the grid. The title bar for a grid can be disabled by setting TitleHeightParm to 0, or by setting the Title array to Invalid.
HCellPaddingParm
Optional. Indicates the horizontal cell padding for the grid.
VCellPaddingParm
Optional. Indicates the vertical cell padding for the grid.
HScrollPosParm
Optional. Indicates the horizontal scroll bar position.
VScrollPosParm
Optional. Indicates the vertical scroll bar position.
DisableVScroll
Optional. A flag that may be set to TRUE (non-zero) to disable vertical scrolling, or FALSE (0) to enable vertical scrolling.
DisableHScroll
Optional. A flag that may be set to TRUE (non-zero) to disable horizontal scrolling, or FALSE (0) to enable horizontal scrolling.
DisableColumnSizing
Optional. A flag that may be set to TRUE (non-zero) to disable column resizing, or FALSE (0) to enable column resizing.
DisableSorting
Optional. A flag that may be set to TRUE (non-zero) to disable sorting by clicking the column headings, or FALSE (0) to enable sorting by clicking the column headings.
DisableSelectedCellParm

Optional bitwise flag. Set bit 0 to disable selected-cell tracking. Set bit 1 to disable highlighting of the selected cell.

Defaults to neither bit being set, thereby enabling selected-cell tracking and highlighting.

DisableVGridLines
Optional. A flag that may be set to TRUE (non-zero) to disable vertical grid lines, or FALSE (0) to enable vertical grid lines.
DisableHGridLines
Optional. A flag that may be set to TRUE (non-zero) to disable horizontal grid lines, or FALSE (0) to enable horizontal grid lines.
LockFirstColumn
An optional flag that may be set TRUE (non-zero) to lock the first column from horizontal scrolling (e.g. the first column contains row titles). The default value if Invalid or not supplied is FALSE.
Sort
An optional parameter that specifies the column on which the GridList is to be sorted. The parameter is 1-based (i.e. a value of 1 refers to the first column).

If negative, the sort order is descending If the user clicks a column title to sort the GridList, then the parameter is set to the appropriate value. .

If Invalid or not supplied, no column sorting will be applied.
SelectedRow
An optional parameter that specifies the row of the selected cell. The parameter is 0-based (i.e. a value of 0 refers to the first row). If the user clicks in a cell, then the parameter is set to the index of the selected row.

If Invalid or not supplied, no cell is selected.
SelectedColumn
An optional parameter that specifies the column of the selected cell. The parameter is 0-based (i.e. a value of 0 refers to the first column). If the user clicks in a cell, then the parameter is set to the index of the selected column.

If Invalid or not supplied, no cell is selected.
GridFontParm
An optional parameter that specifies the font to be used for Titles and Grid elements. The selected font will affect all items in the GridList.

If using callbacks, it will allow the user to use the same font in their callbacks or have a separate title font and use their own font in their callbacks.

Note: Nothing in a GridList is sized based on font size. The caller must ensure that the row and title heights are large enough to accommodate the font.

No default value.
GetSortKeyScope
An optional module value of GetSortKey call-back (example in comments section). Required only when using call-backs for the cells of the Gridlist.
EnableBorderParm
Optional Boolean. Set true to show a border around the grid. Defaults to FALSE.
CellTextColorParm
Optional color value. Color of the text in the cells.
TitleTextColorParm
Optional color value. Color of the text in the title.
TitleBackColorParm
Optional color value. Color of the title background.
TitleGridColorParm
Optional color value. Color of the title grid or border
LockFirstColColorParm
Optional color value. Color of the locked first columns gridline.
CaseSortParm
Optional Boolean. Set TRUE for case-insensitive sorting. Defaults to FALSE.
DisableControlsParm
Optional bitwise flags to disable the keyboard or mouse so that the caller can define its own behavior for controls. Set bit 0 to disable keyboard input. Set bit 1 to disable cell selection by the mouse pointer. Default to neither bit set.
IsFocusableParm

Optional Boolean. If set TRUE, this allows the gridlist to take the focus when it is clicked on or tabbed to. Such a gridlist will only respond to keyboard input if it has focus.

Defaults to FALSE. Note that the focus and keyboard-input behavior will also happen if the selected cell option is explicitly enabled.

Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Where parameters use arrays, they must be dynamic arrays.

Using GridList, you may enable such functionality as column resizing, sorting when clicking on column headings, selection of cells, using the keyboard to move around the grid, and adding scroll bars.

(See: Bitwise Parameters & Operations)

The GridList provides the ability to define a callback function to draw in a cell

  Data[I]      = Self()      { Module in which the CallBack exists };
  DataForms[I] = "DrawCell"  { The CallBack module used to display a cell in this column };

An example of a GetSortKey call-back module:

GetSortKey
(
  Row         { Row index to get the sort key for         };
  Column      { Column index to get the sort key for      };
  Inverted    { Bool: TRUE if the order is being reversed };
)
Main [
  If 1;
  [
     Return(ToUpper(Data[Row][Column]));
  ]
]

GridList has been configured to clip text on the right and display a tooltip if there is not enough room to show the entire text string in a cell.

Do not place a Tooltip widget over a GridList. See previous note.

HasFocus() - Accessor function

Script only. You may call this function in on your GridList to determine whether it has focus.

Examples:

(See also, an example in GUITransform)

Example 1) An extremely simple grid of data:

[
  Titles;
  Data;
]
Init [
  If 1 Main;
  [
    Titles = New(3);
    Data   = New(1,3);
    Titles[0] = "Title 1";
    Titles[1] = "Title 2";
    Titles[2] = "Title 3";

    Data[0][0] = "Three Men in a Boat";
    Data[0][1] = "Heart of a Goof";
    Data[0][2] = "Mostly Harmless";
  ]
]
Main [
  GUITransform(0, 1, 1, 0,
               1 - 100, 500, 500, 1 - (100), 1,
               0, 0, 1, 0,
               0, 0, 0,
               \System.GridList(Titles { Column Titles Array },
                                Data   { Data Array          },
                                "%s"   { Format for Text     }));
...

Where: Titles is a one dimensional array of titles, equal to the number of columns. Data is a two dimensional array of values to display. The format is simply "%s" to display as strings.

Example 2) A sparse array

   {initialize the data array}
   Titles[0] = "Name";
   Titles[1] = "Area";
   Titles[2] = "Description";
   Titles[3] = "I/O Device";
   Titles[4] = "Address";
   Data[0][0] = "Tag1";
   Data[1][0] = "Tag2";
   Data[2][0] = "Tag3";
   Data[0][1] = "Area1";
   Data[1][1] = "Area1";
   Data[2][2] = "I'm a tag";
   Data[1][3] = "PollDrvr1";
   Data[0][4] = "40001";
   DataForm   = "%s";

  GUITransform(50, 500, 350, 50   { Reference rectangle         },
               1                { Scale Left                  },
               1                { Scale Bottom                },
               1                { Scale Right                 },
               1                { Scale Top                   },
               1                { No overall scaling          },
               0, 0, 1, 0       { No movement; visible; res   },
               0, 0, 0          { Not selectable              },
               System.GridList(Titles  { Titles array         },
                                Data    { Data array           },
                                DataForm { Cell format         },
                                60     { Column widths array   },
                                3      { # Data rows           },
                                5      { # Data cols           },
                                15, 8  { Grid BGnd, Grid color },
                                1, 1 { Grid line width, line style},
                                30, 30 { Row/Title height      },
                                0, 0 { Horiz/Vert cell padding },
                                0, 0 { Horiz/Vert Scroll position },
                                1, 1 { Disable V/H scroll bars },
                                1    { Disable column sizing   },
                                1    { Disable Sorting         },
                                1    { Disable selected cell   },
                                0, 0 { Enable V/H grid lines  },
                                1    { LockFirstColumn         },
                                Invalid  { Sort                },
                                0        { SelectedRow         },
                                0        { SelectedColumn      },
                                \_DialogFont { GridFontParm    }));

This code example will create a Grid List that looks like the following:

Example 3) Building a grid with data from an application:

The following is coded in a dedicated page.

[
  Title = "Privileges List";
  Color = "<FFFFFFFF>";
  AllAccounts   { All accounts and roles        };
  NumAccounts   { Count of user accounts        };
  AccountKey    { Key for each dictionary entry };
  LastKey       { Used when looping             };
  Item          { One item from the dictionary  };
  LastItem      { Used when looping             };
  Titles        { Array of column titles        };
  Data          { Data for the grid             };
  I = 0         { Counter                       };

]

Init [
  If 1 Main;
  [
    { GetAccountInfo will return Invalid unless the current account has
       the Manager privilege. We can use that as a test for whether to
       display anything. }
    AllAccounts = \SecurityManager.GetAccountInfo();
    IfThen(Valid(AllAccounts);
      { Parse the dictionary, removing roles }
      Item = GetNextKey(AllAccounts, Invalid, 1, AccountKey);
      WhileLoop(Valid(AccountKey),
        LastKey = AccountKey;
        LastItem = Item;
        Item = GetNextKey(AllAccounts, LastKey, 1, AccountKey);
        IfThen(LastItem.IsRole == 1,
          DictionaryRemove(AllAccounts, LastKey);
        );
      );
      { Get the number of user accounts and make a data array to hold them }
      NumAccounts = GetKeyCount(AllAccounts);
      Data = New(NumAccounts,4);
      { Check each account for privileges: Manager, Administrator, and Remote Data }
      Item = GetNextKey(AllAccounts, Invalid, 1, AccountKey);
      WhileLoop(I <= NumAccounts,
        LastKey = AccountKey;
        LastItem = Item;
        Data[I][0] = Item.AccountName;
        Data[I][1] = \SecurityManager.SecurityCheck(-3, TRUE, Item.AccountName) ? "✓" : "✗";
        Data[I][2] = \SecurityManager.SecurityCheck(-4, TRUE, Item.AccountName) ? "✓" : "✗";
        Data[I][3] = \SecurityManager.SecurityCheck(-47, TRUE, Item.AccountName) ? "✓" : "✗";
        I++;
        Item = GetNextKey(AllAccounts, LastKey, 1, AccountKey);
      );
      { Create titles for the columns }
      Titles = New(4);
      Titles[0] = "Name";
      Titles[1] = "Manager";
      Titles[2] = "Administrator";
      Titles[3] = "Remote Data";
    );
  ]
]

Main [
  Return(Self);

  GUITransform(0, 1, 1, 0,
               1 - 100, 300, 500, 1 - (100), 1,
               0, 0, 1, 0,
               0, 0, 0,
               \System\GridList(Titles    { Column titles array   },
                                Data      { Data array            },
                                "%s"      { Format for all text   }));

]

Assuming that the application has security enabled, the result will be similar to the following. Nothing will appear unless a user who has the Manager privilege is currently signed in. (The check mark and X depend on the file being saved with UTF-8) encoding.

Example 4) A grid that uses a callback with sorting for the title

This example was taken from a script application, starting at the Graphics submodule. Adjust accordingly to use it in a page.

The example illustrates the use of a callback for the title, including the ability to sort the data when any cell in the title row is clicked. If a callback is used for the titles, then one must also be used for the data cells. The callback is deliberately simple for brevity. Note that boundary lines and up/down arrows are missing. If defining a callback to draw the title cells, you must provide for all aspects of the cell's appearance.

<
{============================= System\Graphics ===============================}
{ This module handles all of the graphics for the application                 }
{=============================================================================}
Graphics
[
  Data;
  Formats;

  DrawTitle   MODULE          { Callback module to draw titles                };
  DrawCell    MODULE          { Callback module to draw data cells            };
  GetSortKey  MODULE          { Callback module to get sort key               };
]
Init [
  If 1 Main;
  [
    Data    = New(3, 3);
    Formats = New(3);

    Data[0][0] = 1;          { Simple data values for the example }
    Data[1][0] = 2;
    Data[2][0] = 3;
    Data[0][1] = 16;
    Data[1][1] = 15;
    Data[2][1] = 14;
    Data[0][2] = "b";
    Data[1][2] = "a";
    Data[2][2] = "c";

    Formats[0] = "DrawCell"; { Using the DrawCell call-back }
    Formats[1] = "DrawCell";
    Formats[2] = "DrawCell";
  ]
]

Main [
  GUITransform(0, 1, 1, 0,
               1 - 100, 500, 500, 1 - (100), 1,
               0, 0, 1, 0,
               0, 0, 0,
               \System.GridList("DrawTitle" { Column Titles Array   },
                                Self        { Data Array            },
                                Formats     { Format for Text       },
                                60          { Column widths array   },
                                3           { # Data rows           },
                                3           { # Data cols           }));
]

<
{==================================== DrawTitle ==============================}
{ Callback to draw a custom title row for the Gridlist.                       }
{=============================================================================}
DrawTitle
(
  CallBackScope               { The callback module of GridList               };
  TitleIndex                  { The index of the title to be seen             };
)

[
  Titles                      { Titles will be shown. This could be defined
                                in the parent module, and could be any format
                                besides an array                              };
]

Init [
  If 1 Main;
  [
    Titles = New(3)         { Using a simple array of values for the example };
    Titles[0] = "Title 1";
    Titles[1] = "Title 2";
    Titles[2] = "Title 3";
  ]
]

Main [
   { GUIText or any customized call back module to show the title }
  If GUIText(0, 18, 60, 0         { Unit bounding box           },
             1, 1, 1, 1, 1        { Scaling                     },
             0, 0                 { No movement                 },
             1, 0                 { Visible, Reserved           },
             68                   { Button                      },
             0, 0                 { FocusID, Trigger            },
             -1, 0, 0             { Colors                      },
             4, 4                 { Alignment                   },
             "%s"                 { Format                      },
             Titles[TitleIndex]   { Text to display             });
  [
     { Gridlist will adjust the sorting for us accordingly }
    CallBackScope.TitleClicked();
  ]
]
{ End of DrawTitle }
>

<
{==================================== DrawCell ===============================}
{ Callback to draw a custom cell row for the Gridlist.                        }
{=============================================================================}
DrawCell
(
  Row;
  Col;
)

Main [
   { GUIText or any customized call back module to show the data cell }
  GUIText(0, 18, 60, 0         { Defined unit bounding box   },
          1, 1, 1, 1, 1        { Scaling                     },
          0, 0                 { No movement                 },
          1, 0                 { Visible, Reserved           },
          68                   { Button                      },
          0, 0                 { FocusID, Trigger            },
          -1, 0, 0             { Colors                      },
          4, 4                 { Alignment                   },
          "%s"                 { Format                      },
          Data[Row][Col]       { Text to display             });
]
{ End of DrawCell }
>

<
{=================================== GetSortKey ==============================}
{ Callback to get the sort key for the GridList.                              }
{=============================================================================}
GetSortKey
(
  Row         { Row index to get the sort key for         };
  Column      { Column index to get the sort key for      };
  Inverted    { Bool: TRUE if the order is being reversed };
)

Main [
  If 1;
  [
     Return(ToUpper(Data[Row][Column]));
  ]
]

{ End of GetSortKey }
>

{ End of \System.Graphics }
>


GUIArc

(Engine-Level Function)

Description: | Draws an arc in a window. Can return a Boolean when selected by a mouse button or when the <ENTER> key is pressed after the graphic acquires focus.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Graphics
Format: | GUIArc(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Opacity, Reserved, Button, FocusID, FocusTrigger, Pen, Vertex)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Opacity
Required. Any Numeric expression, setting the opacity of the object. A value of one results in a solid, zero is invisible and values between zero and one are used as an alpha setting for opacity.
Reserved
Reserved for future use, set to 0.
Button
Required. Any numeric expression giving the button combination that activates this graphic.
Button | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any Boolean expression. If FocusTrigger changes from a valid false to a valid true, this graphic will become acquire focus.
Pen

Required. Any expression that returns a Pen value to describe the color, width and style. You may also use any of the following to draw a single-pixel, solid arc:

  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Vertex

Required. Any expression that returns a Vertex value that describes this arc. The center point of the vertex is the center point of the arc. The two vertex handle points are used to find the start and end angle of the arc, by the angle each point makes with the center point.
The points do not describe absolute positions - that is controlled by the object's bounding box. What matters is the relation of the points to each other.

The vertex points defining the arc should be given in the following order:
First => Center point
Second => Start angle
Third => End angle, measured counter-clockwise.

Refer to the example image in the comments section.

Comments:

This function is a layered graphics statement. For information about positioning a layered graphic, please refer to "Use Scaling to Position GUI Objects".

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.

The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

Example:

  Press = GUIArc(0, 99, 99, 0,
                 1, 1, 1, 1, 1 { Scaling              },
                 0, 0          { Movement             },
                 1, 0          { Visibility, Reserved },
                 0, 0, 0       { Selectability        },
                 Pen("<FF000000>", 1, 1),
                 Vertex(1,
                        Point(560, 512, Invalid, Invalid),
                        Point(623, 449, Invalid, Invalid),
                        Point(489, 583, Invalid, Invalid)));

This shows a black arc in the upper left corner of the window. No scaling and no animation are performed.

Vertex Examples:

Related Functions:

Arc | Circle | DrawArcPath | DrawChordPath | DrawEllipticalPath | DrawPiePath | Ellipse | GUIChord | GUIEllipse | GUIPie | GUITransform | NextFocusID | Normalize | Pie Point | Rotate | Trajectory | Vertex | VStatus


GUIBitmap

(Engine-Level Function)

Description: | Draws an image of any of the following formats in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired. Available formats include, BMP, EMF, WMF, APM, CUT, PCX, JPG, PNG, and TIF
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics
Format: | GUIBitmap(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Visibility, Reserved, Button, FocusID, FocusTrigger, Image)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Visibility
Required. Any logical expression. If true, the image is drawn normally. If false, the image is not drawn.
Reserved
Reserved for future use, set to 0.
Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is 0, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any Boolean expression. If FocusTrigger changes from a valid false to a valid true, this graphic will acquire focus.
Image

Required. Either an image expression or a text expression. An image value will display that image. A text value identifies the name of an image file.

If an expression is used, this graphic can function like an Image Change, switching images in response to changing application states.

Comments:

32-bit color is used for all VTScada image drawing.
The performance of image drawing is heavily influenced by the presence or absence of graphics acceleration hardware. An anti-aliased image draws much more slowly than one without this option set, and becomes much less compatible with masking operations such as zColorChange.

This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

EMF/WMF images will not display in the Anywhere Client.

Using ScaleWhole will impact image coordinates.
ScaleWhole is applied before the ScaleLeft, ScaleBottom, ScaleRight and ScaleTop and that factors into the resulting vertical and horizontal translation.

Example:

[
  { variable declaration & assignment }
  Left = 10; { scaling parameters }
  Right = 110;
  Top = 50;
  Bottom = 150;
]
Main [
  GUIBitmap(0, 1, 1, 0 { Bounding box of image },
            1 - Left, Bottom, Right, 1 - Top { Scaling },
         1 { ScaleWhole },
            0, 0 { No trajectory or rotation },
            1 { Bitmap is visible },
            0 { Reserved },
            0 { Left mouse button activates },
            0 { Focus ID number },
            FALSE { Focus trigger },
            "..\Bitmaps\Smiley face icon.bmp" { Bitmap file name });

...

This shows an image in the upper left corner of the window. Position and size are set using scaling parameters.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.

Related Functions:

BitmapInfo | Crop | GUIButton | GUITransform | ImageArray | ImageSweep | MakeBitmap | ModifyBitmap | NextFocusID | Normalize | Rotate | Trajectory | VStatus


GUIButton

(Engine-Level Function)

Description: | Draws a push-button in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | BitmapInfo | Crop | Brush | GUIBitmap | ImageArray | ImageSweep | MakeBitmap | ModifyBitmap | NextFocusID | Normalize | Pen | Rotate | Trajectory | VStatus | ZButton
Format: | GUIButton(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Visibility, Reserved, Button, FocusID, FocusTrigger, Brush, HighlightPen, ShadowPen, TextColor, Sides, Reserved, UpLabel, DownLabel, Font, DownValue, UpValue, Variable[, ImageSet, ClickSound])
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Visibility
Required. Any logical expression. If true, the image is drawn normally. If false, the image is not drawn.
Reserved n/a
Reserved for future use, set to 0.
Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID

Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic will not immediately have focus, but will work in any other manner.

This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.

FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
Brush
Required. Used to fill the background of the button. Any of the following may be used:
  • a Brush object
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
HighlightPen
Required. Used to draw the highlight sides of the button, one pixel wide. Any of the following may be used:
  • a Pen object (in which case the pen's width value may be used)
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
ShadowPen
Required. . Used to draw the shadowed sides of the button, one pixel wide. Any of the following may be used:
  • a Pen object (in which case the pen's width value may be used)
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
TextColor
Required.Used to set the color of the text that appears on the button. Any of the following may be used:
  • a Pen object (only the color will be used)
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Sides

Required. Any numeric expression giving the number of sides on the button. If this value is 0, the button will have four sides. If not zero, the value must be greater than or equal to 4.

In general, the use of non-rectangular shapes is discouraged. When the button is selected, a rectangular outline will be shown.

Reserved
Reserved for future use, set to 0.
UpLabel

Required. An expression returning a Bitmap value, or text. If text, it will be drawn in the font set by the Font parameter. Both text and images will be centered on the button while it is up. Images will be scaled to fill the button area. To use an image file, use: MakeBitmap("relative\path\to\file") Any of the recognized image formats may be used. The file extension is not required.

DownLabel
Required. An expression returning a Bitmap value, or text. If text, it will be drawn in the font set by the Font parameter, Both text and images will be centered on the button while it is down. Images will be scaled to fill the button area.
Font

Required. A Font value, or the number zero. Set as "0" to use the default system font.

DownValue
Required. Any expression. This will be assigned to the variable parameter when the button is down (pressed). If the value of Variable matches the value of this expression, the button will immediately be drawn as down.
UpValue
Required. Any expression. This will be assigned to the variable parameter when the button is up (released). If the value of Variable matches the value of this expression, the button will immediately be drawn as up.
Variable
Required. Any variable or any expression which may receive an assignment (any l-value). This will be set whenever the button is pressed or released. If this value is changed by another expression (or is given a default value) to match either the UpValue or the DownValue, the button will be drawn in whatever status the value represents - up or down.
ImageSet

A set of image values, stored in a structure, to be used in response to various mouse actions. Not all need be specified.

The full list of possible members for the structure is as follows:

ImageSetStruct STRUCT [
  UpImage          { Image to use when the button is "up" };
  DownImage        { Image to use when the button is "down" };
  MouseOverUpImage { Image to use when the mouse is over an
                        "up" button };
  MouseOverDownImage { Image to use when the mouse is over
                        a "down" button };
  DisabledImage    { Image to use when user actions on
                        the button are disabled };
]

Examples are provided later in this topic.

ClickSound
The name of a .wav file that is to be played when the button is clicked. The extension ".wav" will be appended if not provided in the parameter. This file will not be played while another sound (for example, an alarm,) is sounding.
Comments:

GUIButtons drawn on a page cannot be modified using ribbons or properties dialogs. Editing can only be done in code.

Standard practice is to use WinButtons if displaying plain text labels, and to use images for the labels when using a GUIButton.

There are three basic types of buttons:

  • Momentary
  • Toggle (or latching)
  • Radio (which is actually a group of buttons behaving as a unit)

For details on how to create each of these types, see the Examples section.

A momentary button is one that immediately releases when pressed (i.e. it does not remain in its pressed position). It is usually used in conjunction with an If statement as an action trigger for a script.

A toggle or latching button is a button that when pressed remains locked (latched) into its pressed position until it is pressed again (unlatched). Its Variable parameter will be set according to the position of the button - if it is latched in (pressed), the variable will be set to 1, otherwise it will be 0. Similarly, if the variable's value is set by an external source from 0 to 1, the button will become pressed to match the value. This latching/toggling effect is achieved by the UpValue parameter being set to ! Variable, which is the same as saying "not the value of the Variable parameter" or more simply, "toggle the value from what it is".

A radio button is one of a set of latching buttons that are mutually exclusive, that is to say, only one button in the set may be latched (down) at one time. When another button in the same set is pressed, the current depressed button will "pop out". Two buttons cannot be latched in at once.
If the FocusID parameter of a GUIButton is to be used in a NextFocusID statement to force this graphic to get the focus, it is important to note that this does not cause the GUIButton statement to become true (selected), but only for it to become focused. When the button is focused it may then be selected via the <CR> key on the keyboard.

Because structures cannot be initialized in steady state, the ImageSet parameter must be created in a script. You may create your own structures, or use one that has been created for you. The syntax to use the predefined structure varies depending on whether you are working in a script application or a standard VTScada application.

  • For script applications, use System.ImageSetStruct()
  • For standard applications, use \ImageSetStruct().

The following set of rules defines the ImageSet behavior...
In the absence of the ImageSet parameter or, if that parameter is present but is not valid, the GUIButton statement will display a set of predefined renderings.
In the presence of a valid ImageSet parameter, the current GUIButton rendering will be disabled. (Note that providing a valid variable that holds Invalid for this parameter will not disable the older GUIButton rendering).

It is possible to specify the ImageSet parameter as Invalid and use only the ClickSound parameter

The ImageSet parameter, when valid, must consist of a structure holding the images.

Each structure member must be named as described in the parameter listing above.

The only valid formats for each image in the structure are image values.

You may declare your own structure or use one of the pre-created structures in VTScada. For standard apps you can simply use \ImageSetStruct ()and for script apps you can use System.ImageSetStruct()

In addition to these rules for the ImageSet structure, the following rules govern how the button will be rendered:

  • If no image is provided in the set, no images shall be displayed for the button. You will end up with a blank, click-able area
  • If the button is disabled, the "Disabled" image will be displayed at all times. If there is no Disabled image the "Up" image will be displayed.
  • If the mouse cursor is not within the bounding box of the button:
  • If the button state is logically up, the "Up" image (if any) shall be displayed. If there is no "Up" image, no image shall be displayed.
  • If the button state is logically down, the "Down" image (if any) shall be displayed. If there is no "Down" image, no image shall be displayed.
  • If the mouse cursor is within the bounding box of the button:
    • If the button state is logically up, the "MouseOverUp" image (if any) shall be displayed. If there is no "MouseOverUp" image, the "Up" image (if any) shall be displayed. If there is no "Up" image, no image shall be displayed.
    • If the button state is logically down, the "MouseOverDown" image (if any) shall be displayed. If there is no "MouseOverDown" image, the "Down" image (if any) shall be displayed. If there is no "Down" image, no image shall be displayed.
  • If the mouse cursor is within the bounding box of the button:
    • If the button state is logically up, the "MouseOverUp" image (if any) shall be displayed. If there is no "MouseOverUp" image, the "Up" image (if any) shall be displayed. If there is no "Up" image, no image shall be displayed.
    • If the button state is logically down, the "MouseOverDown" image (if any) shall be displayed. If there is no "MouseOverDown" image, the "Down" image (if any) shall be displayed. If there is no "Down" image, no image shall be displayed.

The control has the ability to display text layered on top of the images. The text is displayed regardless of which image is being displayed. The text must be provided by the existing UpLabel, DownLabel, TextColor and Font parameters. If the UpLabel and DownLabel parameters are images, then they will not be used if the ImageSet parameter has prevented old GUIButton rendering.

The following parameters do not affect how the new images are displayed:

Brush, HighlightPen, ShadowPen, Sides.

This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.

The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present. Will not display tab characters.

Example:

The following illustrates how to create a momentary button used as an action trigger for a script. Notice that in this particular example images are used to label the button rather than text. The image files are assumed to be in the Bitmaps folder, while the code for this module is in the Pages folder.

Examples often use English text in labels so that you can make a copy as a starting point when building your own version.
Better practice is to replace the text with phrase keys, and the \GetPhrase() function.

  If GUIButton(10, 90, 100, 50 { Outline of the button },
               1, 1, 1, 1, 1 { No scaling },
               0, 0, 1, 0 { No movement; visible },
               64 + 4, 1, 0 { Triggered by left mouse button release },
               GetSystemColor(15){ Windows button face color },
               GetSystemColor(20){ Windows button highlight color},
               GetSystemColor(16){ Windows button shadow color },
               GetSystemColor(18){ Windows button text color },
               0, 0 { Windows standard attributes },
               MakeBitmap("..\Bitmaps\StartPict"),
               MakeBitmap("..\Bitmaps\StopPict") { Up and down labels },
               0, 0, 1, 2 { No variable assignment });
  [
  ...
  ]

This statement is a latching button that sets the value of the variable called pos:

  GUIButton(10, 90, 100, 50 { Outline of the button },
            1, 1, 1, 1, 1 { No scaling },
            0, 0 { No movement },
            1, 0 { Visible; reserved },
            64 + 4, 1, 0 { Left mouse button release },
            7, 15, 8, 0 { Colors },
            0, 0 { Number of sides; reserved },
            MakeBitmap("..\Bitmaps\StartPict"),
            MakeBitmap("..\Bitmaps\StopPict") { Up and down labels },
            \_DialogFont { Font },
            1, ! pos, pos { Latching });

To situate a button at a position given by left, bottom, right, top:

[ { variable declaration and initialization }
  Left = 10;
  Right = 100;
  Top = 50;
  Bottom = 140;
]

{ ... state code ... }
  If GUIButton(0, 1, 1, 0 { Unit bounding box },
               1 - (Left) { Left scaling }, Bottom { Bottom scaling },
               Right      { Right scaling },
               1 - (Top)  { Top scaling },
               1, 0, 0    { No overall scaling/movement },
               1, 0, 68, 2, 0 { Visible; selectable },
               7, 15, 8, 0, 4, 0 { Colors; sides },
               MakeBitmap("..\Bitmaps\StartPict"),
               MakeBitmap("..\Bitmaps\StopPict") { Up and down labels },
               0, 0, 1, 2 { No variable assignment });
  [
  ...
  ]

To use the ImageSetStruct structure, you can either set the images in one statement like so: (note that in a script application, \System must be prefixed. These file names assume that the files are in the same folder as the module.)

  ButtonImages = \ImageSetStruct(MakeBitMap("UpButton.png"),
                                 MakeBitmap("DownButton.png"),
                                 MakeBitmap("HoverUpButton.png"),
                                 MakeBitmap("HoverDownButton.png"),
                                 MakeBitmap("DisabledButton.png");

You can also set the images in multiple statements (which is recommended as better practice):

  ButtonImages                    = \ImageSetStruct();
  ButtonImages\UpImage            = MakeBitMap("UpButton.png");
  ButtonImages\MouseOverUpImage   = MakeBitmap("HoverUpButton.png");
  ButtonImages\DownImage          = MakeBitmap("DownButton.png");
  ButtonImages\MouseOverDownImage = MakeBitmap("HoverDownButton.png");
  ButtonImages\DisabledImage      = MakeBitmap("DisabledButton.png");

Having initialized the structure as shown, you can then use it in a GUIButton:

  GUIButton(10, 90, 100, 50    { Outline of the button },
            1, 1, 1, 1, 1      { No scaling },
            0, 0, 1, 0         { No movement; visible },
            64 + 4, 1, 0       { Left mouse button release },
            GetSystemColor(15) { Windows button face color },
            GetSystemColor(20) { Windows button highlight color},
            GetSystemColor(16) { Windows button shadow color },
            GetSystemColor(18) { Windows button text color },
            0, 0               { Windows standard attributes },
            "Up", "Down"       { Up and down labels },
            0, 0, 1, 2         { No variable assignment },
            ButtonImages, "Click.WAV");


GUIChord

(Engine-Level Function)

Description: | Draws a chord in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DrawArcPath | DrawChordPath | DrawEllipticalPath | DrawPiePath | Ellipse GUIArc | GUIEllipse | GUIPie | GUITransform | NextFocusID | Normalize | Pie Point | Rotate | Trajectory | Vertex | VStatus
Format: | GUIChord(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Opacity, Reserved, Button, FocusID, FocusTrigger, Brush, Pen, Vertex)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Opacity
Required. Any Numeric expression, setting the opacity of the object. A value of one results in a solid, zero is invisible and values between zero and one are used as an alpha setting for opacity.
Reserved n/a
Reserved for future use, set to 0.
Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
Brush
Required. Any expression that returns a Brush value to be used to describe the fill. For a solid color fill, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Pen
Required. Any expression that returns a Pen value to describe the color, width and line style of the border. For a 1-pixel solid border, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Vertex
Required. Any expression that returns a Vertex value that describes this chord. The center point of the vertex is the center point of the ellipse that describes the chord. The two vertex handle points are used to find the start and end angle of the chord, by the angle each point makes with the center point.
Comments: This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

Example:

  GUIChord(400, 150, 600, 55 { Bounding box of the chord },
           1, 1, 1, 1, 1 { No scaling },
           0, 0 { No trajectory or rotation },
           1 { Chord is visible },
           0 { Reserved },
           0 { Not activated },
           6 { Focus ID number },
           FALSE { No focus trigger },
           Brush(12, 0, 0) { Brush light red, background
                              ignored (style is solid) },
           Pen(15, 1, 1) { Pen draws white solid lines 1 pixel wide },
           Vertex(0 { Rectangular mode },
                  Point(50, 50, Invalid, Invalid){ Center },
                  Point(50, 0, Invalid, Invalid) { Start angle },
                  Point(0, 50, Invalid, Invalid) { End angle }));

This shows a chord in the upper right corner of the window. If it is selected with the left mouse button, on the release of the mouse button the statement will return true. This is also the case if it is focused and the return key is pressed. This chord will attempt to get the keyboard input focus when the "F" key is pressed (because of the MatchKeys function in the trigger). It is focus number 6. This is the number to use in the NextFocusID function to force this graphic to get the focus. No scaling is performed, and no animation is performed.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.


GUIEllipse

(Engine-Level Function)

Description: | Draws an ellipse in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics
Format: | GUIEllipse(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Opacity, Reserved, Button, FocusID, FocusTrigger, Brush, Pen)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Opacity
Required. Any Numeric expression, setting the opacity of the object. A value of one results in a solid, zero is invisible and values between zero and one are used as an alpha setting for opacity.
Reserved n/a
Reserved for future use, set to 0.
Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
Brush
Required. Any expression that returns a Brush value to be used to describe the fill. For a solid color fill, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Pen
Required. Any expression that returns a Pen value to describe the color, width and line style of the border. For a 1-pixel solid border, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Comments: This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
GUIEllipses whose Pen value has an even numbered width are subject to pixel rounding errors, which is particularly obvious when drawing two concentric ellipses, one with an even width outline and one with an odd. To avoid this, always use all even or all odd outline widths for concentric ellipses.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

Example:

  GUIEllipse(215, 128, 315, 58,
             1, 1, 1, 1, 1 { Scaling              },
             0, 0          { Movement             },
             1, 0          { Visibility, Reserved },
             0, 0, 0       { Selectability        },
             Brush("<FFA0A0A0>", 0, 1), Pen("<FF000000>", 1, 1));

A basic gray ellipse with a single-pixel-wide, black border.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.

Related Functions:

DrawArcPath | DrawChordPath | DrawEllipticalPath | DrawPiePath | GUIArc | GUIChord | GUIPie | GUITransform | NextFocusID | Normalize | Point | Rotate | Trajectory | Vertex | VStatus


GUIPie

(Engine-Level Function)

Description: | Draws a pie-shaped wedge in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics
Format: | GUIPie(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Opacity, Reserved, Button, FocusID, FocusTrigger, Brush, Pen, Vertex)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Opacity
Required. Any Numeric expression, setting the opacity of the object. A value of one results in a solid, zero is invisible and values between zero and one are used as an alpha setting for opacity.
Reserved n/a
Reserved for future use, set to 0.
Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
Brush
Required. Any expression that returns a Brush value to be used to describe the fill. For a solid color fill, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Pen
Required. Any expression that returns a Pen value to describe the color, width and line style of the border. For a 1-pixel solid border, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Vertex
Required. Any expression that returns the vertex that describes this pie. The center point of the vertex is the center point of the ellipse that describes the pie. The two vertex handle points are used to find the start and end angle of the pie, by the angle each point makes with the center point.
The points do not describe absolute positions - that is controlled by the object's bounding box. What matters is the relation of the points to each other.
Comments: This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

Example:

  GUIPie(30, 570, 100, 420 { Bounding box of the pie },
         1, 1, 1, 1, 1 { No scaling },
         0, 0 { No trajectory or rotation },
         1, 0 { Pie is visible; reserved },
         0 { Not activated by selection },
         0 { Focus ID number },
         0 { No focus trigger },
         Brush(4, 6, 25) { Brush is dark red, brown
                             background, style is brick },
         Pen(2, 2, 2) { dark green dashed line, 2 pixels wide },
             Vertex(0 { Rectangular mode },
                    Point(30, 495, Invalid, Invalid) { Pie point },
                    Point(90, 495, Invalid, Invalid) { Start },
                    Point(30, 0, Invalid, Invalid) { End }));

This shows a red and brown brick patterned pie outlined in a dark green (slightly thick) line in the lower left corner of the window. No scaling is performed, and no animation is performed.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.

Related Functions:

DrawArcPath | DrawChordPath | DrawEllipticalPath | DrawPiePath | GUIArc | GUIChord | GUIEllipse | GUITransform | NextFocusID | Normalize | Point | Rotate | Trajectory | Vertex | VStatus


GUIPipe

(Engine-Level Function)

Deprecated. Do not use in new code.

GUIPipes from older applications will still be drawn, but will be displayed as a wide line. GUIPipe statements are no longer generated by users drawing pipes in their applications.

Description: | Draws a 3 dimensional, shaded pipe in a window and returns an indication when selected by a mouse button or the <ENTER> key.
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics
Format: | GUIPipe(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Visibility, Reserved, Button, FocusID, FocusTrigger, LowIndex, HighIndex, PixelWidth, Path)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Visibility
Required. Any logical expression. If true, the image is drawn normally. If false, the image is not drawn.
Reserved n/a
Reserved for future use, set to 0.
Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
LowIndex
Required. Any numeric expression specifying the low index into the current color palette. It is used in conjunction with the next parameter to adjust the brightness and contrast of the shading.
HighIndex
Required. Any numeric expression specifying the high index into the current color palette. It is used in conjunction with the previous parameter to adjust the brightness and contrast of the shading.
PixelWidth
Required. Any numeric expression specifying the width of the shaded pipe in pixels and is subject to applicable scaling factors.
Path
Required. Any expression that returns a Path value that is used to draw the pipe. This defines the pipe's shape.
The points do not describe absolute positions - that is controlled by the object's bounding box. What matters is the relation of the points to each other.
Comments: This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
The pipe will be drawn with a miter effect, such that pipe segments meet at 45-degree angles. For best results, use a vertex mode of 4, which preserves right angles, as shown in the example.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

Example:

  BottomLeft = Point(385, 145, Invalid, Invalid);
  TopLeft = Point(385, 25, Invalid, Invalid);
  TopRight = Point(645, 25, Invalid, Invalid);
  BottomRight = Point(645, 145, Invalid, Invalid);
  GUIPipe(385, 145, 645, 25 { Bounding box of pipe },
          1, 1, 1, 1, 1 { No scaling },
          0, 0 { No trajectory or rotation },
          1, 0 { Pipe is visible; reserved },
          0, 0, 0 { Cannot be focused/selected },
          176, 239 { Very dark gray to very light gray },
          24 { Width of pipe in pixels },
          Path(1 { Closed path },
               Vertex(4 { Manhattan  Closed Meaning that all lines are horizontal or vertical. Inspired by a skyline of tall, rectangular buildings. mode, right angles preserved },
                      BottomLeft, BottomLeft, BottomLeft),
               Vertex(4 { Manhattan mode, right angles preserved },
                      TopLeft, TopLeft, TopLeft),
               Vertex(4 { Manhattan mode, right angles preserved },
                      TopRight, TopRight, TopRight),
               Vertex(4 { Manhattan mode, right angles preserved },
                      BottomRight, BottomRight, BottomRight)));

This draws a pipe that follows an orthoganal path. The pipe is 24 pixels wide and is shaded from a dark to a light gray.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.

Related Functions:

GUITransform | Normalize | NextFocusID | Path | Pipe | Point | Rotate| Trajectory | Vertex | VStatus | ZPipe | GUIPolygon | PathDraw


GUIPolygon

(Engine-Level Function)

Description: | Draws a multi-sided polygon in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Graphics
Format: | GUIPolygon(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Opacity, Reserved, Button, FocusID, FocusTrigger, Brush, Pen, Path)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Opacity
Required. Any Numeric expression, setting the opacity of the object. A value of one results in a solid, zero is invisible and values between zero and one are used as an alpha setting for opacity.
Reserved n/a
Reserved for future use, set to 0.
Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
Brush
Required, but used only if the polygon is closed. Any expression that returns a Brush value to be used to describe the fill. For a solid color fill, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Pen
Required. Any expression that returns a Pen value to describe the color, width and line style of the border. For a 1-pixel solid border, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Path
Required. Any expression that returns a Path value that is used to draw the polygon. This defines the polygon's shape.
The points do not describe absolute positions - that is controlled by the object's bounding box. What matters is the relation of the points to each other.
Comments: This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
The handle points on each vertex control the Bezier curve used to draw that segment of the polygon.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

Example:

[
  { variable declaration & assignment }
  Left = 50; { scaling parameters }
  Right = 210;
  Top = 550;
  Bottom = 10;
]

{ ... main state for page or window... }
  GUIPolygon(0, 1, 1, 0 { Bounding box of image },
             1 - Top, Left, Bottom, 1 - Right, 1 { Scaling },
             0, 0 { No trajectory or rotation },
             1, 0 { Polygon is visible; reserved },
             0, 0, 0 { Cannot be focused/selected },
             Brush(14, 2, 13) { Brush is yellow, dark green
               background, style crosshatched },
             Pen(2, 1, 3) { dark green solid line, 3 pixels wide },
             Path(1 { Closed figure },
                  Vertex(0 { Rectangular mode, no curvature },
                         Point(0, 100, Invalid, Invalid) { Center },
                         Point(0, 100, Invalid, Invalid) { In handle },
                         Point(0, 100, Invalid, Invalid) { Out handle }),
                  Vertex(0 { Rectangular mode, no curvature },
                         Point(100, 100, Invalid, Invalid){ Center },
                         Point(100, 100, Invalid, Invalid){ In handle },
                         Point(100, 100, Invalid, Invalid){ Out handle }),
                  Vertex(0 { Rectangular mode, no curvature },
                         Point(100, 0, Invalid, Invalid) { Center },
                         Point(100, 0, Invalid, Invalid) { In handle },
                         Point(100, 0, Invalid, Invalid) { Out handle })));

This shows a triangle at the top of the window. It has a yellow crosshatched pattern on a dark green background and is outlined by a thick dark green line. It cannot be focused. No animation is performed.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.

Related Functions:

DrawPath | NextFocusID | Normalize | Point | Rotate | Trajectory | Vertex | VStatus


GUIRectangle

(Engine-Level Function)

Description: | Draws a rectangle in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics
Format: | GUIRectangle(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Opacity, Reserved, Button, FocusID, FocusTrigger, Brush, Pen)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Opacity
Required. Any Numeric expression, setting the opacity of the object. A value of one results in a solid, zero is invisible and values between zero and one are used as an alpha setting for opacity.
Reserved n/a
Reserved for future use, set to 0.
Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
FocusID is any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
Brush
Required. Any expression that returns a Brush value to be used to describe the fill. For a solid color fill, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Pen
Required. Any expression that returns a Pen value to describe the color, width and line style of the border. For a 1-pixel solid border, you may use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Comments: This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

Examples:

  GUIRectangle(19, 126, 143, 58,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Brush("<FFA0A0A0>", 0, 1), Pen("<FF000000>", 1, 1));

A basic gray rectangle with a single-pixel-wide, black border.

  GUIRectangle(25, 100, 225, 80 { Bounding box of rectangle },
               1, 1, 1, 1, 1 { No scaling },
               0, 0 { No trajectory or rotation },
               1, 0 { Rectangle is visible; reserved },
               4 { Left mouse button },
               5 { Focus ID number },
               MatchKeys(2, "T"){ Focus trigger },
               Brush(14, 0, 1) { Brush is yellow, background
                                 ignored (style is solid) },
               Pen(2, 1, 1) { Pen is dark green solid
                              line, 1 pixel wide });

This shows a rectangle in the upper left corner of the window. If it is clicked with the left mouse button, or if it is focused and the return key is pressed, it will return true. This rectangle will attempt to get the keyboard input focus when the "T" key is pressed (because of the MatchKeys function in the trigger). It is focus number 5. This is the number to use in the NextFocusID function to force this graphic to get the focus. No scaling is performed, and no animation is performed.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.

Related Functions:

Bar | Box | NextFocusID | Normalize | Rotate | Trajectory | ZBar | ZBox| GUITransform | VStatus


GUIText

(Engine-Level Function)

Description: | Draws formatted text in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | BuffWrite | FileSize | Format | FWrite | GetStreamLength | Print | TextBox
Format: | GUIText(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Opacity, Options, Button, FocusID, FocusTrigger, Brush, Pen, Font, HCenter, VCenter, Format, V1, V2, ...)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Opacity
Required. Any Numeric expression, setting the opacity of the object. A value of one results in a solid, zero is invisible and values between zero and one are used as an alpha setting for opacity.
Options
Required. Any numeric expression giving how a font behaves with regards to scaling, as follows:
Options | Font Behavior
0 | The text will stay at its native font size, even though all the other graphics around it are being scaled with the page
1 | The font size will scale proportionally to the vertical scaling of the page. If the text is drawn by a widget, it will scale doubly, both with the containing widget and the containing page.
2 | Typically used by a widget that draws its own GUIText. By setting Options to 2, the text inside the widget will only scale in proportion to the topmost scaling, i.e. the page's scaling, and will ignore any scaling of the intermediate widget(s).

Text squeezing is on by default, reducing text by as much as 35% to fit within the available space. If you set bit 3 (add 0b1000 to whatever value you are using in the Options parameter), then text will not scale down to fit within the available space. Text that does not fit is clipped.

Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
Brush
Required. Any expression that returns a Brush value to describe the background. A solid-color background may be defined by using any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Pen
Required. Any expression that returns a Pen value. Only the color property of the pen will be used. You may also use any of the following:
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Font
Required. Any expression that returns a Font value used to display the text.
HCenter
Required. Any numeric expression that specifies the horizontal justification and clipping, as shown in the following table:
Value | H. Justification | Clipping
0 | Left | Right
1 | Left | Both
2 | Left | Left
3 | Center | Right
4 | Center | Both
5 | Center | Left
6 | Right | Right
7 | Right | Both
8 | Right | Left
VCenter
Required. Any numeric expression that specifies the vertical justification and clipping, as shown in the following table:
Value | V. Justification | Clipping
0 | Top | Bottom
1 | Top | Both
2 | Top | Top
3 | Center | Bottom
4 | Center | Both
5 | Center | Top
6 | Bottom | Bottom
7 | Bottom | Both
8 | Bottom | Top
Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be written. This format is similar, but not identical, to the C language format string for the printf function, whereby each of the Vn parameters in the statement is assigned to a % format specification in the order in which each appears in the list.

Note that like a standard text string, these format specifiers must also be enclosed by double quotes.

If a format specification appears for which there are no remaining V parameters, the format specification characters themselves are output to the stream exactly as they appear in the Format.

For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[-][+][SPACE][#][width][.precision]type

where

% (percent sign) is mandatory;

- (minus sign) (optional) causes the data to be left justified within the field (for binary types b and ASCII character types c, this option is ignored);

+ (plus sign) (optional) causes positive numbers to be prefaced with a + sign (negative numbers are unaffected). This allows easy alignment of positive and negative numbers in a printed column of numbers. For binary types b and non-numerical types, this option is ignored;

space represents the single space character, and is similar to the [ + ] option but places a single space rather than a plus sign in front of positive numbers (negative numbers are still unaffected). This allows alignment of a column of numbers without having to show all signs. For binary types b and non-numerical types, this option is ignored;

# (hash mark) When used with the o , x , or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.

width is a number that specifies the minimum number of characters to output. Numbers that require more characters than specified by the width value are truncated on output. If the number of characters in the number or string is less than width, blanks will be added to the left or right, depending upon whether the output is left or right justified (i.e. whether the [ - ] option has been specified) until the width is reached. For binary types b and ASCII character types c, this option is ignored;

precision has a different meaning for each of the type options as follows:

  • Integer types d, l, u, o, x, and X precision specifies the minimum number of digits to output. If the number contains fewer digits, leading zeroes will be added to the left of the number. If precision is 0, omitted, or if the decimal point appears without a number following it, the precision defaults to 1. The number is not truncated.
  • Floating point types e and E precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision in this case is 6. If the precision is 0 or if the decimal point appears without a number following it, no decimal point appears in the output.
  • Floating point type f precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision is 0. If the precision is explicitly 0, no decimal point is output. If a decimal point is output, at least one digit will be placed before the decimal point.
  • Floating point types g and G precision specifies the maximum number of significant digits to be output. If no precision is specified, all significant digits are written.
  • String type s precision specifies the maximum number of characters of the string to be output. If the string contains more characters than specified by the precision, the string is truncated and only the first characters are written. If the precision is not specified, all of the string characters are output.
  • Byte type c The precision option is ignored.
  • Binary type b The precision option is ignored.

type is mandatory. The type specification must be one of those listed below.

Note: The case of the letter is important. Specifying a character for the type that is not in this list will result in all the characters following the % up to that point to be output exactly as they appear in the Format string.

Type | Meaning
nb | Binary format; where n is a number indicating the type of value (see below).
c | Single character (byte values from 0 to 255)
d | Signed decimal 64-bit integer, 64-bit output by default
e | Signed exponential; exponent key is "e".
E | Signed exponential; exponent key is "E".
f | Signed floating point.
g | e or f format, whichever is shorter.
G | E or f format, whichever is shorter.
h | Handle to a window.
i | Signed decimal 64-bit integer, 64-bit output by default
o | Unsigned octal integer. Default 32-bit integer. Use %llo to output 64-bit value.
p | Pointer to a buffer.
s | Text string.
t | Writes a utf-8 string as used by OPC UA binary TCP: a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string
u | Unsigned decimal 64-bit integer, 64-bit output by default
x | Unsigned hex integer using "abcdef". Default 32-bit integer. (See following note.)
X | Unsigned hex integer using "ABCDEF". Default 32-bit integer. (See following note.)

When writing negative values using either x or X format codes, the output will use a minimum of 32 bits because that is the smallest possible size to display the full information. Defining a format string such as "%4X" will not reduce this to 16 bit output for negative values. To output 64-bit values, use the modifier ll. %llx and %llX output 64-bit values.

nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.

n | Value Type
0 | Byte, unsigned
1 | Signed short integer (2 bytes)
2 | Signed long integer (4 bytes)
3 | IEEE single precision float (4 bytes)
4 | <obsolete>
5 | IEEE double precision float (8 bytes)
6 | <obsolete>
7 | Unsigned short integer (2 bytes)
8 | Unsigned long integer (4 bytes)
9 | Writes a time in Microsoft FILETIME format, which contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).
10 | Outputs signed 64-bit integers in binary form.

Note: Other options such as width and precision do not apply to the b type.

c, Byte type: This type is not representative of a single character in a string, but rather, represents single bytes. Input values (the Vn parameter to which this format specification applies) must be integers in the range of 0 to 255. Strings are not acceptable input values. Note that the %c format specifier behaves differently when used in an output statement such as BuffWrite than when used in an input statement, such as BuffRead. Some UTF-8 characters can require multiple bytes. Values from 0-127 are consistent between the traditional ASCII encoding and the UTF-8 encoding.

d, Signed decimal 64-bit integer:

e, Signed exponential: Exponent key is "e"

E, Signed exponential: Exponent key is "E"

f, Signed floating point

g, e or f formats: Whichever is shorter

G, E or F formats: Whichever is shorter

h, Window handle type: This type is used for building structures to be handed to DLLs and should be used by advanced users only.

p, Buffer pointer type: This type is also used for building structures to be handed to DLLs and should be used by advanced users only.

s, Text string type:

t, Writes a utf-8 string as used by OPC UA binary TCP:
a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string

u, Unsigned decimal 64-bit integer,

x, Unsigned hex integer using "abcdef": 32-bit value by default. Use modifier %llx for 64-bit value output.

X, Unsigned hex integer using "ABCDEF": 32-bit value by default. Use modifier %llX for 64-bit value output.

SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Plain text Text in the Format parameter is written exactly as it appears, with three exceptions:

  • Percentage sign (%) Because format specifications for the Vn parameters are indicated by a percentage sign, to include an actual percentage sign as part of the Format parameter, precede it with a backslash character (i.e. \%).
  • Backslash character (\) Because this is used to indicate special control characters such as line feed, carriage return, and form feed, to write a backslash as part of the Format parameter, use two backslash characters (i.e. \\).
  • Quotation marks (") The entire test string is delimited by quotation marks, so to include a set of quotation marks as part of the Format parameter, use a set of quotations marks (i.e. "").

Control characters In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result (notice that the letters must be lower case):

Code | Meaning
\b | Backspace
\f | Form feed
\n | Line feed
\r | Carriage return
\t | Horizontal tab
\v | Vertical tab

\nnn In addition to the above predefined codes, \nnn may be used, where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

znnn Escape character where nnn is the 3-digit ASCII code
For example: SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Offset is any numeric expression giving the starting buffer position in bytes for the write, starting at 0.

V1, V2, ...
Required. Any expressions giving the values to be output in the form described by the Format parameter. Each of the Vn parameters is evaluated and written in the order in which each appears in the parameter list. The way in which they are formatted is dictated by the % format specifications. V1 is formatted by the first % sequence in the Format parameter, V2 by the second, and so on. If there are more V parameters than % sequences in the Format string, the remainder are ignored. If there are fewer V parameters than % sequences in the Format string, the remaining % sequences are written literally without any translation.
If a numeric value is Invalid or outside of the range of the type indicated by the format specifier, a 0 is used as its value. If a text string value is Invalid, spaces will be output. Invalidity of Vn parameters does not preclude execution of this function.
Comments:

This function is a layered graphics statement. See Use Scaling to Position GUI Objects for information about positioning a layered graphic.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.

It produces formatted text in exactly the same manner as BuffWrite, FWrite, and SWrite. The text is displayed directly on the screen, centered in the reference box after any animation is applied. Line breaks are not permitted. To display text with line breaks,TextBox may be more suitable. Binary formats are not useful here and will produce strings with non-printable characters.

As of version 12.0, VTScada expects all strings to be encoded using UTF-8.

Will not display tab characters.

Example:

Examples often use English text in labels so that you can make a copy as a starting point when building your own version.
Better practice is to replace the text with phrase keys, and the \GetPhrase() function.

The following example assumes a variable named, ValvePosition.

  GUIText(0, 100, 100, 0 { Bounding box of text },
          1, 1, 1, 1, 1 { No scaling },
          0, 0 { No trajectory or rotation },
          1, 0 { Text is visible; reserved },
          0, 0, 0 { Cannot be focused/selected },
          Brush(12, 0, 1){ Brush is red, background
                          ignored (style is solid) },
          Pen(15, 1, 1) { White solid line 1 pixel wide },
          Font("Courier" { Font name },
               0 { Character set },
               14 { Height },
               0 { No rotation },
               0 { Weight },
               0 { Not italicized },
               1 { Fixed pitch }),
           4 { Center horizontally },
           4 { Center vertically },
          "Valve = %6.2f%% open." { Format specifier },
          ValvePosition { First value });

This shows text in the upper left corner of the window. It cannot be focused. No scaling or animation is performed. If the variable, ValvePosition, contains the number 56.789, the text is displayed as:

Valve = 56.78% open.

See GUITransform for an example of how to compute the position dynamically.

Related Functions:

BuffWrite | Font | FWrite | NextFocusID | Normalize | Point | SWrite | TextAttribs | VStatus | Trajectory | ZText | TextBox


GUITransform

(Engine-Level Function)

Description: | Applies a graphical transformation to all graphics in a module and returns an indication when selected by a mouse button or the <ENTER> key.
Returns: | GUI Object Return Codes
Usage: | Steady State only.
Function Groups: | Graphics, Advanced Module
Related To: | GetXformRefBox | ImageParmSet | NextFocusID | Normalize | Point | Rotate | Trajectory | UnTransform | Vertex | VStatus | Window
Format: | GUITransform(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Visibility, Options, Button, FocusID, FocusTrigger, ModuleCall)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleBottom
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleRight
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleTop
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.
ScaleWhole
Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.
Trajectory
Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.
Rotation
Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.
Visibility
Required. Any logical expression. If true, the image is drawn normally. If false, the image is not drawn.
Options

Bit 1 (2^1) == Marks the transform as a GUIStretch. Rendering of the transform is done by stretching the content.

Bit 2 (2^2) == Transform may be dragged onto a window from the palette.

All transforms in a palette that can be dragged must have both bits set. A transform may be dragged even if its visibility flag is set to zero.

Note that only Windows with bit 22 of the Style parameter set can function as a drop-target. Windows with bit 23 of the Style parameter set are palette windows.

Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value | Locator Buttons
0 | No button combination will activate this graphic
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID
Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is 0, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
ModuleCall
Required. Any function containing a module call.
Comments:

This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1st 42 pixels of a VTScada application will be obscured by the title bar, if present.
This is typically used to display a module which contains an active graphics symbol.
The transformation is applied by finding the minimum area box which contains all reference box coordinates (the first 4) for all graphics active in that module. A scaling is performed on all graphics in that module to make them appear in the reference box specified in the transform.
This is typically used to make a group of objects move and scale together. For example, a module (called PumpSymbol) could draw a symbol (such as a pump). By applying a transform to this module, it can be made to appear in a certain area of the screen.
Any mouse functions contained by the transform will also be affected. For example, if the object is rotated 90 degrees XLoc will begin to behave like YLoc.

A draggable GUITransform has two renderings. The palette rendering is what is displayed in the palette and is the image attached to the mouse at the start of dragging the transform onto a drop-target window. When the mouse cursor is moved over a drop-target window, the module called by the GUITransform is rendered at the native size of the called module and displayed in its place. The rendering is scaled according to the zoom factor of the drop-target window. Moving off the drop target window again displays the palette rendering.

The relative mouse position within the graphic when the drag operation is started is maintained throughout the operation. Therefore, when the image switches from the palette rendering to the called module rendering, the mouse position within the called module rendering is over the same feature of the graphic as when the palette rendering is used.

Examples:

  GUITransform(0, 150, 100, 50 { Bounding box of object },
               1, 1, 1, 1, 1 { No scaling },
               0, 0 { No trajectory or rotation },
               1, 0 { Object is visible; reserved },
               0, 0, 0 { Graphic cannot be focused },
               Flow = PumpSymbol(1, amps) { A sample module call });

This shows a pump object in the upper left corner of the window. It cannot be focused. No extra scaling is performed, and no animation is performed.

This shows how a symbol can be defined once, and positioned in a multiple area (reused).

To use the magic formula to situate an image that reacts like a button at a position given by variables Left, Bottom, Right, Top:

[
  Left   = 100;
  Right  = 175;
  Top    = 100;
  Bottom = 135;
]

Main [
  If GUITransform(0, 1, 1, 0 { Unit bounding box },
                  1 - Left { Left scaling },
                  Bottom { Bottom scaling},
                  Right { Right scaling },
                  1 - Top { Top scaling },
                  1, 0, 0 { No overall scaling/movement },
                  1, 0 { Object is visible; default options },
                  4, 0, 0 { Respond to left-click.
                            Graphic cannot be focused },
                  Scope(\Code, "Library", TRUE)\Bitmap("Bitmaps\Symbols\Smile face.wmf"));
  [
  ...
  ]

The following displays an image that will re-size to match the Window object it is displayed within:

[
  Bottom;
  Right;
]

Main [
  Bottom = VStatus(Self(), 12);
  Right  = VStatus(Self(), 11);
  GUITransform(0, 1, 1, 0   { Reference rectangle   },
               1- 0         { Left edge of window   },
               Bottom       { Bottom edge of window },
               Right        { Right edge of window  },
               1- 42        { Top edge of window under title bar },
               1            { No overall scaling    },
               0, 0         { Movement              },
               1, 0         { Visibility, Reserved  },
               0, 0, 0      { Selectability         },
               Scope(\Code, "Library", TRUE)\Bitmap("Bitmaps\Symbols\Smile face.wmf"));
...


H Functions

The sections that follow identify all VTScada functions beginning with "H".


HasCompilationErrors

Description: Reports if the working copy presently has unresolved compilation errors
Returns: Boolean
Usage: Script Only.
Function Groups: Configuration Management
Related to: IsAppEditable |
Format: \AppLayer.HasCompilationErrors()
Parameters: None.
Comments:

Returns TRUE if the last attempted compilation of the layer failed. This is a situation that shouldn't ever be encountered, as any attempt to commit a compilation error to the repository should fail, with the working copy (WC) being rolled back to a compilable version.

However, if the WC becomes corrupted or if there are compilation dependencies outside of the working copy, then in theory the WC can be in an unresolvable, non-compilable state, which is what this subroutine reports. This function should only be called as a subroutine, following Activation.


Hash

(Engine-Level Function)

Description: | Generates a hash - a text string of bytes - of the given string.
Returns: | Text
Usage: | Script only.
Function Groups: | Cryptography
Related to: | Encrypt | Decrypt |ImportKey | GetCryptoProvider
Format: | Hash(PlainText[, AlgID, Seed, HashHandle, CSP])
Parameters: |
PlainText
Required. Any text string to create a hash from.
AlgID
Specifies the algorithm to use when creating the hash. Valid options are as follows: Defaults to 0 (SHA-1) if missing or invalid.
AlgID | Hash
0 | SHA-1 (160 bit hash)
1 | MD5 (128 bit hash)
2 | SHA-2 (256 bit hash)
3 | SHA-2 (384 bit hash)
4 | SHA-2 (512 bit hash)
Seed
Optional text buffer, which will be used as a seed for the hash algorithm. The contents of the buffer will be pre-pended to the text from the first parameter when creating the hash.
HashHandle
Optional. LValue. If Invalid, a hashing handle for the given AlgID is created and used for this and subsequent calls that supply this handle. No output is generated until a call, with this handle, is made with an Invalid PlainText parameter, at which time the hash built up using the handle is returned. At that time, the handle is destroyed and the LValue invalidated.

For one-time hashing, the hash value is returned from this function as a text string of bytes. For progressive hashing the return value of this function is Invalid until a call with an Invalid PlainText parameter and a valid HashHandle is made.
CSP
Optional. The CSP to be used for hashing. This has the same type as used in ImportKey() and Encrypt(). Generated by a call to GetCryptoProvider.
Comments & Example

The use of a seed string is functionally equivalent to the following example, but will execute slightly faster.

    X = Hash(Concat("XYZ", "ABCDE"), 2);

Does not support CNG (Cryptography New Generation).


HasMetaData

(Engine-Level Function)

Description: | Tests whether a given variable is a dictionary. Because the default behavior of most operands and functions on dictionaries is to return just the value of the dictionary’s root, this function provides the only means to determine whether a variable contains a dictionary.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Dictionary, Variable
Related to: | Dictionary | MetaData | IsDictionary
Format: | RVAL = HasMetaData( dictionary );
Parameters: |
Dictionary
Required. The name of any variable to test.
Comments: Returns TRUE if the object is a dictionary and FALSE otherwise.
Because the default behavior of most operands and functions on dictionaries is to return just the value of the dictionary’s root, this function provides the only means to determine whether a variable contains a dictionary.


HasReturnStatement

(Engine-Level Function)

Description: | Examines a specified object to see if it is running a return statement in steady-state.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | SetReturnValue
Format: | HasReturnStatement(Object)
Parameters: |
Object
Required. Reference to the object of interest.
Comments:

This function examines a specified object to see if it is running a return statement in steady-state. Returns 1 if such a statement is running, 0 if no return statement is running in steady-state, or Invalid if the first parameter cannot be resolved to an object.


HasUndeployedChanges

Description: | Finds whether the local machine is maintaining changes that have not been deployed, including changes that have been recorded by EditFile but have yet to be committed.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Configuration Management
Related to: | HasCompilationErrors | IsAppEditable | IsRunOnly |
Format: | \AppLayer.HasUndeployedChanges()
Parameters: | none
Comments: | This function returns TRUE if the Layer is running with changes that have not been deployed. This may be true if running on a local branch (auto deploy is off), or there are working copy modifications that have yet to be committed such as page changes.

Examples:

  If 1 NextState;
  [
    IfThen(\AppLayer.HasUndeployedChanges(),
     ...
    )
  ]


Help

(Engine-Level Function)

Description | Calls a topic in a help system.
Returns | Nothing
Usage | Script Only.
Function Groups | Help
Related to: | SetHelp
Format | Help(FileName, Option, SearchValue)
Parameters |
FileName

Required. Any text expression for the name of the help system to display. May be the name of a .CHM file. To call a topic in the VTScada help system, use the system property, \DevHelpFile.

Refer to the comments section for more options.

Option
Required. Any numeric expression controlling how the topic will be located within the help system, as indicated by the following table. Not all options work with all help system formats. Calls to topics using context sensitive help ID values should use option 3.
Option | Display Option | SearchValue
0 | Help contents | 0
1 | Key | Key string
2 | Partial key | Partial key string
3 | ID | ID number
4 | Help Topics | 0
SearchValue
Required. Any expression that provides the proper qualification needed by the Option parameter as indicated by the preceding table.

Comments

If calling a help system compiled using the DocToHelp NetHelp system, use the string, "MyHelpfolder\NetHelp". If calling your own help system compiled using the Flare HTML5 system, use the string "MyHelpFolder\MadCapWebHelp".

DocToHelp and Flare are products of Madcap Software Ltd. and are recognized by VTScada.

The .HLP format is obsolete and will not open in modern versions of Windows.

Example:

  If ZButton(10, 40, 110, 10, "Help", 1);
  [
    Help("C:\VTScada\MyCustomHelpFile.chm", 0, 0);
  ]

This displays a button on the screen that when pressed, opens the table of contents of the named CHM format file.

  If WinButton(513, 135, 547, 101,
               0                      { normal appearance },
               "?"                                { label },
               1                { focus id enables button },
               0                    { default system font },
               Invalid                { no ToggleVal used },
               Invalid     { image displayed in the button});
  [
    Help(\DevHelpFile, 3, 10180);
  ]

This will display a button that when pressed will open topic id 10180 in the VTScada help system.


HexToBuff

(System Library)

Description: | Converts a hex string to a binary buffer.
Returns: | Buffer
Usage: | Script only.
Function Groups: | String and Buffer
Related to: | BuffToHex
Format: | System.HexToBuff(HexValue)
Parameters: |
HexValue
Required. Any string representing a hexadecimal value.
Comments: Given an invalid parameter value, the function will return Invalid.

Examples:

    BuffResult = System.HexToBuff("57494C4C");

BuffResult will contain "Will".


HighlightModule

Obsolete. Code using this function will compile, but will do nothing.

Description | Highlighted a module in a module tree.
Returns | Boolean
Usage | Script Only.
Function Groups | Module Tree Diagram
Related to: | HighlightState | HighlightTree | ModuleHighlighted
Format | HighlightModule(ModuleTree, Module, Mode)
Parameters |
ModuleTree
Required. Any expression for the module tree value.
Module
Required. Any expression for the code value of the module.
Mode
Required. Any numeric expression that indicates how to highlight
Mode | Highlight
0 | Turn on highlighting
1 | Turn off highlighting
2 | Toggle highlighting
Comments none


HistorianConnect

(Engine-Level Function)

Description | Opens a logging connection and controls the lifetime of all resources associated with that connection.
Warning | This function should be used only by advanced programmers. The functions, WriteHistory and GetTagHistory and GetLog are recommended for most uses.
Returns | Invalid if the parameters are invalid, 0 otherwise
Usage | Script Only.
Threaded | Yes
Function Groups | Logging
Related to: | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords
Format | HistorianConnect(ConnectionType, ConnectionString, HistorianName, Namespace, HistorianHandle, Error[, SchemaToTableNameDict, UptimeTagName])
Parameters |
ConnectionType

A text keyword that indicates the storage methodology required. Permitted values are

  • FileDB for storage on a local or networked hard drive, using the VTScada proprietary database format.
  • ODBC for storage using a local or networked DBMS, accessed via ODBC drivers.

The keywords are not case-sensitive.

ConnectionString

A text string that provides the information required to connect to the database specified by the ConnectionType. (Non-ASCII characters will be removed.)

ConnectionType | ConnectionString
FileDB | The root path to the storage folder. If a relative path is provided, then it is relative to the VTScada installation directory
ODBC | Any valid ODBC connection string. This may begin with DSN= to specify a data source name, or it may be a complete connection string.
HistorianName
An ASCII text string (letters and numbers only) providing the Historian Tag Name. This string is used as part of the full path to a file-based data store and is also the name of the UpTime table in the database.
Namespace

The top-level namespace in which to store data (may be an empty string).

Non-ASCII characters will be removed.

HistorianHandle
Historian Connection handle value. For the VTScada proprietary data store, this will be invalidated on an "out of disk space" error, or on loss of access to the file storage. For other databases, this will be invalidated on any connection loss.
Error

A value in which the error code, (if any) will be returned.

Defined error codes are provided in the reference chapter. See: Historian Error Codes

SchemaToTableNameDict
Optional dictionary. Maps historian schema strings to table names for use with ODBC-backed historians. Typically assembled from the HistorianODBCTableNames0 ... HistorianODBCTableNamesN settings, with the dictionary key consisting of the schema string and the value specifying the table name.
UptimeTagName
Optional Text. Specifies the table name to use when accessing VTScada uptime history. When not specified the value given in the HistorianName parameter is substituted.
Comments

The connection to the data store is done asynchronously. HistorianHandle will become valid when the connection has been made. If the connection fails Error will be set to some sort of error information.
Each separate connection will create its own thread for writing data. Invalidating the connection handle will flush all pending write data and then terminate the thread, DB connections etc.
The Namespace parameter may be used to allow the same root storage location to be shared by multiple applications or machines or both.

The UptimeTagName parameter ensures that the uptime can be obtained regardless of whether StorageName parameters vary from one server to another for the same Historian. Without this parameter, and with a typical Historian tag configuration, the HistorianName is derived from the Historian tag's "Storage Name" parameter. If this varies by machine (for example where a parameter expression is used to derive a different values across workstations), it can lead to an incomplete view of the overall VTScada uptime and in turn lead to inconsistent invalidation of data returned from the historian depending on the workstation performing the query.

Example:

No example provided. WriteHistory and GetTagHistory are recommended for most use.


HistorianDeleteRecords

(Engine-Level Function)

Description: | Conditionally deletes full sequences of records from the data store identified by the ConnectionHandle
Warning: | This function should be used only by advanced programmers. The functions, WriteHistory and GetTagHistory and GetLog are recommended for most uses.
Returns: | An array of SequenceID values, indicating which sequences were deleted
Usage: | Script Only.
Threaded: | Yes
Related to: | HistorianConnect | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords
Format: | HistorianDeleteRecords (ConnectionHandle, TagName, Schema, MinGroupValue, NumRecordsToKeep)
Parameters: |
ConnectionHandle
As returned by an HistorianConnect call.
TagName
A text string identifying the tag whose records are to be deleted.
Schema
This is a textual representation of a schema structure.
MinGroupValue
All sequences with a Group Value (the last 4 bytes of the 12-byte SequenceID) less than this value will be deleted, provided that the NumRecordsToKeep condition is also met.
NumRecordsToKeep
A numeric expression, specifying a minimum number of records that are to be kept for the tag.
Comments:

This function will delete as many entire sequences from storage for a tag as it can so that at least NumRecordsToKeep records are kept, and only sequences with a lower group value than MinGroupValue are deleted.

While considered to be threaded, this function has no lifetime after it passes the records to another thread for deletion.

Example:

No example provided. This function is not recommended for most use.


HistorianGetData

(Engine-Level Function)

Description: | Queries an Historian data store and returns an array of processed records. For most uses, GetTagHistory is recommended in place of HistorianGetData.
Returns: | Invalid if parameters are invalid, otherwise 0.
Usage: | Script Only.
Threaded: | Yes
Related to: | HistorianConnect | HistorianDeleteRecords | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords
Format: | HistorianGetData (ConnectionHandle, TagName, Schema, Data, FieldNames, TPP, StartTime, EndTime, NumEntries, Modes, StaleTimes, LastRestartTime, ErrorCode)
Parameters: |
ConnectionHandle
As returned by an HistorianConnect call.
TagName
A text string representing the desired table name. Engine code may modify this to conform with storage limitations.
Schema
A text expression describing the schema from which to retrieve data.
Data
A variable in which the data will be returned.

This will be a two-dimensional array representing the returned data, indexed by [col][row]. If TPP is non-zero, the number of rows in the result set will equal the value of the NumEntries parameter. If TPP is zero there could be fewer rows than specified by NumEntries
FieldNames
Names of the fields.
Typically "Value" for most tag values, or "Value!" for tag attribute data. (Value! was introduced with VTScada version 12 and is not available in legacy data. It cannot be retrieved by SQL queries.)
TPP
Required. Any numeric expression giving the time span in seconds for each array entry. Each array element will contain the data which correspond exactly to this time period which corresponds to 0 or more data points. If TPP is positive and FieldNames selects a text value, the first entry which falls in a time is read and Mode is ignored.

If TPP is equal to 0, the data is read and placed in the array on a one to one basis.

If TPP is less than 0, an error will be returned.
StartTime
Timestamp in UTC. The report will include values matching and later than this time.
EndTime
Ending timestamp. Ignored if TPP is non-zero. The report will include values less than and matching this value.
NumEntries
Number of log entries in the array (numEntriesRequested - determined by Size or TPP parameters of Getlog)
Use a negative value to retrieve values in reverse chronological order.
Modes

Optional numeric expression giving the method of handling the data. If TPP is greater than 0, the values that fall in each time span will be represented as follows:

Mode | Data Collection
0 | Time-weighted average
1 | Minimum in range
2 | Maximum in range
3 | Change in value over the range
4 | Value at start of range
5 | TimeOfMinInRange
6 | TimeOfMaxInRange
7 | SumOfZtoNZTransitions
8 | SumOfNonZeroTime
9 | Totalizer. (Invalid is counted as zero)
10 | Deprecated. Equivalent to mode 4.
11 | Difference between the start and end values of a range (see following note)
12 | Bitwise OR (see following note)
13 | Bitwise AND (see following note)
14 | Value at end of range

Mode 11:

This is for hardware that can count to a limited number, then rolls over to start a fresh count. For example, a tag that counts equipment starts, but which can only count from 0 to 15 before wrapping around to start again. This gives a value of sixteen per roll-over since there must be one more start after fifteen to have the roll-over occur. A graph of a very simple case where there is a start every second would look like the following:

(Each rollover must be followed by a fresh start, not a gradually declining value. If there are a series of declining values then, because each is less than the previous, each counts as another rollover.)

The formula used is (RolloverCount * RolloverValue) + (LastValidValue - FirstValidValue).

Where, for any given time interval:

  • Rollovers are counted when a new value is smaller than the last valid value.
  • The RolloverValue is passed to the function in the parameter StaleTime.
  • LastValidValue starts with the last valid value in the previous time interval (if any), and is updated with each new valid value within the time interval.
  • FirstValidValue starts with the last valid value in the previous time interval (if any), and is updated with only the first valid value found in the current time span.

Given this example, suppose that you want a count of starts in each thirty-second interval. In the first interval there is no previous valid value, one wrap-around and a last valid value of 12. (1*16) + (12 - 0) = 28.

This is an idealized case. Consider a more realistic case where not all values are logged. (This may be due to factors such as polling intervals, deadbands, hardware, etc.) The following graph shows the same data where the orange dots represent values obtained and logged and the gray line represents what really happened:

In the first 30 seconds there is one roll-over when the value drops from 13 to 2. The first value is 0 and the last is 11. The Historian will return 27: (1*16) + (11-0) = 27.

The Historian will return 30 for the period from 30 to 60. The first valid value (carried from the previous period) is 11. The last valid value is 9 and there are two roll-overs. (2*16) + (9-11) = 30.

Modes 12 and 13:

These are intended to provide a summary of the bit-wise Historian value attributes within a query. (Value attributes were added in VTScada version 11.5 / 12.0)

With mode 12, the first value is OR'd with zero, and each successive value in the time period is OR'd with result of the last comparison. From the result you will know whether any particular attribute bit was set on any values within the period.

With mode 13, the first value is AND'd with a value having all bits set to 1 and each successive value is AND'd with the result of the last comparison. From the result you will know whether any particular attribute bit was set on all values within the period.

In the case of modes 5 and 6, FieldName should still be set to indicate the field on which the mode is to act. The return values will be times indicating the maximum or minimum in that field for each time span.

If TPP is less than or equal to 0, Mode is ignored. If the data is text, the first entry in a given time range is used for the array entry and Mode is ignored.

It is possible to retrieve more than one mode in a single GetTagHistory statement. To do this, pass an array of values in as the Mode parameter.

StaleTimes

The meaning of StaleTime depends on the selected Mode.
For all modes but 11, this optional parameter sets a maximum validity duration for data elements that are being TPP processed. Normally, every data point is treated as remaining valid until the next data point. If a valid StaleTime parameter is given, then any data point will be treated as invalid, StaleTime seconds after the recorded time. If TPP is less than or equal to 0, StaleTime is ignored. If StaleTime is not required but EnableDowntimeOverride is, then StaleTime should be given as an Invalid value.

For Mode 11, this is the maximum value of a range (see comments in the Mode parameter.).
It is possible to specify more than one stale time in a single GetTagHistory statement. To do this, pass an array of values in as the StaleTime parameter.

LastRestartTime
A Timestamp value used in UpTime processing. (see comments)
ErrorCode

A value in which the error code (if any) will be returned.

Defined error codes are provided in the reference chapter. See: Historian Error Codes

Comments:

If a record has been written that duplicates the timestamp of an existing record then, when reading, the newer record will be supplied in place of the older. This arbitration is performed by means of a Secondary (or Generation) Timestamp.

To support this, properties can be associated with Schema columns. One property defines the Primary Timestamp for the record and another property value defines the Secondary (or Generation) Timestamp for the record. If no secondary timestamp column is defined, then arbitration will not take place. If no primary timestamp column is defined, then retrieval of a specific time range is not possible.

Uptime processing allows VTScada to show gaps in data for periods when VTScada did not record any data. As long as there is at least one Historian logging on a machine, the logging system is deemed available and there is no downtime. Any gap indicates that the logging system was down. (That is, the application may be running but the Historian has lost its connection to its SQL database). The UpTime information is logged by an Historian tag and is therefore to be found in the Historian’s normal log data table.

No downtime invalids are inserted when reading in the reverse order.

Value Attributes...

Querying Value Attributes

Version 12 of VTScada introduced value attributes. These can be queried using "Value!" rather than "Value" for the field name or array of field names. Value! stores bitwise values according the following table.

Attributes flagged with a star (*) apply only if the I/O tag is attached to a DNP3 driver or a custom driver supporting this feature.

Refer to the constant, #NUM_DATA_ATTR_BITS, to discover the number of bits in data attributes for your version of VTScada.

Bit Number | Defined Constant Name | Meaning
0 | #DATA_ATTR_MANUAL_DATA | The value was from the tag's ManualData parameter
1 | #DATA_ATTR_MANUAL_ENTRY | The value was manually entered
2 | #DATA_ATTR_EDITED_DATA | The historical value was manually edited
3 | #DATA_ATTR_QUESTIONABLE | The tag was marked as questionable
4 | #DATA_ATTR_STALE_DATA | The value was reported as stale by VTSDriver
5 | #DATA_ATTR_IMPORTED | The value was imported from a CSV file
6 | #DATA_ATTR_COMMFAIL | The driver experienced a comm failure
7 | #DATA_ATTR_QUALITY | The tag has marked the value as unreliable
8 | #DATA_ATTR_DRIVER_COMMFAIL | The PLC reported a downstream comm failure
9 | #DATA_ATTR_DRIVER_QUALITY | The PLC reported the value may be unreliable
10 | #DATA_ATTR_DRIVER_OVERRIDDEN | (*) The PLC reported the value was overridden
11 | #DATA_ATTR_DRIVER_NODATA | (*) The PLC reported there is no data available

Example:

No example provided. This function is not recommended for most use.


HistorianGetInfo

(Engine-Level Function)

Description: | Retrieves information about a specified Historian or all Historians.
Returns: | Varies depending on the request.
Usage: | Script Only.
Threaded: | No.
Related to: | HistorianConnect | HistorianDeleteRecords | HistorianGetData | HistorianReadRecords | HistorianWriteRecords
Format: | HistorianGetInfo(ConnectionHandle, InfoType)
Parameters: |
ConnectionHandle
As returned by an HistorianConnect call.
InfoType
A numeric expression specifying the type of information to be returned, as follows:
InfoType | Information requested
0 | Counters. A dictionary of dictionaries of dictionaries containing full counter information for all sequences stored by this Historian.
1 | Errors. A dictionary of write or deletion errors that occurred in this Historian since the last time GetInfo(Historian, 1) was called.
2 | Overall write queue count. The number of records in the write queue for all Historians (ConnectionHandle parameter is ignored).
3 | Overall records stored. A rollover count of the records stored by all Historians (ConnectionHandle parameter is ignored). This counter rolls over (2^32) and therefore is only useful for performance diagnostics. It is not a count of all records in storage.
4 | Write queue count. The number of records in the write queue for this Historian.
5 | Records stored. A rollover count of the records stored by this Historian. This counter rolls over and therefore is only useful for performance diagnostics. It is not a count of all records in storage.
6 | Overall write queue size. The approximate memory size of the write queue for all Historians (ConnectionHandle parameter is ignored).

Example:

No example provided. This function is not recommended for most use.


HistorianReadRecords

(Engine-Level Function)

Description: | Reads a range of records from the data store. The range is specified by the Start and End counter values supplied.
Warning: | This function should be used only by advanced programmers. The function GetTagHistory is recommended for most uses.
Returns: | Invalid if parameters are invalid, 0 otherwise.
Usage: | Script Only.
Threaded: | Yes
Related to: | HistorianConnect | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianWriteRecords
Format: | HistorianReadRecords (ConnectionHandle, TagName, Schema, Data, MID-S, StartCounter, EndCount, ErrorCode)
Parameters: |
ConnectionHandle
As returned by an HistorianConnect call.
TagName
A text string representing the desired table name. Engine code may modify this to conform with storage limitations.
Schema
This is a textual representation of a schema structure.
Data
A variable in which the values will be returned.

This will be a single dimension array representing the Fields (columns). The entries in the array will be an array of values (all fields will be the same) and the size of one of these arrays gives the number of records (rows) in the result set.
Mid-S
A 64 bit binary token.
StartCounter
Starting counter number. Starts counting at 1 rather than zero.
EndCounter
Ending counter number. Starts counting at 1 rather than zero.
ErrorCode

FileDB or SQL DB error code returned.

Defined error codes are provided in the reference chapter. See: Historian Error Codes

Comments: Data will be set on completion of the operation.
ErrorCode will be set on completion of the operation. This will be set to zero if the operation was successful

Together, the Schema and the MID-S parameters define the subset of records in the Index file from which the data in the required Counter range will be retrieved. If this filtered subset has no data, then none will be returned.

Example:

No example provided. This function is not recommended for most use.


HistorianWriteRecords

(Engine-Level Function)

Description | Writes records to the data store identified by the ConnectionHandle
Warning | This function should be used only by advanced programmers. The function WriteHistory is recommended for most uses.
Returns | A counter value, or Invalid if parameters are invalid
Usage | Script Only.
Threaded | Yes
Related to: | HistorianConnect | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords
Format | HistorianWriteRecords (ConnectionHandle, TagName, Schema, Records, SequenceID)
Parameters |
ConnectionHandle
As returned by an HistorianConnect call.
TagName
A text string representing the desired table name. Engine code may modify this to conform with storage limitations.
Schema
This is a textual representation of a schema structure.
Records
Array of data. This is a single dimension array representing the Fields (columns) to be written. Each entry in this array may be either a single data value or an array of values. If any entry is an array, then the size of the largest array gives the number of records (rows) to be written. If any individual field is underspecified, then a representation of INVALID is written for the missing values.
SequenceID
A 12-byte, binary token.
Comments Data is always appended to the data store, and records are not deleted or replaced unless HistorianDeleteRecords is called explicitly.
The function returns the counter value for the last record being written.

Note: At the point that the function returns, the data has not yet been written. Because the Counter is the actual record number (FileDB) or an index (SQL) the counter value returned here will be a calculated value, based on the number of records that are pending.

As well as defining the column format, the Schema defines the subset of tables to which the supplied data will be written.

While considered to be threaded, this function has no lifetime after it passes the records to another thread for writing.

Each record will be represented by a Counter value which is one greater than the previous Counter value, unless either Schema or MID-S have changed from the previous write. In this case, a new table/file set is started. The counter value for a new table always starts from 1.

Example:

No example provided. This function is not recommended for most use.


HoursEntry

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Displays a time editing field.
Returns: | Nothing (see parameter descriptions)
Usage: | Steady State only.
Function Groups: | Graphics, Time and Date
Format: | \HoursEntry(Left, Top, Hours, Minutes, Enable, TimeChange[, Trigger, FocusID, Force24HourEditing])
Related to: |
Parameters: |
Left
Required. Left reference
Top
Required. Right reference
Hours

Required integer. Displays and returns the hour portion of the time from 0 to 23. "0" will be shown only for a 24-hour clock. In a 12-hour clock, midnight is shown as 12:00 AM

See comments.

If the initial value is not an integer, the return value must be cast to an integer.

Minutes

Required integer. Displays and returns the minute portion of time from 0 to 59. See comments.

If the initial value is not an integer, the return value must be cast to an integer.

Enable
Required Boolean. Set TRUE to enable, or FALSE to display the selector as a grayed-out control.
TimeChanged

Optional Boolean. Will be set TRUE when the operator changes the hour or minute value. If provided, this parameter should be initialized to FALSE.

Does not reset automatically.

Trigger
An optional numeric value. Will be set to the status of the underlying edit field.
FocusID

Optional. Any numeric expression from 0 to 32767. Defaults to 1 if not set.

Force24HourEditing

Optional Boolean. Set TRUE for a 24-hour clock. AM and PM will not be displayed.

Set FALSE for a 12-hour display with AM or PM shown. Defaults to FALSE if missing or Invalid.

Comments:

This module displays a time selector at the given top, left coordinates. Values are returned in the 3rd and 4th parameters, which update when the user selects a value.

Example:

...
  Hours;
  Minutes;
  TimeChanged = FALSE;
  StartTime;
]
Init [
  If 1 Main;
  [
    StartTime = Int(Seconds());
    Hours = Int(StartTime / 3600);
    Minutes = Int((StartTime % 3600)/ 60);
  ]
]
Main [
  Return(Self);
  \HoursEntry(100, 200, Hours, Minutes, TRUE, TimeChanged, Invalid, 1, Invalid );
  If Edge(TimeChanged, 1);
  [
     TimeChanged = FALSE   { Reset the trigger    };
     {... Process the new time }


HScrollbar

(System Library)

Description | Draws a horizontal scrollbar and returns its position.
Returns | Boolean
Usage | Steady State only.
Function Groups | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | Listbox | RadioButtons | SpinBox | SplitList | TextBox | ToolBar | VScrollbar
Format | System.HScrollBar(Left, Top, Width, Steps, PageLen[, Position, StepSize, WindowObj])
Parameters |
Left
Required. Any numeric expression for the left side coordinate of the scrollbar.
Top
Required. Any numeric expression for the top coordinate of the scrollbar.
Width
Required. Any numeric expression for the width of the scrollbar in pixels.
Steps
Any numeric expression giving the number of steps in the scrollbar.
PageLen
Required. Any numeric expression giving the number of steps to jump per page.
Position
Optional numeric. This variable may be used to monitor or set the current scroll position.
StepSize
Optional. Any numeric expression giving the number of lines to scroll through when the user clicks on an arrow. Defaults to 1 if not specified.
WindowObj
Used by the Anywhere client. Enables redirection to the HScrollbar of horizontal panning over a given region. Required because on many touchscreens you cannot interact directly with the scrollbar therefore this object is needed to make it possible to scroll HScrollbar on those platforms.
Comments

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Steps and Pages: Refer to the explanation inVScrollbar, substituting columns for rows.

Custom script graphics using the HScrollbar module directly must pass in a window object to serve as source for the mouse wheel messages. Typically this would be the window that the VScrollbar module is controlling. Note that the HScrollbar module itself uses a native windows scrollbar, which will therefore work automatically without any script changes, so long as the mouse pointer is over the actual scrollbar.

Example:

  System.HScrollBar(VStatus(Self, 11) - VStatus(Self, 21) { Left },
                     VStatus(Self, 12) - 1 { Top },
                     VStatus(Self, 12) { Width },
                     Length - LinesVisible { Total steps },
                     LinesVisible { Steps in page },
                     Offset { Thumb tab pos },
                     StepSize { Number of lines per arrow click. });


HTTPSend

Description: | Sends HTTP requests to an HTTP server
Returns: | A reference to itself so that you can monitor for completion. See also pResponse in the comments.
Usage: | Script Only.
Function Groups: | Stream and Buffer
Related to: |
Format: | System.HTTPClient.HTTPSend(URL, pResponse[, Username, Password, ExtraHeaders, Action, MessageBody, ContentType, TimeLimit, NConcurrent, KeepAlive, MessageOnly, MaxSendRate ])
Parameters: |
URL
Full URL
pResponse
[OUT] Pointer set to a response structure when request completes
Username
Optional text. Self explanatory.
Password

Optional text. Self explanatory.

The HTTP client supports both HTTP basic and digest authentication schemes

ExtraHeaders
Dictionary of extra HTTP headers where the dictionary key is used as the header name and its value as the header value
Method
Typically "POST" or "GET"; default GET
MessageBody
The "payload" of the HTTP message
ContentType
Meaningful only if MessageBody is valid; default "text/xml; charset="UTF-8""
TimeLimit
Time in seconds to wait for response; default 60
NConcurrent
Number of concurrent keep-alive connections to maintain per server-port; default 1
KeepAlive
TRUE to keep the connection alive; default TRUE
MessageOnly
TRUE to just send the message body; default FALSE
MaxSendRate
Optional numeric. the maximum number of requests to send per second to the host. Defaults to an unlimited rate if not specified. (See comments)
Reserved
Reserved. Set to 'Invalid'.
Reserved
Reserved. Set to 'Invalid'.
CertificateName
Optional string. Friendly name of a TLS Client Certificate used to validate the request.
Comments:

Note that HTTPSend is part of the HTTPClient library, which is part of the System library, and therefore must be used in the form, System.HTTPClient.HTTPSend(...

The port number that will be used depends on the protocol that is used in the URL parameter.
For HTTP the default port is 80.
For HTTPS the default port is 443.
For FTP the default port is 21.
A custom port number can be specified in the URL. The protocol defaults to HTTP.

The response structure contains the following fields:

ReturnCode

The response code. See following notes.

Body

The response body

Headers

A dictionary of response headers

ErrorText

Supplementary error text beyond ReturnCode

The ReturnCode will either be a standard HTTP status code, such as 200 for success, or one of the following:

  • -1: Connection timed out
  • -2: Response timed out
  • -3: Invalid (non-HTTP) response
  • -4: Incomplete response
  • -5: Unsupported transfer-encoding
  • -6: Missing parameters

Related properties in Setup.INI:

HTTPClientKeepAliveTime

The length of time to maintain an inactive HTTP connection marked as "keepalive". Default is 15 seconds.

HTTPMaxDeflatedDataSize

An integer that specifies the max size of a payload to decompress. If the payload is bigger than this size it will be truncated. Defaults to 65536 bytes.

There is risk when changing this setting: If it is too large, and a bad payload is received, it could cause VTScada to allocate a buffer of the max size. Most users should not need to change this property.

MaxSendRate

The maximum number of requests to send per second to the host. It defaults to an unlimited rate. This is necessary for situations where a host may reject a client if it has received more than X requests per second from that client. By setting MaxSendRate, HTTPClient throttles the rate at which it sends messages.


I Functions

The sections that follow identify all VTScada functions beginning with "I".


IconMarker

Deprecated. Do not use in new code.

(System Library)

Description: | Creates the question mark and exclamation mark graphics, used to indicate questionable and manual data in a widget. This module places a set of icons on the screen centered over a given rectangular region. The icon displayed is cycled with each passage of the period, measured in seconds
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GetXformRefBox | Scale | TagIconMarker
Format: | \IconMarker(Left, Bottom, Right, Top, Period, Mode, SizeX, SizeY, IconArray)
Parameters: |
Left, Bottom, Right and Top
Are numeric expressions providing the bounds of the graphic to mark. The symbol will appear in the center of this area.
Period
A numeric expression setting the period (in seconds) at which the symbol is changed
Mode
A numeric expression indicating the symbol to display according to the following table
Mode | Symbol
0 | Inhibit symbol display
1 | Questionable Data symbol
2 | Manual Data symbol
3 | Questionable and Manual symbols
4 | Error symbol
5+ | User supplied symbols
SizeX
A numeric expression providing the horizontal extent of the symbols to display
SizeY
A numeric expression providing the vertical extent of the symbols to display.
IconArray
The array of images to display. This must be a variable - use of the "Invalid" keyword or a constant here will cause the module to fail. The value of this variable is discarded for mode values less than 5.

Comments:

This is an older function. TagIconMarker should be used for all new code.


If

(Engine-Level Function)

Description: Trigger to perform an action. It changes the active state in a module instance or executes a script or both.
Returns: Nothing
Usage: Steady State only.
Function Groups: Logic Control
Related to: IfElse | IfOne | IfThen | Cond
Format:
If Trigger Destination; { Optional change to state, Destination }
[
  { Optional script  code }
]
Parameters:
Trigger
Required. Any logical expression. If false, nothing happens. If true, the action is performed, and any functions in the Trigger expression that may be reset are automatically reset.
Destination
Optional. Destination is not an expression, it is the text name of a state. If provided, it must be a legal name of a state in the module where this action is defined.
It is not possible to change to a state in another module. Each object must have one (and only one) active state, unless the module has no states defined.
Comments:

Do not use this function in expressions that you write in tags or Idea Studio objects. The If statement is for use only in full VTScada scripting modules.

An action may have a Destination, a Script, or both. (Or neither, although it does not make sense to have neither.)

Note that an object is not in any active state while it is executing a script that is changing states. The object leaves the old state when the script starts, and the object enters the new state when the script ends.

Script is a list of functions and statements, ending in semicolons, contained by square brackets. The Script is optional and may be omitted. There is no limit to the number of statements in Script (other than RAM). If the script is omitted, the square brackets should also be omitted. A script's statements are executed in order, from top to bottom. While a script is executing, no other statements in the current script thread can execute until this script is complete. (Script running in another bubble can run fully in parallel across multiple processor cores.)

Any function used within a script block must be one that can run in a script. (Refer to the Usage description of the function.) The IF statement itself and the expression used for the trigger run in steady state, therefore any function used in the trigger must be legal in steady state.

Examples:

When the current local time is after 12 PM, the state MorningState is stopped and the state AfternoonState is started.

{ Use an If to switch states }

MorningState [
  If Now(3600)/3600 >= 12 AfternoonState;
    { ... code to run or display during the morning ... }
  ] { End state MorningState }

AfternoonState [
...

The next example counts five-second intervals. This illustrates a use for AbsTime() , which is a member of the group of the Latching and Resetting Functions. These are well-suited to be conditionals for If statements because they automatically reset themselves to FALSE immediately after triggering the If.

{ Use an If to control when a set of statements execute }
TakeFive [
  If AbsTime(1, 5, 0);
  [
    FiveCounter++;
    { ... other code to run every 5 seconds ... }
  ]
]

The next example is of an extremely common construct in VTScada modules. An initialization state assigns values to variables, then control is passed to the main state. The script in the initialization state runs exactly once before the state transfer, even though the conditional test is "If TRUE...".

[ { Declare variables... }
  StartTime        { Will hold a timestamp for when the module begins }
  { ... Other variables as needed }
]
Init [
  If 1 Main;
  [
    StartTime = CurrentTime(1);    { Set StartTime to the current UTC time }
  ]
]
Main {
{ ... Code that requires a start time ... }

When using an IF to run a script block that does not then proceed to another state, use care to avoid If 1 conditions. Consider the following variation on an earlier example:

{ An example of poorly written code }
[ { Declare and initialize the variable... }
  AfternoonCount = 0      { Count of morning to noon transitions };
  AnotherNoon    = FALSE  { Boolean to indicate whether it is afternoon };
]
Main [
  AnotherNoon = Now(3600)/3600 >= 12 { Check every hour whether it's after 12 };
  If AnotherNoon;
  [
    AfternoonCount++    { Increment the afternoon count };
  ]
]

This is an example of what to AVOID!

This action will trigger over and over again until midnight. This is called an "If 1" condition and will degrade system performance to a small percentage of its normal potential. All the time AnotherNoon is true (1), AfternoonCount will increase by one at a very rapid rate. This is because there is no destination state and the action remains active for 12 hours. The trigger is checked again and again.

To avoid this, use the following:

   { Only run script when value changes }
  If Watch(1, AnotherNoon);
  [
    { Is this the first or a following AfterNoon? }
    IfThen(AnotherNoon,
      AfternoonCount += 1;
    );
  ]

Refer to "Latching and Resetting Functions" for further information.


IfElse

(Engine-Level Function)

Description: | Executes one of two expressions depending upon the result of a conditional expression.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | Logic Control
Related to: | Ternary Operator (IfElse) | Cond | Execute | IfThen | True | False
Format: | IfElse(Condition, TrueCase, FalseCase) or Condition ? TrueCase : FalseCase
Parameters: |
Condition

Required. An expression that returns TRUE or FALSE. If TRUE, the TRUECase is executed. If FALSE, the FALSECase is executed.

If Invalid, neither case is executed.

TRUECase
Required. The expression (sometimes an Execute statement) that is executed when Condition is TRUE.
FALSECase
Required. The expression (sometimes an Execute statement) that is executed when the Condition is FALSE.
Comments:

Refer to the Style Guide for VTScada Code for guidance on when to use IfElse versus the in-line Ternary Operator (IfElse), versus Cond.

Scripting example:

  If Watch(1, Value);
  [
    IfElse(Value > 50, Execute(
      ValueIsHigh = TRUE;
      HighValueCount++;
    );
    { Else }
      ValueIsHigh = FALSE;
    );
  ]

Writing long "If Else - Else - Else ... " expressions is not efficient and can be avoided. To prevent excessively nested expressions, the property MaxNestedExpressionDepth limits you to 200 function calls (including IfElse) within a single expression. There is no need to test this limit, regardless of the complexity of your application.

Alternatives to nested IfElse structures:

A common task is to build a string based on the current value of a tag (or several tags). For this example, suppose that you need to build a message or address that varies with a tag's current state. A long and inefficient method might be to write:

[SomeTagName] == 0 ? "Message (or) Address 0"
                   :
[SomeTagName] == 1 ? "Message (or) Address 1"
                   :
[SomeTagName] == 2 ? "Message (or) Address 2"
                   :
 etc. for 100 or more messages...

There are alternatives:

Option 1

A much easier method is to use a CASE statement in steady state. All statements will execute, but only the result of the statement matching the requested index will be returned.

X = Case([SomeTagName],
     { 0 } "Message (or) Address 0",
     { 1 } "Message (or) Address 1",
     { 2 } "Message (or) Address 2",
     { etc });

Option 2

Another option is somewhat more complicated to create, but has the benefit that the messages are stored in application properties instead of code and therefore can be added to or edited by anyone with the Configuration privilege. It is not necessary to write more code when messages change or new messages are created.

1. Create a set of application properties for each situation:

 Situation0         = Message or Address 0
 Situation1         = Message or Address 1
 Situation2         = Message or Address 2
   (etc.)

2. Write an expression that uses the Variable function to concatenate the tag value onto the prefix "Situation" to return the appropriate property value.

 Variable(Concat("Situation",[<SomeTagName1>]))

No comparisons or If-Else statements are required. This single line of code can return any message that you have created. For more complicated situations, use Concat to build the appropriate property name or combine several values into one message or address.


IfOne

(Engine-Level Function)

Description: | Check for an If One Condition. This function checks for an infinite loop in an action script and returns the value of the location.
Warning | This statement should be used by advanced users only. In nearly every instance, it is faster and easier to identify an If One condition using the Source Debugger.
Returns: | Module
Usage: | Script only.
Function Groups: | Logic Control
Related to: | Ternary Operator (IfElse) | Cond | Execute | IfElse
Format: | IfOne()
Parameters: | None
Comments: Check for an If 1 (If TRUE) Condition. This function is used for debugging VTScada applications and returns the module, state and statement value of the If statement that did not switch states, and the predicate condition remain TRUE after the associated script block executed, resulting in the script block executing again repeatedly. Symptoms of an If 1 condition are high CPU and slow responsiveness.

Example of an If-one:

  If X;
  [
    Y = X;
  ]

where X and Y are defined and X is set to TRUE.


IfThen

(Engine-Level Function)

Description: | Conditionally execute statements. This statement executes all provided statements or expressions if the condition parameter is true.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Logic Control
Related to: | Cond | Execute | IfElse
Format: | IfThen(Condition, Expression1, Expression2, ...)
Parameters: |
Condition
Required. An expression that will indicate whether the Expression parameters are executed. If this is true, the Expression parameters will be executed.
Expression1, Expression2, ...
Required. Any statements to be executed when Condition is true. Any number of Expression parameters may be listed. They are executed once in the order that they are listed.
Comments: This statement may only appear in a script.

Example:

  If 1 Main;
  [
    IfThen(Valid(TankPtr) && FluidLevel > 1000,
      StartPump = 1;
      ActiveTankNum++;
      Msg = "Changing tanks..."
    );
  ]

The statement in the script will test to see if TankPtr exists (is valid) and if FluidLevel > 1000. If these conditions are both true, the series of actions will be taken.

Note that VTScada does not use short-circuit evaluation. Both parts of the condition will always be checked even if TankPtr is Invalid. Do not write code similar to the following:

    IfThen(Valid(Tank) && (Level = Tank.FluidLevel) > 1000,
     ...
    );

Since we do not do short-circuit evaluation of Boolean expressions, Level always gets set, even when Tank is Invalid. In that case, Level will be set to Invalid, which may not be appropriate. Solve this by nesting the code:

    IfThen(Valid(Tank),
      IfThen(Level = Tank.FluidLevel) > 1000,
       ...
      );
    );

Note that the Trihedral code style recommends doing the Level assignment before the nested IfThen, and then simply checking Level in the nested IfThen's condition.


ImageArray

(Engine-Level Function)

Description: | Reads an existing image handle and returns another one containing an image created from that handle by tiling the image a given number of times.
Returns: | Image handle
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | Crop | GUIBitmap | GUIButton | ImageSweep | MakeBitmap | ModifyBitmap
Format: | ImageArray(Handle, HorizontalSpacing, VerticalSpacing, RowCount, ColCount[, Orientation, CropLeft, CropTop, CropWidth, CropHeight, Tessellate])
Parameters: |
Handle
Required. The image handle to copy and modify.
HorizontalSpacing
Required. Any numeric expression for the horizontal space between each tile.
VerticalSpacing
Required. Any numeric expression for the vertical space between each tile.
RowCount
Required. Any numeric expression for the number of tiles running vertically.
ColCount
Required. Any numeric expression for the number of tiles running horizontally.
Orientation

Optional numeric value between 0 and 15, specifying the orientation of the tiles. Defaults to zero.

Orientation Value | Meaning | Orientation Value | Meaning
0 | No rotation, no flipping | 8 | No rotation, flip vertically
1 | 90-degree CW rotation without flipping | 9 | 90-degree CW rotation and flip vertically
2 | 180-degree CW rotation without flipping | 10 | 180-degree CW rotation and flip vertically
3 | 270-degree CW rotation without flipping | 11 | 270-degree CW rotation and flip vertically
4 | No rotation, flip horizontally. | 12 | No rotation, flip horizontally, then vertically
5 | 90-degree CW rotation and flip horizontally | 13 | 90-degree CW rotation, flip horizontally, then vertically
6 | 180-degree CW rotation and flip horizontally | 14 | 180-degree CW rotation, flip horizontally, then vertically
7 | 270-degree CW rotation and flip horizontally | 15 | 270-degree CW rotation, flip horizontally, then vertically
CropLeft
Optional. Left coordinate of the cropping region.
This and the following three parameters must all be specified if any are specified. Together, they apply a clipping rectangle that will be applied to the tiled image after tiling occurs.
CropTop
Optional. Top coordinate of the cropping region.
CropWidth
Optional. Width of the cropping region.
CropHeight
Optional. Height of the cropping region.
Tessellate

Optional Boolean. Defaults to FALSE (0). Optimizes drawing for a simple grid of images, but causes ImageArray to ignore spacing and transformation of the images. Does not improve the appearance of the result, but uses significantly less memory and may be marginally faster.

The result may be clipped and stretched.

Comments:

More commonly used in script than in steady-state.

The cropping parameters work in contrast to the Clip function, which applies a clipping region to the image before tiling occurs.

A regular image array will allow for gaps between the tiles and some transformations of the original image. The algorithm for this is less than optimal if one wants an unspaced grid of images, such as in a wallpaper bitmap. For the latter case, set the Tessellate parameter to true.


ImageParmSet

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns a structure of image attributes that can be passed to an image-based widget.
Returns: | A structure of image parameters suitable for use by a GUITransform
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | | | | | | | | GUITransform
Format: | \ImageParmSet(Filename[, ColorMultiplier, Mirror, AntiAlias, RotateAngle, Opacity, Lightness, Contrast, Hue, Saturation, ColorizeIntensity, ColorizeHue])
Parameters: |
Filename
Required. The relative path and file name of the image
ColorMultiplier
Optional color value in the form aRGB Closed A colour value, defined as four, two-digit hexadecimal values. Alpha - Red - Green - Blue. An Alpha value of FF is assumed if only the RGB values are provided., used to apply a specific color to a gray-scale image.
Mirror
Optional Boolean. A logical value that can be set to 1 to reflect the image about the vertical axis. The default is no reflection (0).
AntiAlias

Optional numeric. This is a bit-wise parameter where Bit 0 controls whether anti-aliasing will be done when the image is stretched. Defaults to 1 (TRUE) if missing or invalid.

By default, feathering will be applied to an anti-aliased image when it is stretched. Set bit 1 to 1 (TRUE) to suppress feathering.

RotateAngle
Optional floating point value, specifying the clockwise rotation in degrees to be applied when the image is drawn.
Opacity
Optional numeric expression for a multiplier to the transparency (alpha value) of every color in the image. Range 0 (transparent) to 1 (opaque). Defaults to 1 if missing or invalid.
Lightness
Optional numeric expression that is a multiplier to the brightness of the image. Range 0+. Defaults to 1 if missing or invalid.
Contrast
Optional numeric expression to enhance the differences between the colors in the image. Range 0+. Defaults to 1 if missing or invalid.
Hue
Optional numeric expression for the hue rotation to apply to all of the colors in the image. Range -180 to 180. The default is no hue rotation, (0).
Saturation
Optional numeric expression that is a multiplier to the intensity of each primary color component of every color in the image. Range: 0+. Defaults to 1 if missing or invalid.
ColorizeIntensity
Optional numeric expression for the intensity of the added color. Zero means that no color is added. Range 0-255. Defaults to 0 if missing or invalid.
ColorizeHue
Optional numeric expression for the hue value of a color to be mixed with every color in the image. Range -180 to 180. Defaults to 0 if missing or invalid.
Comments:

...

Example:

GUITransform(207, 195, 307, 95,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "MeterParts", TRUE)\DrawScale(
                                      \ImageParmSet("Bitmaps\Meter Parts\Tick Marks\Large_Thin.png" { Filename },
                                                    "<FFFFFFFF>" { ColorMultiplier   },
                                                    1            { ColorMultiplier   },
                             Invalid      { Mirror            },
                                                    0            { AntiAlias         },
                                                    1            { RotateAngle       },
                                                    1            { Opacity           },
                                                    1            { Lightness         },
                                                    0            { Contrast          },
                                                    1            { Hue               },
                                                    0            { ColorizeIntensity },
                                                    0            { ColorizeHue       }),
                                      \ImageParmSet("Bitmaps\Meter Parts\Tick Marks\Small_Thin.png",
                                                    "<FFFFFFFF>", 0, Invalid, 0,
                                                    1, 1, 1, 0, 1, 0, 0), 7, 5, 1,
                                                    0, 0, 0, 225, 135, 0, 1, 1, 1,
                                                    1, 0, 0, "<FFFFFFFF>", 0));


ImageSweep

(Engine-Level Function)

Description: | Reads an existing image handle and returns another one containing an image created from that handle by tiling the image a given number of times along an arc-shaped path.
Returns: | Image handle or Invalid on failure
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | Crop | GUIBitmap | GUIButton | ImageArray | MakeBitmap | ModifyBitmap
Format: | ImageSweep(Handle, Count, Radius, StartAngle, EndAngle[, CropLeft, CropTop, CropWidth, CropHeight])
Parameters: |
Handle
Required. The image handle to copy and modify.
Count
Required. Any numeric expression for the number of tiles to draw.
Radius
Required. Any numeric expression for the natural radius of the short axis of the ellipse, used to determine scaling.
StartAngle
Required. Any numeric expression for the angle at which the first tile is to be drawn. The range -180 to 180. The start point is the vertical axis. Angles are positive, counter-clockwise..
EndAngle
Required. Any numeric expression for the angle at which the last tile is to be drawn. Range -180 to 180, start point is the vertical axis, angles are positive counter-clockwise..
CropLeft
Optional. Left coordinate of the cropping region.
This and the following three parameters must all be specified if any are specified. Together, they apply a clipping rectangle that will be applied to the tiled image after tiling occurs.
CropTop
Optional. Top coordinate of the cropping region.
CropWidth
Optional. Width of the cropping region.
CropHeight
Optional. Height of the cropping region.
Comments:

The result is a radial array of tiles. Drawing angles intersect the center of the tiles. The path is based upon the size and shape of an ellipse traced out using the bounding box of the drawing transform. Scaling is based upon a comparison of the described radius and the final size of the transform on the screen. In the case of an ellipse the radius is assumed to be the smallest elliptical radius. Returns Invalid upon failure

The cropping parameters work in contrast to the Clip function, which applies a clipping region to the image before tiling occurs.

Example:

[ { Variable declarations ...}
  Image;
  Swept;
  MidX = 200;
  MidY = 200;
  Radius = 20;
]
Init [
  If 1 Main;
  [
    Image = MakeBitmap("C:\VTScada\VTS\Bitmaps\Arrows\Half rounded.wmf.png");
  ]
]
Main [
  Swept = ImageSweep(Image,3,100, 0, 120);
    GUIBitmap(0, 1, 1, 0,
            1 - (MidX - Radius),
            MidY + Radius,
            MidX + Radius,
            1 - (MidY - Radius), 1,
            0, 0, 0, 0,
            0, 0, 0,
            Swept);
  Return(Self);
]


ImportAPI

(System Library)

Description: | Imports objects of class API from a given module, for use in the calling module.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Advanced Module
Related to: | TreeControl
Format: | System.ImportAPI(SourceModule[, DestinationModule])
Parameters: |
SourceModule
Required. Any expression for the module from which the API-class constants should be imported.
DestinationModule
An optional expression, giving the module that the API-class constants should be imported into. Used only if the constants are not being imported into the current module.
Comments: When using modules such as TreeControl, the ImportAPI function can reduce the programming workload by importing all the required constants with one command. Only those constants that have been declared as class API in the source module will be imported.

ImportAPI "imports" the source objects by creating variables with the same name in the destination module and assigning to these the default values from the source module. Results may be unpredictable if more than one instance of the source module is found.

Returns the number of variables that were found to have the same name in the calling module and that therefore were not imported from the source module.

Example:

A selection of constants declared in TreeControl.SRC:

  {***** Indices into the Tree array nodes *****}
[ (API)
  Constant #TI_KEY      = 0  { "Key" value...see heading comment };
  Constant #TI_TEXT     = 1  { Text value to display        };
  Constant #TI_SUBTREE  = 2  { Subordinate tree below this node  };
… etc …

Importing the TreeControl constants in DropTree.SRC:

Init [
  If 1 DropTree;
  [
     { Import the Tree Control API }
    System.ImportAPI(\TreeControl);
… etc …


ImportKey

(Engine-Level Function)

Description: | The ImportKey function transfers a cryptographic key from a key BLOB into a CSP (cryptography service provider). It is the VTScada analog of the CryptoAPI’s ImportKey call.
Returns: | Key
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | DeriveKey | Decrypt | Encrypt | ExportKey | GenerateKey | GetCryptoProvider | GetKeyParam | SetKeyParam
Format: | ImportKey(CSP, BlobType, KeyBLOB [, DecryptKey, Flags, Error])
Parameters: |
CSP
Required. The handle to the CSP which is receive the imported key.
BlobType
Required. A parameter specifying the type of key BLOB to be imported. Values are defined in WinCrypt.h
KeyBLOB
Required. Text string containing the KeyBLOB to be imported.
EncryptKey
An optional parameter containing a Key handle for a key to be used to encrypt the exported key so that it may only be encrypted by the destination user. If omitted or invalid, then the value NULL is used.
Flags
An optional parameter specifying the flags to be passed to CryptExportKey. If omitted or invalid then the value 0 is used.
Error
An optional variable in which the error code for the function is returned. It may have the following values:
Error | Meaning
0 | Key successfully imported.
1 | CSP, BlobType or KeyBLOB parameters invalid.
X | Any other value is an error from CryptImportKey.
Comments: The new key is returned as a Key handle. If an error occurs, the return value is invalid.

Example:

[
  Constant PUBLICKEYBLOB = 0x6;
  Key3;
]
Init [
  If 1 Main;
  [
    { Import the public key }
    Key3 = ImportKey(CSP, PUBLICKEYBLOB, PubKey1, Key2);
  ]
]


In

(Engine-Level Function)

Deprecated. This function relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.

Description: | Read I/O Byte. This function returns the byte read from an I/O port.
Returns: | Byte
Usage: | Script or steady state.
Function Groups: | Memory I/O, Stream and Socket
Related to: | InWord | Out | OutWord
Format: | In(Port)
Parameters: |
Port
Required. Any numeric expression, which specifies which I/O port to read. Port must be in the range 0 to 65535
Comments: This function requires that the VTSIO driver be installed.
If In is used in a statement or an action trigger, it will be evaluated at a very fast rate. In is a high priority function, and should be used sparingly to avoid reducing overall system performance.

Example:

reg = In(0x300);

This reads a byte from CPU input port 300 hex. If this statement appears in a script the read takes place when the script is executed. If this statement appears in steady state, it is updated very rapidly as a high-priority function.


InsertArrayItem

(Engine-Level Function)

Description: | Insert Array Item. This function inserts an element into a dynamically allocated array and returns the modified array.
Returns: | Array
Usage: | Script Only.
Function Groups: | Array
Related to: | DeleteArrayItem | New
Format: | InsertArrayItem(Array [, Index, Value])
Parameters: |
Array
Required. Any variable whose value is invalid or contains a dynamically allocated array (one created via a New function call). This should be a single dimension array or unexpected results may occur.
Index
An optional parameter that is any numeric expression for the index at which to insert a new element. If this value is invalid, the new element will be inserted at the end of the array.
Value
An optional parameter that is any expression for the value to assign to the new array element.
Comments:

Building an array in this fashion has O(n^2) complexity, meaning it is an extremely slow way to build an array of any size.
It is far more efficient to add elements to a Dictionary and use ListKeys to make an array

This function is intended for use on dynamically allocated arrays, created via the New function. If used with an array that has been statically declared, then unless otherwise specified in the Array parameter, the first element of the array will be used, and a dynamically allocated array will be created/added-to in this element.

Examples:

  If 1 Next;
  [
    Data = InsertArrayItem(Data { Array to use },
                           Invalid { Insert at end },
                           32 { Value of element });
    Names = InsertArrayItem(Names { Array to use  });
  ]

The first statement inserts an element with a value of 32 at the end of array Data, while the second statement inserts an invalid element at the end of array Names.


Instance

(Engine-Level Function)

Description: | Limit module instances. This function limits the number of fixed module instances allowed to run simultaneously and returns the old limit
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | NumInstances | CalledInstances | GetInstance
Format: | Instance(Module, Count)
Parameters: |
Module
Required. Any text expression that specifies the fixed module to limit. It must be in the current scope. Scope resolution operators ( \ ) are not permitted.
If the module does not exist, nothing is done. If the module is not a fixed module, the return value is -1.
Count
Required. Any numeric expression that specifies the number of fixed module instances allowed to run simultaneously.
If Count is in the range 1 to 2, 147,483,647, the new limit is set and the old limit is returned.
If Count is 0, the limit is not changed, but the current limit is returned.
Count is ignored if the module is not a queued module.
Comments: This function is recommended for experienced users only and is not needed for most applications. If this function is not used, the number of concurrent instances for a given fixed module defaults to 1.

This limit is the number of concurrent instances allowed for each parent instance. Each parent module instance has a separate Count for each of its fixed modules, which is separate from other instances of itself.

Example:

  If 1 Main;
  [
    Motors = Instance("Motor", 5);
  ]

Assume that this statement is found in a module that has a child module called Motor. Execution of the script will cause Motors to be assigned a value of 1, and to limit the number of instances of Motors to 5 (note that it is necessary for Motor to be a member or an ancestor of Feeder). All instances the parent module will be affected, which is to say that each one will be allowed to have up to 5 running instances of Motor.


Int

(Use for rounding by adding 0.5)

(Engine-Level Function)

Description: | Integer Portion of Number. This function returns the portion of a number before the decimal point. Also used for rounding.
Returns: | Integer
Usage: | Script or steady state.
Function Groups: | Rounding Math
Related to: | Ceil |Step
Format: | Int(X)
Parameters: |
X
Required. Any numeric expression. Normally this is a floating point value.

Comments:

The Int function is sometimes referred to as "floor."

To round a number instead of truncating it, add 0.5 to each value.

Examples:

  a = Int(1.00);
  b = Int(1.12);
  c = Int(1.99);
  d = Int(2.00);
  e = Int(-1.00);
  f = Int(-1.9);

The variables a, b, c, d, e and f will have values of 1, 1, 1, 2, -1 and -2 respectively.

  x1 = 3.4;
  y1 = 4.7;
  x2 = Int(x1 + 0.5);
  y2 = Int(y1 + 0.5);

The value of x2 and y2 in the above example will be 3 and 5 respectively. Notice how adding 0.5 to each value causes the Int function to perform mathematical rounding (of the original value, not the sum) rather than truncation.


Intgr

(Engine-Level Function)

Description: | Time Integral. This function returns the time integral of a value.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Generic Math
Related to: | Deriv | PID
Format: | Intgr(Value, Time)
Parameters: |
Value
Required. Any numeric expression giving the value to integrate with respect to time.
Time
Required. Any numeric expression giving the maximum time in seconds between integral function updates.
Comments:

The integral function takes the Value parameter, multiplies by the elapsed time and adds it to the accumulated value so far. If the Value changes from invalid to valid, the new valid result will start at zero. This function is the inverse of Deriv.
The time parameter is necessary because of VTScada's evaluation method of not doing any calculations unless necessitated by a change in a parameter. This means that if Value remains unchanged, the Intgr function will be re-calculated after the time interval specified by the Time parameter.
This function is often used in control functions such as PID loops where it makes up the "I" in the "PID."
The Intgr function is reset when it appears in a true action trigger, when a state starts, or when it appears in a function which resets its parameters (e.g. Latch, Toggle, and Save). When Intgr is reset, the integral starts from zero again.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Examples:

  Speed = Intgr(Acceleration, 0.1);

This computes speed as the time integral of Acceleration. The integral starts when the state containing this function starts, and stops when the state stops. The integral is updated every 0.1 seconds.

  RunTime = Intgr(MotorOn, 0.25);

This integrates a constant 1 while the motor is running, 0 otherwise. This computes the running time of the motor, accurate to 0.25 seconds.

This example illustrates how the function works. If you found this topic while searching for a way to monitor the run-time of equipment you are advised to use a History Statistics Tag, monitoring the non-zero time rather than building an expression.

Related Functions:

Latching and Resetting Functions


Invalid

(Engine-Level Function)

Description: | Return Invalid Value. This function always returns an invalid value.
Returns: | Invalid
Function Groups: | Logic Control, Variable
Usage: | Script or steady state.
Related to: | Valid
Format: | Invalid()
Parameters: | None
Comments: This function is useful to invalidate data that are found to be incorrect, or to disable statements or functions that will not execute with invalid parameters.

Examples:

  X = Valid(Invalid());

This will set X to 0.

Another example of this function's usefulness follows:

Main [
  If !Valid(aa);
  [
    a = Scale(Rand(), 0, 1, -1000, 1000);
    ...
  ]
  If Valid(a);
  [
    ...
    a = Invalid();
  ]
]

By toggling between a valid and an invalid value, you can ensure that the two scripts in Main will take turns executing. It is not possible for a race condition to occur.


InWord

(Engine-Level Function)

Deprecated. This function relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.

Description: | Read I/O Word. This function reads a 16 bit unsigned word from an I/O port.
Returns: | Word
Usage: | Script or steady state.
Function Groups: | Memory I/O
Related to: | In | Out | OutWord
Format: | InWord(Port)
Parameters: |
Port
Required. Any numeric expression that gives the I/O address. Port must be in the range 0 to 65535.
Comments: This function requires that the VTSIO driver be installed.
This is a high priority function. If InWord is used in a state, it will be evaluated at a very fast rate. InWord should be used sparingly to avoid reducing system performance.

Examples:

reg = InWord(0x300);

This reads reg as a 16 bit unsigned word from input port 300 hex. If this statement appears in a script, it is executed when the script is executed (when the action is triggered). If it appears in a state, it will be updated rapidly as a high priority function.


IPAddressList

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Displays a list of IP address which can be added to or removed from.
Returns: | Text
Usage: | Steady State only.
Function Groups: | Graphics, String and Buffer
Related to: | PIPAddressList
Format: | \IPAddressList(X1, Y1, X2, Y2, AddressList, BaseFocusID[, Title, DrawBevel, AlignTitle, ListBGndColor, OverlayCallback]);
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the object and its label. The smaller of X1 and X2 will always be to the left
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the object. The smaller of Y1 and Y2 will always be the top.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the object and its label opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the object, whichever is the opposite to Y1.
AddressList
Required. The array of IP addresses to display / the array of IP addresses returned.
BaseFocusID
Required. Reserves 10 focus ID values beginning at the value provided. Set to zero to disable user input.
Title
Optional. Any text expression to use as the title for the field. No default value
DrawBevel
Optional. Any logical expression. If TRUE, a bevel is drawn around the graphic. Defaults to FALSE.
AlignTitle
Optional. Any logical value. If TRUE then title affects alignment
ListBGndColor
Optional. Any numeric expression setting a background color for the list. No default value.
OverlayCallback
Optional module value. Called from the listbox. No default value.
Comments: Control is read-only if BaseFID is zero.
Addresses are validated by a utility function in SocketServerManager before being added to the list.
Controls are available for removing items and reordering. A double-click on a list item will copy it into the edit field. The resulting list is stored in the AddressList array, which also serves as the initial display on initialization. Note that addresses are only validated when the add button is pressed.

Example:

The following example is taken from the PIPAddressList code. The overlay callback allows the caller to react to user actions such as right-clicks.

  \IPAddressList(LHS, BTM, RHS, TOP, AddressArray,
                 AllowEdit ? ID : 0,
                 Title, DrawBevel, AlignTitle, HighlightColor,
                 Variable("OverlayCallback") { List overlay graphics callback });


IPMaskToText

(Engine-Level Function)

Description: | Extracts an IP mask from MaskSet and converts it to text, returning the new text value.
Returns: | Text
Usage: | Script Only.
Function Groups: | Network and Workstation
Related to: | CheckIPMask | MakeIPMask
Format: | IPMaskToText(MaskSet [,MaskSetIndex])
Parameters: |

MaskSet

Required. A "maskset", generated by one ore more calls to MakeIPMask

MaskSetIndex

Optional numeric. Specifies the index into MaskSet to use, in the case where MaskSet has more than one mask and you want a mask other than the first one. Often obtained from a call to CheckIPMask. Defaults to zero.
Comments:

For advanced use only.

The returned text value will be the most generalized (canonicalized) representation of the IP address.

If the MaskSet index being converted has a mask other than all 1s, a canonicalized CIDR representation will be returned.

In conjunction with MakeIPMask(), this allows you to validate and convert an arbitrary IP address string to the most canonicalized representation. For example:

Example:

    CanonicalizedIP = IPMaskToText(MakeIPMask(Invalid, InputString))


IsActive

(Alarm Manager module)

Description: | Will indicate if an alarm is active. It can be used either as a subroutine or as a called function.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: | GetAlarmStatus | IsShelved | IsDisabled | IsUnacked
Format: | \AlarmManager.IsActive(AlarmName[, IncShelving]);
Parameters: |
AlarmName
Required.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

InclShelving

Optional Boolean. If TRUE, a shelved alarm will be reported here as inactive, regardless of its status. Defaults to TRUE.

In most cases, shelving an alarm is considered the same as masking the Active status to FALSE. (Makes it look like inactive, regardless of what it actually is.)

For the rare use cases where shelving is to be ignored, the IncludeShelving parameter can be set to FALSE

Comments: The IsActive subroutine returns a 1 if the alarm is active, and returns a 0 otherwise.

Example:

Within a custom tag...

  ActiveStatus = \AlarmManager.IsActive(\GetAlarmName(\Root, "Low"));


IsAppEditable

(VTScada-Layer function. Must be called with a leading backslash.)

Description: Returns TRUE if the application can accept changes without being re-started.
Returns: Boolean
Usage: Script or steady state.
Function Groups: Configuration Management
Related to: HasCompilationErrors | HasUndeployedChanges | AppIsRunning | AcquireLock | GetAppInstance | GetLoadedAppInstance | GetOEMLayer
Format: \AppLayer.IsAppEditable() or \IsAppEditable()
Parameters: none
Comments:

Note that a steady-state call of this function is not automatically updated with a repository change.

This function can evaluate to false if applying an outstanding set of changes would cause an error or if there are outstanding changes that require a restart to be applied. It will also return FALSE if the working copy is not at the repository tip, or if there is a compilation error (generally due to corruption of the working copy files).

  If WorkingCopyLock Commit;
  [
     { Now that we have the WC lock, make sure the Layer still is editable }
     IfElse(\ApLayer.IsAppEditable(),
        WriteINIPropertiesObj = Layer\WriteINIProperties(ConfigData, TRUE);
     { Else }
        ForceState("ReleaseLock"); { Abort if app not editable }
     );
  ]


IsChild

(Engine-Level Function)

Description: | Identify Child Module. This function returns an indication of whether one module is a child module of another.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Basic Module
Related to: |
Format: | IsChild(Child, Parent)
Parameters: |
Child
Required. Any expression that returns an object or module value.
Parent
Required. Any expression that returns an object or module value.
Comments: This function returns true if Child is a descendant module of Parent, false if it isn't, and invalid if either, or both arguments are invalid or not module or object values.

Example:

  If ! Valid(IsMember);
  [
    IsMember = IsChild(ReadModule { Read module object value },
                       Driver { I/O driver module object value });
  ]

The variable isMember will be set to true if the object ReadModule is a child of (defined within) the object driver.


IsClient

(RPC Manager Library)

Description: | Is Client of a Service. This subroutine returns an indication of whether a particular workstation is a client connected to a service. Returns 1 for the specified service if the specified machine is a client to the machine on which the IsClient() call is made.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | Send | SetRemoteValue
Format: | \RPCManager\IsClient(ServiceName, Workstation [, OptGUID])
Parameters: |
ServiceName
Required. Any text expression giving the name by which the service is known.
Workstation
Required. Any text expression giving the name or IP address by which the workstation is known to the RPC Manager.
OptGUID
Any optional parameter that provides the GUID for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

The return value from this subroutine is a logical value, if true (1) the workstation is a client connected to the service, if false (0) it is not.
If the 16-byte binary format of the GUID is not known, the GetGUID function may be used to obtain it.

To obtain a list of service names for your application, open the Trace Viewer Application, connect to RPC Diagnostics, then open the Services Dialog

Example:

  If 1 Main;
  [
    IfThen(\RPCManager\IsClient("ModemManager",
           "TestMachine"),
           ...
          );
  ]

Related information:

RPC Manager Service


IsEqual

Deprecated. Do not use in new code.

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Exists only for backward compatibility. Use StrictlyEqual or StrictlyNotEqual for all new code. Will return TRUE if the parameter values are equivalent, or if both are invalid.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | Valid | StrictlyEqual | StrictlyNotEqual
Format: | \IsEqual(Parm1, Parm2);
Parameters: |
Parm1
Required. Any value, to be compared to parameter 2.
Parm2
Required. Any value, to be compared to parameter 1.
Comments:

This function is equivalent to the longer expression:

!Valid(Parm1) == !Valid(Parm2) OR Parm1 == Parm2

If the parameters are text or numeric, they will be compared directly. If the parameters are expressions, the strings that they evaluate to will be compared. If object values, the Name variables will be used, thus allowing tag to tag comparisons. Other value types will be turned into strings before the comparison.

Examples:

  If !\IsEqual(Color, ChosenColor);
  [
     Color             = ChosenColor;
     EnableColorSelect = 0;
  ]


IsDictionary

(Engine-Level Function)

Description: | A synonym for HasMetadata. Tests whether the parameter is a dictionary.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Dictionary, Variable
Related to: | HasMetaData | Dictionary
Format: | IsDictionary( Value );
Parameters: |
Value
Required. Any value to be tested.
Comments: Any value can be entered as the lone, required, parameter. The result is TRUE if the value is of type Dictionary, regardless of the presence of a root value. Otherwise, a FALSE will always be returned. An invalid parameter will cause a response of FALSE. IsDictionary cannot have an invalid outcome.


IsDisabled

(Alarm Manager module)

Description: | Will indicate if an alarm is disabled. It can be used either as a subroutine or as a function.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: | GetAlarmStatus | IsActive | IsShelved | IsUnacked
Format: | \AlarmManager.IsDisabled (AlarmName);
Parameters: |
AlarmName
Required.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Comments: The IsDisabled subroutine returns a 1 if the alarm is disabled and returns a 0 otherwise.

Example:

Within a custom tag...

  DisabledStatus = \AlarmManager.IsDisabled(\GetAlarmName(\Root, "Low"));


IsLoggedOn

(Security Manager Module

Description: | Returns TRUE if the calling user is signed in, else FALSE.
Returns: | Boolean
Usage: | Script or steady state.
Related to: | GetAccountID | GetAccountInfo | GetFullName | GetGroupName | GetUserName | IsSecured | IsSuspended | SecurityCheck | UIErrorToText
Format: | \SecurityManager.IsLoggedOn()
Parameters: | None
Comments: | This function will report only whether a user is signed in. Use SecurityCheck to test for privileges.

Example:

As an expression in the Opacity property of a page hotbox widget...

  GUITransform(160, 201, 282, 169,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               PickValid(\SecurityManager.IsLoggedOn(), 0), 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "Library", TRUE)\PageChange("SiteListWithMapPage", 14, Invalid, 0, "0", Invalid, Invalid));


IsMatch

(RPC Manager Library)

Description: | Determines whether two names or IPs indicate the same workstation. This subroutine returns a "1" if the two names or IPs (any combination) refer to the same workstation.
Returns: | Boolean
Function Groups: | Network
Usage: | Steady State only.
Related to: |
Format: | \RPCManager.IsMatch(Name1, Name2);
Parameters: |
Name1
Required. Any of the names or IPs by which the first workstation is known to the RPC Manager.
Name2
Required. Any of the names or IPs by which the second workstation is known to the RPC Manager.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
The return value from this function will be a "1" if the two names or IPs (any combination) refer to the same workstation.

Related information:

RPC Manager Service


IsOnLocalBranch

Description: | Returns TRUE if the local machine is maintaining changes that have not been deployed within the repository.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Configuration Management
Related to: | HasCompilationErrors | IsAppEditable | IsRunOnly | HasUndeployedChanges | GetAppInstance | GetLoadedAppInstance | GetOEMLayer
Format: | \AppLayer.IsOnLocalBranch()
Parameters: | None
Comments: | Also defined as the repository tip being on the local branch. Useful for determining whether there is anything that can be deployed or reverted. Note that a steady-state call to this function will not be updated automatically with a repository change. The Layer object can be acquired using GetAppInstance, GetLoadedAppInstance or GetOEMLayer.


IsPotentialServer

(RPC Manager Library)

Description: | Is Potential Server for a Service. This subroutine returns an indication of whether the local workstation is a potential server for a service. Returns "1" if the local workstation can be a server for the specified service. IsPotentialServer should not be called in steady state.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPrimaryServer | Register (RPC Manager) | Send | SetRemoteValue
Format: | \RPCManager\IsPotentialServer(ServiceName [, OptGUID])
Parameters: |
ServiceName
Required. The name by which the service is known.
OptGUID
Any optional parameter that provides the GUID of the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
This function returns Invalid if the local service instance is not running.
If the 16-byte binary format of the GUID is not known, the GetGUID function may be used to obtain it.

To obtain a list of service names for your application, open the Trace Viewer Application, connect to RPC Diagnostics, then open the Services Dialog

Example:

  If 1 Main;
  [
    IfThen(\RPCManager\IsPotentialServer("ModemManager"),
          ...
          );
  ]

Related information:

RPC Manager Service


IsPrimaryServer

(RPC Manager Library)

Description: | Returns 1 if the local machine is connected to the primary server for the specified service.
Returns: | Integer
Usage: | Steady State only.
Function Groups: | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPotentialServer | Register (RPC Manager) | Send | SetRemoteValue
Format: | \RPCManager\IsPrimaryServer(ServiceName [, OptGUID])
Parameters: |
ServiceName
Required. The name by which the service is known.
OptGUID
Any optional parameter that provides the GUID of the application in which the service instance is known. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the module call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

To obtain a list of service names for your application, open the Trace Viewer Application, connect to RPC Diagnostics, then open the Services Dialog

The return value from this module is a logical value, if true (1) the primary server is the active server for the service, if false (0) a backup or no server is active is active.
If the 16-byte binary format of the GUID is not known, the GetGUID function may be used to obtain it.

To determine if a workstation is the current RPC server for a service call RPCManager\GetStatus.

To obtain a list of service names for your application, open the Trace Viewer Application, connect to RPC Diagnostics, then open the Services Dialog

Example:

  If \RPCManager\IsPrimaryServer("ModemManager") Main;
  [
    ...
  ]

Related information:

RPC Manager Service


IsRunning

(Engine-Level Function)

Description: | Check if an external program is running. This function returns an indication of whether a named program is running on the same computer.
Returns: | Boolean
Usage: | Script only.
Function Groups: | Software and Hardware
Related to: | DDE | Spawn
Format: | IsRunning(Program)
Parameters: |
Program
Required. Any text expression giving the program name to test (with or without the .EXE extension).
Comments: This function returns 1 if the specified program is running on the same computer.
If running under 32-bit, this statement will only be valid if the value of Program refers to another 32-bit process.

Example:

  If ! Valid(running);
  [
    running = IsRunning("Excel");
  ]

After executing this statement, the variable running will have a value of 1 if the program Microsoft™ Excel is running and a 0 if not.


IsRunOnly

Description: | Returns TRUE if the application is a run-file-only app, according to the WC contents.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | AcquireLock| IsRunning | GetAppInstance | GetLoadedAppInstance | GetOEMLayer
Format: | \AppLayer.IsRunOnly()
Parameters: | none
Comments: | The application is defined as run-only if it does not contain source files. This function should only be launched as a subroutine.
  If WorkingCopyLock Commit;
  [
     { Now that we have the WC lock, make sure the Layer still is editable }
     IfElse(Layer\IsAppEditable(),
        WriteINIPropertiesObj = Layer\WriteINIProperties(ConfigData, TRUE);
     { Else }
        ForceState("ReleaseLock"); { Abort if app not editable }
     );
  ]


IsSecured

(Security Manager Module

Description: | Returns TRUE if the application has any user accounts defined, else FALSE.
Returns: | Boolean
Usage: | Script or steady state.
Related to: | GetAccountID | GetAccountInfo | GetFullName | GetGroupName | GetUserName | IsLoggedOn | IsSuspended | SecurityCheck | UIErrorToText
Format: | \SecurityManager\IsSecured()
Parameters: | None
Comments: | An application can be unsecured, yet have roles configured. An application is only considered secured if one or more user accounts exist.

Example:

As an expression in the Opacity property of a page hotbox widget...

  GUITransform(160, 201, 282, 169,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               PickValid(\SecurityManager.IsSecured(), 0), 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "Library", TRUE)\PageChange("SiteListWithMapPage", 14, Invalid, 0, "0", Invalid, Invalid));


IsServiceReady

(RPC Manager Library)

Description: | Is Primary Server Active for a Service. This module returns an indication of whether the specified server is in synchronization with the server instance. Returns "1" if the local instance is in synchronization with the server instance.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPrimaryServer | IsPotentialServer | Register (RPC Manager) | Send | SetRemoteValue
Format: | \RPCManager.IsServiceReady(ServiceName [, OptGUID])
Parameters: |
ServiceName
Required. The name by which the service is known.
OptGUID
Required. Any optional parameter that provides the GUID of the application in which the service instance is known. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section. If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.
If the 16-byte binary format of the GUID is not known, the GetGUID function may be used to obtain it.

To obtain a list of service names for your application, open the Trace Viewer Application, connect to RPC Diagnostics, then open the Services Dialog

Related information:

RPC Manager Service


IsShelved

(Alarm Manager module)

Description: | Will indicate if an alarm is shelved. It can be used either as a subroutine or as a called function.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: | GetAlarmStatus | IsActive | IsDisabled | IsUnacked
Format: | \AlarmManager.IsShelved(AlarmName);
Parameters: |
AlarmName
Required.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Comments: The IsShelved subroutine returns a 1 if the alarm is active and returns a 0 otherwise.

Example:

Within a custom tag...

  ShelvedStatus = \AlarmManager.IsShelved(\GetAlarmName(\Root, "Low"));


IsSuspended

(Security Manager Module

Description | Returns TRUE if the user’s account is suspended, else FALSE.
Returns | Boolean
Usage | Script or steady state.
Related to: | GetAccountID | GetAccountInfo | GetFullName | GetGroupName | GetUserName | IsLoggedOn | IsSecured | SectionControl | UIErrorToText
Format: | \SecurityManager\IsSuspended()
Parameters | None
Comments | A user’s account will become suspended when a user tries to sign in, but a password change is required. IsSuspended() will return TRUE until the user closes the password change dialog.


IsSuppressed

(Alarm Manager module)

Description: | Will indicate if an alarm is suppressed. It can be used either as a subroutine or as a called function.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: | GetAlarmStatus | IsActive | IsDisabled | IsUnacked
Format: | \AlarmManager.IsSuppressed(AlarmName);
Parameters: |
AlarmName
Required.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Comments: The IsSuppressed subroutine returns a 1 if the alarm is suppressed and returns a 0 otherwise.

Example:

Within a custom tag...

  SuppressedStatus = \AlarmManager.IsSuppressed(\GetAlarmName(\Root, "Low"));


IsTagOperable

Description: | Returns TRUE if the user is able to operate the selected tag from the Tag Browser using the right-click menu.
Returns: | Boolean
Usage: | Script only.
Function Groups: | Variable
Related to: | DoOperate
Format: | \IsTagOperable(TagObj)
Parameters: |
TagObj
Required object value. The tag to be examined.
Comments:

All of the following are examined to determine whether the tag in question can be operated from the Tag Browser:

  • Security status
  • The current user's privilege set (if security is enabled)
  • Any relevant details of the tag's configuration.


IsUnacked

(Alarm Manager module)

Description | Will indicate if an alarm is unacknowledged. It can be used either as a subroutine or as a function.
Returns | Numeric
Usage | Script or steady state.
Function Groups | Alarm
Related to: | GetAlarmStatus | IsActive | IsDisabled | IsShelved
Format: | \AlarmManager.IsUnacked(AlarmName[, IncShelving]);
Parameters |
AlarmName
Required.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

InclShelving
Optional Boolean. If TRUE, a shelved alarm will be reported here as non-acknowledged, regardless of its status. Defaults to TRUE.
Comments

The IsUnacked subroutine returns a 1 if the alarm is unacknowledged and returns a 0 otherwise.

In most cases, shelving an alarm is considered the same as masking the IsUnacked status to FALSE. (Makes it look like not unacknowledged, regardless of what it actually is.)

For the rare use cases where shelving is to be ignored, the IncludeShelving parameter can be set to FALSE

Example:

Within a custom tag...

  UnackedStatus = \AlarmManager.IsUnacked(\GetAlarmName(\Root, "Low"));


IsVICSession

(Engine-Level Function)

Description | Returns TRUE to indicate that a call is being made from a VTScada Thin Client session.
Returns | Boolean
Usage | Script Only.
Function Groups | VTScada Internet Client
Related to: |
Format: | IsVICSession([IsAnywhere])
Parameters |
IsAnwhere
Optional Boolean. When set TRUE, makes IsVICSession only return true if the session is an Anywhere client session. When FALSE (0), the function returns true if the client is either a VIC or an Anywhere client. Defaults to 0.
Comments Certain modules need to know whether they are being executed from a VTScada workstation or a VIC, and will adjust their behavior as needed. IsVICSession provides a quick test to determine this.


J Functions

The sections that follow identify all VTScada functions beginning with "J".


JoinStrings

(System Library)

Description: | Joins an array of string elements together into one string, with a given separator added between each element from the array.
Returns: | String
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | SplitString
Format: | System.JoinStrings(StringArray[, Delimiter, Count])
Parameters: |
StringArray
Required. One-dimensional array containing text elements to be joined into a string. Numeric elements will be treated as strings.
Delimiter
Optional text. The character (or characters) to be inserted between array elements in the output string. Defaults to "".
Count
Optional integer. If provided, then no more than Count array elements will be used in the resulting string.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Example:

[
  SomeArray         { Array of words                     };
  SomeText          { comma delimited list               };

]
Init [ If 1 Main;
  [
    SomeArray = New(3);
    SomeArray[0] = "One";
    SomeArray[1] = "Two";
    SomeArray[2] = "Three";
    SomeText = System.JoinStrings(SomeArray, ", ");
  ]
]
Main [
  ZText(100, 100, SomeText, 5, 0);
]


JSONEncode

(Engine-Level Function)

Description: | Converts any given VTScada value into a JSON string using UTF-8 encoding.
Returns: | Text or Stream
Usage: | Script only.
Function Groups: | String and Buffer
Related to: | JSONParse | Pack
Format: | JSONEncode(InputValue[, PrettyPrint, Alphabetical, Indent, StreamVar])
Parameters: |
InputValue

Required. Any value to be encoded as JSON.

Text is expected to use UTF-8 encoding.

PrettyPrint
Optional Boolean. If TRUE, the output will have white space and line breaks added for presentation. Defaults to FALSE.
Alphabetical
Optional Boolean. If TRUE, dictionaries will be listed alphabetically. If FALSE, dictionaries will be listed chronologically. Defaults to FALSE.
Indent
Optional numeric. Ignored if PrettyPrint is FALSE. Sets the number of spaces to indent the encoding when PrettyPrint is TRUE.
StreamVar
Optional. If a valid stream is provided, the JSON encoded string will be appended to that stream and returned. The default is for JSONEncode to return a text string.
Comments:

VTScada value types that do not have a string or numeric representation, and are not dictionaries, arrays or structures, will be represented as JSON null.

Arrays of up to three dimensions are supported.

Value metadata does not get included in JSON encodings. Accordingly, when you encode a dictionary with a root value, only the root value gets encoded

Example:

<
{============================== JSONEncodeSample ===========================}
{ Example code to demonstrate JSONEncode().                                 }
{===========================================================================}
JSONEncodeSample
[
  Protected Input               { Input dictionary                          };
  Protected JSONResult          { Input encoded as JSON                     };
  Protected PrettyPrintedResult { Pretty printed JSON result                };
]

Main [
  If Watch(1);
  [
    Input = Dictionary();
    Input["Values"   ] = New(3);
    Input["Values"   ][0] = 10;
    Input["Values"   ][1] = 20;
    Input["Values"   ][2] = 30;
    Input["Timestamp"]    = "2017-01-02T03:24:19Z";

    JSONResult = JSONEncode(Input);
    PrettyPrintedResult = JSONEncode(Input, TRUE);
  ]
]

{ End of JSON_EncodeSample }
>

JSONResult will be the following:

{"Values":[10,20,30],"Timestamp":"2017-01-02T03:24:19Z"}

PrettyPrintedResult will be the following:

{
  "Values": [
    10,
    20,
    30
   ],
  "Timestamp": "2017-01-02T03:24:19Z"
}


JSON_Encode

(System Library)

Deprecated. This is now a wrapper for JSONEncode

Description: | Takes a VTScada dictionary, structure or array which may be nested, and encodes it as JSON.
Returns: | Text
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | JSONParse
Format: | \System.JSON_Encode(Input[, PrettyPrint])
Parameters: |
Input
Required. Any stream expression for the socket. If this isn't a socket stream, invalid is returned.
PrettyPrint
Optional Boolean. If TRUE, the output will have white space and line breaks added for presentation. Default to FALSE.
Comments:

The return value will be the input encoded as JSON. Text will be encoded as UTF-8, unless there are any sequences of bytes in the input string that cannot be represented as UTF-8, in which case the string will be substituted for JSON null.

VTScada value types that are not dictionaries, arrays or structures, and that do not have a string or numeric representation, will be represented as JSON null.

Value metadata does not get included in JSON encodings. Accordingly, when you encode a dictionary with a root value, only the root value gets encoded


JSONParse

(Engine-Level Function)

Description: | Parse JSON text, converting it to VTScada arrays, objects / structures, strings or other data types as appropriate.
Returns: | Varies. Invalid on non-recoverable error.
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | JSON_Encode | XMLParse
Format: | JSONParse(JSONInputText[, ErrorMessageOut, ObjectsAsStructures])
Parameters: |
JSONInputText
Required. JSON text to be parsed.
ErrorMessageOut
Optional text. Output parameter that is set to a text representation of the error.
If recoverable parsing errors occur, this may be set in addition to the return value being valid. If for example an array of strings has one string that cannot be displayed in the system's configured code page, only that element of the VTScada array will be invalid and the ErrorMessageOut text will reflect this.
ObjectsAsStructures
Optional Boolean. If this parameter is TRUE, JSON objects will be created as VTScada structures for compatibility with XMLParse(). If this is not specified or is false, JSON objects will be translated into VTScada dictionaries. Defaults to FALSE.
Comments:

Dictionaries and structures returned by JSONParse() are case sensitive. The order that JSON object names are inserted into VTScada dictionaries or structures should be treated as undefined.

The input text is expected to be encoded as UTF-8, as per the JSON standard. Text using another encoding can be converted to UTF-8 with TextEncode().

Example:

<
{================================= JSONTest ================================}
{ Example code to demonstrate JSONParse().                                  }
{===========================================================================}
JSONTest
[
  Protected JSONInput = "{""type"": ""temperature"", ""values"" :
                       [23.5, 19.7, 21.4], ""enabled"": true}";
  Protected Result;
]

Main [
  If Watch(1);
  [
    Result = JSONParse(JSONInput);
  ]
]

{ End of JSONTest }
>

In this example Result would be a dictionary containing three keys: "type", "values" and "enabled". The "type" key's value is a string "temperature". "Value" is an array of 23.5, 19.7 and 21.4, and "enabled" is the value 1.


K Functions

The sections that follow identify all VTScada functions beginning with "K".


KeyCount

(Engine-Level Function)

Description: | Returns the number of keys pressed since the state became active, either edited or non-edited.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Keyboard
Related to: | KeyFake | Keys | MatchKeys
Format: | KeyCount(Option)
Parameters: |
Option
Any logical expression. If true, the number of non-edited keystrokes is returned; if false, the edited keystrokes is returned.
Comments:

Edited keystrokes are printable characters and the enter key. Non-edited keystrokes are all keystrokes, including printable characters, enter key, special keys, and function keys.
When the Backspace key is pressed, the key code for backspace is entered as a non-edited keystroke, and the previous edited keystroke is removed. That is, when Backspace is pressed the number of non-edited keystrokes increments, and the number of edited keystrokes decrements (and possibly goes negative).

Count keys only while the calling state (window) has focus.

Examples:

  If KeyCount(1) MainMenu;

This action simply waits for any key to be pressed, and changes to another state. Another way of using this function would be:

  If KeyCount(1) > KeysChecked;

This checks that the number of non-edited keys pressed is greater than the value of keysChecked. This might be the beginning of a loop that would process keystrokes one at a time (such as a text editor).


KeyFake

(Engine-Level Function)

Description | Places a string of characters in a window's keyboard buffer, simulating a key press.
Returns | Nothing
Usage | Script Only.
Function Groups | Keyboard, String and Buffer
Related to: | KeyCount | Keys | MatchKeys
Format: | KeyFake(Object, String)
Parameters |
Object
Any expression that returns an object value that defines a window.
String
Any text expression that gives the characters to place in the window's keyboard buffer.

Examples:

  If 1 Main;
  [
    KeyFake(myWindow, "Hello World");
  ]


Keys

(Engine-Level Function)

Description | Returns the most recently pressed keys, optionally flagging virtual key codes.
Returns | Text
Usage | Script or steady state.
Function Groups | Keyboard, String and Buffer
Related to: | KeyFake | KeyCount | MatchKeys
Format: | Keys(N, Option)
Parameters |
N
Any numeric expression giving the number of keys to get.
Option
Any logical expression indicating whether edited mode or non-edited mode should be used. Set to TRUE for the non-edited mode.
Comments

In the non-edited mode, function keys and others that return a virtual key code will have an escape code in the range [0xF8,0xFF]. There could be a 0xFB, 0xF8, etc. pre-pended to the return value. (See Microsoft's online MSDN reference for a list of virtual key codes.) Because of this, the return value may contain more bytes than specified by the parameter, N.

Keys does not work in the Anywhere Client.

Examples:

nonEditPressed = Keys(5, 1);

This sets nonEditPressed to a text string containing the key codes for the last five keys pressed, in order from oldest to most recently pressed.

In Edited Mode, the keys [a][b][c][up-arrow][d] results in the buffer, 61 62 63 64.

In Non-edited mode, [a][b][c][up-arrow][d] results in 61 62 63 FD 48 64.


L Functions

The sections that follow identify all VTScada functions beginning with "L".


LargeSocketWrite

(System Library)

Description: | Paces the write speed to prevent exceeding the socket output buffer limit.
Returns: | None.
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | | SocketAttribs |ClientSocket
Format: | System.LargeSocketWrite(Stream, Source)
Parameters: |
Stream
The socket stream to which data will be written.
Source
A stream or text value containing the data to write.
Comments:

LargeSocketWrite writes as many bytes as there is space in the socket output buffer and then waits for there to be space for some more before writing more bytes until all content in Source has been drained. It is a launched module and so you should launch it and wait for completion (the object value returned from the launch statement goes Invalid). Failure to do so may result in not all data being written.

LargeSocketWrite is more efficient if a stream is passed in the Source parameter - a text value is first converted to a BuffStream before writing and the BuffStream discarded after the write completes. If the Source Parameter is a stream, writing to the socket starts from the current position in the stream. The Source stream is not repositioned at the end of the write. Passing in a Stream parameter that is not a ClientSocket or ServerSocket stream does nothing and LargeSocketWrite will terminate quickly.


LastSelected

(Engine-Level Function)

Description: | Returns the most recently selected graphics statement.
Returns: | Text
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Graphics
Related to: |
Format: | LastSelected(Object)
Parameters: |
Object
Required. Any object value expression that defines the window where the selected items are found.
Comments: None


Latch

(Engine-Level Function)

Description | Latch On or Off. This function allows a transient change of a variable to be captured. Its return value is determined by the rules listed in the comments section.
Returns | Boolean
Usage | Steady State only.
Function Groups | Variable
Related to: | Toggle | MatchKeys | TimeOut | Intgr | RTimeOut
Format: | Latch(Set, Reset)
Parameters |
Set
Required. Any numeric expression. When TRUE (i.e. not equal to 0), the latch is set.
Reset
Required. Any numeric expression. When TRUE (i.e. not equal to 0), the latch is reset.
Comments This function starts in a state with its return value being a valid 0 (false). The change in values is governed by the following rules
Set | Reset | Old Value | New Value
FALSE | FALSE | FALSE | FALSE
FALSE | FALSE | TRUE | TRUE
Either | TRUE | Either | FALSE
TRUE | FALSE | Either | TRUE
Invalid | TRUE | Either | FALSE
Either | Invalid | Either | Invalid

If both the Set and Reset are false, the latch value remains unchanged. Note that a TRUE Reset overrides a TRUE Set but does not reset that parameter. Each parameter is reset individually.

This function resets its parameters after they evaluate to true. This is significant only for functions that can be reset, such as MatchKeys, TimeOut, Intgr and RTimeOut.

Example:

motorOn = Latch(MatchKeys(1,"1") { Set the var with a "1" },
                MatchKeys(1,"0") { Reset the var with a "0" });

This controls the variable motorOn from the keyboard. MotorOn initially starts as 0. When 1 is pressed on the keyboard, the latch is set and motorOn becomes 1. When 0 is pressed on the keyboard, the latch is reset and motorOn becomes 0.

Related information:

Latching and Resetting Functions


Launch

(Engine-Level Function)

Description | Runs a module instance and returns a pointer to it.
Returns | Varies - see comments
Usage | Script Only.
Function Groups | Basic Module
Related to: | Call | FindVariable | LoadModule | Return | Slay | Thread
Format: | Launch(\Launchee, Parent, Caller[, P1, P2, ...])
Parameters |
\Launchee
Required. A module pointer or a text expression giving the module to run.
See Comments
If this parameter is a module value that has been returned from a LoadModule or FindVariable statement, that module will be launched.
If this parameter is type text it may either designate the module by its name, if it is in scope, or it may give the name of a variable that contains the module value of the module to launch.
Parent
Required. The object value of the module where the Launchee is to resolve its global variable references.
If a valid non-object value is supplied the Launchee will resolve its global variable references to the scope defined by the first parameter.
If this is invalid, the module will still run, but global references will be invalid.
Caller
Required. . This specifies the module instance (object) where the Launchee acts as if it were called from there.
If this is invalid, the module will still run but will not stop without a Slay. A Return in the case of a subroutine.
If it is valid, the module will stop when the Caller module instance stops, when a Slay is executed upon it, or (subroutine only) when it calls Return. Often, the object value of the window to draw within.
P1, P2, ...
Optional. Are any expressions that will be supplied as parameters to the launched module.
Comments

You should do implicit launches when possible, noting that it is almost always possible. The only time you need to do an explicit launch is if you need the code to execute with a different parent or caller than it normally would. This use-case is quite specialized.

This function returns an object value of the newly started module. In general, variables that are listed in the final parameter spots are passed to the module as a value only. This means that if the launched module instance changes the value of one of the parameters, its value will not change outside of the scope of the module.
If a launched module contains a Return statement it is will run as a subroutine, whether it is explicitly or implicitly launched. This is true even if the Return statement is in a state that does not get executed. In that case, the script that launches the sub-routine will stop its execution indefinitely, waiting for the sub-routine to return a value.
If "myMod" is a subroutine, then in the statement,

x = Launch("myMod", …);

x will be set to the value returned by the subroutine's Return statement upon completion. Prior to execution of the Return statement, x will be invalid, unlike a module that is not a subroutine, which would set x to the object value of the launched module.

A common syntactical problem with the use of the Launch function will result in two instances of a module running. The following example shows the improper syntax

[
  X Module;
  Y;
]
Launch(X, Self, Self);

(assuming that "X" is declared as a module.) The problem here is the first parameter. As written above, the code will launch a module called "X", and use the return value from the launch (an object value) as the first parameter for Launch . This will result in two copies of the "X" module running. If you copy the module value into Y (ie Y = \X;), then Launch(Y, Self, Self) does not launch two copies.

The correct syntax is:

 Launch("X", Self, Self);

Use care in how you write a Launch statement. For example:

X = Launch(Scope(<variable>, "Y", TRUE)...

If it is unknown whether Y exists in the module pointed to by <variable> or if in fact <variable> is valid, then setting the ScopeLocal parameter to TRUE as shown, may help to avoid undesirable results.

In the rare case that the module being launched is a child module of the caller's module, and if there are variables external to the module that the module itself will be required to alter, it is best to make them within the scope of Parent.

Example:

  If !Valid(Obj);
  [
    Obj = Launch(\DataLog,
                 Self(), Self()  { Parent and caller },
                 TimeSpan, FileSave { Parameters });
  ]

This launches one instance of the module DataLog. The current module is its parent and caller. The two variables TimeSpan and FileSave are passed as parameters to the module.


LayerInUse

Description: | Returns true if the application is running or if there are any applications that depend on this layer, running or not.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: |
Format: | \AppLayer.LayerInUse()
Parameters: | None
Comments: | If this function returns FALSE, the layer is not in use and may be removed from the VAM.

Examples:


LayerRoot\Stop

Description: | Stop the application designated by LayerRoot
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | Start |
Format: | LayerRoot\Stop
Parameters: |
IsRestart
Optional Boolean. Set TRUE if the application is to be re-started.
Comments: For a VTScada application, most of the work is done in Start\VTSThread. After the app is stopped, AppStopMonObj does some post-stop clean-up. The work is done there rather than here as a script application often stops just by slaying itself, and AppStopMonitor picks up on both situations.
This module launches a worker module into the Layer so that the operation is not interrupted by this module's caller being slain.

Examples:

Building on the example in Start(), the following will stop the application started in that example.

CompLayer\Stop();


Limit

(Engine-Level Function)

Description | Set Value Minimum and Maximum. This function returns a value that is limited both on the high and low ranges.
Returns | Numeric
Usage | Script or steady state.
Function Groups | Rounding Math
Related to: | Max | Min
Format: | Limit(X, Low, High)
Parameters |
X
Required. The variable whose numeric value will be limited.
Low
Required. Any numeric expression giving the lower limit for the value X.
High
Required. Any numeric expression giving the upper limit for the value X.
Comments This function performs the same operation as Min(High, Max(Low, X)) but is simpler to write and requires less memory. If the value exceeds one of the limits, the function returns that limit. Otherwise, the value is returned unchanged. If Low is greater than High, the value for High is returned. If any of the parameters is invalid, the function returns invalid.

Examples:

a = Limit(123.4, 0, 100);
b = Limit(-2.6, 0, 100);
c = Limit(36.7, 0, 100);
d = Limit(36.7, Invalid, 100);

The values for a, b, c, and d are 100, 0, 36.7 and invalid, respectively.


Line

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Draws a line on the screen that may consist of multiple segments.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUIPolygon | Pipe | PlotXY | ZLine
Format: | Line(Style, Width, Color, Curvature, X1, Y1, X2, Y2, ...)
Parameters: |
Style
Required. Any numeric expression giving the Line Types. Valid line styles are from 1 to 5 inclusive. A line style of 1 is a solid line
Width
Required. Any numeric expression giving the width of the line in units of X screen coordinates. The width is always rounded to result in an odd number of pixels on the screen. The minimum width displayed will be 1 pixel.
Color
Required. Any numeric expression giving the VTScada Color Palette of the line.
Curvature
Required. Any numeric expression giving the radius of curvature of the corners for the line. This is specified in units of X screen coordinates. If the number of endpoints is 2, Curvature is ignored.
X1, Y1, X2, Y2, ...
Required. Any numeric expressions giving the screen coordinates of the line endpoints.
Comments:

This statement has been superseded by the GUIPolygon and ZLine statements and is maintained for backwards compatibility only.
The radius of curvature of the line corners is the radius of the arc that joins the line endpoints. A Curvature of 0 results in sharp (square) line corners. Larger Curvature numbers result in greater rounding of the line corners.

As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.

Within an Anywhere Client session, this function does nothing.

Example:

Line(1 { Solid line style },
     1 { Line width is 1 pixel },
     10 { Light green },
     0 { Curvature not applicable (2 endpoints) },
     0, 0 { Coordinates of first end },
     XLoc(), YLoc() { Second end follows mouse });

This statement will draw a light green solid line with one end anchored at (0, 0) and the second end following the movements of the mouse.


LinearIndicator

(Meter Parts Library)

Description: | Will draw a linear type indicator. A linear indicator can be drawn in 3 different ways. Scaled from min to current position, cropped from min to current position or as a line that moves to the current position. This function must be called inside a GUITransform to work properly.
Returns: | Image handle
Usage: | Steady State only.
Function Groups: | Graphics
Related to: |
Format: | \MeterParts\LinearIndicator(DataSource, IndicatorImage, Orientation, DrawMode, IndicatorRToL, Hue, Saturation, Brightness, Transparency, Contrast, ColorizeHue, ColorizeIntensity, UseTagScaling, MinScaleValue, MaxScaleValue, DampenIndicator, NumberOfSteps)
Parameters: |
DataSource
Required. A Tag name, constant or expression that provides the value to show.
IndicatorImage
Required. The full path to the name of an image file to use as the indicator. Typically this is an image of a needle.
Orientation
A flag indicating the orientation of the Indicator. Set to 0 for Horizontal and 1 for Vertical. The default is 0 (Horizontal).
DrawMode
Controls how the indicator is drawn. Details of the 3 modes are as follows
DrawMode | Meaning
0 | Scaled. This mode will scale the Indicator image from the 0 position to the position that represents the current value of the DataSource.
1 | Cropped. This mode will scale the indicator image from the 0 position to the full position and then crop it to the position that represents the current value of the DataSource.
2 | Moving This mode will keep the Indicator image at a constant size and simply move it to the position that represents the current value of the DataSource.
IndicatorRToL
A flag that changes the location of the 0 position. If set to true, the 0 position is on the right side or the top in vertical orientation.

If set to false and the 0 position is on the left side or the bottom in vertical orientation. The default is false.
Hue
The hue translation to perform on the Indicator image. This enables you to change the color.
The image must have color in it already to perform a hue translation. If there is no color to start with, then changing this value does nothing. You can add color by setting a value for the ColorizeHue parameter, described later.
The default is 0, indicating that no hue translation is done and the indicator is in its native color.
Saturation
The amount of saturation of the colors in the indicator image. A value of 0 will make the image black and white (no color saturation). A value of 2 produces a brightly colored (saturated) indicator. The default is 1 which corresponds to the native saturation of the indicator image.
Brightness
An adjustment of the brightness of the indicator image. Higher numbers produce a brighter indicator image. A 0 produces a black image. The default is 1 which corresponds to the native brightness of the indicator image.
Transparency
An adjustment of the opacity of the indicator where 1 means 100% opacity and 0 means %100 transparent. The default is 1.
Contrast
An adjustment of the contrast of the colors in the indicator image. A value of 0 produces a flat looking image and a value of 2 gives a high contrast image. The default is 1 which corresponds to the native contrast of the indicator image.
ColorizeHue
A value that works in conjunction with ColorizeIntensity. This is the hue of the color that is introduced by colorizing an image. Colorizing an image will introduce color into an image that previously was black and white or grayscale. The default value is 0.
ColorizeIntensity
A value to define how much color to introduce into the image. The default is 0, meaning not to introduce any color at all into the image.
UseTagScaling
A flag that indicates whether to use the supplied Tag’s scaling values. The default is false.
MinScaleValue
The minimum scale value to use if the UseTagScaling flag is not true. The default is 0.
MaxScaleValue
The maximum scale value to use if the UseTagScaling flag is not true. The default is 100.
DampenIndicator
A flag to indicate whether to dampen the indicator movement. Dampened movement creates the effect of animating the indicator. The default is false.
Comments: This function must be called within a GUITransform statement in order for it to work correctly.
The size of the indicator image is scaled with respect to the original size of the image and the size of the transform. If you want a smaller indicator you can simply make a smaller transform.

Example:

  GUITransform(350, 144, 500, 124,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "MeterParts", TRUE)\LinearIndicator(Invalid,
        "Bitmaps\Meter Parts\Indicators\Linear\LIndicator2.png", 0,
               2, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 100, 0, 0, "<FFFFFFFF>",
               Invalid, Invalid));


LinearLegend

(Meter Parts Library)

Description | Draws a legend (i.e. the text labels) for a linear type meter. They are drawn in a line, either horizontally or vertically, with consistent spacing. This function must be called inside a GUITransform to work properly.
Returns | Image handle
Usage | Steady State only.
Function Groups | Graphics
Related to: |
Format: | \MeterParts\LinearLegend(TagName, Orientation, NumLabels, Font, Color, Reserved, UseTagScaling, MinScaleValue, MaxScaleValue)
Parameters |
TagName
Required. The name of the Tag to use for scaling. If no tag is specified, then tag scaling cannot be used to automatically obtain the minimum and maximum scale values.
Orientation
A flag indicating the orientation of the legend. Set to 0 for horizontal and 1 for vertical. The default is 0 (Horizontal).
NumLabels
The number of Labels to show. The default is 3.
Font
The name of a Font tag to use for the legend text.
Color
A color index for the color of the legend text. The default is 0 (black).
Reserved n/a
For use at a later time. Should be set to 0.
UseTagScaling
A flag that indicates whether to use the supplied tag’s scaling values. The default is false.
MinScaleValue
The minimum scale value to use if the UseTagScaling flag is not true. The default is 0.
MaxScaleValue
The maximum scale value to use if the UseTagScaling flag is not true. The default is 100.
Comments This function must be called within a GUITransform statement in order for it to work correctly.
The text should scale with the size of the transform. If it does not, then you might have picked a font that doesn’t scale. Some non true-type fonts will not scale.

Example:

  GUITransform(694, 852, 844, 702,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               \MeterParts\LinearLegend(Invalid, 0, 3, Invalid, 0, 0,
                                        0, 0, 0, 100));


ListAdd

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | This subroutine will add the alarm object to a list. This is useful if a user-defined list has been created.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | CurrentTime
Format: | \AlarmManager\ListAdd(AlarmObject, [EventTime], List);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine.
EventTime
The time stamp to use when adding this event to the alarm lists. If invalid, the default is CurrentTime().
List
Required. Any numeric expression for the number of the list to which to add the alarm.
Comments: The ListAdd subroutine always returns "0".


Listbox

(System Library)

Description: | Draws a list box with scroll bar (if required) and indicates the selected item.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | RadioButtons | SpinBox | SplitList | TextBox | ToolBar | VScrollbar
Format: | System.Listbox(X1, Y1, X2, Y2, Data, Index, [Picked, Flat, DoubleClick, MaxLen, RightClick, PostIt, FocusID, Multi, PickList, ColWidths, ColLabels, ColDivider, EditSelected])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the Listbox, usually the left side.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the Listbox, usually bottom.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the Listbox opposite to X1, usually the right side.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the Listbox, whichever is the opposite of Y1, usually the bottom.
Data
Required. An array of data to display in the Listbox.
Index
Required. The index of the highlighted item (i.e. any variable whose value will be set to the index of the chosen item (highlight).) If Multi is true, this will be the index of the last chosen item.
Picked
An optional parameter that may be a variable whose value is set to true (1) when an item is chosen in the Listbox. The setting of Index by an external source will not trigger Picked. If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.
Flat
Obsolete.
DoubleClick
An optional parameter that may be a variable whose value is set to true (1) when an item has been double clicked upon. If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.
MaxLen
An optional parameter that is any numeric expression giving the maximum length of the list. If omitted or invalid, the maximum list length is given by the size of the array Data.
RightClick
An optional parameter that may be a variable whose value is set to true (1) when an item is selected with the right mouse button.
If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.
PostIt
An optional parameter that is any logical expression. If true (non-0), a tool tip will be displayed if the text in the list box has been truncated at its right edge. The default is true.
FocusID

An optional parameter that is any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is zero, the list box will not accept keyboard input, but mouse input will still be recognized.
If it is less than zero, the Listbox will not accept any input and will appear grayed out. The default value is 1.

Multi
An optional parameter that is any logical expression. If true (non-0), multiple items may be selected in the list. The default is false.
PickList
An optional parameter that is a variable whose value is set to the list of items selected if Multi is true (1). If invalid, no items are selected.
This variable may initially be set to a dynamically allocated array (one created with the New function) containing items to be highlighted/selected upon the startup of the listbox.
ColWidths
An optional parameter that indicates the starting widths for multiple columns.
ColLabels
An optional parameter that provides an array of labels for the columns.
ColDivider
An optional parameter that indicates the type of divider to appear between columns. No border appears if the list is a single column. ColDivider may have one of the following values: The default is "2".
ColDivider | Divider Type
0 | No column divider shown.
1 | Show a non-moveable column divider.
2 | Show a moveable column divider.
EditSelected
An optional flag that indicates whether a selected item may be edited in the list. EditSelected will be set to 0 when the editing stops. EditSelected may have one of the following values:
EditSelected | Meaning
Invalid | No editing.
0 | Enable item editing.
1 | Edit current selected item.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

If Multi is true, multiple items in the list may be selected by using the <Shift> or <Ctrl> keys along with mouse input. If <Ctrl> is held while an item is clicked on by the mouse, it will become selected (or deselected if it is already selected) and will be added to the list of chosen items. If <Shift> is held while an item is clicked on by the mouse, all items from the last selected item to the selected item will be selected. All other items outside of this list will be deselected. If both <Ctrl> and <Shift> are held while an item is clicked on by the mouse, all items from the last selected item to the selected item will be set to the state of the last selected item.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Examples:

System.Listbox(10, 10, 110, 210 { Outline of list box },
               List { Data to display },
               Highlight { Index of highlight });

In this example, the listbox is displayed with only a single black line around it. Notice that since none of the optional parameters are used, they have been omitted. Also, the listbox will display the full contents of the array because MaxLen has similarly been omitted.

System.Listbox(20, 355, 295, 100 { Outline of listbox },
               NameList { list of names to display },
               ListIndex { Index of highlight },
               0 { Picked parm not used },
               0 { Drawn 3D },
               Double { TRUE when double clicked },
               Invalid { MaxLen parm not req'd },
               RtClick { TRUE when rt clicked on },
               1 { tool tips as req'd },
               5 { Focus ID },
               1 { Multiple selections },
               FinalList { Var containing list of
               selected items });

This example illustrates including all of the optional parameters, even those such as MaxLen that in this case are not used.


ListCertificates

(Engine-Level Function)

Description: | Enumerates X.509 certificates in a certificate store resident on the local computer.
Returns: | An array of structures, with each structure representing key fields from a certificate.
Usage: | Script Only.
Function Groups: | Certificates
Related to: | AddCertificate | CheckCertificateChain | FindCertificate | GetCertificateInfo | MakeSelfSignedCertificate | RemoveCertificate | SetCertificateProperty
Format: | ListCertificates(UseMachineStore, StoreName[, ExtendedKeyUsage, Issuer, RequirePrivateKey, ])
Parameters: |
UseMachineStore
Required Boolean. If TRUE, enumerates certificates from the Personal store in the Local Computer's certificate collection. If FALSE enumerates certificates from the Personal store of the Current User.
StoreName
Required text. The name of the certificate store to list.
ExtendedKeyUsage
Optional text. If valid, this must be an Object Identifier (OID) for an extended key usage. This allows you to filter the returned list of certificates by extended key usage (EKU).
For example, "1.3.6.1.5.5.7.3.1" is the OID for an EKU allowing server authentication.
Issuer
Optional text. If valid, specifies the name of a certificate issuer. This allows you to filter the returned list of certificates by issuer.
RequirePrivateKey
Optional Boolean. If TRUE, only returns certificates for which you hold a private key. Defaults to FALSE.
Comments

ListCertificates will return certificates that have either expired or are not yet valid.

The array of information returned is an array of structures, with one structure per certificate that meets the supplied criteria. The structure has the following members:

FriendlyName

Text. The friendly name of the certificate.

Name

Text. The Common Name of the certificate.

Description

Text. The description of the certificate.

Country

Text. The country code (e.g. CA, GB).

State-Province

Text. The state/province on the certificate.

Locality

Text. The locality on the certificate (e.g. town).

Organization

Text. The organization the certificate is issued to.

OrganizationUnit

Text. The organization unit the certificate is issued to.

Issuer

Text. The Common Name of the certificate issuer.

Serial

Text. The certificate serial number.

ValidFrom

Double. VTScada timestamp of the certificate start date/time.

ValidTo

Double. VTScada timestamps of the certificate end date/time.

EKU

Array. Each Extended Key Usage on the certificate is stored as a text OID in its array element.

SHA1Thumbprint

A binary buffer holding the computed SHA1 thumbprint of the certificate. This will match with the thumbprint that the Windows certificate dialog’s Details tab displays.

SHA256Thumbprint

A binary buffer holding the computed SHA256 thumbprint of the certificate.

AlternateNames

A structure with the following members, extracted from the Subject Alternative Name certificate extension:

DNS

An array of DNS names.

URL

An array of URLs.

IP

An array of IPs.

Other

An array of structures of other entries that are defined by an OID. The structure has the following format:

OID

The Object Identifier of the quantity.

Value

The value of that quantity.

Blob

The DER-binary encoded certificate.

PublicKey

The public key of the certificate.

This is held in a VTScada cryptographic key value and may be used as an input parameter to appropriate VTScada cryptographic statements.

PrivateKey

The private key of the certificate, if one is stored on this computer and the current user has permission to access it.

This is held in a VTScada cryptographic key value and may be used as an input parameter to appropriate VTScada cryptographic statements.

If the user has insufficient permission or there is no private key, Invalid is stored here.

Example:

    CertificateData = ListCertificates(FALSE,  { User store }
                                       "My",   { Which user store }
                                      \szOID_PKIX_KP_CLIENT_AUTH,{ Suitable for client identity authentication }
                                      Invalid, { Any issuer will do }
                                      TRUE);   { Must have a private key }

This will return an array of structures, with one element for each certificate in the user’s Personal store that is suitable for client authentication and has a private key that matches its public key.


ListInstances

(Engine-Level Function)

Description: | Returns an array of all instances of a module.
Warning: | This function should be used only by advanced programmers.
Returns: | Object
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Basic Module
Related to: | FindVariable | CalledInstances | NumInstances | GetInstance
Format: | ListInstances(Module)
Parameters: |
Module
Required. Any expression for the code value of the module.
Comments:

Returns Invalid if there are no instances.


ListKeys

(Engine-Level Function)

Description | Returns an array of all keys used within a dictionary. Use this to discover what is in a dictionary.
Returns | Array
Usage | Script Only.
Function Groups | Dictionary, Variable
Related to: | Dictionary | MetaData | DictionaryCopy | DictionaryRemove | GetNextKey | GetKeyCount
Format: | ListKeys( dictionary[, order, return value ]);
Parameters |
Dictionary
Required. The name of the dictionary.
Order
An optional numeric expression. Defines the search according to the following table of values. Defaults to 0 if missing or invalid
Order | Meaning
0 | List in forward alphabetic order.
1 | Ordered by when the keys were added to the dictionary with the oldest key first.
2 | List in backward alphabetic order
3 | Ordered by when the keys were added to the dictionary with the newest key first.
4 | Sparse Numeric. Keys must be numeric. Used to return a sparse array in order based on the key values.
Return Value
Controls what is returned according to the following table. Defaults to 1.
Value | Returns
< = 0 | Invalid
1 | 1D array (vector) containing the dictionary keys
2 | 1D array (vector) containing the dictionary values, ordered by key
3 | 2D array (table). The first column (left-most) will contain the dictionary keys and the second (right-most) will contain the dictionary values. Ordered by key.
>= 4 | Invalid
Comments: To get the number of keys in a given dictionary only, GetKeyCount is more suitable.

Example 1:

(given a dictionary named X as shown in the following image)

  R = ListKeys( X );
  R == ["A", "B", "C"];

Example 2:

Given the code:

 If Watch(1);
  [
    X = Dictionary();
    X["A"] = 42;
    X["B"] = 86;
    X["C"] = 99;
    Buf = ListKeys(X, 1, 3);
  ]

Buff will contain:


ListRemove

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | This subroutine will remove the alarm object from a list. This is useful if a user-defined list has been added.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | CurrentTime
Format: | \AlarmManager\ListRemove(AlarmObject, [EventTime], List);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine.
EventTime
The time stamp to use when adding this event to the alarm lists. If invalid, the default is CurrentTime().
List
Required. Any numeric expression for the number of the list from which to remove the alarm.
Comments: The ListRemove subroutine always returns a "0".


ListVars

(Engine-Level Function)

Description: | Returns a list of variables.
Returns: | Array
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modification, Variable
Related to: | FindVariable | ReadPropertiesFile
Format: | ListVars(Module, Name, LowClass, HighClass, Type, Attributes, Global, Info, Sort)
Parameters: |
Module
Required. Any module or object value. This identifies the module where the variable list begins.
Name
Required. Any text value, which specifies a name to match when listing. Wildcards are allowed. The wildcard "?" will match any character in a name. The wildcard "*" will match any series of characters.
The backslash character has special meaning, in that it can be added in front of the characters *, ? or \ to search for these characters explicitly. In these three cases, the leading backslash will be ignored.
Other characters must match exactly. A leading backslash in front of any characters other than the three noted will be included in the search.
LowClass
Required. Any numeric expression. This specifies the lowest class included in the list. Valid range is 0 to 65535. Default class for variables is 0. See also: Variable Classes.
HighClass
Required. Any numeric expression. This specifies the highest class included in the list. Valid range is 0 to 65535. Default class for variables is 0.
Type

Required. Any numeric expression that specifies the type of variable to match, as found by adding together values in the following table:

(See: Bitwise Parameters & Operations)

Type | Bit No. | Variable Type
0 | - | Match all
1 | 0 | Normal
2 | 1 | Array
4 | 2 | Parameter
8 | 3 | Module
Attributes
Required. Any numeric expression that specifies the attributes of a variable to match, as found by adding together values in the following table:
Attributes | Bit No. | Variable Attribute
0 | - | Match all
1 | 0 | Shared
2 | 1 | Persistent
4 | 2 | Constant
8 | 3 | Simple
16 | 4 | Temporary
32 | 5 | Protected
Global

Required. Any logical expression.

If false, only local variables in Module are listed.

If true and Module is a module value, then all variables in parent objects of Module are also included in the results.

If true and Module is an object value, then all variables in parent objects of Module are also included.

Info
Required. Any numeric expression, which specifies the information to return in the array, as shown in the following table:
Info | Information
0 | Text name
1 | Attributes (bit field - same as for VarAttributes function)
2 | Default value
3 | Class
4 | Module value where defined
5 | Module text name where defined
6 | Number of instances
7 | Current value
8 | Pointers to variables
9 | Use List - each element in the returned array is an array of #VTypeModStateStmnt showing the steady-state statements presently reading the listed value.
10 | Set List - each element in the returned array is an array of #VTypeModStateStmnt showing the steady-state statements presently assigning the listed value (usually at most one).
11 | Variable - each element in the returned array is a #VTypeVariable, as would be returned by FindVariable
12 | DebugInfo - each element in the returned array is an array of 2 elements. The first is the value that option 11 would return (a #VTypeVariable). The second is the value that option 8 would return (a #VTypePtr).

If Info is 7 or 8, then Module should be the object value of the instance where the variable instances reside to get all information.

If Module isn't an object value, then the return value will be invalid unless there are shared or persistent variables.

Values 9, 10 and 12 are used only by the Source Debugger.

Sort

Required. Any logical expression. Sorting behavior is affected by both the Global parameter and the Module parameter, and is not a simple toggle.

The results are always ordered such that instance variables (if Module is an object with instance variables) appear first, followed by module's non-instance variables. If Global is true, then variables for Module's parents follow, in order stepping up the static tree (if Module is a module) or scope tree (if Module is an object). This ordering of variables is preserved whether or not the Sort parameter is TRUE.

If Sort is FALSE, then beyond the above primary ordering, each group of variables gets a secondary ordering, sorting the variables in the order that they appear in the module's source file, with any variables added to the module since it was loaded added to the end of the list in the order that they were added. If Sort is true, then the secondary ordering is instead alphabetical.

Comments: The variable used to store the returned array does not need to be declared as an array. It will be dynamically allocated as such by the function. If no variables are found, the return value will be a valid pointer to an array with no elements.

Data Handling in Statically-declared Arrays vs. Dynamically-allocated Arrays.
ListVars handles data in statically declared arrays differently from data stored in dynamically allocated arrays. In the following example, two arrays have been declared. The first (A1) is statically-declared, while the second (A2) is dynamically-allocated.
A1[2][3];
A2;

A2 = New(2, 3);
A1[0][0] = "zerozero";
A2[0][0] = "zerozero";
A1[1][0] = BuffStream("onezero");
A2[1][0] = BuffStream("onezero");
A1[1][1] = 11;
A2[1][1] = 11;
A1[1][2] = 12;
A2[1][2] = 12;

AFiles = ListVars(Self(), "A*", 0, 65535 { class limits }, 0, 0 { all matches },
0 { local only }, 8 { ptr to variables }, 1 { sort });

To retrieve the value of each element in the statically-declared array named, "A1", you can use:

ElemA1_00 = AFiles[0][0][0];
ElemA1_10 = AFiles[0][1][0];
ElemA1_11 = AFiles[0][1][1];

… and so forth. However, this same call for the dynamically-allocated array named, "A2", will not retrieve the expected elements. Rather, the correct syntax for data retrieval in this case is:

ElemA2_00 = (*AFiles[0])[0][0];
ElemA2_10 = (*AFiles[0])[1][0];
ElemA2_11 = (*AFiles[0])[1][1];

The data retrieval method displayed above for the dynamically-allocated array will also work for static arrays, thus it is recommended that this be the method used for general array data retrieval.

Example:

If ! Valid(myList);
[
  myList = ListVars(FindVariable("Calculations", Self(), 0, 1)
  { Module to find variables of },
  "*" { List all variables },
  0, 0 { Class 0 variables only },
  0, 0 { All types and attributes },
  0 { Variables of this module only },
  0 { Name of variable },
  1 { List alphabetically });
]
Table(myList[0] { Starting array element },
      ArraySize(myList, 0) { Number of elements },
      10, 10, 0, 10 { Start at (10, 10) list vertically },
      4, 0, 100, 14, 0, 0, 8, 0 { Text values and attributes });

This set of statements will display a list of all variables that belong to the module Calculations in alphabetical order in the upper left had corner of the window. Note that the first statement has the potential to become an "If 1" condition (infinite loop) if there are no variables belonging to module Calculations (i.e. the ListVars function returns Invalid).

In the next example, the ListVars statement is returning an array of pointers to all variables beginning with the letter A, which in this case is two arrays, one statically declared (A1) and the other dynamically allocated (A2):

A1[2][3];
A2;
…
A2 = New(2, 3);
A1[0][0] = "zerozero";
A2[0][0] = "zerozero";
A1[1][0] = BuffStream("onezero");
A2[1][0] = BuffStream("onezero");
A1[1][1] = 11;
A2[1][1] = 11;
A1[1][2] = 12;
A2[1][2] = 12;
AFiles = ListVars(Self(), "A*", 0, 65535 { class limits },
                  0, 0 { all matches }, 0 { local vars },
                  8 { ptr to variables }, 1 { sort });

The array AFiles will now contain a list of pointers to the two arrays. To access the individual elements of array A1 and A2, each element of array AFiles must be de-referenced using the * character:

ElemA1_00 = (*AFiles[0])[0][0];
ElemA1_10 = (*AFiles[0])[1][0];
ElemA2_00 = (*AFiles[1])[0][0];

It is interesting to note that while this method may be used on either array, the following statement format will only set the variables to the expected value in the case of the statically declared array (A1):

ElemA1_00 = AFiles[0][0][0];


Ln

(Engine-Level Function)

Description: | Returns the natural logarithm (base e) of a value.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | Exp | Log | Pow
Format: | Ln(X)
Parameters: |
X
Required. Any numeric expression. The value must be strictly greater than 0 for the result to be valid.
Comments:

This is the inverse function to Exp.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

a = Exp(23);
b = Ln(a);

In this example, b will be equal to 23.


LoadDLL

(Engine-Level Function)

Description: | Loads a Microsoft Windows™ dynamic link library. 64-bit VTScada can load only 64-bit DLLs. 32-bit VTScada can load only 32-bit DLLs. VTScada Internet Clients (VICs) can load only 32-bit DLLs regardless of whether the VTScada server is 32-bit or 64-bit.
Returns: | DLL handle, numeric error code, or Invalid. See comments
Usage: | Steady State only.
Function Groups: | Compilation and On-Line Modifications, DLL, Software and Hardware
Related to: | DLL
Format: | LoadDLL(FileName[, VICRemoted])
Parameters: |
FileName

Required. Any text expression for the file name of the DLL to load. If the path is not specified, the standard Windows search pattern for DLLs will be used.

Windows applications that load DLL's without using a fully qualified pathname are vulnerable to DLL hijacking where an attacker can place a malicious copy of the DLL in the search path. Take care to specify the path in all cases.

VICRemoted
(Optional). A parameter that indicates whether the handle returned by LoadDLL will be remoted to the VIC.
If VICRemoted is a valid, non-zero, positive integer, and the LoadDLL function is being executed in a module instance that is within a VIC session, then all DLL calls using the handle that LoadDLL returns will be remoted to the VIC.
Whether the LoadDLL is in a VIC session is determined by the call tree from the module instance running the LoadDLL call. The root of the call tree must be an instance of BrowserClient. In practical terms, this means that you cannot expect session-aware DLL calls to function if you explicitly launch a module with a caller other than a module instance within the VIC session tree.
Defaults to 0 if not otherwise specified.
Comments:

Your DLL must return an object as a buffer in order for VTScada to be able to read it.

The return value is either the Windows™ handle of the new DLL (ValueType == 38), or on failure, the least significant 16-bits of operating system error code (ValueType < 3).
There is no dynamic download of a DLL to the VIC. DLLs must be manually installed on the VIC in either the system program folder (e.g. \Windows\System 32), or in a folder that is on the executable search path (the PATH environment variable).
LoadDLL is a steady-state statement. If it stops, all VALUEs holding a copy of the DLLHandle returned from the LoadDLL statement will be invalidated, and if there are no other LoadDLLs running for the same DLL, the DLL will be unloaded. (LoadDLL is not an expensive operation, but it is good programming not to do this very often.)

Note: LoadDLL will block the calling interpreter thread until the DLL loaded has completed on the VIC. This means that nothing else will execute on the VIC session thread until the DLL load is complete. This has the advantage (from the programmer's perspective) that the DLL handle returned is immediately ready for use. LoadDLL will return Invalid if there is a problem with the parameters, an integer error code if it cannot load the DLL, or a DLLHandle (ValueType ==38) if the load was successful. On failure, the return value will be the least significant 16-bits of operating system error code (ValueType < 3).

DLL calls do not need to consume the return value, or have no return value should be written as such (i.e. explicitly specify a return type of zero to indicate that there is no return value, or that the return value is irrelevant. If you specify other than zero for the return type, the DLL call will block the calling interpret thread until the VIC has run the DLL call and returned the value. This means that scripts that rely on synchronous DLL calls will still work, even with the DLL remoted, however, they will slow down. If you specify a return value type of zero, a remoted DLL call is dispatched to the VIC asynchronously (i.e. your interpreter thread will not block). If, for example, you have a sequence of DLL calls that will execute asynchronously, followed by one that is synchronous (because you want the return value), the calling interpreter thread will block only on the synchronous call. This may take a little longer because the order of the DLL calls is preserved on the VIC, and all the asynchronous ones will have to complete execution before the synchronous one can be executed. This is much quicker than using all synchronous calls, because the asynchronous ones are batched together and require no reply (other than a batch acknowledgment from the VIC), reducing comms latency.
DLL handles should not be declared as shared if they are going to be remoted. Shared DLLs will only be created once, and so will only operate on the server OR client, depending upon which one started them first.


LoadMIB

(Engine-Level Function)

Description: | Loads a specified MIB or set of MIBs and returns a dictionary describing the hierarchy of the MIBs.
Returns: | Dictionary
Usage: | Script
Function Groups: | File I/O, Software and Hardware
Related to: |
Format: | LoadMIB(MIBPath[, SubIDIndexing, LoadDescriptions, ErrorOut])
Parameters: |
MIBPath
Required. A path to any single MIB or a directory containing MIBs (possibly in further subdirectories). The returned MIB dictionary will also include those elements of the base MIBs found in <VTSInstallDir>\MIBS that are referenced in the MIB found in MIBPath. If Invalid, then the returned MIB dictionary will only include the base MIBS.
SubIDIndexing
An optional Boolean expression. If TRUE, then items in the returned MIB dictionary are keyed by numeric portion of the OID for that element. If FALSE, then the items are keyed by the label for the element. Defaults to TRUE.
LoadDescriptions
An optional Boolean expression. If TRUE, then the returned MIB dictionary will contain any description for the element (which may be lengthy). If FALSE, then no description is loaded. The default is TRUE.
ErrorOut
An optional variable into which any errors found in parsing the MIBs will be returned. Will take the form of a linked list of error message structures. The message structure will contain two fields: Error, containing the error text and Next containing the next error message structure, if any.
Comments:

VTScada supports only ASCII-encoded MIB files.

The return value is a Dictionary representing the MIBs specified. Depending on the actual element, the following members may be present

Label | The textual "name" of the element.
SubID | The portion of the OID corresponding to the element.
OID | The full OID for the element.
Desc | The textual description of the element (if the LoadDescriptions parameter is TRUE).
Syntax | The type of the element, e.g. "OCTET STRING" or "INTEGER" etc.
Type | The numeric type of the element, e.g. INTEGER is 3. The full list of possible types is: OTHER0 OBJID1 OCTETSTR2 INTEGER3 NETADDR4 IPADDR5 COUNTER6 GAUGE7 TIMETICKS8 OPAQUE9 NULL10 COUNTER6411 BITSTRING12 NSAPADDRESS 13 UINTEGER14 UNSIGNED3215 INTEGER3216 SIMPLE_LAST16 TRAPTYPE20 NOTIFTYPE21 OBJGROUP22 NOTIFGROUP23 MODID24 AGENTCAP25 MODCOMP26 OBJIDENTITY 27
Access | The permitted access to the element, One of "NoAccess", "ReadOnly", "WriteOnly", "ReadWrite", "Notify", "Create".
Enums | If the element provides an enumeration of values, then this member will be present and contain a linked list of enumeration structures, each structure has the following elements: Label - the label for the enumeration. Value - the value of the enumeration. Next - the next enumeration structure (if any) in the list.
Indexes | If the element is a table, this member lists the indexes of the items in the table. The member contains a linked list of index structures, each structure has the following elements Label - the label for the index. IsImplied . Next - the next index structure (if any) in the list
Children | If the element is not a leaf element this member will be present and will contain dictionaries for each of the elements child elements keyed by the child's OID SubIndex or Label as specified by the SubIDIndexing parameter.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


LoadModule

(Engine-Level Function)

Description: | Loads a module from its .RUN files and returns a pointer to that module.
Returns: | Module
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | Launch | Thread
Format: | LoadModule(FileName, Library, [ModuleName, LoadNow, AppGUID, Reserved, TestCodeLoad])
Parameters: |
FileName
Required. Any text expression giving the name of the .RUN file from which to load the module.
Library
Required. Any module value that indicates the library module to which the loaded module will belong.
ModuleName
An optional parameter that is the text expression giving the module's name. This name will then be associated with the module when it is displayed in certain situations, such as in the debugger and the module tree diagram. If this parameter is invalid, the module will appear as "System" when its name is displayed.
LoadNow
An optional parameter that is any logical expression. If true (non-0), the module and its entire sub-tree are loaded immediately. If false (0), the module and its subtree are loaded on demand. The default is false.
AppGUID
An optional parameter that should be included and hold the text GUID of the application when the LoadModule is loading an application.
Reserved
Should be set to Invalid if provided.
TestCodeLoad
An optional parameter that has been reserved for use by the Test Framework to indicate that the LoadModule is loading actual code to be run.
It can contain any Boolean expression that evaluates to TRUE to indicate that the code to run is being loaded.
Comments:

The return value is a pointer to the module. It can be used in a Launch or Thread statement.
The usage of the AppGUID parameter determines how the VTScada engine will treat the module load:

  • If AppGUID is Invalid, this is a "normal" load. No special processing is performed.
  • If AppGUID is a text GUID, the load is a load of the root module for the application. This causes the loading module to become the "namespace root" for the application.

Example:

If ! Valid(CompiledModule);
[
   ExpressionTemplateRUN = RunFileName( FindVariable( "ExpressionTemplate", Self, 0, 0));
   CompiledModule = LoadModule( ExpressionTemplateRUN,  ExpressionParentModule, "Compiled Expression");
]


LocalGroup

(Engine-Level Function)

Description | Returns an indication of whether the current Windows™ user is a member of the specified local group. LocalGroup interrogates only local groups, not domain groups.
Returns | Numeric
Usage | Script or steady state.
Function Groups | Security
Related to: |
Format: | LocalGroup(Group)
Parameters |
Group
Required. The group parameter, which is a value from 0 to 5. These values are defined in the following table:
Group | Local Group
0 | Administrators
1 | Backup Operators
2 | Guests
3 | Power Users
4 | Replicator
5 | Users
Comments This function returns an indication of whether the current Windows™ user is a member of the specified local group. Its return values are outlined in the following table:
Return Value | Information
0 | Not a member
1 | Is a member
2 | Not applicable

Invalid Parameter or internal error:

The user must sign out and sign in if a local group was changed for the change to be noticed by the LocalGroup function call. (This behavior is inherent to Windows and is not due to a VTScada feature or defect.)

Custom local groups (local groups that are not of type Administrators, Backup Operators, Guests, Power Users, Replicator or Users) cannot be interrogated by this function.


LocalScope

Description: Equivalent to Scope(Obj, Name, TRUE).
LocalScope is more clear, concise, and efficient. The Trihedral code style guidelines require LocalScope() as opposed to Scope(..., TRUE) for these reasons.
Returns: Reference
Usage: Script or steady state.
Function Groups: Basic Module
Related to: Variable | ScopeLocal | Scope
Format: LocalScope(Obj, Member)
Parameters:
Object
Required. Any expression for the object value where Member may be found.
Member
Required. Any text expression for the member name.
Comments:

This function is the same as the '.' operator, when the '.' operator is used between two operands. (Object.Member).

As an example, the LocalScope() function is useful for referencing a tag object where its name contains special characters or spaces:

TagObj = LocalScope(VTSDB, "R&R Level")

Example:

  TagName = "MyTag";
  TagObj  = LocalScope(VTSDB, TagName);

Returns a reference to the given tag object, found within the current module.

This is the equivalent to:

  VTSDB.MyTag


Locate

(Engine-Level Function)

Description: | Locates a text string, returning the offset of the first matching string in a buffer.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | CharCount | BuffWrite
Format: | Locate(Buffer, Offset, Search [, Method])
Parameters: |
Buffer
Required. The text expression to search.
Offset
Required. Any numeric expression giving the buffer offset (in characters or bytes), from which to start searching (i.e. to start at the beginning of the buffer, set this parameter to 0).
Search
Required. Any text expression for which to search.
Method
An optional numeric expression that controls how the Search parameter is interpreted as per the following table. The default value for Method is "0".
Method | Description
0 | Treat Search as the exact string for which to search (strstr).
1 | Treat Search as the case-insensitive string for which to search (stristr).
2 | Treat Search as a set of characters to match against (strpbrk).
3 | Treat Search as a case-insensitive set of characters to match against.
Comments: This function returns the buffer offset of the first string matching Search. If no match is found, or if the length of Search plus Offset is larger than the length of Buffer, -1 is returned. The return value could be used in the Offset parameter to perform successive searches.

This function can be used to perform fast table searches. Build a table in a text variable using BuffWrite. Make sure that all entries in the table are the same length. You can now use Locate to find the buffer offset of a matching text string.

Examples:

w = Locate("abcABCabc", 0, "bc");
x = Locate("abcABCabc", 2, "bc");
y = Locate("abcABCabc", 0, "Bc");
z = Locate("abcABCabc", 0, "X");

The values of w, x, y and z will be 1, 7, -1 and -1 respectively.


LocCapture

Description: | Capture Locator Input. This statement captures all subsequent input from the locator device and routes it to a specific window.
Returns: | TRUE if capturing. Invalid otherwise.
Usage: | Steady State only.
Function Groups: | Locator, Window
Related to: | WinXLoc | WinYLoc | XLoc | YLoc
Format: | LocCapture(Object, Enable)
Parameters: |
Object
Required. Any expression that returns an object value of a window or an object within a window whose coordinate system is to be used for locator coordinate reports until capture is released.
Enable
Required. Any logical expression. If true (non-0), the locator input will be captured by the window containing the module expressed by Object. If false (0), the locator capture is yielded.
Comments: This statement captures all locator input and routes it to the window containing the module instance that issued the LocCapture statement. This is most useful when there are child windows present that are graphically in front of the window with capture. With capture disabled (the normal condition), the coordinates returned to a WinXLoc(Self( )) would change from being relative to the parent window's coordinate origin to the child window's coordinate origin as the locator moved over the child window. With capture enabled, the coordinates would always be relative to the parent window's coordinate origin, no matter which window the locator was over.

Example:

LocCapture(Self(), 1);


LocSwitch

Description: | Returns the current status of the locator (mouse) buttons over the window which contains the LocSwitch statement.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Locator
Related to: | Click | SetXLoc | SetYLoc | Target | WinLocSwitch | XLoc | YLoc
Format: | LocSwitch()
Parameters: | None
Comments: The function has no parameters and therefore the empty parentheses following the function name are optional.
If the locator is not installed, or if it is over a window other than the one containing the module with the LocSwitch statement in it, the function returns 0.
Unlike the WinLocSwitch statement, this function is not triggered by mouse clicks in parent or child windows, only those occurring over the owning window. The return value has the following significance:
Return Value | Mouse Button(s) | No. of Clicks
0 | No buttons - |
1 | Right button | Single
2 | Middle button | Single
3 | Right & middle button | Single
4 | Left button | Single
5 | Left & right button | Single
6 | Left & middle | Single
7 | All three buttons | Single
8 | No buttons | -
9 | Right button | Double
10 | Middle button | Double
11 | Right & middle button | Double
12 | Left button | Double
13 | Left & right button | Double
14 | Left & middle | Double
15 | All three buttons | Double

Example:

If LocSwitch() == 4 NextState;

This statement causes a state change to NextState at the press of the left mouse button.


Log

(Engine-Level Function)

Description: | Returns the common logarithm (base 10) of a number.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | Exp | Ln | Pow
Format: | Log(X)
Parameters: |
X
Required. Any numeric expression. The value must be strictly greater than 0 for the result to be valid.
Comments:

The common antilogarithm can be found using the Pow function.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

n = Log(10000);

The variable n will be set to 4.


LogNTEvent

(Engine-Level Function)

Description | Logs events to the system event log.
Returns | Nothing
Usage | Script or steady state.
Function Groups | Log
Related to: |
Format: | LogNTEvent(Severity, Strings [, Source, Category, EventID, DataSize, Data, UNCServerName])
Parameters |
Severity
Required. A numeric code indicating the type of event to log. Severity can be one of:
Severity | Event
0 | Informational
1 | Warning
2 | Error
3 | Audit Success (Security Event)
4 | Audit Failure (Security Event)
String
Required. A single string or an array of strings to pass to the event as parameters.
Source
An optional parameter indicating the name of the source program. The default value for Source is "VTScada" (see comments section).
Category
An optional parameter indicating the numeric ID of event category. The default value for Category is "0", indicating "none" (see comments section).
EventID
An optional parameter indicating the numeric event code. The default value for EventID is "1001" (see comments section).
DataSize
An optional parameter indicating the size of binary data in bytes (see comments section).
Data
An optional parameter indicating the binary data to store with the event (see comments).
UNCServerName
An optional string specifying the UNC server name for Source (see comments).
Comments Event logs store important events for applications running on Windows. Because the logging function is designed to be general purpose, you must decide what information is appropriate to log. As a general rule, you should only log information that could be useful in diagnosing a hardware or software problem. The event logging facility is not intended to be used as a tracing tool.
Event logging consumes system resources such as disk space and processor time. The amount of disk space that an event log requires depends on how much information you choose to log. For this reason, it is important to log only essential information.
Following, are some Microsoft guidelines regarding the types of events you may wish to log for each severity

Informational Information events indicate significant successful operations that occur infrequently. It is not generally considered appropriate for an application to log an event each time it starts.

Warning Warning events indicate problems that are not immediately significant, but that may indicate conditions that could cause problems in the future. Generally, if an application can continue or recover from an event without loss of functionality or data, it can classify the event as a warning.

Error Error events indicate significant problems about which the user should know. Error events usually result in or from the loss of functionality or data.

Audit Failure When a security access attempt fails, it is considered an audit failure. A failed logon attempt is a failure audit event.

Audit Success When a security access attempt succeeds, then it is a success audit event. For example, a successful logon attempt is a success audit event.

For more information on NT Event Logging, please see the Microsoft MSDN documentation.

The only required parameters for LogNTEvent are the severity code (Severity) and the string or array of strings to log with the event (Strings)

You may optionally specify:
  • The application event Source (the default value is "VTScada").
  • The Category (numeric starting at "1", where "0" is the "none" category). The default is "0" (none).
  • The EventID (numeric, generally starting at 1000 or so to not conflict with the category numbers. The first and only defined EventID for source "VTScada" is "1001", which simply displays the passed-in string).
  • Data and Datasize (used to store binary data with the event). DataSize should be the size, in bytes, of the Data array. Data is any array of binary data to be stored along with the event. And
  • UNCServerName, which is the machine to which to log the event (the default is Invalid, which results in the event being logged on the local machine. Otherwise, you may specify the UNC name for the machine to which you would like the event logged ).

Note that specifying values other than the defaults for Source or EventID will result in the event log displaying the event improperly, unless a custom DLL is written to handle the case. However, this does not prevent the event from being logged, and a custom DLL can be added at a later time.

Example:

databuff = MakeBuff(10, 65);
textstring = "RTU 0015 is offline";
res = LogNTEvent(1,
                 textstrings,
                 Invalid {source},
                 Invalid {category},
                 Invalid {EventID},
                 10,
                 databuff);

This example will log a warning event under the source name "VTScada", with default category ("none"), and default event ID (1001). The details of the event will be the string "RTU 15 is offline, and attached to the event is 10 bytes of binary data - an array of 10 letter A's.


LogOff

Security Manager Module

Description | Logs the calling user session off.
Returns | Nothing
Usage | Script Only.
Related to: | AlternateLogoff | AlternateLogon | Authenticate | QuietLogon | UserCredChange | UserLogonDialog
Format: | \SecurityManager\LogOff()
Parameters | None
Comments | After logging off, the user session reverts to the Logged Off user.


LookUp

Description: | Looks up a value in an array and returns the index of the element containing that value. This function replaces the deprecated TextSearchList and SearchForListItem system modules.
Returns: | Numeric
Usage: | Script or Steady State
Function Groups: | Array
Related to: | AMax | AMin | ArrayDimensions | ArraySize | ArrayStart | AValid | Sort | Sum | TextSearch
Format: | Lookup(ArrayElem, N, Match [, CaseInsensitive])
Parameters: |
ArrayElem
Required. Any array element giving the starting index for the array operation. The index for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to compute. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Match
Required. Any value of any type to look for in the array. In the case of text, the search is case sensitive. If this value is invalid, the return value will also be invalid.
CaseInsensitive
An optional parameter that is any logical expression. If true (non-0) and the array contains text strings, the comparison will not be case sensitive. If false (0), the comparison will be case sensitive for text strings. The default is false.
Comments:

It is acceptable for the array to contain invalid values - these will be skipped over in the search for Match.
The return value will be invalid if the value of Match isn't found in the array.

Note that TextSearch should be used for large arrays due to its considerably faster search algorithm.

Example:

index = Lookup(labels[0], ArraySize(labels, 0), "off", 1);

This searches the array labels for a string of any case that matches the string "off". If a match is found, its value is assigned to index.


LValue

(Engine-Level Function)

Description: | Left-hand Side Value. This function returns an indication of whether its argument can be used on the left-hand side of an assignment.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Generic Math, Variable
Related to: |
Format: | LValue(Expr)
Parameters: |
Expr
Required. Any expression.
Comments: | This is a compiler function that returns 1 (true) if data can be stored into Expr (i.e. if it is a variable, etc.) and 0 otherwise.


M Functions

The sections that follow identify all VTScada functions beginning with "M".


MACID

(Engine-Level Function)

Description: | Enumerates and returns the MAC IDs registered on a particular machine.
Returns: | A 2D array containing network card names and MACIDs
Usage: | Script only.
Function Groups: | Software and Hardware
Related to: |
Format: | MACID()
Parameters: | None
Comments: MACIDs are unique to the NIC cards present within the machine but are NOT guaranteed to be unique for the virtual NICs generated for things like virtual machines or NIC emulations.
The name of the resource that generated the ID is provided with each ID to help sift out faux MACs. Note that Windows appears to always provide the real MACs first, and since almost all machines have a built-in NIC the first MAC can be assumed to be real.

Example:

MACIDInfo =  MACID();

On a machine, which has two network cards, MACIDInfo will have (for example):

MACIDInfo[0][0] == Realtek RTL8169/8110 Family PCI Gigabit Ethernet NIC (NDIS 6.0)
MACIDInfo[0][1] == Realtek PCIe GBE Family Controller
MACIDInfo[1][0] == a buffer containing the binary MAC address for the card named in MACIDInfo[0][0]
MACIDInfo[1][1] == a buffer containing the binary MAC address for the card named in MACIDInfo[0][1]


MakeAlarmRecordSpeechFile

(Alarm Manager module)

Description: | Creates a .wav file given an alarm record.
Returns: | Nothing. (Values returned via parameters) See descriptions in the parameter list.
Usage: | Script Only.
Function Groups: | Alarm, Speech and Sound
Related to: |
Format: | \AlarmManager.MakeAlarmRecordSpeechFile(AlarmRecord, pVoiceFilename, pVoiceLength, pVoiceReady[, Template, pError])
Parameters: |
AlarmRecord
Required An Alarm Record Structure to be used as the basis for voice file generation
pVoiceFilename
Required text. (Pointer) Holds the voice filename - Return variable.
pVoiceLength
Required numeric. (Pointer) Holds the length of the voice file in seconds - Return variable.
pVoiceReady
Required Boolean (Pointer) Set to TRUE when voice file generation is complete - Return variable.
Template
Optional text. Speech template. (See More Information... later in this topic)
pError
Optional Boolean (Pointer) Error pointer - Return variable.
Comments:

It also works out the length of the audio file. If the voice file fails to generate, then use the default voice file. The .wav file audibly speaks the alarm.

Wait for VoiceReady to be TRUE before playing VoiceFileName

Example:

Init [
  If 1 Wait;
  [
    \AlarmManager.MakeAlarmRecordSpeechFile(AlarmRecord, &VoiceFilename, &VoiceLength, &VoiceReady, "This alarm is in area %A" {Template}, &Error);
  ]
]

Wait [
  If VoiceReady PlayAlarm;

  If Error Done;
]

PlayAlarm [
  If TimeOut(1, VoiceLength + 0.5) Done;

  Play(VoiceFilename, 0b10011, TRUE);
]

Done [
  .
  .
  .
]

More Information: Using Alarm Templates or Control Strings with Tokens

Control the content of alarm messages by defining templates using application properties. If added to your Settings.Dynamic file, the templates are used by all alarms in the application. You can also add templates to Context tags for use by alarms within a site or other user-defined tag structure.

You can define a separate template for each of:

Template name | Used for...
Section 1: Alarm message templates
AlarmDialerTemplate | Telephone alarm descriptions. The initial greeting is not set by a template. You can set the spoken name in the greeting using the Alarms tab of the Edit Properties dialog.
AlarmEmailTemplate | Emailed alarm descriptions. Does not apply to SMS-ready emails.
AlarmPagerTemplate | Paged alarm descriptions.
AlarmSMSTemplate | Descriptions of alarms when sent by SMS message including SMS-ready email.
AlarmSpeechTemplate | Locally spoken alarm descriptions Select "Speak alarms..." in the Alarms tab of the Edit Properties dialog, then configure one or more AlarmPriority tags to speak the alarm instead of playing a tone.
Section 2: Alarm status templates. If DialOnClear is enabled, the status will be appended to the message. Does not apply to locally spoken alarms.
AlarmDialerStatusTemplate | Alarm status appended to telephone messages.
AlarmEmailStatusTemplate | Alarm status appended to emailed alarms.
AlarmPagerStatusTemplate | Alarm status appended to paged alarms.
AlarmSMSStatusTemplate | Alarm status appended to SMS alarms, including SMS-ready emails.
Section 3: Additional email and SMS templates
AlarmEmailAckTemplate | Message confirming alarm acknowledgment by email.
AlarmEmailAckSubjectTemplate | Subject line for alarm acknowledgment by email.
AlarmEmailAckCollisionTemplate | Emailed message to operators, informing them that the code they used acknowledged more than one alarm.
AlarmSMSAckTemplate | Message confirming alarm acknowledgment by text.
AlarmSMSAckCollisionTemplate | Text message to operators, informing them that the code they used acknowledged more than one alarm.

In addition to these, you may set the subject line for alarm emails using the property, AlarmEmailSubjectTemplate.

Format control strings take the form: TemplateName = control string,

The control string can be a combination of words and the following replaceable parameters. Note that the pause can add clarity to the message by separating words that might otherwise run together when spoken.

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Examples:

AlarmSpeechTemplate = %P alarm. %T, %M

Speaks (for example): "Critical alarm. 10:35 pm, Well level high"

AlarmSpeechTemplate = VTScada %P alarm in %A %W %M has reached %V at %T.

"VTScada critical alarm in zone one <pause> Holding tank level has reached eighty at eleven forty nine a. m.".


MakeArray

(System Library)

Description: | Create and initialize a one-dimensional array with one line of code.
Returns: | Array
Usage: | Script Only.
Function Groups: | Array
Related to: | New
Format: | \System.MakeArray(Elem1, Elem2, ...)
Parameters: |
Elem1, Elem2
Elements for the new array
Comments:

A maximum of 100 elements can be provided. Multi-dimensional arrays can be created by calling MakeArray() for each of the elements.

If the MakeArray() call is passed as a function argument, a temporary array is created and will be destroyed when the function ends.

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Examples:

Create an array of data type names.

DataTypes = \System.MakeArray("Byte", "Short", "Long", "Float", "String", "Octal", "Hex", "Unknown");

Create a temporary array for a single use in a function.

 SomeFunction(\System.MakeArray(1, 2, 3));
{ is equivalent to:                         }
 A = New(3);
 A[0] = 1;
 A[1] = 2;
 A[2] = 3;
 SomeFunction(A);
 A = Invalid;  { free up memory }


MakeBitmap

(Engine-Level Function)

Description: | Loads an image file of types BMP, EMF, WMF, APM, CUT, PCX, JPG, PNG, or TIF into memory and returns a handle to the result. Returns Invalid upon failure.
Returns: | Image handle
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | BitmapInfo | Crop | GUIBitmap | GUIButton | ImageArray | ImageParmSet| ImageSweep | ModifyBitmap
Format: | MakeBitmap(FileName [, Transparent1, Transparent2])
Parameters: |
FileName
Required. Any text expression giving the name of the file containing the image. A known path Known Path Aliases for File-Related Functions may be provided in the form, :{KnownPathAlias}.
Transparent1

An optional parameter giving the first color value to make transparent. Any of the following may be used:

  • a palette index VTScada Color Palette
  • a system color (constant)
  • an RGB string in the format, "<RRGGBB>"

If this value is negative 1 (-1), this parameter is ignored and no first color is made transparent.

Transparent2
An optional parameter giving the second color value to make transparent. Any of the following may be used:
  • a palette index color
  • a system color (constant)
  • an RGB string in the format, "<RRGGBB>"

If this value is negative 1 (-1), this parameter is ignored and no second color is made transparent.

Comments:

This function creates and returns an image value by loading an image from a file. All images are rendered in 32-bit color. An indexed color must translate into an exact 32-bit match to cause transparency. Colors may have their own transparency data via alpha values. Using an image value can improve speed and reduce memory requirements over using a file name directly in a function or statement.

EMF/WMF images will not display in the Anywhere Client.

Example:

  Image = MakeBitmap("C:\VTScada\VTS\Bitmaps\Arrows\Half rounded.wmf.png");

This will create an image value storing the image from the file "C:\VTScada\VTS\Bitmaps\Arrows\Half rounded.wmf.png".


MakeBuff

(Engine-Level Function)

Description: | Creates a buffer and returns its address.
Returns: | Address
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | BuffOrder | BuffRead | BuffStream | BuffToArray | BuffToParm | BuffToPointer | BuffWrite |
Format: | MakeBuff(Length, Value)
Parameters: |
Length
Required. Any numeric expression giving the length (number of bytes) of the buffer to create. This value must be between 0 and 0x7FFFFFFF.
Value
Required. Any numeric expression giving the initial value from the ASCII Character Set for every byte in the new buffer (see "ASCII Character Set"). It must be in the range 0 to 255.
Comments: This function can be used to create buffers for BuffWrite or similar functions that require an existing buffer. The return value is an address to a buffer of Length bytes, with each byte equal to Value. If the two parameters are integer constants and the buffer length is no more than 256 bytes, the compiler will convert this statement internally to a constant text string for speed at execution time.

The maximum buffer size is 0x7FFFFFFF (2, 147,483,648) characters. Any size larger than this will result in an invalid value.

Example:

buff1 = MakeBuff(5, 0x41);

This will cause buff1 to be assigned the address where the value "AAAAA" is stored.


MakeCall

Modem Manager

Description | This subroutine queues a call request.
Returns | Numeric
Related to: | CancelCall
Format: | \ModemManager\MakeCall(PhoneNumber, Baud, DataBits, StopBits, Parity [, CallTime, Tag, Workstation, MediaMode, Voice, UseLocal, Area, UserData, Service, Attempts, QTime, ID, InitString, UserName, Password, Domain, PPPFlags]);
Usage | Script Only.
Parameters |
PhoneNumber
Any text expression for the phone number to be called. If required, this may be the canonical international format.
Baud
Any numeric expression giving the baud rate to be used on the modem connection. The baud rate must be in the range of 0 to 115200, and must divide evenly into 115200 with no more than a 2.5% error. The value of "0" has special significance. This corresponds to the maximum baud rate available for the particular device. See Baud Rate.
DataBits
Any numeric expression giving the number of data bits per character to be used on the modem connection. DataBits must be 5, 6, 7, or 8.
StopBits
Any numeric expression giving the number of stop bits per character to be used on the modem connection. StopBits must be 1 or 2.
Parity
Any numeric expression giving the parity checking to be used on the modem connection. This may be one of:
Value | Parity
0 | No parity
1 | Odd parity
2 | Even parity
3 | 0 Stick (space parity)
4 | 1 Stick (mark parity)
CallTime
A signed, numeric expression representing the time in seconds, relative to the current time, at which the call should be made. A negative value means that the call should be started as soon as possible. However, the call will be queued behind calls that specified a more negative time. If the value CurrentTime() is used here, then the call will go to the head of the queue. The default value for this parameter is "0" (i.e. now).
Tag
Any expression resolvable to the name of the tag making the call. The default is Caller(Self())\Name. Tag must be resolvable in the scope of Code, and must resolve to an object. That object must contain a variable called DataPort that will be used by the Modem Manager for call control and progress purposes.
Workstation
Any text expression identifying the computer on whose behalf the call is to be made. The call progress and results will be delivered to the DataPort variable in the object Code\Tag running in the application identified by the GUID of the application that originally called MakeCall() on the workstation identified by the Workstation parameter (but see also the Service parameter). This parameter defaults to the value \RPCManager\WkstnName on the machine that calls MakeCall().
MediaMode
A valid numeric expression being a valid MediaMode constant. Use this when you require particular media properties (e.g. Voice) of a modem, and not all modems in the pool posses those properties. The default value selects any available modem.
Voice
If making an outgoing voice call, then this parameter specifies the text GUID of the voice to be used by the Text-to-Speech engine.
UseLocal
Normally, calls are queued for dispatch via one of the pool modems, which may be on a completely different machine. If you wish to use a local modem (e.g. a USB or PC Card modem on a laptop computer), then this parameter should be set to a numeric, non-zero value. It is necessary to also configure at least one modem as a local modem.
Area
The area parameter of modem tags may be used to create functional groupings. If this parameter is specified to MakeCall(), then only a modem that has the same area parameter will be used to make the call. If there is no such modem configured in the system, then the call will be unceremoniously canceled.
UserData
Opaque user-supplied data that is passed back to the user when the ModemControl plug-in is called.
Service
The parameter Workstation explains the normal rules for delivery of the call results. If this Service parameter is given, and is the text name of a driver service, then the call results will be delivered to the current server for that service, rather than the machine identified by the Workstation parameter.
Attempts
Count of attempts at this connection. This parameter should be INVALID or 0 initially.
QTime
The time that the call was originally requested. This parameter should be INVALID initially. It is used on subsequent attempts.
ID
If valid, then this is the Server's call ID.
InitString
An optional text value that will be sent to the modem as the final part of initializing it for use, just before it dials out. The string should include any terminating characters that the modem will require to complete the string, such as "\r".
UserName
An optional text value providing the user name for remote authentication of a PPP connection.
Password
An optional text value providing the password for remote authentication of a PPP connection.
Domain
The domain name, used for remote authentication of a PPP connection.
PPPFlags
An optional numeric value indicating parameters of the PPP connection. See PPPDial for a list of values and their meanings.
Comments Returns one if the call is successfully queued. If a zero is returned, the call has not been queued, and will not be queued.
As soon as MakeCall() is called, the tag's DataPort variable is set to a valid value. This value will be changed many times subsequently, but will remain valid until the call is completed or canceled.

Shortly after calling MakeCall(), DataPort will become a pointer to an array. This indicates that the call is queued. When call setup is initiated, DataPort will become an integer value >= "0". Should the call fail in any way, then DataPort will become negative.

If the call setup completes successfully, then DataPort will change to a Stream value (ValueType(DataPort)==8). The call requestor may now read and write to that stream to communicate with the called party. To hang-up the call, call CloseStream(). If the other end hangs up or the call fails, then DataPort will go invalid.

If the call setup fails, then the call will be retried according to the configured retry settings. If the call is retried, then DataPort will again become an array pointer while the call is queued. DataPort will not go Invalid until the call is abandoned.
If the originator requires that a call be canceled before it is completed, then the CancelCall() method should be used. If the originator changes the DataPort value, the effect is undefined.

Related information:

Refer to Call Progress and Error Codes. in the VTScada Programmer's Guide.


MakeDAG

(Engine-Level Function)

Description: | Constructs a Directed Acyclic Graph (DAG - an internal function representation).
Warning: | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications
Related to: | SelectDAG
Format: | MakeDag(Opcode, Parms)
Parameters: |
Opcode
Required. Any numeric expression for the opcode of the DAG to construct.
Parms
Required. Any numeric expression that indicates the number of additional parameters to be included in the new DAG. This is normally 0, except in cases such as a new FWrite DAG.
Comments: This function constructs a Directed Acyclic Graph (an internal function representation). This may be used to build up a function or statement without compiling. This is only intended to be used to define a new VTScada code syntax.


MakeDictionary

(VTS Library)

Description: | Create and initialize a dictionary with one line of code.
Returns: | Dictionary
Usage: | Script Only.
Function Groups: | Dictionary, Variable
Related to: | Dictionary | ArrayToDictionary
Format: | \System.MakeDictionary(Key1, Value1, ...)
Parameters: |
Key1
The first key of the dictionary
Value1
Value for that key
Comments:

Up to 50 key + value pairs can be provided as parameters.

If the MakeDictionary() call is passed as a function argument, a temporary dictionary is created and will be destroyed when the function ends.

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Examples:

 SomeFunction(\System.MakeDictionary("Key1", 1,
                                     "Key2", 2,
                                     "Key3", 3));
{ is equivalent to:  }
 D = Dictionary();
 D["Key1"] = 1;
 D["Key2"] = 2;
 D["Key3"] = 3;
 SomeFunction(D);
 D = Invalid;  { free up memory }


MakeEditor

(Engine-Level Function)

Description: | Returns an editor value which is used by an editor
Returns: | Editor
Usage: | Script Only.
Function Groups: | Editor
Related to: | AddEditorText | CurrentLine | Editor | ForceEvent | GoToOffset | SetEditMode
Format: | MakeEditor()
Parameters: | None
Comments: | This function is used by all of the functions that require an editor.

Example:

  aNewEditor = MakeEditor();
  AddEditorText(aNewEditor, "The start of my editor");

These functions will create an editor called aNewEditor and put the above text string in it.


MakeIPMask

Description: | Make an IP MaskSet that can then be passed into CheckIPMask and IPMaskToText, by returning text holding the encoded binary IP address and mask. Works for IPv4 and IPv6.
Returns: | MaskSet value
Usage: | Script Only.
Function Groups: | Network and Workstation
Related to: | CheckIPMask | IPMaskToText
Format: | MakeIPMask((OldMaskSet, IPAddress [, Mask])
Parameters: |

OldMaskSet

Required. The result of previous calls to this method, or Invalid when starting afresh.

IPAddress

Required. This can be a single IP address, in which case the Mask parameter will be used if valid, OR an IP subnet address. IPv4 and IPv6 both have their subnet representations and either is acceptable here, as are IPv4-mapped IPv6 addresses.
Mask
Optional text. An optional IP mask, used as an alternative way of specifying a subnet range, in conjunction with a non-CIDR IPv4 or IPv6 second parameter.
Comments:

For advanced use only.

As a general process, use MakeIPMask to generate a MaskSet that can then be passed into CheckIPMask and IPMaskToText.

Use to generate a value that can then be fed into CheckIPMask to verify if an IP address is in the set of subnet ranges specified by the mask set built by this function.

In typical usage, OldMaskSet would initially be Invalid and a new MaskSet created as a result of the first call. Each time a successful call is made, the MaskSet grows by a fixed size (32 bytes), being 16 bytes of binary IP address 16 bytes of matching mask bits, held in a binary buffer.

IPv4 addresses/masks are expanded into IPv4-mapped IPv6 addresses to make them the same size.

No ordering or coalescence is done to reduce the mask to the minimum set needed.

An Invalid IPAddress parameter simply results in the first parameter (mask set) being returned unchanged. A bad one has no effect. This also means that this statement can be used to check the syntactic validity of an IP address or CIDR notation by passing Invalid for the OldMaskSet and checking the return value is valid.


MakeNonPersistent

(Engine-Level Function)

Description: | Takes a variable and makes it not persistent.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | AddVariable | FindVariable | MakeNonShared | MakePersistent | MakeShared | PersistentSize
Format: | MakeNonPersistent(Variable)
Parameters: |
Variable
Required. Any expression for the variable value. This value is typically returned from a FindVariable or an AddVariable call.
Comments: A persistent variable saves its current value on disk and is automatically restored upon restarting the module. This function will also make the variable not shared. See MakeNonShared for the results of making the variable a non-shared value. The variable will be removed from the persistent (.VAL) file as well.


MakeNonShared

(Engine-Level Function)

Description: | Takes a shared variable and makes it not shared.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | AddVariable | FindVariable | MakeNonPersistent | MakePersistent | MakeShared
Format: | MakeNonShared(Variable)
Parameters: |
Variable
Required. Any expression for the variable value. This value is typically returned from a FindVariable or an AddVariable call.
Comments: A shared variable has the same value for all instances of its owning module. An instance will be created for the variable in every running instance where the variable is used. The instance will be initialized with the value of the shared variable.
If Variable is a module value, it will be unaffected.


MakeParmPhrase

(Function Library)

Description: | Returns a \ParmPhrase structure given a phrase key and parameters.
Returns: | ParmPhrase structure
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | GetParmPhrase
Format: | \MakeParmPhrase(PhraseID, P1, P2, P3, P4, P5, P6, P7, P8, P9, P10])
Parameters: |
PhraseID
Required text. The key for a parameterized phrase.
P1
Required text. By definition, a parameterized phrase requires at least one parameter.
P2 - P10
Optional text. A parameterized phrase can have up to 10 parameters.
Comments:

MakeParmPhrase returns a structure of parameterized phrase information for use in tag parameters.

It must be used when creating non-optimized tag parameter expressions for properties that take a PhraseID as a parameter (for example, Description or Units)

For optimized parameter expressions, \ParmPhrase() is the preferred method of building a parameterized phrase structure and should be used instead. Refer to Phrases in tag parameters

Do not use for text drawn on a page. Instead, use \GetParmPhrase(...) or \GetPhrase(\MakeParmPhrase(...)) as applicable.

As a specialized use-case, MakeParmPhrase also supports the use of translation dictionaries for any of its parameters. Use the following information only in the rare case that a standard .csv file of static translations is not suitable.

Translation dictionaries should take the following form, which is used in place of a PhraseKey:

System.MakeDictionary("en", "hello", "fr", "bonjour", "es", "hola");

MakeParmPhrase will then return the translation corresponding to the user's current language. If the dictionary does not include a translation for the user's current language but does for the default language, then the default will be returned. If that also does not exist, then it returns "Missing translation" (language dependent).

Note that the phrase may not update dynamically when the content for a given key in the dictionary changes.

Translation dictionaries should not be used in most applications.

Example:

\MakeParmPhrase("MyTwoParmLabel", ..\Description, " amperage")


MakePersistent

(Engine-Level Function)

Description: | Takes a variable and makes it persistent (static).
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | AddVariable | FindVariable | MakeNonPersistent | MakeNonShared | MakeShared | PersistentSize
Format: | MakePersistent(Variable, Size)
Parameters: |
Variable
Required. Any expression for the variable value. This value is typically returned from a FindVariable or an AddVariable call.
Size
Required. Any numeric expression giving the number of bytes of storage allocated in the .VAL persistent variable file for this variable.
For array types, set this to the byte size of the largest array element (normally 8 bytes for numeric values). For arrays containing text, enter the character length of the longest string element.
Comments: Because a variable can not be persistent without being shared as well it will make Variable shared. (see MakeShared for the results of this). If the variable is already persistent,. there will be no change made to the variable. In particular, the persistent size of the variable will not change.


MakeSelfSignedCertificate

Description: | Creates a new self-signed certificate.
Returns: | Buffer. The SHA1 thumbprint of the new certificate.
Usage: | Script Only.
Function Groups: | Certificates
Related to: | AddCertificate | CheckCertificateChain | FindCertificate | GetCertificateInfo | ListCertificates | RemoveCertificate | SetCertificateProperty
Format: | MakeSelfSignedCertificate(MachineStore, StoreName, Subject [, KeyAlgorithm, HashAlgorithm, ValidityPeriod, KeyStrength, KeyUsage, EKU, SAN])
Parameters: |

MachineStore

Required Boolean. If TRUE (non-zero) attempts to find the certificate in a store in the Local Computer certificate hive. If FALSE (zero) attempts to find a certificate in a store in the Current User certificate hive.
StoreName
Required text. The name of the store in which to search for the certificate.
Subject
Required text. The subject that will be written into the certificate.
KeyAlgorithm
Optional text. The name of the algorithm used with the public / private key pair and to sign the certificate.
HashAlgorithm
Optional text. The name of the algorithm used to hash the certificate prior to signing.
ValidityPeriod
Optional numeric. The number of days for which the new certificate will be valid.
KeyStrength
Optional numeric. The key strength in bits.
KeyUsage
Optional numeric. The permitted usages for the private / public key pair.
EKU
Optional text or array of text values. The Extended Key Usages permitted for the private / public key pair.
SAN
Optional text or array of text values. A set of Subject Alternative Names to be written into the certificate.
Comments

This statement creates a self-signed certificate. A self-signed certificate is one that has no chain of trust and, hence, to be trusted requires to be installed in a trusted root store or (better) the software that uses it is explicitly allowed to trust it.

The issuer name written into the self-signed certificate is the same as the Common Name field in the Subject parameter.

The Subject parameter has a familiar form to many other certificate generation packages. It is a sequence of:

<identifier>=<value>

separated by semi-colons, where identifier is one of the RFC 5280/X.520-specified fields. For example:

CN=LPoint;O=Trihedral;OU=Engineering

defining the Common Name as "LPoint", the Organization as "Trihedral" and the Organizational Unit as "Engineering".

The KeyAlgorithm and HashAlgorithm are the Microsoft Cryptography Next Generation (CNG) algorithm names. For example "RSA" is a valid KeyAlgorithm and "SHA256" is a valid HashAlgorithm.

The ValidityPeriod is expressed in days from the time of certificate creation.

KeyStrength specifies the length of the key, in bits. For RSA this should be at least 2048 bits. Larger sizes are permitted but not commonly used at present.

KeyUsage is a set of bit values that specify the intended usages for the private / public key pair. These are defined as:

  Constant #KeyUsageSignature        = 0x80;
  Constant #KeyUsageNonRepudiation   = 0x40;
  Constant #KeyUsageKeyEncipherment  = 0x20;
  Constant #KeyUsageDataEncipherment = 0x10;
  Constant #KeyUsageKeyAgreement     = 0x08;
  Constant #KeyUsageCertSign         = 0x04;
  Constant #KeyUsageCRLSign          = 0x02;
  Constant #KeyEncipherOnly          = 0x01;

These bits are combined for use with a certificate. RFC 5280 describes these bits and their purpose. For example, a combination of 0xF0 is typically used for client authentication purposes.

EKU is a text value or an array of text values that define Extended Key Usages (sometimes called Enhanced Key Usages) that the keys are intended for. The text values are Object Identifiers (OIDs). Commonly used ones include:

Server authentication	1.3.6.1.5.5.7.3.1
Client authentication	1.3.6.1.5.5.7.3.2
Code signing	        1.3.6.1.5.5.7.3.3

SAN is a text value or an array of text values that define Subject Alternative Names to be written into the certificate. These are specified in the form:

<identifier>=<value>

where <Identifier> is one of "DNS" or "URL". Support for other types may be added in the future. Value is a string representing the value.

Example:

SANArray = New(2);
    SANArray[0] = "URL=urn:localhost:Trihedral:VTScada:MyApplication";
    SANArray[1] = "DNS=demoserver.trihedral.com";
    NewCertThumbprint = MakeSelfsignedCertificate(FALSE,
                                                  "My",
                                                  "CN=LPoint;O=Trihedral"
                                                  "RSA",
                                                  "SHA256",
                                                  90,
                                                  2048,
                                                  #KeyUsageSignature +
                                                  #KeyUsageNonRepudiation +
                                                  #KeyUsageKeyEncipherment +
                                                  #KeyUsageDataEncipherment,
                                                  "1.3.6.1.5.5.7.3.2",
                                                  SANArray);

This will create a self-signed certificate in the current user’s Personal store with a 2048-bit RSA private/public key pair, hashed with a SHA256 algorithm (and then signed RSA key). The certificate name will be LPoint, the organization name Trihedral and it will be valid for 90 days from today. The public key is intended for client authentication and should only be used for signing, non-repudiation, key and enciphering data. The SAN will hold one URL and one DNS entry.


MakeShared

(Engine-Level Function)

Description: | Takes a variable and makes it shared.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | AddVariable | FindVariable | MakeNonPersistent | MakeNonShared | MakePersistent
Format: | MakeShared(Variable)
Parameters: |
Variable
Required. Any expression for the variable value. This value is typically returned from a FindVariable or an AddVariable call.
Comments: There will only be one instance of the variable's value so anywhere the variable is set it will set it for all uses. Care must be exercised that by making a variable shared you do not create a "double set" on the variable (i.e. setting it in two different statements at the same time). If you do the result will be that the variable will become invalid. For more information on double sets see the "Variable" section in Chapter 3.
If Variable is a module value, it will be unaffected.


MakeValidFName

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Create a file name that is guaranteed to contain only legal characters.
Returns: | Text
Usage: | Script Only.
Function Groups: | Text
Related to: |
Format: | \MakeValidFName(FileName)
Parameters: |
FileName
Required. Any string to be turned into a valid file name.
Comments:

Any characters in FileName that cannot be used in a file name will be traded for a unique, two-character set: the Delete character (7F) followed by an integer. The integer increments with each successive replacement.
It is important that the parameter FileName not contain the Delete character.

This function was designed to deal with the situation of saving (new format) tags to a database for later retrieval.

Defined at the VTScada level - not available to script applications.

Examples:

NewName = "VTSDB\Widget.SRC";
NewName = MakeValidFName(NewName);

NewName will now contain "VTSDB⌂0Widget.SRC"


MapDraw

Description: | Draws a "slippy" map, showing a list of site tags as pins on that map.
Returns: | Object reference
Usage: | Steady State only. (called from a GUITransform)
Function Groups: | Graphics
Related to: | SlippyMapRemoteTileSource1 | GetSessionContainers
Format: | \MapDraw([Latitude, Longitude, Sites, InitZoom, MinZoom, MaxZoom])
Parameters: |
Latitude
Optional numeric expression specifying the Y-axis center of the map. If not provided, the calculated center of all sites to be drawn on the map will be used.
Longitude
Optional numeric expression specifying the X-axis center of the map. If not provided, the calculated center of all sites to be drawn on the map will be used. If there are no sites to display on the map, the initial display will be centered on North America.
Sites
Optional array of sites to display. Each site item in the array must be a structure, containing valid pointers for latitude, longitude and a callback object. See comments.
InitZoom
Optional numeric expression, specifying the initial zoom factor to use for the map. Ranges from 2 to 18. If not specified, the maximum zoom level (smallest area) that encompasses all the sites will be used.
MinZoom
Optional numeric expression, setting the lowest permitted zoom level (corresponding to the set of the largest tiles to be used, in the sense of maximum displayed area per tile).
MaxZoom
Optional numeric expression, setting the greatest permitted zoom level (corresponding to the set of the smallest tiles to be used, in the sense of minimum displayed area per tile).
UserInput
Optional Boolean. Set FALSE to disable user input. Affects only the map, not pins on the map. Defaults to TRUE.
DisableTools

Optional bit-wise value controlling which tools are disabled. Default to zero - all tools enabled.

(See: Bitwise Parameters & Operations)

Bit # | Tool disabled
0 | Zoom tools
1 | Reset tool
2 | Style tool
Reserved
Do not use.
Comments:

The zoom factor corresponds to the tile set that should be used within the area of the map. To zoom in or zoom out means switching to a tile set that shows a greater or lesser amount of detail, and therefore a corresponding smaller or larger area of geography.

Tiles are downloaded on request from the url specified in the property, SlippyMapRemoteTileSource1, found in Setup.INI file

If a sites array to be used, it is created by first making a call to GetSessionContainers. This returns an array of tag names to be used. This is used as the basis for a new array that contains structures for each site, build using the site's latitude, longitude and a call-back to a method for drawing the site. The structure of the array is defined as follows:

{***** Structure that holds information for drawing a Site on a map *****}
MapSite Struct [
   PtrLatitude  { Pointer to site's latitude in decimal degrees };
   PtrLongitude { Pointer to site's longitude in decimal degrees };
   Callback  { Scope where Draw(MapObj, Lat, Lon) is called to draw marker on map};
];

The following example shows how this would be done.

Examples:

Init [
  If 1 Main;
  [
    Sites = New(2);
    SiteObj = Scope(\Code, "MySite1");
    Sites[0] = MapSite(&(SiteObj\Latitude), &(SiteObj\Longitude), SiteObj);
    SiteObj = Scope(\Code, "MySite2");
    Sites[1] = MapSite(&(SiteObj\Latitude), &(SiteObj\Longitude), SiteObj);
  ]
]

Main [
  GUITransform(0, 400, 600, 0,
               1, 1, 1, 1, 1,
               0, 0, 1, 0,
               0, 0, 0,
               \MapDraw(Invalid, Invalid, Sites));
]

SiteObj is expected to have a Draw module. Draw is called by MapDraw to draw this site at its location on the map. Draw is called with the following parameters:

MapObj

Object value of MapDraw in which various helper functions can be called.

PtrLatitude

A pointer to the site’s latitude value.

PtrLongitude

A pointer to the site’s longitude value.

PtrHide

A pointer to a Boolean value. When true, the result should be that Draw will hide its graphic objects.

PtrZoomLevel

A pointer to the map's current zoom level, ranging from zero to twenty where zero shows the entire world.

Draw should use the helper functions LonToX() and LatToY(), to position its graphics at the correct x,y location on the map. For example:

X = MapObj\LonToX(PtrLongitude);
Y = MapObj\LatToY(PtrLatitude);


MatchKeys

(Engine-Level Function)

Description: | Returns true if the specified keyboard keys have been pressed in the sequence given.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Keyboard
Related to: | MakeBuff | KeyCount |Keys
Format: | MatchKeys(Enable, Keys)
Parameters: |
Enable

Required. Any numeric expression that enables the function. Testing of keyboard input is enabled when this parameter is true (i.e. not 0). If it is 0 (false), then the function's value is false.

In addition, the Enable parameter controls the type of comparison done. If the Enable is 1, a case-sensitive match is made. If the Enable is 2, then the match is not case-sensitive.

(Any non-zero value other than 2 will cause a case-sensitive match. The use of 1 and 2 is recommended for clarity.)

Keys

Required. A text expression giving the key sequence to watch for. The case of individual letters may be significant, depending on the Enable parameter.

To generate extended keys that are not already available as constants defined in the system layer, use MakeBuff to turn the character code(s) into a text expression. For example:

    PageUp    = Concat(MakeBuff(1, 253), MakeBuff(1, 0x49));
    F2        = Concat(MakeBuff(1,253), MakeBuff(1,60));
    F3        = Concat(MakeBuff(1,253), MakeBuff(1,61));
    CtrlZKey  = MakeBuff(1, 26);
Comments:

This function should be used in a window or page module to monitor key strokes.

The Enable parameter is a status expression controlling the comparison. The comparison starts after the Enable becomes true. If the Enable becomes false, the function's value becomes false and the comparison starts at the beginning of the Keys string again after the Enable becomes true. This feature is useful for resetting the MatchKeys function after an action using the function's result has been performed.
The MatchKeys function is also reset automatically when it occurs in an action trigger that becomes true.
The function's result is automatically set to 0 (false) when the state containing the function is entered. After the function becomes true, it remains true as long as the state does not change and the Enable remains true.
Any key sequence may be used for the Keys parameters including the function keys. Note that the MatchKeys function is case sensitive (upper and lower case letters are treated as different characters) when the Enable is an odd number. Often only one key is included in the Keys string. Several keys may be used in the Keys string and function as a password. The keys typed are not displayed on the screen by this function. Several MatchKeys functions may be active at any time, each comparing the keyboard input against their own Keys parameter.

If watching for function keys, you are advised not to override the behavior of F1.

Buffer constants for ASCII codes
Name of Constant | Contents | Description
BS | MakeBuff(1, 8) | Backspace key
CR | MakeBuff(1, 13) | Carriage return
CRLF | Concat(CR, LF) | CR/LF pair
ESC | MakeBuff(1, 27) | Escape key
FF | MakeBuff(1,12) | Form feed
LF | MakeBuff(1, 10) | Line feed
NULL | MakeBuff(1, 0) | Null byte
TAB | MakeBuff(1, 9) | Tab key
CtrlBraceOpen | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBC)) | Ctrl and [
CtrlBraceClose | Concat(MakeBuff(1, 253), MakeBuff(1, 0x39)) | Ctrl and ]
UpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x48)) | Up arrow key
DownArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x50)) | Down arrow key
LeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4B)) | Left arrow key
RightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4D)) | Right arrow key
AltLeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9B)) | Alt and left arrow
AltRightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9D)) | Alt and right arrow
SUpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB8)) | Shift and up arrow
SDownArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xC0)) | Shift and down arrow
PageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0x49)) | Page up key
PageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0x51)) | Page down key
HomeKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x47)) | Home key
EndKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4F)) | End key
DeleteKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x53)) | Delete key
SPageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB9)) | Shift and page up
SPageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0xC1)) | Shift and page down
SHomeKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB7)) | Shift and home
SEndKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBF)) | Shift and end
CtrlPageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0x84)) | Ctrl and page up
CtrlPageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0x76)) | Ctrl and page down
CtrlHome | Concat(MakeBuff(1, 253), MakeBuff(1, 0x77)) | Ctrl and home
CtrlEnd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x75)) | Ctrl and end
CtrlBKey | MakeBuff(1, 2) | Ctrl and B
CtrlCKey | MakeBuff(1, 3) | Ctrl and C
CtrlDKey | MakeBuff(1, 4) | Ctrl and D
CtrlIKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB5)) | Ctrl and I
CtrlMKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBA)) | Ctrl and M
CtrlPKey | MakeBuff(1, 16) | Ctrl and P
CtrlSKey | MakeBuff(1, 19) | Ctrl and S
CtrlTKey | MakeBuff(1, 20) | Ctrl and T
CtrlUKey | MakeBuff(1, 21) | Ctrl and U
CtrlVKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x06)) | Ctrl and V
CtrlXKey | MakeBuff(1, 24) | Ctrl and X
CtrlYKey | MakeBuff(1, 25) | Ctrl and Y
CtrlZKey | MakeBuff(1, 26) | Ctrl and Z
Buffer constants for non-ASCII codes
AltEnter | Concat(MakeBuff(1, 253), MakeBuff(1, 0x32)) | Alt and Enter
AltUpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x98)) | Alt and up arrow
SLeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBB)) | Shift and left arrow
SRightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBD)) | Shift and right arrow
F2 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3C)) | F2
F3 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3D)) | F3
F4 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3E)) | F4
F5 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3F)) | F5
ShiftF2 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x55)) | Shift and F2
ShiftF3 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x56)) | Shift and F3
ShiftF4 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x57)) | Shift and F4
ShiftF5 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x58)) | Shift and F5
STab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x09)) | Shift and Tab
CtrlTab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x94)) | Ctrl and Tab
CtrlShiftTab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9C)) | Ctrl, Shift and Tab
CtrlMinus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2A)) | Ctrl and -
CtrlPlus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2D)) | Ctrl and +
CtrlShiftMinus | MakeBuff(1, 0x1F) | Ctrl, Shift and -
CtrlShiftPlus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2E)) | Ctrl, Shift and +
CtrlNumAdd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x90)) | Ctrl and Numpad +
CtrlNumSubtract | Concat(MakeBuff(1, 253), MakeBuff(1, 0x8E)) | Ctrl and Numpad -
CtrlNumMultiply | Concat(MakeBuff(1, 253), MakeBuff(1, 0x36)) | Ctrl and Numpad *
CtrlShiftNumAdd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9A)) | Ctrl, Shift & Numpad +
CtrlShiftNumSubtract | Concat(MakeBuff(1, 253), MakeBuff(1, 0x96)) | Ctrl, Shift & Numpad -
AltNumMultiply | Concat(MakeBuff(1, 253), MakeBuff(1, 0x37)) | Alt & Numpad*
WinContext | Concat(MakeBuff(1, 253), MakeBuff(1, 0xE8)) | Context Menu Key
CtrlTilde | Concat(MakeBuff(1, 253), MakeBuff(1, 0x26)) | Ctrl and ~
CtrlShiftBraceOpen | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBE)) | Ctrl, Shift and [
CtrlShiftBraceClose | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3A)) | Ctrl, Shift and ]
Ctrl0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x72)) | Ctrl and 0
CtrlNum0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x92)) | Ctrl and Numpad0
Alt0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x81)) | Alt and 0
AltNum0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9E)) | Alt and Numpad0
CtrlShiftNKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x08)) | Ctrl, Shift and N
CtrlShiftVKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x05)) | Ctrl, Shift and V

Comparisons exceeding 256 bytes (source string) is not supported and will return FALSE. Note that this is not the number of characters but the underlying bytes. Characters can be between 1 to 4 bytes since UTF-8 is supported.

Multi-character String comparison is not supported on VIC.

Example:

If MatchKeys(2,"Y");
[
  ...
]

When the letter "Y" is typed on the keyboard, regardless of case, the action will trigger, execute its script, and reset the MatchKeys function to wait until "Y" is typed again.

Related information:

Defined Constants for Buffers

Latching and Resetting Functions


Max

(Engine-Level Function)

Description: | Returns the maximum of a group of parameters.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | Abs | AMax | AMin | Limit | Min
Format: | Max(Parm1, Parm2 [, Parm3, ...])
Parameters: |
Parm1, Parm2, Parm3, ...
Required. Any number of parameters giving any numeric expressions, from which a maximum value will be selected.
Comments: The order of the values is irrelevant. If any of the parameters is invalid, the return value is invalid also.

Examples:

p = Max(2, 3, 2.9, -3);
q = Max(3, 2);
r = Max(Invalid, 6);

The values of p, q, and r will be 3, 3 and Invalid respectively.


MCSInstance

(Engine-Level Function)

Description: | Module Calling Structure Instance. This function returns the object value of a module called by another module.
Warning: | This function should be used by advanced users only.
Returns: | Object value
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | MCSMod
Format: | MCSInstance(Code)
Parameters: |
Code
Required. The code value in which the module call is embedded.

Example:

startedInstance = MCSInstance(mcs);

This makes startedInstance an object value that points to a running instance of a module started by the module given by mcs.

Related Functions:


MCSMod

(Engine-Level Function)

Description | Module Calling Structure Module. This function returns the module value from a line of code that calls that particular module.
Returns | Module
Usage | Script or steady state.
Function Groups | Compilation and On-Line Modifications, Advanced Module
Related to: | MCSInstance
Format: | MCSMod(Code)
Parameters |
Code
Required. The code value in which the module call is embedded.
Comments This is an advanced function for use in writing and implementing the main toolbar.


Mean

(Engine-Level Function)

Description | Returns the mean (average) of a portion of a numerical array.
Returns | Numeric
Usage | Script or steady state.
Function Groups | Array, Generic Math
Related to: | AMax | AMin | AValid | FiltHigh | FiltLow | FitOffset | FitSlope | SDev | Sum | Variance
Format: | Mean(ArrayStart, N)
Parameters |
ArrayStart
Required. Any numeric array element giving the starting element of the array. The index for the array may be any numeric expression and specifies the starting point for the array search. If processing a multi-dimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to use starting at the element given by the first parameter. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Comments Invalid array elements are not included as part of the calculation, unless there are no valid numerical array elements in the specified range, in which case the function returns invalid. Invalid is also returned if either parameter is invalid, or if the number of elements to use is 0.

Example:

x[0] = Invalid;
x[1] = Invalid;
x[2] = Invalid;
x[3] = 1;
x[4] = 2;
x[5] = 1;
x[6] = 2;
avg = Mean(x[0], 7);

The value of avg will be set to 1.5.


MemIn

(Engine-Level Function)

Deprecated. This function relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.

Description: | Returns a byte, word, or longword of RAM memory.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | Memory I/O
Related to: | CopyIn | CopyOut | MemOut
Format: | MemIn(Address, Type)
Parameters: |
Address
Required. Any numeric expression which gives the RAM address to read. This may be specified using the @ operator.
Type
Required. Any numeric expression giving the type of read to perform.
Type | Read Type
0 | Read 8 bit byte
1 | Read 16 bit word
2 | Read 32 bit long word
Comments: This function requires that the VTSIO driver be installed.
This is a high priority function. If used in a statement or action trigger, it will be evaluated at a very fast rate. MemIn should be used sparingly to avoid reduced system performance.
In certain cases, the registry may need to be modified to allow access to the memory location.


Memory

(Engine-Level Function)

Description: | Returns the amount of memory that VTScada has acquired from the OS heap for internal use.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Memory I/O
Related to: | Memory MemTrace
Format: | Memory([Reserved, JustThisBubble])
Parameters: |
Reserved
Leave blank or set to Invalid if using the second parameter.
JustThisBubble
Optional Boolean. Set to TRUE to get just the memory use for the current bubble. FALSE (the default) gets the global memory use across all of VTScada.
Comments:

The value returned is not the total amount of memory used by the VTScada process as it does not include other allocations that may be made from the OS heap.

While the value reported when JustThisBubble is TRUE is accurate up to that instant, the global memory use value is only updated internally approximately every second.

Example:

If ! Valid(memUsed);
[
  memUsed = Memory();
]


MemOut

(Engine-Level Function)

Deprecated. This function relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.

Description: | Writes a byte, word, or longword of RAM memory.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Memory I/O
Related to: | CopyIn | CopyOut | MemIn
Format: | MemOut(Address, Type, Value)
Parameters: |
Address
Required. Any numeric expression that gives the RAM address to write. This may be specified using the @ operator.
Type
Required. Any numeric expression giving the type of write:
Type | Write Type
0 | Write 8 bit byte
1 | Write 16 bit word
2 | Write 32 bit long word
Value: Required. Any numeric expression giving the value to write.
Comments: This function requires that the VTSIO driver be installed.
In certain cases, the registry may need to be modified to allow access to the memory location.


MemTrace

(Engine-Level Function)

Description: | Writes memory allocation information to a file.
Returns: | Boolean indication of success or failure.
Usage: | Script Only.
Function Groups: | Memory I/O functions
Related to: | Memory
Format: | MemTrace(Tracefile, Lowstamp, Highstamp, Lowsize, Highsize, LowID, HighID, Done[, AppendMode])
Parameters: |
Tracefile
Required. Any text expression for the name of the file to generate.
Lowstamp
Required. The low timestamp range specifier. Defaults to 0 if Invalid.
Highstamp
Required. The high timestamp range specifier. Defaults to 1E99 if Invalid.
Lowsize
Required. The low size range specifier. Defaults to 0 if Invalid.
Highsize
Required. The low size range specifier. Defaults to 0xFFFFFFFF if Invalid.
LowID
Required. The low caller id range specifier. Defaults to 0x0000 if Invalid.
HighID
Required. The high caller id range specifier. Defaults to 4096 if Invalid.
Done
Required. A return variable, which will be set TRUE after the memory trace file has been written. MemTrace is a threaded function.
AppendMode
Optional Boolean. When TRUE, causes the function to skip writing the output file's header and appends to the output file rather than rewriting it. Defaults to FALSE.
Comments:

If the file was generated, TRUE is returned, otherwise, FALSE is returned.

This function traces only the memory used by the bubble that calls the MemTrace function. In most cases, this will be the top-level System bubble.

If you want to trace memory across multiple bubbles, call MemTrace with ApendMode FALSE in the first bubble, and then call it in each other bubble (one at a time) with the parameter set to TRUE.


Merge

Description: | Applies a set of changes (the output of a Diff operation) to a buffer.
Returns: | Buffer
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | Combine | Diff | Merge2
Format: | Merge(SourceBuff, DiffBuff)
Parameters: |
SourceBuff
Required. The buffer or stream to be modified.
DiffBuff
Required. The buffer or stream containing formatted instructions for how to modify the source buffer.
Comments:

The source buffer must be identical to the origin buffer used to create the Diff buffer in the first place. This operation cannot fail, but will produce unexpected results if either input buffer is corrupt or if the wrong origin buffer is used. This function is synchronous and returns the result of the operation.

The operations in the DiffBuff are formatted as follows:

  • The low 31 bits of the first four bytes hold the length of the data portion, measured in bytes.
  • The highest bit of those first four bytes will be a 0 to indicate that this is a delete operation or a 1 to indicate that this is an add operation.
  • The next four bytes hold the offset into the source buffer where the operation should take place.
  • The final "length" bytes (where length was defined in the first 31 bits) hold the data to be added in the case that this is an add operation.

"DiffBuff" could be the result from the Diff function.

Merge assumes that the diffs in DiffBuff are ordered and correct, hence does no checking for offsets outside SourceBuff, etc. It is the responsibility of the caller to get it right.

Merge relies on "Modify" operations being ordered as an "Add" in a particular location followed by a "Delete" in the same location. This is the ordering generated by the Diff function. Reversing the order will cause undesirable results.

Examples:


Merge2

(System Library)

Description: | Attempts to apply two different Diff buffers to a single origin buffer.
Returns: | Result buffer.
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | Combine | Diff | Merge
Format: | System.Merge2()
Parameters: |
Source
Required. Buffer or stream to be modified .
Diff1
Required. Buffer or stream containing the first set of Diffs for modifying "SourceBuff"
Diff2
Required.Buffer or stream containing the second set of Diffs for modifying "SourceBuff"
pConflict1
Optional, pointer to a dictionary of conflicting records of Diff1
pConflict2
Optional, pointer to a dictionary of conflicting records of Diff2
pDiffStream
Optional, pointer to a stream contains all non-conflicting records from Diff1 and Diff2.
Comments:

Similar to Combine, but without automatic conflict resolution or change priority.

Both Diff buffers must have started from the same origin and that origin must be the one provided. It is assumed that the Diff buffers represent different changes to the same origin.
This function fails if the changes cannot be applied cleanly, without interfering or conflicting with one another. A conflict is defined as any of the following:

  • Two additions occurring at the same location and adding different data.
  • One deletion and one addition where the addition occurs within the range of the deletion.

Information describing the nature of the failure is provided to the fourth and fifth parameters. The sixth parameter is provided with a combined Diff buffer containing all of the changes that did not conflict.

Rules applied to detect conflicts:

1. Both operations delete and overlapping deletes are combined to create a composite delete. If the composite delete conflicts with a subsequent add, all of the constituent deletes of the composite delete are also marked as being conflicts.

2. Both are addition operations. Conflict can only occur at the offset.

  • If additions occur at different offsets then there is no Conflict.
  • If additions occur at the same offset with the same data, then there is no conflict.
  • If additions occur at the same offset, but adding different data then there is a conflict.

3. One operation adds and the other deletes.

  • If addition occurs within the range of the deletion operation then there is a conflict.
  • If addition occurs outside of the range of the deletion operation, then there is no conflict.

When two records are determined to be conflicting based on the previous rules, we need to go through all previously saved records marked #Pending to move them to the conflicting dictionary.

If there are conflicts between the two Diffs, the subroutine returns conflict information, whereas if there are none then the two diffs are simultaneously applied to the source buffer.

This operation is synchronous, the result buffer is returned by the call.

Examples:


MetaData

(Engine-Level Function)

Depending on the context in which it is used, this command has two different purposes.

Description: | If used with a variable which is not a dictionary, this command attaches meta data to that variable, thereby creating a dictionary object. The primary purpose in this case is to provide a means of associating extended data with a variable. If used with a variable which is a dictionary, this command will return the value associated with the specified key.
Returns: | Varies - see description
Usage: | Script or steady state.
Function Groups: | Dictionary, Variable
Related to: | Dictionary | RootValue
Format: | MetaData( dictionary, key, [case sensitive] );
Parameters: |
Dictionary
Required. A variable name that will become the dictionary.
Key

Required. A text value. Integers may be used, but will be cast to text.

This will become the first key within the dictionary.

Case

An optional Boolean, controlling whether the dictionary will use case sensitive keys or non case sensitive.

TRUE (default) defines a non-case sensitive key.

FALSE defines case sensitive.

Example 1: Adding meta data to a variable

X  =  42;    { X is an integer variable with the value 42 }
MetaData(X, "A",  1 ) = 10;

X becomes a case sensitive dictionary having a root value that is the integer 42 and possessing one key, "A", that has the value 10.

Example 2: Retrieving the meta data from a dictionary

X  =  Dictionary(5);
X["A"]  =  42;
Y = MetaData(X, "A");

Y will now hold the integer 42, being the value stored with the key "A" in the dictionary X.

Related information:

Dictionaries


Min

(Engine-Level Function)

Description: | Returns the minimum of a group of parameters.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | Abs | AMax | AMin| Limit | Max
Format: | Min(Parm1, Parm2 [, Parm3, ...])
Parameters: |
Parm1, Parm2, Parm3, ...
Required. Any number of parameters, giving any numeric expressions, from which a minimum value will be selected.
Comments: The order of the values is irrelevant. If any of the parameters is invalid, the return value is invalid also.

Examples:

p = Min(62, 3, 2, 2.01);
q = Min(3, 2);
r = Min(Invalid, 6);

The values of p, q, and r will be 2, 2 and invalid respectively.


MkDir

(Engine-Level Function)

Description: | Create a new folder (directory) and returns its own error code.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | File I/O
Related to: | RmDir
Format: | MkDir(Name)
Parameters: |
Name
Required. Any text expression which is the full path name of the directory to create. A known path Known Path Aliases for File-Related Functions for File-Related Functions may be provided in the form, :{KnownPathAlias}.
Comments: The return value is as follows
Return Value | Meaning
0 | Directory successfully created
1 | Directory already exists
2 | Creation failed
3 | Bad path

In VTS version 7.0 and later, MkDir can now create directories recursively, so that

MkDir("C:\one\two\three");

will create directory one (if it does not already exist), then create directory two (if it does not already exist), and then finally create directory three (if it does not already exist).

If Name is given as a relative path, it will be created below the VTScada installation directory.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example 1:

  err = MkDir("C:\SAMPLE");

This creates the directory Sample on drive C.

Example 2:

err = MkDir("SAMPLE");

This creates the directory C:\VTScada\SAMPLE


ModemCount

(Engine-Level Function)

Description | Returns the number of data modems configured and operational in the system.
Returns | Numeric
Usage | Script or steady state.
Function Groups | Modem
Related to: | ModemDial | ModemList | ModemMedia | ModemStream | ModemTransfer
Format: | ModemCount()
Parameters | None


ModemDev

(Engine-Level Function)

Description: | Obtains the identifier for a modem sub-device. (In order to use the audio capabilities of a voice modem, the device identifier for the wave output device is required.)
Returns: | See description
Usage: | Script Only.
Function Groups: | Modem
Related to: | ModemMedia | Sound
Format: | ModemDev(ModemStream, DeviceName )
Parameters: |
ModemStream
Required. The connected modem stream (returned from a ModemStream or ModemDial function call).
DeviceName
Required. A text value describing the device whose identifier is required. Only "wave/out" is supported.
Comments: When called with a DeviceName of "wave/out", this function returns a value suitable for use with the Sound function.


ModemDial

(Engine-Level Function)

Description: | Dials and attempts to connect to a remote modem and returns the modem stream or an error code.
Returns: | Modem Stream or Error Code
Usage: | Script Only.
Function Groups: | Modem
Related to: | ModemCount | ModemList | ModemMedia | ModemStream | ModemTransfer
Format: | ModemDial(Modem, PhoneNumber, ReceiveLen, TransmitLen, MinBaud, MaxBaud, DataBits, StopBits, Parity, XonXOff [, MediaMode, Timeout, InitString])
Parameters: |
Modem
Required. Either a numeric expression giving the modem number between 1 and the number of modems in the system (the return from ModemCount), or a modem stream opened via the ModemStream function.
PhoneNumber
Required. Any text expression specifying the phone number to dial. It can contain any of the special dialing characters that WindowsÔ allows. If this parameter is invalid a pass-through connection will be obtained.
ReceiveLen
Required. Any numeric expression giving the size of the receive buffer for the serial stream in bytes. ReceiveLen must be in the range 2 to 32 766. If more bytes are received than can fit in the receive buffer before the application removes them, the additional data will be lost.
TransmitLen
Required. Any numeric expression giving the size of the transmit buffer for the serial stream in bytes. TransmitLen must be in the range 2 to 32 766. The buffer must be large enough to hold the maximum number of bytes pending transmission at any instance.
MinBaud
Required. Any numeric expression giving the minimum baud rate which will be acceptable on the modem connection. The baud rate at which the connection is made may actually be higher than this value but may not exceed MaxBaud. The baud rate must be in the range 0 to 115,200, and must divide evenly into 115,200 with no more than 2.5% error. The value of 0 has special significance. This corresponds to the maximum baud rate available for the particular device.
MaxBaud
Required. Any numeric expression giving the maximum baud rate which will be acceptable on the modem connection. The baud rate at which the connection is made may actually be lower than this value but may not be less than MinBaud. The baud rate must be in the range 0 to 115,200, and must divide evenly into 115,200 with no more than 2.5% error. The value of 0 has special significance. This corresponds to the maximum baud rate available for the particular device.
DataBits
Required. Any numeric expression giving the number of data bits per character. DataBits must be 5, 6, 7, or 8.
StopBits
Required. Any numeric expression giving the number of stop bits per character. StopBits must be 1 or 2.
Parity
Required. Any numeric expression giving the parity checking to use:
Parity | Checking Type
0 | No parity
1 | dd parity
2 | Even parity
3 | Stick (space parity)
4 | 1 Stick (mark parity)
XOnXOff
Required. Any logical expression. If true (non-0) software flow control is to be used. If false (0) it is not. Because software flow control is only supported for DigiBoards, this should normally be set to 0.
MediaMode
An optional numeric expression, specifying the desired media mode for the call. See ModemMedia for a description of valid values and their meanings.
Timeout
An optional parameter that should be set to the number of seconds after the completion of dialing that the call should be allowed to wait before it is automatically abandoned as NOANSWER. A value of 0 indicates that the application does not desire automatic call abandonment. The default value of Timeout is 0.
InitString
An optional text value that will be sent to the modem as the final part of initializing it for use, just before it dials out. The string should include any terminating characters that the modem will require to complete the string, such as "\r".
Comments: The return value for this function will be one of the following integer values until the modem has a valid connection with a remote modem:
Return | Status
0 | Idle (no connection), waiting for a call
1 | Starting outbound call
2 | Outgoing call request accepted by modem
3 | Dial tone on outbound call
4 | Dialing outbound call
5 | Remote phone ringing on outbound call
6 | Remote phone busy on outbound call
7 | Connected (should not be seen since a stream value will be returned at this point)
8 | Another application is handling the call after a ModemTransfer
9 | Incoming call detected. The modem is being called, but has not yet answered. Changes to 11 when the modem answers.
10 | The modem is temporarily unavailable. Occurs when trying to place an outgoing call and either the modem is still initializing or another TAPI aware application has the modem.
11 | The modem has answered a call. Modem training in progress. Normally followed by a valid stream connection. If an error has occurred, the return values will be one of the following error codes:
Error code | Meaning
-1 | The (numeric) first parameter to the function is out of range
-2 | No dial tone detected on outbound call
-3 | Remote phone busy on outbound call
-4 | No answer on outbound call
-5 | Remote hung up on incoming call
-6 | Modem unavailable
-7 | Other call termination condition

Errors equal to or less than -101 correspond to the Microsoft Telephony Interface (TAPI) errors (which are normally numbered from 1). Specific errors that may be encountered are:

-101 TAPI error code 1 (LINEERR_ALLOCATED) | the serial port is in exclusive use by some other process
-112 TAPI error code 12 (LINEERR_INCOMPATIBLEAPIVERSION) | the system does not have the required version of telephony support (TAPI 2.0 required)
-115 TAPI error code 15 (LINEERR_INUSE) | the line device is in use and cannot currently be configured, nor can it allow a party to be added or a call to be answered, placed or transferred
-147 TAPI error code 47 (LINEERR_INVALMEDIAMODE) | the requested media mode could not be accommodated (e.g. voice call request on a non-voice modem).
-167 TAPI error code 67 (LINEERR_NODEVICE) | the specified device identifier, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized. Alternately, the line device has no associated device for the given device class
-168 TAPI error code 68 (LINEERR_NODRIVER) | either TAPIAddr.DLL could not be located or the telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. Use the Telephony Control Panel to correct the problem
-169 TAPI error code 69 (LINEERR_NOMEM) | insufficient memory to perform the operation, or unable to lock memory
-175 TAPI error code 75 (LINEERR_RESOURCEUNAVAIL ) | insufficient resources to complete the operation (e.g. a line cannot be opened due to a dynamic resource over commitment). Also occurs where a modem is being used by a non-TAPI application

If the PhoneNumber parameter is invalid, a pass-through connection will be obtained. This allows the application to send and receive raw modem commands as if it had exclusive access to the serial port. The difference is that pass-through allows the modem to be shared with other TAPI applications. If the modem is not currently involved in a call then a stream value is returned immediately and may be used to read/write modem commands and data. If the modem is currently involved in a call then the return value will be 10 (modem temporarily unavailable) - wait for a period and then retry.

While a pass-through connection is open, the application has complete control over the modem. If an incoming call arrives, then a notification will be given by the modem (usually "\r\nRING\r\n"). If handling of incoming calls is not required and some other TAPI application does require call handling (e.g. RAS) then the stream should be closed immediately after a ring is detected. Handing off the call using ModemTransfer will not work, because as far as TAPI is concerned there is no call in progress at that stage.

When a modem is in voice mode it is not able to detect call progress accurately. The Microsoft Telephony Service still returns call progress indications but they are fallible. For example, call connected state is returned immediately dialing is complete.

It is not possible to change the media mode of a call after the ModemDial function has been invoked.

Due to operating system restrictions audio mode is only available with Windows 98/ME/2000.


ModemDigits

(Engine-Level Function)

Description: | Controls the receipt of DTMF digits entered from the keypad of a telephone engaged on a voice call via a voice modem.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Modem
Related to: | GetStreamLength | ModemDial | ModemMedia | ModemStream | SRead
Format: | ModemDigits(ModemStream, Enable )
Parameters: |
ModemStream
Required. The connected modem stream (returned from a ModemStream or ModemDial function call).
Enable
Required. Any logical value that is "true" (non-zero) to enable digit monitoring, and "false" (zero) to cancel digit monitoring.
Comments: After digit monitoring is enabled, any digits detected by the modem will appear as text characters (0123456789#*) in the ModemStream. The presence of these characters can be determined by using the GetStreamLength function and they can be read using the SRead function.


ModemList

(Engine-Level Function)

Description: Returns a list of the modems in the system. This function should be used to determine the correct parameter for the ModemStream or ModemDial functions.
Returns: Array
Usage: Script only.
Function Groups: Modem
Related to: ModemCount | ModemDial | ModemMedia | ModemStream | ModemTransfer
Format: ModemList()
Parameters: None
Comments: The return value is a two-dimensional array with each row storing the information for a single modem (i.e. ArraySize(ReturnValue, 0) = = ModemCount( ) ). There are four columns per row as follows
Column # | Information
0 | The operating system enumeration for this device
1 | Comport identifier (e.g. "COM1")
2 | 'Friendly name" of the modem (e.g. "Standard Modem")
3 | MediaMode. Bit significant value indicating the capabilities of the modem. Please refer to ModemMedia for a description of valid values and their meanings.
4 | If set to1, the modem is controlled by the Trihedral TSP. The Trihedral TSP is to be preferred over other options.

The Microsoft Telephony Interface (TAPI) enumerates a number of devices - not just modems. This function enumerates only the data/voice modems into a compact list. The ordering of this list should not be relied upon as it may change due to system hardware changes.

To use this function:

  1. Call the ModemList function
  2. Iterate through the resulting array, choosing a modem by its 'Friendly Name' or by its 'MediaMode' capabilities.
  3. Add one to the array index and use the resulting value as the first parameter to ModemStream or ModemDial.


ModemMedia

(Engine-Level Function)

Description: | Enables you to determine the media mode of a serial stream open on a modem, and change it if necessary (for example, if you require the ability to be able to handle both incoming voice mode and data mode calls).
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Modem
Related to: | ModemDev | ModemDial | ModemDigits | ModemList | ModemStream | ModemTransfer | Sound
Format: | ModemMedia(ModemStream [, MediaMode])
Parameters: |
ModemStream
Required. The connected modem stream (returned from a ModemStream function call) that is to be handed off to another interested application.
MediaMode
Optional. Specifies the desired media mode for the call. Valid values are bit significant, and more than one may be specified.
MediaMode | Meaning | Comments
2 | Unknown | Is set whenever more than one of the other values is set.
4 | Interactive Voice | A voice mode call using the modem microphone/speaker.
8 | Automated Voice | For simulated speech and wave files. Allows DTMF digit detection.
16 | Datamodem | For data calls.
32 | Group 3 Fax | For FAX calls.
Comments: MediaMode is important when handling multi-mode calls. It may be specified when dialing a call (ModemDial) or preparing a modem for answering incoming calls (ModemStream), and is a consideration before handing off a call to another service (ModemTransfer). If more than one MediaMode bit is set, then the call type is undetermined, and Unknown (2) should also be set.
It is not possible to change the media mode to a mode other than those specified when the ModemStream was created. If the requested Media change cannot be implemented, the function will return Invalid. The function will also return Invalid if there is no active call in progress on ModemStream.

If Interactive Voice (4), or Automated Voice (8) is specified, then the modem will be initialized in voice mode. On outgoing calls, this has the effect that progress indication is unreliable - the call will be reported as connected as soon as dialing completes. This is a limitation of analog voice modems.
Changes to media mode may not happen instantly. For example, changing a call from voice mode to data mode initiates the modem training sequence that may take several seconds to complete. The return value of the ModemMedia function indicates the current state, and so can be used to determine when the change has completed.

Example:

As an example, the following steps would be required to provide an automated alarm reporting system that hands off incoming data calls to the system RAS service.

  1. Enumerate the available modems with ModemList and choose one with DataModem and Automated Voice facilities.
  2. Use ModemStream to prepare the modem for incoming calls, specifying Datamodem, Automated Voice, and Unknown as the media mode.
  3. When a call arrives, it will initially be answered in voice mode. Use ModemDigits to set up digit monitoring.
  4. Use ModemDev to obtain the handle for the wave/out device. This handle can then be used with the Sound function to play a wave file, or with the SpeechSpeak function to play simulated speech. A typical initial function would be to request that the caller press a digit key on the phone.
  5. If, for example, no DTMF digit is received within a few seconds, then it may be assumed that this is actually a data call. In this case, ModemMedia should be called to set the Datamodem media mode. If the return value is valid, then the mode should be polled approximately every 0.5 second, until ModemMedia returns a value that no longer contains Automated Voice. The ModemTransfer function may now be called to transfer the call, and the modem stream can be closed.


ModemStream

(Engine-Level Function)

Description: | Open a serial stream on a modem and returns its status (prior to the connection being made), a modem stream (after the connection has been established), or an error code.
Returns: | Varies - see description
Usage: | Script Only.
Function Groups: | Modem
Related to: | ModemCount | ModemDial | ModemList | ModemMedia | ModemTransfer
Format: | ModemStream(Modem [, RingCount, ReceiveLen, TransmitLen, MediaMode])
Parameters: |
Modem
Required. Any numeric expression giving the modem number between 1 and the number of modems in the system (the return from ModemCount).
RingCount
An optional parameter that is any numeric expression designating the number of rings after which the modem should be answered. If this parameter is 0 the modem will not answer the call. The default is 1.
ReceiveLen
An optional parameter that is any numeric expression giving the size of the receive buffer for the serial stream in bytes. ReceiveLen must be in the range 2 to 32 766. The default length is 1024. If more bytes are received than can fit in the receive buffer before the application removes them, the additional data will be lost.
TransmitLen
An optional parameter that is any numeric expression giving the size of the transmit buffer for the serial stream in bytes. TransmitLen must be in the range 2 to 32 766. The default length is 1024. The buffer must be large enough to hold the maximum number of bytes pending transmission at any instance.
MediaMode
An optional numeric expression, specifying the desired media mode for the call. See ModemMedia for a description of valid values and their meanings.
Comments Typically, this function is used to prepare a modem for the receipt of incoming calls. Use the ModemDial function to make outgoing calls.
The return value for this function will be one of the following integer values until the modem has a valid connection with a remote modem
Return Value | Status
0 | Idle (no connection), waiting for a call
1 | Starting outbound call
2 | Outgoing call request accepted by modem
3 | Dial tone on outbound call
4 | Dialing outbound call
5 | Remote phone ringing on outbound call
6 | Remote phone busy on outbound call
7 | Connected (should not be seen since a stream value will be returned at this point)
8 | Another application is handling the call after a ModemTransfer
9 | Incoming call detected. The modem is being called, but has not yet answered. Changes to 11 when the modem answers
10 | The modem is temporarily unavailable. Occurs when trying to place an outgoing call and either the modem is still initializing or another TAPI aware application has the modem
11 | The modem has answered a call. Modem training in progress. Normally followed by a valid stream connection

If an error has occurred, the return values will be one of the following error codes:

Error Code | Error
-1 | The (numeric) first parameter to the function is out of range
-2 | No dial tone detected on outbound call
-3 | Remote phone busy on outbound call
-4 | No answer on outbound call
-5 | Remote hung up on incoming call
-6 | Modem unavailable
-7 | Other call termination condition

Errors equal to or less than -101 correspond to the Microsoft Telephony Interface (TAPI) errors (which are normally numbered from 1). Specific errors which may be encountered are:

-101 TAPI error code 1 (LINEERR_ALLOCATED) | the serial port is in exclusive use by some other process
-112 TAPI error code 12 (LINEERR_INCOMPATIBLEAPIVERSION) | the system does not have the required version of telephony support (TAPI 2.0 required)
-115 TAPI error code 15 (LINEERR_INUSE) | the line device is in use and cannot currently be configured, nor can it allow a party to be added or a call to be answered, placed or transferred
-147 TAPI error code 47 (LINEERR_INVALMEDIAMODE) | the requested media mode could not be accommodated (e.g. voice call request on a non voice modem).
-167 TAPI error code 67 (LINEERR_NODEVICE) | the specified device identifier, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized. Alternately, the line device has no associated device for the given device class
-168 TAPI error code 68 (LINEERR_NODRIVER) | either TAPIAddr.DLL could not be located or the telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. Use the Telephony Control Panel to correct the problem
-169 TAPI error code 69 (LINEERR_NOMEM) | insufficient memory to perform the operation, or unable to lock memory
-175 TAPI error code 75 (LINEERR_RESOURCEUNAVAIL) | insufficient resources to complete the operation (e.g. a line cannot be opened due to a dynamic resource over commitment). Also occurs where a modem is being used by a non-TAPI application. It is not possible to change the media mode of a call during a call.


ModemTransfer

(Engine-Level Function)

Description: | Transfers a modem call to another application and returns an indication of success.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Modem
Related to: | ModemCount | ModemDial | ModemList | ModemMedia | ModemStream
Format: | ModemTransfer(ModemStream )
Parameters: |
ModemStream
Required. The connected modem stream (returned from a ModemStream function call) that is to be handed off to another interested application.
Comments: The call is transferred to the next highest priority application interested in the call. When the transfer is made, the stream value will be set to 8. This function will return true (1) to indicate a successful transfer or false (0) if the transfer was unsuccessful.
Passing an incoming call to a RAS would be a common use for this function.


ModifyAccount

Security Manager Module

Description: | Used to change any of the elements of an account definition that may be modified.
Returns: | Object value
Usage: | Script Only.
Related to: | AddAccount | DeleteAccount
Format: | \SecurityManager\ModifyAccount (NewAccountData [, PtrReturnCode, HaveLock]);
Parameters: |
NewAccountData
Required. An AccountData structure, a single dimension array of AccountData structures or a dictionary of AccountData structures containing the data to modify in each account.
PtrReturnCode
Optional. A pointer to a value that will contain one of the defined result codes at the conclusion of the operation.
HaveLock
Optional. A Boolean value that indicates whether the working copy lock is held by the calling code. Default FALSE.
Comments:

To use this API, the calling code must be running in a security session that has Manager privilege.

Modifying an account is an asynchronous operation. If the asynchronous operation was not attempted, due to detection of an error, the return value will be Invalid. If the asynchronous operation is attempted, the return value will be an object value. The object value will become Invalid when the asynchronous operation completes. At that time (or when the method returns Invalid), the value addressed by PtrReturnCode can be examined to determine the status of the operation. The contents of the value addressed by PtrReturnCode is undefined until the method returns Invalid.

A single account can be modified by supplying a single AccountData structure in NewAccountData. Multiple accounts can be modified in one operation by providing a single dimension array or dictionary of AccountData structures in NewAccountData.
The result code returned in the value addressed by PtrReturnCode will be a scalar value if a single structure was supplied in NewAccountData. If an array of structures or a dictionary of structures was supplied, a single dimension array of the same size as NewAccountData will be returned in the value addressed by PtrReturnCode, each element containing the result code for the corresponding NewAccountData element.

Modifying an account requires a working copy write lock. If such a lock is held by the calling code, the HaveLock parameter must be set to TRUE. Otherwise omit this parameter or set it to FALSE. If the calling code holds a read lock on the working copy, this must be released before ModifyAccount can complete its operation.
The AccountData structure(s) provided must have the AccountID member set to an existing account ID.

Any other member of the structure can be Invalid, in which case no change is made to that member of the account record. Only valid members cause modification.
If the password is being changed, the new password must meet application password strength settings. On return the Password member is not erased. It is highly recommended that calling code be careful to ensure that unencrypted passwords are destroyed as soon as possible after completion of this operation.


ModifyBitmap

(Engine-Level Function)

Description: | Reads an existing image handle and produces a new one with modifications. The original image is not altered. Returns invalid upon failure.
Returns: | Image
Function Groups: | Graphics
Usage: | Script or steady state.
Related to: | Crop | GUIBitmap | GUIButton | ImageArray | ImageSweep | MakeBitmap
Format: | ModifyBitmap(Handle[, Reflect, Hue, Saturation, Lightness, Transparency, Contrast, ColorizeHue, ColorizeSaturation, AntiAlias, ScalarColor, Rotation] )
Parameters: |
Handle
Required. The image handle to copy and modify.
Reflect
An optional logical value that can be set to 1 to reflect the image about the vertical axis. The default is no reflection (0).
Hue
An optional numeric expression for the hue rotation to apply to all of the colors in the image. Range -180 to 180. The default is no hue rotation, (0).
Saturation
An optional numeric expression that is a multiplier to the intensity of each primary color component of every color in the image. Range: 0 to 255. Defaults to 1 if missing or invalid.
Lightness
An optional numeric expression that is a multiplier to the brightness of the image. Range 0+. Defaults to 1 if missing or invalid.
Transparency
An optional numeric expression for a multiplier to the transparency (alpha value) of every color in the image. Range 0 (transparent) to 1 (opaque). Defaults to 1 if missing or invalid.
Contrast
Optional numeric expression to enhance the differences between the colors in the image. Range 0+. Defaults to 1 if missing or invalid.
ColorizeHue
Optional numeric expression for the hue value of a color to be mixed with every color in the image. Range -180 to 180. Defaults to 0 if missing or invalid.
ColorizeSaturation
Optional numeric expression for the intensity of the added color. Zero means that no color is added. Range 0-1. Defaults to 0 if missing or invalid.
AntiAlias

Bit 0 controls whether anti-aliasing will be done when the image is stretched. Defaults to 1 (TRUE) if missing or invalid.

By default, feathering will be applied to an anti-aliased image when it is stretched. Set bit 1 to 1 (TRUE) to suppress feathering.

ScalarColor
Optional color value in the form aRGB Closed A colour value, defined as four, two-digit hexadecimal values. Alpha - Red - Green - Blue. An Alpha value of FF is assumed if only the RGB values are provided., used to apply a specific color to a gray-scale image.
Rotation
Optional floating point value, specifying the clockwise rotation in degrees to be applied when the image is drawn.
Comments Some image modifications have a greater performance impact than would typically be assumed, due to the way image rendering is optimized. Scaling and cropping changes are slow, for example


ModifyConfiguration

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Provides a safe way to write to configuration files.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | File I/O
Related to: | FRead | ReadConfiguration | WritePropertiesFile
Format: | \ModifyConfiguration(pSuccess, CallBackModuleName[, ExtraInfo, Deploy])
Parameters: |
pSuccess
A required pointer to a value, which will be set to 1 on successful completion or 0 on failure.
CallBackModuleName
A required text value, containing the name of the callback module to be launched into the caller.
ExtraInfo
An optional parameter which may be any value. If present, it will be passed through to the callback module.
Deploy
Optional Boolean. Has no effect while the application is running in automatic-deploy mode. If auto-deploy is off, then when this parameter is TRUE (or Invalid) the modified files will be deployed immediately after the changes occur. Defaults to TRUE.
Deploy must be present and set to FALSE to prevent ModifyConfiguration from acting as if auto-deploy is always on.
Comments:

If the caller of ModifyConfiguration is subscribed to working copy changes (via WCSubscribe), then it will not get subscription callbacks for its own changes following a call to this function.

The callback module, named in the second parameter, must be either a launched module or a subroutine that returns Invalid. The callback module is allowed to write configuration files and is guaranteed that, for the life of the module, no other configuration code can modify that file.

The callback module must have the following parameters

pUserID
A pointer variable, to which the current user ID should be assigned. This will be saved as part of the version history.
pComment
A pointer variable for a text comment, to be recorded in the version history.
ChangedFiles
A dictionary that must be populated with the names of the files to be changed during the callback. For each file, add an entry with the key being the file name and the value set to zero. File names may be absolute or relative.
The callback must record the changed files in this dictionary or else they will not be recorded in the configuration management system or deployed to other workstations.
ExtraInfo
Extra data to be passed to the callback function.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


ModifyTags

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Can be used to create, modify, or delete running tags. Replacement for StartTag for the case where persisted tags were created. See comments for more detail.
Returns: | Object reference
Usage: | Script Only.
Function Groups: | Configuration
Related to: | GetTagConfiguredParameters | SimpleOpChange| OpChange | NewTagsFullyStarted
Format: | \ModifyTags(pSuccess, TagParameters[ , newTags, UserID, Comment, Merge, HaveLock, pErrors)
Parameters: |
pSuccess
An optional pointer to a value, which will be set to 1 on successful completion or 0 on failure.
TagParameters
Dictionary of tag parameters, each of which is also a dictionary. See examples.
NewTags
Optional. Dictionary of tag additions. Key is tag friendly name and value is tag type.
If you have a NewTags entry for a tag that already exists, then the action will be a deletion and an add of that tag. The added tag will not have the same UniqueID as the original tag, and therefore page references and history for the old tag will not be associated with the new tag,
UserID
Optional. User making change
Comment
Optional. Comment to store with changes
Merge
Optional. On update, true to retain parameters not specified in parameter dictionary, false to revert all other parameters to their defaults. Defaults to TRUE
HaveLock
Optional. If false, this module gets the working copy lock and commits changes and update tags when finished. If true, caller must have WC lock ModifyTags will not get WC lock, commit changes, or update running tags. Defaults to FALSE
pErrors

Optional output: dictionary of errors, keyed by name of tag with error, containing #MODTAGS_* error code. Defined in Code.

Constants used as error codes, returned in the pErrors dictionary parameter of ModifyTags:

Constant | Value | Description
#MODTAGS_BADNAME | 1 | Name of added tag is not allowed. Refer to tag naming rules.
#MODTAGS_BADTYPE | 2 | Provided type is not an existing type
#MODTAGS_MISSINGTAG | 3 | Attempting to modify a non-existent tag.
#MODTAGS_MISSINGPARENT | 4 | Attempting to add a child to a non-existing parent.

Constants used as global error codes returned in root value of ModifyTags's pErrors dictionary parameter:

Constant | Value | Description
#MODTAGS_NOERROR | 0 | No error.
#MODTAGS_TAGERROR | 1 | One of the errors listed in the preceding table.
#MODTAGS_NOTEDITABLE | 2 | Application cannot be edited at this time. (Most likely, a restart is required.)
Comments:

Some readers may have used non-persisted StartTag calls to create parent/child tag structures. Now that StartTag is obsolete, those structures should be created with the Tag Browser, not in code.

This module launches a worker module into Code so that the operation is not interrupted by this module's caller being slain. The return value of the function is a reference to this worker module. By watching for this to become invalid, you can discover when the module has finished.

ModifyTags works by modifying root tag declarations or adding overrides for child tags not defined in the root tag database. It does not modify tag type definitions.

The TagParameters dictionary is formatted as follows:

 TagParameters[FullFriendlyName] = {TheChange};
  • For tag deletion, {TheChange} is simply Invalid.
  • For a creation or update, {TheChange} is a dictionary of parameter values, keyed by parameter name.

When creating a new tag, the NewTags dictionary must have an entry specifying the tag type. If there is a tag with the given name already running, it will be deleted and the new tag will be created with a new unique ID, even if the type specified in NewTags is the same as the type of the currently-running tag. Hence, this is a way to stop a tag and create a tag having the same friendly name, but a different unique ID and possibly a different type, all in a single operation.

When updating a tag, what will happen to tag parameters that are not specified in the TagParameters dictionary will depend on the value of the Merge parameter. If TRUE (the default), then those parameters remain unchanged by the operation. If FALSE, then those parameters revert to their default, where default for a root tag is the default specified in the tag type, and the default for a child tag is the value specified by its parent's type's child tag definition record (that is, the value it would have without any root overrides). The Merge parameter has no effect on tag additions or deletions.

To set parameters to expressions, you can set metadata on individual parameter values. For example:

TagParms[TagName][ParmName] = ExpressionText;
Metadata(TagParms[TagName][ParmName], System.#EXPRESS_META) = System.#EXPRESS_REFRESH; {non-optimized expression}
Metadata(TagParms[TagName][ParmName], System.#EXPRESS_META) = System.#EXPRESS_SNAPSHOT; {optimized expression}

If HaveLock is TRUE, then when this module finishes, the memory cache of tag parameters will have been updated, and those changes will be pending to be written out to tag files and incorporated into running tags. Note that there is no guarantee that those actions have been performed. That will happen during the next commit. If HaveLock is FALSE, then it is guaranteed that all running tags affected by these changes will have been updated or stopped (whichever applies). Also, while all root tags and all child tags (whose parents are running and that the changes cause to bring into existence) will be running, it is not guaranteed that they will have run their Refresh modules. It is also not guaranteed that children of tags just started will be running yet let alone Refreshed. UseNewTagsFullyStarted to check if all new tags have started, run their Refresh modules, and started their children (if any).

When called with the Merge==FALSE parameter it is possible to revert a tag parameter to its default or remove an override using the API GetTagConfiguredParameters. If ModifyTags is called with Merge=FALSE without using this API, there is no way to remove some configured parameters while keeping others. To make changes to some configured parameters, called GetTagConfiguredParameters, modify the dictionary of parameters (add/modify/remove), then pass the modified dictionary into a call to ModifyTags.

Examples:

Example 1 - Modify running tags (A and B exist and are running):

TagParms = Dictionary();
NewTags   = Dictionary();

TagParms["A"] = Dictionary();
TagParms["A"]["Description"] = "Updated description1";
TagParms["A\B"] = Dictionary();
TagParms["A\B"]["Description"] = "Updated description2";

Success = Invalid;
\Code.ModifyTags(&Success, TagParms, NewTags, GetUserID(), "Modify tags", TRUE, FALSE, &Errors);

Example 2 - Add child tags (Tag C exists and is running):

TagParms = Dictionary();
NewTags   = Dictionary();

NewTags["C\D"]   = "AnalogInput";
TagParms["C\D"] = Dictionary();
TagParms["C\D"]["Description"] = "New AI description";
NewTags["C\D\E"]  = "DigitalInput";
TagParms["C\D\E"] = Dictionary();
TagParms["C\D\E"]["Description"] = "New DI description";

Success = Invalid;
\Code.ModifyTags(&Success, TagParms, NewTags, GetUserID(), "Add tags", TRUE, FALSE, &Errors);

Example 3 - Delete a tag (Tag C\F exists. The third parameter must be invalid. The sixth must be false.):

TagParms = Dictionary();
TagParms["C\F"] = Invalid;
Success = Invalid;
\Code.ModifyTags(&Success, TagParms, Invalid, GetUserID(), "Delete Tags", FALSE, FALSE, &Errors);

Example 4 - Add a parent and a child tag (G and H do not exist):

TagParms = Dictionary();
NewTags   = Dictionary();

NewTags["G"]   = "Calculation";
TagParms["G"] = Dictionary();
TagParms["G"]["Description"] = "New Calc description";
NewTags["G\H"]   = "AnalogStatus";
TagParms["G\H"] = Dictionary();
TagParms["G\H"]["Description"] = "New AS description";

Success = Invalid;
\Code.ModifyTags(&Success, TagParms, NewTags, GetUserID(), "Add tags", TRUE, FALSE, &Errors);

After ModifyTags completes, the following changes to the running tags are guaranteed:

  • A and A\B will be updated.
  • C\F will be stopped.
  • C\D and G will be running but not necessarily refreshed yet.
  • C\D\E and G\H (added tags whose parents weren't already running) will not necessarily be running yet.

If TagParms includes the deletion of a parent tag, then all TagParms and NewTags records related to the addition / modification / deletion of any children of that tag are discarded.


ModifyUserPrivilege

(Security Manager Library)

Description: | Modifies a privilege for the specified username.
Returns: | Numeric (via the first parameter)
Usage: | Script Only.
Function Groups: | Security
Related to: |
Format: | \SecurityManager\ModifyUserPrivilege(PtrReturnCode, Username, Privilege, SetPrivilege[, HaveLock])
Parameters: |
PtrReturnCode
Required. A pointer to a variable that will be used for the return code.
PtrReturnCode | Meaning
1 | Privilege modified.
2 | Denied. The calling context does not have the Manager general privilege.
3 | The privilege is not valid - no action taken.
4 | The specified user does not exist - no action taken.
5 | The SetPrivilege flag is invalid - no action taken.
6 | The application cannot be edited.
UserName
Required. Any expression for the name of the user account to modify.
Privilege
Required. Any numeric expression for the privilege to be modified. Use a negative value for a general privilege and a positive value for a custom privilege.
SetPrivilege
A Boolean expression. Set TRUE if the privilege is to be added.
HaveLock
Optional Boolean expression. Set to true if we have the WC lock. Defaults to 0 or FALSE.
Comments: May only be called from a user-context that has the Manager general privilege. The return value of the function is the object value of the launched worker module. This will be set to Invalid when the operation has completed and may be used to discover when that occurs.
Use of this function requires an understanding of the VTScada security system and the general privileges. Please refer to System Privileges in the chapter Security Manager Service.


ModuleFileName

(Engine-Level Function)

Description: | Returns the full path (including the drive letter) and file name of the document (.SRC) file of a module.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, File I/O, Advanced Module
Related to: |
Format: | ModuleFileName(Module)
Parameters: |
Module
Required. Any expression for the module to enquire about.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

If 1 Next;
[
  PageFiles = ChildDocs(Scope(\Code, PageName), 10);
  I = 0;
  WhileLoop(I < ArraySize(PageFiles, 0),
            PageFiles[I] = ModuleFileName(PageFiles[I]);
            I++;
  );
]


ModuleHighlighted

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Returns true if the module is highlighted.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Module Tree Diagram
Related to: | HighlightModule
Format: | ModuleHighlighted(ModuleTree, Module)
Parameters: |
ModuleTree
Required. Any expression for the module tree value.
Module
Required. Any expression for the module.


ModuleSnapshot

(Engine-Level Function)

Description: | Launched module that draws a module as an image.
Returns: | Image
Usage: | Script Only.
Function Groups: | Graphics
Related to: | |GUIBitmap |
Format: | ModuleSnapshot(ModToCaptureParm, ModWidth_XCoords, ModHeight_YCoords, ptrImage, P1, P2, P3, P4, P5, P6, P7, P8, P9, P10)
Parameters: |
ModToCaptureParm
The name of the module to draw as an image.
ModWidth_XCoords
Either the width of the photo or an array [L, R] where L is the left coordinate of the photo and R is the right coordinate. If this is the width, the left coordinate will be zero.
ModHeight_YCoords
Either the height of the photo or an array [T, B] where T is the top coordinate of the photo and B is the bottom coordinate. If this is the height, the top coordinate will be zero.
ptrImage
This parameter will store the image once it is returned.
P1, P2, P3...P10
Arguments to pass into the module. Up to 10 are supported.
Comments:

This is intended to be used to draw unlinked widgets that use windows controls. It is impossible to draw on top of certain windows controls, so we cannot draw unlinked indicators over unlinked widgets. This skirts the problem by drawing the widget off-screen, taking a photo of it, then getting rid of the off-screen widget. It should then be drawn onscreen using GUIBitmap.

Example:

If Watch(1, Wd, Ht);
[
  ModuleSnapshot("DrawMain", Wd, Ht, &FlatImg, Parm1, Parm2, Parm3...);
]

GUIBitmap(0, BtnHt, BtnWd, 0,
          1, 1, 1, 1, 1,
          0, 0, 1, 0,
          0, 0, 0,
          FlatImg);

Example using coordinates:

If Watch(1, LHS, RHS, TOP, BOT);
[
  ModuleSnapshot("DrawMain", \System.MakeArray(LHS, RHS), \System.MakeArray(TOP, BOT), &FlatImg, Parm1, Parm2, Parm3...);
]

GUIBitmap(0, 1, 1, 0,
          1 - LHS,
          TOP + BitmapInfo(FlatImg, 1) - 1,
          LHS + BitmapInfo(FlatImg, 0) - 1,
          1 - TOP,
          1,
          0, 0, 1, 0,
          0, 0, 0,
          FlatImg);


Month

(Engine-Level Function)

Description: | Returns the month for a given date number.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | Date | DateNum | Day | Today | Year
Format: | Month(Date)
Parameters: |
Date
Required. Any numeric expression giving the number of days since January 1, 1970.
Comments: This function works in conjunction with the Day and Year functions to decompose a date number into the corresponding day, month and year. January is month 1.

Example:

myMonth = Month(8394 { 25 December 1992 });

The variable myMonth will be given the value 12.


MoveEditor

Deprecated. Do not use in new code.

(Engine-Level Function)

Description | Moves the Editor to the given line and column.
Returns | Nothing
Usage | Script or steady state.
Function Groups | Editor
Related to: | WinEditCtrl
Format: | MoveEditor(EditorVal, Line, Column)
Parameters |
EditorVal
Required. An editor Value which is returned by MakeEditor.
Line
Required. Any numeric expression that specifies the line to move the editor to.
Column
Required. Any numeric expression that specifies the column to move the editor to.


MoveSibling

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Moves the position of a module in a module tree diagram.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Module Tree Diagram
Related to: | MoveSelState | MoveState
Format: | MoveSibling(Source, Destination)
Parameters: |
Source
Required. Any expression for the module to be moved.
Destination
Required. Any expression for the module code value of the sibling module where Source will be moved.
Comments: Source will be moved to the position occupied by Destination. Source and Destination must have exactly the same parent object.


MoveWindow

(Engine-Level Function)

Description: | Will move a window to the specified coordinates.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics, Window
Related to: | CurrentWindow | SizeWindow | WindowOptions |Window
Format: | MoveWindow(Win, X, Y)
Parameters: |
Win
Required. Any expression that gives an object value contained in the window to move. Often, Self().
X
Required. Any numeric expression giving the pixel coordinate to place the left hand side of the window.
Y
Required. Any numeric expression giving the pixel coordinate to place the top of the window.
Comments:

The pixel coordinates given are relative to the upper left hand corner of the screen if this is a non-child window. If this is a child window, then the coordinates are relative to the top left corner of the virtual client area of the parent window. This is consistent with the Window function.

The corner being point (0, 0). The X coordinates increase as you move right across the screen. The Y coordinates increase as you move towards the bottom of the screen.

Use with care in pages: your code will run when the page is displayed in the Idea Studio and when the Page Menu page shows a live preview, possibly with undesirable results in those situations. In a page, the trigger for this function should be a user action rather than anything that runs automatically.

Example:

MoveWindow(CurrentWindow(), 20, 20);

This statement will cause the current window to move to the upper left corner of the screen. (Will not cause an error in script mode, but this is not common usage)


MultiCheckboxParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | (A wrapper for NumericParameterEdit.) Use this function to make any number of check boxes in a group.
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | NumericParameterEdit
Format: | MultiCheckboxParameterEdit(Left, Right, Top, ParmPtrArray, CodePtrArray, TitleArray, PtrWaitClose, DialogRoot[, FIDArray, ManualWidth, PTypePtrArray, DescArray]))
Parameters: |
Left
Required numeric. Left placement coordinate.
Right
Required numeric. Right placement coordinate.
Top
Required numeric. Top placement coordinate.
ParmPtrArray
Required. An array of pointers to the value of each parameter.
CodePtrArray
Required. An array of pointers to the definition of each parameter.
TitleArray
Required. An array of titles to display.
PtrWaitClose

Required. A pointer to the SubwaitClose of that panel if applicable.

(Note that only one is used, rather than an array. It will trigger if any of the checkboxes are being edited.)

DialogRoot
Required. The root dialog calling this control. It will be passed on to each individual check box's NumericParameterEdit.
FIDArray
Optional. An array of Focus IDs for each check box. This allows for conditional statements to change the ability of each check box to interact. Each defaults to TRUE if Invalid.
ManualWidth
Optional numeric. Use to provide a value for consideration when calculating the width needed for titles. A manual width smaller than the required width of a title will be ignored.
PTypePtrArray
Optional. An array of PTypes that are handed directly into each checkbox's numericParameterEdit.
DescArray
Optional. An array of descriptions that are placed under each related title. This allows for comments, clarification, or the splitting of a long title.
Comments:

There are two public variables that can be accessed from the object value returned from the wrapper. These are "Height" and "TitlesWidth".

"Height" is the total height of all the checkboxes and the space between them.

"TitlesWidth" is the largest width that the titles in the wrapper require in order to be displayed properly. (Or, the manual width if one is provided and it is greater than that of any of the titles.)

Example:

{ set up variables for multiple checkboxes...  }
    ParmPtrArray = System.MakeArray(&Parms.QueryChange,
                                    &Parms.DisableControl,
                                    &Parms.DisableNavigation,
                                    &Parms.DisableTooltip);

    CodePtrArray = System.MakeArray(&ParmDefs.QueryChange,
                                    &ParmDefs.DisableControl,
                                    &ParmDefs.DisableNavigation,
                                    &ParmDefs.DisableTooltip);

    TitleArray = System.MakeArray("ConfirmationDialogLabel",
                                  "DisableControlLabel",
                                  "DisableNavigationLabel",
                                  "DisableTooltipLabel");
  ]
]

Panel [
 {... }
     { Options }
  PEObj[1] = MultiCheckboxParameterEdit(Space, #PanelWd - Space, PEBot[0] + 2*Space + TitleSpace { Position     },
                                        ParmPtrArray, CodePtrArray                               { Parm Val/Def },
                                        TitleArray, &(SubWaitClose[1])                           { Titles/Wait  },
                                        DialogRoot, Invalid                                      { Root/FIDs    },
                                        TitleWd - Space, Invalid                                 { Width/PTypes },
                                        DescArray                                                { Descriptions });
]


MuteSound

(Alarm Manager module)

Description | This subroutine is used to turn off alarms sounds for all alarms, both current and future.
Returns | Numeric
Usage | Script
Function Groups | Alarm, Speech and Sound
Related to: |
Format: | \AlarmManager\MuteSound([Invalid, MuteState, ExpiryTime]);
Parameters | None.
Invalid
Placeholder. This parameter is now obsolete.
MuteState
Optional Boolean. Set TRUE to mute sound or FALSE to unmute. Defaults to TRUE.
ExpiryTime
Optional numeric. Time at which a muted alarm should unmute (UTC). Leave empty to toggle alarm muting immediately according to the MuteState setting.
Comments

This subroutine will check the current user session to ensure that the logged-on user has the required privilege to toggle alarm muting before proceeding.

The alarm Mute button can be selected or released for each individual user or for computers in the network, according to application configuration. See: ApplyMuteSilencePerComputer, and ApplyMuteSilencePerUser

Example:

IF AlarmShouldBeMuted;
[
  \AlarmManager\MuteSound();
]


N Functions

The sections that follow identify all VTScada functions beginning with "N".


New

(Engine-Level Function)

Description | Allocates memory for an array from RAM and returns a pointer to that array.
Returns | Pointer
Usage | Script Only.
Function Groups | Array, Memory I/O
Related to: | AddVariable | AdjustArray
Format: | New(Size) { Mode 1} New(Dimensions, Start, Size) { Mode 2 } New(FirstDimension, SecondDimension) { Mode 3 }
Parameters

{ Mode 1 }

Size

Required. A numeric value specifying the size of a one-dimensional array

{ Mode 2 }

Dimensions

Required. Any numeric expression giving the number of array dimensions to allocate. To allocate a simple value, use 0 and for a one dimensional array, use 1.

Start

Required. Either a numeric expression or an array.

Specifying a start index other than zero for any dimension of an array is generally regarded as poor practice.

  • If Dimensions is omitted, this parameter must also be omitted. { Mode 1 }
  • If Dimensions is 0, this is ignored.
  • If Dimensions is 1, this is treated as a number, which is the index of the first element in the array allocated.
  • If Dimensions is greater than 1, this is must be the first element of an array of numbers, each element indicating the starting index for a dimension.
Size

Required. Either a numeric expression or an array.

  • If Dimensions and Start are omitted, a single value will define the number of elements in the single dimension array that is created. { Mode 1 }
  • If Dimensions is 0, this parameter is ignored.
  • If Dimensions is 1, this is treated as a number, which is the number of elements in the array allocated.
  • If Dimensions is greater than 1, this must be the first element of an array of numbers, each element indicating the number of elements in a dimension.

{ Mode 3 }

FirstDimension
Required. A numeric value that determines the number of elements in the first dimension of the two dimensional array that is created.
SecondDimension
Required. A numeric value that determines the number of elements in the second dimension of the two dimensional array that is created.

Examples:

  If 1 NextState;
  [
    Simple  = New(0, 0, 0)  { Creates a simple value        };
    Array1 = New(1, 0, 10) { Creates a 1-dimensional array };

    Start[0]  = 0 { Dimension 1 - Starting index     };
    Start[1]  = 0 { Dimension 2 - Starting index     };
    Length[0] = 3 { Dimension 1 - Number of elements };
    Length[1] = 4 { Dimension 2 - Number of elements };
    Array2    = New(2, Start[0], Length[0]);
     { Creates a 2-dimensional array }
  ]

The above script allocates memory for 3 variables:

Simple is a simple value

Array1 is a 1-dimensional array with 10 elements, numbering from 0 to 9.

Array2 is a 2-dimensional array having 3 elements in its first dimension, numbering from 0 to 2, and 4 elements in its second dimension, numbering from 0 to 3.

Array1 could also have been created with the same attributes by using the following statement:

    Array1 = New(10);

Array2 could have been created with same number of rows and columns by using:

    Array2 = New(3, 4);

Multi-dimensional array:

    A = New(3, 0, 2);
    { A is an array of two elements, each of which is an array of two elements, which in turn are arrays of two elements }
    A[0][0][0] = 0;
    A[0][0][1] = 1;
    A[0][1][0] = 2;
    A[0][1][1] = 3;
    A[1][0][0] = 4;
    A[1][0][1] = 5;
    A[1][1][0] = 6;
    A[1][1][1] = 7;


NewTagsFullyStarted

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns TRUE when all new tags have started, run their Refresh modules, and started their children (if any).
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Configuration
Related to: | ModifyTags|OpChange
Format: | \Code.NewTagsFullyStarted()
Parameters: |
Comments:

In script usage, this function returns the value TRUE or FALSE when called.

In steady state usage, this function waits for all tag updates associated with a ModifyTags call to complete before returning True. This is useful because ModifyTags() does not guarantee that all new children have been refreshed and started their own children.

Make sure that the working copy lock is not engaged while this function is being called. Otherwise, it could end up in a deadlock situation if a tag being started needs the working copy before it refreshes but the working copy lock is already being acquired by some other operation.

Example:

\Code.NewTagsFullyStarted() ? Waiting = FALSE:Waiting = TRUE;

In this example, if the new tags have been registered as started and refreshed, the variable,
"Waiting", is set to FALSE. Otherwise, "Waiting" is set to TRUE.


NextFocusID

(Engine-Level Function)

Description: | Moves the focus position to a specific ID number.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics, Keyboard
Related to: | FocusID
Format: | NextFocusID(Object, ID[, Local])
Parameters: |
Object
Required. Any expression for the object that defines the window where the focus is found.
ID
Required. Any numeric expression for the new focus ID number.
Local
Optional Boolean. If True then focus calls are module-specific (i.e. local to the module calling Focus.)
Comments: This statement is useful for forcing the focus to a specific object in a window.

Example:

If Change(myVar, 0);
[
  IfThen(FocusID(Self()) != myFocus,
         NextFocusID(Self(), myFocus));
]

These statements check a variable called myVar, whose value is set in previous code by an edit field, and whenever its value changes (i.e. the edit field received the focus) the focus is checked, then reverted to another object (such as an OK button).


Normal

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Use this function to tell the Alarm Manager when an alarm clears. This subroutine will deactivate the alarm. It will not affect the unacknowledged status.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | CurrentTime | IsActive
Format: | \AlarmManager\Normal(AlarmObject[, EventTime]);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine.
EventTime
Optional. The time stamp to use when adding this event to the alarm lists. If invalid or not defined, the default is CurrentTime().
Comments: The Normal subroutine always returns "0".

Example:

To avoid an If 1 condition when normalizing an alarm, it is common practice to include a variable to ensure that the script runs only once. This should take its value from the current alarm state.

Init [
  AlarmOn  =  AlarmManager\IsActive(MyAlarm);
]
Main [ If value < SomeSetpoint && AlarmOn;
[
  AlarmOn = 0;
  AlarmManager\Active(MyAlarmObj);
]


Normalize

(Engine-Level Function)

Description: | Returns a normalized value.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Limit | Scale | Tag
Format: | Normalize(Value, LowScale, HighScale)
Parameters: |
Value
Required. Any numeric expression which represents the value to normalize.
LowScale
Required. Any numeric expression, which represents the lowest normal scaled value of Value. This is not a limit.
HighScale
Required. Any numeric expression, which represents the highest normal scaled value of Value. This is not a limit.
Comments:

This function encapsulates an expression with low and high scale values. Typically, this is used in a trajectory, rotation or layered graphics function for scaling. The return value is a Normalize value. The function does not limit the value to be within the range defined by LowScale and HighScale, but rather, makes it such that when Value equals HighScale the object (if using in a layered graphics function) will fill its bounding box. If Value exceeds HighScale, the object will extend past its bounding box.
Low and high scale values may be calculated expressions. The compiler will reduce them to constants if they evaluate to constants. If any parameters are invalid, the resulting value will still be valid normalized value.

For example:

Valid(Normalize(Invalid, 1, 2))

will evaluate to 1 (true) and

ValueType(Valid(Normalize(Invalid, 1, 2)))

will evaluate to 21 - a normalize value.

Example:

GUIRectangle(0, 100, 100, 0 { Bounding box of rectangle },
             1, 1, 1 { No scaling of left, bottom or right },
             Normalize(reactorTemp, 0, 150), 1
             { Scale top only, not whole object },
             0, 0 { No trajectory or rotation },
             1, 0 { Rectangle is visible; reserved },
             0, 0, 0 { Cannot be focused },
             12, 15 { Bright red outlined in white });

The variable reactorTemp will be scaled for upper and lower values of 0 and 150. As the value of reactorTemp changes, the top of the rectangle will move proportionately. If it exceeds 150, the top of the rectangle will move outside of the original bounding box.


NormalTrip

Deprecated. Do not use in new code. (Alarm Manager module)

Description: | This subroutine will deactivate an alarm and signal it as unacknowledged.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | CurrentTime
Format: | \AlarmManager\NormalTrip(AlarmObject[, EventTime]);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine.
EventTime
Optional. The time stamp to use when adding this event to the alarm lists. If invalid or not defined, the default is CurrentTime().
Comments: The NormalTrip subroutine always returns "0".


Not

(Engine-Level Function)

Description: | Returns the result of a bitwise logical NOT operation.
Returns: | Signed 64-bit integer
Function Groups: | Bitwise Operation
Usage: | Script or steady state.
Related to: | And | Or | XOr
Format: | Not(Value)
Parameters: |
Value
Required. Any numeric expression.
Comments:

This function produces the binary compliment of a value. It takes all the bits of a binary number and flips them. Each 1 becomes 0 and each 0 becomes 1.

This function takes signed 64-bit integers values. If a number is passed outside the range of a signed 64-bit integer, then the function will return invalid. If Value is invalid, the return value is invalid.

(See: Bitwise Parameters & Operations)

Examples:

r = Not(1);
s = Not(-1);
t = Not(0);
u = Not(-3);

The values of r, s, t and u will be -2 (0xFFFFFFFFFFFFFFFE), 0 (0x0000000000000000), -1 (0xFFFFFFFFFFFFFFFF) and 2 (0x0000000000000002) respectively.


NotifyVIC

(Engine-Level Function)

Description: | Sends a message to a VTScada Thin Client. The message sent depends on the parameter given to the function.
Warning: | This function should be used only by advanced programmers.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | VTScada Internet Client
Related to: |
Format: | NotifyVIC(Value)
Parameters: |
Value
Required. Any numeric expression from the following table.
Value | Meaning
0 | No Op
1 | App is stopping
2 | Authentication Failure
3 | User stopped the session
4 | User logged out
5 | The operator terminated the session (from the Thin Client Monitor)
6 | The operator forced a server changeover (from the Thin Client Monitor)
7 | Refused due to license limits
Comments: none


Now

(Engine-Level Function)

Description: | Returns the current time in seconds since midnight.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Time and Date
Related to: | Seconds | Time | CurrentTime
Format: | Now(Interval)
Parameters: |
Interval
Required. Any numeric expression giving the update time in seconds. Fractions of a second may be specified however, Interval must be greater than or equal to 0.
Comments: This function is similar to Seconds, except that the update interval can be specified. The Now function is re-evaluated every Interval seconds, and the return value is the time in seconds since midnight, rounded to the next lowest whole multiple of Interval.
Now will report time to an accuracy of 0.001 seconds, however it would be unreasonable to expect the function to trigger reliably each millisecond under normal operating conditions. Your CPU speed and the load placed upon it by other processes will both affect the maximum number of times that Now can be triggered each second.

Example:

ZText(20, 20 { Window location of text },
      Time( { Convert from seconds to standard time }
            Now(1 { Update the time every second }),
            2 { Use hh:mm:ss format }),
      5, 0 { Color is dark magenta, use default font });

This displays the time on the screen. It updates every second on the second.

Related information:

Latching and Resetting Functions


NParm

(Engine-Level Function)

Description: | Returns the number of parameters listed in a module instance.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AddParameter | FormalParms | NumParms | Parameter | RemoveParameter | ResetParm
Format: | NParm(Object)
Parameters: |
Object
Required. Any object value, variable, or expression for a Module.
Comments: This function is for experienced users, and is not needed for normal operation. Any user-defined module can be called with any number of parameters. This function returns the actual number of parameters in the call made to the module instance Object. For launched modules the return value is the minimum of the actual and the formal parameters.

Example:

<
Show
(
  parm1;
  parm2;
)
Main [
  myParms = NParm(Self());
]
>

When called in steady-state as Show("A", "b", "C"), the value of myParms will be "3". When launched as Launch("Show", Invalid, Invalid, "A", "b", "C"), the value of myParms will be "2".


NumericParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper for ParameterEdit, used when adding a numeric parameter to a control.
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | ParameterEdit| ColorParameterEdit | TagParameterEdit | DurationParameterEdit |MultiCheckboxParameterEdit |TextParameterEdit | TimestampParameterEdit|
Format: | NumericParameterEdit(Left, Bottom, Right, Top, ParmVal, ParmCodePtr, TagObjPreferred, Title, PtrWaitClose, DialogRoot, MinLimit, MaxLimit, PTypeIdx[, TitleWidth, ShowDrawnTagProperty, FocusID, Type, IsSpinBox, ToolTitleWidthOut, Description, DroplistChoices])
Parameters: |
Left
Required. Any numeric expression for the left edge of the object.
Bottom
Required. Any numeric expression for the bottom edge of the object.
Right
Required. Any numeric expression for the right edge of the object.
Top
Required. Any numeric expression for the top edge of the object.
ParmVal
The parameter value to be altered.
Typically, one element of the array of parameters passed to the panel.
ParmCodePtr
The code pointer to the parameter.
Typically, one element of the array of parameter definition structures that correspond to the ParmVal.
TagObjPreferred
Set to TRUE to obtain a tag object when possible.
Title
The title to display.
PtrWaitClose
Wait to close.
The parameter edit module will set the value of this pointer to true when the caller should wait to close. For example, if the parameter edit is displaying a dialog, or completing a calculation.
DialogRoot
Root dialog calling this control.
Typically provided by the panel module.
MinLimit
Minimum limit of the selection.
MaxLimit
Maximum limit of the selection.
PTypeIdx
Index of the Parameter type selection.
TitleWidth
Optional, number of pixels allotted for the width of the title.
ShowDrawnTagProperty
Optional Boolean, set to TRUE to show "Drawn Tag Property". Defaults to TRUE.
FocusID
Optional value from 0 to 32767 for the focus ID of this control.
Type
Optional value specifying the type for the parameter. Defaults to Double.
IsSpinBox
Optional Boolean. When TRUE the numeric option is displayed as a spin box.
ToolTitleWidthOut
Optional numeric output value. Holds the width of the parameter edit's tool and title.
Description
Optional text describing this parameter.
DroplistChoices
Optional. Dynamic array. Contains the array of labels for a droplist. If it is valid, the NumericParamterEdit's value will be displayed as a droplist.
Comments:

Automatically determines what module to use for display and entry of the existing value.

If DroplistChoices is valid, selecting the first entry in the droplist sets the value to 0, the second to 1...

Example #1:

ParmEditObj = \NumericParameterEdit(0, 2 * (EditHt + Space), PanelWd, 0,
                          Parms.DisableTooltip      { Parm to disable the tool tip },
                          ParmDefs.DisableTooltip   { Pointer to Parm Code     },
                          0                         { The tooltip is not a tag },
                          \GetPhrase("DisableTooltipLabel") { Title            },
                          &SubWaitClose[7]          { Wait to close            },
                          DialogRoot                { Calling dialog window    },
                          0                         { MinLimit                 },
                          1                         { MaxLimit                 },
                          Invalid                   { No index for this parm   },
                          TitleWd                   { Width of the title       },
                          True                      { Show drawn tag property  },
                          1                         { FocusID                  });

Example #2:

FormatOptions[0]      = GetPhrase("BinaryLabel");
FormatOptions[1]      = GetPhrase("OctalLabel");
FormatOptions[2]      = GetPhrase("HexLabel");
FormatOptions[3]      = GetPhrase("DecimalLabel");

{***** IntegerFormat *****}
ParmEditObj[0] = \NumericParameterEdit(Left                                   { Placement coordinate                          },
                                       Bottom                                 { Placement coordinate                          },
                                       Right                                  { Placement coordinate                          },
                                       Top                                    { Placement coordinate                          },
                                       Parms[#IntegerFormat]                  { The Parameter value to alter                  },
                                       ParmDefs[#IntegerFormat]               { The code pointer to the parameter             },
                                       FALSE                                  { Not a tag                                     },
                                       "Data type"                            { The title to display                          },
                                       &(SubWaitClose[0])                     { Wait to close                                 },
                                       DialogRoot                             { Root dialog calling this control              },
                                       Invalid                                { Minimum limit of the selection                },
                                       Invalid                                { Maximum limit of the selection                },
                                       1                                      { Index of the Parameter type selection         },
                                       TitleWidth                             { Width alloted for the Title                   },
                                       Invalid                                { True to show "Drawn Tag Property"             },
                                       1                                      { Focus ID                                      },
                                       Invalid                                { The parameter type                            },
                                       False                                  { Not a spinbox                                 },
                                       Invalid                                { [OUT] Width of ParmEdit's tool and title      },
                                       Invalid                                { Optional text describing this parameter       },
                                       FormatOptions                          { Is a droplist                                 });


NumInstances

(Engine-Level Function)

Description: | Returns the number of module instances currently running.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Basic Module
Related to: | GetInstance | Instance | CalledInstances
Format: | NumInstances(Module)
Parameters: |
Module
Required. Any module or object value of the module to count.
Comments: This function is useful for counting both the number of active instances of the current module as well as the number of active instances of another module.

Example:

numThis = NumInstances(Self());
If ! Valid(numAnother);
[
  numAnother = NumInstances(FindVariable("Calculations", Self(),
  0, 1));
]

These statements count the number of active instances of the current module and the Calculations module. Notice that the script is necessary in the second case, not because of the NumInstances function, but because of the FindVariable function.

To determine whether a page is already open before calling ShowPage() use:

NumInstances(\PageModuleName)

... where PageModuleName is the name of the page module.


NumParms

(Engine-Level Function)

Description: | Returns the number of parameters of a statement.
Warning: | This function should be used by advanced users only.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | FormalParms | NParm
Format: | NumParms(Statement)
Parameters: |
Statement
Required. Any expression for the statement code value or code pointer value.
Comments: This function returns the number of parameters of a statement.


NumSelected

(Engine-Level Function)

Description: | Returns the number of selected graphics statements in a window.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | SelectGraphic | UnselectGraphics | UnselectObject
Format: | NumSelected(Object)
Parameters: |
Object
Required. Any expression for the object that defines the window.

Example:

selGraphic = NumSelected(CurrentWindow());

This will set selGraphic to the number of currently selected objects in the window that the mouse is presently over.


NumSets

(Engine-Level Function)

Description: | Returns the number of statements that are currently active in setting a particular variable.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | Watch
Format: | NumSets(Variable)
Parameters: |
Variable
Required. Any variable for which the number of sets is required.

Example:

setsOnX = NumSets(x);

This will set setsOnX to the number of statements that are currently active in setting the value of variable x.


NumVariables

(Engine-Level Function)

Description: | Returns the number of variables in a module.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | SelectGraphic | UnselectGraphics | UnselectObject
Format: | NumVariables(Module)
Parameters: |
Module
Required. Any expression for the object or module value.

Example:

numVars = NumVariables(Self());

This will set numVars to the number of variables in the current module.


O Functions

The sections that follow identify all VTScada functions beginning with "O".


ODBC

(Engine-Level Function)

Description | Performs an ODBC command and returns a dynamically allocated array if required.
Returns | Array
Usage | Script Only.
Function Groups | Database and Data Source, ODBC
Related to: | ODBCConfigureData | ODBCColumns | ODBCConnect | ODBCDisconnect | ODBCSources | ODBCStatus | ODBCTables | TODBC | TODBCConnect | TODBCDisconnect
Format: | ODBC(DB, SQLCommand [, Attrib, ErrorMsg, SQLState, ErrorCode, CellLimit, HasMoreCells]) Refer to the comments section of TODBC for a discussion on the differences between blocking and non-blocking ODBC calls.
Parameters
DB
Required. An ODBC value for the ODBC database as returned by ODBCConnect.
SQLCommand
Required. Any text expression for the SQL command to perform on the ODBC database driver. If the query involves long binary data types, then a structure should be used. See examples.
Attrib
An optional parameter that returns a 2D array, with each row in the array holding detailed attributes for one column of the result set, as per the following
Attrib | Attribute
Attrib[col][0] | Name of the column
Attrib[col][1] | Type of data VTScada will return for the column: 0 == text 1 == numeric
Attrib[col][2] | Type SQL ODBC Types indication for the field:
Attrib[col][3] | A numeric value that is either the maximum or actual character length of a character string or binary data type. It is the maximum character length for a fixed-length data type, or the actual character length for a variable-length data type.
ErrorMsg:
A descriptive error or status message, returned by the function. If valid, both ErrorMsg and SQLState will be valid.
SQLState:
A 5-character SQL State code. SQL State codes are defined by Microsoft and by the vendor of each ODBC driver.
ErrorCode:
An unsuccessful operation always returns a non-zero value, which is a numeric error code specific to the DBMS vendor's ODBC driver or Microsoft's ODBC Driver Manager.
A successful operation will always return a 0. ErrorMsg and SQLState may or may not be set valid in the event of a successful connection. If set valid, they should be examined for relevant status information.
CellLimit

Optional. If provided, returns number of cells to CellLimit.

  • If less than 0 or higher than the total cells, all data is returned.
  • If equal to 0 or less than the number of columns, no data is returned.
  • If CellLimit is not a multiple of the number of columns, partial rows will not be included in the returned data.
HasMoreCells
Optional output parameter. Indicates that more data was available than returned. If the CellLimit is not provided OR is less than 0, all data is returned and the flag updates to FALSE.
Comments:

There may or may not be a return value for this function, depending on the nature of the SQL command that was executed. If a return value exists, it will be a dynamically allocated, two-dimensional array that contains the rows resulting from the query. The format for the array is Result[Field][Record].
If any error, no matter how minor, occurs as a result of the SQL command, and if the ODBCConnect that connected to the database had its Disconnect parameter set true, then the value of DB will become invalid (i.e. the connection to the database will be dropped).
All ODBC operations can result in one or more status or error conditions arising. VTScada records the entire set of status/error conditions arising and buffers them internally. Use the ODBCStatus function to retrieve the entire set. Only the first condition that occurred or, if both error and advisory conditions occur, the first error condition, is returned in the ErrorMsg and SQLState values.
From VTS 10.0 onwards, VTScada uses ODBC 3.x compliant operations (formerly ODBC 2.x). This has the side effect that different SQLState return values are returned for some SQLState values. If you have written code that depends on the value returned by SQLState, you may need to change the value you expect. See http://msdn.microsoft.com/en-us/library/ms712451%28VS.85%29.aspx for a reference on the value changes.
In the case of the optional parameters, any parameter that is not required may be set to 0 if it is followed by a valid parameter, or may be simply omitted if no valid parameters follow it.
This command requires a knowledge of SQL (Structured Query Language). The examples provide several SQL statements which you can use as templates.

Numeric values retrieved from an ODBC data source are restricted to double precision floating point values. There is no support for receiving full-precision 64-bit integers.

Example 1

Optional entities are enclosed in square brackets [ ], while required ones are enclosed by angled brackets < >. Italicized text represents names of tables, fields, etc. Embedded quotes need to appear twice to signify to VTScada that they are part of the string, and do mark the close of the string.

To create a table, the basic format is:

Create Table "TableName" (< list of fields/types >)

where

< list of fields/types > is a comma separated list of fields and their types (the field and type are separated by a white space character) that define the table. The field names must be enclosed in quotation marks if they duplicate an SQL reserved word or if they contain a white space character. Field types include (but are not limited to):

  • Int or Integer, SmallInt, Float, Real, Double, Precision, Dec(p,d) or Decimal(p,d), Numeric(p, d)

  • Char(n) or Character(n), VarChar(n) or Char Varying(n) or Character Varying(n)

  • Bit(n), Bit Varying(n)

  • Date, Time

where p is the precision (total number of decimal digits) and d is the number of places after the decimal point.

To create a table for a custom tag type called Motor, the SQL command might look something like the following:

Create Table "Motor" ("Name" Char(32), "Area" Char(32), "Description" Char(32), "Input" Char(32),
"Status" Int, "Temperature" Decimal(5, 1))

To insert an entry into a table, the basic format is:

Insert Into "TableName"
[(<list of fields >)]
Values (<list of values >)

where

[(< list of fields >)] is an optional clause that is a comma separated list of fields defining which fields to assign the values to. The field names must be enclosed in quotation marks if they duplicate an SQL reserved word or if they contain a white space character. If this field list is omitted, all fields must have an assigned value, even if they are null, in which case the reserved word NULL (no quotes) is used.

< list of values > is a comma separated list of field values that define the record and take the form:

'Value'

Values must be enclosed in single quotes if they are text strings.

Example 2:

To insert a record with binary large objects:

{ Declare and initialize the structure }
ODBCQuery STRUCT [
  QueryString;
  Parameters;
];
Query = ODBCQuery();

Query\QueryString = "INSERT INTO TestLargeBlobs (id, Blob1, Blob2) VALUES (1, ?, ?)";
Query\Parameters = New(2);
Query\Parameters[0] = MakeBuff(10000000, 65);
Query\Parameters[1] = MakeBuff(20000000, 66);
ODBC(DBHandle, Query);

Similarly, to do an update:

Query = ODBCQuery();
Query\QueryString = "UPDATE TestLargeBlobs SET Blob2=? WHERE id=1";
Query\Parameters = MakeBuff(30000000, 67);
ODBC(DBHandle, Query);

Example 3:

To insert a record with a valid name and status (but all other fields invalid) into the table created in the previous example, the SQL command might look something like the following:

Insert Into "Motor" ("Name", "Status") Values ('Motor 1234', 1)

To retrieve data from a table, the basic format is:

Select [ number of records ]< list of fields >
From <list of tables >
[Where < conditions >]
[Order By < list of fields >]

where

[number of records] is an optional statement that limits the number of records retrieved. It takes the form:

Top N

where N is the number of records.

< list of fields > is a comma separated list of fields to retrieve for each record, or by which the records are sorted. The field names must be enclosed in quotation marks if they duplicate an SQL reserved word or if they contain a white space character. If all of the fields for a record are to be retrieved, an asterisk should be used. The asterisk must not be enclosed in quotation marks.

<list of tables > is a comma separated list of tables from which to retrieve the data. As with the attribute list, the table names must be enclosed in quotation marks if they duplicate an SQL reserved word or if they contain a white space character.

[< conditions >] is an optional clause giving the list of conditions that take the form:

"FieldName" = 'Value'

where FieldName is the actual name of the field and Value is the numeric or text value to match. Note that each field name need only be enclosed in quotation marks if it duplicates an SQL reserved word or contains a white space character. Similarly, the value needs to be enclosed in single quotes only if it is a text string. Multiple conditions are separated by the key word And.

Example 4

Suppose that in a VTScada application a user wanted retrieve the first 10 entries of an alphabetical list of names and descriptions for standard analog input tags that belonged to the system area and had questionable data:

Select Top 10 "Name", "Description" From "AnalogInput"
   Where "Area" = 'System' And "Questionable = 1 Order by "Name"

To modify an entry in a table, the basic format is:

Update "TableName" Set <list of fields/values >

Where < conditions >

where

< list of fields/values > is a comma separated list of fields and their values that define the record and take the form:

"FieldName" = 'Value'

Field names must be enclosed in quotation marks if they duplicate an SQL reserved word or if they contain a white space character. Values must be enclosed in single quotes if they are text strings.

< conditions > is a list of conditions that define which record to modify. For more information, see the < conditions > section in item number 3.

Example 5

To change an existing record (tag) in the standard analog input table (tag type), the SQL command might look something like the following:

Update "AnalogInput" Set "Area" = 'System', "UnscaledMin" = 10, "UnscaledMax" = 80 Where "Name" = 'AI36'

To delete an entry from a table, the basic format is:

Delete From "TableName" Where < conditions >

where

< conditions > is a list of conditions that define which record to delete. For more information, see the < conditions > section in item number 2.

Example 6

To delete the record that was modified in the previous example entirely, the SQL command might look something like the following:

Delete From "AnalogInput" Where "Name" = 'AI36'

Example 7

To connect to an ODBC data source and create a table whose name is held in the variable tableName, and whose text string lengths are limited to the value of the variable maxLen, the calls might look something like the following:

If Valid(dsName) Main;
[
  dbHandle = ODBCConnect(dsName, "", "", eMsg, eState, eCode);
  eType = ODBCStatus(0);
  IfThen(eType != 0,
         Slay(Self(), 0);
  );
  commandString = Concat("Create Table """, tableName,
       """ (""Name"" Char(", maxLen, "), ""Area"" Char(", maxLen,
       ""Description""", Char(", maxLen, "), "Input" Char(", maxLen,
       "), "Status" Int, "Temperature" Decimal(5, 1));
  result = ODBC(dbHandle, commandString, fieldAttrib, eMsg,
                eState, eCode);
  IfThen(eType != 0,
    Slay(Self(), 0);
  );
]

The following example shows an SQL command placed into a VTScada parameter:

ODBC(DB, "Create Table ""Motor"" (""Name"" Char(32), ""Area""   Char(32), ""Description"" Char(32),
""Input"" Char(32), ""Status"" Int, ""Temperature"" Decimal(5, 1))");

Note that all embedded quotes need to appear twice to tell VTScada that they are part of the string and not the end of the string. This applies to all text constants used anywhere in VTScada.


ODBCBeginTrans

(Engine-Level Function)

Description: | Indicates to a specified ODBC-compliant database that a transaction is to be started.
Returns: | Nothing (return values in parameters)
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBCCommit | ODBCRollback | TODBCBeginTrans | TODBCCommit | TODBCRollback
Format: | ODBCBeginTrans(DB [, ErrorMsg, SQLState, ErrorCode])
Parameters: |
DB
Required. An ODBC-compliant database as returned by ODBCConnect.
ErrorMsg
A descriptive error or status message, returned by the function. If valid, both ErrorMsg and SQLState will be valid.
SQLState
A 5-character SQL State code. SQL State codes are defined by Microsoft and by the vendor of each ODBC driver.
ErrorCode
An unsuccessful operation always returns a non-zero value, which is a numeric error code specific to the DBMS vendor's ODBC driver or Microsoft's ODBC Driver Manager.
A successful operation will always return a 0. ErrorMsg and SQLState may or may not be set valid in the event of a successful connection. If set valid, they should be examined for relevant status information.
Comments: A transaction is a unit of work that is done as a single operation. The operation succeeds or fails as a whole. ODBCBeginTrans indicates that a transaction is to be started on the specified ODBC database. Note that each ODBC database driver may have different levels of transaction support (or none at all), and the documentation for that driver should be consulted to determine the level of transaction support. The transaction should be terminated either with an ODBCCommit or an ODBCRollback.
If any error (no matter how minor) occurs as a result of the statement, and the TODBCConnect or ODBCConnect that connected to the database had its Disconnect parameter set to true, the value of DB will become invalid (i.e. the connection to the database will be dropped).

Example:

[
  ODBCBeginTrans(DB);
  ODBC(DB, "DELETE * FROM TEST");
  ODBC(DB, "INSERT INTO TEST VALUES('KeyString', 'Value')");
  ODBCCommit(DB);
]


ODBCColumns

(Engine-Level Function)

Description: | Retrieves a list of the columns present in an ODBC-compliant database and returns it as a dynamically allocated array.
Returns: | Dictionary
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBC |ODBCConfigureData |ODBCConnect |ODBCDisconnect |ODBCSources |ODBCStatus |ODBCTables |
Format: | ODBCColumns(DB[, TableSearch, ColumnSearch, Timeout, MaxResults, HasMore])
Parameters: |
DB
Required. ODBC database handle as returned by OBDCConnect.
TableSearch
Optional. Include a string to match against table names for a filtered return. "%" acts as a wildcard in these search strings.
ColumnSearch
Optional. Include a string to match against column names for a filtered return. "%" acts as a wildcard in these search strings.
Timeout
Optional. Sets the period (in seconds) that the driver will wait for the request to complete.
The default value of "0" indicates that there is no timeout. See comments.
MaxResults
Optional. Specify the maximum number of columns to be returned.
If this is Invalid or less than 0, there is no limit. See comments.
HasMore
Optional. If the request would return more than MaxResults results, this output parameter gets set to TRUE. Otherwise it will be set to FALSE.
Comments:

ODBCColumns will stall the calling thread while it executes. Consider calling it from a separate script thread that doesn't need to remain responsive.

ODBCColumns can be slow collecting results across many tables. Hence, callers should consider using the Timeout and MaxResults parameters to limit the potential impact.

For Timeout, Please note:
Not all ODBC drivers support the optional Timeout parameter. (In particular, the Microsoft Access (.mdb) driver). If the driver does not support the option, it will have no effect.

For MaxResults, please note:
In the case of ODBCColumns, this is the spread across all tables returned in the results. If the ODBCColumns call would return results from three tables with 10 columns each, and MaxResults is set to 15, then the results will only include 15 columns instead of 30.
No guarantee is given as to which of those 30 columns will be included.

Each dictionary key is a table name matching the TableSearch parameter paired with an array of structs. Each struct constitutes the information of an individual column and is comprised of four main fields:

Name

The column name.

VTSType

TRUE for numeric, FALSE for text.

SQLType

The SQL ODBC column data type (SeeSQL ODBC Types)

Length

The reported ODBC column size.

If the SQLType is SQL_CHAR or SQL_VARCHAR, Length will be the maximum number of character the column may contain.

If the SQLType is a date of time, Length will be the total amount of characters required to display the value.

For numeric types, Length will be determined by the number of digits or the maximum number of bits allowed in the column.

The length of an SQL interval will be the number of characters required for its literal expression.

Example:

To query the SQL type of the second column of a table named "MyTable", you would access the column information in the dictionary similarly to a 2D array, like so:

ColumnData = ODBCColumns(DB, "MyTable");
SQLTypeCo12 = ColumnData["MyTable"][1].SQLType


ODBCCommit

(Engine-Level Function)

Description: | Indicates to a specified ODBC-compliant database that a transaction is to be committed.
Returns: | Nothing (return values in parameters)
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBCBeginTrans | ODBCRollback | TODBCBeginTrans | TODBCCommit | TODBCRollback
Format: | ODBCCommit(DB [, ErrorMsg, SQLState, ErrorCode])
Parameters: |
DB
Required. An ODBC value for the specified ODBC database as returned by ODBCConnect.
ErrorMsg
A descriptive error or status message, returned by the function. If valid, both ErrorMsg and SQLState will be valid.
SQLState
A 5-character SQL State code. SQL State codes are defined by Microsoft and by the vendor of each ODBC driver.
ErrorCode
An unsuccessful operation always returns a non-zero value, which is a numeric error code specific to the DBMS vendor's ODBC driver or Microsoft's ODBC Driver Manager.
A successful operation will always return a 0. ErrorMsg and SQLState may or may not be set valid in the event of a successful connection. If set valid, they should be examined for relevant status information.
Comments: Commits a transaction defined as all the SQL statements executed on an ODBC-compliant database since the transaction began.
If any error, no matter how minor, occurs as a result of the statement, and the TODBCConnect or ODBCConnect that connected to the database had its Disconnect parameter set to true, the value of DB will become invalid (i.e. the connection to the database will be dropped).

Example:

[
  ODBCBeginTrans(DB);
  ODBC(DB, "DELETE * FROM TEST");
  ODBC(DB, "INSERT INTO TEST VALUES('KeyString', 'Value')");
  ODBCCommit(DB);
]


ODBCConfigureData

(Engine-Level Function)

Description: | Configures an ODBC data source and returns its error code.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBC |ODBCColumns |ODBCConnect | ODBCDisconnect | ODBCSources | ODBCStatus | ODBCTables | TODBC | TODBCConnect | TODBCDisconnect
Format: | ODBCConfigureData(Mode, DriverName [, Settings])
Parameters: |
Mode
Required. Any numeric expression for the mode as follows:
Mode | Meaning
0 | Add data source
1 | Configure data source
2 | Remove data source

In order for 64-bit VTScada to work with 64-bit data sources, add 64 to the Mode parameter. 32-bit VTScada cannot configure a 64-bit data source.

DriverName
Required. Any text expression for the ODBC driver name, as configured in the ODBC setup menu under Microsoft Windows™. In the case of Excel, use "Microsoft Excel Driver (*.xls)".
Settings
A variety of optional parameters that are text expressions, giving the variable and value pairs used to specify the configuration of the ODBC data source.
Any number of these parameter pairs may be used by simply listing the text string containing the variable name, followed by the value that the variable is to be set to. The variables to use include
Settings | Description
DBQ | Name of the workbook (database) file
DefaultDir | Workbook directory
Description | Text description for data source
Driver | Path to the driver .DLL
DriverID | Integer ID for the driver
DSN | Data source name
FileType | File type
FirstRowHasNames | Sets if first row contains column names
MaxScanRows | Rows to scan in setting data type of column (range is 0 - 16)
ReadOnly | Sets the database file as read only

If the DriverID option was selected, the Excel driver values that may be used are as follows:

Value | Driver
534 | Microsoft Excel 3.0
278 | Microsoft Excel 4.0
22 | Microsoft Excel 5.0/7.0
790 | Microsoft Excel 97

Microsoft SQL Server requires additional keyword-value pairs. It uses the keywords in the following table. Note that only the SERVER keyword is required for this function. All other keywords are optional.

Keyword | Description
ADDRESS | The network address of the SQL Server database management system from which the driver retrieves data.
DATABASE | The name of the SQL Server database.
DESCRIPTION | A description of the data in the data source.
LANGUAGE | The national language to be used by SQL Server.
NETWORK | The network library that connects the platforms on which SQL Server and the SQL Server driver reside.
OEMTOANSI | Enables conversion of the OEM character set to the ANSI character set if the SQL Server client machine and SQL Server are using the same non-ANSI character set. Valid values are YES for on (conversion is enabled) and NO for off. The default value is set by using the SQL Client Configuration Utility.
SERVER | The name of the network computer on which the data source resides.
TRANSLATIONDLL | The name of the DLL that translates data passing between an application and a data source.
TRANSLATIONNAME | The name of the translator that translates data passing between an application and a data source.
TRANSLATIONOPTION | Enables translation of data passing between an application and a data source.
USEPROCFORPREPARE | Disables generation of stored procedures for SQLPrepare. Valid values are NO for off (generation is disabled) and YES for on. The default value (set in the Setup dialog box) is YES.
Comments: If the data source already exists, it will be reconfigured as per the specs given and "0" (no error) will be returned.
The data source name may not contain apostrophes or an ODBC error will occur. The function will return the error code.
Some types of ODBC data sources, such as Microsoft™ Excel, do not require the file to be created prior to executing SQL commands on the data source, but will create a blank file when the first SQL Create Table command is executed. Others, such as Microsoft™ Access require the file to be created prior to execution of any SQL statements.

Please note that configuration of ODBC Data Sources requires write permission to the registry key "HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI". If the current user doesn't have write permission to the key, then the string "Insufficient permissions" will be returned. This means that VTScada must be run as Administrator for the function to work.

The following table identifies some possible errors and their meaning:

Error Message | Significance
General Installer Error | An error occurred for which there was no specific ODBC installer error.
Invalid Type of Request | The Mode parm was something other than 0, 1, or 2.
Invalid Driver or Translator Name | The DriverName parm was not a valid ODBC driver name (found in the registry).
Invalid Keyword-value pairs | One of the Settings parms contained a syntax error. For example, spaces are not permitted around the equals sign in the keyword-value pair, nor are certain illegal characters (listed under the "Invalid Data Source Name" error).
Request Failed | The installer could not perform the operation requested.
Could Not Load the Driver or Translator Setup Library | The driver setup library could not be loaded.
Out Of Memory | The ODBC installer could not perform the function because of a lack of memory.
Invalid Data Source Name | The length of the data source name exceeded the maximum length of 32 characters, consisted entirely of blanks, or contained one of the following illegal characters: [ ] { } ( ) , ; ? * = ! @ \

Examples:

{ Create a data source }
If ZButton(10, 30, 110, 10, "Create DS", 1);
[
  { Make sure name doesn't contain apostrophes }
  Replace(DSName, 0, StrLen(DSName), "'", "");
  ODBCConfigureData(0, "Microsoft Access Driver (*.mdb)",
                    "DSN", DSName,
                    "DefaultDir", Concat(DSDrive, DSPath),
                    "DBQ", Concat(DSFileName, ".MDB"),
                    "Description", DSDesc,
                    "FileType", "Access",
                    "ReadOnly", 0);
]
{ Create the data source's file }
If ZButton(10, 70, 110, 40, "Create file", 2);
[
  ODBCConfigureData(1, "Microsoft Access Driver (*.mdb)",
                    "DSN", DSName,
                    "CREATE_DB",
                    Concat(DSDrive, DSPath,
                    DSFileName, ".MDB"));
]
{ Delete the data source }
If ZButton(10, 110, 110, 80, "Delete DS", 3);
[
  ODBCConfigureData(2, "Microsoft Access Driver (*.mdb)",
                    "DSN", DSName);
]
{ Create a MS SQL Server data source }
If ZButton(10, 150, 110, 120, "Create SQL DS", 3);
[
  ErrorCode = ODBCConfigureData(0, "SQL Server", "DSN",ODBCName,
                                "Description",
                                "SQL server connection created by VTS.",
                                "SERVER",
                                ComputerName, "NETWORK",
                                "DBMSSOCN" );
]

To remove a 64-bit data source (using 64-bit VTS):

ODBCConfigureData(66, …)

To add a 32-bit data source (using either 64-bit or 32-bit VTS):

ODBCConfigureData(0, …)


ODBCConnect

(Engine-Level Function)

Description: | Forms a connection to an ODBC-compliant database and returns the ODBC value associated with that database.
Returns: | ODBC database
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBC | ODBCColumns | ODBCConfigureData | ODBCDisconnect | ODBCSources | ODBCStatus | ODBCTables | TODBC | TODBCConnect | TODBCDisconnect
Format: | ODBCConnect(DSName, UserName, Password [, ErrorMsg, SQLState, ErrorCode, Disconnect, LoginTimeout, ConnectTimeout])
Parameters: |
DSName
Required. Any text expression for the ODBC data source name, as configured in the ODBC setup menu under Microsoft Windows™.
UserName
Required. Any text expression for the ODBC login user name.
Password
Required. Any text expression for the ODBC login password.
ErrorMsg
A descriptive error or status message, returned by the function. If valid, both ErrorMsg and SQLState will be valid.
SQLState
A 5-character SQL State code. SQL State codes are defined by Microsoft and by the vendor of each ODBC driver.
ErrorCode
An unsuccessful operation always returns a non-zero value, which is a numeric error code specific to the DBMS vendor's ODBC driver or Microsoft's ODBC Driver Manager.

A successful operation will always return a 0. ErrorMsg and SQLState may or may not be set valid in the event of a successful connection. If set valid, they should be examined for relevant status information.
Disconnect
An optional parameter that is any logical expression that determines how errors are to be handled. If true (non-0), the connection to the database will be disconnected should any error (no matter how minor) occur.

If false (0) an error will not cause a disconnect to occur. The default value is false.
LoginTimeout
Optional. An SQLUINTEGER (unsigned long) value corresponding to the number of seconds to wait for a login request to complete before returning to the application. The default is driver-dependent. If the value is 0, then the timeout is disabled and a connection attempt will wait indefinitely.

If the specified timeout exceeds the maximum login timeout in the data source, then the driver substitutes that value and returns SQLSTATE 01S02 (Option value changed).
ConnectTimeout
Optional. An SQLUINTEGER value corresponding to the number of seconds to wait for any request on the connection to complete before returning to the application. The driver should return SQLSTATE HYT00 (Timeout expired) any time that it is possible to time out in a situation not associated with query execution or login.
If the value is equal to 0 (the default) then there is no timeout.
Comments:

If the UserName and Password parameters are specified as invalid, the DSName parameter is treated as a literal connection string for the ODBC connection. For example, in the statement ODBCConnect("DSN=MyData;UID=;PWD=", Invalid, Invalid), the first parameter is used to set the attributes of the connection, which makes this statement equivalent to ODBCConnect("MyData", "", "").

In the case of the optional parameters, any parameter that is not required may be set to 0 if it is followed by a valid parameter, or may be simply omitted if no valid parameters follow it.

On successful completion of the ODBC and ODBCConnect functions, the native error code will be set to 0, allowing the user to tell if a command that has no result set has been completed. The user should not assume that since a 0 is returned, then the command has been executed successfully. Some drivers (such as Excel) will return a 0 in the native error code, even when an error has occurred.

All ODBC operations can result in one or more status or error conditions arising. VTScada records the entire set of status/error conditions arising and buffers them internally. Use the ODBCStatus function to retrieve the entire set. Only the first condition that occurred or, if both error and advisory conditions occur, the first error condition, is returned in the ErrorMsg and SQLState values.

From VTS 10.0 onwards, VTS uses ODBC 3.x compliant operations (formerly ODBC 2.x). This has the side effect that different SQLState return values are returned for some SQLState values. If you have written code that depends on the value returned by SQLState, you may need to change the value you expect. See http://msdn.microsoft.com/en-us/library/ms712451%28VS.85%29.aspx for a reference on the value changes.

64-bit VTScada is able to connect to either 64-bit or 32-bit ODBC data sources. ODBCConnect will first try to connect to the database through a 64-bit ODBC driver. If this fails for any reason it will then try the connection through a 32-bit ODBC driver. This means that any ODBC code that worked under 32-bit VTScada should not need to be modified for use with 64-bit VTScada, but 64-bit VTScada has the extra ability of being able to use 64-bit ODBC drivers.


ODBCDisconnect

(Engine-Level Function)

Description: | Stops a connection to the ODBC database.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBC | ODBCConfigureData | ODBCConnect | ODBCSources | ODBCStatus | ODBCTables | TODBC | TODBCConnect | TODBCDisconnect
Format: | ODBCDisconnect(DB)
Parameters: |
DB
Required. An ODBC value for the ODBC database as returned by ODBCConnect.
Comments: none.


ODBCRollback

(Engine-Level Function)

Description: | Indicates to a specified ODBC-compliant database that a transaction is to be rolled back (discarded).
Returns: | Nothing (return values in parameters)
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBCBeginTrans | ODBCCommit | TODBCBeginTrans | TODBCCommit | TODBCRollback
Format: | ODBCRollback(DB [, ErrorMsg, SQLState, ErrorCode])
Parameters: |
DB
Required. An ODBC value for the specified ODBC database as returned by ODBCConnect.
ErrorMsg
A descriptive error or status message, returned by the function. If valid, both ErrorMsg and SQLState will be valid.
SQLState
A 5-character SQL State code. SQL State codes are defined by Microsoft and by the vendor of each ODBC driver.
ErrorCode
An unsuccessful operation always returns a non-zero value, which is a numeric error code specific to the DBMS vendor's ODBC driver or Microsoft's ODBC Driver Manager.
A successful operation will always return a 0. ErrorMsg and SQLState may or may not be set valid in the event of a successful connection. If set valid, they should be examined for relevant status information.
Comments: Discards a transaction defined as all the SQL statements executed on an ODBC-compliant database since the transaction began.
If any error, no matter how minor, occurs as a result of the statement, and the TODBCConnect or ODBCConnect that connected to the database had its Disconnect parameter set to true, the value of DB will become invalid (i.e. the connection to the database will be dropped).

Example:

[
  ODBCBeginTrans(DB);
  ODBC(DB, "DELETE * FROM TEST");
  ODBC(DB, "INSERT INTO TEST VALUES('KeyString', 'Value')");
  ODBCRollback(DB);
]


ODBCSources

(Engine-Level Function)

Description: | Retrieves a list of ODBC data sources and returns it as a dynamically allocated array.
Returns: | Array
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBC | ODBCConfigureData | ODBCConnect | ODBCDisconnect | ODBCStatus | ODBCTables | TODBC | TODBCConnect | TODBCDisconnect
Format: | ODBCSources()
Parameters: | None
Comments: | The return value is a pointer to a two-dimensional array, which contains a list of ODBC data sources. The first row of the array ([0][N]) contains the data source names, while the second describes the driver. 64-bit VTScada only... The returned list will include both 32-bit and 64-bit data sources.

Example:

If ! Valid(sources);
[
  sources = ODBCSources() { Find the list of sources };
  count = ArraySize(sources, 1) { The number of sources };
]

This will obtain the list and number of ODBC data sources.


ODBCStatus

(Engine-Level Function)

Description: | Returns the requested information about the last ODBC statement to execute.
Returns: | Varies - see comments
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBC | ODBCConfigureData | ODBCConnect | ODBCDisconnect | ODBCSources | ODBCTables | TODBC | TODBCConnect | TODBCDisconnect
Format: | ODBCStatus(Option[, ODBCHandle])
Parameters: |
Option
Required. Any numeric expression for the option to indicate what information is desired about the last ODBC statement executed as follows:
Option | Information desired
0 | Return 0 if information or 1 if error
1 | SQL state text
2 | Native error code
3 | ODBC error text
4 | Error text length
ODBCHandle
Optional ODBC Handle value, as returned from ODBCConnect or TODBCConnect, for which you want a status report.
Omitting the ODBCHandle parameter returns a status report for the last ODBC operation that was executed. As ODBC operations can be concurrently executed, there is no guarantee that this is the operation for which you intend to obtain status, unless you explicitly provide an ODBC handle value
Comments: The return value for this function may be a single value, an array of values (if more than one error was generated), or invalid (if the last ODBC operation did not generate any status information).
This function may be used with threaded ODBC calls, however, if multiple ODBC calls are executing simultaneously, there is no indication as to which one generated the message.


ODBCTables

(Engine-Level Function)

Description: | Retrieves a list of the tables present in an ODBC-compliant database and returns it as a dynamically allocated array.
Returns: | Array
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | ODBC | ODBCConfigureData | ODBCConnect | ODBCDisconnect | ODBCSources | ODBCStatus | TODBC | TODBCConnect | TODBCDisconnect
Format: | ODBCTables(DB [, Search, TableType, Timeout, MaxResults, HasMore])
Parameters: |
DB
Required. An ODBC value for the ODBC database as returned by ODBCConnect.
Search
Optional. Any text string indicating the pattern to match for table names.
If this parameter is omitted, the search pattern defaults to "%", where the percent sign is the SQL wildcard (i.e. all table names are returned).
TableType
Optional. List of table types to match. Parameters include the following:
"TABLE", "VIEW", "SYSTEM TABLE",..., or a data source-specific type name.
Timeout
Optional. Sets the period (in seconds) that the driver will wait for the request to complete.
The default value of "0" indicates that there is no timeout. See comments.
MaxResults
Optional. Specify the maximum number of tables to be returned.
If this is Invalid or less than 0, there is no limit. See comments.
HasMore
Optional. If the request would return more than MaxResults results, this output parameter gets set to TRUE. Otherwise it will be set to FALSE.
Comments:

If TableType is not an empty string, it must contain a list of comma-separated values for the types of interest. Each value may be enclosed in single quotation marks (') or unquoted for example, 'TABLE', 'VIEW' or TABLE, VIEW. An application should always specify the table type in uppercase. If the data source does not support a specified table type, no results will be returned for that type.

ODBCTables will stall the calling thread while it executes. Consider calling it from a separate script thread that doesn't need to remain responsive.

For Timeout, Please note:

Not all ODBC drivers support the optional Timeout parameter. (In particular, the Microsoft Access (.mdb) driver). If the driver does not support the option, it will have no effect.

Example:

If 1 Next;
[
  tables = ODBCTables(dBase, "Analog%");
]

This will obtain the list of all tables in the database beginning with the string "Analog".


OffNormal

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | This subroutine will activate the alarm. However, it will not affect the unacknowledged status.
Returns: | Numeric
Function Groups: | Alarm
Usage: | Script Only.
Related to: | Register (Alarm Manager) | CurrentTime
Format: | \AlarmManager\OffNormal(AlarmObject[, EventTime]);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine.
EventTime
Optional. The time stamp to use when adding this event to the alarm lists. If invalid or not defined, the default is CurrentTime().
Comments: The OffNormal subroutine always returns "0".


OilVolumeCorrectionFactor

(Function Library)

Description: | Returns a coefficient to adjust a volume of oil to different temperature and pressure conditions.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Oil & Gas
Related to: |
Format: | OilVolumeCorrectionFactor(FluidType, Alpha60In, RhoIn, TRhoIn, PRhoIn, TAltIn, PAltIn[, ErrorTag])
Parameters: |
FluidType

Required numeric. An integer to identify the commodity group as follows:

  • 0 for Crude Oil
  • 1 for Refined Liquids
  • 2 for Lubricating Oil
  • 3 for Special Fluids
Alpha60In
Optional numeric. A thermal expansion factor that is required for special fluids, where FluidType is 3.
RhoIn
Required numeric. The observed density of the fluid in kg per meter cubed.
TRhoIn
Required numeric. The temperature in °F at which the density of the fluid is observed.
PRhoIn
Required numeric. The pressure in psig at which the density of the fluid is observed.
TAltIn
Required numeric. The temperature in degrees F of the fluid for the volume correction.
PAltIn
Required numeric. The pressure in psig of the fluid for the volume correction.
ErrorTag

Deprecated - for diagnostics at configuration time only, not for operations.

An optional tag object that will be set to the error value. Error values include:

0 | No error
1 | Fluid type outside range
2 | Thermal expansion factor required but not specified
3 | Density outside range
4 | TRholn outside range
5 | PRholn outside range
6 | TAltln outside range
7 | PAltln outside range
8 | Rho60ln outside range
9 | Too many iterations
Comments:

The function computes an oil volume correction factor based on the American Petroleum Institute Manual of Petroleum Measurement Standards Chapter 11.1.6.

This factor is used to correct a volume from a set of observed conditions to a set of alternate conditions due to changes in temperature and pressure. Note that if the observed density is given at a set of conditions different from the current conditions, the function will be need to be evaluated twice. Once to determine the volume correction to the density conditions, and again to determine the volume correction from the density conditions to the alternate conditions.

For simple volume corrections from observed conditions to base conditions (60°F,0psig) use OilVolumeCorrectionToBase.


OilVolumeCorrectionToBase

(Function Library)

Description: | Wrapper for OilVolumeCorrectionFactor, used to determine the volume correction factor for shifting a fluid at alternate conditions to standard conditions (60°F, 0 psig).
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Oil & Gas
Related to: | OilVolumeCorrectionFactor
Format: | OilVolumeCorrectionToBase(FluidType, Alpha60In, Rho, T, P[, ErrorTag])
Parameters: |
FluidType

Required numeric. An integer to identify the commodity group as follows:

  • 0 for Crude Oil
  • 1 for Refined Liquids
  • 2 for Lubricating Oil
  • 3 for Special Fluids
Alpha60In
Optional numeric. A thermal expansion factor that is required for special fluids, where FluidType is 3.
Rho
Required numeric. The density of the fluid at base conditions (60°F,0psig).
T
Required numeric. The current temperature of the fluid in °F.
P
Required numeric. The current pressure of the fluid in psig.
ErrorTag

Deprecated - for diagnostics at configuration time only, not for operations.

An optional tag object that will be set to the error value. Error values include:

0 | No error
1 | Fluid type outside range
2 | Thermal expansion factor required but not specified
3 | Density outside range
6 | Temperature T outside range
7 | Pressure P outside range
Comments:

The function computes an oil volume correction factor based on the American Petroleum Institute Manual of Petroleum Measurement Standards Chapter 11.1.6.1. This factor is used to correct a volume from an alternate set of conditions to base conditions (60°F, 0 psig).

This function uses the more generic OilVolumeCorrectionFactor to compute the volume correction factor from base conditions to alternate conditions and then inverts the answer.

For oils where the density is provided at conditions other than base, use OilVolumeCorrectionFactor.


OkToWrite

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns true if a user is permitted to control a particular tag on a particular workstation.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: |
Related to: | CanControl (Control Lock Manager) | CanControl (Control Token Manager) | Set
Format: | \OkToWrite([SecurityPrivilege, Feedback, EnableOutput, TagObj, DisableControl])
Parameters: |
SecurityPrivilege
Optional integer. The tag's custom security privilege, if it has one. Most often set to \Root.SecurityBit. Whether or not this is provided, the user must also have the Control Outputs privilege.
Feedback
Optional Boolean. TRUE to allow a feedback dialog to appear if permission cannot be granted. FASLE to suppress the dialog. Defaults to FALSE.
EnableOutput
Optional Boolean. TRUE if the I/O tag has its output capability is enabled. Most often set to \Root.EnableOutput. Defaults to TRUE.
TagObj
Optional tag object. The I/O tag being controlled. Defaults to the calling tag
DisableControl
Optional. TRUE to disable control. Most often set by the widget according to its own internal logic or parameters. Defaults to FALSE.
Comments:

All widgets that are used for writing a value to a PLC or storing a value in a memory tag should call OkToWrite prior to calling the tag's Set() module. It can also be called in steady state to determine whether to visually enable or disable the widget's graphics.

Permission is granted based on several factors including user security, tag configuration, read-only-workstation configuration, realm filtering, control locks and control tokens.

If OkToWrite is to be used as a Called module (such as, within a widget) FeedBack must be False, otherwise the Popup dialog would show by switching users or pages, which is not the intent.

Example 1:

  If WinButton();
  [
    IfThen(\OkToWrite(\Root.SecurityBit, TRUE, \Root.EnableOutput, \Root, DisableControl),
      \Root.Set(Value);
    );
  ]

Example 2:

  EnableButton = \OkToWrite(\Root.SecurityBit, FALSE, \Root.EnableOutput, \Root, DisableControl)
  If WinButton(232, 148, 412, 100,
               0                    { normal appearance },
               Concat("Press Me ", ButtonPresses) { label },
               EnableButton         { focus id enables button },
               0                    { default system font },
               ToggleVal            { monitor state});
  [
  [
    \Root.Set(Value);
  ]


Ones

(Engine-Level Function)

Description: | Returns the number of bits set in an integer number.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Bitwise Operation
Related to: | Bit | SetBit
Format: | Ones(Value)
Parameters: |
Value
Required. Any numeric expression.
Comments: Value must be a valid number, truncated to an integer, whose absolute value lies in the range of 0 to 9223372036854775807 (This is the largest 64-bit signed integer.) The number of bits set is returned.

Examples:

a = Ones(0b010110);
b = Ones(0b001100);
c = Ones(2.3);

The values of a, b and c will be 3, 2 and 1 respectively.


OpChange

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper for TagMigrator\OpChange. Performs an immediate deploy of a single tag change without disturbing any other tag changes already in place on the local branch. The tags must already exist.
Returns: | Object value of the worker module.
Usage: | Script Only.
Function Groups: | Configuration
Related to: | SimpleOpChange | GetTagConfiguredParameters | ModifyTags
Format: | \OpChange(TagName, ParmsDict, User[, Comment, Merge])
Parameters: |
Tagname
Required. The name of the tag to be changed.
ParmsDict

Required. A dictionary of tag parameters to change.
The keys are parameter names and the values are the parameter values. For example:

{
  "Address": 40001,
  "Questionable": 0
}
User
Required. The user responsible for the operational change.
Comment
Optional text. A descriptive comment about the change.
Merge
Optional Boolean. Defaults to TRUE. Controls whether the parameters are to be merged with the existing tag's parameters. If false, the parameters replace the tag's parameters and are expected to contain user and timestamp metadata.
Comments:

If your application is set to auto-deploy, then OpChange and ModifyTags accomplish the same result.
If auto-deploy is not set, then there is a difference in the result of the two functions. ModifyTags makes a tag change locally, whereas OpChange will immediately deploy that tag change. Running a deploy operation after ModifyTags' change, results in the entire tag file (and all the included tags and their parameters) being deployed. OpChange is able to deploy just the one change to the one tag within the file, leaving other modified tags in that file as local changes.

OpChanges are used for any tag change that is expected to be performed during systems operation, as opposed to changes made during configuration. The example is an operator changing a tag's questionable status by using the context menu rather than opening the configuration dialog.

When called with the Merge==FALSE parameter it is possible to revert a tag parameter to its default or remove an override using the API GetTagConfiguredParameters. If OPChange is called with Merge=FALSE without using this API, there is no way to remove some configured parameters while keeping others. To make changes to some configured parameters, called GetTagConfiguredParameters, modify the dictionary of parameters (add/modify/remove), then pass the modified dictionary into a call to OPChange.


OPCServer

(Engine-Level Function)

Description: | Adds a new top-level branch to the VTScada OPC Server’s namespace hierarchy.
Returns: | Handle - see comments
Usage: | Steady State only.
Function Groups: | Network
Related to: | SetOPCData
Format: | OPCServer(BranchName, CallbackContext)
Parameters: |
BranchName
Required. The name of the branch added at the highest level of the hierarchy.
CallbackContext
Required. The object value of a running module containing some or all of the following callback modules (these callback modules must be implemented by the programmer).

In each case the Item ID passed to the callback will *not* contain the top-level branch name specified in the call to OPCServer.
Modules:

OPCGetItemAttributes(itemID) - Given an OPC item ID, returns a structure containing the attributes of the item. Structure format:

ItemAttributes STRUCT [
        AccessRights;
        Type;
        HasChildren
 ];

Where:

AccessRights is one of the following values:

1 = READABLE,

2=WRITEABLE,

3= READWRITEABLE

Type is the COM data type of the item value:

2 = VT_I2,

3 = VT_I4,

5 = VT_R8,

8 = VT_BSTR,

11 = VT_BOOL

HasChildren is one of the following values:

0 = has no children,

1 = has children

OPCGetChildNodes(itemID) - Given an OPC item ID, returns an array of strings that are the names of child items.

OPCReadItem(itemID) - Given an OPC item ID, returns a structure containing the value, quality and UTC timestamp of the item. Structure format:

OPCVQT Struct [
    Value;
    Quality;
    Timestamp;
  ];

OPCWriteItem(itemID, Value) -- Given an OPC item ID and a value, attempts to write the value to the item.

OPCGetInternalName(itemID) - Given an OPC item ID, returns the internal name used for that item. This is useful for the case when two or more different item Ids might refer to the same internal "item".

OPCGetProperties(itemID) - Given an OPC item ID, returns an array of structures describing the properties found on that item. Structure format:

  OPCProperty Struct [
    ID             { Property ID number                     };
    Type           { Data type of the property              };
    Name           { Name of the property                   };
    Description    { Description of the property            };
    InvalidMeansBadQuality  { TRUE to indicate that an invalid
 property value implies Bad quality data                     };
  ];

OPCGetPropertyValue(itemID, propertyID) - Given an OPC item ID and a numeric property ID, returns the current value of the specified property.

Comments: This function returns a handle to the OPC server namespace branch (to be used in calls to SetOPCData).

Example:

<
{==================== SimulateOPCServer =====================}
{ This module runs a simulated OPC server.                 }
{============================================================}
SimulateOPCServer
(
  ServerName;
)
[
  OPCGetChildNodes          Module;
  OPCGetPropertyValue       Module;
  OPCGetProperties          Module;
  OPCReadItem               Module;
  OPCWriteItem              Module;
  OPCGetInternalName        Module;
  OPCGetItemAttributes Module;

  CONSTANT OPC_QUALITY_BAD = 0x00;
  CONSTANT OPC_QUALITY_UNCERTAIN = 0x40;
  CONSTANT OPC_QUALITY_GOOD = 0xC0;

  CONSTANT VT_EMPTY = 0;
  CONSTANT VT_NULL  = 1;
  CONSTANT VT_I2    = 2;
  CONSTANT VT_I4    = 3;
  CONSTANT VT_R4    = 4;
  CONSTANT VT_R8    = 5;
  CONSTANT VT_CY    = 6;
  CONSTANT VT_DATE  = 7;
  CONSTANT VT_BSTR  = 8;
]

ServerOn [
  OPCServer(ServerName, Self());
]

<
OPCGetChildNodes
(
  itemID;
)
[
  returnVal = 0;
]

Main [
  If watch(1);
  [
    IfThen(itemID == "",
      returnVal = New(1);
      returnVal[0] = "tags";
    );
    IfThen(itemID == "tags",
      returnVal = New(7);
      returnVal[0] = "ai1";
      returnVal[1] = "ai2";
      returnVal[2] = "NeverSet";
      returnVal[3] = "TextTag";
      returnVal[4] = "ao1";
      returnVal[5] = "AnalogInputs";
      returnVal[6] = "ao2";
    );

    IfThen(itemID == "tags\AnalogInputs",
      returnVal = New(1);
      returnVal[0] = "ai1";
    );
    Return(returnval);
  ]
]
>

<
OPCGetPropertyValue
(
  itemID;
  propertyID;
)
[
  returnVal;
]
Main [
  If watch(1);
  [
    IfThen(propertyID == 5555,
      returnVal = 888;
    );
    IfThen(propertyID == 104,
      returnVal = 99.5;
    );
    IfThen(propertyID == 5000,
      returnVal = "TestArea";
    );
    Return(returnVal);
  ]
]
>

<
OPCGetProperties
(
  itemID;
)
[
  returnVal;
  I;
  OPCProperty Struct [
    ID                { Property ID number             };
    Type              { Data type of the property      };
    Name              { Name of the property           };
    Description       { Description of the property    };
  ];

  OtherStruct Struct [
    TestComment;
    Name;
    ItemHandles;
    Value;
    Quality;
    Timestamp;
  ];
]
Main [
  If watch(1);
  [
      IfThen(itemID == "tags\ai1",
        returnVal = New(3);
        I = 0;
        returnVal[I++] = OPCProperty(104, VT_R8, "HighRawValue",
   "High Instrument Range");
        returnVal[I++] = OPCProperty(5000, VT_BSTR, "Area", "Area");
        returnVal[I++] = OPCProperty(5555, VT_I2, "Type",
                                     "myVTSProp");
      );
      IfThen(itemID == "tags\ai2",
        returnVal = 0;
      );
    Return(returnVal);
  ]
]
>

<
OPCWriteItem
(
  itemID;
  Value;
)
Main [
  If watch(1);
  [
   { Do a write to the specified item. }
    Return(0);
  ]
]
>

<
OPCGetInternalName
(
  itemID;
)
[
  retval;
]

Main [
  If watch(1);
  [
    IfThen(itemID == "tags\ai1",
      retval = "ai1";
    );
    IfThen(itemID == "tags\ai2",
      retval = "ai2";
    );
    IfThen(itemID == "tags\TextTag",
      retval = "TextTag";
    );
    IfThen(itemID == "tags\ao1",
      retval = "ao1";
    );
    IfThen(itemID == "tags\ao2",
      retval = "ao2";
    );
    IfThen(itemID == "tags\AnalogInputs\ai1",
      retval = "ai1";
    );

    Return(retval);
  ]
]
>

<
OPCReadItem
(
  itemID;
)
[
  returnVal;

  OPCVQT Struct [
    Value;
    Quality;
    Timestamp;
  ];

]
Main [
  If watch(1);
  [
    ReadItemTimestamp = CurrentTime();

    IfThen(itemID == "tags\NeverSet",
      returnVal = OPCVQT("NeverSetValue",
                         OPC_QUALITY_UNCERTAIN,
                         ReadItemTimestamp + TimeZone(0));
    );

    Return(returnVal);
  ]
]
>

<
OPCGetItemAttributes
(
  itemID;
)
[
  retval;

  Constant OPCACCESS_READABLE      = 1;
  Constant OPCACCESS_WRITEABLE     = 2;
  Constant OPCACCESS_READWRITEABLE = 3;

  ItemData Struct [
    AccessRights      { Property ID number            };
    Type              { Data type of the property     };
    HasChildren;
  ];
]

Main [
  If watch(1);
  [
    IfThen(itemID == "tags\ai1",
      retval = ItemData(OPCACCESS_READABLE, VT_I4, 0);
   );
    IfThen(itemID == "tags\ai2",
      retval = ItemData(OPCACCESS_READABLE, VT_R8, 0);
    );
    IfThen(itemID == "tags\TextTag",
      retval = ItemData(OPCACCESS_READWRITEABLE, VT_BSTR, 0);
    );
    IfThen(itemID == "tags\ao1",
      retval = ItemData(OPCACCESS_READWRITEABLE, VT_R8, 0);
    );
    IfThen(itemID == "tags\ao2",
      retval = ItemData(OPCACCESS_READWRITEABLE, VT_I4, 0);
    );
    IfThen(itemID == "tags\AnalogInputs\ai1",
      retval = ItemData(OPCACCESS_READABLE, VT_I4, 0);
    );
    IfThen(itemID == "tags\NeverSet",
      retval = ItemData(OPCACCESS_READABLE, VT_BSTR, 0);
    );

{ The following elements are just structural - they have no data }
    IfThen(itemID == "", { A top-level name }
      retval = 0;
    );
    IfThen(itemID == "tags",
      retval = 0;
    );
    IfThen(itemID == "tags\AnalogInputs",
      retval = 0;
    );

    Return(retval);
  ]
]
>

{ End of SimulateOPCServer\CallbacksParent }
>

{ End of SimulateOPCServer }
>


Or

(Engine-Level Function)

Description: | Performs a bit-wise OR operation and returns the result.
Returns: | Signed 64-bit integer
Usage: | Script or steady state.
Function Groups: | Bitwise Operation
Related to: | Not | XOr | And
Format: | Or(Parm1, Parm2[, Parm3...])
Parameters: |
Parm1, Parm2[, Parm3 ...])
Required. Any number of numeric expressions. The expressions will be truncated to 32 bit unsigned integers.
Comments:

The OR operation takes two binary numbers and compares their bits. Each corresponding bit in the result is 1 if at least one of the corresponding bits is 1. If both bits are 0, the corresponding bit in the result is 0.

This function takes signed 64-bit integers values. If a number is passed outside the range of a signed 64-bit integer, then the function will return invalid. If Value is invalid, the return value is invalid.

(See: Bitwise Parameters & Operations)

Example:

newVal = Or(0b1010, 0b1100);

The value of newVal will be 0b1110.


Out

(Engine-Level Function)

Deprecated. This function relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.

Description: | Writes an 8 bit byte to an I/O port.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Memory I/O
Related to: | In | InWord | OutWord
Format: | Out(, Value)
Parameters: |
Port
Required. Any numeric expression giving the I/O address of the port to write. Port must be in the range 0 to 65535.
Value
Required. Any numeric expression giving the byte to write. Value must be in the range 0 to 255.
Comments: This function requires that the VTSIO driver be installed.
If Port or Value is out of range or invalid, nothing is written. If this statement appears in a state, Value is written when its value changes. If it is in a script, Value is written when the script is executed.

Example:

Out(0x300, reg);

This writes reg to CPU output port 300 (hex).


Output

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Places formatted numbers or text on the screen.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Format | GUIText | TextAttribs | ZText
Format: | Output(X, Y, Type, Width, Precision, Value, Foreground, Fill, Background, Size, Obsolete)
Parameters: |
X
Required. Any numeric expression giving the X screen coordinate of the lower left corner of the number or text on the screen.
Y
Required. Any numeric expression giving the Y screen coordinate of the lower left corner of the number or text on the screen.
Type
Required. Any numeric expression giving the type of the data to display. The valid values for this parameter are:
Type | Data Type
1 | Short
2 | Long
3 | Float
4 | Text
5 | Binary
6 | Octal
7 | Hexadecimal

Status variables can be output using a Type value of 1 that will produce either a 0 or 1 on the screen. The type of the Value parameter does not have to match the Type parameter, except for text.

Width
Required. Any numeric expression giving the minimum number of characters to display. If fewer characters are required to produce the output, the area is filled with blank spaces on the left to make up the required number of characters. This is useful for aligning numbers up on the right. If more characters are required than the Width parameter specifies, the extra characters are extended to the right.

By making Width zero, the output will be aligned on the left. If the Width parameter is greater than or equal to 100 and the Type parameter is 3, the format of the floating point number displayed is in the most compact form which may be in exponential form if the exponent is less than -4 or is greater than the specified Precision parameter.

The actual width used in this mode is 100 less than the specified width. Trailing zeroes are not displayed in this mode. Values of Width outside the range of 0 to 255 inclusive are invalid.
Precision
Required. Any numeric expression giving the precision of the output. This has different meanings for the different output types.

For types 1 and 2 (short and long), it gives the minimum number of digits to appear. If fewer digits are required to display the number, leading zeroes are added to the number.

For type 3 (float), it gives the number of digits to appear after the decimal point if Width is less than 100. If Width is greater than or equal to 100, it specifies the maximum number of significant digits to appear.

For type 4 (text), it gives the maximum number of characters to display. If the string is longer than this parameter, only the number of characters given by the Precision parameters are displayed.

Note: Values of Precision outside the range of 0 to 255 are invalid.
Value
Required. Any numeric or text expression giving the value to display. If the Type is 4, this value may only be a text expression. Otherwise, this value is not required to have the same type as specified by the Type parameter - VTScada does the conversion.
Foreground
Required. Any numeric expression giving the color of the characters to display.
Fill
Obsolete - set to zero.
Background
Required. Any numeric expression giving the color of the background area for the output characters.
Size
Required. Any numeric expression giving the height of the characters in units of Y screen coordinates. If this value results in a specification of less than 12 screen pixels high, the text will be the small text (8 pixels high). Otherwise, the text will be the large text. If Size is negative, it will be interpreted as a dot text output of size equivalent to the absolute value of the size. The number will be displayed to the nearest multiple of the base 8 pixel by 8 pixel text. This produces faster, non-destructive large characters than the normal large text characters.
Obsolete n/a
No longer used, but is maintained for backward compatibility with previous versions of VTScada. Set to 0.
Comments: Should not be used for new code. Maintained for backward-compatibility only. This statement is the general statement for displaying numbers and text on the screen. For small characters, or large characters with a negative Size, the statement is non-destructive (can change without destroying the underlying image). Large character output is destructive. For non-destructive out put, care must be taken when choosing the colors on a colored (non-zero) background since the characters are exclusive ORed with the background. This gives a more general method of displaying text than the Text statement but requires more parameters.


OutWord

(Engine-Level Function)

Deprecated. This function relies on the VTSIO driver, which is no longer included in new installations. Will continue to function in legacy installations but should not be used in new code.

Description: | Writes a 16 bit word to an I/O port.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Memory I/O
Related to: | In | InWord | Out
Format: | OutWord(Port, Value)
Parameters: |
Port
Required. Any numeric expression giving the I/O address of the port to write. Port must be in the range 0 to 65535.
Value
Required. Any numeric expression giving the word to write. Value must be in the range 0 to 65535.
Comments: This function requires that the VTSIO driver be installed.
This function writes a 16 bit unsigned value to a CPU I/O port. If this statement appears in a state, Value is written when its value changes. If it is in a script, Value is written when the script is executed.

Example:

OutWord(0x300, reg);

This writes reg to I/O port 300 (hex).


OwningModule

(Engine-Level Function)

Description | Returns the module which contains a certain variable.
Warning | This function should be used by advanced users only.
Returns | Module
Usage | Script or steady state.
Function Groups | Compilation and On-Line Modifications, Advanced Module
Related to: | FindVariable
Format: | OwningModule(Variable)
Parameters |
Variable
Required. Any expression for the variable value.
Comments None


P Functions

The sections that follow identify all VTScada functions beginning with "P".


Pack

(Engine-Level Function)

Description: | Serializes an array of data or a set of parameters to the object parameter into a stream
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Advanced Module, Stream and Socket
Related to: | Unpack | BuffStream | TempFileStream
Format: | Pack(Data, Start, End, StreamVarPtr, KeyDictionary)
Parameters: |
Data
Required. An object value, an array, or a structure. Contains the data or the object value of the module whose parameters are to be packed.
For example, if you have 5 numeric values to pack, you would allocate a 1-dimensional array, 5 elements in length. You would then assign the 5 numerics to this array's elements, and pass the array to this parameter. You would specify that you wish to pack from subscript 1 to 5. Refer to the example section for more information.
Start
Required. The starting array index (zero-based), or parameter number (one-based) of the data to pack.
End
Required. For arrays this is the last array index. For parameters, it is the parameter number of the data to pack. If packing a structure rather than an array, this must be the number of elements rather than the final index.
StreamVarPtr
Required. A pointer to a variable holding the stream into which the data will be packed. The variable can also hold Invalid - see Comments section for more details.
KeyDictionary

Optional. A dictionary that maps structure names to a number that will represent the structure in the packed stream. Within the dictionary, the key is the structure name and the value is the assigned number.

There is no requirement for the Pack KeyDictionary parameter and the Unpack MirrorKey parameter to have the same number of elements. All that is required is that the Unpack MirrorKey dictionary has all of the structures that are in that particular packed stream. If the KeyDictionary doesn’t have the structure that was packed, the returned data is a simple array rather than a structure.

If KeyDictionary is not used at all, structures packed using Pack() will also include additional data to allow UnPack to generate an equivalent structure. So use the KeyDictionary mechanism if you need to avoid the associated code bloat.

Comments: Pack() is recursive. If the values contain arrays, then those are packed and so on.

StreamVar must be a pointer to a variable, not simply the name of a variable that holds a stream. This is because the Pack function will create a new stream under certain circumstances and store the packed data in it.

If the variable that StreamVarPtr addresses contains a stream, then the data will be packed into that stream.
If the variable that StreamVarPtr addresses contains Invalid, Pack will create a new buffer stream, pack the data into it and store the new stream in the variable pointed at by StreamVarPtr.
If a buffer stream is supplied, or Pack creates a buffer stream, it will be replaced by a temporary file stream if the output stream exceeds 2Mb. This provides a balance between performance and memory use.
If a stream is provided, packing starts at the current stream position. After packing, the stream current position is left at the end of the packed data.
Only variables of numeric, text, or stream types will be packed. Arrays of those types, up to and including 3 dimensions, will also be packed.

Any illegal values are packed as Invalid. Further, the Pack function has been designed in such a way that multidimensional arrays that have not had a value assigned can be handled. After the stream is unpacked, the array elements are allocated, but are assigned Invalid.

Generally called in the form:

Pack(Self(), 1, NParm(Self()), &Stream);

This works because NParm(Self()) equals the highest index.

Example:

Pack(Self, 2, 2, &Stream);  { Pack only the second parameter }
Pack(Array, 1, 1, &Stream); { pack only the second array item }

Example: Multi-dimensional array

If you wish to pack 2 3-dimensional arrays, you would allocate a 1-dimensional array, 2 elements in length. You would then assign the 3-dimensional arrays to the 1-dimensional array elements, and then Pack the 1-dimensional array.

Array1D = New(2);
Array1D[0] = Array3D_1;
Array1D[1] = Array3D_2;
Pack(Array1D, 0, 1, &Stream);

Unpacking this is almost an identical operation:

Array1D = New(2);
UnPack(Array1D, 0, 1, Stream);
Array3D_1 = Array1D[0];
Array3D_2 = Array1D[1];

All you need to know is how many things you wish to pack and unpack, not the sizes or types of the things (a ValueType(Array1D[0]) will tell you the type). As the stream position is moved after each pack or unpack, you can simply unpack one item at a time and check the return value of UnPack.

Example: KeyDictionary

In this example, the presence of a Key parameter allows the example to be packed into a stream that is less than half the size that would be obtained without the Key parameter. (Exact number depending on the names used in the structure definitions.)

"Record", "Values", and "AA_Info" are all STRUCTs.

Rec = Record( GetGUID(1)             { GUID       },
              1                      { Priority   },
              Values(87, 54, "feet") { Values     },
              System.MakeDictionary("AA",
                             AA_Info("AAData1", 2)) { Extensions });

{ Omitted: Place record in ArrayToPack }

Key = System.MakeDictionary("Record", 0,
                             "Values", 1,
                             "AA_Info", "AA")

Pack(ArrayToPack, 0, 0, &PackStream, Key);

{ Omitted: Rewind stream }

MirrorKey = System.MakeDictionary("0", Record,
                                   "1", Values,
                                   "AA", AA_Info));

UnPack(UnpackedArray, 0, 0, PackStream, Invalid, Invalid, MirrorKey);


PackParms

(RPC Manager Library)

Description: | This method packs supplied parameters into a stream. Subroutine call only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Network, Stream and Socket
Related to: | UnpackParms
Format: | \RPCManager\PackParms(Stream [, P1, P2, …]);
Parameters: |
Stream
Required. The initial packed RPC stream. The parameters provided in parameters P1, P2, etc. will be packed and appended onto this stream. If Invalid, a new BuffStream will be created to hold the packed parameters.
P1, P2, …
Optional parameters that will be packed into the stream. Up to 100 parameters are allowed.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
The stream contents can be unpacked into variables using the UnpackParms method. The parameters can be any of the permitted RPC data types. If a parameter is provided which is other than one of those data types, an Invalid is packed in its place.

Related information:

RPC Manager Service


PackRPC

(RPC Manager Library)

Description: | Packs an RPC call and a set of parameters into a stream. Subroutine call only.
Returns: | BuffStream
Usage: | Script Only.
Function Groups: | Network, Stream and Socket
Related to: | RunPack
Format: | \RPCManager\PackRPC(Stream, ModuleName, Scope [, Parameters]);
Parameters: |
Stream
Required. The initial packed RPC stream. The RPC specified in this call will be appended onto the end of this stream. If Invalid, a new BuffStream will be created to hold the RPC.
ModuleName
Required. The textual name of the RPC subroutine to be executed. Must be valid.
ModuleContext
Required. The context in which the "ModuleName" will be executed. The "base" context for a VTScada layer-based application is "Code". For a non-VTScada (pure script) application, the base context is "\System". Must be valid.
Parameters
Required. A set of up to 32 parameters to the RPC subroutine. Can be any mixture of the legal types. Supplying a parameter of an illegal type will cause it to be replaced with Invalid when the RPC subroutine is invoked.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
The return value from this method is a BuffStream containing the original contents as specified in the Stream parameter with the new RPC appended. This can be used to build a stream of RPCs for transmission as one atomic unit.

Related information:

RPC Manager Service


PAddressEntry

(Dialog Library)

Description: | To be used for Tag I/O address entry. Checks whether the attached driver has an AddressAssist module and uses that if available. Otherwise, presents a standard edit field into which the I/O address may be entered.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | AddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName |PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PAddressEntry(ParmNum, IODevice, SupportedData, FunctionType, Title, FocusID[, Trigger, DrawBevel, MinVal])
Parameters: |
ParmNum
Any numeric expression giving the parameter number (from 0) in the caller to alter.
IODevice
Any expression for the object value of the I/O device driver being used.
SupportedData

A bitwise expression, indicating the data type.

(See: Bitwise Parameters & Operations)

Bit | Meaning when set
0 | Digital
1 | Analog
2 | Text
FunctionType
A Boolean expression controlling whether the function should be read (FALSE) or write (TRUE).
Title
Any text expression to use as the title for the field.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
A parameter whose value is derived from ZEditField and can therefore be set to "0" (internal buffer changed), "1" ("Enter" key pressed), or "2" (focus lost). If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.
DrawBevel
Any logical expression. If TRUE, a bevel is drawn around the graphic.
MinVal
Optional. Any expression giving the minimum value or minimum number of characters to be accepted by the edit field (depending on the data type).
This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value less than LowLimit is entered in the field (or there are too few characters, in the case of text value), the variable set by the field will revert to the previous value. No default:
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

PAddressEntry should not be used with the AnalogStatus tag as that tag stores Address, History Address and History Scan Rate together in one parameter. Use AddressEntry instead.

Usual height of the GUITransform: 45 - 55 pixels.

Example:

{***** Address *****}
GUITransform(30, 160, 230, 115,
  1, 1, 1, 1, 1            { No scaling                     },
  0, 0, 1, 0               { No movement; visible; reserved },
  0, 0, 0                  { Not selectable                 },
  \DialogLibrary.PAddressEntry(\#Address    { Parm number            },
          Scope(\Root, Parms[\#SitePoint])  { IO Device              },
          0b010                             { SupportedData: Analog  },
          TRUE                              { FunctionType:  Write   },
          \GetPhrase("AddressLabel")        { Title                  },
          TRUE                              { Focus ID               },
          Trigger                           { trigger                }));


PAlmPriority

(Dialog Library)

Description: | Draws a droplist of the currently available alarm priorities with an optional title and bevel.
Returns: | Image handle
Usage: | Steady State only.
Function Groups: | Alarm
Related to: | GUITransform | PAddressEntry | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName |PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PAlmPriority(ParmNum, Title[, AlignTitle, FocusID, Trigger, Init, DrawBevel, VertAlign])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
Required. Any text expression to be used as a title for the droplist.
AlignTitle
Optional. Any logical expression. Indicates the title alignment such that if it is TRUE (non-zero), the title is included in the calculation for vertical alignment. If FALSE (0), it is added to the droplist after it, and its bevel (if one exists) has been vertically aligned.
The default is TRUE.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Optional. Any logical expression. A variable whose value is set to true (1) when the ParmNum parameter's value has been set by the droplist. The setting of the parameter will not cause Trigger to be set.

If this information is not required, a constant may be used.
Init
Optional. Any expression for the initial value displayed in the field. The default value is Data[Index]. If Index is invalid, then the droplist will initially appear blank.
DrawBevel
Optional. Any logical expression. If TRUE (non-0), a bevel is drawn around the droplist. If FALSE (0), no bevel is drawn. The default value is TRUE.
VertAlign
Optional. Any numeric expression that sets the vertical alignment of the unopened droplist according to one of the following:
Value | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle.
The default value is 0.

Comments:

This module is a member of the VTScada Dialog Library, and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
The "P" tools are intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.
This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the text string displayed in the selected line of the droplist.
The height of the unopened droplist is constant, with the horizontal boundaries of its calling transform defining its width, and the vertical boundaries of its calling transform defining its opened height, which will include the added height of the bevel above the field, but may or may not include the title, depending on the alignment used. Note that if the entire list can be displayed in a smaller area than indicated by the vertical boundaries of the calling transform, the dropped list height will be decreased. The dropped height of the list will always have a minimum height of 1 line (below the field).

Usual height: 45 pixels.

Example:

GUITransform(30, 200, Width/2 - 5, 155
  1, 1, 1, 1, 1 { No scaling                      },
  0, 0, 1, 0    { No movement; visible; reserved  },
  0, 0, 0       { Not selectable                  },
  \DialogLibrary.PAlmPriority(\#Priority               { Parm to edit  },
                              \GetPhrase("AlarmPriorityLabel") { Label },
                              FALSE                    { Align Title   },
                              TRUE                     { ID            },
                              1                        { Trigger       },
                              0                        { Init          },
                              TRUE                     { Draw bevel    },
                              1                        { Vert align    }));


PalStatus

(Engine-Level Function)

Description: | Returns the color intensities of the current palette. Maintained for backward compatibility only.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Color, Graphics
Related to: |
Format: | PalStatus(Color, RGBIndex)
Parameters: |
Color
Required. Any expression giving the color to examine. May be a number from 0 to 255 (from the VTScada palette) or an RGB value with alpha channel, expressed as "<AARRGGBB>".
RGBIndex
Required. Any numeric expression giving the color component to return. Red, green, blue, or alpha.
RGBIndex | Color Content
0 | Red
1 | Green
2 | Blue
3 | Alpha channel
Comments: The returned number ranges from 0 to 1, and indicates the red, green, or blue color content of a color index, or the alpha channel (opacity) in the case of index 3.

Example:

ZText(10, 10, Concat("Red = " , PalStatus(14, 0)), 14, 0);
ZText(10, 20, Concat("Green = ", PalStatus(14, 1)), 14, 0);
ZText(10, 30, Concat("Blue = " , PalStatus(14, 2)), 14, 0);

This displays the color mix for color index 14 (yellow - FFFFFF00) in that color. The values displayed in this case will be 1, 1 and 0 respectively.


Parameter

(Engine-Level Function)

Description: | Returns the value of (or may assign a value to) a parameter of a module, specified by the index.
Returns: | varies
Usage: | Script or steady state.
Function Groups: | Basic Module, Variable
Related to: | BuffToParm | NParm | ParmToBuff | PType | ResetParm
Format: | Parameter(Object, Index)
Parameters: |
Object
Required. Any object (the object value of any module instance).
Index
Required. Any numeric expression giving the number of the parameter of interest, starting from 1.
Comments: This function returns the value passed in the module call in the position Index. It may also appear on the left side of an assignment operator (=), in which case it will try to assign the value to the parameter in Index. The parameter must be a reference type parameter to receive an assignment (all undeclared parameters default to reference type). Assignment to a non-reference parameter or function has no effect. The return value of Parameter is invalid if there is no parameter at Index.
For launched modules, this function will not look at parameters beyond the number of formal parameters.

Example:

If 1 Main;
[
  Parameter(Self(), 5) = 4;
]

This attempts to set parameter #5 to 4. Either the module must have parameter 5 declared as a reference parameter, or have no declaration for parameter 5 at all. The module call must have at least 5 parameters listed, and the fifth parameter must be a variable or array element. If any of these conditions are not met, nothing happens. If the module call is:

Show Normalize(1, 2, 3, 4, X);

Then X is set to 4.


ParameterEdit

Description: | Draws an interface to allow the user to choose how to edit a parameter. Used in tag widgets.
Returns: | Self
Usage: | Steady State only.
Function Groups: | Graphics, Variable
Related to: | DurationParameterEdit | ColorParameterEdit | TagParameterEdit | NumericParameterEdit | TextParameterEdit
Format: | \ParameterEdit(ParmVal, ParmPtr, Enable, Title, Modules, Contexts, Parameters, TitleWidth, StartIndex, PtrWaitClose, DialogRoot[, FocusID, Description])
Parameters: |
ParmVal
The variable to be changed. Metadata indicating the revision number (always 0) must be attached.
ParmPtr
Code Pointer to the parameter value so the ParameterEdit modules can dissect and categorize it
Enable
Flag - TRUE to enable the drawing of this parameter edit module.
Title
Title for this parameter
Modules
Array of module names (snap-ins such as ParmEditColor, etc.) for parameter editing
Contexts
No longer used. Should be set to INVALID. Context is always Code.
Parameters
Parameters for the parameter edit modules. A multidimensional array, where each sub-array is a parameter list for each of the entries in the Modules array.
TitleWidth
Width allotted for the title. If Invalid, uses a standard size (160px).
StartIndex
Starting Index for Parm Edit Modules
PtrWaitClose
Set to true to tell caller to wait to close
DialogRoot
Calling dialog window
FocusID
Optional focus ID value from 0 to 32767 . Defaults to 1 if the control is enabled, otherwise 0. The parameter edit control will have two parts and thus use two ID values: the one specified (or the default) and one greater than that.
Description
Optional text, describing this parameter
Comments: Metadata indicating the version number must be added to the ParmVal parameter. For example,
{ Set up variables for ParameterEdit }
    MetaData(Value, "Revision") = 0;

Do not attempt to modify parameter values directly. Rather, set this to a copy of the Parms array value and then reassign this when updated. For example:

{ In the init state: }
    MyPanelParm = MyOldPanelParm = Parms[#MyParm];

{ In the main panel: }
  ParameterEdit(MyPanelParm, ParmDefs[#MyParm], ...);
  If MyPanelParm != MyOldPanelParm || Valid(MyPanelParm) != Valid(MyOldPanelParm);
  [
    MyOldPanelParm = Parms[#MyParm] = RootValue(MyPanelParm);
  ]

Wrappers such as NumericParameterEdit exist to make this function easier to use. See: ParameterEdit Snap-ins

Example:

GUITransform(0, 1, 1, 0                      { Unit Outline               },
             1 - (Left)                      { Left Scaling               },
             Top + PickValid(Height, 0)      { Bottom Scaling             },
             Right                           { Right Scaling              },
             1 - (Top + TitleBarHeight)      { Top Scaling                },
             1                               { Overall Scaling            },
             0, 0                            { Trajectory, Rotation       },
             PickValid(DrawOptions, 1), 0    { Visibility, Reserved       },
             0, 0, 0                         { Selectability              },
             ParmEditObj = \ParameterEdit(
                             TextHAlign      { Parameter Value            },
                             CodePtr         { Pointer to Parm Code       },
                             PickValid(DrawOptions, 1) { Enable Flag      },
                             \GetPhrase(PickValid(ParmLabel, \HorizAlignmentLabel))
                                                                  { Title },
                             Modules         { Array of Parm Edit Modules },
                             Contexts        { Contexts for Edit Modules  },
                             Parameters      { Parameters for Edit Modules},
                             Invalid         { Title Width                },
                             Invalid         { Start Index                },
                             PtrWaitClose    { Wait to close              },
                             DialogRoot      { Calling dialog window       }
                           ));

Related information:

ParameterEdit Snap ins


ParameterSet

Description: | When passed a set of up to 256 parameters, will return them as an array.
Returns: | Array
Usage: | Script or Steady State
Function Groups: | Array, Variable
Related to: | ParameterEdit
Format: | \ParameterSet(Parm0[ Parm1, ... Parm256])
Parameters: |
Parm0
The first parameter to include.
Parm1 to Parm256
More parameters.
Comments: The returned array of parameters is suitable for use with ParameterEdit.


PAreaSelect

(Dialog Library)

Description: | Draws a droplist of area options with optional title and bevel.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PAreaSelect( CanEdit, FocusID, Init, DrawBevel, VertAlign, AlignTitle, ParmNum, ExtTrigger, OKPressed[, Title])
Parameters: |
CanEdit
Any logical expression. If true (non-0) the text displayed in the area droplist can be edited in the same manner as an editfield, if false (0) it cannot be edited directly. Defaults to true (1) if invalid.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Init
Any numeric expression indicating the initial value. No default is provided.
DrawBevel
Any logical expression. If true (non-0) a bevel is drawn around the area droplist, if false (0) no bevel is drawn. Defaults to true (1) if invalid.
VertAlign
Any numeric expression that sets the vertical alignment of the unopened area droplist according to one of the following:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated, is determined by the value of AlignTitle. Defaults to 0 if invalid.

AlignTitle
Any logical expression. If true (non-0) the title is included in the calculation for vertical alignment. If false(0) it is added to the area droplist after it (and its bevel if one exists) has been vertically aligned. Defaults to true (1) if invalid.
ParmNum
A parameter number (starting from 0), that will be edited instead of the default Area parameter. Specify the parameter to which you wish to add an area.
ExtTrigger
An external trigger, to be set when the area changes. Output value only.
OKPressed
Required. Linked to the OK button on the Config folder.
Title
An optional parameter that defaults to "Area"
Comments

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the second element (element 1) to the text string that designates the selected area.
The height of the (unopened) area droplist is constant, with the horizontal boundaries of its calling transform defining its width, and the vertical boundaries of its calling transform defining its opened height, which will include the added height of a bevel, but may or may not include the title, depending on the alignment used. Note that if the entire list can be displayed in a smaller area than indicated by the vertical boundaries of the calling transform, the dropped list height will be decreased. The dropped height of the list will always have a minimum height of 1 line (below the field).

Usual height: 100 pixels.

Example 1

*PtrWaitClose = PickValid(SubWaitClose, 0);

GUITransform(10, 120, 110, 20,
             1, 1, 1, 1, 1 { No scaling },
             0, 0, 1, 0 { No movement; visible; reserved },
             0, 0, 0 { Not selectable },
              \DialogLibrary.PAreaSelect(TRUE      { Can Edit },
                                         2         { ID },
                                         Parms[1]  { Init },
                                         FALSE     { Bevel },
                                         0         { Top Align },
                                         1         { Align Title },
                                         13        { ParmNum },
                                         Trigger   { ExtTrigger },
                                         OKPressed { OKPressed }));

Example 2

GUITransform(30, 180, 210, 80,
             1, 1, 1, 1, 1 { No scaling },
             0, 0, 1, 0 { No movement; visible; reserved },
             0, 0, 0 { Not selectable },
              \DialogLibrary.PAreaSelect(FALSE     { Not Editable },
                                         2         { ID },
                                         Parms[1]  { Init },
                                         TRUE      { Bevel Drawn},
                                         1         { Center Align },
                                         1         { Align Title },
                                         1         { ParmNum },
                                         Trigger   { ExtTrigger },
                                         OKPressed { OKPressed },
                                         "Title Area"{ Title }));


ParentModule

(Engine-Level Function)

Description: | Returns the parent module of a module.
Returns: | Module
Usage: | Script or steady state.
Function Groups: | Advanced Module
Related to: | Caller | ParentObject
Format: | ParentModule(Module)
Parameters: |
Module
Required. Any expression for the module.
Comments: The parent module is the module in which Module is defined.

Example:

ZText(10, 20, ParentModule(Self()), 15, 0);

This will display the parent module of the current module on the screen.


ParentObject

(Engine-Level Function)

Description: | Returns the parent of an object.
Returns: | Module
Usage: | Script or steady state.
Function Groups: | Advanced Module
Related to: | Caller | ParentModule
Format: | ParentObject(Object)
Parameters: |
Object
Required. The object you are inquiring about.
Comments: Returns the parent object of the given object instance.

Example:

parent = ParentObject(Self());
If ! Valid(Parent);
[
  Slay(Self(), 0);
]

This example illustrates how the function may be used to monitor a module's parent to prevent orphaning of the object.


ParentWindow

(Engine-Level Function)

Description: | Returns the object value of the nearest non-child window.
Returns: | Window Object
Usage: | Script or steady state.
Function Groups: | Graphics, Window
Related to: | ActiveWindow | RootWindow
Format: | ParentWindow(Object)
Parameters: |
Object
Optional. Any object (the object value of any running module instance).
Comments:

This function will start at the object value given and find the first window which is not a child window. If there is no window found the return value will be invalid.

For modules in non-child windows (i.e. one without bit 9 set), RootWindow and ParentWindow will return the same value.
For child windows, RootWindow will return the root module in the child window, while ParentWindow will return the root module in the child window's closest non-child calling window.

To test whether a custom widget is being displayed while in "editing mode" (that is, in the Idea Studio) you can test whether ParentWindow()\Editing is TRUE or FALSE.


ParmPhrase

\ParmPhrase is not a function, although it may look like one at first glance.

A \ParmPhrase is a parameterized phrase structure that is useful when creating Phrases in tag parameters


ParmToBuff

(Engine-Level Function)

Description: | Returns a buffer of formatted numeric parameter values.
Returns: | Buffer
Usage: | Script Only.
Function Groups: | Advanced Module, String and Buffer
Related to: | ArrayToBuff | BuffToArray | BuffToParm
Format: | ParmToBuff(Object, Index, N, Option, Size, Skip [, BadData])
Parameters: |
Object
Required. Any object (the object value of any running module instance).
Index
Required. Any numeric expression giving the first parameter to format, starting from 1.
N
Required. Any numeric expression giving the number of parameters to format. If there are fewer actual parameters than N + Index, this statement stops at the last parameter.
Option
Required. Any numeric expression which specifies the format of the buffer read.
Option | Format
0 | Unsigned binary (low byte first)
1 | Signed binary (low byte first)
2 | BCD (binary coded decimal) (low byte first)
3 | ASCII octal (high byte first)
4 | ASCII decimal (high byte first)
5 | ASCII hex (high byte first)
6 | ASCII floating point (high byte first)
7 | IEEE float/double (low byte first)
8 | <obsolete>
9 | Allen-Bradley® PLC/3 floating point
10 | VAX single precision floating point
Size
Required. Any numeric expression giving the number of digits in each datum. It has a different meaning for each option as indicated:
Option | Size Meaning | Size Range
Binary types | Number of bits | The following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64
BCD | Number of 4-bit digits | 1 - 16 digits
ASCII types | Number of bytes | 1 - 64 bytes
Float types | Precision | 1 for single precision, 2 for double precision

For Options 7 and 9 the data is written as appropriate binary format.

Skip
Required. Any numeric expression giving the number of buffer bits/digits/bytes to skip after writing each non-floating point element. In binary modes, the following values are supported: 8, 16, 32, and 64. For floating point types, this parameter must be set to 0.
BadData
An optional parameter that designates how invalid data is to be handled, according to the following table: Defaults to 0 if missing or invalid.
BadData | Handled
0 | Output to buffer as invalid values
1 | Causes buffer to be invalid
2 | Output to buffer as valid 0s
Comments:

This function may only be used with parameters containing numeric data. It is useful for encoding serial port data when writing I/O drivers.

In binary modes, for the Size parameter, the following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64. For the Skip parameter, the following values are supported: 8, 16, 32, and 64.

Size and Skip values not in those ranges will only work if their combined value is a multiple of 8. For instance, a Size of 12 and a Skip of 4 will work. A Size of 48 and a Skip of 0 will work. When Skip + Size is not a multiple of 8, the behavior of this function is undefined.

If your values are of Size 1 (i.e. a single bit), use unsigned mode. A Size of 1 is not supported for signed values.

Option 0 - 5 will write out values as 64-bit integers when the Size parameter is large enough to support a 64-bit value. Otherwise, they will be written as 32-bit values.

Format Type | Minimum Size for 64-bit Value
Binary | Greater than 32 bits
BCD | Greater than 8 digits
Octal | Greater than 11 digits
Hex | Greater than 8 digits.

If the size is large enough to suppoer a 64-bit output but 64 bits are not needed for the value (the value is less than the largest 64-bit integer) padding will be used to make up the difference. Decimal value interpretation is not affected by the size parameter.

Example:

If a module call looks like:

Write(1, 2, 3, x, y, z);

And there is a statement in module Write that looks like:

If ! Valid(writePacket);
[
  writePacket = ParmToBuff(Self(){ Current module },
                           4 { Skip first 3 parameters },
                           NParm(Self()) - 3
                           { Use rest of parameters },
                           0 { Unsigned binary format },
                           16 { Bits },
                           0 { No skip });
]

Because this statement encodes x, y, and z as 16 bit unsigned integers, the returned buffer will be 16 bytes long, byte-ordered as follows:

Byte | Description
0 | Low byte of x
1 | High byte of x
2 | Low byte of y
3 | High byte of y
4 | Low byte of z
5 | High byte of z


ParserSRO

(Engine-Level Function)

Description: | Adds a scope resolution reference to a variable on the top of the PARSER_STACK given the stack and the object variable.
Warning: | This function should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications
Related to: | Compile
Format: | ParserSRO(ParserStack, Variable)
Parameters: |
ParserStack
Required. Any expression for the parser stack value.
Variable
Required. Any expression for the variable value that will be referenced by scope resolution.
Comments: The ParserStack is returned from the Compile function. This assumes that the text value for the variable after the \ is already added as a parameter. This is only used when compiling text and is not required for normal operation.


PasteObjects

Description: | Pastes the code for multiple GUITransforms into a page source file.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics
Related to: |
Format: | PasteObjects(ObjectText, SelDAGs)
Parameters: |
ObjectText
Required. The text string containing objects.
SelDAGs
Required. An array of code pointers of the pasted objects.


Path

(Engine-Level Function)

Description: | Returns a graphics path value.
Returns: | Path
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUIPolygon | Point | Trajectory | Vertex
Format: | Path(Closed, V1, V2, ...)
Parameters: |
Closed
Required. Any logical expression. If true, this is a closed path, and the last Vertex is considered to be connected to the first point. If false, this is an open path ending at the last Vertex.
V1, V2, ...
Required. Any expressions that return Vertex values.
Comments: A path is a series of Vertex values, connected by either straight lines or Bezier curves. A path may be open, with two separate ends, or closed, with one continuous loop from the last vertex to the first. A Path value is used in such things as the GUIPolygon layered graphics function to specify its shape or in a Trajectory value to specify the path of animation or translation.

Example:

truckPath = Path(0 { Open path, doesn't close on self },
                Vertex(0 { Rectangular mode },
                Point(20, 200, Invalid, Invalid),
                Point(20, 200, Invalid, Invalid),
                Point(20, 200, Invalid, Invalid)),
                Vertex(0 { Rectangular mode },
                Point(200, 200, Invalid, Invalid),
                Point(200, 200, Invalid, Invalid),
                Point(200, 200, Invalid, Invalid)),
                endVertex { A variable containing a vertex });

This shows a 3 vertex path with one vertex found in a variable. This vertex might be used in other functions, such as another path.


PathDraw

(Engine-Level Function)

Description: | Used within a Idea Studio handler to inform the engine that a path is being drawn, and to set the appearance of that path. Used for both lines and pipes. The resulting object will be a GUIPolygon.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Graphics
Related to: |
Format: | PathDraw(Pen, Brush);
Parameters: |
Pen

Required. Defines the color, style and width of the path. May be any of the following:

Value | Notes
Pen object | If the pen color is transparent, invisible, or has a zero width, then a 1-pixel black line will be shown only while the path is being drawn to show the position.
Palette index | Defines only the color of the line. A 1-pixel, solid line will be drawn.
System color | Defines only the color of the line. A 1-pixel, solid line will be drawn.
-1 (transparent line) | The line will not be shown, except that a 1-pixel solid black line will be used while the path is being drawn.
aRGB string | Defines only the color of the line. A 1-pixel, solid line will be drawn.
Brush

Required. Defines the fill color of a closed figure or the color of a pipe. May be any of the following:

Value | Notes
Brush object | Defines a foreground, background and pattern for the fill.
Palette index | Defines only the color of the fill.
System color | Defines only the color of the fill.
-1 (transparent line) | The fill will not be shown.
aRGB string | Defines only the color of the fill.
Comments:

Do not confuse PathDraw with the function DrawPath().

This function will work only inside the context of a window with the Drop Target bit (22) set.

The path may have multiple vertices. If the function stops during drawing, no portion will be drawn.

When drawing a pipe, set the style for the Pen() to 100.

Examples:

Render a path as a narrow black line:

PathDraw(Pen(("<FFFFFFFF>", 1, 1), Brush(("<FF000000>", 0, 1));

Render a path as a pipe:

PathDraw(Pen("<FF80FF80>", 100, 29), Brush(-1, 0, 1));


PatternMatch

(Engine-Level Function)

Description: | Compares a string against a reference pattern and returns true if the string matches the pattern. Along with literal characters, PatternMatch currently supports the * and ? wildcard characters within the reference pattern (see Pattern parameter).
Returns: | Boolean
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: |
Format: | PatternMatch(String, Pattern [, CaseInsensitive])
Parameters: |
String
Required. The string you wish to compare to Pattern.
Pattern

Required. The reference pattern to which you wish String to be compared.
Wildcards are allowed. The wildcard "?" will match any character in a name. The wildcard "*" will match any series of characters.
The backslash character has special meaning, in that it can be added in front of the characters *, ? or \ to search for these characters explicitly. In these three cases, the leading backslash will be ignored.
Other characters must match exactly. A leading backslash in front of any characters other than the three noted will be included in the search.

CaseInsensitive
An optional Boolean parameter that indicates whether PatternMatch should be case insensitive when it performs the matching. The default for this parameter is FALSE, indicating that PatternMatch should be case sensitive.
Comments: If any of the arguments to PatternMatch are Invalid, PatternMatch returns Invalid.

Examples:

PatternMatch call | Result | Comments
PatternMatch("Pump_1", "Pump_*") | True |
PatternMatch("Pump_123", "Pump_*") | True |
PatternMatch("Pump_1", "Pump_?") | True |
PatternMatch("Pump_123", "Pump_?") | False | Only matching if there is a single character after the underscore
PatternMatch("abc", "a?c") | True |
PatternMatch("abbc", "a?c") | False |
PatternMatch("abbc", "a*c") | True |
PatternMatch("a*c", "a\*c") | True |
PatternMatch("abc", "a\*c") | False | Only matches a literal '*' character


PCheckBox

(Dialog Library)

Description: | Parameter Setting check box. This module draws a check box with optional label.
Returns | Nothing
Usage:: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PCheckBox(ParmNum [, Label, BoxOnLeft, Alignment, FocusID, PrivNotReq])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Label
An optional parameter that is any text expression to be used as a label with the check box. The default value is a blank label.
BoxOnLeft
An optional parameter that is any logical expression. If TRUE (non-0) the check box will appear to the left of the label, if FALSE (0) it will be to the right. The default value is TRUE.
Alignment
An optional parameter that is any numeric expression that sets the alignment of the check box and its label according to one of the following options:
Alignment | Horizontal Alignment | Vertical Alignment
0 | Left | Top
1 | Right | Top
2 | Full | Top
3 | Left | Centered
4 | Right | Centered
5 | Full | Centered
6 | Left | Bottom
7 | Right | Bottom
8 | Full | Bottom

FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
PrivNotReq
An optional parameter that is any logical expression. If set to true (non-0), anyone can change the value in this editfield. If set to false (0), only those users whose user accounts have been granted the "TagModify" privilege may set it. The default value is false.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the logical value set by the check box.
The size of the check box is constant, with the boundaries of its calling transform defining the position of the check box and its label.

Usual height: 12 pixels.

Examples:

  GUITransform(70, 190, 210, 170,
               1, 1, 1, 1, 1,
               0, 0, 1, 0,
               0, 0, 0,
               \DialogLibrary.PCheckBox(3         { Parm num            },
                                        \GetPhrase("YourLabel") { Label },
                                        FALSE     { Box on right        },
                                        2         { Full, top alignment },
                                        TRUE      { Focus ID            }));


PColorEdit

(Dialog Library)

Description: | Wrapper module for the standard color editing parameters including hue, saturation, brightness, transparency, contrast, colorizing hue and intensity.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PColorEdit(Parms, Hue, Saturation, Brightness, Transparency, Contrast, ColorizeHue, ColorizeInt[, Title, FocusID, Trigger])
Parameters: |
Parms
Required. A pointer to the array of parameters.
Hue
The parameter number for the Hue.
Saturation
The parameter number for the Saturation.
Brightness
The parameter number for the Brightness.
Transparency
The parameter number for the Transparency.
Contrast
The parameter number for the Contrast.
ColorizeHue
The parameter number for the ColorizeHue.
ColorizeInt
The parameter number for the Colorize Intensity.
Title
An optional parameter that is any expression for a title to be applied.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Set when the variable is changed.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain a pointer to an array of tag parameters. It will then set the elements indicated by Hue, Saturation, Brightness, Transparency, Contrast, ColorizeHue and ColorizeInt to the logical value set by the matching input field.
This module provides an easier way to add color editing to a Panel module. It will default invalid parameters.

Usual height: 260 pixels.

This module uses 7 Focus ID's.

Examples:

  GUITransform(0, 1, 1, 0,
               1                  { Scale Left                      },
               PanelHt - TitleSpace { Scale Bottom                  },
               PanelWd            { Scale Right                     },
               1                  { Scale Top                       },
               1                  { Scale Whole                     },
               0, 0, 1, 0         { No movement; visible; reserved  },
               0, 0, 0            { Not selectable                  },
               \DialogLibrary.PColorEdit(Parms,
                                         #Hue,
                                         #Saturation,
                                         #Lightness,
                                         #Transparency,
                                         #Contrast,
                                         #ColorizeHue,
                                         #ColorizeIntensity,
                                         \GetPhrase("ColorOptionsLabel") { Title },
                                         TRUE                   { to 15 - ID     },
                                         Trigger                { Trigger        }));


PColorSelect

(Dialog Library)

Description: | Draws a button that opens a color selection dialog and an area that displays the currently selected color.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Color, Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PColorSelect(ParmNum [, BtnLabel, BtnOnLeft, Standard, VertAlign, FocusID, Open])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
BtnLabel
An optional parameter that is any text expression to be used as a label on the color selection button.
BtnOnLeft
An optional parameter that is any logical expression. If true (non-0) the button will appear to the left of the color display area, if false (0) it will be to the right. The default value is true.
Standard
An optional parameter that is any logical expression. If true (non-0) the button and color display area will be standard system size, if false (0) they will be sized to fit their boundaries and VertAlign will be ignored. The default value is true.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the button and display area according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Note: If Standard is true, this parameter is ignored. The default value is 0, top alignment.

FocusID

Optional.

Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Open

An optional parameter that is any logical expression. If TRUE (non-0) the dialog will be forced open. If FALSE (0), it will be forced closed. The default is TRUE.

If provided as a variable, it will be set TRUE when the window is open and FALSE otherwise.

Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the chosen color index.
If the button and display area are set to be standard size, the button size will remain a constant size (101 x 31 pixels) regardless of the calling transform, but the display area will vary between a minimum (square) size to a maximum length equal to the length of the button, depending on the transform. After the maximum display area size has been reached, the button and area will be fully justified to cover the entire width of the transform (the vertical alignment will be set by the value of VertAlign).
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Usual height: 21 pixels.

Example:

GUITransform(70, 200, 290, 170,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.PColorSelect(8                 { Parm num            },
                                         \GetPhrase("Your_Custom_Label") { Label },
                                         TRUE              { Button on left      },
                                         TRUE              { Standard size       },
                                         1                 { Centered vertically },
                                         TRUE              { Focus ID            }));


PContributor

(Dialog Library)

Description: | Draws a split list displaying all contributors to a specific tag.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Containers and Contributors, Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PContributor(HolderName, ContainerObj, ContribType, TagType [, Title, FocusID, NoAdd])
Parameters: |
HolderName
Required. Any text expression giving the variable name for container information.
ContainerObj
Required. The object value of the container.
ContribType
Required. Any text expression giving the contribution type.
TagType
Required. Any text expression for the type of Tag for which the contributors are being sought.
Title
An optional parameter that is any text expression to be used as a title for the splitlist.
FocusID
Required. A parameter that is any numeric expression for the focus number of the splitlist and its two buttons. The splitlist will have a focus ID equal to FocusID, the left button will have one of FocusID + 1, while the right button will have a focus ID of FocusID + 2.

If FocusID is 0, the splitlist will display its current setting, but its accompanying buttons will not be able to be selected.
NoAdd
An Boolean optional expression. Set TRUE when the Add button is disabled.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the chosen tag's name.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.
This function provides a split list containing the names and descriptions of all contributors stored in HolderName. Double-click on an item in this list to obtain the Properties dialog for the tag. Click on the Add button to add a new contributor of the tag type "PointType", which is owned by "ContainerObj", and which has a contribution type "ContribType". Click on the Delete button to terminate the container/contributor relationship for the currently highlighted contributor. The former contributor is not deleted from the application, or from the database.

Usual height: 200-250 pixels.

Examples:

GUITransform(10, 410, 310, 10,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.PContributor(""              { Holder name      },
                                         Var             { Container object },
                                         ""              { Contributor type },
                                         "AnalogInput"   { Tag type         },
                                         \GetPhrase("Contributors") { Title },
                                         4               { Focus ID         }));


PDroplist

(Dialog Library)

Description: | Parameter Setting Droplist. This module draws a droplist with (optional) title and bevel.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms SiteDispParms
Format: | \DialogLibrary.PDropList(ParmNum, Title, DataOrAlignTitle [, CanEdit, Index, FocusID, Trigger, Init, DrawBevel, VertAlign, AlignTitle_L0, RetArray_L1, DoNotTranslate_L2, ..., L16])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
Required. Any text expression to be used as a title for the droplist.
DataOrAlignTitle
Required. A flexible parameter that is either an array of data to display in the droplist, or a logical expression indicating the alignment of the droplist's title.
If this is an array, the parameter called AlignTitleOrL1 indicates the title alignment.
If this parameter is invalid or numeric, it indicates the title alignment such that if it is TRUE (non-0) the title is included in the calculation for vertical alignment, if FALSE (0) it is added to the droplist after it (and its bevel if one exists) has been vertically aligned. The default is TRUE.
CanEdit
An optional parameter that is any logical expression. If TRUE (non-0) the text displayed in the droplist can be edited in the same manner as an editfield, if FALSE (0) it cannot be edited directly. The default value is FALSE.
Index
An optional parameter that is a variable whose value indicates the array index of the highlighted item in the list. If this information is not required, a constant may be used. This value will be used to calculate the initial value displayed in the droplist (see Init).
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Optional. If the droplist is editable, Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero, 1 if enter is pressed, and 2 otherwise.
Init
An optional parameter that is any expression for the initial value displayed in the field. The default value is Parms[ParmNum]. If Index is invalid, the droplist will initially appear blank.
DrawBevel
An optional parameter that is any logical expression. If true (non-0) a bevel is drawn around the droplist, if false (0) no bevel is drawn. The default value is true.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the unopened droplist according to one of the following:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle_L0
A flexible parameter that is either a logical expression indicating the alignment of the title, or it is the first label (option) in the list that is displayed by this graphic. If the parameter called DataOrAlignTitle is a data array of options, this parameter will indicate the title alignment (see the summary for the DataOrAlignTitle parameter) otherwise this will be any text expression that gives the first label in the dropped list.
RetArray_L1
A flexible parameter that is either the second label in the list displayed by this graphic, or it can be an array of values to which the parameter at ParmNum will be set. This allows PDropList to be used in places that would otherwise need to use System.Droplist and manually set the value of Parameter[#ParmNum]
DoNotTranslate_L2
A flexible parameter that is either a logical expression indicating that text should not be translated (when set TRUE), or the third label in the list.
L3, ...L16
A list of text expressions giving the remaining options in the dropped list. Any number of these may be left invalid. The resulting list displayed when droplist is opened will contain all valid entries in the 16 available positions.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the text string displayed in the selected line of the droplist.
The height of the (unopened) droplist is constant, with the horizontal boundaries of its calling transform defining its width, and the vertical boundaries of its calling transform defining its opened height, which will include the added height of the bevel above the field, but may or may not include the title, depending on the alignment used. Note that if the entire list can be displayed in a smaller area than indicated by the vertical boundaries of the calling transform, the dropped list height will be decreased. The dropped height of the list will always have a minimum height of 1 line (below the field).
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Usual height: 40

Example:

The following example illustrates the data options being stored in an array:

  GUITransform(70, 210, 210, 170,
               1, 1, 1, 1, 1,
               0, 0, 1, 0,
               0, 0, 0,
               \DialogLibrary.PDroplist(6          { Parm num             },
                                        \GetPhrase("Your_Title")  { Title },
                                        PLCTypes   { Array of data        },
                                        FALSE      { Not editable         },
                                        Idx        { Chosen element       },
                                        FALSE      { Focus ID             },
                                        0          { Trigger not req'd    },
                                        Invalid    { Use default for init },
                                        TRUE       { Draw bevel           },
                                        1          { Center list          },
                                        0          { Align top of bevel   }));

The next example shows how data options may be entered as a grouping of text strings:

  GUITransform(70, 210, 210, 170,
               1, 1, 1, 1, 1,
               0, 0, 1, 0,
               0, 0, 0,
               \DialogLibrary.PDroplist(6         { Parm num             },
                                        \GetPhrase("Your_Title") { Title },
                                        1         { Align title with top },
                                        FALSE     { Not editable         },
                                        Idx       { Chosen element       },
                                        TRUE      { Focus ID             },
                                        0         { Trigger not req'd    },
                                        Invalid   { Use default for init },
                                        TRUE      { Draw bevel           },
                                        1         { Center list          },
                                        "PLC-2", "PLC-3",
                                        "PLC-5", "PLC-5/250",
                                        "SLC-500" { Options in list      }));


PEditField

(Dialog Library)

Description: | Parameter Setting Editfield. This module draws an editfield with (optional) title and bevel. Note: PPhraseEdit is recommended for use instead of PEditField in most situations where the parameter is text.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditName | PFileChooser | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PEditField(ParmNum [,Title, DataType, FocusID, Trigger, View, DrawBevel, VertAlign, AlignTitle, LowLimit, HighLimit, PrivNotReq, Style, PrefixValue, PostfixValue, PlaceHolder])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
An optional parameter that is any text expression to be used as a title for the field.
DataType
Defaults to 4 unless otherwise specified.
DataType | Type
0 | Byte (unsigned)
1 | Short (2 byte signed)
2 | Long (4 byte signed)
3 | Double precision floating point (8 byte signed)
4 | Text
5 | Octal (4 byte unsigned)
6 | Hexadecimal (4 byte unsigned)

For types 0 - 2, if the number entered into the field is prefaced by a "0x" the value is taken to be hexadecimal format, and if it is prefaced by a "0" it is considered to be octal. In either case, the value is converted to decimal format when return is pressed or the focus is lost.
For type 5, regardless of whether the number entered into the field is prefaced by a "0" the value is taken to be octal and will be displayed as such. The actual type of Variable will be text.
Type 6, like type 5 will be kept in its declared format of hexadecimal regardless of whether the number entered into the field is prefaced by a "0x". The actual type of Variable will be text

FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Optional. Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero: 1 if enter is pressed, 2 otherwise.
View
An optional parameter indicating how to display the editfield , as follows. The default value is 2 if FocusID is 0 and 1 otherwise.
View | Display mode
0 | Invisible
1 | Normal (color scheme - no graying)
2 | Grayed-out (only if FocusID is 0)

This parameter may be used to force an editfield with a FocusID of 0 to display normally, rather than allowing it to default to its grayed color.
Note that if the FocusID is not 0, setting this value as 2 will not force the field to gray out.

DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control. If the editfield is beveled, its size will become fixed and will be the same as that for a droplist.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the editfield according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
An optional parameter that is any logical expression. If AlignTitle is true (non-0), the title will be included in the calculation for vertical alignment. If AlignTitle is false (0), the title will be added to the editfield after both the editfield and its bevel have been vertically aligned. The default is true.
LowLimit
An optional parameter that is any expression giving the minimum value or minimum number of characters to be accepted by the editfield (depending on the data type). This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value less than LowLimit is entered in the field (or there are too few characters, in the case of text value), the variable set by the field will revert to the previous value. No default
HighLimit
An optional parameter that is any numeric expression giving the maximum value or maximum number of characters to be accepted by the editfield (depending on the data type). This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value greater than HighLimit is entered in the field (or there are too many characters, in the case of text value), the variable set by the field will revert to the previous value.
PrivNotReq
An optional parameter that is any logical expression. If set to true (non-0), anyone can change the value in this editfield. If set to false (0), only those users whose user accounts have been granted the "TagModify" privilege may set it. The default value is false.
Style
An optional parameter indicating the style of the PEditField object. It is a bit-wise field made up of the sum of the following values, to yield the desired effects.
Bit | Value | Definition
0 | 1 | Reserved for bit compatibility with WinComboCtrl, and should be set to "0"
1 | 2 | Reserved for bit compatibility with WinComboCtrl, and should be set to "0"
2 | 4 | Input is converted to all uppercase (note 1)
3 | 8 | Input is converted to all lowercase (note 1)
4 | 16 | Input is masked. Any characters typed will appear as asterisks. This is useful for such things as password fields
5 | 32 | Multiline editing. Setting this bit causes a typed <CR> (Enter or Return) to be interpreted as "move to the start of the next line". Text that contains <CR> characters has a line break inserted at each
6 | 64 | Reserved
7 | 128 |
8 | 256 | Reserved
9 | 512 | Not used. Height is defined by \EditHt or TEditHt (with title).

If neither values 4 or 8 are set, input is passed to script code as typed.

PrefixValue
An optional parameter indicating the text expression that should be displayed immediately before (i.e. to the left of) the editable part of the control.
SuffixValue
An optional parameter indicating the text expression that should be displayed immediately after (i.e. to the right of) the editable part of the control. No Default
PlaceHolder
Optional text to be displayed in the field when there is otherwise no valid value.
Typically provides context or instructions to the user. This is not a default value for the parameter.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the value in the editfield.

The height of the editfield is constant, with the horizontal boundaries of its calling transform defining its width, and the vertical boundaries of its calling transform defining the boundaries in which it is to be confined vertically, which will include the added height bevel, but may or may not include the title, depending on the alignment used.

Usual height: 45 pixels.

Examples:

  GUITransform(10, 215, 225, 15,
               1, 1, 1, 1, 1,
               0, 0, 1, 0,
               0, 0, 0,
               \DialogLibrary.PEditField(1             { Parm num          },
                                         \GetPhrase("Your_Title")  { Title },
                                         3             { Type float        },
                                         TRUE          { FocusID           },
                                         0             { Trigger not req'd },
                                         Invalid       { Use default view  },
                                         0             { No bevel          },
                                         Invalid       { Default alignment },
                                         1             { Align title       },
                                         98.6          { Minimum value     },
                                         Invalid       { No maximum value  }));

Notice in the above example that the last parameter could have been omitted, because it is optional and its setting matches the default.


PEditName

(Dialog Library)

Description: | An edit field for setting tag names. This module draws an edit field that is to be connected to the name of a tag. Should be used by all tag ConfigFolder modules for setting the name parameter.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PEditName(Trigger[, DrawBevel, Title, ID])
Parameters: |
Trigger
Required. Set when the name variable is changed.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control.
Title
Optional. Any text that you would like display as the title of the edit field. Defaults to "Name".
ID
Optional. Any numeric expression providing the Focus ID of the edit field. Defaults to 1.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
The "P" tools (PCheckBox, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

Usual height: 45 pixels.

Example:

  {***** Name of the tag *****}
  GUITransform(30, 90, 470, 45,
               1, 1, 1, 1, 1  { No scaling                 },
               0, 0, 1, 0     { No movement. Visible. Reserved},
               0, 0, 0        { Not selectable             },
               \DialogLibrary.PEditName(Trigger));


PFileChooser

(Dialog Library)

Description: | Parameter setting file selection. Provides an edit box for specifying a file name, along with a label and a browse button.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms|FileChooser
Format: | \DialogLibrary.PFileChooser(ParmNum, Title, ButtonLabel, ID, Trigger, View, Save, FilterPattern, FilterDesc, DialogTitle, ExtensionToUse, [DrawBevel, VertAlign, AlignTitle])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
An optional parameter that is any text expression to be used as a title for the field. Defaults to "" if invalid.
ButtonLabel
An optional parameter that is any text expression to be used as a label for the browse button. Defaults to "..." if invalid.
ID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Required. Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero: 1 if enter is pressed, 2 otherwise.
View
Required. Indicates how to display the editfield, as follows. The default value is 2 if FocusID is 0 and 1 otherwise.
View | Display mode
0 | Invisible
1 | Normal (color scheme - no graying)
2 | Deprecated.
3 | Grayed-out if FocusID is 0.

This parameter may be used to force an editfield with a FocusID of 0 to display normally, rather than allowing it to default to its grayed color.
Note that if the FocusID is not 0, setting this value as 2 will not force the field to gray out.

Save
Save | Save Mode
0 | Open dialog
1 | Save dialog
-1 | Browse for folder
-2 | Browser for folder + add trailing "\"
FilterPattern
Required text. An array or a semicolon-separated list of wildcard file patterns for the types that will appear. Defaults to "" if invalid.
FilterDesc
Required text. An array or a semicolon-separated list of text values describing the corresponding FilterPatterns. Defaults to "" if invalid.
DialogTitle
Required text. The title to apply to the file dialog. Defaults to "" if invalid.
ExtensionToUse
Required text. For save dialogs (Save parameter == 1) the file extension to use if not specified by the user. Defaults to "" if invalid.
DrawBevel
OptionalBoolean. If TRUE, the bevel is drawn
VertAlign
Optional. Any numeric expression that sets the vertical alignment of the edit field according to one of the following options
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
Optional Boolean. TRUE if title affects alignment
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the value in the editfield.

Example:

  { Custom Point Definition File }
  GUITransform(30,
               45 + 4*Space + 2*TDropHt + 3*TEditHt,
               Width - 30,
               45 + 4*Space + 2*TDropHt + 2*TEditHt,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PFileChooser(\#PointDefCSV, \GetPhrase("CustomPointDefLabel") {Title}, \GetPhrase("BrowseLabel") {BtnLabel},
                                           7 {FID}, Trigger, 2, 0 {Open},
                                           "*.CSV" { filter }, GetPhrase("CSVFileLabel") { desc },
                                           \GetPhrase("CustomPointDefLabel"), Invalid, FALSE));


PeekStream

(Engine-Level Function)

Description: | Returns a string of bytes from a stream without removing them from the stream.
Returns: | See description
Usage: | Script only.
Function Groups: | Stream and Socket
Related to: | GetStreamLength | PipeStream | SRead | StreamEnd
Format: | PeekStream(Stream, N)
Parameters: |
Stream
Required. Any expression returning a pipe stream.
N
Required. Any numeric expression giving the number of bytes to get from the pipe.
Comments: Execution of this function doesn't affect the stream position pointer.
The second parameter may specify up to 2,147,483,647 characters. Beyond that, Invalid will be returned.

Example:

If ! Valid(data);
[
  data = PeekStream(strm, 10);
]

This stores the last 10 bytes from strm in data. The stream is unaffected.


Pen

(Engine-Level Function)

Description: | Returns a pen value.
Returns: | Pen
Usage: | Steady State only.
Function Groups: | Color, Graphics
Related to: | Brush
Format: | Pen(Color, Style, Width)
Parameters: |
Color
Required. Any numeric expression giving the color of the line.. Any of the following may be used:
  • a palette VTScada Color Palette
  • a Constants for System Colors (constant)
  • -1 (transparent)
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Style
Required. Any numeric expression giving the Line Types. Valid line styles are from 1 to 5 inclusive for standard lines. A line style of 1 is a solid line.
If the Pen command is used within a GUIPolygon to draw a pipe, the use line style 100 (constant: PEN_STYLE_PIPE).
Width
Required. Any numeric expression that gives the line width in pixels.
Comments: Pen values are used in layered graphics statements that draw lines (such as GUIArc or GUIRectangle).

Example:

GUIArc(728, 227, 477, 50 { Bounding box for arc },
       1, 1, 1, 1, 1 { No scaling },
       0, 0 { No trajectory or rotation },
       1, 0 { Arc is visible; reserved },
       0, 0, 0 { Cannot be focused/selected },
       Pen(14 { yellow }, 3 { dotted }, 2 { pixel width }),
       Vertex(1 { Double smooth mode },
       Point(602.5, 138.5, Invalid, Invalid),
       Point(710, 293, Invalid, Invalid),
       Point(413, 52, Invalid, Invalid)));

This shows how a Pen statement may be used to affect the attributes of a drawing object. In the above example, the arc will be drawn with a dotted yellow line 2 pixels wide.


Pending

(Engine-Level Function)

Description: | Returns the number of statements of a certain type pending.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Graphics
Related to: |
Format: | Pending(StatementType)
Parameters: |
StatementType
Required. Any numeric expression giving the type of statement for which to get the number pending as follows:
StatementType | Pending type
0 | Always returns 0. High priority statements are no longer supported.
1 | Normal priority statement
2 | Timer
3 | Priority statement
4 | Logger queue length (logQsize in LogFile.cpp)

Example:

If 1 Next;
[
  numPending = Pending(1);
]
This script finds the number of normal priority statements pending at the time of execution and assigns the value to the variable numPending.


PercentDifference

(Function Library)

Description: | Returns the percentage difference between two numbers
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | General Math
Related to: |
Format: | \FunctionLib.PercentDifference(Value1, Value2)
Parameters: |
Value1
The first numeric value.
Value2
The second numeric value.
Comments:

This module is a member of the Function Library, and must therefore be prefaced by \FunctionLib as shown in the "Format" section.

Performs the following calculation:

Return(Abs(Value1 - Value2)/Value2);

Example:

\FunctionLib.PercentDifference(50, 100)

Will return 0.50

The calculation is the percentage of the difference between the two parameters, not the first parameter as a percent of the second. Division is always by the second parameter, therefore it should usually be the larger of the two values.

\FunctionLib.PercentDifference(25, 100)

Will return 0.75

\FunctionLib.PercentDifference(100, 25)

Will return 3


PersistentSize

(Engine-Level Function)

Description: | Returns the size in bytes of a variable's persistent value size in the persistent value (.VAL) file.
Warning: | This function should be used by advanced users only.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | AddVariable | FindVariable | MakeNonPersistent | MakePersistent
Format: | PersistentSize(Variable)
Parameters: |
Variable
Required. Any expression for the variable value. This value is usually returned from a call to AddVariable or FindVariable.
Comments: If Variable is not a persistent variable the function will return invalid.


PhraseDroplist

(System Library)

Description: | Language sensitive Droplist.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | PhraseEdit
Format: | \System.PhraseDroplist(X1, Y1, X2, Y2, PhraseIDArr, Title, Index, ID, Trigger, NoEdit, PhraseId[, DrawBevel, VertAlign, AlignTitle, Style, BGColor, FGColor, FontParm, TitleBGColor, TitleFGColor, BevelColor, SortPhrases])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the graphic.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of thegraphic.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the graphic opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the graphic, whichever is the opposite of Y1.
PhraseIDArr
Required. An array containing Phrase IDs (keys) for the list.
Title
Optional text expression to be used as a title for the droplist. Set to Invalid for no title.
Index
Required Numeric. The index variable to update within the array.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Optional numeric. Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero: 1 if enter is pressed, 2 otherwise.
NoEdit
Optional Boolean. Set TRUE to prevent direct editing of the text.
PhraseID
Required text. ID (phrase key) of the current value entered in the dialog.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control. Defaults to TRUE. If the editfield is beveled, its size will become fixed and will be the same as that for a droplist.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the editfield according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
Optional Boolean. If AlignTitle is TRUE (non-0), the title will be included in the calculation for vertical alignment. If AlignTitle is FALSE (0), the title will be added to the editfield after both the editfield and its bevel have been vertically aligned. The default is true.
Style
Optional. Comprised of a combination of bit values to yield the desired effects.
Bits 0 and 1 define mutually exclusive styles of operation. They can be set to one of the following values:
Bit Number | Definition
0 | No droplist, rather a listbox with the selected item above
1 | Droplist and editable selection
2 | Droplist with non-editable selection

Bits 2 and 3 define input character handling. If neither is set, input is passed to script code as typed.

Bit Number | Definition
2 | Input is converted to all uppercase.
3 | Input is converted to all lowercase.

Bit 4 controls list sorting.

Bit Number | Definition
4 | The list is presented in sorted order to the user.

Bit 8 enables Windows visual styles.

Bit 9 defines and enables exact use of application-defined geometry. The default is to perform auto-geometry modification to give the best fit.

Bit Number | Definition
9 | Enable application-defined geometry.
BGColor
Optional. Background color of the dropList
FGColor
Optional. Foreground (text) color of the dropList
FontParm
Optional Font value.
TitleBGColor
Optional. Background color under title

TitleFGColor

Optional. Foreground (text) color of the title.
BevelColor
Optional. Color of the bevel line.
SortPhrases
Optional Boolean. If present and TRUE, the entries in the list will be sorted by the translated phrase.
Comments:

Droplist used to select a PhraseID by presenting the user with a droplist full of translated phrases. If CanEdit is TRUE then it is possible for the user to input new labels, in which case they will be added to the list and will be added to the language manifest.


PhraseEdit

(System Library)

Description: | Language-sensitive editfield. This module draws an editfield with (optional) title and bevel. Recommended in place of the older Edit function.
Returns: | Nothing (See PhraseID parameter)
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | PhraseDroplist
Format: | \System.PhraseEdit(X1, Y1, X2, Y2, Title, PhraseID, ID[, Trigger, View, DrawBevel, VertAlign, AlignTitle, MinVal, MaxVal, Style, PrefixValue, PostfixValue, BGColor, FGColor, FontParm, TitleBGColor, TitleFGColor, BevelColor, PlaceHolder])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the edit field.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the edit field.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the edit field opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the edit field, whichever is the opposite of Y1.
Title
Optional. The text expression to be used as a title for the field. Set Invalid if not shown.
PhraseID
Required. Output variable. Set to the phrase ID of the new text.
ID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger

Optional numeric. Set when the text changes and provides feedback as follows.

  • Initially set to Invalid.
  • Set to 0 while the phrase editor dialog is open
  • Set to Invalid if user opens the phrase editor manually and does not change the PhraseID
  • Set to 1 if the user selects a different PhraseID using the phrase editor dialog
View
Optional numeric. Directs how to display the editfield , as follows.
View | Display mode
0 | Invisible
1 | Normal (color scheme - no graying)
2 | Grayed-out (only if FocusID is 0)
3 | Non-grayed text on a type 2 background.
DrawBevel
Optional Boolean. Set to TRUE to draw a bevel around the control.
VertAlign
Optional numeric. Sets the vertical alignment of the editfield according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated as determined by the value of AlignTitle.

AlignTitle
Optional Boolean. If AlignTitle is TRUE (non-0), the title will be included in the calculation for vertical alignment. If AlignTitle is FALSE (0), the title will be added to the editfield after both the editfield and its bevel have been vertically aligned.
MinVal
Optional. The minimum acceptable value.
MaxVal
Optional. The maximum acceptable value.
Style

An optional parameter indicating the style of the EditField object. It is a bit-wise field made up of the sum of the following values, to yield the desired effects.

(See: Bitwise Parameters & Operations)

Bit | Value | Definition
0 | 1 | Reserved for bit compatibility with WinComboCtrl, and should be set to "0"
1 | 2 | Reserved for bit compatibility with WinComboCtrl, and should be set to "0"
2 | 4 | Input is converted to all uppercase (note 1)
3 | 8 | Input is converted to all lowercase (note 1)
4 | 16 | Input is masked. Any characters typed will appear as asterisks. This is useful for such things as password fields
5 | 32 | Multiline editing. Setting this bit causes a typed <CR> (Enter or Return) to be interpreted as "move to the start of the next line". Text that contains <CR> characters has a line break inserted at each
6 | 64 | Reserved
7 | 128 |
8 | 256 | Reserved
9 | 512 | Not used. Height is defined by \EditHt or TEditHt (with title).

If neither values 4 or 8 are set, input is passed to script code as typed.

PrefixValue
Optional text. An expression that should be displayed immediately before (i.e. to the left of) the editable part of the control.
SuffixValue
Optional text. An expression that should be displayed immediately after (i.e. to the right of) the editable part of the control. No Default
BGColor
Optional background color of the edit box
FGColor
Optional foreground color of the edit box
FontParm
Optional Font value.
TitleBGColor
Optional. Background color under title

TitleFGColor

Optional. Foreground (text) color of the title.
BevelColor

Optional. Color of the bevel line.

PlaceHolder

Optional text. Information to display in place of invalid entry. Typically a phrase describing how the field is to be used.
Comments:

Allows a user to enter a multilingual phrase. Input is done in the user's active language and a pop-up dialog is available for editing all other languages in the application.

If a new phrase is typed, the dialog will automatically open to allow the user to provide translations. If an existing phrase is typed, an indicator appears if there are missing translations. The dialog will not pop up in this case.

If a phrase is typed that has multiple matching entries (homographs) then a dialog will open to allow selection and modification of the matches.

Examples:


PHSliderBar

(Dialog Library)

Description: | Called graphic module that connects a horizontal slider bar to a given parameter number.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PHSliderBar(ParmNum [, Title, FocusID, Trigger, DrawBevel, MinValue, MaxValue, EnableEditField])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
An optional parameter that is any text expression to be used as a the title to put on the bevel.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Set when the variable is changed.
DrawBevel
Any Boolean expression which, when set to TRUE, indicates that a bevel is to be drawn around the control.
MinValue
Any numeric expression for the minimum of Value's range.
MaxValue
Any numeric expression for the maximum of Value's range.
EnableEditField
An optional parameter that is any logical expression. If true (non-0) the edit field will be shown. The default is FALSE.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the value of the element indicated by ParmNum.

Usual height: 40 pixels.

Example:

  GUITransform(70, 200, 290, 160,
               1, 1, 1, 1, 1          { No scaling                     },
               0, 0, 1, 0             { No movement; visible; reserved },
               0, 0, 0                { Not selectable                 },
               \DialogLibrary.PHSliderBar(#RelativeSize,
                                          \GetPhrase("Your_Title"), { Title },
                                           5        { ID               },
                                          Trigger   { Trigger          },
                                          0         { No Bevel         },
                                          0         { Min scale value  },
                                           100      { Max scale value  },
                                          1         { Enable edit      }));


PHueSelect

(Dialog Library)

Description: | Called graphic module that connects a hue selection tool to a given parameter number.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Color, Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PHueSelect(ParmNum [, Title, FocusID, Trigger, DrawBevel, EnableEditField])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
An optional parameter that is any text expression to be used as a the title to put on the bevel.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Set when the variable is changed.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control.
EnableEditField
An optional parameter that is any logical expression. If TRUE (non-0) the edit field will be shown. The default is FALSE.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the value of the element indicated by ParmNum.

Usual height: 77 pixels.

Example:

  GUITransform(30, 200, 300, 270,
               1, 1, 1, 1, 1            { no scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PHueSelect(#MismatchHue,
                                         \GetPhrase("Your_Title")  { Title },
                                         10                        { ID    },
                                         Trigger,
                                         0, 1));


Pick

(Engine-Level Function)

Description: | Returns an indication of whether the locator (e.g. mouse) has had a specified change in its button status.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Graphics, Locator
Related to: | Click | LocSwitch | SetXLoc | SetYLoc | Target | WinLocSwitch | WinXLoc | WinYLoc | XLoc| YLoc | GUITransform
Format: | Pick(X1, Y1, X2, Y2, Button)
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the screen area ("target").
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the screen area ("target").
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the "target" opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the target, whichever is the opposite of Y1.
Button
Required. Any numeric expression giving the button combination that activates this graphic when the locator cursor is within the "target" screen area.
Button | Button Locator
0 | No buttons
1 | Right button
2 | Middle button
3 | Right and middle buttons
4 | Left button
5 | Left and right buttons
6 | Left and middle buttons
7 | All three buttons

If the value is:

- multiplied by 8 the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (8 * 4)

- increased by 64, the function will become true when the mouse buttons are released rather than when they are pressed

- increased by 128, the button(s) must be double-clicked

- increased by 256, forces the control with the input focus (in the same window as the Pick) to simulate the Enter key being pressed prior to the Pick function returning a value of true. In other words, with code similar to:

   If Pick(X1, Y1, X2, Y2, 0X104);
   [
    …script statements…
   ]

any value affected by the control with input focus will be set to the current value of the control prior to the script statements being run.

- increased by 512, horizontal panning is disabled over the region.

- increased by 1024, vertical panning is disabled over the region.

These last two options, 512 and 1024, allow Pick, WinLocSwitch and other events to be handled by a region within the window - for example a map within a Sites page when viewed using the VTScada Anywhere Client. These should be used only by advanced users.

Comments:

This function returns true if the locator button combination changes as specified by the Button parameter while the locator position is within the boundaries of the "target" ((X1,Y1) - (X2,Y2)). This function is "edge triggered" which means that it only acts upon the changes in locator button status. Making the button combination specified by the Button parameter outside the target area and then sliding the cursor into the target will not cause the function to return true. If the locator is not installed, the function will return false (0).
This function is very useful for capturing fast mouse button presses by the operator. VTScada remembers the locations where the mouse buttons were pressed and released. The actual buttons do not have to be pressed when the Pick is actually executed since it will examine the list of all button changes since the last time it was executed.
This function is latched on after it becomes true. Use Click() for steady state feedback rather than Pick().

Note: This function is disabled when using a GUITransform as a GUIStrectch.

Example:

If Pick(300, 500, 600, 700, 56) MixerScreen;

This action will switch to the MixerScreen state when the mouse is inside the target box and any mouse button is pressed.

Related information:

Latching and Resetting Functions


PickBMP

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Displays a"Select Image" dialog box with samples of bitmaps available for selection.
Returns: | Image object (Selection is returned via a parameter.)
Usage: | Script Only.
Function Groups: | Graphics
Related to: | FileDialogBox
Format: | PickBMP(Invalid, Invalid, Invalid, Left, Top, pFName[, Invalid, Animated, pParms])
Parameters: |
Invalid x 3
The first three parameters are obsolete. Provide Invalid as a placeholder.
Left
Required numeric. The coordinates for the left edge of the dialog box.
Top
Required numeric. The coordinates for the top edge of the dialog box.
pFName

Required pointer. The file name of the selected image will be returned via this parameter.

Returns zero (0) if no valid file name can be returned.

Invalid
Obsolete parameter
Animated
Required Boolean. The dialog can provide animated bitmaps if this parameter is set TRUE.
pParms

Required pointer.

In the case of a selection of animations, this is a pointer to the parameters array of the selected Animated bitmap. These include Image directory, scale, FPS, etc.

In the case of an image, this is set to the image directory path.

Comments:

The selected image can be drawn using either \Bitmap or \AnimatedBitmap.

Example:

  If WinButton(100,100,140,120,
               0, GetPhrase("SelectLabel"),
               0 {FID},
               \System\DefFont);
  [
    PickBmpObj = \PickBMP(Invalid, Invalid, Invalid, 0, 0, &ImageFile);
  ]
  If Valid(ImageFile);
  [
    IfThen(ImageFile != 0 && StrLen(ImageFile) > 0,
      Parms\IconFile = ImageFile;
      ImgFilePath    = \FindFile(ImageFile);
    );
    ImageFile = Invalid;
  ]


PickValid

(Engine-Level Function)

Description: | Attempts to return a valid value given a list of parameters.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | Logic Control
Related to: | Valid
Format: | PickValid(Parm1, Parm2 [, Parm3, ...])
Parameters: |
Parm1, Parm2, Parm3...
Required. Any number of parameters giving any expressions, from which the first valid value will be selected.
Comments:

This function continues its search through its parameter list in order until the first valid value is found. If no valid parameters are supplied, INVALID is returned.

Use True(X) instead of PickValid(X, False). This is simpler and cleaner.

If executed in a script, after the first valid parameter is found, no further parameters are evaluated.

If executed in steady state, all parameters are always evaluated.

A relevant example might be an attempt to display one of two objects, depending on which is valid:

PickValid(Obj1.Widget(), Obj2.Widget());

In steady state, even if Obj1 is valid, both widgets will run. For the desired behavior, you should instead use code such as the following:

PickValid(Obj1.Widget, Obj2.Widget)();

Examples:

  A = Invalid;
  B = 83;
  C = Invalid;
  D = -1;
  ValidAns1 = PickValid(A, B, C, D);
  ValidAns2 = PickValid(A, C, D, B);

The value of ValidAns1 and ValidAns2 will be 83 and -1 respectively.

A typical use for this function is in setting default values as follows:

<
MyGraphic
(
  ParmLeft;
)
[
  Left       { local value for the left edge };
]
SetDefaults [
  If 1 Main;
  [
    Left = PickValid(ParmLeft, 100);
  ]
]
Main...
>

Given that module MyGraphic draws something in the window, adding the PickValid statement ensures that even if an invalid value is given as a parameter, the box will still be displayed, because its invalid parameter will have been replaced with the default value of 100.

Note that a local parameter is defined for Left, rather than using the parameter, parmLeft. This is necessary because, if the value passed to the module's parameter had been defined as a constant Invalid, it would not be possible to redefine it within MyGraphic using PickValid or any other statement.


PID

(Engine-Level Function)

Description | Perform PID Controller Function. This function returns a control value to maintain a parameter at a given setpoint.
Returns | Numeric
Usage | Steady State only.
Function Groups | Variable
Related to: | Deriv | Intgr
Format: | PID(PV, SP, Mode, Track, LowLimit, HighLimit, P, I, D, Bias, Time)
Parameters |
PV
Required. Any numeric parameter which gives the "process variable" to be maintained at the given setpoint.
SP
Required. Any numeric parameter that gives the value to use for the "setpoint." The PID function will change its return value to make the PV value match the SP value.
Mode
Required. Any numeric parameter giving the manual/auto mode for the function. When the parameter is not equal to 0, the function is in auto mode and uses the PID algorithm to control the output.
When the parameter is equal to 0, the function simply returns the value of the Track parameter. When the mode switches from manual to auto, the PID function implements a "bumpless transfer." This results in a smooth output change rather than an abrupt change.
This is done by forcing the internal integral to assume a value which forces the PID function to output a value which matches the Track parameter at the moment of the change. The integral value will not, however, exceed the value imposed upon it by the LowLimit and HighLimit parameters.
Mode | Algorithm | Derivative | Gains
0 | Manual | N/A | N/A
1 | Normal | Uses PV | Independent
2 | Normal | Uses PV | Dependent
3 | Normal | Uses Error | Independent
4 | Reverse | Uses Error | Dependent
5 | Reverse | Uses PV | Independent
6 | Reverse | Uses PV | Dependent
7 | Reverse | Uses Error | Independent

The PID function operates in eight automatic modes and one manual mode. These modes are listed in the above table. If in doubt, use mode 1 or 5.
The Action column in the above table indicates whether the PID function operates using normal action (SP - PV) or reverse action (PV - SP). With normal action, when PV increases, the function output decreases. With reverse action, when PV increases, the function output increases also.
The Derivative column in the above table indicates whether the PID function derivative bases its value upon PV or the error between PV and SP. For normal action, the error is (SP - PV). For reverse action, the error is (PV - SP). The difference between the two modes is only clear when the setpoint (SP) is changed. If the derivative uses PV, the response to setpoint changes is normal. If the derivative uses the error, the response to setpoint changes is faster but usually produces an abrupt change in the PID function output which is often undesirable.
The Gains column in the above table indicates which PID equation is used. Refer to the "Comments" section for these equations. The independent gains equation uses seconds as the time base and the gain parameter (P) does not affect either the integral or derivative. The dependent gain equation is the ISA equation. It uses minutes as the time base and the gain parameter (P) affects both the integral and derivative.

Track
Required. Any numeric parameter that gives the function output value when in manual mode (i.e. Mode equal to 0). When in auto mode, this parameter is ignored except at the instant immediately following the change from manual to auto mode.
LowLimit
Required. Any numeric expression giving the minimum value allowed for the PID function. The integral component may grow to a very large value if the setpoint (SP) is outside the controllable range.
Physical plant limitations may prevent the PV value from reaching the SP value. In such situations, the controller will respond very slowly to bringing the SP within the controllable range since it will take a long time for the large integral value to increase to the correct value.
The LowLimit parameter puts a lower bound on the value of the PID function. It does this by limiting the value of the internal integral that results in instantly regaining control after the setpoint is brought back into the controllable range. This feature is sometimes called "anti-reset windup."
HighLimit
Required. Any numeric expression giving the maximum value allowed for the PID function. This is similar to the LowLimit parameter except that it handles the upper limit for the PID function output.
P
Required. Any numeric expression giving the "proportional" or "gain" contribution to the PID output. It has no units (dimensionless).
I
Required. Any numeric expression giving the "integral" or "reset" contribution to the PID output. For independent gains, the units are inverse seconds and the I parameter is used directly as the gain for the integral portion of the PID equation.
For dependent gains, the units are minutes and the P parameter divided by I is used as the gain for the integral portion of the PID equation. Refer to the "Comments" section for the equations.
D
Required. Any numeric expression giving the "derivative" or "rate" contribution to the PID output. For independent gains, the units are seconds and the D parameter is used directly as the gain for the derivative portion of the PID equation.
For dependent gains, the units are minutes and P times D is used as the gain for the derivative portion of the PID equation. Refer to the "Comments" section for the equations.
Bias
Required. Any numeric expression giving the output offset or feed forward input. This value is added to the output value. Refer to the equations in the "Comments" section.
Time
Required. Any numeric expression giving the time interval in seconds between integral and derivative updates for the PID function. This value results in a smoothing of the derivative values for the sampled process data of VTScada .
The longer the time, the greater the smoothing. The shorter the time, the faster the controller response. A suggested time interval is the I/O update time for the PV parameter.
Comments Typically, this function is used to set a variable that controls a process output point. The equations used for this function follow.

Independent Gains Equation:

CV = P * E + I *∫ E dt + D * dA/dt + Bias

Dependent Gains Equation (ISA):

CV = P * (E + 1/I *∫ E dt + D * dA/dt) + Bias

Where:

  • CV PID function output.
  • E Error. E = (SP - PV) for normal action modes and E = (PV - SP) for reverse action modes.
  • A Derivative selection. For modes with the derivative based upon the PV value, A = PV. For modes with the derivative based upon the error value, A = E.

PID control may be done by a PLC or other device rather than VTScada. Setpoints, coefficients, and so forth may be read and written by VTScada I/O drivers. This form of PID control does not involve use of the VTScada PID function. See the reference manual of the PLC or other device and the VTScada I/O driver manual for more.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

{ Valve loop controller for heat exchanger }
valvePos = PID(cooledTemp { Process value },
               cooledSP { Setpoint for cooled temperature },
               Cond(valveManual, 0, 5)
               { Manual or reverse acting deriv
               uses PV, independent gains },
               manValvePos { Track value used in manual mode },
               0, 1 { Lower/upper limits of valve position },
               0.1 { P coefficient - proportional gain },
               0.5 { I coeff - integral gain or reset time },
               0.02 { D coefficient - derivative gain or rate },
               0 { Output bias },
               0.5 { Update loop every half second });

This performs PID control of a heat exchanger. A valve is used to control a temperature given a setpoint. If valveManual is true, the PID simply updates its internal integrators every half second using manValvePos. If valveManual is false, PID control is updated every half second. The P, I, and D gains are constants, but might be variables, to allow online tuning.


Pie

Deprecated. Do not use in new code.

(Engine-Level Function)

Description | Draws a pie shaped wedge on the screen.
Returns | Nothing
Usage | Steady State only.
Function Groups | Graphics
Related to: | Arc | Ball | Circle | Ellipse | GUIArc | GUIChord | GUIEllipse | GUIPie
Format: | Pie(X, Y, Radius, Angle1, Angle2, Foreground, Pattern, Background)
Parameters |
X
Required. Any numeric expression giving the X coordinate of the center of the pie on the screen.
Y
Required. Any numeric expression giving the Y coordinate of the center of the pie on the screen.
Radius
Required. Any numeric expression giving the radius of the pie specified in units of X screen coordinates.
Angle1
Required. Any numeric expression giving the starting angle of the pie in radians. An angle of 0 lies on the X axis to the right of the center of the pie.
Angle2
Required. Any numeric expression giving the ending angle of the pie in radians.
Foreground
Required. Any numeric expression giving the color index for the foreground color of the pie fill pattern.
Pattern
Required. Any numeric expression giving the hatch Fill Patterns to use for the fill. The valid hatch style numbers are from 1 to 25 inclusive.
Background
Required. Any numeric expression giving the background color for the hatch pattern. This value is only significant if the Pattern parameter is not equal to 1.
Comments

This statement has been superseded by the GUIPie function and is maintained for backwards compatibility only.
The pie is drawn in a counterclockwise direction from the Angle1 to Angle2.

As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.

Example:

Pie(100,200 { X-Y coordinates for the center of the pie },
    200 { Radius in pixels },
    0 { Start angle (3 o'clock position) },
    3.14 { Draw counterclockwise for 180 degrees },
    10, 1, 0 { Light green solid (background ignored });

This draws the top half of a light green circle.


PImageSelect

Description: | Called graphic module that connects an image selection tool to a given parameter number. Buttons and dialogs for Select, Adjust and Clear operations are provided.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PImageSelect(ParmNum,ParmDef [, Title, PtrWaitClose, ShowBevel, ColorReplaceParmDef, DisableRotation])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) to alter in the caller.
ParmDef
Required. The parameter definition structure.
Title
An optional parameter that is any text expression to be used as a the title to put on the bevel.
PtrWaitClose

Pointer to a bit-wise value. Prevents the Idea Studio closing while a dialog is open. (*PtrWaitClose != 0)

Bit 0 indicates a regular wait condition

Bit 1 indicates a wait condition due to an expression (compilation) error.
*PtrWaitClose being set to 2 (or 3) causes the warning dialog regarding an expression with errors in it to be shown by the caller.

(See: Bitwise Parameters & Operations)

ShowBevel
Any Boolean expression that when set to TRUE causes a bevel to be drawn around the control. Defaults to TRUE
ColorReplaceParmDef
Optional. Parameter definition structure for legacy color to use in place of orange 241.
DisableRotation
Optional Boolean. Rotation controls will be disabled when set TRUE. Defaults to FALSE.
Comments:

Further information about parameter information structures may be found in examples of the ParameterEdit function.

Example:

   { Indicator image selection }

  GUITransform(0, 1, 1, 0,
              1 - (0),
              PEBottom + Space + BevTImgSelHt,
              PanelWd,
              1 - (PEBottom + Space), 1,
              0, 0, 1, 0,
              0, 0, 0,
              PImageSelect(Parms[#IndicatorImage],
                           ParmDefs[#IndicatorImage],
                           \GetPhrase("ImageLabel"),
                           &(SubWaitClose[1])));

In this example, an array is being used to store values for the PtrWaitClose parameter. Parameter definitions for the panel have been stored in an array, similar to the parameters array.


PIPAddressList

(Dialog Library)

Description: | Uses an IPAddressList to set a parameter with a semicolon-delimited IP address list.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PServerListName | PSecBit | PSelectObject | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PIPAddressList(ParmNum [, Trigger, FocusID, Title, DrawBevel, AlignTitle])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Trigger
Set when the variable is changed.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Title
An optional parameter that is any text expression to be used as a the title to put on the bevel.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control.
AlignTitle

An optional parameter that is any logical expression. If TRUE (non-0) the title is included in the calculation for vertical alignment, if FALSE (0) it is added to the droplist after it and its bevel has been vertically aligned. The default is true.

Usual height: 130 pixels.

Comments:

This module should be used whenever the user needs an IP Allow filter for use with the SocketManagerServer.

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the value of the element indicated by ParmNum.
The recommended minimum height ranges from 100 pixels for a plain list to 130 pixels for a list with an aligned titled bevel. The up/down buttons will hide if there is not enough room for them to display.

Example:

{***** Allowed incoming IP address (or ranges) -- optional *****}
GUITransform(30, 309, 240, 177, { Ht 130 }
             1, 1, 1, 1,
             1, 0, 0, 1, 0, 0, 0, 0,
             \DialogLibrary.PIPAddressList(\#IPAddressAllow         { ParmNum },
                                           Trigger,
                                           Valid(Parms[\#ListenerGroup]) ?  10 { FID to 19} : 0,
                                           \GetPhrase("IPAllowLabel"){ Title     },
                                           TRUE                     { DrawBevel  },
                                           TRUE                     { AlignTitle }));


PIPListenerGroup

Dialog Library

Description: | Draws a droplist of all available IP Listener Groups. (In general, the groups will be the IP Listener tag names.)
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PIPListenerGroup(ParmNum, Trigger, FocusID [, Title, DrawBevel, VertAlign, AlignTitle])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter
Trigger
Set when the variable is changed.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Title
An optional parameter that is any text expression to be used as a the title to put on the bevel.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control.
VertAlign

An optional parameter that is any numeric expression that sets the vertical alignment of the droplist according to one of the following options:

VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
An optional parameter that is any logical expression. If TRUE (non-0) the title is included in the calculation for vertical alignment, if FALSE (0) it is added to the droplist after it and its bevel has been vertically aligned. The default is true.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..

The "P" tools are intended for use only in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the value of the element indicated by ParmNum.

Usual height: 45 pixels.

Examples:

{***** Network Listener group *****}
GUITransform(30, 168, 240, 123, { Ht 45 }
             1, 1, 1, 1, 1            { No scaling                     },
             0, 0, 1, 0               { No movement; visible; reserved },
             0, 0, 0                  { Not selectable                 },
             \DialogLibrary.PIPListenerGroup(\#ListenerGroup,
                                             Trigger,
                                             TRUE                  {ID},
                                             \IPNetworkListenerGroup));


Pipe

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Draw a double line
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUIPipe | Line | ZPipe
Format: | Pipe(Width, Color, Curvature, X1, Y1, X2, Y2, ...)
Parameters: |
Width
Required. Any numeric expression giving the spacing of the lines in units of X screen coordinates. The width is always rounded to result in an odd number of pixels on the screen. The minimum width displayed will be 1 pixel.
Color
Required. Any numeric expression giving the VTScada Color Palette of the pipe.
Curvature
Required. Any numeric expression giving the radius of curvature of the corners for the pipe. This is specified in units of X screen coordinates.

If the number of endpoints is 2, the Curvature is ignored.
X1, Y1, X2, Y2, ...
Required. Any numeric expressions giving the screen coordinates of the pipe endpoints.
Comments:

The radius of curvature of the pipe corners is the radius of the arc that joins the line endpoints. A Curvature of 0 results in sharp (square) pipe corners. Larger Curvature numbers result in greater rounding of the pipe corners.
This statement is useful for drawing piping on the screen, especially if it changes dynamically.

Within an Anywhere Client session, this function does nothing.

Example:

Pipe(10 { Width of pipe in pixels },
     11 { Light cyan color },
     20 { Radius of curvature in pixels },
     100, 100 { Coordinates of first point },
     0, 900 { Coordinates of second point },
     100, 200 { Coordinates of third point },
     200, 500 { Coordinates of fourth point });

This statement draws a cyan colored pipe, 50 pixels wide between four points.


PipeStream

(Engine-Level Function)

Description: | Returns a stream based on an operating system named pipe.
Returns: | Stream
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | BlockWrite| BuffStream | CloseStream | FileStream | GetStreamLength | PeekStream | SRead | StreamEnd | SWrite
Format: | PipeStream(Name, Mode)
Parameters: |
Name
Required. Any text expression giving the name of the named pipe.
Mode
Required. Any numeric expression giving the manner in which the pipe is opened, as shown in the following table:
Mode | Open state
0 | Not opened yet
1 | Opened for read
2 | Opened for read or write
Comments: None

Example:

If ! Valid(pStream);
[
  pStream = PipeStream("\\dataserv\datapipe", 1);
]

This opens a pipe named pStream as a stream from which to read data.


PixelColor

(Engine-Level Function)

Description: | Returns the color of a pixel in the window.
Returns: | Numeric or String (see 4th parameter)
Usage: | Script or steady state.
Function Groups: | Color, Graphics
Related to: | GetSystemColor
Format: | PixelColor(Object, X,Y[,UseRGB])
Parameters: |
Object
Required. Any expression that returns an object value. This identifies the window where the pixel is drawn.
X
Required. Any numeric expression, giving the x-axis coordinate of the location of the pixel.
Y
Required. Any numeric expression, giving the y-axis coordinate of the location of the pixel.
UseRGB
Optional. Any Boolean expression, which when true, will cause the pixel color to be returned as an RGB string. If false, the numeric palette value will be returned.
Comments: Location (x, y) is taken to be in the window where the module instance identified by Object is drawn.

Example:

mouseColor = PixelColor(Self(),XLoc(),YLoc());

This finds the color under the mouse in the window where this function is defined.


PKTrend

Description: | Displays a tag in a history window whenever it receives a left-click in the defined area.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Variable
Related to: | WinTooltipCtrl | Navigator Calls (Shortcut Menu)
Format: | \PKTrend(LeftReference, BottomReference, RightReference, TopReference, PtObj[, Enable, HistoryWindowParms])
Parameters: |
LeftReference
The left side reference of the target area.
BottomReference
The bottom side reference of the target area.
RightReference
The right side reference of the target area.
TopReference
The top side reference of the target area.
PtObj
The object value of the point to trend
Enable
Optional Boolean. Flag - TRUE when this action is enabled
HistoryWindowParms
Optional array. Parameters for the History Window
Comments:

Used only as part of a custom widget, created from scratch.

If a history window is already open, PkTrend adds its PtObj to the existing window, otherwise it opens a new history window and adds its PtObj to the new window.

PkTrend adds all of the fields in PtObj that are supported by AnalogDataSource, DigitalDataSource, or NotesDataSource to the history window. It also adds numerous related notes tags:

1. The preconfigured system-wide notes tag.

2. All of the notes tags that have a Area field that matches PtObj's Area field.

3. All of the notes tags in all of the groups that contain PtObj.

Example:

((DisableTools || True(TrendPopupDisable)) ? Invalid : Self)\PkTrend(Left, Bottom, Right, Top, \Root, TRUE);


Platform

(Engine-Level Function)

Description: Returns a fifteen element structure that indicates the platform under which VTScada is currently running.
Returns: Structure - see comments
Usage: Script only.
Function Groups: Network, Software and Hardware
Related to: WKStaInfo
Format: Platform()
Parameters: None
Comments: The return value for this function is a fifteen element structure in which the elements have the following meanings
Element | Value
PlatformId | 0 = Windows ME, Windows 98 SE, Windows 95 1 = Windows NT, Windows 2000, Windows XP, Windows Server 2003, Windows Server 2008, Windows Vista, Windows 7
MajorVersion | Major version number of the operating system
MinorVersion | Minor version number of the operating system
ProductType | Additional information about the system. For a list of the codes and their meanings, refer to http://msdn2.microsoft.com/en-us/library/ms724833.aspx
SuiteMask | Identifies the product suites available on the system. For a list of the codes and their meanings, please refer to http://msdn2.microsoft.com/en-us/library/ms724833.aspx
BuildNumber | The build number of the operating system
SPName | The latest service pack installed on the system
SPMajorVersion | Major version # of latest service pack installed
SPMinorVersion | Minor version # of latest service pack installed
ProductInfo | For a list of the codes and their meanings, please refer to http://msdn2.microsoft.com/en-us/library/ms724358.aspx
CPUArchitecture | A 0 indicates x86 architecture, while a 9 indicates x64 architecture
NumberOfCPUs | The number of processing threads in the machine.
PhysicalMemory | The amount of physical memory, measured in bytes. Not the available memory.
InServiceMode | TRUE if VTScada has been started in service mode
TempFilePath | The path of the directory designated for temporary files

Some common names and their major and minor versions are as follows:

Common Name | Major Version | Minor Version
Windows Server 2012 | 6 | 2
Windows 8.1 | 6 | 3
Windows 2016 | 10 | 0
Windows 2019 | 10 | 0
Windows 10 | 10 | 0
Windows 11 | 10 | 0

Prior to VTS 8.0, this function returned a three-element array. Backwards compatibility has been maintained so that code designed to use the earlier version of this function will still work properly.

Example:

If 1 Main;
[
  p = Platform();
    IfThen(p\MajorVersion == 6 && p\MinorVersion == 0
 && p\ProductType == 1,
       UsingVista = 1;
    );
];

This script checks to see if the platform is Windows Vista


Play

(Engine-Level Function)

Description: | Plays a multimedia sound file as installed in the operating system. It differs from Sound in that it is a steady-state statement and is supported by VTScada Internet Client (VIC).
Returns: | Boolean. See comments.
Usage: | Steady State only.
Function Groups: | Speech and Sound
Related to: | Sound
Format: | Play(File, Option, Enable [, DevID])
Parameters: |
File
Required. Any text expression giving the file name to play. If the extension is omitted, the default extension ".WAV" is added. If an empty string is provided here, then any currently playing sound is stopped.
Option
Required. Any numeric expression that indicates how to play the file. The value of Option may be obtained by adding together numbers from the following table:
Value | Bit No. | Option
1 | 0 | Play asynchronously (don't wait)
2 | 1 | Don't use default sound if file missing.
4 | 2 | Reserved for future use.
8 | 3 | Loop the sound until next Sound function executed.
16 | 4 | Don't stop any currently playing sound.

If Option is "0", VTScada will halt all execution until the sound is finished. This is not recommended. Add "1" to avoid this behavior.

(See: Bitwise Parameters & Operations)

Enable
Required. A value indicating whether the sound is played. This can be one of:
Value | Description
1 | Sound is played.
0 or Invalid | The sound being played is stopped.
DevID
An optional parameter that is required when you wish to play a sound through a device other than the default system audio device. The ModemDev function can return the identifier of the wave device for a voice modem.
Option value 8 is the only option considered when DevID has been set.
Note: DevID is ignored for VIC sessions. Options must be configured appropriately if there is a chance that playback might occur over a VTScada Internet Client.
Comments:

The return value is a Boolean flag. It is TRUE while the file is playing and FALSE when not playing.

Playback will stop when any of the following conditions occur:

  • Enable is set to false
  • File is set to Invalid or ""
  • The steady state call, Play() is stopped.

If the session is remote via a VTScada Internet Client (VIC), the return value of this function will not be set to true until the audio file has been completely transferred and the playback has begun remotely.


Plot

(Engine-Level Function)

Description: Displays a plot of a subsection of a numeric array in a particular area of the window.
Returns: Nothing
Usage: Steady State only.
Function Groups: Graphics
Related to: PlotBuff | PlotXY
Format:

Format version 1:
Plot(ArrayElem, N, Low, High, X1, Y1, X2, Y2, Style, Color, Pattern, PatternBackground)

Format version 2:
Plot(ArrayElem, N, Low, High, X1, Y1, X2, Y2, Pen, Brush [, XORMode, Direction, DrawStepped, BitNumber, Average])

Plot takes the first parameter set or else detects that the Style parameter is a Pen, in which case the second parameter set is used.

Parameters:
ArrayElem
Required. Any numeric expression specifying the starting array element to plot. If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to plot starting at the element given by the first parameter. N must be greater than or equal to 2, and no greater than 32000.

If this parameter is greater than the dimension of the first array, the number of points plotted will be the array dimension.

If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Low
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be less than High but must not be equal to it.

In the standard case, when this value is less than High, it will define the minimum value to display. For example, if Low was 10, a data value of 10 would fall on the edge of the bounding box, on either the line described by X1, if the plot is vertical, or on the line described by Y1, if the plot is horizontal. Any values below 10 in this case would not be shown since they would be outside the clipped box.
High
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than Low but must not be equal to it. In the standard case, when this value is greater than Low, it will define the maximum value to display. For example, if High was 1000, a data value of 1000 would fall on the edge of the bounding box, on either the line described by X2, if the plot is vertical, or on the line described by Y2, if the plot is horizontal. Any values above 1000 in this case would not be shown since they would be outside the clipped box.
X1 (Left)
Required. Any numeric expression giving the X coordinate on the screen of the left side of the plot area.
For horizontal plots, this is the screen coordinate of the first point or bar plotted. For vertical plots, this is the value which corresponds to the Low parameter value. For vertical bar plots, X1 is the base coordinate for the bars.
Y1 (Bottom)
Required. Any numeric expression giving the Y coordinate on the screen of bottom side of the plot area.
For vertical plots, this is the screen coordinate of the first point or bar plotted. For horizontal plots, this is the value which corresponds to the Low parameter value. For horizontal bar plots, Y1 is the base coordinate for the bars.
X2 (Right)
Required. Any numeric expression giving the X coordinate on the screen of the right side of the plot area.
For horizontal plots, this is the screen coordinate of the last point or bar plotted. For vertical plots, this is the value which corresponds to the High parameter value.
Y2 (Top)
Required. Any numeric expression giving the Y coordinate on the screen of the top side of the plot area.
For vertical plots, this is the screen coordinate of the last point or bar plotted. For horizontal plots, this is the value which corresponds to the High parameter value.
Style
Required (Format version 1 only). Any numeric expression giving the style of the plot. The plot Style gives the line style, direction, bit number for bits plots, and the number of points to average per point displayed.

The Style is determined by adding together the following values:
Line style + Direction + Path + Bit number + Average

Line style is a number between 1 and 5 inclusive which gives the line style for line plots. A line style of 1 indicates a solid line (see Chapter 9 for more styles). For bar plots, the line style portion of the Style parameter is ignored.

Direction is either 0 or 10. Use 0 for a standard horizontal plot (array index runs along the X axis and values are plotted up or down). Use 10 for a vertical plot (array index runs along the Y axis and values are plotted left or right).

Path is either 0 or 50. A 0 indicates that line plots are to be drawn directly from point to point. A 50 indicates that plots are to be drawn in a step fashion with two line segments between each point. The first segment runs parallel to the X-axis and the second segment runs parallel to the Y-axis. This produces a square-looking plot. These step plots are useful for plotting status values which change in jumps rather than continuously. The Path value is ignored for bar plots.

Bit number is either 0 or a value starting at 100. This is the number of the bit to use in the array data for plotting. If the normal entire value of the data is to be plotted, use 0 for this value. If only one of the bits from the data is to be plotted, use the bit number plus 1. The value to add is (Bit number + 1) * 100 or 0. The ability to plot only a single bit from an array of short or long values allows status data to be stored very efficiently by not requiring a separate array for each status value. For bit plots, the value plotted is always a 0 or a 1 corresponding to the value of the selected bit. The use of this plotting option is usually done in conjunction with a Path value of 50 for step plots.

Average is either 0 or a value starting at 10000. This is the number of consecutive array points to average to give a single point on the screen. It can be used to plot a very large array of values on the screen without having to draw all of the points on the screen. This will produce a smoothed plot and reduce the drawing time. The number to add is (Data points per displayed point - 1) * 10000.
Color
Required (Format version 1 only). Any numeric expression giving the VTScada Color Palette of the line and the foreground color for filled plots. If the number is less than 10000, the plot is non-destructive. If the number is greater than or equal to 10000, the plot is destructive and the actual color used is Color - 10000.
RGB color strings may not be used.
Pattern
Required (Format version 1 only). Any numeric expression giving the bar Fill Patterns for the plot. For a Pattern value of 0, the plot is a line plot.
For Pattern values in the range of 1 to 25 inclusive, the plot is a bar plot with the hatch pattern corresponding to the Pattern parameter value. If the parameter is 1, the bars are a solid color and the Background parameter is ignored.
PatternBackground

Required (Format version 1 only). Any numeric expression giving the color number of the plot fill background color. This number is ignored if the Pattern parameter is equal to 1. For values of Pattern greater than one, it gives the background color for the bar.

RGB color strings may not be used.

Pen
Required (Format version 2 only). The pen to be used (if any). Must be provided, but will be ignored for bar plots.
Brush
Required (Format version 2 only). The brush to be used (if any). For line drawing, this parameter must be provided with pattern 0.
XORMode
(Format version 2 only) An optional parameter specifying whether the plot is destructive (if destructive, the plot line won't be affected by the background color).
If set to 0 or Invalid (default), the destructive drawing mode will be used. If set to 1, the non-destructive or XOR drawing mode will be used.
Direction
An optional parameter specifying the horizontal or vertical direction for the plot. 0 or Invalid indicates horizontal, while 1 indicates vertical.
DrawStepped
(Format version 2 only) An optional parameter specifying whether the plot is to be drawn from point-to-point, or stepped. 0 or Invalid indicates point-to-point, while 1 indicates stepped.
BitNumber
(Format version 2 only) An optional parameter specifying the use of a whole value or a bit number. Invalid indicates a whole value should be used, while >=0 indicates that the specified bit number should be used. No default
Average
(Format version 2 only) An optional parameter specifying whether consecutive points should be averaged to give a single point. Invalid or 0 indicates that averaging should not be used, while >0 indicates that the number of consecutive points should be averaged to give a single point. No default.
Comments: This function is a layered graphics statement.
The Plot statement will execute timer functions during the plotting process. This will allow time critical functions such as driver I/O and data logging to continue running during the relatively long times it takes to update a plot on the screen.

Through the ordering of the Low, High, X1, X2, Y1, and Y2 parameters, the plot may have 8 different orientations for line plots and 16 different orientations for bar plots. The normal left to right plot with the minimum at the bottom will have Low < High, X1 < X2, and Y1 < Y2.

By exchanging Low and High (i.e. Low > High), the plot will have the minimum value at the top with bars still drawn from the bottom. Exchanging X1 and X2 (i.e. X1 > X2) will plot values from right to left. Exchanging Y1 and Y2 (i.e. Y1 > Y2) will plot values with the minimum at the top with bars being drawn from the top also. Combining these actions with the Style (horizontal or vertical) gives all possible plot orientations.
The plot ignores invalid data elements in the array and leaves blank spaces for them on the display. If the number of points extends past the end of the array, the plot will continue at the first of the array until N points or all the points of the array have been plotted.

The plot area defined by X1, Y1, X2, and Y2 limits the area which can be plotted on the screen. Any points which fall outside this area will not appear on the screen but will be "clipped" at the boundary.

Example:

Given an array with 10 elements whose values range from 0 to 100.

IF Watch(1);
[
   Data = new(10);
   Data[0] = 0;
   Data[1] = 1;
   Data[2] = 20;
   Data[3] = 25;
   Data[4] = 26;
   Data[5] = 40;
   Data[6] = 55;
   Data[7] = 60;
   Data[8] = 75;
   Data[9] = 99;
]

A plot of the data may be done with the following:

Plot(data[0] { Starting element },
     10      { Number of elements to plot },
     0       { Low limit },
     100      { High limit },
     100, 150, 200, 50 { Bounding box for plot area, offset for 42 pixel title bar},
     1+10+50 { Style: Solid line style, vertical plot, step fashion },
     4       { Color: dark red},
     0       { Pattern: Line plot (not bars) },
     0       { Pattern Background: Ignored for line plot });

This statement will result in a line plot of 10 data points in an area in the upper left corner of the window. The line will be vertically orientated meaning that Data[0] is at the bottom left corner and each successive array value is plotted one step higher, with values increasing to the right. It is a single line in style and dark red in color. It will follow a step pattern. That is, it will look like the outline of a bar graph of the points.

Warning: when drawing a stepped line plot, the final vertical rise will be clipped:

Example 2:

Plotting the same values as a horizontal plot, using Pen and Brush values:

Plot(Data[0],
     10,
     0,
     100,
     200, 150, 300, 50,
     Pen("<FFFFFF00>" { yellow }, 3 { dotted }, 2 { pixel width }),
     Brush("<FFFFFF>", 0, 2 { Stripe pattern });
     {, XORMode, Direction, DrawStepped, BitNumber, Average});


PlotBuff

(Engine-Level Function)

Description: Displays a plot of a subsection of a buffer in a particular area of the window after converting the buffer to element values. Extends Plot.
Returns: Nothing
Usage: Steady State only.
Function Groups: Graphics, String and Buffer
Related to: Plot | PlotXY
Format: PlotBuff(Buffer, Offset, N, Type, Low, High, X1, Y1, X2, Y2, Style, Color, Pattern, Background)

...OR...

PlotBuff(Buffer, Offset, N, Type, Low, High, X1, Y1, X2, Y2, Pen, Brush [, XORMode, Direction, DrawStepped, BitNumber, Average])
Parameters:
Buffer
Required. Any text expression that contains data to be plotted.
Offset
Required. Any numeric expression that gives the starting buffer position in data elements (not bytes or characters) of the first data element.
N
Required. Any numeric expression giving the number of elements to plot starting at the element given by the offset parameter. N must be greater than or equal to 2, and no greater than 32000.

If this parameter is greater than the length of the buffer, the number of points plotted will be the number of points available in the buffer. If the end of the buffer is encountered before N points have been plotted, plotting continues with the first point in the buffer (offset 0).
Type
Required. Any numeric expression giving the type of data held in the buffer. The types are described in the following table:
Value | Type
0 | Byte (0-255)
1 | Short (2 bytes. -32768 to 32767)
2 | Long (4 byte signed integer)
3 | Float (4 byte IEEE floating point)
Low
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be less than High but must not be equal to it. In the standard case, when this value is less than High, it will define the minimum value to display.

For example, if Low was 10, a data value of 10 would fall on the edge of the bounding box, on either X1, if the plot is vertical, or on Y1, if the plot is horizontal. Any values below 10 in this case would not be shown - they would be outside the clipped box.
High
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than Low but must not be equal to it. In the standard case, when this value is greater than Low, it will define the maximum value to display.

For example, if High was 1000, a data value of 1000 would fall on the edge of the bounding box, on either X2, if the plot is vertical, or on Y2, if the plot is horizontal. Any values above 1000 in this case would not be shown - they would be outside the clipped box.
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the plot area. This is typically, although not necessarily, the left side of the plot.

For horizontal plots, this is the screen coordinate of the first point or bar plotted. For vertical plots, this is the value which corresponds to the Low parameter value. For vertical bar plots, X1 is the base coordinate for the bars.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of one side of the plot area. This is typically, although not necessarily, the bottom of the plot.

For vertical plots, this is the screen coordinate of the first point or bar plotted. For horizontal plots, this is the value which corresponds to the Low parameter value. For horizontal bar plots, Y1 is the base coordinate for the bars.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the plot area opposite to X1. This is typically, although not necessarily, the right side of the plot.

For horizontal plots, this is the screen coordinate of the last point or bar plotted. For vertical plots, this is the value which corresponds to the High parameter value.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the side of the plot area opposite to Y1. This is typically, although not necessarily, the top of the plot. For vertical plots, this is the screen coordinate of the last point or bar plotted. For horizontal plots, this is the value which corresponds to the High parameter value.
Style
Required. Any numeric expression giving the style of the plot - the line style, direction, bit number for bits plots, and the number of points to average per point displayed.

If PlotBuff senses that the Style parameter is a Pen, the Destructive, XORMode, DrawStepped, BitNumber, and Average parameters will become relevant. The Style is determined by adding together the following values.

Line style + Direction + Path + Bit number + Average

Line style is a number between 1 and 5 inclusive, giving the line style for line plots. A line style of 1 indicates a solid line. For bar plots, the line style portion of the Style parameter is ignored.
Direction is either 0 or 10, where 0 is a horizontal plot and 10 is a vertical plot.
Path is either 0 or 50. A 0 indicates that line plots are to be drawn directly from point to point. A 50 indicates that plots are to be drawn in a step fashion with two line segments between each point. The first segment runs parallel to the X-axis, the second, parallel to the Y-axis. This produces a square-looking plot. These step plots are useful for plotting status values which change in jumps rather than continuously. The Path value is ignored for bar plots.
Bit number is the number of the bit to use in the data for plotting. If the normal entire value of the data is to be plotted, use 0 for this value. If only one of the bits from the data is to be plotted, use the bit number plus 1. The value to add is (Bit number + 1) * 100 or 0. The ability to plot only a single bit from short or long values allows status data to be stored very efficiently by not requiring a separate buffer for each status value. For bit plots, the value plotted is always a 0 or a 1 corresponding to the value of the selected bit. This plotting option is usually done in conjunction with a Path value of 50 for step plots.
Average is the number of consecutive points to average to give a single point on the screen. It can be used to plot a very large number of values on the screen without having to draw all of the points on the screen. This will produce a smoothed plot and reduce the drawing time. The number to add is (Data points per displayed point - 1) * 10000.
Color
Required. Any numeric expression giving the VTScada Color Palette of the line and the foreground color for filled plots. If the number is less than 10000, the plot is non-destructive. If the number is greater than or equal to 10000, the plot is destructive and the actual color used is Color - 10000.
Pattern
Required. Any numeric expression giving the bar Fill Patterns for the plot. For a Pattern value of 0, the plot is a line plot. For Pattern values in the range of 1 to 25 inclusive, the plot is a bar plot with the hatch pattern corresponding to the Pattern parameter value. If the parameter is 1, the bars are a solid color and the Background parameter is ignored.
Background
Required. Any numeric expression giving the color number of the plot fill background color. This number is ignored if the Pattern parameter is equal to 1. For values of Pattern greater than 2, it gives the background color for the bar.
Pen
Required. The pen to be used (if any).
Brush
The brush to be used (if any).
XORMode
An optional parameter specifying whether the plot is destructive (if destructive, the plot line won't be affected by the background color). If set to 0 or Invalid (default), the destructive drawing mode will be used. If set to 1, the non-destructive or XOR drawing mode will be used.
Direction
An optional parameter specifying the horizontal or vertical direction for the plot. 0 or Invalid indicates horizontal, while 1 indicates vertical.
DrawStepped
An optional parameter specifying whether the plot is to be drawn from point-to-point, or stepped. 0 or Invalid indicates point-to-point, while 1 indicates stepped.
BitNumber
An optional parameter specifying the use of a whole value or a bit number. Invalid indicates a whole value should be used, while >=0 indicates that the specified bit number should be used.
Average
An optional parameter specifying whether consecutive points should be averaged to give a single point. Invalid or 0 indicates that averaging should not be used, while >0 indicates that the number of consecutive points should be averaged to give a single point.
Comments: This function is a layered graphics statement.
This statement will execute timer functions during the plotting process, allowing time critical functions such as driver I/O and data logging to continue running during the relatively long times it takes to update a plot on the screen.

Through the ordering of Low, High, X1, X2, Y1, and Y2, there are 8 different orientations possible for line plots and 16 for bar plots. The normal left to right plot with minimum at the bottom will have Low < High, X1 < X2, and Y1 < Y2. By exchanging Low and High (i.e. Low > High), the plot will have minimum at the top with bars drawn from the bottom. Exchanging X1 and X2 (i.e. X1 > X2) will plot values from right to left. Exchanging Y1 and Y2 (i.e. Y1 > Y2) will plot values with minimum at the top and bars drawn from the top also. Combining these actions with the Style (horizontal or vertical) gives all possible plot orientations.

If the number of points extends past the end of the buffer, the plot will continue at the first of the buffer until N points or all the points of the buffer have been plotted.
The plot area defined by X1, Y1, X2, and Y2 limits the area which can be plotted on the screen. Any points which fall outside this area will not appear on the screen but will be "clipped" at the boundary.

The PlotBuff statement works the same as the Plot statement. However, invalid values cannot exist in the buffer. The RAM memory savings of using buffers rather than arrays is in the range of 45% to 73%.

Example:

{ Create the buffer and store the data in it }
If ! Valid(data);
[
  data = MakeBuff(5, 0);
  SetByte(data, 0, 1);
  SetByte(data, 1, 9);
  SetByte(data, 2, 0);
  SetByte(data, 3, 6);
  SetByte(data, 4, 10);
]
PlotBuff(data { Buffer name },
         0, 10 { Start at first point and plot 10 points },
         0 { Data in the range of 0-255; a single byte },
         0, 10 { Low and high limits },
         100, 500, 600, 100 { Bounding box for clipped area },
         0 { Horizontal plot },
         12 { Light red },
         6 { Bar plot with vertical line pattern },
         4 { Dark red background for pattern });

This plots a bar graph of 5 points in an area centered in the window. The bars will be vertical (points run along the horizontal), with light red vertical line pattern on dark red background.


PlotXY

(Engine-Level Function)

Description: | Displays a plot of a curve in the window given the X and Y values in two arrays.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Plot | PlotBuff | Sort
Format: | PlotXY(XArrayElem, YArrayElem, N, Left, Right, Top, Bottom, X1, Y1, X2, Y2, Style, Color) < OR > PlotXY(XArrayElem, YArrayElem, N, DataLimitLeft, DataLimitRight, DataLimitTop, DataLimitBottom, X1, Y1, X2, Y2, Pen, Reserved [, XORMode, Direction, DrawStepped, BitNumber, Average]) PlotXY takes the first parameter set or else detects that the Style parameter is a Pen, in which cast the second parameter set is used:
Parameters:
XArrayElem
Required. Any array element giving the starting point in the array of X coordinates. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
YArrayElem
Required. Any array element giving the starting point in the array of Y coordinates. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to plot starting at the element given by the first parameters. N must be greater than or equal to 0, and no greater than 16384.

If this parameter is greater than the dimension of the first array, the number of points plotted will be that array dimension.

If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
DataLimitLeft
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be less than Right but must not be equal to it. In the standard case, when this value is less than Right, it will define the minimum value to display from the array of X-values.
For example, if Left was 10, a data value of 10 would fall on the edge of the bounding box, on either X1, if the plot is vertical, or on Y1, if the plot is horizontal. Any values below 10 in this case would not be shown - they would be outside the clipped box.
DataLimitRight
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than Left but must not be equal to it. In the standard case, when this value is greater than Left, it will define the maximum value to display from the array of X-values.
For example, if Right was 1000, a data value of 1000 would fall on the edge of the bounding box, on either X2, if the plot is vertical, or on Y2, if the plot is horizontal. Any values above 1000 in this case would not be shown - they would be outside the clipped box.
DataLimitTop
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be less than Bottom but must not be equal to it. In the standard case, when this value is less than Bottom, it will define the minimum value to display from the array of Y-values.
For example, if Top was 10, a data value of 10 would fall on the edge of the bounding box, on either Y1, if the plot is vertical, or on X1, if the plot is horizontal. Any values below 10 in this case would not be shown - they would be outside the clipped box.
DataLimitBottom
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than Top but must not be equal to it. In the standard case, when this value is greater than Top, it will define the maximum value to display from the array of Y-values.
For example, if Bottom was 1000, a data value of 1000 would fall on the edge of the bounding box, on either Y2, if the plot is vertical, or on X2, if the plot is horizontal. Any values above 1000 in this case would not be shown - they would be outside the clipped box.
X1 (Left)
Required. Any numeric expression giving the X coordinate on the screen of the left side of the plot area. This corresponds to the Left parameter for horizontal plots and to the Top parameter for vertical plots.
Y1 (Top)
Required. Any numeric expression giving the Y coordinate on the screen of the top side of the plot area. This corresponds to the Top parameter for horizontal plots and to the Left parameter for vertical plots.
X2 (Right)
Required. Any numeric expression giving the X coordinate on the screen of the side of the plot area opposite to X1. This corresponds to the Right parameter for horizontal plots and to the Bottom parameter for vertical plots.
Y2 (Bottom)
Required. Any numeric expression giving the Y coordinate on the screen of the side of the plot area opposite to Y1. This corresponds to the Bottom parameter for horizontal plots and to the Right parameter for vertical plots.
Style
Required. Any numeric expression giving the style of the plot - the line style, direction, bit number for bits plots, and the number of points to average per point displayed. If PlotXY senses that the Style parameter is a Pen, XORMode, DrawStepped, BitNumber, and Average parameters will become relevant. The Style is determined by adding together the following values.

Line style + Direction + Path + Bit number + Average

Line style is a number between 1 and 10 inclusive which gives the line style for line plots. A line style of 1 indicates a solid line. For other line styles, the background color is set to the current background screen color.
Direction is either 0 or 10. A 0 indicates a horizontal plot and a 10 indicates a vertical plot.
Path is either 0 or 50. A 0 indicates that line plots are to be drawn directly from point to point. A 50 indicates that plots are to be drawn in a step fashion with two line segments between each point. The first segment runs parallel to the X-axis and the second segment runs parallel to the Y-axis. This produces a square-looking plot. These step plots are useful for plotting status values which change in jumps rather than continuously.
Bit number is the number of the bit to use in the YArray data for plotting. If the normal entire value of the data is to be plotted, use 0 for this value. If only one of the bits from the data is to be plotted, use the bit number plus 1. The value to add is (Bit number + 1) * 100 or 0. The ability to plot only a single bit from an array of short or long values allows status data to be stored very efficiently by not requiring a separate array for each status value. For bit plots, the value plotted is always a 0 or a 1 corresponding to the value of the selected bit. The use of this plotting option is usually done in conjunction with a Path value of 50 for step plots.
Average is the number of consecutive array points to average to give a single point on the screen. Both XArray and YArray values are averaged. It can be used to plot a very large array of values on the screen without having to draw all of the points on the screen. This will produce a smoothed plot and reduce the drawing time. The number to add is (Data points per displayed point + 1) * 10000.
Color
Any numeric expression giving the VTScada Color Palette of the line and the foreground color for filled plots. If the number is less than 10000, the plot is non-destructive.

If the number is greater than or equal to 10000, the plot is destructive and the actual color used is Color - 10000.
Pen
The pen to be used (if any).
Reserved
Reserved has been allocated to permit the addition of a Brush parameter, should such a parameter become necessary in the future. Reserved can currently be any value or Invalid.
XORMode
An optional parameter specifying whether the plot is destructive (if destructive, the plot line won't be affected by the background color).
If set to 0 or Invalid (default), the destructive drawing mode will be used. If set to 1, the non-destructive or XOR drawing mode will be used.
Direction
An optional parameter specifying the horizontal or vertical direction for the plot. 0 or Invalid indicates horizontal, while 1 indicates vertical.
DrawStepped
An optional parameter specifying whether the plot is to be drawn from point-to-point, or stepped. 0 or Invalid indicates point-to-point, while 1 indicates stepped.
BitNumber
An optional parameter specifying the use of a whole value or a bit number. Invalid indicates a whole value should be used, while >=0 indicates that the specified bit number should be used.
Average
An optional parameter specifying whether consecutive points should be averaged to give a single point.
Invalid or 0 indicates that averaging should not be used, while >0 indicates that the number of consecutive points should be averaged to give a single point.
Comments:

This function is a layered graphics statement.
The PlotXY statement will execute timer functions during the plotting process. This will allow time critical functions such as driver I/O and data logging to continue running during the relatively long times it takes to update a plot on the screen.

Through the ordering of the Left, Right, Top, Bottom, X1, X2, Y1, and Y2 parameters, the plot may have 8 different orientations. The normal left to right orientation with the minimum at the bottom will have Left < Bottom, Top < Bottom, X1 < X2, and Y1 > Y2.

Exchanging either Left and Right (i.e. Left > Right) or X1 and X2 (i.e. X1 > X2), the plot will be from right to left. This means that the minimum X-value will be on the right rather than the left. Exchanging either Top and Bottom (i.e. Top > Bottom) or Y1 and Y2 (i.e. Y1 > Y2),will result in the plot will having its minimum Y-value at the top rather than the bottom.
PlotXY ignores invalid data elements in the arrays and leaves blank spaces for them on the display. If the X-values are not in order, the plot will appear as a scatter of lines. The Sort statement may be used to order the points in the arrays prior to plotting.

The plot area defined by X1, Y1, X2, and Y2 limits the area which can be plotted on the screen. Any points which fall outside this area will not appear on the screen but will be "clipped" at the boundary.

On a standard VTScada page, any Y value less than 40 will be hidden by the title bar.

Example:

Two arrays called speed and efficiency exist that each have 100 elements. The array called speed has values that range from 0 to 1800, while efficiency has values ranging from 0 to 100 (percent). A plot of speed against efficiency may be done with the following:

PlotXY(speed[0] { Starting element of X-values },
       efficiency[0] { Starting element of Y-values },
       100 { Number of elements to plot },
       0, 1800 { Low/high limits for speed },
       0, 100 { Low/high limits for efficiency },
       50, 550, 550, 50 { Bounding box for clipped area },
       1 { Solid line style, horizontal plot },
       0 { Plot is black });

This statement will result in a line plot of 100 data points in an area in the upper left corner of the window. The line will be horizontally orientated, solid in style and white in color.


PMultiCheckBox

(Dialog Library)

Description: | Tool used to display the standard set of check boxes. Commonly used in the Owner tab of a configuration folder.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PMulticheck box(ParmNum [, LeftToRight, CheckBoxLabels, ID, DrawBevel, Label, BitOffset])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
LeftToRight
Required. If TRUE, order from left to right. If FALSE, order from top to bottom.
CheckBoxLabels
Required. An array of labels for the checkboxes.
ID

Starting with FocusID with one for each checkbox.

Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control. Default: False
Label
Required. A text expression to be used as a label for the checkboxes.
BitOffset
Offset at which to start the bit setting.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..

The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditfield) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.
This parameter tool expects the first parameter of its calling module to contain an array of tag parameters.

Example:

{ Variable declarations }
[

...

  CheckboxItemLabels          { Array of labels for options checkboxes        };
  PROTECTED HavePrivs         { TRUE if user has tag modify priv              };

...

]

...

{ InitState }
InitConfigFolder [
  If 1 SwitchTab;
  [

...

    CheckboxItemLabels      = New(4);

...

  ]
]

...

{ TabState }
OptionsState [

...

  { PMultiCheckboxes don't check configure priv }
  HavePrivs = \SecurityManager\SecurityCheck(\SecurityManager\PrivBitTagModify, 1);

...

  { Tag options settings }
  CheckboxItemLabels[0] = GetPhrase("Option 1");
  CheckboxItemLabels[1] = GetPhrase("Option 2");
  CheckboxItemLabels[2] = GetPhrase("Option 3");
  CheckboxItemLabels[3] = GetPhrase("Option 4");
  GUITransform(40, 308, WIDTH/2 - 10, 220,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary\PMultiCheckBox(\#Options, 0, CheckboxItemLabels,
                                             HavePrivs ? 1 { to 4 } : 0, 0, Invalid, 0));
]


Point

(Engine-Level Function)

Description: | Returns a two-dimensional point, or location, in a window.
Returns: | Point
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Path | Rotate | Trajectory | Vertex
Format: | Point(X, Y, Rotation, Trajectory)
Parameters: |
X
Required. A numeric constant, that describes the reference x-axis location of the point. Expressions are not permitted here. If it is desired to change the x coordinate, use the Trajectory or Rotation parameters.
Y
Required. A numeric constant, that describes the reference y-axis location of the point. Expressions are not permitted here. If it is desired to change the y coordinate, use the Trajectory or Rotation parameters.
Rotation
Required. Any expression that returns a Rotate value. This specifies any translation of this point from its reference position (X, Y) by rotation about another point. If this is invalid, no rotation is performed, but the Point is still valid.
Trajectory
Required. Any expression that returns a Trajectory value. This specifies any translation of this point from its reference position of (X, Y) along a path. If this is invalid, no translation is performed, but the Point is still valid.
Comments:

A point describes an (x, y) location. Points may be animated to rotate around another point by specifying a Rotate value, or they may be animated to travel along a path by specifying a Trajectory value, both of which are described below. Points are used in certain functions (such as GUIChord), in the Rotate value, and in the Vertex value.

Examples:

centerPt = Point(489, 122.5, INVALID, INVALID);
startAnglePt = Point(609, 27, INVALID, INVALID);
endAnglePt = Point(586, 243, INVALID, INVALID);

This defines 3 points that are neither translated nor rotated. They can be used in a Vertex or a Rotate function, like in the following example.

GUIPie(395, 187, 583, 58 { Bounding box for pie },
       1, 1, 1, 1, 1, 0, 0 { No scaling, trajectory or rotation },
       1, 0 { Pie is visible; reserved },
       0, 0, 0 { Cannot be focused/selected },
       12, 15 { Red fill outlined in white },
       Vertex(1 { Double smooth },
       centerPt, startAnglePt, endAnglePt));


PointerToBuff

(Engine-Level Function)

Description: | Returns a buffer containing the numeric data from the variables pointed at by each element of the array.
Returns: | Buffer
Usage: | Script or steady state.
Function Groups: | Array, String and Buffer
Related to: | BuffToArray | BuffToParm | BuffToPointer | GetByte | ParmToBuff | SetByte
Format: | PointerToBuff(ArrayStart, N, Option, Size, Skip)
Parameters: |
ArrayStart
Required. Any expression that specifies the starting array element. This array contains the pointers to the variables whose values will be written to a buffer. If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to convert starting at the element given by the first parameter.

If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Option
Required. Any numeric expression that specifies the format of the buffer write:
Option | Format
0 | Unsigned binary (low byte first)
1 | Signed binary (low byte first)
2 | BCD (binary coded decimal) (low byte first)
3 | ASCII octal (high byte first)
4 | ASCII decimal (high byte first)
5 | ASCII hex (high byte first)
6 | ASCII floating point (high byte first)
7 | IEEE float/double (low byte first)
8 | <obsolete>
9 | Allen-Bradley® PLC/3 floating point
10 | VAX single precision floating point

For Options 7 and 9 the data is written as appropriate binary format.

Size
Any numeric expression giving the number of digits in each datum. Size has a different meaning for each option as indicated below:
Option | Size Meaning | Size Range
Binary types | Number of bits | The following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64
BCD | Number of 4-bit digits | 1 - 16 digits
ASCII types | Number of bytes | 1 - 64 bytes
Float types | Precision | 1 for single precision, 2 for double precision
Skip
Any numeric expression giving the number of buffer bits/digits/bytes to skip after writing each non-floating point element. In binary modes, the following values are supported: 8, 16, 32, and 64. For floating point types, this parameter must be set to 0.
Comments:

This function may only be used with pointers pointing at numeric data. Any invalid array elements, or invalid data pointed at by array elements are written to the buffer as formatted zeroes. This function is useful for writing I/O drivers and saving arrays of data in RAM with a fraction of the memory requirement.

In binary modes, for the Size parameter, the following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64. For the Skip parameter, the following values are supported: 8, 16, 32, and 64.

Size and Skip values not in those ranges will only work if their combined value is a multiple of 8. For instance, a Size of 12 and a Skip of 4 will work. A Size of 48 and a Skip of 0 will work. When Skip + Size is not a multiple of 8, the behavior of this function is undefined.

If your values are of Size 1 (i.e. a single bit), use unsigned mode. A Size of 1 is not supported for signed values.

Option 0 - 5 will write out values as 64-bit integers when the Size parameter is large enough to support a 64-bit value. Otherwise, they will be written as 32-bit values.

Format Type | Minimum Size for 64-bit Value
Binary | Greater than 32 bits
BCD | Greater than 8 digits
Octal | Greater than 11 digits
Hex | Greater than 8 digits.

If the size is large enough to suppoer a 64-bit output but 64 bits are not needed for the value (the value is less than the largest 64-bit integer) padding will be used to make up the difference. Decimal value interpretation is not affected by the size parameter.

Example:

buff1 = PointerToBuff(dataPtr[0]{ Starting point in array },
                      100 { No. of elements to convert },
                      5 { Write as ASCII hex },
                      4 { Number of bytes per },
                      0 { No skip between writes });

This produces a formatted buffer 400 bytes long (100 four byte groups). Each 4 bytes is a hex number corresponding to a variable pointed at by an element in the array. Invalid array elements and invalid data are written as 0.


PointList

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Returns an array of tag names within the current scope, given the name of a tag type or group. NOTE: GetTagList should be used in place of PointList for all new code.
Returns: | Array
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | GetTagList | ListVars
Format: | \PointList(TagType[, SearchString, NoFilterSimulation])
Parameters: |
TagType
Required. Any text expression giving a type of tag or the name of a tag group.
SearchString
An optional text expression. The search will be limited to tags with matching names. May include wildcards. The default is "*" (any name).
NoFilterSimulation
Obsolete.
Comments: This utility function reduces the effort required to obtain a list of tags of a particular type or group membership. If no matching tags are found, the first element of the array will be Invalid.

Examples:

 { Get a list of the Stations }
 Stations =  \PointList("LiftstationDrivers", "*", 0);
 NStations = ArraySize(Stations, 0);


Popup

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Causes an alarm pop-up dialog to display.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Alarm, Graphics
Related to: |
Format: | \AlarmManager.Popup(ModuleName, Title, Width, Height, X, Y);
Parameters: |
ModuleName
Required. Any expression providing a text result. Name of module to draw in the window
Title
Required. Any expression providing a text result. Window title
Width
Required. Numeric expression. Number of pixels wide for the dialog
Height
Required. Numeric expression. Number of pixels high for the dialog
X
Required. Numeric expression. Location on the screen for the dialog, measured from the left.
Y
Required. Numeric expression. Location on the screen for the dialog measured from the top.
Comments: The Popup subroutine always returns "1".


POverride

(Dialog Library)

Description: | Tool used to override non-standard ConfigFolder controls for child tags.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.POverride(ParmNum [, ShowHotbox, ShowHighlight, HighlightColor, IntTrigger, ShowProperties, ValType, MinVal, MaxVal, ValArray, Enable, DoNotTranslate])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
ShowHotbox
An optional parameter that is any logical expression. If TRUE, the click-able area will be shown.
ShowHighlight
An optional parameter that is any logical expression. If TRUE the area will be emphasized with the HighlightColor.
HighlightColor
An optional output giving the highlight color to display if ShowHighlight is true.
IntTrigger
An optional trigger used by the caller's Edit field. See comments.
ShowProperties
An optional Boolean, controlling whether the Properties item should appear in the menu.
ValType
Optional. The VTScada value type of the parameter.
MinVal
Optional numeric. The minimum for the parameter value.
MaxVal
Optional numeric. The maximum for the parameter value.
ValArray
Optional array. If provided, defines a list of acceptable values for the parameter.
Enable
Optional Boolean. Set TRUE to enable the right-click menu. Defaults to TRUE
DoNotTranslate
Optional Boolean. Set TRUE when you do not want to translate a parameter that is a PhraseKey, retaining it as a key for later translation.
Comments:

This tool handles the shortcut menu and optionally highlights it's entire area when the override is specified. Feedback is also provided to allow custom controls to be highlighted in a more attractive fashion.

Do not reuse a trigger variable between POverride (intTrigger) and any other PTools if they are tied to different parameters. This will lead to unintended highlighting. POverride must have its own trigger so it will only respond to changes related to the control it is handling.

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters.

Usual height: 45 pixels.

Example:

GUITransform(30, 145, WIDTH/2 - 5, 100,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.POverride(\#Address,
                                      0,
                                      0,
                                      HighlightColor,
                                      PickValid(Trigger1, 1) &&
                                      PickValid(Trigger2, 1) &&
                                      PickValid(Trigger3, 1)));


Pow

(Engine-Level Function)

Description: | Returns a number raised to a power.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | Exp | Ln | Log
Format: | Pow(X, Exponent)
Parameters: |
X
Required. Any numeric expression giving the number to be raised to the power of Exponent.
Exponent
Required. Any numeric expression giving the number to which X should be raised.
Comments: This function may be used to perform the common antilogarithm by using 10 for X. The return value is invalid if X is less than or equal to 0 and Exponent is not a numeric.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Rather than using something like "And(X, Pow(2, 63))" to get the top bit in a 64-bit integer, use the SetBit function.

Examples:

r = Pow( 2, 4);
s = Pow(10, 2);
t = Pow(64, 0.5);

The values of r, s, and t will be 16, 100, and 8 respectively.


PPageSelect

(Dialog Library)

Description: | Shows the currently selected page and provides a tool to open the Page Select dialog.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PFileChooser | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PPageSelect(ParmNum [, Title, FocusID, VertAlign, AlignTitle, DrawBevel, ShowTitles, UnspecifiedLabel, FilterContext, ShowSubordinates])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
An optional parameter that is any text expression to be used as a title for the droplist.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the droplist according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
An optional parameter that is any logical expression. If true (non-0) the title is included in the calculation for vertical alignment, if false(0) it is added to the droplist after it and its bevel has been vertically aligned. The default is true.
DrawBevel
Optional Boolean. Set to TRUE if a bevel is to be drawn. Defaults to TRUE.
ShowTitles
Optional Boolean. Set to TRUE to show page titles. Defaults to FALSE.
UnspecifiedLabel

Optional text. A label to display when no page is selected.

FilterContext
Reserved.
ShowSubordinates

Optional BOOLEAN. TRUE to show pages from subordinate apps. Defaults to FALSE.

Note that tags in a master application should never be configured to use site pages from a subordinate application.

Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the name of the chosen page.
The height of the (unopened) droplist is constant, with the horizontal boundaries of its calling transform defining its width, and the vertical boundaries of its calling transform defining its opened height, which will include the added height of the bevel above the field, but may or may not include the title, depending on the alignment used. Note that if the entire list can be displayed in a smaller area than indicated by the vertical boundaries of the calling transform, the dropped list height will be decreased. The dropped height of the list will always have a minimum height of 1 line (below the field).
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Usual height: 45 pixels.

Examples:

  GUITransform(10, 145, 160, 45,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.PPageSelect(2                 { Parm num          },
                                        \GetPhrase("SelectPageLabel") { Title },
                                        TRUE              { Focus ID          },
                                        Invalid           { Default alignment },
                                        1                 { Align title       }));

Notice in the above example that the last two parameters could have been omitted because they are optional and their settings match those used as a default.


PPhraseDroplist

(Dialog Library)

Description: | Handles the complexity of parameter expressions by switching between display of a PhraseDroplist and regular Droplist control as is done in PPhraseEdit.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PRadioButtons | PSecBit | PSelectObject | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PPhraseDroplist(ParmNum,Title, PhraseIDArr, CanEdit, Index, FocusID[, Trigger, DrawBevel, VertAlign, SortPhrases])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
An optional parameter that is any text expression to be used as a title for the droplist.
PhraseIDArr
An array containing Phrase IDs (keys) for the list.
CanEdit
Boolean. If TRUE, users can edit within the field, adding new phrases.
Index
Numeric. The index variable to update within the array.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Optional. Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero: 1 if enter is pressed, 2 otherwise.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control. Defaults to TRUE. If the editfield is beveled, its size will become fixed and will be the same as that for a droplist.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the editfield according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
Optional Boolean. If AlignTitle is TRUE (non-0), the title will be included in the calculation for vertical alignment. If AlignTitle is FALSE (0), the title will be added to the editfield after both the editfield and its bevel have been vertically aligned. The default is true.
SortPhrases
Optional Boolean. If present and TRUE, the entries in the list will be sorted by the translated phrase.
Comments:

Droplist used to select a PhraseID by presenting the user with a droplist full of translated phrases. If CanEdit is TRUE then it is possible for the user to input new labels, in which case they will be added to the list and will be added to the language manifest.

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
The "P" tools (PCheckBox, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

Examples:

   { Equipment Type }
  GUITransform(0, 1, 1, 0,
               1 - 30,
               CtrlTop + 5*Space + 3*TEditHt + 3*TDropHt,
               Width - 30,
               1 - (CtrlTop + 5*Space + 3*TEditHt + 2*TDropHt), 1,
               0, 0, 1, 0,
               0, 0, 0,
               \DialogLibrary.PPhraseDroplist(\#EquipmentType, GetPhrase("EquipmentTypeLabel"),
                                              EquipmentTypesList, TRUE, EquipmentIdx, 1 {FID},
                                              Trigger, FALSE, 0, TRUE, TRUE));


PPhraseEdit

(Dialog Library)

Description: | Language-sensitive, parameter-setting editfield. This module draws an editfield with (optional) title and bevel. Recommended in place of the older PEditField.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PPhraseEdit(ParmNum, Title, FocusID[, Trigger, View, DrawBevel, VertAlign, AlignTitle, MinVal, MaxVal, PrivNotReq, Style, PrefixValue, SuffixValue, PlaceHolderText])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
An optional parameter that is any text expression to be used as a title for the field.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Optional. Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero: 1 if enter is pressed, 2 otherwise.
View
An optional parameter indicating how to display the editfield , as follows. The default value is 2 if FocusID is 0 and 1 otherwise.
View | Display mode
0 | Invisible
1 | Normal (color scheme - no graying)
2 | Grayed-out (only if FocusID is 0)

This parameter may be used to force an editfield with a FocusID of 0 to display normally, rather than allowing it to default to its grayed color.
Note that if the FocusID is not 0, setting this value as 2 will not force the field to gray out.

DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control. Defaults to TRUE. If the editfield is beveled, its size will become fixed and will be the same as that for a droplist.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the editfield according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated as determined by the value of AlignTitle. The default value is 0.

AlignTitle
An optional parameter that is any logical expression. If AlignTitle is TRUE (non-0), the title will be included in the calculation for vertical alignment. If AlignTitle is FALSE (0), the title will be added to the editfield after both the editfield and its bevel have been vertically aligned. The default is true.
MinVal
An optional parameter that is any expression giving the minimum value or minimum number of characters to be accepted by the editfield (depending on the data type). This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value less than MinVal is entered in the field (or there are too few characters, in the case of text value), the variable set by the field will revert to the previous value. No default
MaxVal
An optional parameter that is any numeric expression giving the maximum value or maximum number of characters to be accepted by the editfield (depending on the data type). This value may be a decimal, octal or hexadecimal value. If this parameter is valid and a value greater than MaxVal is entered in the field (or there are too many characters, in the case of text value), the variable set by the field will revert to the previous value.
PrivNotReq
An optional parameter that is any logical expression. If set to true (non-0), anyone can change the value in this editfield. If set to FALSE (0), only those users whose user accounts have been granted the "TagModify" privilege may set it. The default value is false.
Style
An optional parameter indicating the style of the PEditField object. It is a bit-wise field made up of the sum of the following values, to yield the desired effects.
Bit | Value | Definition
0 | 1 | Reserved for bit compatibility with WinComboCtrl, and should be set to "0"
1 | 2 | Reserved for bit compatibility with WinComboCtrl, and should be set to "0"
2 | 4 | Input is converted to all uppercase (note 1)
3 | 8 | Input is converted to all lowercase (note 1)
4 | 16 | Input is masked. Any characters typed will appear as asterisks. This is useful for such things as password fields
5 | 32 | Multiline editing. Setting this bit causes a typed <CR> (Enter or Return) to be interpreted as "move to the start of the next line". Text that contains <CR> characters has a line break inserted at each
6 | 64 | Reserved
7 | 128 |
8 | 256 | Reserved
9 | 512 | Not used. Height is defined by \EditHt or TEditHt (with title).

If neither values 4 or 8 are set, input is passed to script code as typed.

PrefixValue
An optional parameter indicating the text expression that should be displayed immediately before (i.e. to the left of) the editable part of the control.
SuffixValue
An optional parameter indicating the text expression that should be displayed immediately after (i.e. to the right of) the editable part of the control. No Default
PlaceholderText
Optional text to be displayed in the field when there is otherwise no valid value.
Typically provides context or instructions to the user. This is not a default value for the parameter.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
The "P" tools (PCheckBox, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

When more than one language is enabled in the application, a phrase-editing button is provided at the right edge of the field. Optionally, the phrase editor will open automatically when VTScada detects that new or untranslated text is entered into the field.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the value in the editfield.
The height of the editfield is constant, with the horizontal boundaries of its calling transform defining its width, and the vertical boundaries of its calling transform defining the boundaries in which it is to be confined vertically, which will include the added height bevel, but may or may not include the title, depending on the alignment used.

Usual height: 45 pixels.

Examples:

GUITransform(10, 215, 225, 45,
             1, 1, 1, 1, 1,
             0, 0, 1, 0, 0, 0, 0,
             \DialogLibrary.PPhraseEdit(1,
                                        \GetPhrase("AddDotDotDotLabel"),
                                        TRUE                     { ID },
                                        0                   { trigger },
                                        2,
                                        0));

Notice in the above example that the last parameter could have been omitted, because it is optional and its setting matches the default.


PPPDial

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Creates a PPP connection to a remote peer. The connection can be via a dial-up or direct device connection.
Returns: | PPPhandle if succesful, otherwise an error value.
Usage: | Script Only.
Function Groups: | Modem, Serial Port
Related to: | PPPHandles | PPPStatus
Format: | PPPDial(DeviceName[, PhoneNumber, UserName, Password, Domain, Flags, DeviceType, DeviceSubType])
Parameters: |
DeviceName
Required. Any text expression giving the name of the modem as configured in Windows™. The function will return Invalid if this parameter is not a valid text value.
PhoneNumber
An optional text expression giving the phone number to be used when making a PPP call. Required only for use with modems. Defaults to Invalid.
UserName
An optional text expression, providing the user name for remote authentication.
Password
An optional text expression, providing the password for remote authentication.
Domain
An optional text expression, providing the domain name for remote authentication.
Flags
An optional numeric expression, specifying compression, encryption and other options to be provided. A bit-wise AND operation is done between this value and the following constants.
Value | Constant | Meaning
0x0001 | PPPDF_IpHeaderCompression | Use IP header compression
0x0002 | PPPDF_SwCompression | Use software compression
0x0004 | PPPDF_DisableLcpExtensions | Disable LCP extensions.
0x0008 | PPPDF_RequireEncryptedPw | Require encrypted password.
0x0010 | PPPDF_RequireDataEncryption | Require data encryption
DeviceType
An optional numeric expression identifying the class of RAS device referred to by DeviceName. Possible values are
1 (Phone),
2 (VPN),
3 (Direct - serial/parallel/USB),
4 (Internet) and
5 (Broadband).
To create a PPPoE connection, use 5.
DeviceSubType
An optional text expression specifying the type of device referred to by DeviceName. Possible values are "modem", "isdn", "x25", "vpn", "pad", "GENERIC", "SERIAL", "FRAMERELAY", "ATM", "SONET", "SW56", "IRDA", "PARALLEL" and "PPPoE".
Comments: PPPDial works by creating a phonebook entry in a temporary phone book in the installation folder. The entry is GUID named and has a lifespan the same as the PPPHandle this method creates. A RAS call is then initiated and a PPPHandle created to represent the call.
This function looks for the subroutine, PPPStatus in the scope of the caller. After initiation of the call, this subroutine is called to notify the caller of the progress and status of the call.
The call is terminated and the phonebook entry removed after the PPPHandle destructs. Invalidating the last reference will do this. Destruction is asynchronous. VTScada shutdown waits for all PPP handles to gracefully close.


PPPHandles

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: Returns an array of all Point-to-Point Protocol handles on the local machine. This includes all such handles, whether inbound or outbound and whether made by VTScada.
Returns: An array of PPP handles
Usage: Steady State only.
Function Groups: Modem, Serial Port
Related to: PPPDial | PPPStatus
Format: PPPHandles()
Parameters: None
Comments: A PPP handle is a structure, defined as follows.

To access these values, use the PPPStatus command as follows:

PPPStruct = PPPStatus(Handles[I]);
rr1 = PPPStruct\ConnectionID;
Variable | Contents
ConnectionID | Only valid for outbound connections. The GUID used in the temporary phone book used to dial the call. PPPDial creates a temporary RAS phone book in the Data\Temp folder of the VTScada installation folder. It is removed on graceful exit of VTScada. Each outbound call is given a unique call ID (a GUID) that is entered into the phone book.
State | A numeric value identifying the state of the connection. There are many intermediate states, but the significant ones are 2 (dialling), 8192 (connected) and 8193 (disconnected).
Error | Zero indicates no errors. When non-zero, this holds a standard RAS error code, normally in the range 600-800.
RemoteIP | The IP of the remote end of a connected or disconnected connection.
LocalIP | The IP of the local end of a connected or disconnected connection. The IP is not invalidated after being set, so that script code can handle transient connections.
DeviceName | The same as the DeviceName parameter of PPPDial. This is the Windows-assigned friendly name for the device that the connection is made through.


PPPStatus

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Obtains the structure of a PPP connection.
Returns: | A structure describing the state. See comments
Usage: | Script or steady state.
Function Groups: | Modem, Serial Port
Related to: | PPPDial | PPPStatus
Format: | PPPStatus(PPPHandle)
Parameters: |
PPPHandle
The PPP Handle to be monitored.
Comments: If called in script mode, the current state will be returned. If called in steady state, the function will be retriggered each time there is a state change in the parameter, PPPHandle.

The return value is a structure containing the following members:

    ConnectionID: Actually the phonebook entry name, which is a GUID.

    State: See enumeration RASCONNSTATE (defined in the Visual Studio file, ras.h)

    Error: Last error code from RAS (defined in the Visual Studio file, raserror.h)

    RemoteIP: The IP address of the remote peer. Only valid when State is RASCS_Projected or greater.

    LocalIP: The IP address on this machine that the remote peer is connected to. Only valid when State is RASCS_Projected or greater.

If the PPPHandle parameter is bad, this function will return an Invalid.

Related Functions:


PRadioButtons

(Dialog Library)

Description: | Parameter Setting Radio Buttons. This module draws a set of labeled radio buttons with optional title and border.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PRadioButtons(ParmNum, FocusID, Border, Title, Options, AlignTitle, L0 [, L1, ..., L15])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Border

Numeric that may have the following values:

0 = No outline (default)

1 = Raised box outline

2 = Bevel outline

Title
Any text expression to be used as a title with the radio buttons. The default value is to have no title.
Options
A bit-wise expression.
Bit 0 controls left/right placement of the buttons. If set, buttons will be placed to the left of the labels.
Bit 1 controls vertical/horizontal orientation. If set, the radio buttons will be displayed horizontally. Bit 0 has no effect while bit 1 is set.
Bit 2, if set, causes the radio buttons to adopt a "standard" vertical spacing of 5 pixels.
Defaults to 0 - neither bit set.
AlignTitle
Any logical expression; if TRUE (non-0) the title is drawn within the radio buttons' boundaries, if FALSE (0) the buttons fill their bounding area and the title is added at the top (i.e. it extends past the top boundary). The default is true.
L0

Labels. The number of labels determines the number of buttons displayed. At least two must be provided.

If L0 is an individual label, then up to L15 individual labels may follow.

If L0 is an array of labels, L1 may (optionally) be defined as an array of Return values, similar to the return array in PDropList.

L1
A flexible parameter. If L0 is an array, this may contain a matching array of return values. Otherwise, this may contain the second label.
L2
A flexible parameter. This may contain a logical expression indicating (when TRUE) that expressions should not be translated. Or, this may be the third label.
L3...L15
The remaining labels, if any.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the selected item.
The boundaries of the calling transform define the outline of the buttons including their border, if there is one. If the area is too small to fully display the buttons they will extend beyond their right and bottom boundaries. Buttons and their border will not overlap each other and will always be shown in their entirety, although the labels may be clipped or entirely deleted.

Usual height: varies according to number of buttons. Seldom less than 50px.

Example:

GUITransform(50, 400, 450, 100,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.PRadioButtons(7               { Parm num          },
                                          TRUE            { Focus ID          },
                                          TRUE            { Draw a border     },
                                          ""              { No title required },
                                          0               { Buttons on right  },
                                          Invalid         { Not req'd  title) },
                                          \GetPhrase("OnLabel"),
                                          \GetPhrase("OffLabel"),
                                          \GetPhrase("ServiceLabel") { Labels }));


PrepStringForTemplate

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Prepares text for use in an alarm template by escaping % symbols.
Returns: | Text
Usage: | Script or Steady State
Related to: |
Function Groups: | String and Buffer
Format: | \PrepStringForTemplate(Value)
Parameters: |
Value
Required. The text to be cleaned.
Comments: Text is cleaned for use in an alarm template by doubling any instance of a % symbol.


Print

(Engine-Level Function)

Description: | Allows text to be printed.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Printer
Related to: | FWrite | PrintLine | PrtScrn | Redirect | SWrite
Format: | Print(PrinterSpec, Text)
Parameters: |
PrinterSpec
...will accept any of the following:
  • Local Printer:
  • Port name (including virtual ports) with or without a trailing colon (e.g. DEF or DEF:. COM1 or COM1:; USB001 or USB001:; etc.)
  • Windows printer share (e.g. "XYZ Laser Printer")
  • Windows share name (if the printer is shared) (e.g. "XYZLaser")
  • Local or Remote Printer:
  • UNC share name (which includes the host and share name (e.g. "\\localhost\XYlaser" or "\\lab1\NetPrinter")
Text
Required. Any text expression that gives the text to print. Control characters may be included in the text.
Comments: This statement is very similar to the PrintLine statement except it does not add the carriage return or line feed after the text.
All print functions are compatible with the values returned in either of the first two parameters of the PrintDialogBox function.

Example:

If 1 NextScreen;
[
  Print(1, "Daily Report: ");
]

This prints the string "Daily Report: " to LPT1:.


PrintDialogBox

(Engine-Level Function)

Description: | Displays a threaded system common printer selection dialog box.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics, Printer
Related to: | FontDialog | FileDialogBox | FileStream
Format: | PrintDialogBox(PrinterName, PrinterDevice, MinPage, MaxPage, FirstPage, LastPage, NumCopies, Result [, AllowSelection])
Parameters: |
PrinterName
Required. Any text expression giving the initial printer name to display as selected. If this is not a valid text value, the default printer (as configured under Windows) will initially be selected.

If PrinterName refers to a variable and the user clicks the "Print" button on the dialog, thereby closing it, the variable will be set to the name of the selected printer. If the user cancels the dialog box, the variable is unchanged.
PrinterDevice
Required. Any variable that will be set to the device name for the selected printer when the user clicks the "Print" button on the dialog.

If the user cancels the dialog box, the variable is unchanged. The text expression returned here can be supplied to a FileStream statement to open a stream to the selected printer.
MinPage
Required. Any positive integer expression specifying the minimum page number in the printed output (see Comments section for further details).
MaxPage
Required. Any positive integer expression specifying the maximum page number in the printed output (see Comments section for further details).
FirstPage
Required. Any integer expression specifying the first page to be printed (see Comments section for further details).
LastPage
Required. Any integer expression specifying the last page to be printed (see Comments section for further details).
NumCopies
Required. Any integer expression specifying the number of copies to be printed (see Comments section for further details).
Result
Required. A variable that will be set to one of the following values:
  • Invalid when this statement is run,
  • Zero (0) to indicate that the user has canceled the dialog, or
  • One (1) to indicate that the user has clicked the "Print" button.
AllowSelection
An optional parameter. If provided, it must be a non-constant variable. This enables and controls the "Selection" radio button in the print dialog box. See the Comments section for further details.
Comments: This function creates a printer selection dialog that runs in its own thread, thereby avoiding blocking the calling code. The calling code can use the Result parameter to determine when the user has completed the dialog box (see Result above).

In addition to the Result parameter, the function itself will return an error code to indicate whether the dialog was successfully opened. A "1" indicates failure to open while a "0" indicates success.

The caller of this function is expected to supply the MinPage and MaxPage parameters, representing the minimum and maximum page number from which the user may select. FirstPage and LastPage can be initially set to any values between MinPage and MaxPage. If the combination of the four values is not logical (e.g. LastPage is smaller than FirstPage), VTScada will force logical values for the dialog. When Result is set to one, FirstPage and LastPage will contain the page range that the user selected. If Result is set to zero (i.e. the user has canceled the dialog), FirstPage and LastPage are left at their initial values. Setting MinPage and MaxPage to Invalid or to equal values will disable the page range field. NumCopies can likewise contain an initial value, and will be set to the user-selected number of copies if Result returns a value of one.

The initial value of the Selection radio button is controlled by the value of the variable provided for the AllowSelection parameter:

  • If the variable's value evaluates to a non-zero positive number, the Selection radio button will be selected.
  • If the variable's value is zero, the radio-button will initially be unselected.

When the Print button on the print dialog box is clicked, this variable receives a zero if the Selection radio-button was not selected and one if it was selected.

Within an Anywhere Client session, this function does nothing.

Example:

If ZButton(10, 90, 110, 120, "Browse Print", 1, System.DefFont);
[
  PrintDialogBox(PrinterName, PrinterDevice, MinPage, MaxPage,
                 FirstPage, LastPage, NumCopies, Result);
]
ZText(120, 112,
      Concat("Printer chosen: ", PickValid(PrinterName, "Invalid"),
             " (", PickValid(PrinterDevice, "Invalid"), ") Page ",
             PickValid(FirstPage, "Invalid"), " to ",
             PickValid(LastPage, "Invalid"), " Copies: ",
             PickValid(NumCopies, "Invalid")),
      0, System.DefFont);


PrintLine

(Engine-Level Function)

Description: | Allows text to be printed and is followed by a carriage return-line feed to the printer.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Printer
Related to: | FWrite | Print | PrtScrn | Redirect | SWrite
Format: | PrintLine(PrinterSpec, Text)
Parameters: |
PrinterSpec
...will accept any of the following:
  • Local Printer:
  • Port name (including virtual ports) with or without a trailing colon (e.g. DEF or DEF:. COM1 or COM1:; USB001 or USB001:; etc.)
  • Windows printer share (e.g. "XYZ Laser Printer")
  • Windows share name (if the printer is shared) (e.g. "XYZLaser")
  • Local or Remote Printer:
  • UNC share name (which includes the host and share name (e.g. "\\localhost\XYlaser" or "\\lab1\NetPrinter")
Text: Required. Any text expression that gives the text to print. Control characters may be included in the text.
Comments: This statement adds a carriage return and line feed to the end of the text so that the printer goes to the start of a new line after the text is printed.
All print functions are compatible with the values returned in either of the first two parameters of the PrintDialogBox function.

Example:

If 1 NextScreen;
[
  PrintLine(1, "Daily Report: ");
]

This prints the string "Daily Report: " to LPT1:, followed by a carriage return and a line feed.


ProcessingLoad

(Engine-Level Function)

Description: | Returns the current VTScada processing load of the calling bubble
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Bubbles and Threads
Related to: |
Format: | ProcessingLoad()
Parameters: |
Comments:

The value returned shows the processing load of the calling bubble in percentage. The value reported is accurate up to that instance and it is updated internally approximately every second. If the value stays higher for a long period of time, that suggests that the system is getting slower and performance crisis could appear at any time. An intervention should occur as soon as possible to avoid performance degradation.

Example:

If !Valid(currentLoad);
[
    currentLoad = ProcessingLoad();
]


ProcInfo

(Engine-Level Function)

Description: | Returns basic information about the VTScada process.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Software and Hardware
Related to: |
Format: | ProcInfo(DataType)
Parameters: |
DataType
Required. A numeric value that specifies the type of process information to be retrieved by the function.
DataType | Function returns
0 | Process ID
1 | GDI Handle Count
2 | User Handle Count
Comments: Used by the workstation status tag.

Example:

GDIHndl = ProcInfo(1);


ProgressBar

(System Library)

Description: | Displays a horizontal progress bar.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: |
Format: | System.ProgressBar(LeftReference, BottomReference, RightReference, TopReference, Value[, Low, High, LeftLabel, RightLabel, Align, Delay, ContinuousLoop)
Parameters: |
LeftReference
A constant number that gives the left side reference coordinate.
BottomReference
A constant number that gives the bottom side reference coordinate. The top and bottom references are measured down from the top of the screen.
RightReference
A constant number that gives the right side reference coordinate.
TopReference
A constant number that gives the top side reference coordinate.
Value
Required. The value to display as the progress.
Low
Optional numeric, specifying the minimum value for the progress bar. Defaults to zero.
High
Optional numeric, specifying the maximum value for the progress bar. Defaults to 100.
LeftLabel
Optional text providing the left-justified label.
RightLabel
Optional text providing the right-justified label.
Align
Optional numeric. If 0 (the default if unspecified) the graphic will be top-justified. If 1, the graphic will be center-justified.
Delay
Optional numeric. The number of seconds to wait before the graphic is displayed. Defaults to zero.
ContinuousLoop
Optional Boolean. When set true, the progress bar will loop continuously rather than representing the value.
Comments: None


ProtobufDecode

(Engine-Level Function)

Description: | Decodes Protobuf serialized data.
Returns: | VTScada data structures representing the message.
Usage: | Script Only.
Function Groups: | Protobuf
Related to: | ProtobufInstantiate | ProtobufEncode | ProtobufParse
Format: | ProtobufDecode(ProtobufHandle, MessageTypeName, EncodedString[, NoOptionalDefaulting])
Parameters: |
ProtobufHandle
Protobuf handle generated by ProtobufParse
MessageTypeName
Message type from ProtobufHandle's proto file
EncodedString
Protocol buffer to decode
NoOptionalDefaulting
Optional Boolean. Defaults to FALSE when unspecified or invalid. When TRUE, fields in a Protobuf message defined as optional and not present in the message are not given a default value when decoded.
Comments:

When decoding messages with optional fields (note that in Protobuf version 3 all fields are optional) the default value will be used if it is absent from the encoded message. An exception to this is fields defined within a oneof where no default values will be used.

Decoding and encoding of proto2 groups is not supported.

Related Information:

Protobuf Support

Example:

See: ProtobufInstantiate


ProtobufEncode

(Engine-Level Function)

Description: | Creates a buffer for a given Protobuf file containing VTScada value data.
Returns: | An encoded protocol buffer.
Usage: | Script Only.
Function Groups: | Protobuf
Related to: | ProtobufDecode | ProtobufInstantiate | ProtobufParse
Format: | ProtobufEncode(ProtobufHandle, MessageTypeName, DataToEncode)
Parameters: |
ProtobufHandle
Protobuf handle generated by ProtobufParse
MessageTypeName

Message type from ProtobufHandle's proto file.

This is the full name, meaning that if the .proto file includes a package name "com.trihedral.protobufexample" and the message name is "AMessage", this would be "com.trihedral.protobufexample.AMessage". For nested messages this also includes all ancestor messages

DataToEncode
VTScada data structure representing the message to be encoded.
Comments:

Protobuf version 2 allows fields to be defined as required. If all fields marked as required are not present when encoding a message ProtobufEncode will return invalid.

Decoding and encoding of proto2 groups is not supported.

ProtobufEncode conducts a recursive search on DataToEncode. Ensure there are no circular references within DataToEncode's nested data structures. This can lead to infinite recursion, and instability.

Related Information:

Protobuf Support

Example:

See: ProtobufInstantiate


ProtobufInstantiate

(Engine-Level Function)

Description: | Instantiates a message using default values. This is useful where a non-trivial message type is used as it allows the script code developer to create an instance of a message suitable for encoding without re-defining the message structure.
Returns: |
Usage: | Script Only.
Function Groups: | Protobuf
Related to: | ProtobufDecode | ProtobufEncode | ProtobufParse
Format: | ProtobufInstantiate(ProtobufHandle, MessageTypeName[, optionalsAsInvalid])
Parameters: |
ProtobufHandle
A Protobuf handle returned from ProtobufParse.
MessageTypeName
The message type to use for decoding. This is the full name, that is, if the .proto file includes a package name "com.trihedral.protobufexample" and the message name is "AMessage", this would be "com.trihedral.protobufexample.AMessage". For nested messages this also includes all ancestor messages
OptionalsAsInvalid
Optional Boolean. Defaults to FALSE when unspecified or invalid.
When TRUE, fields in a Protobuf specification file that are defined as optional are not given a default value when instantiated.
Comments:

Generates a VTScada data structure based on the loaded proto file, so that the structure can be populated with data from script code before being used in a call to ProtobufEncode.

Related Information:

Protobuf Support

Example:

Given a Protobuf specification file held in "example.proto" in a sub-folder protobuf of an application:

syntax = "proto2";

package com.trihedral.protobuf.example;

message VersionInformation {
  required string name    = 1;
  required double version = 2;
}

The following code parses, instantiates, encodes and then decodes a message:

<
{============================= ProtobufExample ===============================}
{ Demonstration of parsing, encoding, decoding and instantiating Protobuf    }
{ messages.                                                                   }
{=============================================================================}
ProtobufExample
[
  Protected ProtobufHandle;
  Protected MessageInstance;
  Protected EncodedMessage;
  Protected DecodedMessage;
]

ProtobufExample [
  If TRUE;
  [
    ProtobufHandle = ProtobufParse(Concat(Layer.GetWCPath(), "protobuf\example.proto"));
    MessageInstance = ProtobufInstantiate(ProtobufHandle, "com.trihedral.protobuf.example.VersionInformation");

    MessageInstance.name = "VTScada";
    MessageInstance.version = 12;

    EncodedMessage = ProtobufEncode(ProtobufHandle, "com.trihedral.protobuf.example.VersionInformation", MessageInstance);

    DecodedMessage = ProtobufDecode(ProtobufHandle, "com.trihedral.protobuf.example.VersionInformation", EncodedMessage);

    Return();
  ]
]

{ End of ProtobufExample }
>


ProtobufParse

(Engine-Level Function)

Description: | Load a Protobuf specification from a file.
Returns: | A Protobuf Handle value. See comments.
Usage: | Script Only.
Function Groups: | Protobuf
Related to: | ProtobufDecode | ProtobufEncode | ProtobufInstantiate
Format: | ProtobufParse(ProtobufFileName[, ErrMsg])
Parameters: |
ProtobufFileName
Required text. Absolute path to the file that defines a Protobuf spec.
ErrMsg
Optional. If provided, this will be set to an array of error messages on failure.
Comments:

The return value is of type #VTypeProtobufHandle if successful, or invalid if there were errors. The handle can be used with ProtobufEncode, ProtobufDecode, and ProtobufInstantiate.

The ErrMsg parameter is set to invalid if there were no errors, or an array of one or more errors if there were issues parsing the file specified in the ProtobufFileName parameter. Each error consists of a structure with members file name, line, column, and message.

Related Information:

Protobuf Support

Example:

See: ProtobufInstantiate


PrtScrn

(Engine-Level Function)

Description: | Prints the image in a window on the default Windows™ printer and returns an error code.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Printer
Related to: | Print | PrintLine | Redirect
Format: | PrtScrn([Window, PaletteChanges, PrinterSpec])
Parameters: |
Window
An optional object value of a module instance that specifies the window to print. If it is not specified, it defaults to Self which will print the window from which the PrtScrn function is executed.
PaletteChanges
An optional two-dimensional array of RGB values. Each RGB value overrides the default printed color for the palette index, which is the same as the first array subscript.
The first array subscript may have any size (e.g. [0..255] for the whole palette, or [123..125] for just palette indices 123 to 125). (Please see the example in the "Example" section.)
The second array subscript should be sized [0..2] and holds the red, green, and blue components of the color respectively. Each color value must be a real number between zero and one. "0" represents a total absence of that color, while "1" represents the full intensity of the color.

Colors that are in other indexed positions of the palette, but which have the same RGB value as the indexed color to be changed, will usually also change. The danger is that the process of mapping colors from VTS’s palette to that of the printer may cause results to differ from those expected. If using the PaletteChanges parameter, you are advised to test this function to determine the actual results.

PrinterSpec
An optional parameter that will accept any of the following:
  • Local Printer:
  • Port name (including virtual ports) with or without a trailing colon (e.g. DEF or DEF:. COM1 or COM1:; USB001 or USB001:; etc.)
  • Windows printer share (e.g. "XYZ Laser Printer")
  • Windows share name (if the printer is shared) (e.g. "XYZLaser")
  • Local or Remote Printer:
  • UNC share name (which includes the host and share name (e.g. "\\localhost\XYlaser" or "\\lab1\NetPrinter")

A note to OEM programmers:

When the VTScada Display Manager or Trend Manager performs a screen print, printer palette color substitution is performed by calling module "GetPrinterPalette". This module is searched for in Code. The VTS layer does not provide this module. The default printing palette is the display palette. If you wish to provide a separate palette, provide a GetPrinterPalette module. This should be a subroutine module that returns an array of palette color substitution values in the same format required by the PrtScrn statement's PaletteChanges parameter.

Comments: The return value for this function is as follows
Return Value | Description
0 | Success
1 | Printing
2 | Failure

When printing using this function, make sure that the print job is spooled to the Windows™ Print Manager, otherwise execution of the application will be suspended for the duration of the print job.

Care should be taken to ensure that the graphics in the window you are printing do not change while printer output is being generated. If the graphics do change, the printer output is unpredictable.

In VTS 7.0 and later, all print functions are now compatible with the values returned in either of the first two parameters of the new PrintDialogBox function.

Within an Anywhere Client session, this function does nothing.

Example:

If MatchKeys(2, "p") && ! wait;
[
  wait = PrtScrn();
]

This will cause the window containing the PrtScrn statement to be printed out when the "P" key is pressed so long as another print job is not already printing or has failed.

Another example might be:

 PalValues = New(256, 3); { Sized enough for entire palette }
 PalValues[0][0] = 1;  { Red - Full intensity }
 PalValues[0][1] = 1;  { Green - Full intensity }
 PalValues[0][2] = 1;  { Blue - Full intensity }
 .
 .
 .
 PrtScrn(Self(), PalValues);

This will set the color for palette index 0 (default black) to be white.


PSecBit

(Dialog Library)

Description: | Parameter Setting Security Bit. This module draws a titled, [beveled] droplist of options for setting the security bit.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Bitwise Operation, Graphics, Security
Related to: | GUITransform | PAddressEntry | PAreaSelect | PCheckBox | PColorSelect | PContributor | PDroplist | PEditField | PFileChooser | PPageSelect | PRadioButtons | SelectGraphic | PServerListName | PSpinbox |PTimeZone | PTypeToggle
Format: | \DialogLibrary.PSecBit(ParmNum, Title, FocusID[, VertAlign, AlignTitle, DrawBevel])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
Required. Any text expression to be used as a title for the droplist.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the droplist according to one of the following options:
Value | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
An optional parameter that is any logical expression. If AlignTitle is true (non-0), the title will be included in the calculation for vertical alignment.

If AlignTitle is false (0), the title will be added to the editfield after both the editfield and its bevel have been vertically aligned. The default is true.
DrawBevel
An optional parameter that is any logical expression. if true, a bevelled edge will be added around the control.
Comments

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the chosen security bit.
The height of the (unopened) droplist is constant, with the horizontal boundaries of its calling transform defining its width, and the vertical boundaries of its calling transform defining its opened height, which will include the added height of the bevel above the field, but may or may not include the title, depending on the alignment used. Note that if the entire list can be displayed in a smaller area than indicated by the vertical boundaries of the calling transform, the dropped list height will be decreased. The dropped height of the list will always have a minimum height of 1 line (below the field).
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Usual height: 45 pixels.

Example:

GUITransform(50, 400, 450, 100,
1, 1, 1, 1, 1,
0, 0, 1, 0,
0, 0, 0,
\DialogLibrary.PSecBit(9 { Parm num },
\GetPhrase("Your_Title") { Title },
3 { Focus ID },
1 { Centered },
0 { Align bevel }));


PSelectCertificate

(Dialog Library)

Description: | Parameter setting Select Certificate tool. This module draws a droplist with a certificate summary section and a 'Manage Certificates' button (see Certificate Management UI). Select Certificate function UI example
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform |PAddressEntry |PAlmPriority |PAreaSelect |PCheckBox |PColorEdit |PColorSelect | PContributor | PEditField | PEditName | PFileChooser |PHueSelect| PImageSelect | PIPAddressList | PIPListenerGroup |PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox |PTimeZone | PTypeToggle|SiteDispParms
Format: | \DialogLibrary.PSelectCertificate(ParmNum, ID, CertificateEKU, CertificateStore, CertificateType, CallbackScope, CertificateData, ReturnThumbprint, AdditionalSAN, DefaultCertName)
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
ID
Required. Focus ID of the PTool.
CertificateEKU
Required. Extended Key Usage OID ('Object ID') of the certificates.
CertificateStore
Required. Name of the Certificate Store to use.
CertificateType
An optional parameter flag. 1 = 'Self Signed certificate', 2 = 'CA Signed certificate,' Defaults to 1 (Self signed certificates).
CallbackScope

An optional callback scope which must strictly use the module names listed below. All callback modules are invoked with the parameters provided in the following list. All the callbacks below shall be subroutines.

  • CreateCertificate – Called to create or renew a certificate.

  • CreateCertificate(

    • SubjectRDN { Subject (RDN) },

    • FriendlyName { Friendly name },

    • ValidityPeriod { Validity period (days) },

    • KeyStrength { Key strength },

    • CertificateEKU { Enhanced key usage },

    • SANArray { Subject Alternative Names } )

  • DeleteCertificate(CertThumbprint) – Called to delete a certificate.

  • ImportCertificate(ImportCertificateFileName, Password) – The API could be updated to accept a certificate blob, but this is not currently necessary since the caller of 'SelectCertificate' will be on the same machine.

  • IsCertValid(CertificateObject) – Optional. Can be implemented if the caller wants to provide its own certificate validation logic. This module shall return a Boolean based on a certificate object provided.

CertificateData
Optional. Provides an array of certificates. This can be used if the user doesn’t want to retrieve certificates from the certificate store but instead wants to supply their own.
ReturnThumprint
An optional parameter flag. Boolean. If TRUE, the parameter would be set to hex thumbprint. If FALSE, the parameter would be set to Certificate name. Defaults to FALSE.
AdditionalSAN
An optional parameter that is an array of additional SAN entries.
DefaultCertName
An optional parameter that specifies the default name used when creating a new certificate.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by '\DialogLibrary\'.

The 'P tools (PCheckBox, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the text string displayed in the selected line of the droplist.

Example 1:

GUITransform(70, 210, 210, 170,
          1, 1, 1, 1, 1,
          0, 0, 1, 0,
          0, 0, 0,
          \DialogLibrary.PSelectCertificate(\#UserCertificateName { Parm num         },
                                    EnableCtrls           { ID               },
                                    EKU                   { Certificate EKU  },
                                    \#CerStore            { CertificateStore },
                                    1                     { CertificateType  }));

Example 2:

GUITransform(70, 210, 210, 170,
          1, 1, 1, 1, 1,
          0, 0, 1, 0,
             0, 0, 0,
          \DialogLibrary.PSelectCertificate(\#UserCertificateName { Parm num         },
                                    EnableCtrls           { ID               },
                                    EKU                   { Certificate EKU  },
                                    \#CerStore            { CertificateStore },
                                    1                     { CertificateType  },
                                    CallbackScope         { CallbackScope    },
                                    CertificateData       { CertificateData  },
                                    FALSE                 { ReturnThumbprint },
                                        AdditionalSAN         { AdditionalSAN    }));


PSelectObject

(Dialog Library)

Description: | Parameter Setting Select Tag Object Tool. This module draws a beveled, titled box showing the currently selected tag, a button to modify the connection in the hierarchy, and a new tag creation button.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PServerListName | PSecBit | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PSelectObject(ParmNum, TagType [, Title, FocusID, VertAlign, AlignTitle, DisableDeselect, DrawBevel, AllowRootSelection, BrowserObj, DefaultText, MissingText])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
TagType
Required. May be a text expression for the type or type-group of tag to be used to create the droplist. (Type-groups include "ports", "drivers", "analogs", etc.)
Alternatively, this may be an array of types. The array may not include groups.
All existing tags of the type or types will be listed.
Title
An optional parameter that is any text expression to be used as a title for the droplist. If not provided, the title will be blank.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the unopened droplist according to one of the following:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
An optional parameter that is any logical expression. If AlignTitle is true (non-0), the title will be included in the calculation for vertical alignment.
If AlignTitle is false (0), the title will be added to the editfield after both the editfield and its bevel have been vertically aligned. The default is true.
DisableDeselect
Optional Boolean. Set TRUE to disable the Deselect button
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control. Defaults to TRUE.
AllowRootSelection
Optional Boolean. Set TRUE to allow the Root tag to be selected. Default is FALSE
BrowserObj
Optional object. The object value of the tag browser which has been opened by the tool
DefaultText
Optional text. What to display in place of "No tag selected".
MissingText
Optional text. What to display in place of "--Missing--".
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the chosen item.
The height of the (unopened) droplist and the create new tag button are constant, with the horizontal boundaries of the calling transform defining their combined width, and the vertical boundaries of the calling transform defining the droplist's opened height, which will include the added height of the bevel above the field, but may or may not include the title, depending on the alignment used. Note that if the entire list can be displayed in a smaller area than indicated by the vertical boundaries of the calling transform, the dropped list height will be decreased. The dropped height of the list will always have a minimum height of 1 line (below the field).
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Usual height: 45 pixels.

  IF Watch(1);
  [
    TagTypes = New(3);
    TagTypes[0] = "Calculation";
    TagTypes[1] = "AnalogInput";
    TagTypes[2] = "AnalogStatus";
    TagTypes[3] = "AnalogOutput";
    TagTypes[4] = "AnalogControl";
  ]
  GUITransform(170, 160, 370, 60,
               1, 1, 1, 1, 1,
               0, 0, 1, 0,
               0, 0, 0,
               \DialogLibrary.PSelectObject(2           { Parm num           },
                                            TagTypes    { Tag type           },
                                            \GetPhrase("Your_Title") { Title },
                                            TRUE        { Focus ID           },
                                            1           { Center list        },
                                            0           { Align top of bevel }));


PServerListName

(Dialog Library)

Description: | Called graphic module that creates an editable droplist of Server List Names, available to the tag.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PColorEdit(Parms, Title, ID, Trigger, DrawBevel, VertAlign, AlignTitle)
Parameters: |
Parms
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
An optional parameter that is any expression for a title to be applied.
ID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Set when the variable is changed.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control. If the editfield is beveled, its size will become fixed and will be the same as that for a droplist.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the droplist according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
Boolean. Set to TRUE if the title is aligned with the top.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

Example:

  {***** ServerList of the point *****}
  GUITransform(30,
               45 + 3*Space + 2*TEditHt + 2*TDropHt,
               WIDTH - 30,
               45 + 3*Space + 2*TEditHt + TDropHt,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PServerListName(\#ServerListName, GetPhrase("ServerListLabel"),
                                              TRUE { ID }, Trigger { Trigger }, FALSE {DrawBevel }));


PSpinbox

(Dialog Library)

Description: | Parameter Setting Spinbox. This module draws a spinbox with optional label.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PSpinBox(ParmNum, Label, BoxOnLeft, LowLimit, HighLimit [, Alignment, NumChars, CanEdit, FocusID, TextOption, TextValue, Trigger])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Label
Required. Any text expression to be used as a label with the spinbox.
BoxOnLeft
Required. Any logical expression. If true (non-0) the spinbox will appear to the left of the label, if false (0) it will be to the right. Defaults to TRUE.
LowLimit
Required. Any numeric expression giving the lowest permissible value. If the spinbox is editable and a value less than LowLimit is entered, it will revert to the LowLimit value.
HighLimit
Required. Any numeric expression giving the highest permissible value. If the spinbox is editable and a value greater than HighLimit is entered, it will revert to the HighLimit value.
Alignment
An optional parameter that is any numeric expression that sets the alignment of the spinbox and its label according to one of the following options. The default value is 0.
Alignment | Horizontal Alignment | Vertical Alignment
0 | Left | Top
1 | Right | Top
2 | Full | Top
3 | Left | Centered
4 | Right | Centered
5 | Full | Centered
6 | Left | Bottom
7 | Right | Bottom
8 | Full | Bottom
NumChars
An optional parameter that is any numeric expression giving the number of digits wide to make the spinbox. A value of 0 or invalid results in the spinbox being automatically sized to fit the widest number (or text string if TextOption and TextValue are set). The default value is 0.
CanEdit
An optional parameter that is any logical expression. If TRUE (non-0), the number in the field may be edited directly, if false (0), it may not. The default value is false.
Note that the value of this parameter directly affects the TextOption and TextValue parameters' effectiveness. If CanEdit is true, both are ignored.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
TextOption
An optional parameter that is any text expression used to replace a certain value (expressed by TextValue) in the spinbox field. This parameter will be ignored if CanEdit is true.
TextValue
An optional parameter that is any numeric expression for the value in the spinbox that is to be replaced by the text string in TextOption. This parameter will be ignored if CanEdit is true.
Trigger
An optional numeric expression. The value in Trigger will become 0 if the user changes the internal buffer (i.e. when the value of the WinEditCtrl as logged in the variable Change transits from invalid to zero). If the user presses any of Enter, the spin box arrows or the arrow buttons on the keyboard, Trigger becomes 1. If the spinbox loses focus, the value of Trigger becomes 2.
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..
This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the value displayed in the spinbox.
The size of the spinbox is constant, with the boundaries of the calling transform defining the position of the check box and its label.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Usual height: 22 pixels.

Example:

GUITransform(30, 100, 130, 20,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.PSpinbox(4 { Parm num },
                                     \GetPhrase("Your_Title"){ Label       },
                                     1                       { Box on left },
                                     0, 100                  { Limits      },
                                     5              { Full align, centered },
                                     0                      { Autosize box },
                                     TRUE                    { Editable    },
                                     TRUE                    { Focus ID    },
                                     \GetPhrase("NoneLabel") { Text option },
                                     0              { Index of text option },
                                     Trigger                 { Trigger     }));


PTimeZone

(Dialog Library)

Description: | Tool used to display a list of timezones, as defined by the operating system.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PTimeZone(ParmNum,Title, AlignTitle[, FocusID, Trigger, InitVal, DrawBevel, VertAlign])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
Title
Text to be displayed above the parameter.
AlignTitle
Boolean controlling the text alignment. If this parameter is invalid or numeric, it indicates the title alignment such that if it is true (non-0) the title is included in the calculation for vertical alignment, if false(0) it is added to the droplist after it (and its bevel if one exists) has been vertically aligned. The default is true
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Optional. If the list is editable, Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero: 1 if enter is pressed, 2 otherwise.
InitVal
An optional parameter that is any expression for the initial value displayed in the field.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control.
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the unopened list according to one of the following:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

Comments:

Value will be set to one of:

  • Invalid = UTC selected
  • 0 = Local timezone selected
  • Text = Name of timezone selected

The set value can be plugged directly into calls to ConvertTimestamp()

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary\.
The "P" tools (Pcheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters.

Usual height: 155 pixels.

GUITransform(30, 45 + 4*Space + TitleSpace + 3*CheckHt + TEditHt + TDropHt,
             WIDTH-30, 45 + 4*Space + TitleSpace + 3*CheckHt + TEditHt,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.PTimeZone(\#DeviceTimezone         { Parm num   },
                                      \GetPhrase("Your_Title") { Title      },
                                      TRUE                     { AlignTitle },
                                      TRUE                     { FocusID    },
                                      Trigger,
                                      Invalid                  { InitVal    },
                                      FALSE                    { DrawBevel  },
                                      0                        { VertAlign  }));


PType

(Engine-Level Function)

Description: | Returns the actual type of parameter at an index.
Returns: | Numeric - see comments
Usage: | Script Only.
Function Groups: | Advanced Module, Variable
Related to: | NParm | Parameter | ResetParm
Format: | PType(Object, Index)
Parameters: |
Object
Required. Any object (the object value of a running module instance).
Index
Required. Any numeric expression giving the number of the parameter of interest, starting from 1.
Comments: This function is for experienced users, and is not needed for normal operation. The return value reveals the type of parameter passed to the module from the module call, and is determined by the following table
Value | Meaning
0 | Status reference
1 | Short reference
2 | Long reference
3 | Float reference
4 | Text reference
5 | Object reference
6 | Status value (formal parameter type)
7 | Short value (formal parameter type)
8 | Long value (formal parameter type)
9 | Float value (formal parameter type)
10 | Text value (formal parameter type)
11 | Object value (formal parameter type)
12 | Calculated value (not a reference or constant)
13 | Short constant without formal parameter
14 | Long constant without formal parameter
15 | Float constant without formal parameter
16 | Text constant without formal parameter


PTypeToggle

(VTS Library)

Description: | Parameter Setting Type Toggled Field. This module draws a beveled, titled box showing the currently selected tag, numeric value or expression and buttons to modify the value as appropriate.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics, Variable
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | SiteDispParms |
Format: | \DialogLibrary.PTypeToggle(ParmNum, TagType, Title, FocusID, VertAlign, AlignTitle[, LowLimit, HighLimit, Trigger, EnableExpressions, DrawBevel, PtrValue, Immutable, AllowRootSelection, ParmValueType, StatusLabel])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) in the caller to alter.
TagType
Required. Any text expression for the type of tag used to create the droplist portion of the graphic. All existing tags of this type will be listed.
Title
An optional parameter that is any text expression to be used as a title for the tool. May be left as Invalid for no title.
FocusID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
VertAlign
Required. Any numeric expression that sets the vertical alignment of the unopened droplist according to one of the following:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

Whether the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle
Required Boolean. If AlignTitle is true (non-0), the title will be included in the calculation for vertical alignment.
If AlignTitle is false (0), the title will be added to the editfield after both the editfield and its bevel have been vertically aligned. The default is true.
LowLimit
An optional parameter that is any numeric expression giving the minimum value to be accepted by the editfield portion of the tool (it does not affect the tag's value if a tag is accepted).

If this parameter is valid and a value less than LowLimit is entered in the field, the variable set by the field will revert to the previous value.
HighLimit
An optional parameter that is any numeric expression giving the maximum value to be accepted by the editfield portion of the tool (it does not affect the tag's value if a tag is accepted).

If this parameter is valid and a value greater than HighLimit is entered in the field, the variable set by the field will revert to the previous value.
Trigger
An optional parameter that is set when the variable is changed.
EnableExpressions
An optional parameter that indicates the initial state of DoEnableExpressions.
If EnableExpressions is set to TRUE, a radio button will be shown that toggles display of the ExpressionEdit widget, which in turn allows users to enter an expression.
EnableExpressions defaults to FALSE, but if the value controlled by the PTypeToggle is already an expression, then the expressions option will be displayed regardless.
DrawBevel
Optional Boolean expression that when set to TRUE, causes a bevel to be drawn around the control.
PtrValue
Used to return the value of expressions/tags
Immutable
TRUE if we want to force all tag references to generate immutable reference code. Defaults to FALSE.
AllowRootSelection
TRUE to allow the Root tag to be selected. Default is FALSE
ParmValueType

ValueType of the parameter:
0 = Status (boolean)
1 = Short
2 = Long
3 = Double
4 = Text
5 = Octal
6 = Hexadecimal
7 = Color
8 = Object

StatusLabel
Label for the type Status radio button
BrowserObj
Set to the instance of the Tag Browser opened by SelectObject
DefaultTypeParm

Type to use when we have an Invalid value. May be one of:

  • 0 --> Constant (default)
  • 1 --> Expression
  • 2 --> Tag
RootParm
Optional - Object value of the root tag. Defaults to the caller's root.
FcnSelectionMode

Optional Numeric. What type of function should be selectable according to the following:

  • 0 --> Script
  • 1 --> Steady State (all)
  • 2 --> Steady State, no exclusive Steady States
Comments:

This module is a member of the VTScada Dialog Library and must therefore be called from within a GUITransform and prefaced by \DialogLibrary..

This control is not to be used in widget panel modules as it creates undesired output and does not support the range of type selections required for widget configuration. In widget panel modules, use ParameterEdit Snap-ins or NumericParameterEdit instead.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the numeric value or the name of the selected tag.
The height of the (unopened) droplist, the create new tag button and the radio buttons beneath them are constant, with the horizontal boundaries of the calling transform defining the combined width of the droplist and button, and the vertical boundaries of the calling transform defining the droplist's opened height, which will include the added height of the bevel above the field, but may or may not include the title, depending on the alignment used. Note that if the entire list can be displayed in a smaller area than indicated by the vertical boundaries of the calling transform, the dropped list height will be decreased. The dropped height of the list will always have a minimum height of 1 line (below the field).
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Usual height: 55-100 pixels.

Example:

GUITransform(10, 160, 270, 60,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.PTypeToggle(1 { Parm num },
                                        "DigitalOutput"          { Tag type    },
                                        \GetPhrase("Your_Title") { Title       },
                                        TRUE                     { ID          },
                                        0                        { Top align   },
                                        1                        { Align title },
                                        10, 20                   { Limits      }));


PWidgetSelect

Description: | Called graphic module that displays a tag selector to allow the selection of a tag widget.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PFileChooser | PHSliderBar | PHueSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle | SiteDispParms
Format: | \DialogLibrary.PWidgetSelect(ParmNum, Title, FocusID, Trigger, DrawBevel, VertAlign, AlignTitle[, UnspecifiedLabel])
Parameters: |
ParmNum
Required. Any numeric expression giving the parameter number (from 0) to alter in the caller.
Title
Any text expression to be used as a the title to put on the bevel.
Focus ID
Boolean. If this value is FALSE (0), the field will display its current setting, but cannot be opened (i.e. its value cannot be changed), and will appear disabled (grayed-out).
Trigger
Set when the variable is changed.
DrawBevel
Any Boolean expression that when set to TRUE causes a bevel to be drawn around the control. Defaults to TRUE
VertAlign
An optional parameter that is any numeric expression that sets the vertical alignment of the button and display area according to one of the following options:
VertAlign | Vertical Alignment
0 | Top
1 | Center
2 | Bottom

The default value is 0, top alignment.

AlignTitle
If true (non-0) the title is included in the calculation for vertical alignment, if false(0) it is added to the droplist after it and its bevel has been vertically aligned. The default is true.
UnspecifiedLabel
Optional. Caption to appear inside the selector field when a selection has not been specified.
Comments:

The "P" tools (PWidgetSelect, PCheck box, PContributor, PColorSelect, PDroplist, and PEditField) were intended only for use in configuration folders and drawing panel modules, and therefore are subject to the system security restraints.

This parameter tool expects the first parameter of its calling module to contain an array of tag parameters. It will then set the element indicated by ParmNum to the logical value set by the check box.

The PWidgetSelect will open the Widget Panel where the widgets available will be filtered to the tag type using this pTool.

Example:

      { Widget }
  GUITransform(0, 65, 400, 45,
               1, 1, 1, 1, 1            { No Scaling                             },
               0, 0, 1, 0               { No movement, visible, reserved         },
               0, 0, 0                  { Not selectable                         },
               \Code.DialogLibrary\PWidgetSelect(#TagParameter  { Parm Num       },
                          "Widget" 	 { Label          },
                           TRUE          { Focus ID       },
                           Trigger       { Trigger        },
                           FALSE         { No Bevel       },
                                                  0             { Top Vert align },
                           True          { Align Title    },
                           "Use Default" { Caption        }));


Q Functions

The sections that follow identify all VTScada functions beginning with "Q".


QuietLogon

Security Manager Module

Description: | Authenticates the AuthToken and if successful logs the calling user session on as the user specified in the AuthToken
Returns: | Boolean
Usage: | Script Only.
Related to: | AlternateLogoff | AlternateLogon | Authenticate | LogOff | UserCredChange | UserLogonDialog
Format: | \SecurityManager\QuietLogon(AuthToken [, Device, Namespace]);
Parameters: |
AuthToken
The concatenation of the user name, a colon (:) and the password.
Device
Optional. Name of the device that is making the request. Defaults to none.
Namespace
Optional. The namespace of the user. Defaults to none.
Comments: If the authentication fails, a failure event is recorded in the security event log.
Returns TRUE if the user was signed in successfully, otherwise FALSE.


R Functions

The sections that follow identify all VTScada functions beginning with "R".


RadialIndicator

(Meter Parts Library)

Description: | Will draw a radial type indicator that sweeps from a minimum angle to a maximum angle in the same fashion that a real radial meter would. Call from within a GUITransform.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | RadialLegend
Format: | \MeterParts\RadialIndicator(DataSource, IndicatorImage[, OffsetFromCenter, Direction, MinimumAngle, MaximumAngle, Hue, Saturation, Brightness, Transparency, Contrast, ColorizeHue, ColorizeIntensity, UseTagScaling, MinScaleValue, MaxScaleValue, DampenIndicator])
Parameters: |
DataSource
Required. A Tag name, constant or expression that represents the value to show.
IndicatorImage
Required. The full path to the name of an image file to use as the indicator. Typically, this is an image of a needle.
OffsetFromCenter
The offset from the center to translate the image. This allows the user to change the rotation center point of the indicator image. The default is 0 which sets the bottom of the indicator image as the rotation center point.
Direction
A flag indicating the direction from the minimum to the maximum value representation. 0 means increase in a clockwise manner while 1 indicates a counter-clockwise manner. The default is 0 (clockwise).
MinimumAngle
The start angle of the sweep. 0 is defined as up or the 12 o’clock position. The default is 225.
MaximumAngle
The end angle of the sweep. 0 is defined as up or the 12 o’clock position. The default is 135.
Hue
The Hue translation to perform on the Indicator image. This enables you to change the color of the indicator image. The image must have color in it already to perform a hue translation. If there is no color to start with, then changing this value does nothing. You can add color by setting a value for the ColorizeHue parameter, described later.
The default is 0, indicating that no hue translation is done and the indicator is in its native color.
Saturation
The amount of saturation of the colors in the indicator image. A value of 0 will make the image black and white (no color saturation). A value of 2 produces a brightly colored (saturated) indicator. The default is 1 which corresponds to the native saturation of the indicator image.
Brightness
An adjustment of the brightness of the indicator image. Higher numbers produce a brighter indicator image. A 0 produces a black image. The default is 1 which corresponds to the native brightness of the indicator image.
Transparency
An adjustment of the opacity of the indicator where 1 means 100% opacity and 0 means %100 transparent. The default is 1.
Contrast
An adjustment of the contrast of the colors in the indicator image. A value of 0 produces a flat looking image and a value of 2 gives a high contrast image. The default is 1 which corresponds to the native contrast of the indicator image.
ColorizeHue
A value that works in conjunction with ColorizeIntensity. This is the hue of the color that is introduced by colorizing an image. Colorizing an image will introduce color into an image that previously was black and white or grayscale. The default value is 0.
ColorizeIntensity
A value to define how much color to introduce into the image. The default is 0, meaning not to introduce any color at all into the image.
UseTagScaling
A flag that indicates whether to use the supplied Tag’s scaling values. The default is FALSE.
MinScaleValue
The minimum scale value to use if the UseTagScaling flag is not true. The default is 0.
MaxScaleValue
The maximum scale value to use if the UseTagScaling flag is not true. The default is 100.
DampenIndicator
A flag to indicate whether to dampen the indicator movement. Dampened movement creates the effect of animating the indicator. The default is false.
Comments: This function must be called within a GUITransform statement in order for it to work correctly.
The size of the indicator is scaled with respect to the original size of the image and the size of the transform. If you want a smaller indicator you can simply make a smaller transform. Using the offset from center in conjunction with the size of the transform allows for extensive customization of the size and position of the needle.

Example:

  GUITransform(458, 392, 608, 242,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               \MeterParts\RadialIndicator(Invalid,
               "Bitmaps\Meter Parts\Indicators\Radial\Needle5.png",
                0, 0, 225, 135, 0, 1, 1, 1, 1, 0, 0, 0, 0, 100, 0));


RadialLegend

(Meter Parts Library)

Description: | Draws a legend (i.e. the text labels) for a radial type meter. They are drawn at a constant radius from the center point of the drawing coordinates, beginning at a defined minimum angle and ending at a defined maximum angle. To be called from within a GUITransform.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | RadialLegend
Format: | \MeterParts\RadialLegend(TagName[, MinimumAngle, MaximumAngle, NumLabels, Font, Color, Direction, Orientation, UseTagScaling, MinScaleValue, MaxScaleValue])
Parameters: |
TagName
Required. The name of the Tag to use for scaling. If no tag is specified, then tag scaling cannot be used to automatically obtain the minimum and maximum scale values.
MinimumAngle
The start angle of the sweep. 0 is defined as up or the 12 o’clock position. The default is 225.
MaximumAngle
The end angle of the sweep. 0 is defined as up or the 12 o’clock position. The default is 135.
NumLabels
The number of Labels to show. The default is 5.
Font
The name of a font tag to use for the legend text.
Color
A color index for the color of the legend text. The default is 0 (black).
Direction
A flag indicating the direction from the minimum to the maximum value representation. 0 means increase in a clockwise manner while 1 indicates a counter-clockwise manner. The default is 0 (clockwise).
Orientation
A reserved parameter and should be set to 0.
UseTagScaling
A flag that indicates whether to use the supplied Tag’s scaling values. The default is false.
MinScaleValue
The minimum scale value to use if the UseTagScaling flag is not true. The default is 0.
MaxScaleValue
The maximum scale value to use if the UseTagScaling flag is not true. The default is 100.
Comments: This function must be called within a GUITransform statement in order for it to work correctly.
The text should scale with the size of the transform, if it does not, then you might have picked a font that doesn’t scale. Some non true-type fonts won’t scale.

Example:

GUITransform(478, 616, 628, 466,
1, 1, 1, 1, 1 { Scaling },
0, 0 { Movement },
1, 0 { Visibility, Reserved },
0, 0, 0 { Selectability },
\MeterParts\RadialLegend(Invalid, 225, 135, 5, Invalid,
0, 0, 0, 0, 0, 100));


RadioButtons

(System Library)

Description: | Draws a set of labeled radio buttons with (optional) title and border.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | SpinBox | SplitList | TextBox | ToolBar | VScrollbar
Format: | System.RadioButtons(X1, Y1, X2, Y2, Labels, Select [, FocusID, Border, Title, BtnsOnLeft, AlignTitle, AllowTextResizing, LeftToRight, BGColor, FGColor, Spacing, EnableFlags, Height, DotColorParm, TitleBGColor, TitleFGColor, BevelColor])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the radio buttons.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the radio buttons.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the radio buttons opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the radio buttons, whichever is the opposite to Y1.
Labels
Required. An array of text expressions used to label the buttons. The number of labels determines the number of buttons.
Select
Required. A variable whose value will be set to the index from 0 of the selected button. If the value of this variable is initially invalid, it will default to 0.
FocusID
An optional parameter that is any numeric expression from 0 to 32767 for the focus number of the first radio button. Each radio button following will have a focus ID number equal to the next number in sequence.
If this value is 0, the radio buttons will display the current setting of Select, but its value will not be able to be changed and the buttons will appear grayed out. The default value is 1.
Border

Optional numeric that may have the following values:

0 = No outline

1 = Raised box outline (default)

2 = Bevel outline

Title
An optional parameter that is any text expression to be used as a title with the radio buttons. The default value is to have no title.
BtnsOnLeft
An optional parameter that is any logical expression. If true (non-0) the radio buttons will appear to the left of their labels, if false (0) they will be to the right. The default value is true.
AlignTitle
An optional parameter that is any logical expression. If true (non-0) the title is drawn within the radio buttons' boundaries, if false(0) the buttons fill their bounding area and the title is added at the top (i.e. it extends past the top boundary). The default is true.
AllowTextResizing
An optional flag. If true, then text will resize with the control.
LeftToRight
An optional flag. If true, the buttons will be drawn from left to right.
BGColor
Optional. Any numeric expression for the background color of the control. No default value.
FGColor
Optional. Any numeric expression for the foreground color of the control (text color). No default value.
Spacing

Optional. Any of:

  • FALSE/Invalid = Full spacing
  • TRUE = Standard spacing
  • Array = An array of numeric values, providing the spacing in pixels to be used between one button and the next.
EnableFlags
Optional. An array of flags to enable or disable single buttons.
Height
Optional return value. If a variable is provided for this parameter the function will be set to the control's height, measured in pixels. Standard spacing will be used unless a spacing array has been provided.
DotColorParm
Optional color value, to be used for the radio dot.
TitleBGColor
Optional background color value to be used for the title bar.
TitleFGColor
Optional foreground color value to be used for the title text.
BevelColor
Optional color value to be used for the bevel line.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The parameters X1, Y1, X2 and Y2 define the outline of the buttons including their border, if there is one. If the area is too small to fully display the buttons they will extend beyond their right and bottom boundaries. Buttons and their border will not overlap each other and will always be shown in their entirety, although the labels may be clipped or entirely deleted.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

This does not return TRUE on change and should not be used as the trigger for an action statement. Instead, use a Watch on the variable being modified by the radio button selection.

Example:

System.RadioButtons(10, 10, 300, 210 { Outline of buttons },
                    Types { An array of labels },
                    Selected { Selected btn (from 0)},
                    4 { First btn's focus ID },
                    1 { Show border },
                    "PLC Types" { Title of the buttons },
                    0 { Buttons on the right });


Rand

(Engine-Level Function)

Description | Returns a random number between 0 and 1.
Returns | Numeric
Usage | Script only.
Function Groups | Generic Math
Related to: | Scale
Format: | Rand()
Parameters | None
Comments | This function is useful for simulations.

Example:

If TimeOut(1, 2);
[
   simulatedTemperature = Scale(Rand(), 0, 1, 50, 150);
]

Every 2 seconds, this sets simulatedTemperature to a random value between 50 and 150.


Read

(VTSDriver Library)

Description: | Used to create a request for a single read of a given driver address. (This is in contrast to the polled read request of the AddRead function).
Returns: | Object value of underlying read module.
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | AddRead
Format: | …\Driver\Read(Address, N, PtrDataDest)
Parameters: |
Address
Required. The address of the data to read. Depending on the driver protocol being used, this can be the starting register of the data to be read, a single address string, or an array of address strings.
N
Required. If the PLC supports reading a range of registers, this must be the number of elements to read. If Address is an array, this must be the size of the array. Otherwise this should be set to 1. This must not exceed the driver's VTSMaxBlock value.
PtrDataDest
Required. A pointer to destination for the data. May be a pointer to a variable or the object value of a module that contains a NewData module. If a pointer and N is 1, this will be set to the value that was read. If N > 1, this will be set to an array of values that were read. If an object value, the object's NewData will be called with the value that was read. Will be set to Invalid if the read fails.
Comments:

Allows the reading of a specific address on demand. The resulting data will be sent only to the requesting machine. This will also be the case when the function is run in a client-of-a-client configuration.
The object value of the underlying read module is returned from the function. When the read finishes, the returned object’s value will go to Invalid, signaling the end of read.

This function does not support bit extraction or type conversions. Use BuffRead on the result, followed by BuffWrite to do a type conversion. Depending on how the float was formed by the PLC a call to BuffOrder might be needed to arrange the bytes correctly. To perform bit extraction, use the Bit function on the result of the Read.

Example:

If 1 WaitForReadToEnd;
[
  Obj = ModDrv1\Driver\Read(40001, 5, &Val);
]

WaitForReadToEnd [
  If !Valid(Obj);
  [
    { … process data from read … }
    { When Obj is Invalid, read operation is complete and Val    }
    { will be an array of 5 values.                            }
    { If the read did not succeed, such as in the case of server }
    { failover, Val would be an array of 5 Invalid elements.   }
  ]
]

This example reads from addresses 40001 to 40005 of a Modbus driver tag named ModDrv1 and returns the result as an array in the variable Val.

Related information:

Bit, BuffRead, BuffWrite, BuffOrder


ReadBlock

(VTSDriver Library)

Description | Is launched to read a block of data from the PLC. It maintains a linked list of pointers to tag values with their absolute offset into the PLC file being read by this instance.
Warning | This function should be used only by advanced programmers. It is used only as a part of the VTSDriver module. Engineers writing a driver will not need to call this function directly.
Returns | Linked List
Usage | Script Only.
Function Groups | Stream and Socket
Related to: |
Format: | …\Driver\ReadBlock(Info1, Info2, Info3, DType)
Parameters |
Info1
Driver dependent. The first grouping parameter.
Info2
The second grouping parameter.
Info3
The third grouping parameter.
DType
The data type to read from the I/O device.
Comments Launched from a script, runs in steady state.
This module itself is in a global linked list of instances maintained by the VTSDriver module. This block represents all of the data to be read from a specific file in a specified PLC. All scan rates are handled by this one instance. This module keeps a list of nodes sorted by scan rates. These nodes point to another list of all the memory requests within that scan rate. This module will determine the best organization of blocks and launch a separate read module for each actual block of data read.


ReadConfiguration

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | This function provides a safe way to read configuration files.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | File I/O
Related to: | ModifyConfiguration | ReadPropertiesFile | WCSubscribe
Format: | \ReadConfiguration(CallBackModuleName)
Parameters: |
CallBackModuleName
Required text value, which is the name of the module (either launched or a subroutine that returns Invalid) . The named module is launched in the caller.
Comments: The callback object is allowed to read configuration files and is guaranteed that, for the life of the module, no other configuration code can modify the file. The callback module need not have parameters of its own. ReadConfiguration will not put values in them if they exist.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  If SomeTrigger;
  [
    SomeTrigger = 0;
    \ReadConfiguration("ConfigReader");
  ]
…
]

<
{============================= \ConfigReader ==========================}
{======================================================================}
ConfigReader

Main [
  If 1;
  [
     { The first line of the file is read into InfoVal1, and the second }
     { line is read into InfoVal2.                                    }
    FRead("MyConfigFile.txt" { filename         },
          0                  { offset           },
          "%l%l"             { format string    },
          InfoVal1, InfoVal2  { return variables });
    Return(Invalid);
  ]
]
{ End of \ConfigReader }
>


ReadINI

(System Library)

Description: | This subroutine read a variable entry from an INI file or a buffer containing one and returns its value. Will not access .Startup or .Dynamic files.
Note: | Access to configuration files is not reliable unless the caller holds the working copy lock. Acquiring the lock is a steady-state only operation, and therefore legacy operations that used script-mode access to these files are deprecated or no longer supported (see comments)
Returns: | Varies
Usage: | Script only.
Function Groups: | File I/O
Related to: | ReadConfiguration | CheckFileExist | CheckPathExist | ReadSectINI | WriteINI | WriteSectINI |
Format: | System.ReadINI(File, Section, VarName [, UseBuff])
Parameters: |
File
Required. Any text expression giving the absolute path and file name of the configuration file or the actual buffer containing its contents, depending on the UseBuff parameter.
Section
Required. Any text expression giving the name of the section in the file. This should not include the square brackets delimiting the section.
VarName
Required. Any text expression giving the name of the variable for which the value is required.
UseBuff
An optional parameter that is any logical expression. If true (non-0) the value of File must be a buffer, if false (0) it is a file that is to be used. The default used if this parameter is omitted is false.
Comments:

For developers the lock means that access to VTScada working copy files, both reading and writing, should not be done without having the lock. The lock is across all applications and system layer VTScada code. The lock prevents two different piece of code from changing the same code such that one piece of code sees inconsistent data while the other code is in the middle of changing it

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The return value will be invalid if the configuration file, section or variable was not found. Searches performed by this function are case insensitive.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

If 1 Main;
[
  DSource = System.ReadINI("C:\VTScada\Setup.INI" { Name of file },
                           "System" { Name of section },
                           "OrderlyShutdown" { Name of variable },
                           0 { Read file format });
]

This assigns the value of the variable OrderlyShutdown in the System section of the Setup.INI file to the variable called DSource.


ReadINIProperties

Description: | Gathers the sum of all of the properties files in this layer and all of its parents including the local workstation files.
Returns: | Dictionary (see comments)
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | ReadINI | ReadConfiguration | ReadPropertiesFile
Format: | Layer\ReadINIProperties(Result[, ExternalLock, SuppressOrphanedComments]);
Parameters: |
Result

Required. A pointer to a value that, when all files have been read, is set to the dictionary of structures described in the comments section.

If this is already a valid dictionary and the FileName parameter is valid, the data for the single file will be updated in the dictionary. This feature allow the publisher calls to Notifiy to update the structures.

ExternalLock
Optional Boolean. Set to TRUE if you do not want to acquire and release the lock. Defaults to FALSE.
SuppressOrphanedComments
Optional Boolean. Set to TRUE to ignore "+PseudoProperty" - comments that are not associated with a property. Defaults to FALSE.
Optional. Any
Comments:
INIProperty Struct [
  Name    { Variable name in the settings file                        };
  Value   { Simple Value or an ordered array of Values if the variable occurs more than once in the section of the file };
  Comment { Text comment if present in the file                       };
]

A simpler function, ReadPropertiesFile, is much more direct if the location of the setting to be read is known.


ReadLock

(RPC Manager Library)

Description: | Attempts to acquire a Read lock for the specified service. Subroutine call only.
Returns: | Nothing
Usage: | Script Only.
Related to: | WriteLock
Format: | \RPCManager\ReadLock(ActivePtr, Service [, OptGUID]);
Parameters: |
ActivePtr
Required. A pointer to a variable that will be set to "1" when the Read lock is obtained.
Service
Required. The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
This module maintains a Read lock on a per service basis. This module is intended to be launched. It will set the value pointed to by ActivePtr to 1 when the lock is obtained. To release the lock, or stop waiting for it, simply stop this module by stopping the caller or explicitly slaying it.

Related information:

RPC Manager Service


ReadPropertiesFile

(System Library)

Description | Reads a single Settings file and returns an INIFile Structure. Replaces ReadINI and ReadSectINI
Returns | INIFile Structure. See comments.
Usage | Script Only.
Function Groups | Configuration Management, File I/O
Related to: | WritePropertiesFile | GetINIProperty | ReadConfiguration | SetINIProperty
Format: | System.ReadPropertiesFile(File[, IsBuffer, SuppressOrphanedComments])
Parameters |
File
Required. Any text expression giving the full path and file name of the Settings file or the buffer containing its contents, depending on the IsBuffer parameter.
IsBuffer
An optional logical expression. Set TRUE if the File parameter is a buffer. Defaults to FALSE (0).
SuppressOrphanedComments
An optional logical expression. If TRUE then "+PseudoProperty"s - comments that aren't associated with a property will be left out. Defaults FALSE.
Comments

Returns arrays that are ordered by how they appear in the Settings file.

The INIFile structure returned is as follows:

INIFiles Struct [
  FileName    { full path and file name to the settings file          };
  OEM         { TRUE if an OEM layer file                             };
  Workstation { Name of the workstation or invalid if global          };
  Layer       { Instance of application layer owning the file         };
  Dynamic     { TRUE if a dynamic property                            };
  Sections    { Dictionary of sections each element of which
                is an array of Property structures         };
  Changed     { User sets to true if the file has been changed,
                initialized to false                                  };
 ]

The INIProperty structure is…

INIProperty Struct [
    Name        { Variable name in the .startup/.dynamic file  };
    Value       { Simple value                                 };
    Comment     { Text comment if present in the file          };
    Hidden      { TRUE if not visible in Edit Properties GUI   };
  ];

The INIFiles structure can be modified using SetINIProperty.

Note that if your intention is to read a configuration file, this function should be called from within a ReadConfiguration callback or a ModifyConfiguration callback.

Example:

Properties = ReadPropertiesFile(Concat(GetWCPath(),
                                       #APP_INI_FILENAME,
                                       #DYNAMIC_INI_EXT));
Name       = GetINIProperty(Properties\Sections["Application"], "Name");


ReadSectINI

Description: | This subroutine read an entire section entry from a configuration file or a buffer containing one and returns a 2-dimensional array containing variable names and their values. Will not access .Startup or .Dynamic files. Note: Access to configuration files is not reliable unless the caller holds the working copy lock. Acquiring the lock is a steady-state only operation, and therefore legacy operations that used script-mode access to these files are deprecated or no longer supported (see comments)
Returns: | Array
Usage: | Script Only.
Function Groups: | File I/O
Related to: | CheckFileExist | CheckPathExist | ReadINI | WriteINI | WriteSectINI |
Format: | System.ReadSectINI(File, Section [[, UseBuff] , PtrSectionStatus )
Parameters: |
File
Required. Any text expression giving the absolute path and file name of the Settings file or the name of the buffer containing its contents.
Section
Required. Any text expression giving the name of the section in the file. This should not include the square brackets delimiting the section.
UseBuff
An optional parameter that is any logical expression. If true (non-0) the value of File must be a pointer to a buffer, if false (0) it is a file that is to be used. The default used if this parameter is omitted is false.
PtrSectionStatus
A flag used to inform the caller of what was found, according to the following table:
Value | Meaning
Invalid | when either of the first 2 parameters are invalid
0 | when both section and settings exist
1 | when no section is found
2 | when section is found, but not settings
Comments:

For developers the lock means that access to VTScada working copy files, both reading and writing, should not be done without having the lock. The lock is across all applications and system layer VTScada code. The lock prevents two different piece of code from changing the same code such that one piece of code sees inconsistent data while the other code is in the middle of changing it.

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The array that is returned gives the variable names in its first row (Array[0][N]) and the variables' values in its second row (Array[1][N]). The return value will be invalid if the Settings file or section was not found, or if the section did not contain any variables. Searches performed by this function are case insensitive.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

If 1 Main;
[
  Vars = System.ReadSectINI("C:\VTScada\Setup.ini" { Name of file },
                            "System" { Name of section },
                            0 { Read file format });
]

This creates the array Vars and stores in it all variables in the System section of the Settings.Dynamic file.


ReadX

(Engine-Level Function)

Description | Reads numeric data from a text file into the elements of an array.
Returns | Array
Usage | Script Only.
Function Groups | Array, File I/O
Related to: | FRead | SRead | ReadXY
Format: | ReadX(ArrayElem, N, File)
Parameters |
ArrayElem
Required. Any array element giving the starting point in the array in which to store the data. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used. The array may be either statically declared or dynamically allocated.
N
Required. Any numeric expression giving the number of array elements to read starting at the element given by the first parameter.

If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
File
Required. A text expression giving the file name of the data file. It should be enclosed in double quotes if it is a constant. A known path Known Path Aliases for File-Related Functions for File-Related Functions may be provided in the form, :{KnownPathAlias}.
Comments The data should be stored in the file with one numeric value per line. The EOF marker for the file must not be on the same line as the last numeric value, as per the following rule

If more than one value exists on a line, if the line is left blank, or if it contains a non-numeric character, the corresponding element in the array will be set to invalid.
If the file contains fewer than N values, the remaining values will also be invalid.
This statement is useful for importing data from other databases into VTScada.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

If MatchKeys(1, "G");
[
  ReadX(chlorineCon[0] { Starting point in array },
        30 { Number of elements to read },
        "CHLORINE.TXT" { File from which to read data });
]

This reads 30 numbers from the text file called CHLORINE.TXT into elements 0 to 29 of chlorineCon when a capital G is pressed on the keyboard.


ReadXY

(Engine-Level Function)

Description: | Reads data points from a file into the elements of two arrays.
Returns: | Array
Usage: | Script Only.
Function Groups: | Array, File I/O
Related to: | FRead | ReadX | SRead
Format: | ReadXY(XArrayElem, YArrayElem, N, File)
Parameters: |
XArrayElem
Required. Any array element giving the starting point in the array in which to store the X coordinates. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used. The array may be either statically declared or dynamically allocated.
YArrayElem
Required. Any array element giving the starting point in the array in which to store the Y coordinates. The subscript for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used. The array may be either statically declared or dynamically allocated.
N
Required. Any numeric expression giving the number of array elements to read starting at the elements given by the first two parameters.
If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
File
Required. A text expression giving the file name of the data file. It should be enclosed in double quotes if it is a constant. A known path Known Path Aliases for File-Related Functions for File-Related Functions may be provided in the form, :{KnownPathAlias}.
Comments: The data should be stored in the file with one numeric value per line. The data are then alternately placed into each of the two arrays. If more than one value exists on a line, if the line is left blank, or if it contains a non-numeric character, the corresponding element in that array will be set to invalid. If the file contains fewer than N values, the remaining values will also be invalid.

The arrays need not start at the same index number.
This statement is useful for importing (X, Y) data from other databases or spreadsheets into VTScada.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

If MatchKeys(1, "R");
[
  ReadXY(chlorineCon[0] { Starting point in first array },
         pumpSpeed[0] { Starting point in second array },
         60 { Number of elements to read },
         "CHLORINE.TXT" { File from which to read data });
]

This reads 60 numbers from the text file called CHLORINE.TXT into elements 0 to 29 of chlorineCon and pumpSpeed when a capital R is pressed at the keyboard. Numbers are placed in alternating arrays as they are read.


RecommendAlternate

(RPC Manager Library)

Description: | Instructs RPC Manager that the local service instance does not consider itself a good server candidate.
Returns: | Nothing
Usage: | Script Only. (Subroutine call only)
Function Groups: | Network
Related to: |
Format: | \RPCManager\RecommendAlternate(Service [, OptGUID]);
Parameters: |
Service
The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\ as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.


RecommendPrimary

(RPC Manager Library)

Description: | Instructs RPC Manager that the local service instance considers itself a good server candidate.
Returns: | Nothing
Usage: | Script Only. (Subroutine call only)
Function Groups: | Network
Related to: |
Format: | \RPCManager\RecommendPrimary(Service [, OptGUID]);
Parameters: |
Service
The name by which the service is known.
OptGUID
An optional parameter that is any expression giving the 16-byte binary form of the globally unique identifier (GUID) for the application in which the service instance is located. The default is the application to which the caller belongs.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.


RecordProperty

Code layer

Description: | Modifies one or more properties within a single properties file and commits the result.
Returns: | Object reference to itself, which becomes invalid on completion.
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: |
Format: | \RecordProperty(SettingsFile, Section, Name, Value[, Comment, CommitComment, Deploy, CallerHasLock, ClearSection, Workstation])
Parameters: |
SettingsFile
Required. Text or Integer. The name of the settings file to be altered.
As a convenience this parameter can also be an integer representing any of the four standard settings file types as follows:
0 => workstation.Dynamic
1 => Settings.Dynamic
2 => workstation.Startup
3 => Settings.Startup
Section

Required. May be the name of the section that the property belongs to, or an array of section names.

The section will be <hidden> or [visible] according to the optional Hide parameter.

Name
Required. May be the name of the property to modify, or an array of property names.
Value
Required. May be the value to be set for the property, or an array of values matching the array of property names.
Comment
Optional. May be the comment to add to the property or an array of comments matching the array of property names.
If invalid, the existing comment will be used.
CommitComment
Optional. The comment to be added when the change is committed to the repository.
Deploy
Optional Boolean. Set TRUE to deploy the change immediately.
CallerHasLock
Optional Boolean. Set TRUE if the caller holds the layer lock in write mode.
ClearSection
Optional Boolean. Set TRUE to empty the section (or sections if an array was provided), before writing the new value(s).
Workstation
Optional text. If an integer 0 or 2 was used for the SettingsFile parameter, then the name of the workstation should be provided.
Defaults to the current workstation (WkStaInfo(0)) if missing or invalid.
Hide
Optional Boolean. Set TRUE to hide the section or FALSE to reveal it. Invalid will leave the section as it is.
UserID
Optional text. The user account to be associated with the revision. Defaults to the currently signed-in user.
Comments: This function returns an object reference to itself, which becomes invalid when the operation (handled asynchronously) is complete.

Examples:

Init {
  If 1 WaitEnable;
  [
     { Enable the Alarm Text-to-Speech feature }
    Result = \RecordProperty(1 {Settings.Dynamic},
                                  "System", "AlarmSpeechEnable",
                                  1 { Enable },
                                  Invalid { Leave the existing comment },
                                  "Enable Alarm Text-to-Speech" { Comment for the commit},
                                  TRUE { Deploy });
  ]
]

WaitEnable [
  If !Valid(Result);
  [
     { Do something with related to a spoken alarm }
  ]
]


Redirect

(Engine-Level Function)

Description: | Redirects a local device to network resource.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Printer, Software and Hardware, Network
Related to: | DefaultPrinter
Format: | Redirect(Local, Remote)
Parameters: |
Local
Required. Any text expression giving the local device to redirect, for example "G:", "LPT1:", "DEF:" (default printer), etc.
Remote
Required. Any text expression giving the network resource to map the local device to. If this parameter is an empty string or invalid, the current connection for the device Local is disconnected.
If Local has any value other than "DEF:", this parameter must be the same form used by the Windows™ command prompt, "net use" function:
"\\MyServer\MyPrinter"
If Local has a value of "DEF:", the value of this parameter has three elements separated by commas, as follows:
<printer name>, <driver name>, <port>
Each of these elements must be valid to have a valid Remote parameter. If any are invalid, programs such as Print Manager may revert back to the previous valid printer, while other programs may have unpredictable behavior.
Comments: Caution should be exercised when using this statement, since the redirection of the device is permanent - execution of the statement causes the change to be written to the Windows™ registry. For this reason, when using "DEF:" (the Windows™ default printer), it is always a good idea to use the DefaultPrinter function prior to doing the Redirect, so that the original default printer may be restored at a later date.

Example:

If ZButton(10, 40, 110, 10, "Print", 1);
[
  oldP = DefaultPrinter() { Keep track of original printer };
  Redirect("DEF:" { The Windows default printer },
           "\\Serve1\NPrinter, HPPCL5MS, Ne00:"
           { The printer on the server });
  PrtScrn() { Do a printout of the screen };
]

A press of the button causes the default Windows™ printer to be redirected to the printer called NPrinter on the server called Serve1. The rest of the string indicates the driver to be used in this redirection.


Register Alarm Manager

Viewing: Reference > Function Reference > R Functions > Register Alarm Manager

Register (Alarm Manager)

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Inform the Alarm Manager that a module instance may wish to generate alarms in the future.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Commission
Format: | \AlarmManager\Register(AlarmObject[, Enable]);
Parameters: |
AlarmObject
Required. The object value of the new alarm to add to the configured alarm list. A variable called "Name" must exist within the scope of AlarmObject. This variable uniquely defines the text name of the alarm.
Enable
Required Logical Expression. Set to true if the alarm should start enabled. Defaults to "Enabled" if invalid or not defined.
Comments: The Register subroutine always returns "0".
Registering an alarm does not trigger an alarm. It informs the Alarm Manager that the AlarmObject module instance may wish to generate alarms in the future.


Register (Modem Manager)

(Modem Manager module)

Description: | This module registers a discriminator that accepts incoming calls.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Alarm
Related to: |
Format: | \ModemManager\Register(Context, Station, Priority [, MediaMode, Voice, TimeOutVal, Name]);
Parameters: |
Context
An object value of the context in which the discriminator module is to be called.
Station
A unique identifier for this discriminator instance.
Priority
The relative priority of this discriminator to others. Priorities are in the range of 0..99 with numerically higher priorities being called first.
MediaMode
specifies the media mode that this discriminator wishes to handle. Typically, this would specify AUDIO to handle incoming audio calls. The default is DATAMODEM which handles normal data calls. Please refer to the Comments section.
Voice
If this discriminator is to handle AUDIO calls, then this parameter specifies the text GUID of the voice to be used by the Text-to-Speech engine.
TimeOutVal
An AUDIO discriminator generally relies on some human-generated response. This parameter sets the number of seconds that the discriminator runs from before giving up. The default value is 20 seconds. Please refer to the Comments section for further information.
Name
Usually Context will, when cast to a text value, identify the name of a variable in Code whose value is the object context for the discriminator. If this is not the case, then the name should be given here.
Challenge
A string to send in response to incoming calls that don't initially transmit any data.
Comments:

In order to receive incoming calls, you must first call the Modem Manager's Register method, passing the driver's object value, its station number, and a priority (relative to other drivers).

\ModemManager\Register(Root, Station, 10 { Priority ]);

You must also provide a discriminator subroutine. This subroutine will be called by the Modem Manager when it offers you an incoming call. The Modem Manager passes as a parameter a BUFFER which contains the initial data received from the line (see HelloPacketLength). You should parse this data and decide whether it is supported by your driver, and for which station it is intended.

Return Invalid to reject this call.

Return the (valid) station identifier to accept the call.

If you accept the call, then the Port\IsConnected() module will go true, and you may acquire the serial port semaphore \PortManager.PortConnectSem and read and write data via the serial port.

If Port\IsConnected() goes false, the call has been disconnected. If you wish to hang up the call, call the subroutine Port\CallComplete().


Register

Viewing: Reference > Function Reference > R Functions > Register

Register (RPC Manager)

(RPC Manager Library)

Description | This subroutine registers a service for RPC and returns a pointer to the variable containing the current RPC status of the service.
Returns | Pointer containing the current RPC status.
Usage | Script Only. (Subroutine call only)
Function Groups | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPotentialServer | IsPrimaryServer | Send | SetRemoteValue
Format: | \RPCManager\Register(ServiceName [, ListSource, ListName, SemObj, StartMode, PrioritySync, ServerList, Sticky])
Parameters |
ServiceName
Required. The name of the tag to register.
ListSource

The object that is the source of this service's server list. Should have the following callbacks (like LayerModule):

  • ServerListSubscribe
  • ServerListUnsubscribe
  • GetServerList
  • GetRPCServiceSettings

Defaults to Layer object with this service's LocalGUID.

ListName

Name of the server list to use for this service.

If invalid, the section name will be ServiceName.

If ListSource is a Layer, then the list used follows the following rules of precedence: service and workstation-specific list, service-specific list, workstation-specific list, then default server list.

If no lists can be found at all, this machine is assumed to be the sole server.

SemObj
An object value for an instance of the system Semaphore module. If Invalid, the RPC Manager will launch an instance of Semaphore for this service.
StartMode

The mode that the service instance will start up in or become when it loses its connection to the server instance. The mode of a service determines whether the RPC Manager transmits service broadcast messages from the server. You should supply the constant \RPC_ACCEPT_ALL (default) if your service requires no synchronization whatsoever. Otherwise, set it to \RPC_SYNC_MODE.

Set TRUE to prevent server from sending Broadcast messages to us.

PrioritySync
When set to non-zero, the PrioritySync flag prevents higher priority servers from syncing with lower priority servers, forcing the lower server to synchronize with itself. Most system services do not set this flag.
ServerList
An optional parameter that is an array of server names for this service. If used, it overrides any server list configuration that has been done in the .RPC files. If not used, the usual method of determining the server list is used.
Sticky
An optional flag that causes this service to stick to a server, even if a higher order server comes online (see also sticky status).
Comments Subroutine call only.
This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

The return value from this call is a pointer to a variable that contains the current RPC status of this service instance. Dereferencing this pointer will yield one of the following values
0 - the status of the service instance is unknown at this time.
1 - this service instance is a client to another service instance.
2 - this service instance is the server instance.
Invalid - the caller of Register() has been slain.

This value will almost certainly be required by the service instance's code to allow it to operate correctly.

The ServiceLayer parameter is almost always used for system-level services (services that don't run within running applications). Unless writing a system-level service, leave this parameter as invalid and set the server list via the Edit Server Lists panel of the application properties GUI.

Related information:

Refer to "API Reference" for a listing of Service Control Methods, RPC Methods, and Deprecated RPC Methods.


RegisterCustomTable

(VTSSQLInterface library)

Description: | A launched module that registers a name for a virtual database table and defines what information will be available from that table.
Returns: | Varies. 0 if array size is invalid,
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | SQLQuery
Format: | \VTSSQLInterface\RegisterCustomTable(Name, Description, Columns, IsReadOnly, CallbackObj, SupportsTPP)
Parameters: |
Name
Required. Any text value for the name of the table.
Description
Required. Any text value for the description of the table
Columns

Required. May be either a dictionary or a callback module.

If the first, then Columns will be a dictionary of structures that describing the column contained in the table. The dictionary keys should be the names of the columns. Use this option when the table will refer to a single tag or type of information where the column format is known.

If the second, then a callback context may be provided where the module SQLQueryGetColumnInfo is called to retrieve the column info. If the current module contains this submodule (as is usually the case) then you will use Self() for this parameter.
Use this option if the custom table may refer to multiple tag types, each having its own structure.

Further information is provided in the comments section.

IsReadOnly

Required numeric. Set to 1 for read only. Writes (value 0) are not currently supported through the SQL interface.

CallbackObj

Required. The object value of a module which must contain a submodule named SQLQueryRetrieveData. In most cases, this will be stored in the current file, in which case self() should be used for this parameter.

SQLQueryRetrieveData will be called by VTSSQLInterface\SQLQuery when it needs to retrieve data from the custom table. Further information is provided in the comments section.

SupportsTPP
Required Boolean. Set TRUE if the table has support for additional TPP tables. In this case SQLQueryRetrieveData will be called with a TPP value specified at query-time.

Comments:

Columns Parameter

If the Columns parameter is defined as a dictionary, each element must be a VTSSQLColumnInfo structure. This structure is defined as follows:

VTSSQLColumnInfo STRUCT [
                   SQLType                   { One of the SQL type constants     };
                   IsPrimaryKey              { 1 for primary key column, 0 if not                                 };
];

For example, VTScada uses the following code to define the columns when registering the table name, AlarmHistory:

    AlarmHistoryColumns = Dictionary();
  { Standard fields that will always exist for the alarm history table }

AlarmHistoryColumns["Timestamp"] = ColumnInfo(\#SQL_DATETIME, 1, "Timestamp"
AlarmHistoryColumns["Id"]        = ColumnInfo(\#SQL_VARCHAR,  0, "Name");
AlarmHistoryColumns["Name"]      = ColumnInfo(\#SQL_VARCHAR,  0, "Name");
AlarmHistoryColumns["SubName"]   = ColumnInfo(\#SQL_VARCHAR,  0, "Name");
AlarmHistoryColumns["Event"]     = ColumnInfo(\#SQL_VARCHAR,  0);

If using a callback object for the Columns parameter, your code must include a module named SQLQueryGetColumnInfo. This subroutine will be called by the SQLQuery module, and must return a dictionary of VTSSQLColumnInfo structures, keyed by column name, for each column that to be queried in the given custom table.

RawTableName

Required. Any text value for the custom table name without :TPP modifiers.

SplitColumnName

Optional text. If specified, the returned dictionary is only guaranteed to return that column (if it exists), but may contain other columns as well. This allows for performance optimization for custom tables that contain large numbers of columns.

SQLQueryGetColumnInfo will normally start with code to strip off any prefix or delimiter from the table name, then obtain the object value of the tag type:

{ code to clean up the name followed by...}
TagModuleVal = Scope(\Code, CleanTagTypeName );

This will be followed by a call to ListVars to obtain the variables in the specified tag object, then a loop to add each required variable to the dictionary of VTSSQLColumnInfo structures.

CallbackObj Parameter: SQLQueryRetrieveData

SQLQueryRetrieveData is a launched module that must be implemented on the CallbackObj. Note that zero is the proper return if the array size is zero.

Its parameters are as follows:

PtrResult

Required. A pointer to the variable, within which the results will be returned.

The returned results must be a 2-dimensional array (even if only one column is returned), indexed in the form: Result[Col][Row]. This variable should not be set until the results are complete.

TableName
Required. The name of the table being queried. This is required in case the caller decides to register more than one table with the same CallbackObj.
RequestedColumns

Required. An array of the names of the columns needed to satisfy the SQL query.

MaxRecords

Required numeric. The maximum number of result rows that this module is allowed to return.

StartTime
Optional. If the WHERE clause of the query resolves to a starting timestamp, it will be passed here, otherwise Invalid.
EndTime
Optional If the WHERE clause of the query resolves to an ending timestamp, it will be passed here, otherwise Invalid.
TPP
Optional. The time period per row to apply to the query.
FilterHints

Optional. A dictionary containing structured entries for each field in the WHERE clause that can be filtered to one or more ranges or exact values.

The structure definition follows:

HintStruct STRUCT [
  Ranges;           { Array of RangeDescriptors, field value must fall into one or more of the ranges }
  ExactMatches;     { Array of values that field value must match one of.
                      Only valid if all Ranges have min=max }
  OverallMin;       { Overall minimum for the field value, may be Invalid }
  OverallMax;       { Overall maximum for the field value, may be Invalid }
];

In turn, a RangeDescriptor is a simple structure to contain a min/max range. No distinction is made between inclusive and exclusive ranges. One of min or max may be Invalid, indicating an open-ended range, but not both. For queries that are exact matches, Min and Max will be identical.

RangeDescriptor STRUCT [
  Minimum;
  Maximum;
];

SQLQueryRetrieveData may ignore any or all of the information received in FilterHints. A simple implementation might use only OverallMin and OverallMax, or just the ExactMatches array. More advanced implementations could use the complete information from the Ranges. Note that ExactMatches, OverallMin, and OverallMax are all derivable from Ranges. They are derived by ParseWhereClause itself for convenience of the consumer.

SQLQuery itself will always apply a post-filter derived from the WHERE expression to filter out any rows that do not match the expression. So SQLQueryRetrieveData need only filter out some of the rows suggested by FilterHints. Filtering out not enough rows will not result in incorrect results returned from the query. (This is also why no distinction is made between inclusive and exclusive ranges in FilterHints. If the range was meant to be exclusive in the original WHERE clause it will be post-filtered correctly.)

Example: for the WHERE clause:

... WHERE WellKey="MyWell1" AND Timestamp >= '2015-06-01' AND Timestamp < '2015-07-01'

the dictionary passed to SQLQueryRetrieveData will contain two keys: WellKey and Timestamp.

WellKey's value is a HintStruct containing the following elements:

  • Ranges - In this example the Ranges array would contain one element of the Range structure with Minimum="MyWell1" and Maximum="MyWell1".
  • ExactMatches - In this example ExactMatches array would contain one element set to "MyWell1".
  • OverallMin - In this example would be set to "MyWell1".
  • OverallMax - In this example would be set to "MyWell1".

Timestamp's value is a HintStruct containing these elements, where the timestamps use the VTScada timestamp type.

  • Ranges - Array(Range('2015-06-01 00:00:00', '2015-07-01 00:00:00' ))
  • ExactMatches - Invalid
  • OverallMin - '2015-06-01 00:00:00' -- Note that if the Timestamp is set to be the primary key on this custom table, this same timestamp value will be passed as StartTime to SQLQueryRetrieveData.
  • OverallMax - '2015-07-01 00:00:00' -- Note that if the Timestamp is set to be the primary key on this custom table, this same timestamp value will be passed as EndTime to SQLQueryRetrieveData.
OrderByHints
Object that indicates whether to sort the result in ascending or descending order. Defaults to chronological order.

Related information:

VTScada SQLInterface Module


ReleaseLock

(See: RemoveLock for removal of a Control Lock.)

Description: | Releases a working copy semaphore that was acquired by AcquireLock.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | AcquireLock |
Format: | Layer\ReleaseLock()
Parameters: | none
Comments: | Call only you currently have the working copy semaphore.

Examples:

none


ReleaseToken

(Control Token Manager)

Description: | Releases a control token from a tag
Returns: | Nothing
Usage: | Script Only.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | ControlTokenManager.ReleaseToken(TagID, TokenGUID[, Custom, Timestamp, SessionID, AccountID, MachineID, Device])
Parameters: |
TagID
Required string. The UniqueID of the tag from which to release the token.
TokenGUID
Required string. The GUID of the token to release
Custom
Optional. A structure of custom fields to log
Timestamp
Optional The UTC timestamp of this event. Defaults to current time
SessionID
Optional. The ID of session releasing the token. Relevant only if the token ownership is tied to the session.
AccountID
Optional. The Account ID of user releasing the token. Defaults to the currently signed-in user.
MachineID
Optional. The MachineID of the workstation where this request originated. Defaults to the current machine.
Device
Optional. Name of client device
Comments:

Releasing a token initiates an auto-granting mechanism where the ControlTokenManager will go through the list of Token Requests and grant all the Token Requests it can, starting from the oldest.


RemoveCertificate

Description: | Removes a certificate from a certificate store.
Returns: | Integer. Zero for success or a system error code.
Usage: | Script Only.
Function Groups: | Certificates
Related to: | AddCertificate | CheckCertificateChain | FindCertificate | GetCertificateInfo | ListCertificates | MakeSelfSignedCertificate | SetCertificateProperty
Format: | RemoveCertificate(MachineStore, StoreName, Thumbprint)
Parameters: |

MachineStore

Required Boolean. If TRUE (non-zero), attempts to remove the certificate from a store in the Local Computer certificate hive. If FALSE (zero) attempts to remove the certificate from a store in the Current User certificate hive.
StoreName
Required text. The name of the store from which to remove the certificate.
Thumbprint
Required. A binary buffer holding the SHA1 thumbprint of the certificate to remove.
Comments

A SHA1 thumbprint is used as the certificate identification to ensure that the certificate is uniquely identified and the intended one is removed.

You can obtain the SHA1 thumbprint of a certificate from a number of other certificate statements. For example, AddCertificate returns a SHA1 thumbprint and a thumbprint can be found in the certificate information structure returned from ListCertificates, GetCertificateInfo or FindCertificate.

Thumbprints are convenient, compact values that can be persisted and used again later.

Example:

RemoveCertificate(FALSE, "My", CertificateInfo.SHA1Thumbprint);

This will attempt to remove a certificate identified by the SHA1Thumbprint in structure CertificateInfo from the Personal store in the current user’s certificate hive.


RemoveFromList

(Alarm Manager module)

Description: | Removes an alarm from the specified list in an Alarm Database, usually a custom list.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm Functions
Related to: | AddToList | Commission | EvaluateAlarm
Format: | \AlarmManager.RemoveFromList(AlarmName, ListName, Action[, TimeStamp, AccountID, Device, RecordGUID, HookName, MachineID, Custom, NoteRequired, NoteMinLength, FromPLC, Description])
Parameters: |
Alarm Name
Required text. A unique name for the alarm. Typically, the unique ID obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm.
For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).
ListName
Required. The name of the list to remove from, e.g. “Active”.
Action

A string or PhraseID that identifies the reason for the transaction.

For default options, see Alarm Action Codes in Alarm API Structure Definitions

Timestamp
Optional. UTC timestamp of the value. Defaults to the current time.
AccountID
Optional. AccountID of operator
Device
Optional. Name of client device.
RecordGUID
GUID of the specific record to remove from the list. If Invalid, all records for the specified AlarmName will be removed.
HookName
Advanced Option. Name of the hook module to call before logging this transaction.
MachineID
Optional. Workstation MachineID. Defaults to local.
Custom
Optional. Structure of custom fields to be logged with the event.
NoteRequired
Optional. TRUE to prompt for a note before the transaction.
NoteMinLength
Minimum length of note (Defaults to 1.)
FromPLC
Advanced Option. Set to FALSE.
Description
Optional. Customized description, used if it differs from the description given to Commission.
Comments:

Advanced users only.

RemoveFromList can be used Remove an alarm from a custom list. The custom list can be displayed by specifying it in a <ListFormats><Format> section of AlarmListsFormats.XML as defined in Customize Columns in Alarm Displays

To remove an alarm from the Active of Unacked lists, Ackand EvaluateAlarm may be more practical.

Example:

To remove an alarm from a custom "Deferred" list:

\AlarmManager.RemoveFromList(AlarmName, “Deferred”, “UndeferLabel”);


RemoveLock

(Control Lock Manager)

Description: | Removes a Control Lock from a tag.
Warning | This statement is recommended for advanced users only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | (Control Lock Manager)
Related to: | AddLock | CanAddLock | CanControl (Control Lock Manager) | CanRemoveLock | GetLockLevel | RemoveLock |
Format: | \ControlLockManager.RemoveLock(TagID, LockGUID[, Note, Custom, Timestamp, SessionID, AccountID, MachineID, Device, Auto])
Parameters: |
TagID
Required text. The unique ID of tag from which to remove the lock.
LockGUID

Required text. The lock record GUID of the lock.

To find the lock record use a statement such as AlarmManager.GetAlarmList(...). RemoveLock is not not designed to be user-friendly. Most users should use the 'Remove' button in the Alarm List widget.

Note
Optional text. A note to log following the release operation.
Custom
Optional. A structure of custom fields to log.
Timestamp
Optional timestamp. UTC timestamp of this event. Defaults to current time.
SessionID
Optional text. The ID of the session where this function was called. Defaults to the current security session.
AccountID
Optional text. The AccountID of the user removing the lock. Defaults to the user signed in at the station where this function is called.
MachineID
Optional text. The workstation's MachineID. Defaults to the workstation from which this function is called.
Device
Optional text. The name of the client device.
Auto
Optional Boolean. Set true for automatic lock removal.
Comments:

None

Example:

None available.


RemoveParameter

(Engine-Level Function)

Description: | Removes a parameter from a module's parameter list.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: |
Format: | RemoveParameter(Module, ParmNum)
Parameters: |
Module
Required. Any expression for the module or object value.
ParmNum
Required. Any numeric expression for the parameter to remove, beginning at 1.
Comments: The parameter variable removed by this function becomes a normal local variable.


RemWSDL

(System Library)

Description | Disconnects a Realm from a WSDL file and the associated set of VTScada modules, cleaning up any resourced used by that web service.
Returns | Nothing
Usage | Script Only.
Function Groups | XML
Related to: | SetWSDL | XMLProcessor | XMLAddSchema | XMLParse | XMLWrite
Format: | System.Webservice\RemWSDL(Realm)
Parameters |
Realm
Required. The name of the VTScada Realm to have its web service removed.
Comments After RemWSDL is called, the associated web service will immediately stop processing messages, however any operations set in motion by that service will run to completion. This function is called implicitly if the connected module is destroyed.


Rename

(Engine-Level Function)

Description: | Renames an existing file.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | File I/O
Related to: | GetFileAttribs | SetFileAttribs
Format: | Rename(OldName, NewName)
Parameters: |
OldName
Required. Any text expression for the current name of the file to be changed. A known path Known Path Aliases for File-Related Functions may be provided in the form, :{KnownPathAlias}.
NewName
Required. Any text expression for the new name that the file is to be changed to. A known path alias may be provided in the form, :{KnownPathAlias}.
Comments: This statement will rename the file regardless of its attributes and the attributes will not be changed. If the file to be renamed does not exist, a file will not be created.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

Rename("C:\VTScada\MyApp\TestMod.SRC",
       "C:\VTScada\MyApp\Test1.SRC");

This statement changes the name of a file from "TestMod.SRC" to "Test1.SRC".


Replace

(Engine-Level Function)

Description: | Performs a case sensitive search and replace operation on a buffer and returns the resulting buffer.
Returns: | Buffer
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | Locate
Format: | Replace(Buffer, Offset, N, Search, Replace)
Parameters: |
Buffer
Required. Any text expression giving the buffer to search. There is no limit on the size of the buffer.
Offset
Required. Any numeric expression giving the buffer offset from 0 to start the search. Must be non-negative, otherwise Invalid will be returned.
N
Required. Any numeric expression giving the number of buffer characters (bytes) to search.
Search

Required. Any text expression giving the search string. The search is case sensitive.

If an empty string is provided in this parameter, Replace will return the original text.

Replace

Required. Any text expression giving the replace string.

Comments:

This function returns a buffer that is the same as Buffer, except that within the first N bytes following Offset, all occurrences of Search are replaced with Replace.
Because the search and replace strings are delimited by quotation marks, to include a set of quotation marks as part of either, you must use two sets of quotation marks inside of the quotation marks that delimit the string (see example).

Example:

If a variable exists such that:

txt = "abcdefABCDEF";

And the following statement is executed:

txt = Replace(txt { Buffer },
              0 { Start at beginning of buffer },
              12 { Search through 12 characters },
              "fA" { Search for this string },
              "-wow-" { Replace string with this });

The result will be that txt will contain the string "abcde-wow-BCDEF".

As a further example of how this function is used, if quotation marks were considered illegal characters in a certain context and therefore needed to removed from a string, the following statement could be used to achieve this:

txt = Replace(stringWithQuotes { Search buffer },
              0 { Start at beginning },
              StrLen(stringWithQuotes) { Search entire string },
              """" { Find all quotes },
              "" { Replace with nothing });


ReplaceStatement

(Engine-Level Function)

Description: | Replaces a statement with another statement.
Warning: | This function should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, States
Related to: | Compile
Format: | ReplaceStatement(NewS, Location, Size, Adjust)
Parameters: |
NewS
Required. Any expression for the statement value of the new statement. (This value can be obtained using the Compile function.)
Location
Required. Any expression for the code value that indicates what statement to replace. (This value can be obtained using the Compile function.)
Size
Required. Any numeric expression for the size of the new statement text, in characters.
Adjust
Required. Any logical expression. If true, the text in the file will be moved to allow for the statement that is being replaced. If false, the text will not be moved.
Comments: This statement is disabled in the run time version of VTScada. It will do nothing.


ReportError

(System Library)

Description: | Post error information to VTS Trace and optionally, to the display.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Error Manager
Related to: |
Format: | System.ReportError(eMsg, QualifierSet[, UserAndSession, Silent, HelpFile, HelpID, TraceCategory, ApplicationGUID])
Parameters: |
eMsg
Required. Any text containing the error message.
QualifierSet

Required. An additional error data dictionary. This dictionary can accept any keys and values that can cast to strings. Each error generates a two-column table of information, built using this dictionary. The keys are displayed in the first column and the values are displayed in the second. Note that VTScada system code typically uses Setup.INI values to generate these strings so that they can be changed to suit different languages, but this is not a requirement.

UserAndSession
Optional. This parameter should capture the user responsible for the operation that lead to the error. This is required since users are linked to sessions that are only available to modules ultimately called by the Display Manager (that is, GUI objects). As a result, the "user and "session" often need to be captured earlier and passed to any modules likely to generate errors.
Silent
Optional Boolean. If TRUE, the error dialog will be suppressed. Defaults to the application property, ReportErrorSilenceAll, or FALSE if not otherwise set.
HelpFile
Optional text. If the dialog is to have a help button, and you are using a custom help file, provide its name here. May be left blank if you are using the VTScada help file.
HelpID
Optional numeric. If the dialog is to have a help button, provide the ID value from the help file's Alias file to link to the correct topic.
TraceCategory
Optional. The category to use in the VTScada Trace program.
ApplicationGUID
Optional text. Defaults to the current application's GUID. In the rare case where there can be ambiguity over which application caused the error, a GUID may be supplied for the source application.
Comments:

If this function displays the error message to the operator, it will use the newer format, which was introduced in VTS 10.0. This format enables you to display multiple error messages in one screen, each with its own Help ID value.

The error will be recorded in the Error Log file at the VTScada level, as well as being stored for use by the TraceViewer. The log file ("errors.log") records every error that is raised via ReportError.

Examples:

IfThen(PickValid(!Bit(VarAttributes(FindVariable(VarName, TagMod, 0, 0)), 8 {Temporary}), FALSE),
{ A non-temporary variable of a disallowed name was present.  Produce an error. }
  ErrorInfo = Dictionary();
  ErrorInfo[\System\GetPhraseForLang("TypeNameLabel", \System\ErrorLang)] = Cast(TagMod, \#VTypeText);
  ErrorInfo[\System\GetPhraseForLang("VariableNameLabel", \System\ErrorLang)]        = VarName;
  ErrorInfo[\System\GetPhraseForLang("IncompatibleVersionLabel", \System\ErrorLang)] = Ver;
  ReportError(\System\GetPhraseForLang("BadTagVariableErr", \System\ErrorLang), ErrorInfo, Invalid, 0, DlgHelpFile, 12009 { HelpID 12009 });
);

Related information:

|


RepoSubscribe

Description: | Allows the caller to specify a callback which will be triggered whenever the application’s repository changes
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | WCSubscribe |
Format: | RepoSubscribe(Subscriber[, Callback])
Parameters: |
Subscriber
Required. Scope of the destination for the published messages.
CallBack
Optional. Name of the module to call in the Subscriber when something is published. If invalid, this will default to "RepoNotify".
Comments: The callback is provided with a dictionary of the changed files.
Note that since these changes may not be reflected in the working copy (and therefore not affect the application) the WCSubscribe function is recommended in most cases.

Examples:


RequestToken

(Control Token Manager)

Description: | Requests a Control Token for a tag.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | (Control Token Manager)
Related to: | CanControl (Control Token Manager) | CanDenyTokenRequest | CanGrantTokenRequest | CanReleaseToken | CanRequestToken | DenyTokenRequest | GetToken (Control Lock Module) | GetTokenLevel | GrantTokenRequest | ReleaseToken | RequestToken |
Format: | \ControlTokenManager.RequestToken(TagID, Level[, Auto, Custom, Timestamp, SessionID, AccountID, MachineID, Device])
Parameters: |
TagID
Required string. The UniqueID of the tag for which a token request is to be made.
Level
Optional numeric. The priority level of the token request. Defaults to 1.
Auto
Optional Boolean. Set to TRUE if the request is automatic and to FALSE if the request is manual. Defaults to FALSE.
Custom
Optional structure. A set of custom fields to log. Must be packed.
Timestamp
Optional timestamp. The UTC time of the request. Defaults to current time.
SessionID
Optional. The ID of the session adding the token. Relevant only if token ownership is tied to sessions.
AccountID
Optional. The ID of the user requesting the token. Defaults to the signed in user at the current workstation.
MachineID
Optional. The MachineID of the workstation where the request was made. Relevant only if token ownership is tied to workstations.
Device
Optional. The IP address of a Thin Client device.
Comments:

Token ownership is affected by the value of the property, ControlTokenOwnerMode.

Manual refers to user action while Auto refers to ControlTokenManager / VTScada action

To provide the ability to control the entire tag tree, a fictitious ‘Root Tag’ is declared in the ControlTokenManager. The syntax to use this would look similar to:

\ControlTokenManager.RequestToken(\ControlTokenManager.RootTagID, Level)

This can also be configured in a Request Button widget. The Root Tag name and area can be changed by adding ControlTokenRootTagName and ControlTokenRootTagArea properties.


Reset

(VoiceTalk Module)

Description: | Immediately stops a speech stream and cancels any buffered speech.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Speech and Sound
Related to: | Configure | GetDevices | GetVoices | ShowLexicon | Speak | VoiceTalk
Format: | VoiceTalkStream\Reset
Parameters: |
VoiceTalkStream
Required. A speech stream returned from VoiceTalk.
Comments: This function returns the error code resulting from issuing the command to the speech engine, or zero if no error was encountered.
Issuing this command will immediately stop all speech for the stream on which it was issued. Other streams will be unaffected. Note that in the process of stopping the speech, a new speech request is issued, so the count of queued VoiceTalk\Speak requests will momentarily increase by one.


ResetParm

(Engine-Level Function)

Description: | Can reset parameters that become latched.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | NParm | Parameter | PType
Format: | ResetParm(Object, Index)
Parameters: |
Object
Required. Any object (the object value of a running module instance).
Index
Required. Any numeric expression giving the number of the parameter of interest, starting from 1.
Comments: This statement is for experienced users, and is not needed for normal operation. When this function executes, it attempts to reset Object's parameter at Index. This allows modules to be written which reset their parameters (like the Save statement). This function is useful for resetting TimeOut and MatchKeys functions.


ResultFormat

(ODBC Manager Library)

Description: | Subroutine to convert 2-d array as returned from query in the form, Arr[Field][Rec], to a normalized format of Arr[Rec][Field]. For single record reads, this function returns a single dimension array Arr[N] where N is the number of fields.
Returns: | Array
Usage: | Script Only.
Function Groups: | ODBC
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat StatsWin | TableSynch | Transaction | TransactionCached
Format: | \ODBCManager\ResultFormat( DataArray, MakeSingle )
Parameters: |
DataArray
Required. An array of fields and records to transpose
MakeSingle
Required. If true (1), and if the array size is 1 this indicates that the a single dimension array should be returned.
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.

The only way to ensure that a long running (or faulty) query does terminate is to set appropriate values for both the parameters ExecutionTimeout and UseDriverTimeout. Modules executing queries are designed to be run as launched modules and will remain active until complete.


ResyncDoc

(Engine-Level Function)

Description: | Synchronizes the time and date for the document and .RUN files.
Warning: | This function should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, File I/O, Advanced Module
Related to: | CanEditDoc
Format: | ResyncDoc(Module [, Unsync])
Parameters: |
Module
Required. Any expression for the module or object value.
Unsync
An optional parameter that is any logical expression. If true (non-0), the module's .RUN file(s) are forced to be out of sync with the time stamp on its .SRC file(s). If false (0) the .RUN and .SRC files are synchronized. The default is 0.
Comments: This function will set the date and time for the .RUN file to that of the document file.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


Return

(Engine-Level Function)

Description: | Sets the return value for the module in which it is executed.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Basic Module
Related to: | GetReturnValue | Launch | Slay | SetReturnValue
Format: | Return(X[, Resettable])
Parameters: |
X
Optional. Any variable, expression, constant or object value. It can be of any type.
Resettable

Optional Boolean. Defaults to TRUE.

If present and set to FALSE, the return value will not reset to INVALID until another Return statement specifies otherwise.

Read the following comments before deciding which is appropriate for your code.

Comments:

Return(); is equivalent to Return(Invalid);

Use in Launched Modules / Subroutines

If a Return statement appears anywhere in the code of a launched module (i.e. one that is executed inside of a script or using the Launch statement), even if that portion of the code is not executed, the module will be considered to be a called module, and will block execution of all other modules in the same thread while it is executing.

Execution of the Return statement in a subroutine results in the module being slain without having to use the Slay statement.

Use in Called Modules

If the Return statement is used in a called module (one that appears as a statement in a state), execution of the Return statement will not stop the execution of the calling module.

The return value for the module is set equal to the first parameter, and is the same type as the expected value of the module call. The type of the return value is set every time Return is executed, which allows modules to return different types of values during execution if they are called (rather than launched).

This statement may appear inside or outside of a script, and like other statements that may be called from a state, if multiple calls are active simultaneously in a module, the return value will be invalid.

WARNING 1: Latching Behavior and If statements

If the Return statement is placed within a script block of a called module, and if that module is called by an If statement, then the return value will be reset to Invalid after the If statement executes. This is similar to the behavior of latching functions such as AbsTime() and Watch(). See example 2.

This behavior is not desirable for some called modules. The same goes for some modules that set their return value from script using SetReturnValue. Steady-state modules designed to avoid initial Invalid returns should invoke return functions with Resettable set to FALSE.

Warning 2: Returns, Constructors, and Invalids

If your module is being run as a subroutine and has a constructor, VTScada will return the value set by the constructor.

The return value of a callable module is usually Invalid initially. It is risky to watch for !Valid(CalledModule()) to indicate "Done".

In a called module with a constructor, the first state cannot have a steady-state Return statement, because if it did, the constructor's SetReturnValue would be considered a double-set and would return Invalid. You might move the Return to a script within the first state as follows.

SubReturn [
  If 1 Switch;
  [
    Return(GetReturnValue(Self), FALSE);
  ]
]

If the point is only to monitor for the return value of a callable module as a signal, a more reliable method is to use a previously declared variable.

Example 1:

Main [ { State in Module Graphics }
  ZText(500, 100, test , 15, 0);
]
< { Submodule of Module Graphics }
Test
State1
[
  Return("example of return function");
]
>

This sets the return value of the module Test to "example of return function" which is displayed by the ZText statement in state Main of the Graphics module.

Example 2:

[
  Count = 0;
  XorYPressed Module;
]

Main [
  If XorYPressed();
  [
     { When this script executes, the return value of XorYPressed resets to Invalid }
    Count++;
  ]
  ZText(100, 100, Concat("X or Y was pressed ", Count, " times"), 12, 0);
]

<
XorYPressed

Main [
  If MatchKeys(1, "x") || MatchKeys(1, "y");
  [
    Return(TRUE);
  ]
]
>


Reverse

(Engine-Level Function)

Description: | Returns its parameter with the byte order reversed.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | BuffOrder
Format: | Reverse(Type, Value)
Parameters: |
Type
Required. Any numeric expression giving the type of the Value parameter.
Type | Meaning
1 | Short
2 | Long (32-bit Integers)
3 | 64-bit Integers
4 | Text
Value
Required. Any variable, expression, or constant. It can be of any type except object.
Comments:

If Value is invalid, the return value is invalid.

For type 1, after the bytes are reversed, the result is stored as a 16-bit short integer. If you want an unsigned short for the result, you must AND() it with 0xFFFF. For type 2, the result is stored as a 32-bit signed integer. If you want an unsigned 32bit integer, you must AND() it with 0xFFFFFFFF. For type 3 it is stored as a 64-bit signed integer.

Example:

oldA = 45 { 0b00000000 00101101 };
oldB = "Hello";
newA = Reverse(1, oldA);
newB = Reverse(4, oldB);

The value of newA will be 11 520 which is 0b00101101 00000000. NewB will have a value of "olleH".


RibbonCmd

(Engine-Level Function)

Description: | Provides two variables that the ribbon will set when the user activates a command
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Window
Related to: | RibbonContextUI | RibbonGalleryItems | RibbonPersistState | RibbonSetProperty
Format: | RibbonCmd(CommandID, CommandData)
Parameters: |
CommandID
Required. A variable holding the unique identifier for the activated command.
CommandData
Required. A variable holding any command-specific data.
Comments: The return value of this function can be monitored to initiate script execution when the user activates a ribbon command.

Examples:

IF RibbonCmd(CommandID, CommandData);
[
  ...
]


RibbonContextUI

(Engine-Level Function)

Description: | Displays a mini-toolbar or a pop-up context menu or both at a specified window coordinate.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Window
Related to: | RibbonCmd | RibbonGalleryItems | RibbonPersistState | RibbonSetProperty
Format: | RibbonContextUI(CommandID, X, Y);
Parameters: |
CommandID
Required. The unique identifier of the command.
X
Required. Horizontal coordinate within the nearest window at which to display the pop-up.
Y
Required. Vertical coordinate within the nearest window at which to display the pop-up.
Comments:

UI == user interface.

A context map is an XML declaration of the user interface controls. The XML can hold multiple context maps and therefore, it is possible to select from multiple, pop-up user interfaces to display.


RibbonGalleryItems

(Engine-Level Function)

Description: | Use to populate a gallery with a collection of items or commands, from which the user may make a selection
Returns: |
Usage: | Script Only.
Function Groups: | Window
Related to: | RibbonCmd | RibbonContextUI | RibbonPersistState | RibbonSetProperty
Format: | RibbonGalleryItems(CommandID, GalleryItems);
Parameters: |
CommandID
The unique command identifier of the gallery.
GalleryItems

A structure containing two members:
Categories - A one-dimensional, ordered array of category labels. Each member of the Items array belongs to a category, identifying its category by the index into this array. The categories are displayed as headings within the gallery. If there are no categories, this member must be Invalid.

Items - A one-dimensional, ordered array of RibbonItem structures. Each entry in the array represents an item or command in the gallery. These are displayed in the same order (within their category) as they appear in this array.

RibbonItem structures are described in the comments section.

Comments:

A RibbonItem structure has the following members:

Member | Content
Category | The category number of the item or command. Mandatory. If the item does not belong to a category you must specify Invalid here. Failure to do this can result in undefined behavior, such as missing items if the gallery is added to the quick access toolbar.
Label | The text label to display for the item or command. Optional.
Description | The text description to display for list of most recently used (MRU) entries only. This is displayed as the one-line tooltip for an MRU entry. Optional.
Image | The image to display for the item or command. Any VTScada-supported image can be supplied as a bitmap value. Optional.
CommandID | For command galleries only, the unique command identifier of the command to represent.
CommandType | For command galleries only, the type of command. This controls how the command will be represented in the gallery.


RibbonSetProperty

(Engine-Level Function)

Description: | Set a property on a command. A ribbon control will access those properties of a command that it needs to render itself and respond to user interaction.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Window
Related to: | RibbonCmd | RibbonContextUI | RibbonGalleryItems | RibbonPersistState
Format: | RibbonSetProperty(CommandID, Property, Value);
Parameters: |
CommandID

Required. The unique identifier of the command.

If set to zero, the property and value are applied to all elements of the ribbon, allowing all to be disabled or enabled with a single call.

Property

Required. An integer from the table that follows.

Value
Varies according to the property being set.
Property Value | Property Meaning | Value Type
0 | Enable/Disable the command. If the command is disabled, all control representations of the command will be rendered grayed and the user will be unable to activate the command. | Boolean: 0 (Disable). 1 (Enable)
1 | Boolean value of the command. For example, a command intended to be represented by a toggle button or check-box would have Boolean value. | Boolean
2 | Numeric value of the command. Commands represented by a combo-box or spinner control use numeric values. | Integer or double
3 | String value. Commands represented by controls that display a string value use this to provide the value. | Text
4 | Minimum value. Commands represented by a spinner control use this to regulate the minimum value the user can select. | Integer or double
5 | Maximum value. Commands represented by a spinner control use this to regulate the maximum value the user can select. | Integer or double
6 | Label. The label displayed by a control that has a textual representation of the command, for example the text next to a button. | Text
7 | Description. The description displayed by a control that has a long textual description of a command, for example, a "MajorItems" button in a DropDownButton control. | Text
8 | Tooltip Title. The emboldened title displayed in a tooltip. | Text
9 | Tooltip Description. The textual description displayed in a tooltip. This is not emboldened and is displayed below the tooltip title (if any). | Text
10 | Key tip. Text that is displayed to assist the user when a key combination is bound to the key, e.g. "F9" or "Alt+U". | Text
11 | Small Image. The small (?x?) image displayed by a control. | Image (see comments)
12 | Large Image. The large (?x?) image displayed by a control. | Image
13 | Color. An RGB quad value for a command that is intended to be represented by a color picker control. | Integer
14 | Color Type. An enumerated type for use by a command that is intended to be represented by a color picker control. Normally used in conjunction with the Color property. | Integer as follows: 0 == no color 1 == automatic color 2 == RGB color value
15 | Selected Item. Used for item galleries to force a specific item to be drawn as selected. | Integer
16 | Context Available. Commands whose representation is a contextual tab group have their visibility controlled by this. | Boolean
17 | Font. Commands represented by a font selection control have the values for the fields in the font control set by this property. | A font command structure
18 | Representative String. Supply a string for combo-box or spinner controls to set their width. The string will be used to measure how wide the control will be. | Text
19 | Increment. For spinner controls, the increment or decrement applied when the up or down arrow buttons are clicked. | Integer or double
20 | Decimal places. For spinner controls, the number of decimal places displayed. | Integer
Comments:

Note that setting a property on a command affects all controls that use the changed property of the command.

Images displayed on buttons and other controls that accept images can be defined by the XML markup or via script code.

Images supplied via markup are restricted to Windows .BMP 32-bit ARGB format for supported Windows systems up to and including Windows 7. From Windows 8, .PNG are also supported.

Images supplied via script code can be of any image type supported by VTScada and are internally converted to the appropriate type for the ribbon.

Image size can be hard to define. The exact image size expected by the ribbon framework depends on the resolution the display device is set to. There are two image sizes used by the ribbon, denoted as Large and Small, as follows:

Display resolution(DPI) | Small Image size (pixels) | Large Image size (pixels)
96 dpi | 16x16 pixels | 32x32 pixels
120 dpi | 20x20 pixels | 40x40 pixels
144 dpi | 24x24 pixels | 48x48 pixels
192 dpi | 32x32 pixels | 64x64 pixels


RmDir

(Engine-Level Function)

Description: | Destroys a directory on a disk and returns its own error code.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | File I/O
Related to: | MkDir
Format: | RmDir(Name [, DelAll])
Parameters: |
Name
Required. Any text expression that is the full path name of the directory to delete. A known path Known Path Aliases for File-Related Functions may be provided in the form, :{KnownPathAlias}.
DelAll
An optional parameter which, when set to 1, causes all files and sub-directories of the named directory to be deleted. Default: 0
Comments:

The return value is 0 if successful and a negative integer otherwise.

If a file lock interferes with the operation, RmDir will make 10 attempts, 100ms apart, allowing time for a temporary lock to clear.

If DelAll is not set to 1 and if the directory contains files or subdirectories, then the directory will not be deleted.

If Name is given as a relative path, then VTScada will look for that directory starting in whatever directory holds the module that is making the RmDir call. Thus RmDir("Sample"), run from within an application that is located in the directory C:\VTScada\MyApp, will remove the directory C:\VTScada\MyApp\Sample.

Note that this behavior differs from that of the MkDir function.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

err = RmDir("C:\Sample");

If possible (permissions permitting), directory Sample on the C drive will be deleted and err will be set to 0. If unsuccessful, err will be -1.


RootTransform

(Engine-Level Function)

Description: | Returns the object value that contains the root transform applied to the given module.
Returns: | Object
Usage: | Script or steady state.
Function Groups: | Advanced Module, Graphics
Related to: | GUITransform | UnTransform
Format: | RootTransform(Object)
Parameters: |
Object
Required. Any expression which returns an object value. This is the object value for which the root transform is being sought.
Comments: The return value may be the same as Object if Object contains the transform.

Example:

transMod = RootTransform(Self());


RootValue

(Engine-Level Function)

Description: | Retrieves the root value from a dictionary. This function will always attempt to return a value that is not itself a dictionary. If the value stored as the root of the given dictionary is also a dictionary, this function will return the root value from that second dictionary. Should all root values be other dictionaries (which would imply that the dictionary at the end of the chain must actually be an earlier dictionary) then RootValue will traverse the chain until it finds a root value which is an earlier dictionary (i.e. the end of the chain before it loops back) and will return that root value. This is the only situation where the command will return a dictionary as the result.
Returns: | Varies
Usage: | Script or steady state.
Function Groups: | Dictionary, Variable
Related to: | Dictionary | MetaData
Format: | RootValue( dictionary );
Parameters: | Dictionary | MetaData | DictionaryCopy | DictionaryRemove | GetNextKey | GetKeyCount | HasMetaData | IsDictionary | ListKeys
Dictionary
Required. The name of the dictionary to find the root value of.

Example:

RVAL == 5;

A[0] has a unique relationship with Root Values.
If A[0] is first used as a typical key with an assigned value it will behave like a key with a value forever. The value can be changed by assigning a new value to A[0] and is unaffected by anything else.
If A[0] is first assigned a Root Value it's behavior will change. A[0] becomes a variable with Meta Data. The value can be changed by assigning a new value to A[0] OR A[""] OR by using RootValue().

The order of operations matters.
If you set
A[0] = 7
A[""]= 6
and then
A[0]= 5
then A[0] AND A[""] will both equal 5.

However if you first set
A[""] = 6
and then A[0] = 5
then A[""] = 6 and A[0] = 5

Related information:

Dictionaries


RootWindow

(Engine-Level Function)

Description: | Returns the object value of the root (original) module displayed in the same window.
Returns: | Object
Usage: | Script or steady state.
Function Groups: | Basic Module, Window
Related to: | ParentWindow | Window
Format: | RootWindow(Object)
Parameters: |
Object
Required. Any expression that returns an object value. This is the object value where the search starts for the root window.
Comments: The return value may be the same as Object if Object is the root module of its window.
For modules in non-child windows (i.e. one without bit 9 set), RootWindow and ParentWindow will return the same value. For child windows, RootWindow will return the root module in the child window, while ParentWindow will return the root module in the child window's closest non-child calling window.

Example:

rootWin = RootWindow(Self());


Rotate

(Engine-Level Function)

Description: | Returns a Rotate value, which specifies a rotation about a point.
Returns: | Rotate
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Normalize | Point | Trajectory | Vertex
Format: | Rotate(Amount, MinDegrees, MaxDegrees, Center)
Parameters: |
Amount
Required. Any expression that returns a Normalize value, specifying how much to rotate.
MinDegrees
Required. Any numeric expression giving the minimum amount of rotation, in degrees. This is not a limit on the amount of rotation.
MaxDegrees
Required. Any numeric expression giving the maximum amount of rotation, in degrees. This is not a limit on the amount of rotation.
Center
Required. Any expression that returns a Point. This is the center point for the rotation.
Comments: The return value is a Rotate value, which specifies how to rotate about a point. It has a Normalize value, two angles corresponding to the low and high limits of the Normalize value, and a Point value which specifies the center of rotation. A Rotate value may be used in any layered graphics statement to make the statement rotate.

Example:

armRot = Rotate(Normalize(armEncoderPosition, 0, 100)
               { Amount of rotation },
               45 { Minimum rotation, in degrees },
               135 { Maximum rotation, in degrees },
               Point(50, 75, Invalid, Invalid)
               { Center point for rotation });

This specifies a rotation about the point (50, 75). If armEncoderPosition is 0, any object that uses this Rotate will rotate 45 degrees counter-clockwise about the point (50, 75). If armEncoderPosition is 100, any object that uses this Rotate will rotate 135 degrees counter-clockwise about the point (50, 75). If armEncoderPosition is any other value, the rotation will be by a proportional amount, not limited to the range 45 to 135 degrees.


RTimeOut

(Engine-Level Function)

Description: | Cumulative Timer. This function returns true when the total time that an expression is true reaches the specified value.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Time and Date
Related to: | AbsTime | Latch | TimeOut | Toggle | Save
Format: | RTimeOut(Enable, Time)
Parameters: |
Enable
Required. Any numeric expression giving the condition that results in the timer counting. When this parameter is true (not 0), the timer is "running."
When this parameter is false (0), the timer stops but the total time accumulated so far is maintained as the point which counting will start when the parameter becomes true again.
Time
Required. Any numeric expression giving the time-out limit in seconds. When the cumulative time that Enable is true reaches this value, the function becomes true (1).
Comments: This function is reset when either parameter becomes invalid or when the state containing the function is started. When the function is reset, counting starts at 0 and the returned value is false (0). Note that this function is reset automatically when it occurs in a true action trigger or function parameter of a function which resets its parameters after evaluation (e.g. Latch, Toggle or Save).

Example:

ZText(10, 10 { X-Y coordinates },
      Cond(RTimeOut(motorRunning, 28800),
                    "Check motor - 8 hrs running time accumulated",
                    ""),
      0, 0 { Black text in default font });

This statement displays a message when the variable motorRunning has been true (any non-zero value) for 28800 seconds (8 hours).

Related information:

Latching and Resetting Functions


RUNFileName

(Engine-Level Function)

Description: | Returns the name of the .RUN file for a module including the full drive and path.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, File I/O, Advanced Module
Related to: | ChildDocs | Dir | FileFind | ModuleFileName
Format: | RUNFileName(Module)
Parameters: |
Module
Required. Any expression for the module or object value.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

{ Find all modules including root; recurse in }
allMods = ChildDocs(Self(), 1 + 2 + 8);
numMods = ArraySize(allMods, 0);
{ Find the .RUN file names for all modules }
RUNList = New(numMods);
i = 0;
WhileLoop(i < numMods,
         RUNList[i] = ToUpper(RUNFileName(allMods[i]));
         i++;
);

This group of statements will result in the file names for all .RUN files for the current application being stored in the array called RUNList.


RUNFileVersion

(Engine-Level Function)

Description: | Returns the minimum version of VTScada that can read the .RUN files produced by the current version.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, File I/O, Advanced Module
Related to: | Version
Format: | RUNFileVersion( )
Parameters: | None

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

ZText(10, 10, Concat("Minimum version to read .RUN files is ",
RUNFileVersion()), 0, 0);

This statement will display the .RUN file version in the upper right corner of the window along with a comment about what the number represents.


RunInBubble

Description: | Starts a new thread in the given child bubble and launches the given module into that script thread.
Returns: | Boolean. See comments.
Usage: | Script Only.
Function Groups: | Bubbles and Threads
Related to: | Bubble |BubbleList | BubbleQueueLength |BubbleReceive | BubbleSend
Format: | RunInBubble(BubbleHandle, ThreadName, ModuleOrObject[, ImportDictionary, RetainedPath])
Parameters: |
BubbleHandle
Required bubble handle. A handle as returned by the Bubble and BubbleList functions. Specifies the bubble where the ModuleOrObject will be loaded and launched.
ThreadName
Required text. The name given to a new script thread that is started in the bubble. These names generally only appear in the user interfaces of debugging tools.
ModuleOrObject
Required. The root module that is loaded and launched into the bubble. It is always loaded and launched with no parent or caller.
ImportDictionary

Optional. If provided, a dictionary passed into this parameter allows the caller to specify a subset of variables, modules or both from the ModuleOrObject parameter that will be loaded, launched, or both, into the child bubble rather than simply loading and launching the entire module. This is of particular use when you want to be able to share the same code between modules running inside and outside of the child bubble.

A complete description of this parameter is provided in the Bubble function.

RetainedPath

Optional path to store retained values for all modules loaded in the bubble. By default, the retained path of the imported root module is used.

Caution: If bubble is using retained values, RetainedPath must be unique or the file may get corrupted if accessed inside and outside the bubble.

Comments:

Returns TRUE if the module data was successfully transferred to the bubble. Returns FALSE otherwise, either because it was called with invalid parameter values or because the bubble specified in the given handle has already shut down.

This function loads and launches modules in the same way as the Bubble function.

Example:

{ A simple single-module RunInBubble call to get the VTScada memory use
of a given bubble: }

<
GetBubbleMemory
(
  BubbleHandle;
  pMemoryUsed;
)
[
  BubbleMemoryWorker Module;
  MemoryUsed;
]

Init [
  If 1 WaitForResult;
  [
    BubbleHandle = Bubble("GetBubbleMemory", \BubbleMemoryWorker {use backslash to avoid implicit launch});
  ]
]

WaitForResult [
  If ReceiveBubbleMessage(MemoryUsed, BubbleHandle);
  [
    *pMemoryUsed = MemoryUsed;
    Slay();
  ]
]

<
BubbleMemoryWorker

Main [
  If 1;
  [
     { Send the parent bubble the result. }
    SendBubbleMessage(Memory());
    Slay();
  ]
]
{ End of GetBubbleMemory\BubbleMemoryWorker }
>
{ End of GetBubbleMemory }
>


RunPack

(RPC Manager Library)

Description: | Unpacks and executes a set of RPCs from a stream constructed with PackRPC.
Returns: | Text
Usage: | Script Only. (Subroutine call only)
Function Groups: | Advanced Module, Network, Stream and Socket
Related to: | PackRPC
Format: | \RPCManager\RunPack(Stream [, Service]);
Parameters: |
Stream
Required. A packed RPC stream obtained from one or more PackRPC method calls.
Service
The name of the service to be used to determine root scope for the RPCs within Stream. Invalid for non-service RPCs. If valid, the RPC subroutines specified in the package will be searched for starting in the scope of the service instance of the machine on which the RunPack() RPC is executing.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

Related information:

RPC Manager Service


S Functions

The sections that follow identify all VTScada functions beginning with "S".


Save

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | This threaded function stores data in a circular historical data file at times indicated by a condition and returns the record number last written to disk.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | File I/O
Threaded: | Yes
Related to: | Save | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords | Get | GetHistory | GetLogInfo | SaveHistory | TGet
Format: | Save(NStatus, NByte, NShort, NLong, NFloat, NText, TSize, Records, Buffers, File, Trigger, V1, V2, ...)
Parameters: |
NStatus
Required. Any numeric expression giving the number of status type values to store in the file. Any functions used in this parameter must be able to be executed in a script, since triggering of the Save re-evaluates it as if it were in a script.

Status types must be equal to a 0 or a 1. This value must be greater than or equal to 0.
NByte
Required. Any numeric expression giving the number of values that are only one byte long. Any functions used in this parameter must be able to be executed in a script, since triggering of the Save re-evaluates it as if it were in a script.

Byte types must be in the range 0 to 255 inclusive. This is a subset of the short type but require 50% less file space than short values and 75% less space than either long or float values. This value must be greater than or equal to 0.
NShort
Required. Any numeric expression giving the number of short type values to store in the file. Any functions used in this parameter must be able to be executed in a script, since triggering of the Save re-evaluates it as if it were in a script.

This value must be greater than or equal to 0.
NLong
Required. Any numeric expression giving the number of long type values to store in the file. Any functions used in this parameter must be able to be executed in a script, since triggering of the Save re-evaluates it as if it were in a script.

This value must be greater than or equal to 0.
NFloat
Required. Any numeric expression giving the number of float type values to store in the file. Any functions used in this parameter must be able to be executed in a script, since triggering of the Save re-evaluates it as if it were in a script.
This value must be greater than or equal to 0.
NText
Required. Any numeric expression giving the number of text type values to store in the file. Any functions used in this parameter must be able to be executed in a script, since triggering of the Save re-evaluates it as if it were in a script.

This value must be greater than or equal to 0.
TSize
Required. A short constant giving the number of characters to reserve for text values. Text values that are longer than this number will lose the characters that fall beyond this limit. All text values stored will have the same size.
Records
Required. Any numeric expression giving the number of entries in the file. If the file is to be created full size (to prevent fragmenting of the file as it grows larger), the size should be multiplied by -1.
Because the file is circular in nature, after this number of records have been written, new records will overwrite old ones, beginning with the oldest record in the file.
Buffers
Required. Any numeric expression for the number of records to keep in memory (RAM) before writing to disk. A value of 0 will result in the data being directly written to disk each time Trigger is true. Setting the buffer to large numbers speeds the average data logging rate substantially but requires RAM equal to the number of records specified by Buffers.
When the RAM buffer is full the entire buffer is written to disk. If the buffer size is changed or if the Save is stopped (such as when VTScada stops), any data in the buffer is immediately written to disk.
Also, if a Get is executed, any data in the buffer will be immediately written to disk, so that the user in ensured of getting all current data.
Normally when Save stops, a record with all invalid fields, and the current time and date stamp, is written to the file. This indicates that data are no longer logged, and fields are unknown until Save resumes. If Buffers is negative, this invalid record is not written, and the number of buffered records is -Buffers - 1. This is to remain compatible with prior versions of VTScada.
Be aware that any data held in a RAM buffer will be lost if VTScada is not correctly stopped (for example, a power failure).
File
Required. Any text expression giving the file name for the historical data. Any path name, including any special, remote, and networked drive is allowed. The default extension is ".DAT" and the default path is the current application path (where VTScada was started). If the file name is prefixed with a period, the path will be to the directory the module is contained in.
Trigger
Required. Any resettable function whose transition from false to true indicates the data items V1, V2, ... are to be written to the file. The Save statement resets the Trigger parameter if the Trigger is true (not 0).
V1, V2, ...
Required. A series of expressions which give the values to be stored in the file. The parameters must be in the order: status, byte, short, long, float, and text. The number of each type is given by the NStatus, NByte, NShort, NLong, NFloat and NText parameters.
There must be exactly the number of Vn parameters specified by each of these parameters.
Comments: This function returns the record number last written to disk. Because this function is threaded and runs as a background job, this value can be used to determine when data have actually been written by examining the change in the return value.
This function creates the historical data file when it is entered during configuration. If the file already exists and is of a different format than specified by the statement, the program automatically converts the file to the new format. This conversion will result in data loss if the number of values of any type is reduced. For example, if NStatus is reduced from 16 to 12, the last four status parameters stored in the file before the change will be lost. If a value type number is increased or remains the same, no data will be lost.
When a Save function is triggered, the next buffer is filled. When the number of filled buffers equals the value implied by the parameter Buffers the file is opened, written, and then closed. This allows a file to be logged to a network server, and read by other VTScada applications on the network. The VTScada NetBIOS I/O driver is not required for this type of network communication. All that is required is a network redirector.
If a file is referenced by two or more active Save functions, there will be unpredictable results, with a possibly corrupted file and reduced performance. Do not reference the same file from more than one Save function at the same time. This is not the case with a SaveHistory, Get or TGet statement. Any calls to SaveHistory will result in data being written to the file in the correct location based on its timestamp. When a Get or TGet is executed, the Save statement will write all of the data that it holds in memory to the file prior to the data retrieval. This also occurs if the application is stopped.
The values of the Vn parameters need not be valid for the Save statement to operate. Any invalid values are recorded as such in the file. The data are stored in the file in the order given by the Vn parameters. This order is important for retrieving the data using the Get statement.
Note that the Trigger parameter is reset when it becomes true. This means that data can be saved at regular time intervals by using TimeOut or AbsTime as the trigger. After TimeOut becomes true, the timer will be restarted by the Save statement. Change can also be used in Trigger to cause data to be stored when data values change by a given amount. The starting point for the Change function will be reset after the Trigger becomes true and the data are stored.

The size of the file can be calculated as follows:

Record *
Ceil(Ceil((NStatus + NByte + NShort + NLong + NFloat + NText)/8) +
Ceil(NStatus / 8) + NByte + 2 * NShort + 4 * NLong + 4 * Nfloat +
(TSize + 2) * NText + 8)
+ 25

For example, if the Save statement was as follows :

Save(3, 1, 4, 0, 6, 1, 24, 10000, ...

The file size in bytes would be :

10000 * (Ceil((3 + 1 + 4 + 0 + 6 + 1) / 8) + Ceil(3 / 8) + 1 +
2 * 4 + 4 * 0 + 4 * 6 + (24 + 2) * 1 + 8)
+ 25
= 10000 * (Ceil(15/8) + Ceil(0.375) + 1 + 8 + 0 + 24 + 26 + 8)+ 25
= 10000 * (2 + 1 + 67) + 25
= 700,025 bytes

The size of the files generated by Save must be considered so the available disk space is not exceeded. Note that the files grow as data is recorded up to a maximum of the calculated size. To prevent fragmenting of the file as it grows over time, it may desirable to create the file full size, by making the Records parameter negative.

It is good practice to create several log files of varying frequency. For example, you may want to log data to a file every second for a week. This will be a very large disk file - the minimum size is 6 megabytes! To load a week's data into an array using a Get statement could take several minutes (depending on the computer), during which VTScada will do nothing but process disk information (this is because VTScada is a non-preemptive multitasking system). Also, most screens have only 640 to 1024 pixels across. Displaying 604800 plot points on a VGA screen will be displaying approximately 1000 data points using 1 plot point - not very efficient or easy to read.

The solution is to record two (or more) separate files. One will be a large file recording data every second for a week - this will be used to look at a few minutes at a time. Another file would record hourly averages (or minimums, maximums, etc.) for a week (168 items) - this will be used to look at the entire week. Variations on this strategy, using a variety of log rates will provide the best solution to your data logging problems, both in disk space and processing time.

Another way to decrease logging frequency is using a Trigger based on Change, if the values logged to the file change significantly only rarely.

File Format:The standard file format for Save files is a 38 byte header, followed by identical format records (as specified by the parameters). The header contains the following information:

Bytes

Size

Description

0-1

Int

Number of status values

2-3

Int

Number of bytes values

4-5

Int

Number of short values

6-7

Int

Number of long values

8-9

Int

Number of float values

10-11

Int

Number of text values

12-13

Int

Text size

14-17

Long

Maximum number of records in file

18-21

Long

Index of next record to write

22

Byte

Bits | Meaning
0 | File has not wrapped around
1 | File has wrapped around
2 | File has not wrapped but was created full size
3-5 | File format version
6 | Checked flag. This bit is set when the file has been checked for inconsistent timestamps. If this file is opened by the Save, SaveHistory, or the ValidateHistory function, the invalid record is updated, and the bit is set.
7 | Clean flag. This bit is cleared whenever data is written to the file by the Save, SaveHistory, or ValidateHistory function. When the Save function is stopped, the invalid record is updated, and the bit is set. If the file is opened by the Save, SaveHistory, or ValidateHistory function, the bit is checked, and if not set, the invalid record at the end of the file is corrected

23-24

Int

Length of a record (in bytes)

25

Reserved

26-29

Long

Actual size of header

30-37

Double

A timestamp for determining the latest time for which valid data was written.

The first 8 items in the header are the values in the parameters of the Save statement that created the file. See the Save statement parameters for a more detailed description.

Bytes 18-21 are a long number that indicates where the next record will be written in this file. Record numbers begin at 0. To find the file offset (in bytes) where the next record will be written, multiply this number by the length of a record (in bytes), and add 25. Thus record 0 will be found at offset 25.

Byte 22 is a flag. If 0, the circular file has not been filled (the size of the file continues to grow). If 1, data have been overwritten and the last record index has "wrapped-around" to position 0 at least once.

Bytes 23 to 24 are an integer that specifies the length of a record in bytes.

Note that the size of the file header may be increased by using the SetLogHeader function, which will cause additional bytes to be added to the end of the header. Information may then be written to the header using an FWrite (or similar) function with a starting offset of 25. If the header size is to be expanded and written to, however, it is crucial that the Save statement not be active at the time, and also that the data written to the expanded header not exceed the size by which the header was increased. If either of these conditions is not met, the file will become corrupt and data may be lost.

25 Reserved

26-29 Long actual size of header in this file

30-37 Double a special timestamp value which, in the event that the file is not closed tidily, allows the latest time for valid data to be determined.

In addition, bits 3-5 of byte 22 have the value 1 to indicate the file format version.

Note that the size of the file header may be increased by using the SetLogHeader function, which will cause additional bytes to be added to the end of the header. Information may then be written to the header using an FWrite (or similar) function with a starting offset of 38. If the header size is to be expanded and written to, however, it is crucial that the Save statement not be active at the time, and also that the data written to the expanded header not exceed the size by which the header was increased. If either of these conditions is not met, the file will become corrupt and data may be lost.

Record Format:Each record consists of the following parts:

1. The first 8 bytes of each record are a double precision number in IEEE format, which indicates the time and date when the record was written, as the number of seconds since midnight on 1 January, 1970.

2. Next, 1 byte is allocated for each 8 data items in the record (or fraction thereof). The bits in each byte indicate whether each item is valid (1) or invalid (0).

3. Data items for the record are written sequentially. Each data type is written in a particular Format:1 byte is allocated for each 8 status items or fraction thereof. Each bit contains 1 status value.

Byte items are written as unsigned integers (1 byte each)

Short items are written as signed integers, low byte first (2 bytes each).

Long items are written as signed integers, low byte first (4 bytes each).

Float items are written in single precision IEEE floating point format (4 bytes each).

Text items consist of 2 + TextSize bytes each. The first 2 bytes indicate the number of meaningful data bytes to follow. All bytes beyond that number contain random data. The data bytes are not null-terminated. If, however, TextSize has the value 0, then this indicates that variable length text storage is required. In this case each text entry in the file has a fixed size of 10 bytes and the actual text is stored in a separate file which has the same root filename as the .DAT file, but has a .STR extension.

It should be noted that the Save statement accepts calculated values for its first six parameters. This allows a more efficient generic data logger to be written. The parameters to be logged are treated as if they were in a script so that the changes to these values do not retrigger the Save (thereby saving time and RAM, since this retriggering is always redundant). The Save statement treats assignments in the first six parameters (which is very rare), so that they will only be executed when the Save trigger becomes true. Only expressions that are allowed in scripts are permissible for the first six parameters.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

Save(1 { Number of status values },
     0, 0, 0 { Number of byte, short, long values },
     numFloat { Number of floating point values },
     1 { Number of text values },
     32 { Size of text value },
     1152 { Number of records (4 days worth) },
     50 { Buffer 50 records before writing },
     "G:\DATA\REACTOR" { Path and file name (default .DAT) },
     AbsTime(1, 300, 0) { Save every 5 minutes },
     valveOpen { Status value },
     mixerTemp { First float value },
     inletTemp { Second float value },
     outletTemp { Third float value },
     coreTemp { Fourth float value },
     chemName { Text value });

This stores 1 status, NumFloat float and 1 text value to a file on G: (a shared network drive) in directory DATA called REACTOR.DAT. Only the first 32 characters of the text value chemName are logged. Values are logged every 5 minutes, and written to disk every 250 minutes (50 records). The number of records has been chosen based on the fact that we want to have exactly 4 days worth of data. This means that we need 4 * 24 * 60 / 5 = 1152 records in the file. Because it may also be important to know how large this file is, we can calculate the size as follows:

1152 records *
[ Ceil((1 status value + 4 float values + 1 text value) / 8) +
  Ceil(1 status value / 8) + 4 * 4 float values +
  (32 chars + 2) * 1 text value + 8
]
+ 25
= 1152 * (Ceil(6/8) + Ceil(1/8) + 16 + 34 + 8) + 25
= 1152 * (1 + 1 + 16 + 34 + 8) + 25
= 1152 * (60) + 25
= 69 145 bytes

Related information:

Latching and Resetting Functions


SaveFile

(System Library)

Description: | Helper function to save files or streams on a server, VIC or Anywhere Client
Returns: | Object reference to itself.
Usage: | Script Only.
Function Groups: | File I/O,
Related to: | BlockWrite | BuffStream | ClientSocket | CloseStream | FileStream | GetStreamLength | PipeStream | SRead | StreamEnd | SWrite
Format: | System.SaveFile(Input, Destination, MimeType[, DeleteOnCompletion, pResultPath, pCompletionVar, OpenFileDialog, FilterPattern, FilterDesc, FileExt])
Parameters: |
Input

Required. Input stream, file name or full path to file name to be saved.

Alternatively, may be a callback module that will write data. The callback module should be a launched module and may have two parameters. The first is required and must be a stream to which data will be written. The second is optional and typically called pAbortSave, which is a pointer to a value that the callback can set to TRUE if the SaveFile operation is to be aborted. If that flag is set, anything that has already been written to the file will be discarded. If the destination already existed, it's original contents will have already been deleted so pAbortSave cannot be used to stop that from happening).

Destination
File name or path to save to.
MimeType
Mime type to send to the Anywhere Client in "view" mode.
DeleteOnCompletion
Optional Boolean. Defaults to False. Delete input on completion. Applies only when using a file name as the Input parameter. Does not apply to a stream.
pResultPath
Optional pointer to output destination. The output destination can be a string of the resulting file name including its path if the user selected a file, or can be Invalid if the user canceled the selection or the session is running on the Anywhere Client.
pCompletionVar
Optional pointer to percentage completion of writing the stream to the VIC. Invalid for the Anywhere Client or server sessions.
OpenFileDialog
Optional Boolean. TRUE to open FileDialogBox. Defaults to TRUE.
FilterPattern
Optional. Array of wildcard file patterns for the file types that will be offered to the user.
FilterDesc
Optional. Array of text values that are the descriptions corresponding to the FilePattern values.
FileExt
Optional text expression giving the default file extension to use if the user does not specify one.
Comments:

When run on a workstation or VIC a "save as" dialogue will be displayed. After being accepted, the input file or stream will be copied to that destination. On the Anywhere Client a file download will be initiated.

If DeleteOnCompletion is true and the input is a file, it will be deleted when it is no longer required by System.SaveFile(). You are strongly advised to use this rather than other means to delete the input file after transfer. Otherwise, the file may be deleted before the transfer is complete.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

This will save "output.csv" to the location of a user's choosing, or when run on the Anywhere Client it will initiate a download of "output.csv".

If WinButton(20, 150, 140, 170, 0, "Make CSV", 1);
[
  Stream = BuffStream(Concat("name,value",   System.CRLF,
                      "example1, 111", System.CRLF,
                      "example2,222", System.CRLF,
                      "example3,333", System.CRLF));
  System.SaveFile(Stream, "output.csv", "text/csv");
]


SaveHistory

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | This threaded function saves an array of data to a .DAT file for a certain time span.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Array, File I/O, Log
Threaded: | Yes
Related to: | SaveHistory | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords | Get | GetHistory | GetLogInfo | Save | TGet
Format: | SaveHistory(Array2DElem, Num, File, [Mode], [PathPrefix], [EndTIme])
Parameters: |
Array2DElem
Required. Any array element giving the starting point into the two dimensional array containing the data to write to the file. The subscripts for the array may be any numeric expression, but both must be specified. The format of the array is the same as that returned by GetHistory: [column][record].

Column 0 is the timestamp in seconds since January 1, 1970, while each subsequent column is the data for that record in the same order used by the Save function that created the .DAT file.

Extra columns are ignored, but if there are fewer columns than required to specify all fields in the .DAT file then the function fails and does nothing.
Num
Required. Any numeric expression giving the number of records to write to the file.
File
Required. Any text expression giving the file name for the historical data file. If this file does not exist the SaveHistory function will create it with default format (see Comments). The file extension is optional and will default to ".DAT" if omitted.
Mode
Historical data files use an invalid record to mark discontinuities in the recorded data. Under certain circumstances, it may be desirable to manipulate these records. This optional parameter provides the mechanism to do so. The mode parameter has the following options: (Defaults to 0)
Value | Meaning
0 | Add data after the previous record according to time stamp, and don’t write an invalid record (default).
1 | No longer used
2 | Add data according to time stamp. If previous record is invalid, overwrite it, write data, and then write an invalid record after it.
3 | Perform a tidy closedown of a file which has been written with Mode = 2.
4 | Specifies that SaveHistory should perform a special merge of the supplied data into the referenced data file.

The aim of the special merge is remove invalid records unless the existing and the incoming data both agree that they should exist in the file. The aim of this mode is to assist the resolution of data at primary and backup log servers.

PathPrefix
An optional text expression parameter that enables and controls the retrieval of data from across a set of files.
EndTime
Specifies the end time range for a special merge (Mode = 4). EndTime is optional but may only be specified when Mode = 4.
If omitted or if a value of zero is used, then EndTime defaults to the last time stamp in the records supplied in Array2DElem.
Comments: Each record of data in the array will be inserted into its correct position based on its timestamp. For this reason the transfer to the file will be more efficient if the timestamps are in increasing chronological order, however, any order is allowed. Any records that have an invalid timestamp will be skipped. Because this function is threaded and runs as a background job, there is no way to tell when the data has all been written to the file other than by checking its contents, however, multiple Save or SaveHistory commands will get written to the file in correct locations based on their timestamps. If a Get or TGet statement is executed, the SaveHistory statement will write all of its data to the file prior to the data retrieval. This also occurs if the application is stopped.
If the target file does not exist, SaveHistory will create it. To do this, SaveHistory needs to determine the column structure of the file. Whereas Save has parameters allowing the format to be explicitly defined, there are no equivalent parameters to SaveHistory. Instead, SaveHistory will analyze the first record that is to be written and determine the parameter type required for each column. In order to ensure that the correct format is determined, it is advisable to make the first record a template record. A template record would have an invalid timestamp followed by column values that unambiguously identify the range of values for each column (see the Save function for a description of the data types). In the case of text values, the template string should be the same length as the maximum required length.

If Mode has the value 2, then the understanding is that a series of SaveHistory functions are to be performed on the file and that each will be written at the end of the file (if the write is not at end of file, then Mode = 0 is forced). The invalid record that is written at the end of the file identifies that the file is still (conceptually) open. Should the system suffer any form of abrupt shutdown, then this status will be preserved in the file and will be of use in learning the validity of file data. The final SaveHistory to such a file should be written with Mode = 3. This will change the invalid record to one which signifies that the file is no longer open.

If Mode has the value 4, then SaveHistory compares the data supplied in Array2dElem with the data already existing in the file, for the time range specified by the earliest record in the data and the value of EndTime.
The comparison reviews the validity of each record (a record is deemed invalid if all columns are invalid) and splits both sets of data into periods of validity and invalidity. The resulting file will contain all valid records from both data sets and those invalid records where both data sets saw an invalid.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


SaveImage

(Engine-Level Function)

Description: | Takes an image handle and saves it to an image file on disk.
Returns: | Handle to image
Usage: | Script Only.
Function Groups: | Graphics
Related to: | CaptureImage | MakeBitmap | ModifyBitmap
Format: | SaveImage(BitmapHandle, Filename, [MIMEType, Width, Height])
Parameters: |
BitmapHandle
Required. The handle to the image to be saved.
Filename
Required. Any text expression for the name to be given to the new file.
MIMEType
Optional text for the format to be used. Defaults to "image/png" if not specified.
Options include "image/bmp", "image/jpeg", "image/gif", "image/tiff", and "image/png".
Width
Optional. Any numeric expression for the width of the image in pixels. Defaults to the native size of the image.
Height
Optional. Any numeric expression for the height of the image in pixels. Defaults to the native size of the image.
Comments:

Examples:

SaveImage can be used in conjunction with ModifyBitmap. For example the following code snippet can be used on a VTScada application page (in script):

  SaveImage(ModifyBitmap(CaptureImage(Caller(Self())),
            FALSE  { Mirror },
            0 { Hue },
            Invalid { Saturation },
            Invalid { Lightness },
            Invalid { Transparency },
            Invalid { Contrast },
            Invalid { ColorizeHue },
            Invalid { ColorizeIntensity},
            TRUE    { AntiAlias }),
            "c:\temp\page.png", "image/png", 1000, 500);

To capture an image of the page, modify it to enable anti-aliasing so that high-quality interpolation will be used for the downsizing, and save it as a 1000x500 PNG.


SaveModule

(Engine-Level Function)

Description: | Saves a module definition to its *.RUN file.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: |
Format: | SaveModule(Module)
Parameters: |
Module
Required. Any expression for the module or object value.
Comments: This statement saves a module definition to its *.RUN file.


Scale

(Engine-Level Function)

Description: | Returns a value that has been converted from one scale to another.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | Normalize | Cond | Limit | Step
Format: | Scale(Value, In1, In2, Out1, Out2)
Parameters: |
Value
Required. Any numeric expression giving the value to be scaled.
In1
Required. Any numeric expression giving the minimum of Value's unscaled range. This parameter corresponds to Out1. This is usually the "zero" for the unscaled Value.
In2
Required. Any numeric expression giving the maximum of Value's unscaled range. This parameter corresponds to Out2. In2 must not equal In1.
Out1
Required. Any numeric expression giving the minimum of Value's scaled output range. This parameter corresponds to In1. This is usually the "zero" for the scaled Value.
Out2
Required. Any numeric expression giving the maximum of Value's scaled output range. This parameter corresponds to In2.
Comments:

This function may be used in combination with Cond to perform piecewise linearization of a value or expression. Limit may be used to keep the result within bounds.
The compiler will reduce this function to a constant if all of its parameters evaluate to constants.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Examples:

Suppose the top edge of a bar on the screen is to go from 10 to 527 for a corresponding process value change of -50 to +100. The scale function parameters would be :

Scale(Value, -50, 100, 10, 527);

It should be noted that the Value parameter need not remain within the range of In1 to In2 for the result to be valid. For example, to convert from Fahrenheit to Celsius temperature scales :

Celsius = Scale(Fahrenheit, 32, 212, 0, 100);

This means that 32 F = 0 C and 212 F = 100 C. If the temperature were outside the range of 32 to 212, the resulting Celsius temperature would still be correct.


Scope

(Engine-Level Function)

Description: | Performs a scope resolution and returns a reference to the requested member within a module or other object.
Returns: | Reference
Usage: | Script or steady state.
Function Groups: | Basic Module
Related to: | Variable | ScopeLocal | LocalScope
Format: | Scope(Object, Member[, ScopeLocal])
Parameters: |
Object
Required. Any expression for the object value (module) where Member may be found.
Member
Required. Any text expression for the member name. This must be a simple variable or module.
ScopeLocal
Optional. A Boolean expression. Defaults to FALSE if missing, invalid or if a non-Boolean is provided.
If set TRUE then the call will not search up the scope tree for name matches.
Comments:

This function is the same as the '\' operator, when the '\' operator is used between two operands. (Object\Member). Unlike the backslash operator, the Scope function allows any text string to be used.
This function may be used as a value, or as an L-value (on the left hand side of an assignment). This function is used to reference one specific occurrence of a variable in a module, from another module.
If the final result is Invalid, this function looks for the presence of backslash (\) characters in the second parameter and parses the result.
When searching for a match, this function ignores variables with the PROTECTED attribute. That is, if such a variable is encountered the search will simply skip over it and continue. Detecting variables with the PROTECTED attribute requires use of the 'Variable' function.

If you can use LocalScope instead of Scope, then you should. For example, perhaps you have a tag widget and want to draw range bars based on RangeMin & RangeMax. If you use \Root\RangeMax, and for some reason the tag linked to the widget does not have a RangeMax, then the Scope operator will walk up the scope tree, perhaps finding a RangeMax variable in a parent tag. It is likely that you would rather have an Invalid in that case rather than some parent tag's range value, therefore it is better to do \Root.RangeMax.

Example 1:

  Scope(\Code, "TagName");

Returns a reference to the given tag object.

Example 2:

Given the following tags:

MyContext
MyContext\IO_1
MyContext\Port1
MyContext\Port1\Driver1

If MyContext\IO_1 is configured to use MyContext\Port1\Driver1, the DeviceTag parameter will typically be set to "Port1\Driver1". The IO tag gets its driver tag as follows:

Scope(Root, DeviceTag);

That is, Scope(Root, "Port1\Driver1");

Operations inside the string other than backslashes are not supported. The local scope dot operator is not supported.

Using ScopeLocal. Given the following:

  Scope(\Code, "MyService\Ready");

The Scope operation will never find a variable called "MyService\Ready" in Code, but could find a variable called MyService containing a service object, which itself contains a variable called Ready. This Scope() would return the value of that Ready variable.

If the MyService object does not contain a variable called Ready, but Code does contain a Ready variable, then Scope will return the value of Code's Ready variable, which may not be what is desired. If the ScopeLocal parameter is added and set to TRUE, then it will return Invalid because it will not scope up from MyService to the Ready variable in Code.


ScopeLocal

Deprecated. Do not use in new code.

Description: | Exists only for backward compatibility. Use Scope(Module, VarName, TRUE) for all new code. Performs a scope resolution only if it occurs in the requested context. Returns a reference to the requested member within a module or other object.
Returns: | Reference
Usage: | Steady State only.
Function Groups: | Basic Module
Related to: | Scope | LocalScope
Format: | ScopeLocal(Object, Member)
Parameters: |
Object
Required. Any expression for the object value (module) where Member may be found.
Member
Required. Any text expression for the member name. This must be a simple variable or module. Array references or further scope resolution are not allowed inside the text expression.
Comments: This function differs from the Scope function only in that it is restricted to the requested module context. It will not search through the scope tree if the Member name is not found in the designated object.
If the final result is Invalid, this function looks for the presence of backslash (\) characters in the second parameter and parses the result.

Example:

ScopeLocal(\Code, "TagName");

Returns a reference to the given tag object, found within the current module.


SDev

(Engine-Level Function)

Description: | Returns the statistical sample standard deviation for a subsection of an array.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array, Generic Math
Related to: | AMax | AMin | AValid | FiltHigh | FiltLow | FitOffset | FitSlope | Mean | Sum | Variance
Format: | SDev(ArrayElem, N)
Parameters: |
ArrayElem
Required. Any array element giving the starting point in the array. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to use starting at the element given by the first parameter. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Comments:

The function returns an invalid result if either of its parameters is invalid or if there are less than two valid numerical array elements in the specified range. Invalid elements are not included in the calculation.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

productStdDev = SDev(weight[0], 5);

This computes the standard deviation of elements 0 to 4 of the array weight.


Seconds

(Engine-Level Function)

Description: | Returns the number of seconds since midnight of the current day.
Returns: | Numeric
Usage: | Script only.
Function Groups: | Time and Date
Related to: | AbsTime | CurrentTime | Now | Today
Format: | Seconds()
Parameters: | None
Comments: Care must be taken when using this function together with the Today function to determine the current date and time. If the time is within a fraction of a second of midnight, the value of the date may be calculated in one day and the time in the other day giving an apparent error of almost 24 hours. In situations where this is a problem, the AbsTime function may be helpful, however, the best practice is to use the function CurrentTime.

Examples:

If 1 Main;
[
  timeStamp = Seconds();
]

This assigns the current time in seconds since midnight to the floating point (or long) variable timeStamp. Another example of how this function could be used is:

If 1 Main;
[
  start = Seconds();
  FRead(1, "G:\TOTALS\BARTOTAL.DAT", 120, "%40c", bar4Total);
  duration = Seconds() - start { Compute time for network
  server disk read };
]

This example shows how to measure the execution time of various functions in a script. This provides information on how to improve the performance of the application. In this case, if the time is too long, it may be useful to install a disk drive cache such as SMARTDRV.


SectionControl

(System Library)

Description | Creates a control that displays a variable number of sections. Visually, a section consists of a header and content. The control manages the layout and geometry for the sections and runs a caller-supplied module to display the section content (see Comments).
Returns | Object
Usage | Steady State only.
Function Groups | Advanced Module, Graphics
Related to: | DialogInitPos | DropList | GridList | HScrollbar | Listbox | RadioButtons | SplitList | ToolBar | VScrollbar
Format: | System.SectionControl(HeadingFont, HeadingTextColor, HeadingBackColor)
Parameters |
HeadingFont
Required. The font to use for the heading.
HeadingTextColor
Required. The color to be used for the heading text.
HeadingBackColor
Required. The color to be used as the background for the heading text.
Comments: As indicated above, a section consists of a header and content. The control manages the layout and geometry for the sections and runs a caller-supplied module to display the section content.
Call a SectionControl in steady-state, wait until the public variable Ready goes TRUE (non-zero), and then call AddSection and DeleteSection (see the Related Sub-functions section above) to add sections to and delete sections from the control.
SectionControl assumes that it is being run in a child window and expands to consume the entire window. It automatically adds a vertical scroll bar when required.
Sub-functions and Variables:

Public Variables:

ExpandEnable
Enable/Disable the expand tool button. Default: 1
WindowEnable
Enable/Disable the new window tool button. Default: 1
PopupTitle
The pop-up window title string. Defaults to the value of Heading.
Height

Height is a public (read-only) variable that gives the overall height of the SectionControl in pixels.

Ready
Ready is a public (read-only) variable that must go to a non-zero value prior to AddSection or DeleteSection being called (see Comments section)

Sub-Functions:

AddSection
Comments:

AddSection returns the object value of a SectionControl\DisplaySection instance. This object value is used as a parameter to DeleteSection as well as providing some read-only values that the caller may access. These are:

Ready When 1, the caller can safely access the public variables listed. Default 0.

ExpandEnable Draws and enables the expand tool button. Default 1.

WindowEnable Draws and enables the new window tool button. Default 1.

AddButtons Subroutine module.

Takes a single parameter, being a ToolBar format data array containing additional tool buttons to insert at the LHS of the embedded ToolBar.

Related to:
Format: AddSection(Heading[, ContentModule, InitiallyExpanded, Param1, Param2, ExpandEnable, WindowEnable, Pop-upTitle, AvailableHeightPtr])
Parameters:
Heading
Can be a text value or a module value. If a text value, it is rendered in the header. If it is a module value, it is a caller-supplied module to draw the header with the following parameters:
Parameter | Description
X (in) | X coordinate of LHS of drawing area
Y (in) | Y coordinate of the top of the drawing area.
Width (in) | The number of X-pixels available in which to draw.
Height (in) | The number of Y-pixels available in which to draw.
TextColor (in) | The default heading text color.
BackColor (in) | The background color for the heading text.
TextFont (in) | The default heading text font.
Param1 (in) | Param1 passed to AddSection.
Param2 (in) | Param2 passed to AddSection.
ContentModule
A module value of the caller-supplied module to render the content. It is called with the following parameters:
ContentModule | Description
X (in) | X coordinate of LHS of drawing area
Y (in) | Y coordinate of the top of the drawing area.
Width (in) | The number of X-pixels available in which to draw.
ContentHeight (out) | The number of Y-pixels this method needs.
VisibleContent (in) | Boolean: TRUE if content is visible.
Param1 (in) | Param1 passed to AddSection.
Param2 (in) | Param2 passed to AddSection.
Available Height (in) | Numeric value used if the DisplaySection module knows how much height can be made available

The content drawing module must maintain the value of ContentHeight in steady-state. It is used by the control to manage the geometry of other sections in the control. When the Boolean VisibleContent is TRUE (set by the SectionControl), the module must draw the content. When the control sets VisibleContent FALSE, the module must stop drawing the content. By setting the output value ContentHeight, the drawing module tells the control that it is no longer drawing and the section can be collapsed.

InitiallyExpanded
Can be set to TRUE if the heading is to be initially expanded, or FALSE if the heading is to be initially collapsed.
Param1
A parameter passed to the drawing module.
Param2
A parameter passed to the drawing module.
ExpandEnable
A Boolean value giving the initial setting for whether the expand button should be enabled. Default: 1
WindowEnable
A Boolean value giving the initial setting for whether the popup window button should be enabled. Default: 1
PopupTitle
An initial title string for the pop-up window. Defaults to the value of Heading.
AvailableHeightPtr
A numeric value indicating the number of pixels in the Y-axis available to be drawn in. Can be useful where ContentModule needs to present scrollable content to the operator.
DeleteSection |
Comments: | Deletes a section from the control.
Related to: |
Format: | DeleteSection(Object)
Parameters: |
Object
The object value returned from a previous AddSection call (see above).

The following sub-function, DisplaySection, is not meant to be used externally. It is used internally by AddSection

DisplaySection |
Comments: | Used internally by AddSection.
Related to: |
Format: | DisplaySection(X, Heading, DisplayModule, VisibleContent, Param1, Param2, EpandEnable, WindowEnable, Pop-upTitle, AvailableHeightPtr)
Parameters: |
X
The coordinate of LHS of section.
Heading
The heading text or module for the heading.
DisplayModule
The module value of the content drawing module.
VisibleContent
A Boolean value that can be set to TRUE when content is visible.
Param1
A parameter passed to the drawing module.
Param2
A parameter passed to the drawing module.
EpandEnable
Boolean to enable the Expand button (default: 1)
WindowEnable
Boolean to enable the New Window button (default: 1)
PopupTitle
Text string giving the title of the pop-up window
AvailableHeightPtr
Optional numeric - in case AddSection defines the height available for this section.


SecurityCheck

Security Manager Module

Description: | Examines the rules that apply to the current user or the named user to determine if the specified privilege has been granted.
Returns: | Boolean
Usage: | Script or steady state.
Related to: | GetAccountID | GetAccountInfo | GetFullName | GetGroupName | GetUserName | IsLoggedOn | IsSuspended | UIErrorToText
Format: | \SecurityManager\SecurityCheck(Privilege [, Suppress, AccountName, DenyCaller, TagName])
Parameters: |
Privilege

Required. A privilege number to be used in the security check.

System Privilege Reference for Programmers

Suppress
Optional. A Boolean indicating whether a privilege refusal dialog should be displayed if the SecurityCheck fails. TRUE to suppress the dialog. Defaults to FALSE.
AccountName
Optional. The name or AccountID of an account against which to check the privilege. Defaults to the caller’s account.
DenyCaller
Optional. The object value of the caller to use when launching the privilege refusal dialog. Defaults to the caller’s user session. This is used to control the lifetime of the dialog until dismissed by user action.
TagName
Optional. The name of a tag that will be used in the security check.
Comments: This module can be called in script or in steady-state. It returns TRUE if the security check passes and FALSE otherwise. In steady-state the return value may change if the parameters change, if the user's signed in state changes, or if there is a configuration change on the user’s account.
The security check is iteratively done against each rule in the user account until either a matching rule is found or all rules have been checked and no match found.
If the TagName parameter is Invalid or not specified, SecurityCheck looks in the caller’s scope for the nearest tag and uses the name of that tag as the TagName parameter.


Seek

(Engine-Level Function)

Description: | Changes and returns the current position within a stream. The return value is the current stream position after the seek is done.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | BuffStream | CloseStream | FileStream | GetStreamLength | SRead | StreamEnd | SWrite
Format: | Seek(Stream, Position[, Mode])
Parameters: |
Stream
Required. Any expression that returns the stream to do the Seek on
Position
Required. Any numeric expression that returns either the absolute position, or a relative amount to move the position, depending on Mode. If the mode is relative, this number may be negative (i.e. earlier in the stream).
Mode
An optional numeric expression that denotes which type of positioning to do. If equal to 0, the stream position is changed to Position (absolute mode). If equal to 1, the Position is added to the current stream position (relative mode ). Defaults to 0.
Comments:

This allows repositioning within a stream.
This function can be used to find the current stream position by setting the last two parameters to "0,1".

Reverse seeks on a socket stream are not supported.

Example:

If ! Valid(strm);
[
  strm = BuffStream("ABCDEF");
  Seek(strm, 3, 0);
  SRead(strm, "%1c", streamData);
]

The variable streamData now contains the string "D".


SelColor

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Sets a color value from a dialog
Returns: | Nothing. (The selected color is returned via the second parameter)
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | ColorSelect |PColorSelect |
Format: | \SelColor(Label, ColorIndex, Enable[, NoTrans, ShowColorIndex, DisplayRoot, DisableAlpha])
Parameters: |
Label
Required text. Sets the title of the color selection dialog.
ColorIndex
Required text. The selected color value will be returned via this parameter.
Enable
Required Boolean. Must be set to TRUE for the color picker to open. This parameter is set to FALSE by the color picker upon closing. Use this as a signal that the user has chosen a color.
NoTrans
Boolean. Deprecated option - all transparent options are shown.
ShowColorIndex
Optional Boolean. When true, the string value, "<aaRRGGBB>" of the selected color is shown. Defaults to true.
DisplayRoot

Optional object value.

For example, to make the dialog appear on a monitor than the one holding the window that contains the caller of SelColor (or if the caller of SelColor is not running inside a window), you can pass an object into DisplayRoot to specify the monitor that the dialog should appear on. You would pass in an object running in a window on the desired monitor. Thus, to make the dialog appear on the same window as a pop-up page, you would pass in the popup page object.

DisableAlpha
Disable transparency options in the color picker. This Parameter is false by default meaning transparency settings are enabled, if set to True Transparency settings are disabled.
Comments:

Displays the standard VTScada color-picker dialog.

Example:

ColorSelect [
  \SelColor(GetPhrase("SelectColorLabel"), Color, Open, TRUE, TRUE, Session, TRUE);

  If !Open;
  [
    IfThen(Color != OldColor,
      UserSelectedColor = Color;
    );
    Slay();
  ]
]


SelectArea

(Engine-Level Function)

Description: | Selects active graphics statements within a rectangular area in a window.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: |
Format: | SelectArea(Object, Left, Bottom, Right, Top, MustContain)
Parameters: |
Object
Required. Any expression for the object value that identifies the window.
Left
Required. Any numeric expression for the left side coordinate of the area.
Bottom
Required. Any numeric expression for the bottom side coordinate of the area.
Right
Required. Any numeric expression for the right side coordinate of the area.
Top
Required. Any numeric expression for the top side coordinate of the area.
MustContain
Required. Any logical expression. If true, an object will be selected only if it is completely enclosed by the area. Otherwise, an object will be selected if any part of that object falls within the area.
Comments: SelectArea is a function that returns the number of objects that have been found and selected within the defined area.


SelectCodePointer

(Engine-Level Function)

Description: | Given a window object and a code pointer for an active graphics object within that window, this function adds the graphics object to the window's selection set.
Returns: | Pointer
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | SelectDAG
Format: | SelectCodePointer(Object, CodePointer)
Parameters: |
Object
Required. Any expression for the object value that identifies the window containing the graphic.
CodePointer
Required. Any code pointer value expression for the graphic object. (see comments)
Comments: You must first use StatementInstance to obtain the code pointer to be used in the CodePointer parameter.


SelectDAG

(Engine-Level Function)

Description | Selects an active graphics statement.
Returns | Code Pointer
Usage | Script or steady state.
Function Groups | Graphics
Related to: | SelectCodePointer | MakeDAG
Format: | SelectDAG(Statement, Object, Index)
Parameters |
Statement
Required. Any expression for the code value of the statement to select.
Object
Required. Any expression for the object value that identifies the module instance where Statement is found.
Index
Required. Any numeric expression for the function within Statement.
Comments: A "DAG" is a type of function.


SelectGraphic

(Engine-Level Function)

Description | Obsolete. Will compile but does nothing.
Returns | Code Pointer or Steady State
Usage | Script Only.
Function Groups | Graphics
Related to: |
Format: | SelectGraphic(Object, X, Y, Dist, N)
Parameters |
Object
Required. Any expression for the object value that identifies the window.
X
Required. Any numeric expression for the x-axis coordinate of the selection point.
Y
Required. Any numeric expression for the y-axis coordinate of the selection point.
Dist
Required. Any numeric expression for the maximum distance a graphic may be from (X,Y) and still be considered for selection.
N
Required. Any numeric expression for the object to select. 0 is the first object, 1 is the next, and so on. This allows selection of graphics that are 'underneath' other graphics.


SelectHandle

(Engine-Level Function)

Description: | Returns a pointer to a handle of selected graphics statements at a location in a window.
Returns: | Pointer
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | DragHandle | SelectHandleNum
Format: | SelectHandle(Object, X, Y, DragAll)
Parameters: |
Object
Required. Any expression for the object value which identifies the window.
X
Required. Any numeric expression for the x-axis coordinate of the selection point.
Y
Required. Any numeric expression for the y-axis coordinate of the selection point.
DragAll
Required. Any logical expression. If true, dragging a handle will drag all selected handles at (X,Y). Otherwise, only the first selected handle (in the topmost layer) will drag.

Example:

If LocSwitch() == 4 GetHandle;
[
  handle = SelectHandle(CurrentWindow(), XLoc(), YLoc(), 1);
  handle = PickValid(handle, 0);
]

This script will be executed when the left mouse button is pressed, and will attempt to grab a valid handle that lies directly under the mouse.


SelectHandleNum

(Engine-Level Function)

Description: | Selects the given handle of selected graphics statements in a window.
Returns: | Point
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | DragHandle | SelectHandle
Format: | SelectHandleNum(Object, HandleNum, X, Y)
Parameters: |
Object
Required. Any expression for the object value which identifies the window.
HandleNum
Required. Any numeric expression for the handle number which you wish to choose. The handles are numbered as follows.

0 1 2

6 8 7

3 4 5

X
Required. Any variable in which the X screen coordinate for that handle will be returned.
Y
Required. Any variable in which the Y screen coordinate for that handle will be returned.
Comments: This function selects the handle requested in the window requested and returns the user coordinates for that selected handle. The returned coordinates can then be used in the DragHandle function.
Will return invalid for the X & Y values if an attempt is made to select the middle side handles (1, 4, 6, or 7) when those handles are not visible due to the object selection box being too small to display them.


SelectPath

(Engine-Level Function)

Description: | Selects a path given its code pointer value.
Returns: | Object
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: |
Format: | SelectPath(Object, CodePointer)
Parameters: |
Object
Required. Any expression for the object value that identifies the window.
CodePointer
Required. Any expression for the code pointer value of the path to select.


Self

(Engine-Level Function)

Description: | Returns the object value of the current object.
Returns: | Object Value
Function Groups: | Basic Module
Usage: | Script or steady state.
Related to: | NParm | Parameter | PType | ResetParm | Return | SystemSelf
Format: | Self( )
Parameters: | None
Comments:

This is the only way to get a module's object value and is a way for an object to store a reference to itself.

Often, this object value is passed to other objects so they can :
- Scope into that object to access its member variables / modules.
- Monitor the object's lifetime (wait for the object value to no longer be Valid).

Note: If writing an expression that must reference the object's parent, \Root is more reliable than ParentObject(Self).

Example:

  ModPtr = Scope(Self, DriverTag);

Where DriverTag is a text variable containing the relative name of another tag.


Send

(RPC Manager Library)

Description: | This subroutine sends a message by invoking a remote procedure call (RPC).
Returns: | Current session id of remote procedure, else RPC_NO_SID
Usage: | Script Only.
Function Groups: | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | SetRemoteValue
Format: | \RPCManager\Send(Service, RemoteGUID, ModeCutOff, SendServer, MachineName, SendClients, ExecLocally, Recursive, ModuleName, ModuleContext, UpdateObject, InputSessionID [, Parameters…])
Parameters: |
ServiceName
Required. The name of the service to transmit to. For directed RPCs, set this value to either Invalid or a zero-length string.
RemoteGUID

Required. The GUID of the application to receive the RPC. If Invalid, RemoteGUID is searched for in the caller's scope.

The RemoteGUID parameter MUST be a binary GUID. GetGUID() can be used to convert a text GUID into a binary GUID if required.

ModeCutOff
Required. The service synchronization mode above which this message should not be sent. Normal RPCs should set this to RPC_ACCEPT_ALL mode.
SendServer
Required. If set to "1", this flag will transmit this RPC to the service instance that is currently the server for the service. Ignored for directed RPC requests.
MachineName
Required. The IP or name of the workstation to be used for a directed RPC. Invalid for service RPCs.
SendClients

Required. May be any of the following:

0: Do not send to clients

1: Transmit this RPC to all service instances that are currently clients of the service server. Ignored for directed RPC requests.

2: Send to all clients that are on the local machine's list of potential service servers.

ExecLocally
Required. ExecLocally only has an effect on directed RPCs (i.e. not on service RPCs). If ExecLocally is TRUE, the RPC is forced to execute on the local machine ONLY.
Recursive
Required. If set to "1", and SendClients is also set to "1", this flag will transmit this RPC to all service instances that are clients of this workstation and all service instances that are clients of them.

If set to a "1" and SendServer is also a "1", will transmit to servers of this workstation and servers of those workstations. This is of use when "clients of clients" are configured.

In most cases, it is wise to set this flag when making service broadcast updates.
ModuleName
Required. The textual name of the RPC subroutine to be executed. Must be valid.
ModuleContext

Required. The context in which the "ModuleName" will be executed. The "base" context for a VTScada layer-based application is "Code".

"." may be used as an alias for the object that registered for the RPC service. See comments.
For a non-VTScada (pure script) application, the base context is the root of the application specified by the RemoteGUID parameter. Must be valid.

UpdateObject
Required. If valid, is an object that will act as a holding point for the RPC until it is actually transmitted to the remote workstation. A subsequent RPC with the same UpdateObject value will discard the previous RPC if it has not yet been transmitted, and replace it with the new one. This is of most use to services whose updates completely negate the effect of previous updates, and serves to minimize the transmission of redundant RPCs.
InputSessionID
Required. If Invalid, the RPC will be queued for transmission. If valid, will be interpreted as a SID which must match the current SID for the multi-server application. Otherwise, the RPC will not be queued for transmission.
Only of use in directed RPCs.
Parameters
A set of up to 32 parameters to the RPC subroutine. Can be any mixture of the legal types. Supplying a parameter of an illegal type will cause it to be replaced with Invalid when the RPC subroutine is invoked.

Comments

This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
The method returns the current SID of the multi-server application if the message was queued for transmission. Otherwise, it will return RPC_NO_SID.

Service Relative Context

As of VTScada version 12.0, you can send a message to a remote service object using a module context of "." as an alias for the full scope path of the object that registered for the RPC service. This works on any service-based Send() operation.

The context should be specified as "." where "." is an alias for the object that called RPCManager\Register(). Directed RPC do not support relative context, even if Send() is run using a ServiceName, as those are not truly service RPCs.

Example:

If 1 Main;
[
  sessID = \RPCManager\Send("MyService" { service }, \RemoteGUID,
              \RPC_ACCEPT_FILTER { mode cut-off },
              1 { server }, Invalid { machine },
              0 { clients }, 0 { locally },
              0 { recursive }, "Start" { module },
              "\" { service scope },
              Invalid { queue msgs },
              Invalid { no initial session ID },
              { Parameters: } rev, myName);
  sessID = \RPCManager\Send("MyService" { service },
              \RemoteGUID,
              \RPC_ACCEPT_FILTER { mode cut-off },
              1 { server }, Invalid { machine },
              0 { clients }, 0 { locally },
              0 { recursive }, "Finish" { module },
              "\" { service scope },
              Invalid { queue msgs },
              sessID { original server's sess ID },
              { Parameters: } index);
]

This will cause the modules called Start and Finish, which are found in the scope of the service called MyService, to be executed on the server. Note that by handing in the session ID from the first call to the second call it is guaranteed that module Finish will either be queued for the workstation that was the server at the time when the first message was queued or will be discarded. It will not be sent to another workstation that may take over servership for the MyService service.

Related information:

RPC Manager Service


SendMail

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Sends a string to an email server using the Simple Mail Transport Protocol (SMTP)
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Email
Related to: | ValidateEmailAddrs
Format: | \SendMail(Server, To, From, Subject, Message, Error [,Attachments, AttachmentStreams, OptionalHeaders, ErrorText, SenderMailbox, Username, Password, UseTLS, Bcc, Charset, Port, UseOauth2, OAuth2GrantID, EncryptedSettings, ContentType])
Parameters: |
Server
Required. Any text or buffer expression of the mail server name or IP address
To
Required. Any text or buffer expression of the address of destination
From
Required. Any text or buffer expression of the address of the person from whom the mail is from
Subject
Required. Any text or buffer expression of the subject of the message
Message
Required. Any text or buffer expression of the message - no attachments
Error

Required. A pointer to an error variable, set to 0 if OK. The Error parameter should initially be set Invalid by the caller. When this method is done, it will set Error to one of the following values:

The following error codes are produced by VTScada. Your email server may produce others.

Error | Meaning
0 | Mail has been successfully sent.
1 | Unable to open a connection to the server.
2 | Server did not send a good SMTP welcome message.
3 | Server rejected SMTP HELO message.
4 | Server rejected SMTP MAIL message.
5 | Server rejected SMTP RCPT message.
6 | Server rejected SMTP DATA message.
7 | Server rejected message body.
8 | Badly formatted TO: address.
9 | Server does not support AUTH.
10 | Server does not support implemented AUTH. mechanisms.
11 | Failure to login to SMTP server.
12 | TLS wanted for SMTP, but not available
13 | TLS unavailable or negotiation with server failed
14 | Badly formatted bcc address
Attachments
An optional parameter that is an array of file names to be attached to the email message.
AttachmentStreams
An optional parallel array of attachment streams.
OptionalHeaders
A string of optional MIME headers, separated by CRLF.
ErrorText
An optional pointer to the variable that holds the phrase key of the error message. Use \GetPhrase() to translate this ID to the language currently in use.
SenderMailbox
An optional parameter which is the SMTP reverse path. SenderMailbox overrides the From parameter. This parameter may be used as an alternative to the From parameter when specifying the "MAIL FROM" address in the SMTP.
The From parameter would still be used when specifying the "From:" address in the email header. SenderMailbox should be used only when an email is intended to look like it came from a particular address, but has actually originated from another address.
Username
Allows a user name to be provided to email servers that require authentication.
Password
Allows a password to be provided to email servers that require authentication.
UseTLS
Boolean to indicate that transport layer security should be used.
Bcc
Optional list of recipients, who should receive a bcc copy of the message.
Charset
Optional. Text string to be used for MIME character set.
Port
Optional numeric. Use to specify which port the SMTP server should use. If not provided, the value of the SMTPPort application setting is used, defaulting to 25.
UseOAuth2
Optional Boolean. Set TRUE use Auth
OAuth2GrantID
Text. Must be set if UseOAuth2 is TRUE. The Grant ID
EncryptedSettings
Optional text. A set of encrypted mail settings to use.
ContentType
Body content type (text/plain, text/html)
Comments:

This function opens a TCP/IP socked on port 25 (or other if specified) of the specified mail server. The Message is then sent using the SMTP protocol.
If both Username and Password are valid, then SendMail will attempt to login to the mail server before sending the email message. If the server does not support authentication, then SendMail will abort with an error message.
If both Username and Password are valid, but the server does not support PLAIN authentication, then SendMail will abort with an error.
If either Username or Password is missing or invalid, then the message will be sent without a login attempt.

The To: address will accept a string that conforms to the address-list ABNF from RFC 5322.

If using OAuth2 and the server does not offer XOAUTH2 as an authentication method then error 10 is returned.

Example:

\SendMail("192.168.0.201",
           "sales@trihedral.com",
           "vts@trihedral.com",
           "Great Product!",
           "VTScada is Great\n\rMust buy lots!",
           &ErrorCode);


SerBreak

(Engine-Level Function)

Description: | Sends a break character to a serial port.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Serial Port
Related to: | COMPort | SerCheck | SerialStream
Format: | SerBreak(Port, Status)
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or serial stream value (returned from a SerialStream function).
Status
Required. Any logical expression. If true (non-0), a break will be sent to the serial port defined in Port, if false (0), the break will be cleared from the serial port.

Example:

If MatchKeys(1, MakeBuff(1, 27) { <ESC> key pressed }) BreakSent;
[
  SerBreak(4, 1);
]

The above code causes a break to be sent to serial port 4 if the user presses the <ESC> key.


SerCheck

(Engine-Level Function)

Description: | Check Serial Port. This function returns the immediate or cumulative serial port status.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Serial Port
Related to: | COMPort | SerBreak | SerialStream
Format: | SerCheck(Port, Reset)
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or serial stream value (returned from a SerialStream function).
Reset
Required. Any logical expression. If true (non-0), the serial port status register will be cleared.
Comments: The return value consists of 9 bits that indicate the status of the following
Bit | Meaning
0 | Clear To Send (CTS)
1 | Data Set Ready (DSR)
2 | Ring Indicator (RI)
3 | Carrier Detect (CD)
4 | Overrun error
5 | Parity error
6 | Framing error
7 | Break signal detected
8 | Receive buffer overflow (always cumulative)

(See: Bitwise Parameters & Operations)

Example:

If 1 Send;
[
  parityErr = Cond(And(SerCheck(2, 0), 0b00100000), 1, 0);
  IfThen(parityErr, ForceState("Retry"));
]

In this script, port 2 is checked for a parity error. If there is one, a state transfer to state Retry will occur, otherwise the destination state in the script's trigger (state Send) will be active next.


SerialNum

(Engine-Level Function)

Description: | Returns the serial number of the copy of VTScada running.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Software and Hardware
Related to: | CommandLine | Version
Format: | SerialNum()
Parameters: | None
Comments: | This function can be used to provide copy protection for user-developed modules by checking for a specific copy of VTScada before performing the desired task.

Example:

ZText(20, 20, Cond(SerialNum() != 2975, "Unauthorized serial
number!", ""), 15, 0);

This displays a message if the serial number of VTScada is not 2975.


SerialStream

(Engine-Level Function)

Description: | Returns a serial stream that can be used in any of the serial port functions or with any of the stream functions. Please note that the ComPort function (which functions somewhat differently than the SerialPort function) may also be utilized.
Returns: | Stream
Usage: | Script Only.
Function Groups: | Serial Port, Stream and Socket
Related to: | COMPort | SerCheck | SerIn | StrLen | SerOut | SerRcv | SerSend | SerString | SerStrEsc | SerWait
Format: | SerialStream(Port, ReceiveLen, TransmitLen, Baud, DataBits, StopBits, Parity, RTS, XOnXOff, Control)
Parameters: |
Port
Required. Any numeric expression giving the serial port number to be used. For COM1: Port = 1. For COM2: Port = 2. The valid range for Port is 1 to 4096.
ReceiveLen
Required. Any numeric expression giving the size of the receiver buffer in bytes. ReceiveLen must be in the range 2 to 32766.
If more bytes are received than can fit in the receive buffer before your application removes them using SerRcv or a similar VTScada function, the additional data will be lost.
TransmitLen
Required. Any numeric expression giving the size of the transmitter buffer in bytes. TransmitLen must be in the range 2 to 32766. The buffer must be large enough to hold the maximum number of bytes pending transmission at any instance.
Baud
Required. Any numeric expression giving the baud rate. Baud must be in the range 10 to 57600, and must divide evenly into 115200 with no more than 2.5% error.
DataBits
Required. Any numeric expression giving the number of data bits per character. DataBits must be 5, 6, 7, or 8.
StopBits
Required. Any numeric expression giving the number of stop bits per character. StopBits must be 1 or 2.
Parity
Required. Any numeric expression giving the parity checking to use:
Parity | Checking
0 | No parity
1 | Odd parity
2 | Even parity
3 | 0 Stick (space parity)
4 | 1 Stick (mark parity)
RTS
Required. Any numeric expression that gives the RTS buffer control method. RTS is on while transmitting. When a transmission is complete, RTS is off.
This is usually used to control the transmitters on RS-422/485 ports. This parameter has no effect if the automatic RTS control is selected in the Control parameter.
Acceptable values of the RTS parameter are as follows:
RTS | Buffer Control Method
0 | Force RTS off
1 | Force RTS on
2 | Half-duplex operation
3 | Controlled by SerRTS function

If this parameter is 2, the SerRTS function can set its value. However, regardless of SerRTS, the RTS control line will be asserted when data is sent.

If the SerRTS is called to change the RTS line while data is being transmitted, the RTS line will not change when the last byte is sent. If SerRTS is not executed while the data is transmitted, the RTS line will be cleared after the last byte is transmitted.

XOnXOff
Required. Any logical expression. If true (non-0) software flow control is to be used. If false (0) it is not.
Control
Required. Any numeric expression that specifies the handling procedure for the clear to send (CTS), carrier detect (CD), and data set ready (DSR) input lines, and the data terminal ready (DTR) output line on the serial port. The value must be in the range 0 to 63. The desired action is the sum of the following values:
Control | Bit No. | Handling Procedure
1 | 0 | DTR on (otherwise DTR is off)
2 | 1 | Enable CTS control
4 | 2 | Enable CD control
8 | 3 | Enable DSR control
16 | 4 | Enable RTS/CTS control
32 | 5 | Enable DTR/DSR control

(See: Bitwise Parameters & Operations)

If bit 1 (CTS control) is set, data will only be transmitted if the CTS signal is on. If CTS control is disabled, the CTS line is ignored.

If bit 2 (CD control) is set, data will only be transmitted when the CD signal is on. If CD control is disabled, the CD line is ignored.

If bit 3 (DSR control) is set, data will only be transmitted when the DSR signal is on. If DSR control is disabled, the DSR line is ignored.

If bit 4 (RTS/CTS control) is set, the CTS control behaves as described above, and the RTS line will be held high until the receive buffer reaches 75% full. It will then go low, indicating to the other device to stop transmitting data. The RTS line will go high again when the receive data buffer drops below 25% full. This is known as hardware flow control. RTS/CTS control enabled overrides the RTS parameter.

If bit 5 (DTR/DSR control) is set, the DSR control behaves as described above, and the DTR line will be held high until the receive buffer reaches 75% full. It will then go low, indicating to the other device to stop transmitting data. The DTR line will go high again when the receive data buffer drops below 25% full. This is known as hardware flow control. DTR/DSR control enabled overrides bit 0, DTR on option.

Comments: The parameters for this function are a reduced set from the Comport statement.

Make sure that VTScada's mouse (if it is serial) is on a different port, because the mouse and SerialStream can interfere. Also make sure that no other hardware or software is interfering with the serial port hardware interrupts (IRQ4 for COM1:, IRQ3 for COM2:). Network cards often use IRQ4, which will cause a problem with a mouse or SerialStream on COM1:.

The stream will automatically close when there are no variables referencing the stream. However, if there are bytes still in the transmit buffer, they will not be sent before the stream is closed.

Example:

streamCom2 = SerialStream(2 { COM2: },
                    1024 { Buffer 1024 bytes of received data },
                    1024 { Buffer 1024 bytes of transmitted data },
                    9600 { Baud rate },
                    8 { Data bits per byte },
                    1 { Stop bit per byte },
                    0 { No parity bit },
                    1 { Force RTS on },
                    0 { No Software flow control (XonXOff) },
                    3 { Control: DTR On, CTS control enabled });

This opens COM2: for use with serial port functions. These functions should use streamCom2 as their Port parameter.


SerIn

(Engine-Level Function)

Description: | Get Serial Port Byte. This function returns the next byte in the receive buffer.
Returns: | Byte
Usage: | Script Only.
Function Groups: | Serial Port
Related to: | COMPort | SerCheck | StrLen | SerOut | SerRcv | SerRTS | SerSend | SerStrEsc | SerString | SerWait
Format: | SerIn(Port, Peek)
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or any stream value.
Peek
Required. Any status expression to control whether the byte being read should also be removed from the receive buffer.
If Peek is true, the byte is not removed from the receive buffer.
Comments: If no byte is available, the return value is invalid.

Example:

If 1 Continue;
[
  chkSum = SerIn(2, 0);
  IfThen(! Valid(chkSum), ForceState("Wait"));
]

This reads one byte from the receive buffer for serial port 2. If none is available, chkSum will be invalid. Notice that the next state to become active is dependent on whether a byte has been successfully read.


SerLen

(Engine-Level Function)

Description: | Serial Port Buffer Length. This function returns the number of bytes currently in the receive or transmit buffers.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Serial Port, String and Buffer
Related to: | COMPort | SerCheck | SerIn | SerOut | SerRcv | SerRTS | SerSend | SerStrEsc | SerString | SerWait
Format: | SerLen(Port, Option)
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or any stream value.
Option
Required. Any status expression. If Option is true, the number of bytes in the transmit buffer is returned. If Option is false, the number of bytes in the receive buffer is returned.
Comments: This function may only appear in a script.

Examples:

If ! Valid(rcvBufLen);
[
   rcvBufLen = SerLen(2, 0);
]

This finds the number of bytes presently in the receive buffer on serial port 2. This will always be a valid number equal to 0 or greater.


SerOut

(Engine-Level Function)

Description: | Send Serial Port Byte. This statement sends a byte to the transmit buffer.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Serial Port, String and Buffer
Related to: | COMPort | SerCheck | SerIn | StrLen | SerRcv | SerRTS | SerSend | SerStrEsc | SerString | SerWait
Format: | SerOut(Port, Value)
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or any stream value.
Value
Required. Any numeric expression which gives the byte value to send. Value must be in the range 0 to 255.
Comments: The byte will not be sent if the transmit buffer is full.

Example:

If MatchKeys(2, "t");
[
  SerOut(2, Cond(chkSum == calcChksum, 6, 21);
]

This waits until the operator presses the "t" key, then it compares chkSum to calcChksum. If equal, a 6 byte (ASCII ACK) is sent. If not equal, a 21 byte (ASCII NAK) is sent. The serial port used is 2.


SerRcv

(Engine-Level Function)

Description: | Serial Port Receive. This function returns a buffer containing a string read from the receive buffer.
Returns: | Buffer
Usage: | Script Only.
Function Groups: | Serial Port
Related to: | COMPort | SerCheck | SerIn | StrLen | SerOut | SerRTS | SerSend | SerStrEsc | SerString | SerWait
Format: | SerRcv(Port, Count)
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or any stream value.
Count
Required. Any numeric expression, which gives the number of bytes to read. Value must be in the range 0 to 65500.
Comments: The return value is a buffer containing Count bytes, unless fewer bytes were available in the receive buffer. This function may be used to flush the serial port receive buffer.

Example:

If SerWait(2, 12) { Wait for 12 bytes buffered for port 2};
[
  data = SerRcv(2, 12);
]

This waits until 12 bytes are in the receive buffer for serial port 2, and then reads them into the variable data. Byte 0 of data will be the oldest byte in the receive buffer (received first by VTS).


SerRTS

(Engine-Level Function)

Description: | Sets or clears the RTS line on a serial communication port.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Serial Port
Related to: | COMPort | SerCheck | SerialStream | SerIn | StrLen | SerOut | SerRcv | SerSend | SerStrEsc | SerString | SerWait
Format: | SerRTS(Port, Level)
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or serial stream value (returned from a SerialStream function).
Level
Required. TRUE if the RTS line is to be turned on or false if the RTS line is to be turned off.
Comments: The corresponding ComPort statement must have the RTS parameter set to 2 or 3.

Example:

RTS = 0;
...
ComPort(2 { COM2: },
        1024 { Buffer 1024 bytes of received data },
        1024 { Buffer 1024 bytes of transmitted data },
        9600 { Baud rate },
        8, 1 { Data bits/byte, stop bits/byte },
        0 { No parity bit },
        3 { RTS may be controlled by SerRTS function },
        0, 0, 0 { Obsolete parameters },
        3 { Control: DTR On, CTS control enabled },
        0, 0, 0, 0, 0, 0, 0, 0, 0 { Obsolete parameters });
If MatchKeys(2, "R");
[
  RTS = 1 - RTS { Toggles RTS between 1 and 0 };
  SerRTS(2, RTS);
]

Comport 2 is opened to allow the setting of the RTS line. The second statement then toggles the RTS line of serial port 2 on and off every time the letter R is pressed on the keyboard.


SerSend

(Engine-Level Function)

Description: | Serial Port Send. This function writes a string to the transmit buffer and returns the number of bytes written.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Serial Port
Related to: | COMPort | SerCheck | SerIn | StrLen | SerOut | SerRcv | SerRTS | SerStrEsc | SerString | SerWait
Format: | SerSend(Port, Buffer, MaxBytes, Escape)
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or any stream value.
Buffer
Required. Any text expression to send.
MaxBytes
Required. Any numeric expression which gives the maximum number of bytes to send.
Escape
Required. Any numeric expression which gives the byte value of an escape code. Whenever an escape code is encountered, two escape codes will be transmitted.
To be valid, Escape must be in the range of 0 to 255. If the Escape parameter is greater than 0 or less than 256, it is transmitted with escape codes.
If Escape is a value greater than 255, it will perform in the same manner that it would if Escape were a value of 0.
If the value of Escape is less than 0, it doesn't take into account escape codes and the buffer is transmitted in its entirety, stopping at MaxBytes.
Comments: The return value is the actual number of buffer bytes successfully placed in the transmit buffer (not including extra escape codes). MaxBytes should be transmitted, unless the end of the buffer is encountered, or a transmit buffer overflow occurs.

Example:

If MatchKeys(2, "S");
[
  SerSend(2, "Hello World ", 12, 0);
]

The code above sends the message "Hello World" through serial port 2.


SerStrEsc

(Engine-Level Function)

Description: | Serial Port Receive With Escape. This function reads the receive buffer until a specified character (the 'escape' character) is encountered, incrementing an offset counter for each character read that is not the Escape character. It is assumed that, where the message contains the Escape character as part of the message, that character is 'escaped' by being doubled.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Serial Port
Related to: | COMPort | MakeBuff | SerCheck | SerIn | StrLen | SerOut | SerRcv | SerRTS | SerSend | SerString | SerWait
Format: | SerStrEsc(Buffer, Offset, Port, Escape)
Parameters: |
Buffer
Required. Any text variable to write the received data. This text buffer must already exist. It could be created by another function such as MakeBuff, or by assignment of a text constant.
Offset
Required. Any numeric expression which gives the offset from zero where SerStrEsc will start writing data to Buffer. If Offset is negative, Offset is returned and nothing is done.
Port
Required. Either a numeric expression for the serial port number (opened with a ComPort function) or any stream value.
Escape
Required. Any numeric expression which gives the terminating character code. This must be in the range 0 to 255 to be valid. A value of -1 means that no such code exists.
Comments: Data is read until the receive buffer is empty, Buffer is full, or an Escape value is encountered. If two successive Escape values are received, one is written to Buffer and reading continues normally. Otherwise, reading is terminated if the character following the Escape is not another Escape character. This is useful for reading the serial port receive buffer where the end of a message is signaled by a particular byte sequence. The byte following the final Escape is placed in the buffer.
The value returned by the function increases with each character read. When a single instance of the Escape value is encountered, the return value is the negative of the final offset before reading in the Escape character (the Escape character is discarded). The return value can be used in successive SerStrEsc calls as the Offset parameter to fill Buffer until a Escape character is encountered.

Example:

response = MakeBuff(1, 32) { Fill the buffer with spaces };
...
  { Read port until DLE encountered }
If (! Valid(pos) || pos >= 0) && SerWait(2, 1) { Variable becomes negative when <DLE> encountered };
[
  pos = SerStrEsc(response             { Buffer },
                  PickValid(pos, 0)    { Start at pos or 0 },
                  2                    { Port number },
                  0X10                 { Data end code (<DLE> or decimal 16) });
]
  { DLE found, all done } If Pos < 0  ProcessResponse;
[
   { calculate the size of the response message }
   RespSize = pos * -1;
]

ZText(10, 10, response, 0, 0);

This reads all characters from serial port 2 until a single byte 0x10 is encountered. The byte following the escape code will be the final character in response. When the escape is received, pos will become a pointer to where the last byte was written into the buffer, and the ZText statement will display the received message. Suppose the following (decimal) bytes were received by VTScada on serial port 2:

1, 2, 3, 16, 16, 4, 5, 16, 3, 6, 9, 8

The response would contain the following:

1, 2, 3, 16, 4, 5, 3

and the following bytes would be left in the receive buffer:

6, 9, 8


SerString

(Engine-Level Function)

Description: | Serial Port String Receive. This function reads the receive buffer until a string is encountered and returns the final offset in the buffer.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Serial Port, String and Buffer
Related to: | COMPort | MakeBuff | SerCheck | SerIn | StrLen | SerOut | SerRcv | SerRTS | SerSend | SerStrEsc | SerWait
Format: | SerString(Buffer, Offset, Port, String)
Parameters: |
Buffer
Required. Any text buffer to write the received data to. It must already exist - either by creating it with a function such as MakeBuff, or assignment of a text constant.
Offset
Required. Any numeric expression which gives the offset from 0 where SerString will start writing data to Buffer.
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or any stream value.
String
Required. Any text expression which gives the terminating string.
Comments: Data is read until the receive buffer is empty, Buffer is full, or String is encountered. This is useful for reading the serial port receive buffer where the end of a message is signaled by a particular byte sequence. The optional return value is the final offset after reading into Buffer, unless String was encountered, or Offset is negative.
If String was encountered, the return value is the negative of the final offset after reading in the String sequence. If Offset is negative, Offset is returned and nothing is done.
The return value can be used in successive SerString calls as the Offset parameter to fill Buffer until String is encountered.

Example:

If (! Valid(pos) || pos > 0) && SerWait(2, 1)
{ Pos is positive until "END" };
[
  pos = SerString(response { Buffer },
  Cond(Valid(pos), pos, 0) { Start at the
  beginning, do successive reads },
  2, "END" { Port no. & terminating string });
]

This reads from serial port 2 until the string "END" is encountered. As the message is read from the serial port, pos will be StrLen(response) and "END" will be the final character sequence in response - when it is received, pos will become -StrLen(response).


ServerList

Deprecated. May not work with newer applications or networks. Use GetAllWorkstationNames in new code.

(Engine-Level Function)

Description: | Returns a pointer to an array of all available servers visible from this workstation.
Returns: | Pointer
Usage: | Script Only.
Function Groups: | Network
Related to: | TServerList | WKStaInfo
Format: | ServerList(Obsolete, Domain, Obsolete)
Parameters: |
Obsolete
Parameter is no longer used, but is maintained for backward compatibility with previous versions of VTScada. Set to 0.
Domain
Required. Any text expression for the domain. If this is invalid, the current domain will be used.
Obsolete
Parameter is no longer used, but is maintained for backward compatibility with previous versions of VTScada. Set to 0.
Comments: This function will return the resultant array of servers, or if network problem is encountered or Domain is not found on the network, an error code will be returned.

Example:

If ! Valid(serverArray);
[
  serverArray = ServerList(0, WkStaInfo(2), 0);
]

The second parameter in the ServerList statement is included as an added example of how many functions work together - in actual fact it is redundant, since it simply designates Domain as being the current domain, which could also have been done by simply entering an invalid.


ServerSocket

(Engine-Level Function)

Description: | Returns a server WinSock socket stream given a handle returned by a SocketServerStart function or an integer error code.
Returns: | Stream
Usage: | Script Only.
Function Groups: | Network, Stream and Socket
Related to: | ClientSocket | CloseStream | SocketAttribs | SocketServerEnd | SocketServerStart | SocketWait | SRead | SWrite | LargeSocketWrite
Format: | ServerSocket(Handle)
Parameters: |
Handle
Required. Any numeric expression for the handle returned by the SocketServerStart function.
Comments: This function is used as part of a WinSocket-compliant server application. First, start a socket server using SocketServerStart. Then, use the SocketWait function as the trigger for an action script. Use this function in the script to connect a socket to the client application that triggered the SocketWait function. If the socket connection is lost (client shutdown) the stream is closed and set to a value of 0 (no error code returned).
If you experience difficulty with TCP/IP, a useful troubleshooting tool is the Windows™ diagnostic "NetStat.exe", used to display information about the network. Also of use is the Windows™ "Ping.exe" diagnostic which can be used to test the hardware connection. These files are normally found in the Windows™ directory. Consult the Windows™ documentation on their usage.

Example:

Init [
  If 1 Wait;
  [
    sHandle = SocketServerStart(0 { TCP/IP },
    20000{ Port number offered },
    1024 { Transmit buff length },
    1024 { Receiver buff length },
    1 { No transmit delay });
  ]
]
Wait [
  If SocketWait(sHandle) Main { Wait for client to connect };
  [
    server = ServerSocket(sHandle);
  ]
]
Main [
  If GetStreamLength(server) > 0 || MatchKeys(2, "r");
  [
    SRead(server, Concat("%", Concat(GetStreamLength(server),
    "c")), Data);
    SWrite(server, "%s", Data);
  ]
  { Always close socket when complete !!! }
  If WindowClose(Self());
  [
    CloseStream(server);
    SocketServerEnd(sHandle);
    Slay(Self(), 1);
  ]
  { Display data from client and server status }
  ZText(0, 50, Data, 0, 0);
  ZText(0, 100, Cond(ValueType(server) == 8 ,
  "Connected",
  "Not Connected"),
  10, 0);
]


SerWait

(Engine-Level Function)

Description: | Serial Port Wait. This function returns true when the receive buffer is a specified length.
Returns: | Boolean
Usage: | Steady State only.
Related to: | COMPort | SerCheck | SerIn | StrLen | SerOut | SerRcv | SerRTS | SerSend | SerStrEsc | SerString | GetStreamLength
Format: | SerWait(Port, Count)
Function Groups: | Serial Port
Parameters: |
Port
Required. Any numeric expression for the serial port number (opened with a ComPort function) or any stream value.
Count
Required. Any numeric expression, which gives the number of bytes to wait for. Value must be in the range 0 to 65500.
Comments:

The return value is true when at least Count or more bytes have been received from Port. This is treated as a high priority function, and anything using the return value of SerWait will be executed as soon as Count or more bytes are received from Port.

Example:

If SerWait(3, 16);
[
  recBuff = SerRcv(3, 16);
]

This action trigger will be true when 16 or more bytes are in the receive buffer from port 3, at which point the script will execute and the bytes in the receive buffer will be read into the buffer called recBuff.


Set

Description: | Set tag value. Set is somewhat different from other functions in this reference. Set is a submodule that is a part of every tag that is able to write a value. It is included in the general function reference only for ease of discovery.
Warning: | Use only when a standard VTScada widget is not available for your custom code.
Returns: | Nothing
Usage: | Script Only.
Related to: | OkToWrite
Format: | TabObject.Set(NewVal)
Parameters: |
NewVal
The value to write to the tag.
Comments:

As a general practice, you should use the existing VTScada widgets to create control objects on your pages. But, there may be times when you need a custom button or other control that will write a value to a linked tag. For this, you can use Set.

Example:

If WinButton(232, 148, 412, 100,
             0                      { normal appearance },
             Concat("Press Me ", ButtonPresses) { label },
             1                { focus id enables button },
             0                    { default system font },
             ToggleVal                   { monitor state});
[
  { Write 1 to the relevant tag. }
   MyTag.Set(1);
]


SetAllBlocks

(RPCManager Library)

Description: | This subroutine executes on the client. It accepts all of the blocks and data for a service.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Network
Related to: | COMPort
Format: | SetAllBlocks(NDrivers, Buffer, Vals, TimeStamp, Attrib)
Parameters: |
NDrivers
Required. Any number of drivers in the Buffer.
Buffer
Required. A stream containing all of the data.
Vals
Required. A packed array of driver values.
TimeStamp
Required. A packed array of driver values.
Attrib
Required. A packed array of driver values.
Comments: SetAllBlocks executes on the client. It is called from GetServerChanges on the server via RPC. SetAllBlocks accepts all of the blocks and data for a service.

Related information:

RPC Manager Service


SetBit

(Engine-Level Function)

Description: | Sets or clears a specific bit in a value and returns the result.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Bitwise Operation
Related to: | Bit | Ones
Format: | SetBit(Value, BitNumber, Option)
Parameters: |
Value
Required. Any numeric expression that gives the number to modify the bit in.
BitNumber
Required. Any numeric expression giving the bit number to set or clear. Bit 0 is the least significant bit. Legal values are from 0 to 31 inclusive.
Option
Required. Any status expression indicating whether the bit is to be set or cleared in the Value. A true indicates that the bit is to be set (i.e. set to 1), and a false indicates that it is to be cleared (i.e. set to 0).
Comments:

This function is useful for saving a series of status values in a single short or long variable. If any argument is invalid, the return value is invalid.

(See: Bitwise Parameters & Operations)

Examples:

a = SetBit(0, 1, 1);

In this simple example, the values for a will be 2 { 0b00000010 }. This is not a particularly useful example of SetBit, though. Most likely you will want to use it in a statement like the following:

b = SetBit(b, 2, 1);

In this case, bit number 2 will be set to 1. It is important to note, however, that if b is invalid, this statement will have no effect (i.e. it will not make b valid). A safer way to accomplish the setting of bit 2, then, might be to write

b = SetBit(PickValid(b, 0), 2, 1);

so that the b being invalid case is covered.


SetByte

(Engine-Level Function)

Description: | Writes a single byte to a buffer.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | GetByte | MakeBuff
Format: | SetByte(Buffer, Offset, Value)
Parameters: |
Buffer
Required. Any buffer expression giving the buffer to set. This buffer must already exist. It could be created by a function such as MakeBuff, or by assignment of a text constant.
Offset
Required. Any numeric expression giving the offset from the start of the buffer in bytes, starting from 0.
Value
Required. Any numeric expression giving the byte value to write at Offset bytes from the beginning of Buffer.
Comments: This statement may only appear in a script.

Example:

msg = "ABCDEF";
If MatchKeys(2, "g");
[
  SetByte(msg, 1, 65);
]

The value of msg will be "AACDEF" when the user presses "g" on the keyboard.


SetCertificateProperty

Description: | Sets a modifiable property on a stored certificate.
Returns: | Integer. Zero for success or a system error code.
Usage: | Script Only.
Function Groups: | Certificates
Related to: | AddCertificate | CheckCertificateChain | FindCertificate | GetCertificateInfo | ListCertificates | MakeSelfSignedCertificate | RemoveCertificate
Format: | SetCertificateProperty(MachineStore, StoreName, Thumbprint, Property, PropertyValue)
Parameters: |

MachineStore

Required Boolean. If TRUE (non-zero) attempts to find the certificate in a store in the Local Computer certificate hive. If FALSE (zero) attempts to find a certificate in a store in the Current User certificate hive.
StoreName
Required text. The name of the store in which to search for the certificate.
Thumbprint
Required. A binary buffer holding the SHA1 thumbprint of the certificate to locate.
Property
Required integer. The identifier of a property to set. Properties are identified by numbers.
PropertyValue
Required text. The text to which the property will be set.
Comments

This statement allows you to set the following properties:

Property Name | Property Parameter
Friendly Name | 0
Description | 1

Once a certificate has been created, the only properties that can be set are those that do not comprise the signed part of the certificate.

Example:

SetCertificateProperty(FALSE, "My", NewCertThumbprint, 0, "North Point");

This sets the certificate identified by NewCertThumbprint in the current user’s Personal store to have the friendly name "North Point". The intent is to create an alternative human-friendly means of certificate identification.


SetClock

(Engine-Level Function)

Description: | Sets the VTScada system clock and calendar.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Time and Date
Related to: | Seconds | Today
Format: | SetClock(Date, Time)
Parameters: |
Date
Required. Any numeric expression giving the new date, in days since 1 January 1970.
Time
Required. Any numeric expression giving the new time, in seconds since midnight.
Comments:

This statement allows the synchronization of the VTScada system clock / calendar with another clock / calendar. All pending timers, and all built-in statements and functions that depend on the system clock / calendar are adjusted to match.

This function can work only when VTScada is run with administrative privileges. (Specifically, under a Windows user with the SE_SYSTEMTIME_NAME privilege.)

Caution is necessary, because VTScada will not adjust times and dates stored in variables or files (VTScada does not know if a variable contains a number or time or date). I/O drivers which time and date stamp results will not adjust themselves retroactively. However, as each new action occurs, the new time and date will be used. This is because I/O drivers are not built-in functions, they are modules.

Example:

If ZEditField(10, 40, 110, 10, minPastHr, 2, 1, 1);
[
  currTime = Seconds();
  minPastHr = Cast(minPastHr, 0){ Type status (0 - 255) };
  minPastHr %= 60 { Valid range is from 0 - 60 };
  convTime = currTime { Seconds since midnight }
  - currTime % 24 { Seconds past the hour }
  + (minPastHr * 60){ New seconds past the hour };
  SetClock(Today(), convTime) { Set the system clock };
]

This takes a value that has been entered into an input field and sets the system clock by it. The date and hour remain unchanged, only the minutes are set.


SetCodeText

(Engine-Level Function)

Description: | Will modify a source code file to replace the text for a given CodeValue with the new text.
Returns: | Invalid on success, numeric error code otherwise.
Usage: | Script Only.
Function Groups: | Advanced Module, File I/O
Related to: |
Format: | SetCodeText(CodeValue, NewText)
Parameters: |
CodeValue
Required. Any code value giving the statement whose text is to be replaced..
NewText
Required. Any text or a buffer
Comments: The given source file must be present and have read/write privileges. This function does not immediately update the statement’s currently loaded module until that module is recompiled (usually upon a shutdown/restart cycle.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


SetCurrentFilter

This is a submodule of an Alarm List widget. This function can only be used when referring to an instance of an Alarm List that you have placed on a page.

Description: | Applies a filter that you define to an Alarm List widget.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarms
Related to: | None
Format: | AlarmListObj.SetCurrentFilter([Reserved, TextInDescription, TextInDescription_Case, TagName, TagName_UniqueID, TagName_Children, Area, Priority, Priority_orHigher, User, Reserved, Action, DateRange_Start, DateRange_End, Units, ShowShelved, ShowConfig, SearchString])
Parameters: |
Reserved
Optional. Set to Invalid
TextInDescription
Optional text. Filters for alarms with a matching description. Wild cards are allowed.
TextInDescription_Case
Optional Boolean. True if the text in the description filter is case-sensitive.
TagName
Optional text. Filter for alarms with a matching tag name. Wild cards are allowed.
TagName_UniqueID
Optional text. Filter for alarms with a matching unique ID value.
TagName_Children
Optional Boolean. Set to TRUE to include children of the tags.
Area
Optional text. Filter for alarms with a matching area value
Priority
Required numeric. Filter for alarms with a matching priority.
Priority_orHigher
Required Boolean. Set to TRUE to include alarms with a priority higher than that specified.
User
Required text. Filter for alarms handled by the matching user.
Reserved
Set to Invalid.
Action
Optional text. Filter for alarms with the matching action string (Trip, Rearm, Shelve, etc)
DateRange_Start
Optional timestamp. Filter for alarms later than this date and time.
DateRange_End
Optional timestamp. Filter for alarms earlier than this date and time.
Units
Optional text. Filter for alarms with the matching units.
ShowShelved
Optional Boolean. True to show shelved alarm records.
ShowConfig
Optional Boolean. True to show configuration records.
SearchString
Optional text. Search field string.

Comments:

Any property that you do not want to filter for should be set to Invalid.

Example:

{ The variable, SelectedArea, is assumed to be set by code not shown here. }
  If Watch(1, MyAlarmListObj, SelectedArea);
  [
    MyAlarmListObj.SetCurrentFilter(Invalid, Invalid, Invalid, Invalid, Invalid, Invalid, SelectedArea);
  ]


SetCurrentRecipe

(Recipe Book module)

Description: | Sets the current recipe and clears or updates the current version
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Recipe Book
Related to: | GetRecipes | GetVersions | GetCurrentRecipe | GetCurrentVersion | SetCurrentVersion |
Format: | RecipeBook.SetCurrentRecipe(NewVal[, PickFirstVersion])
Parameters: |
NewVal

Required text. The new value, to which CurrentRecipe should be set.

This must use the phrase key of the recipe name, not the displayed name in the current language. Refer to your language .CSV file to find the matching phase key.
Related information: Languages

PickFirstVersion
Optional Boolean. If TRUE (the default), the version is set to the alphabetically first version. If FALSE, the version is set to the alphabetically last version.
Comments:

"RecipeBook" must be a reference to a Recipe Book tag object, not the name of the tag.

The Parameter tags will be updated automatically for the newly set recipe.


SetCurrentVersion

(Recipe Book module)

Description: | Sets the version of the current recipe
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Recipe Book
Related to: | GetRecipes | GetVersions | GetCurrentRecipe | GetCurrentVersion | SetCurrentRecipe |
Format: | RecipeBook.SetCurrentVersion(NewVal)
Parameters: |
NewVal
Required numeric. The version to set.
Comments:

"RecipeBook" must be a reference to a Recipe Book tag object, not the name of the tag.

The Parameter tags will be updated automatically for the newly set version of the current recipe.


SetCursor

(Engine-Level Function)

Description: | Sets the mouse cursor type for the window.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics, Locator, Window
Related to: |
Format: | SetCursor(Type)
Parameters: |
Type
Required. Usually a numeric expression giving the cursor type to display according to the following table, but may also be a text argument giving the full path of the image file to be loaded as the cursor. Most of the common image files formats can be used. If giving the image file, the size of the cursor will be the system default.
Type | Cursor Type
-1 | Set the cursor to the parent window's cursor
0 | Normal Select (Standard arrow)
1 | Busy (Waiting hourglass)
2 | Text Select (Text I-beam)
3 | Precision Select (Crosshairs)
4 | Unavailable (Slashed circle)
5 | Move (Four-pointed arrow pointing north, south, east, and west)
6 | Diagonal Resize 2 (Double-pointed arrow pointing northeast and southwest)
7 | Vertical Resize (Double-pointed arrow pointing north and south)
8 | Diagonal Resize 1 (Double-pointed arrow pointing northwest and southeast)
9 | Horizontal Resize (Double-pointed arrow pointing west and east)
10 | Alternate Select (Vertical arrow)
11 | Working in Background (Standard arrow and small hourglass)
12 | Help Select (Standard arrow and small hourglass)
Comments: This statement will affect the cursor in the current window in which it is executed. The appearance of the cursor will depend on the current Windows™ cursor settings. The changed cursor will only be displayed within the client area of the window. Changing the cursor for a window will change the cursor for its child windows unless the child windows use SetCursor to change their cursor.

Example:

If editFlag EditText;
[
  SetCursor(2);
]

This is a script that might be executed prior to opening an editor window, for which a Text Select style cursor is desired.


SetDDEServer

(Engine-Level Function)

Description: | Sets the DDE topic name for a window.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | DDE
Related to: | DDE | DDEPoke | DDEShareAdd | DDEShareDel
Format: | SetDDEServer(Object, Title)
Parameters: |
Object
Required. Any object expression that identifies the window.
Title
Required. Any text expression for the new topic name.
Comments:

To ensure that proper DDE communication takes place, each window should have its own unique topic name. The default topic name is the title of the window.

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.


SetDefault

(Engine-Level Function)

Description: | Sets the default value for a variable.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | GetDefaultValue
Format: | SetDefault(Variable, Default)
Parameters: |
Variable
Required. Any expression for the variable value.
Default
Required. Any expression for the new default value.


SetDivert

(RPC Manager Library)

Description: | Informs RPC Manager that the synchronization state of a service has been sampled during synchronization, and service RPCs for the specified client should be buffered until synchronization completes. Subroutine call only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Network
Related to: | GetClientDiverts
Format: | \RPCManager\SetDivert(Service, IP [, OptGUID]);
Parameters: |
Service
Required. The name by which the service is known.
MachineName
Required. A machine name or IP by which the synchronizing client is known.
OptGUID
An optional GUID of the application in which the service instance is located. The default is the application to which the caller belongs.
Comments:

This module is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager, as shown in the "Format" section.

If the application you are developing is a script application, the module call must be prefaced by System\RPCManager, and the System variable must be declared in AppRoot.src.

This subroutine is only called by the service instance that is server during synchronization. It initiates service RPC caching on an auxiliary queue for the service. A service calls this after acquisition of the synchronizable state of a service to ensure that all service RPCs after the state has been sampled are preserved.

This also turns off server RPC diversion, allowing server RPCs to flow.

Related information:

RPC Manager Service


SetEditMode

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Sets the graphics edit mode for a window.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Editor, Window
Related to: | WinEditCtrl
Format: | SetEditMode(Object, Mode)
Parameters: |
Object
Required. Any object expression that identifies the window.
Mode
Required. Any numeric expression for the new edit mode:
Mode | Edit Mode
0 | Disable mouse actions
1 | Enable mouse actions
2 | Toggle mouse on/off


SetEnable

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Tell the Alarm Manager to enable or disable an alarm. This function handles the attribution of changes to a user based on the tag's metadata. Use instead of the older Enable function when writing new code.
Returns: | Invalid (see parameter, FeedBack)
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | Enable
Format: | \AlarmManager\SetEnable(TagName, AlarmObj, Disable, InhibitParm, FeedBack);
Parameters: |
TagName
Required. The name of the tag that owns the alarm.
AlarmObj
Required. An instance of the alarm module.
Disable
Boolean. Set TRUE to disable the alarm, FALSE to enable.
FeedBack
Numeric. Indicates the result of the action. Set to 1 if the alarm was enabled or disable, and 0 if no operation was performed.
Comments: The SetEnable subroutine always returns Invalid.


SetFileAttribs

(Engine-Level Function)

Description: | Sets the attributes of the specified file.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | File I/O
Related to: | GetFileAttribs
Format: | SetFileAttribs(FileName, Attributes, Mode)
Parameters: |
FileName
Required. Any text expression giving the name of the file. A known path alias for File-Related Functions may be provided in the form, :{KnownPathAlias}.
Attributes
Required. Any numeric expression which designates the attributes to be set. This parameter is formed by adding together numbers from the following table:
Value | Bit No | Attribute
0 | - | Normal
1 | 0 | Read only
2 | 1 | Hidden
4 | 2 | System
8 | 3 | Archive

Optionally if mode is 1 or 3, may be a timestamp.

(See: Bitwise Parameters & Operations)

Mode

Controls the action of this function.

0 or Invalid (Default) - The file attributes will be set according to the Attributes parameter.

1 - Date modified using local timestamp.

2 - Reserved. Do Not Use.

3 - Date modified using UTC timestamp.

Comments:

Four file attributes may be set by this statement. All attributes will be changed at once.

Mode 1 (local timestamp) expects a timestamp local to the server receiving the command.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

  If StrictlyNotEqual(NewFile, OldFile);
  [
    SetFileAttribs(Concat(MyPath, NewFile), 9);
    OldFile = NewFile;
  ]

The above statement will cause file NewFile to have its ReadOnly and Archive bit set every time its name changes.


SetHandle

(Engine-Level Function)

Description | Sets the position of graphics handles in a window.
Returns | Nothing
Usage | Script or steady state.
Function Groups | Graphics
Related to: |
Format: | SetHandle(Object)
Parameters |
Object
Required. Any object expression which identifies the window.


SetHelp

(Engine-Level Function)

Description: | Sets the help file name and (optionally) the context identifier for the window containing the specified object.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Help
Related to: | Help
Format: | SetHelp(Object, HelpFileName [, HelpContext])
Parameters: |
Object
Required. The object value of a module instance that is running inside the window whose help context is to be affected.
HelpFileName

Required. The file name of the help file to use if the user presses F1 while the specified window is the active window. If Invalid, the parent window of the specified window will be checked for a help file reference. This continues recursively until the top of the window tree is reached.

If no help file name is found, the default VTScada help file is used. The default help reference can be set by adding the variable "WEBHelp" to the [System] section of the Setup.INI file, or by using the EnableHelp statement.

The help file name may be any .CHM format help file, typically added to the VTScada installation folder. (The .HLP format is obsolete and will not open in modern versions of Windows.)
If you have created a NetHelp (DocToHelp format) or MadCapWebHelp (Flare format) help system, use the strings, "MyHelpFolder\NetHelp" or "MyHelpFolder\MadCapWebHelp" respectively, where MyHelpFolder points to the folder containing your custom help system.

To use the default VTScada Help system, enter simply: \DevHelpFile without quotation marks.

HelpContext

Optional help context. If absent or invalid, but the HelpFileName is valid, then the default home page of the help file or system is displayed when the user presses F1.

If valid and numeric, the help file is searched for a topic with a matching alias number and help is displayed for that topic. If there is no topic with a matching alias ID value, then NetHelp and MadCapWebHelp formats will open to the default home page. CHM formats will not open.

If valid and textual, and if the help file is .CHM format, then the help file is searched for an exact match on the text string in the topic index of the help file. If there is more than one text match, the index is positioned at the first partial string match. NetHelp and MadCapWebHelp formats will ignore a textual value for HelpContext and open to the default home page.

If the HelpFileName parameter is invalid, this parameter is ignored.

Comments:

The setting of help file name and context for a window performed by this statement overrides those specified by Window statement parameters. When this statement stops, the settings for an affected window revert to the state [if any] set up by the Window statement parameters. If more than one of these statements references the same window, the last one to start wins the race.

The object is usually, Self(); if this statement used in the context of a page module.


SetINIProperty

(System Library)

Description: | Given an INIFiles structure, this function sets the property with the specified name and section to the specified value. Does not affect the running system until WritePropertiesFile is called.
Returns: | Reference to the INIProperty structures for the specified section.
Usage: | Script Only.
Function Groups: | Configuration Management, Variable
Related to: | ReadPropertiesFile | WritePropertiesFile | GetINIProperty
Format: | System.SetIniProperty(pProperties, Section, Name, Value, Comment, pFail)
Parameters: |
pProperties
Required. An INIFiles structure.
Section
Required. The name of the section in which the property belongs.
Name
Required. The name of the property being modified.
Value
Required. The value to set for the given property.
Comment
An optional text expression for the comment to write. If invalid, the existing comment (if any) for the property will be used.
pFail
A pointer to a Boolean value. Will be set TRUE if the operation fails.
Comments: This function does not change the property in configuration - it only changes the value in the INIFiles structure, which is obtained using a call to ReadPropertiesFile.
The standard usage is to obtain the structure using ReadPropertiesFile, modify a value using SetINIProperty, then write the structure back to disk using WritePropertiesFile.

The INIFiles structure returned is as follows:

INIFiles Struct [
  FileName    { full path and file name to the settings file          };
  OEM         { TRUE if an OEM layer file                             };
  Workstation { Name of the workstation or invalid if global          };
  Layer       { Instance of application layer owning the file         };
  Dynamic     { TRUE if a dynamic property                            };
  Sections    { Dictionary of sections each element of which
                is an array of Property structures         };
  Changed     { User sets to true if the file has been changed,
                initialized to false                                  };
 ]

The INIProperty structure is…

INIProperty Struct [
    Name        { Variable name in the .startup/.dynamic file  };
    Value       { Simple value                                 };
    Comment     { Text comment if present in the file          };
    Hidden      { TRUE if not visible in Edit Properties GUI   };
  ];


SetInstanceName

(Engine-Level Function)

Description: | Set the name of an instance of a module.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Basic Module
Related to: | GetAccountID
Format: | SetInstanceName(Instance, Name)
Parameters: |
Instance
Required. The object value for which the name is to be assigned. Typically, Self() .
Name
Required. The text string name of the instance. Must be unique.
Comments:

Retained variables allow each separate instance of a module to retain its value on disk between VTScada executions or between instantiations of the module. Each instance must be assigned a name, and this SetInstanceName() function provides this facility.

If storing user-specific property settings, use the GetAccountID function to retrieve a unique identifier for the current user, to be used as part of the name.

Example:

Within a module that is to retain information on a user-by-user basis:

Init [
  If 1 Main;
  [
    SetInstanceName(Self, \SecurityManager.GetAccountID());


SetInstanceRefBox

(Engine-Level Function)

Description: | Programmatically, set the module reference box of a single module instance.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Invalid.
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Graphics, Advanced Module
Related to: | SetModuleRefBox
Format: | SetInstanceRefBox(Module, Left, Bottom, Right, Top)
Parameters: |
Module
Required. Any expression for the object value of the instance of the module.
Left
Required. Any numeric expression for the left side of the reference box for Module's graphics.
Bottom
Required. Any numeric expression for the bottom side of the reference box for Module's graphics.
Right
Required. Any numeric expression for the right side of the reference box for Module's graphics.
Top
Required. Any numeric expression for the top side of the reference box for Module's graphics.
Comments:

This function adds a way to set the module reference box of a single module instance programmatically. If a module has SetInstanceRefBox called for an instance of it, then SetModuleRefBox will not affect that instance.

Comparing the two functions, SetModuleRefBox provides a way to programmatically set the default size of a module whereas SetInstanceRefBox provides a way to set the size of a specific instance of a module.

In any of the parameters are omitted, or if one or more is invalid, the instance-specific reference box will be cleared.

Examples:

The following is a widget that will draw the image, which is specified by its full path name in the text parameter, at its native size:

{================== Image Widget ======================}
(
  ImageChoice <:"Select Image":> Text;
)
[
  Title = "ImageWidget";
  Shared UserMethods (LIBRARIES);
  bWidth  = 1  { default size is 1x1} ;
  bHeight = 1                         ;
  bObj         { bitmap object ref  } ;
]
Init [
  If Watch(1) WidgetMain;
  [
     ifelse(ImageChoice,
            bObj = MakeBitmap(ImageChoice),
            bObj = MakeBitmap("\Bitmaps\Icons\Question icon.bmp"));
    bWidth   = PickValid(BitmapInfo(bObj, 0), 1);
    bHeight = PickValid(BitmapInfo(bObj, 1), 1);
    SetInstanceRefBox(Self, 0, bHeight, bWidth, 0);
  ]
]
WidgetMain [

  GUIBitmap(0, 1, 1, 0 { Bounding box of image },
            1 - 0, bHeight, bWidth, 1 - 0, 1 { Scaling },
            0, 0 { No trajectory or rotation },
            1 { Bitmap is visible },
            0 { Reserved },
            4 { Left mouse button activates },
            0 { Focus ID number },
            0 { Focus trigger },
            bObj { Bitmap to show });
]


SetKeyParam

(Engine-Level Function)

Description: | The SetKeyParam function customizes various aspects of a session key's operations. The values set by this function are not persisted to memory and can only be used with in a single session. It is the VTScada analog of the CryptoAPI SetKeyParam call.
Returns: | Numeric, where 0 indicates success and a non-zero value indicates a system error code.
Usage: | Script Only.
Function Groups: | Cryptography
Related to: | DeriveKey | Decrypt | Encrypt | ExportKey | GenerateKey | GetCryptoProvider | GetKeyParam | ImportKey | TextEncode
Format: | SetKeyParam(Key, Param [, Value, Flags, Error])
Parameters: |
Key
Required. The handle to the key for which values are to be set.
Param

Required text or numeric. A parameter specifying the value to be set.

CAPI (Cryptography API) providers are specified using numeric identifiers. Values are defined in WinCrypt.h

CNG (Cryptography New Generation) algorithm providers are specified using text identifiers.

Value

An optional parameter containing the value to which the keys parameter is to be set. If omitted or invalid then the value 0 is used.

Warning: Accidentally passing a value that is meant to be a number but is actually stored as text, "42", will cause an error.

Flags
An optional parameter specifying the flags to be passed to CryptSetKeyParam. If omitted or invalid then the value 0 is used.
Error
Required. An optional variable in which the error code for the function is returned. It has the following meaning:
Error | Meaning
0 | Key parameter successfully set.
1 | Key or Param or Value parameters invalid.
X | Any other value is an error from CryptSetKeyParam.
Comments:

The allowable values for Param vary with the key type.

Certain modes of SetKeyParam take either a binary string of bytes or a text string. It is up to script code to convert the parameter to the appropriate representation depending on the mode used. As an example, when setting the IV, a binary string of bytes is expected, which is the same representation as a string in script code and this can be passed in directly. When setting ChainingMode, a text string with the desired mode is expected, for example “ChainingModeECB”. The underlying API expects this input as utf-16le characters, so script code must first convert this to null terminated utf-16le. This can be achieved using TextEncode:

SetKeyParam(Key,
            "ChainingMode",
            TextEncode(Concat("ChainingModeECB", MakeBuff(1, 0)),
                       Invalid,
                       "utf-8",
                       "utf-16le"),
            0,
            ErrOut)

Example:

[
  Constant KP_G = 12 { DSS/Diffie-Hellman G value };
]
Init [
  If 1 Main;
  [
    { Set the key parameter }
    SetKeyParam(Key2, KP_G, KeyG);
  ]
]


SetLibrary

(Engine-Level Function)

Description: | Sets the library for an application.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications
Related to: |
Format: | SetLibrary(Module, LibraryName)
Parameters: |
Module
Required. Any expression that identifies the module or object for which the library is to be set.
LibraryName
Required. Any module expression that identifies the library.
Comments: This statement may only appear in a script.


SetModuleRefBox

(Engine-Level Function)

Description: | Sets the default reference box for a module.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Graphics, Advanced Module
Related to: | GetModuleRefBox | GetXformRefBox | SetInstanceRefBox
Format: | SetModuleRefBox(Module, Left, Bottom, Right, Top)
Parameters: |
Module
Required. Any expression for the object value of the module.
Left
Required. Any numeric expression for the left side of the reference box for Module's graphics.
Bottom
Required. Any numeric expression for the bottom side of the reference box for Module's graphics.
Right
Required. Any numeric expression for the right side of the reference box for Module's graphics.
Top
Required. Any numeric expression for the top side of the reference box for Module's graphics.
Comments: A module's reference box defines an area that will exactly enclose all active graphics (graphics currently displayed) in the module before any rotations and trajectories have been applied. A module reference box, or MRB as it is sometimes called, is not a clipping region and objects can and often will extend outside of their MRB as a result of applied rotations or trajectories.
When a module is transformed, the transform is based on the size of the module as determined by its reference box. If the module switches states, the active graphics will change, thereby changing the MRB for that module. The result is that the transform will change such that graphic objects will grow or shrink, so that the module's reference box will always exactly fill the reference box of the transform. In the case of graphics that have had a rotation or trajectory applied to them, the graphics will be transformed correctly, but the MRB may no longer contain the objects in their modified positions.

This statement allows the user to set the reference box of a module to a constant size, so that as graphics become active and inactive, the transform will not cause the graphic objects to grow and shrink - since the transform is based on the module's reference box, and this is now fixed, the transform will be similarly fixed.

This call should be followed by a call to SaveModule, otherwise the module reference box change will only be written when the application containing this statement is stopped (in the case of base VTScada code this means when VTScada is shut down).
Great care should be exercised when using this statement, since the module reference box for the module itself is altered, not just the instance in which the statement is called. All instances of this module will have their reference box permanently changed.

Example:

Init [
  If 1 Main;
  [
    SetModuleRefBox(Self(), 0, 599, 799, 0);
  ]
]

This sets the current module's reference box to a fixed size equal to the default window size.


SetModuleText

(Engine-Level Function)

Description: | Sets the module's .SRC file information.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | SetModuleText(Module, Mode, Value)
Parameters: |
Module
Required. Any expression for the module or object value.
Mode
Required. Any numeric expression for the value to set
Mode | Value to set
0 | .SRC file name Mode 0 cannot be used to make a module have a .SRC file name in a different directory than where the module presently resides.
1 | Character offset to beginning of module definition
2 | Size of module definition in characters
3 | Character offset to first parameter declaration
4 | Character offset to first variable declaration
5 | Character offset to first state
6 | Character offset to first child module definition
7 | Character offset to beginning of variable declaration block
8 | Size of variable declaration block in characters
9 | Character offset to beginning of parameter declaration block
10 | Size of parameter declaration block in characters
11 | Full path and file name of .SRC file
Value
Required. Any expression for the value the module information specified by Mode will be set to.


SetOneParmText

(Engine-Level Function)

Description: | Sets the text for one parameter of a function.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | SetOneParmText(\Code, Index, Text)
Parameters: |
Code
Required. Any expression for the code value of the statement.
Index
Required. Any numeric expression for the parameter number to change, beginning with 0.
Text
Required. Any text expression. The text in the .SRC file for the parameter indicated by Code and Index will be replaced by Text.


SetOPCData

(Engine-Level Function)

Description: | Sets an item value in the VTScada OPC Server.
Warning: | This function should be used only by advanced programmers.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Network
Related to: | OPCServer
Format: | SetOPCData(BranchHandle, ItemName, Value, Quality, Timestamp)
Parameters: |
BranchHandle
Required. A handle returned from an OPCServer call.
ItemName
Required. The internal name for the OPC item being set. It does not necessarily correspond to the OPC item ID. It does correspond to what the OPCGetInternalName callback module returns for a given OPC item ID.
Value
Required. The new value of the item (numeric or text).
Quality
Required. The quality of the value. Should be one of the following:
Quality | Meaning
0x00 | Bad
0x04 | Bad - Configuration Error (The item has been deleted)
0x40 | Uncertain - Questionable quality
0xD8 | Good but local override
0xC0 | Good
0xC3 | Good but constant value
Timestamp
Required. The UTC timestamp corresponding to the value. Will default to the current time if Invalid.
Comments: Returns TRUE if the item being updated is currently included in an OPC client group, or FALSE if not.

Example:

  SetOPCData(Handle    { Returned from an OPCServer call },
             "myitem1",
             23.1,
             0xC0,
             CurrentTime() + TimeZone(0));

This example updates the value of an OPC item with the internal name "myitem1" to be 23.1, with good quality and the current time as the timestamp.


SetOverride

(Engine-Level Function)

Description: | Allows the overriding of OpCodes with a specified script module within a static module tree.
Warning: | This statement should be used by advanced users only. Effective use of this function requires a thorough understanding of VTScada programming.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Advanced Module
Related to: | GetOverrides
Format: | SetOverride(TargetModule, OpCode, [Override, Recursive])
Parameters: |
TargetModule
Required. Any expression that can be resolved to the module value that will be modified.
OpCode
Required. Any numeric value that represents the built-in function to replace.
Override
The module value that will be called in place of OpCode. If invalid or missing, any existing overrides of OpCode in TargetModule will be removed.
Recursive
Required. If true, the OpCode will be replaced with calls to the override function in all of the child modules of the target module. Otherwise, only the target module will be altered. Defaults to true.
Comments: Adds the ability to override a built-in function inside a module with a call to a different module. The purpose of this feature is to help with testing of modules that use time, streams, etc. so that these functions can be overridden with more controllable inputs.


SetParameter

(Engine-Level Function)

Deprecated. Do not use in new code.

Description: | Sets a parameter in a statement.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: |
Format: | SetParameter(Statement, ParmNum, ParmType, Value)
Parameters: |
Statement
Required. Any expression for the statement value. May be a code value or a function value.
ParmNum
Required. Any numeric expression for the parameter number to change, beginning with 0.
ParmType
Required. Any numeric expression for the VTScada Value Types of the new parameter.
Value
Required. Any expression for the new parameter’s value.
Comments: This statement is used to modify the code for a function. Does not have proper support for longs; when the function is called to store a #VTypeLong, it interprets the parameter as a short.


SetParmText

(Engine-Level Function)

Description: | Sets the text for the parameters of a function.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Advanced Module
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetStateText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | SetParmText(\Code, Text)
Parameters: |
Code
Required. Any expression for the code value of the statement.
Text
Required. Any text expression. The text in the .SRC file for the parameters of Code will be replaced by Text.
Comments: None


SetParserParm

(Engine-Level Function)

Description: | Sets the value for the last parameter on the parser stack and returns its own error code.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Numeric error code
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications
Related to: | Compile
Format: | SetParserParm(ParserStack, OpCode, Value, Offset)
Parameters: |
ParserStack
Required. Any expression for the parser stack value returned by the compiler.
OpCode
Required. Any numeric expression for the type of parameter to set as given by the following table
Opcode | Parameter Type
0 | Integer
1 | Double
2 | Text
3 | Variable
Value
Required. Any expression. It will be evaluated as the type specified by Opcode.
Offset
Required. Any numeric expression for the number of characters read from the stream at this point (i.e. the value returned in the last parameter of the Compile function).
Comments: The return value is the error code for this function or 0 if no error.


SetRefRect

(Engine-Level Function)

Description: | Sets the first four constant parameters of a layered graphic statement.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Graphics
Related to: |
Format: | SetRefRect(CodePointer, Left, Bottom, Right, Top)
Parameters: |
CodePointer
Required. Any expression for the code pointer value which identifies the graphics statement.
Left
Required. Any numeric expression for the left side coordinate.
Bottom
Required. Any numeric expression for the bottom side coordinate.
Right
Required. Any numeric expression for the right side coordinate.
Top
Required. Any numeric expression for the top side coordinate.
Comments: This statement affects the .SRC file as well.


SetRemoteValue

(RPC Manager Library)

Description: | This subroutine sets the specified variable within an application instance on a workstation to the specified value. Subroutine call only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Network
Related to: | ConnectToMachine | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | Send
Format: | \RPCManager\SetRemoteValue(VariableScope, Variable, Value, Name [, OptGUID])
Parameters: |
VariableScope
Required. The scope in which to find the variable.
Variable
Required. The name of the variable.
Value
Required. The value to set for the variable. Subject to the restriction of the type of values that can be set via RPC.
Name
Required. Any of the names or IPs by which the workstation is known to the RPC Manager.
OptGUID
Any optional parameter that provides the GUID of the application in which the variable is to be set. The default is the application to which the caller belongs.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
If the 16-byte binary format of the GUID is not known, the GetGUID function may be used to obtain it.

Example:

If 1 Main;
[
  \RPCManager\SetRemoteValue("\" { root of app context },
  "DispMgrFullScreen" { var name },
  1 { value }, "TestMachine");
]

This will cause the variable (flag) DispMgrFullScreen, which is found in the root scope of the application, to be set to 1 on the machine called TestMachine.

Related information:

RPC Manager Service


SetReturnValue

(Engine-Level Function)

Description: | Sets the return value of a specified object if the object is not currently running a Return() statement in steady state.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Basic Module
Related to: | HasReturnStatement | Return
Format: | SetReturnValue(Object, Value[, Resettable])
Parameters: |
Object
Required. A reference to the object whose return value is to be changed.
Value
Required. The new return value.
Resettable
Optional Boolean. Defaults to TRUE. If present and set to FALSE, the return value will not reset to INVALID until another Return statement specifies otherwise. See comments.
Comments:

Returns 1 if successful, 0 on failure, or Invalid if the first parameter cannot be resolved to an object.

When an object is called within an If statement and its return value has been set using SetReturnValue, then the object’s return value will become Invalid when the If statement's script executes. This can be seen with the automatically resetting functions.

This behavior is not desirable for some called modules. The same goes for some modules that set their return value from script using Return. For these, set the parameter Resettable to FALSE.


SetShelved

(Alarm Manager module)

Description: | AlarmManager subroutine that handles the shelving and unshelving of alarms.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm Manager
Related to: | IsShelved | SetSuppressed
Format: | \AlarmManager\SetShelved(AlarmName, Shelve[, ExpiryTime, Timestamp, AccountID, Device, MachineID, Config]);
Parameters: |
AlarmName
Required.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Shelve
Required. Boolean that indicates whether to shelve (TRUE) or unshelve (FALSE) the alarm.
ExpiryTime
Optional. The UTC timestamp for when the alarm should automatically unshelve.
Timestamp
Optional. The UTC timestamp of this event. Defaults to now.
AccountID
Optional. ID of the user who initiated this event. Defaults to the user currently signed in at the workstation.
Device
Optional. The name of the client device calling this function.
MachineID
Optional. The machine ID of the workstation calling this function.
Custom
Optional. Structure of custom fields to log.
(Refer to Alarm API Structure Definitions)
FromPLC
Optional Boolean. Used only with the PLC Alarm tag. TRUE when Shelve or Unshelve took place in the PLC.
Auto
Optional Boolean. TRUE if this is the result of an automated action such as that of unshelving on time expiry. Defaults to TRUE.
Config
Optional cfg structure. To pre-shelve an ad-hoc alarm, Config.Adhoc must be set to TRUE.(Default = Invalid)
Comments:

AlarmManager.SetShelved supports updating alarm information while the alarm is shelved by passing in new data. For example, use SetShelved to update the ExpiryTime.

Examples:

\AlarmManager.SetShelved(AlarmName, TRUE, CurrentTime(1) + 300);


SetStateText

(Engine-Level Function)

Description | Sets the information about the text of a state in a .SRC file.
Warning | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns | Nothing
Usage | Script or steady state.
Function Groups | Compilation and On-Line Modifications, States
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetTransitText | SetVariableText | TextOffset | TextSize
Format: | SetStateText(State, Mode, Value)
Parameters |
State
Required. Any expression for the code value of the state.
Mode
Required. Any numeric expression for the parameter to set in the state
Mode | Parameter to set
0 | Character offset to beginning of state
1 | Size of state text in characters
2 | Character offset to first statement text

Value

Required. Any numeric expression giving the new value (as determined by Mode) for the state.

Comments:

None


SetSubnetPriority

(RPC Manager Library)

Description: | This module enables setting the network priority configuration during runtime.
Warning: | This statement should be used by advanced users only. It will affect all applications on the local workstation.
Returns: | A wait object instance.
Usage: | Script only.
Function Groups: | Network
Related to: | GetSubnetPriority |GetLastUsedSubnet | GetPreferredSubnet
Format: | SetSubnetPriority([Address])
Parameters: |
Address
Optional. Invalid, or an array of strings containing the CIDR representation of the RPC subnets in the order of the desired network priority configuration.
Comments:

Any setting done through this module is lost on restart of VTScada.

The behavior of SetSubnetPriority is undefined until the returned wait object goes invalid.

The provided values are expected to be valid CIDR Closed Classless Inter-Domain Routing format strings. Overlapping subnet addresses are not supported, and have undefined behavior. If a value of Invalid is provided, the network priority configuration of the system is cleared and RPC will return to a round-robin configuration.

(See: [RPCMANAGER-NETPRIORITY] Section)


SetSuppressed

(Alarm Manager module)

Description: | AlarmManager subroutine that handles the suppressing and unsuppressing of alarms.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Alarm Manager
Related to: | Commission | EvaluateAlarm
Format: | \AlarmManager.SetSuppressed(AlarmName, Suppress[, Timestamp, Custom, FromPLC, Description])
Parameters: |
AlarmName
Required.

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

Suppress
Required. Boolean that indicates whether to suppress (TRUE) or unsuppress (FALSE) the alarm.
Timestamp
Optional numeric. The UTC timestamp of this event. Defaults to now.
Custom
Optional structure. A structure of custom fields to log.
FromPLC
Optional Boolean. Used only with the PLCAlarm tag. True if unsuppress events happened in the PLC.
Description
Optional. If used, it supersedes the Description that is typically retrieved from the config struct (CfgStructure) of Commission.
Comments:


SetSyncComplete

(RPC Manager Library)

Description: | Informs RPC Manager that service synchronization is complete as far as the local service instance is concerned. Subroutine call only.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Network
Related to: |
Format: | \RPCManager\SetSyncComplete(Service [, OptGUID, Value]);
Parameters: |
Service
Required. A name by which the service is known.
OptGUID
An optional parameter indicating the GUID of the application in which the service instance is located. The default is the application to which the caller belongs.
Value
An optional Boolean that will indicate the completion state (1 default).
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.

Related information:

Client Changes


SetTransfer

(Engine-Level Function)

Description: | Sets the destination for an action.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, States
Related to: |
Format: | SetTransfer(Action, Destination)
Parameters: |
Action
Required. Any expression for the code value of the action.
Destination
Required. Any expression for the code value of the destination state.
Comments: none


SetTransitText

(Engine-Level Function)

Description: | Sets the information about the document file definition of an action (predicate).
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetVariableText | TextOffset | TextSize
Format: | SetTransitText(Action, Mode, Value)
Parameters: |
Action
Required. Any expression for the code value of the action. This corresponds to value type VTScada Value Types.
Mode
Required. Any numeric expression for the parameter to set in the action:
Mode | Parameter
0 | Script size in characters
1 | Character offset of first script statement
2 | Trigger size in characters
3 | Character offset to trigger
4 | Destination size in characters
5 | Character offset to destination
Value
Required. Any numeric expression giving the new value for the parameter.
Comments: This statement may only appear in a script.


SetUserLanguage

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Changes the user's current session language to any of the languages currently enabled in the application. Useful for dynamic language switching.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: |
Format: | SetUserLanguage(LanguageCode)
Parameters: |
LanguageCode

Required text. The code for the language you want to start using ("EN", "FR", etc.)

The language must be enabled for the application.

Comments:

Language codes in use within an application can be seen in the Application Configuration dialog, Languages page.

This function cannot be used in tags because they will not have access to the user's current session.

Example:

  If WinButton(232, 148, 412, 100,
               0          { normal appearance },
               "English " { label },
               1          { focus id enables button },
               0          { default system font },
               ToggleVal  { monitor state});
  [
    \SetUserLanguage("EN");
  ]

  If WinButton(232, 198, 412, 150,
               0          { normal appearance },
               "French "  { label },
               1          { focus id enables button },
               0          { default system font },
               ToggleVal  { monitor state});
  [
    \SetUserLanguage("FR");
  ]


SetVariableClass

(Engine-Level Function)

Description: | Sets the class number of a variable and returns its previous class number.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | VariableClass
Format: | SetVariableClass(Variable, Class)
Parameters: |
Variable
Required. Any expression for the Variable to set.
Class
Required. Any numeric expression for the class. It must be in the range of 0 to 65535.
Comments: The class number for a variable defaults to 0.

Example:

If ! classSetFlag;
[
  SetVariableClass(FindVariable("newVar", Self(), 0, 1), 20);
  classSetFlag = 1;
]

This sets the class of variable newVar to 20.


SetVariableText

(Engine-Level Function)

Description: | Sets information about the document file definition of a module.
Warning: | This statement should be used by advanced users only since irrevocable alteration of your application may occur.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | TextOffset | TextSize
Format: | SetVariableText(Variable, Mode, Value)
Parameters: |
Variable
Required. Any expression for the Variable value.
Mode
Required. Any numeric expression for the variable to set:
Mode | Expression Variable
0 | Character offset to variable declaration
1 | Variable declaration size in characters
Value
Required. Any numeric expression giving the new value for the variable.


SetVariableType

(Engine-Level Function)

Description | Sets the data type for the variable, so that only values of that data type can be stored in the variable.
Warning | This statement should be used by advanced users only.
Returns | Nothing
Usage | Script Only.
Function Groups | Compilation and On-Line Modifications, Variable
Related to: | GetVariableType | CrossReference
Format: | SetVariableType(Variable, Value)
Parameters |
Variable
Required. A Variable handle, such as would be returned from the FindVariable or AddVariable functions.
Value
Required. The type that values put into this variable should be cast to.
Comments Casts the variable’s value to the given type. If the cast cannot be performed, the variable’s type will be set to Invalid.
The implementation of this function is very similar to SetVarMetadata.


SetVarMetadata

(Engine-Level Function)

Description: | Every variable object contains an embedded value. This function is used to set those values.
Warning: | This statement should be used by advanced users only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Dictionary
Related to: | GetVarMetadata | FindVariable | AddVariable
Format: | SetVarMetadata(Variable, Value)
Parameters: |
Variable
Required. A Variable handle, such as would be returned from the FindVariable or AddVariable functions.
Value
Required. Any value to store within the variable’s metadata.
Comments: Commonly used in conjunction with SetVarMetadata, FindVariable or AddVariable. Note that type data for each variable is stored within the variable using metadata.

Example:

<
TestMod
[
  X;
  Y;
  Var;
]
Main [
  If ! Valid(X);
  [
    X = "This is the value of X"
    Var = FindVariable("X", Self(), 0, 0);
    SetVarMetadata(Var, "This is the metadata in variable X");
    Y = GetVarMetadata(Var);
  ]
  ZText(50, 100, Concat("X: ", X), 14, 0);
  ZText(50, 120, Concat("Y: ", Y), 14, 0);
]
>


SetVicParms

(Engine-Level Function)

Description: | Sets parameters for the VTScada Internet Client.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | VTScada Internet Client
Related to: |
Format: | SetVicParms(ReadTimeout, SessionTimeout, Mode[, AllowedOrigins])
Parameters: |
ReadTimeout
Required. This is the length of time in seconds that the client will wait for the server to respond. Has a minimum of 5 seconds and a default of 15.
SessionTimeout
Required. This is the length of time in seconds that the server will wait for the client to respond. Has a minimum of 10 and a default of 60.
Mode
Required. VIC connection mode values are as follows (Defaults to 0)
Mode | Meaning
0 | legacy
1 | priority
2 | sticky
AllowedOrigins
Optional. An array of the names of possible hosts that Anywhere clients will connect from. The VIC server will not communicate with Anywhere clients running from hosts not in that array.
Comments:

This module returns 1 if the parameters were set or Invalid if not.
Note that the changes made by this statement do not affect current VTScada Internet Connections. Only new connections will use the changed parameters. This statement is used internally by the VTScada System layer. Any changes made by this statement will be overwritten by the VTScada System layer on startup of the VTScada System layer and upon change of any setting in the Internet Client dialog.

Setting either the ReadTimeout or the SessionTimeout to values outside the recommended guidelines can have unpredictable effects on the ability of clients to maintain a reliable communication session with the server.

For the Anywhere Client, all entries in the server list are automatically added to the array of AllowedOrigins. Additional hosts may be added by specifying HostName = 1 in the [Clients-AdditionalAllowedOrigins] section of Setup.INI.


SetWSDL

(System Library)

Description: | Connects a Realm with a WSDL file and a set of VTScada modules to enable a web service interface.
Returns | Numeric (0 for success, 1 for failure)
Usage: | Script Only.
Function Groups: | XML
Related to: | RemWSDL | XMLProcessor | XMLAddSchema | XMLParse | XMLWrite
Format: | System.Webservice\SetWSDL(WSDLFilePath, Realm, CallScope, Service[, pResponse, XSDFileName, WSDrvrVarName, AdditionalSchemas, AuthenticationModule])
Parameters: |
WSDL File Path
Required. This is a file path that indicates where the WSDL file to be used for this service is located. The file path must be encoded in URL format. Only one WSDL file can be declared and it must be passed in the first parameter.
Realm
Required. The name of the VTScada Realm which will be used to expose the web service. Only one Realm can be specified and it must be passed as the second parameter.
Call Scope
Required. An instance (object) of the module in which all of the modules to be called are nested. This provides the scope for the remote module calls by the WebService engine. Only one call scope object can be specified and it must be passed as the third parameter.
Service
Required. The name of the web service to be presented as portrayed in the WSDL's Service tag. This is a string that must match the "name" attribute of the representative Service tag and tells the SetWSDL function where to start searching for data.
pResponse
Optional. A pointer to a variable that will be loaded with the error description should SetWSDL fail. This description takes the form of a single human readable string. The variable will be set to invalid if no error occurs.
XSDFileName
Optional text. File name for the output XSD file. If not specified, a temporary file is used.
WSDrvrVarName
Optional text. Name of variable to be added into the call scope. Useful if setting multiple WSDL/Realms into same scope.
AdditionalSchemas
Optional dictionary. If used, contains a dictionary of additional schemas required by the WDSL document to allow correct validation of it. The keys of the dictionary are the namespaces and the values are the paths to the files containing each schema.
AuthenticationModule

Optional text. If supplied, this is the name of a module, to be found in CallScope, that will be called when a SOAP request for the SOAP service is made, in order to obtain authentication credentials from the SOAP payload. See discussion in the Comments section.

Comments:

Linkage is first applied between the WSDL file and the VTScada modules by generating an XML schema using the WSDL and the parameters provided to this function. The Realm's address is then registered with the VTScada HTTP server to connect the whole thing to the network.

Inclusion of the parameter, pResponse is recommended, for the sake of obtaining error messages when debugging.

AuthenticationModule, if supplied, must be a subroutine and have the following format:

AuthModule(SOAPPackage, pUsername, pPassword, pPrivilege);

where:

SOAPPackage

Is the SOAP payload as an XML node tree

pUsername

Is a pointer to a variable that the AuthModule should store the username extracted from the SOAP payload.

pPassword

Is a pointer to a variable that the AuthModule should store the password extracted from the SOAP payload

pPrivilege

Is a pointer to a variable holding the privilege that the user account must have in order to execute the methods contained in the SOAP payload.

The AuthModule must provide a privilege, otherwise the request will be rejected.

An example AuthModule might look like the following:

]

Authenticate
(
  SOAPPackage { The SOAP payload as an XML node tree };
  pUsername   { Where to store the username };
  pPassword   { Where to store the password };
  pPrivilege  { Where to store a privilege };
)

Authenticate [
If 1;
[
  *pUsername = SOAPPackage\Envelope\Header\TestHeader\#attribs["UserID"];
  *pPassword = SOAPPackage\Envelope\Header\TestHeader\#attribs["Password"];
  *pPrivilege = AppPrivSOAP;
  Return();
]

Example:

Init [
  If Watch(1);
  [
    ServiceActive = System.WebService\SetWSDL(
       "file://C:/vts/StationExample/TagQueryServices.wsdl",
       "QueryServicesRealm",
       Self,
       "TagQueryServices",
       &ErrMsg);
  ]
]


SetXLoc

(Engine-Level Function)

Description: | Sets the X screen location of the locator (mouse).
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Graphics, Locator
Related to: | SetYLoc | XLoc | YLoc
Format: | SetXLoc(X)
Parameters: |
X
Required. Any numeric expression giving the new X coordinate of the locator (mouse) on the screen.
Comments: This statement has no effect if the locator is not installed.

Example:

If XLoc() < 400;
[
  SetXLoc(400);
]

This action keeps the cursor in the right 400 pixels of the screen.


SetYLoc

(Engine-Level Function)

Description: | Sets the Y screen location of the locator (mouse).
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Graphics, Locator
Related to: | SetXLoc | XLoc | YLoc
Format: | SetYLoc(Y)
Parameters: |
Y
Required. Any numeric expression giving the new Y coordinate of the locator (mouse) on the screen.
Comments: This statement has no effect if the locator is not installed.

Example:

If YLoc() > 300;
[
SetYLoc(300);
]

This action keeps the cursor in the top 300 pixels of the screen.


ShellTemperatureCorrection

(Function Library)

Description: | Returns a coefficient to adjust the calculation of volume within a tank.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Oil & Gas
Related to: | TableInterpolation
Format: | ShellTemperatureCorrection(Insulated, LiquidTemp, AirTemp, VolRefTemp[, Material, CoEIn ErrorTag])
Parameters: |
Insulated
Required Boolean. A flag to indicate whether the tank is insulated.
LiquidTemp
Required numeric. The temperature of the liquid in the tank measured in degrees Fahrenheit.
AirTemp
Required numeric. The ambient air temperature measured in degrees Fahrenheit.
VolRefTemp
Required numeric. The reference temperature for the measured volume measured in degrees Fahrenheit.
Material

Optional numeric. An integer representing one of the following materials:

  • 0 for Carbon Steel
  • 1 for 304 Stainless steel
  • 2 for 316 Stainless steel
  • 3 for Monel.

Should be left blank if a custom coefficient of linear expansion is used.

CoEIn
Optional numeric. A coefficient of linear expansion measured in units of in/(in F) that will override the internal coefficient if a material is selected.
ErrorTag

Deprecated - for diagnostics at configuration time only, not for operations.

Optional tag object. If provided, this will be set to the error value. Error values are as follows:

0 | Success
1 | No Material or CoE provided
2 | No Liquid temperature provided
3 | No Reference temperature provided
4 | Insulation parameter not specified
5 | No Air temperature provided
Comments:

The function computes a shell temperature correction factor based on the American Petroleum Institute Manual of Petroleum Measurement Standards guidelines.

This factor is used to correct volume measurements due to expansion or contraction of the tank from its measured reference volume.


ShiftStream

(Engine-Level Function)

Description: | Inserts or deletes characters from a stream and returns its own error code.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Stream and Socket
Related to: | Seek | StreamEnd
Format: | ShiftStream(Stream, Pos, Offset)
Parameters: |
Stream
Required. Any expression giving the stream to shift.
Pos
Required. Any numeric expression giving the stream position to seek to before beginning the shift.
Offset
Required. Any numeric expression giving the number of characters to insert. If this is negative, characters will be deleted.
Comments: The returned value is true if successful, false if not.


ShowLexicon

(VoiceTalk Module)

Description: | Displays a SAPI text-to-speech engine lexicon dialog to permit modification of pronunciation. This function will return immediately, and the lexicon window will be managed in its own thread, preventing the calling thread from being blocked.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Speech and Sound
Related to: | Configure | GetDevices | GetVoices | Reset | Speak | VoiceTalk
Format: | VoiceTalkStream\ShowLexicon([Title])
Parameters: |
VoiceTalkStream
Required. A speech stream returned from VoiceTalk.
Title
An optional parameter that is any text expression to display in the title bar of the dialog box.
Comments: This function spawns a new thread to show the lexicon, so it will not block other statements from executing.
The pronunciations are stored in a file known as a "Lexicon". This file is stored in the VTScada directory. It is therefore available to all users and all VTScada applications. Changes made will affect all instances of VTScada applications that use speech.
Each time this window is opened, the lexicon is refreshed from disk. When the dialog is closed, the lexicon is written back to disk.
On any single installation of VTScada, only one lexicon dialog will be displayed at any time, regardless of how many applications support speech.
Any word may be entered into the lexicon with a custom pronunciation. A word is any set of letters with no whitespace (i.e. no spaces or tabs) within it. Words are case-sensitive. For example, if the word "VTS" is entered with the phonetic spelling "V T S", the way the word "vts" will sound will not be affected.

Example:

sHandle = \VoiceTalk();
If Valid(sHandle) && ZButton(10, 40, 110, 10, "Pronounce", 1);
[
  sHandle\ShowLexicon("Modify Pronunciation");
]

When the button is pressed, the lexicon dialog for the text-to-speech engine open on the SAPI text-to-speech stream will be displayed.


ShowPage

(Display Manager Library)

Description: | When called with a Page Name, will cause that page to display in the caller's display session context.
Returns: | Object reference
Usage: | Script Only.
Function Groups: | Graphics
Related to: | StopPage | ClosePopUp
Format: | \DisplayManager.ShowPage(PageName[, ForceWin, Parm0, ... Parm99]);
Parameters: |
PageName

Required. Any text expression for the page to show. This is the name of the module as declared in AppRoot.

If referencing a page in a subordinate application, prepend the name of the subordinate tag. For example, "SubTagName\Overview".

ForceWin
Optional. Any Boolean value, which if valid and true, requests a new window for the page.
Parm0 through Parm99
Optional. Any parameters to be passed to the page as it is opened.
Comments:

The page's window flags will have priority over the value of ForceWin. A page configured to never open in a pop-up won't, even though you set ForceWin to TRUE. The currently signed-in user's security privileges are checked to ensure they have the right to view the page before VTScada opens it.

Returns the window object that calls the page.

To determine whether a page is already open before calling this function use:

NumInstances(\PageModuleName)

... where PageModuleName is the name of the page module.

Pages that are configured to always open in a window (popup) will always open in a new window. Pages whose behavior is set as "Normal" will open in the same window.

Examples:

If IconPressed[#AlarmIcon];
[
  { Alarm icon -- switch to alarm page if clicked }
  \DisplayManager\ShowPage("AlarmPage");
]


ShowPage2

(Display Manager Library)

Description: | Opens the page specified in PageName
Returns: | Object reference
Usage: | Script Only.
Function Groups: | Graphic
Related to: | StopPage | ClosePopUp | ShowPage
Format: | \DisplayManager.ShowPage2(PageName[, Popup, PageParms, DisplayRoot, UpdateSamePopup, DisplayIndex])
Parameters: |
PageName
Required. Name of page to be displayed.
Popup
Optional boolean. If TRUE, it requests the page be opened as a popup if allowed. Defaults to FALSE.
PageParms
Optional. Array of parameters for the Page.
DisplayRoot
Optional. Represents the display device instance.
UpdateSamePopup
Optional. If the current page is the same as NewPage but with different parms, set this to TRUE to update the current page's parms, or FALSE to open a new popup. Defaults to FALSE.
DisplayIndex
Optional integer. In a multi-monitor environment, the index value of the display instance on which the page should be displayed. Defaults to the caller's display index.
Comments:

...

Example:

If we consider a 3x2 multi-monitor environment, when the alarm icon is clicked on any monitor, the AlarmPage will always be displayed on the 3rd monitor.

If IconPressed[#AlarmIcon];
[
  { Alarm icon -- switch to alarm page if clicked }
  \DisplayManager.ShowPage2("AlarmPage" { Name of the page },
FALSE { not a popup },
ParmsArray { page parameters },
GraphicsInstance [Display Device Instance],
FALSE [to not update existing page's parameters],
3 { Index of display instance};)
]


SilenceSound

(Alarm Manager module)

Description | This subroutine will silence the current sounding alarm.
Returns | Invalid
Usage | Script Only.
Function Groups | Alarm
Related to: |
Format: | \AlarmManager\SilenceSound();
Parameters | None
Comments | The SilenceSound subroutine always returns Invalid. It will silence alarms only if called by a valid session Closed A unique identifier for an instance of an application. See: Session IDs in the RPC Manager chapter.. If called by a non-session, nothing will be silenced unless this function is called via \GetUserSession(TRUE)\SilenceSound(), which will silence the alarms in the root session. See also: ApplyMuteSilencePerComputer ApplyMuteSilencePerUser


SimpleOpChange

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Immediately deploys a single parameter change on a single tag without disturbing any other tag
Returns: | Object
Usage: | Script Only.
Function Groups: | Configuration
Related to: | OpChange | GetTagConfiguredParameters | ModifyTags
Format: | \SimpleOpChange(TagName, NewValue, ParameterName)
Parameters: |
TagName
Required. The full name of the tag, in which the parameter will be changed.
NewValue
Required. The new value for the parameter.
ParameterName
Required. The name of the parameter that is to be changed.
Comments: While a direct call to OpChange is more efficient (it allows, for example, more than one parameter to be changed in the same operation), this function has a parameter set more like the older calls. The object value being returned will go invalid when the asynchronous operational change is complete.
This function is declared in the VTS Library layer.


SimulateMouse

(Engine-Level Function)

Description: | Sets the pointer location and then sends a button press with modifiers such as Ctrl, Shift or Alt.
Returns: |
Usage: | Script Only.
Function Groups: | Graphics,
Related to: | SetXLoc| SetYLoc
Format: | SimulateMouse(Root, mouseX, mouseY, MouseButtons, ModifierKeys)
Parameters: |
Root
Required. The window object within which the mouse should point.
mouseX
Required. Any numeric expression for the horizontal location of the mouse pointer
mouseY
Required. Any numeric expression for the vertical location of the mouse pointer.
MouseButtons

Required. Any numeric expression for the mouse button(s) to be simulated.

Bit | Value | Mouse Button
-- | 0 | no buttons
2^0 | 1 | left down
2^1 | 2 | right down
2^2 | 4 | middle down
2^6 | 64 | release any buttons, as specified above, in the same call to SimulateMouse()
2^7 | 128 | delete key
ModifierKeys

Required. Any numeric expression for the keyboard modifier to be applied to the mouse click. See comments.

Bit | Value | Modifier Key
-- | 0 | no key
2^0 | 1 | shift
2^1 | 2 | control
2^2 | 4 | Alt
2^3 | 8 | Left
2^4 | 16 | Right
2^5 | 32 | Up
2^6 | 64 | Down
Comments:

Similar to SetXLoc and SetYLoc, but all in one, plus mouse buttons and modifier keys. Used primarily for testing.

Only a single modifier can be specified in any call.

The key is not released automatically, but rather is release when called again with bit 15 (0x8000) set. For example, SimulateMouse(x, x, 1) sets shift and SimulateMouse(x, x, 0x8001) releases shift.

Examples:

...
mouseX = 100;
mouseY = 150;
DblClick(mouseX, mouseY);
...
<
{======================== DblClick ============================}
{ Simulates a double click of the left mouse button            }
{==============================================================}
DblClick
(
mouseX              { Left Mouse Coord                       };
mouseY              { Top Mouse Coord                        };
)
[
  Done = FALSE;
  Phase = 0;
  Constant #Btn    = 0x01; { Left click           }
  Constant #Btn_Up = 0x40; { release button       }
  Constant #Key    = 0x00; { No keyboard modifier }
]
First [
  If Timeout(!Done, 0.1);
  [
    Case(Phase,
      { Case 0 } Execute(
        { Does first mouse click }
        SimulateMouse(Root, mouseX, mouseY, #Btn, #No_Keys);
        SimulateMouse(Root, mouseX, mouseY, #Btn + #Btn_Up, #No_Keys);
      ),
      { Case 1 } Execute(
        { does second mouse click }
        SimulateMouse(Root, mouseX, mouseY, #Btn, #No_Keys);
        SimulateMouse(Root, mouseX, mouseY, #Btn + #Btn_Up, #No_Keys);
      ),
      { Case 2 }
        Result = TRUE;
    );
    Phase++;
  ]
]
>


Sin

(Engine-Level Function)

Description: | Returns the trigonometric sine of an angle in radians.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Trigonometric Math
Related to: | ACos | ASin | ATan | Cos | Tan
Format: | Sin(Angle)
Parameters: |
Angle
Required. Any numeric expression giving the angle in radians.
Comments:

The returned value is a number in the range of -1.00 to +1.00. To convert an angle from degrees to radians multiply by \pi / 180 or (approximately) 0.0174533.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

x = Sin(270 * \pi / 180);

The value of x will be - 1.


SiteDispParms

Description: | Parameter setting tool for Site List display options. While not part of the dialog library, and not starting with the letter "p", this is still classified as one of the PTools. Example shows parameters for a site. This function works equally for a connector.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUITransform | PAddressEntry | PAlmPriority | PAreaSelect | PCheckBox | PColorEdit | PColorSelect | PContributor | PDroplist | PEditField | PEditName | PHSliderBar | PHueSelect | PImageSelect | PIPAddressList | PIPListenerGroup | PMultiCheckBox | PPageSelect | PPhraseEdit | PRadioButtons | PSecBit | PSelectObject | PServerListName | PSpinbox | PTimeZone | PTypeToggle
Format: | \SiteDispParms(Parms, SiteDispIdxs, SiteListOptions, Trigger, Reserved, ParmsData, OldParms, OldParmsData, ParmsReady)
Parameters: |
Parms
Required. A pointer to the array of parameters.
SiteDispIdxs

Required. DispParmsStruct of site parameter indices.

Invalid entries in this structure are assumed to be missing parameters. The corresponding control will be grayed out. This parameter is typically created as follows in your module initialization state.

SiteDispIdxs = \DispParmsStruct();
SiteDispIdxs\Latitude           = \#Latitude;
SiteDispIdxs\Longitude          = \#Longitude;
SiteDispIdxs\CustomDetailsPage  = \#CustomDetailsPage;
SiteDispIdxs\CustomMapIcon      = \#CustomMapIconParm;
SiteDispIdxs\SiteListDisplay    = \#SiteListDisplay;
SiteDispIdxs\InitZoom           = \#InitZoom;
SiteListOptions

Required. A bitwise value controlling which Site List display options will be shown in the radio control.

Bit 0 | Automatic
Bit 1 | Site
Bit 2 | Folder
Bit 3 | Exclude
Bit 4 | Flat Folder

(See: Bitwise Parameters & Operations)

Trigger
Required Boolean. A trigger to indicate ongoing editing.
Reserved
Required but unused. Set to Invalid.
ParmsData
Required. An array of parameter data. One of the parameters to your configuration folder module.
OldParms
Required. An array of old parameters. One of the parameters to your configuration folder module.
OldParmsData
Required. An array of old parameter data. One of the parameters to your configuration folder module.
ParmsReady
Required. An array of "Ready" flags. One of the parameters to your configuration folder module.
Comments:

Examples:

GUITransform(30, 45 + SiteDispParmsHt, Width, 45,
             1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 0, 0,
             \SiteDispParms(Parms, SiteDispIdxs, 0b11111, Trigger, Invalid,
                            ParmsData, OldParms, OldParmsData, ParmsReady));


SizeWindow

(Engine-Level Function)

Description: | Changes the visible size of a window on the screen.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Window
Related to: | MoveWindow | WindowOptions
Format: | SizeWindow(Win, Width, Height[, VirtualWidth, VirtualHeight])
Parameters: |
Win
Required. Any expression which gives an object value contained in the window to size. Often, Self().
Width
Required. Any numeric expression that gives the new width of the window.
Height
Required. Any numeric expression that gives the new height of the window.
VirtualWidth
Any numeric expression that gives the width inside the new window in user coordinates (which may be pixels). If VirtualWidth is larger than the client area specified, a horizontal scroll bar appears.
VirtualHeight
Any numeric expression that gives the height inside the new window in user coordinates (which may be pixels). If VirtualHeight is larger than the client area specified, a vertical scroll bar appears.
Comments:

This statement will change the size of the window to the size given. Any objects drawn in the window are not scaled - this resizing simply changes the area displayed. Vertical and horizontal scroll bars will be added to the window's borders so that the entire area can be viewed.
If either VirtualWidth or VirtualHeight are specified, then both must be provided. Attempting to set one without the other will cause the one you set to be ignored. If these parameters are omitted, the virtual size of the window will be changed to whatever value is in the Width and Height parameters.

Use with care in pages: your code will run when the page is displayed in the Idea Studio and when the Page Menu page shows a live preview, possibly with undesirable results in those situations. In a page, the trigger for this function should be a user action rather than anything that runs automatically.

Example:

If ZButton(25, 50, 145, 100, "Resize", 1);
[
  SizeWindow(Self(), 300, 500);
]

This will display a button in the upper left corner of the window that when pressed, re-sizes the window to be 300 pixels wide by 500 pixels high.


Slay

(Engine-Level Function)

Description: | Stops a launched module, and possibly any parent modules.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | Stop | WindowClose
Format: | Slay([Object, KillParents])
Parameters: |
Object
An optional parameter which is any object expression for the launched module. The default value of Object is Self().
KillParents
An optional logical expression for the action to take. If true, Slay will attempt to stop parents as well. It will step through and slay each parent object until it encounters a parent object that is a called object. It will not slay that object or any of that object's parents. The default value for KillParents is FALSE.
Comments: If Object is in the middle of executing script, it is immediately stopped. Slay and Return are the only statements that will cause a script to terminate mid-way through its execution. Others like ForceState will not.
Slay() is the same as Slay(Self(), FALSE).

Example:

  If ZButton(20, 50, 120, 70, "Motor On/Off", 1);
  [
    IfElse(!MotorOn,
       Execute(MotorOn = 1;
               MotorObj = RunMotor() { Module launched implicitly };
       );
    { else } Execute(
         MotorOn = 0;
         Slay(MotorObj, 0);
    ));
  ]

When the button is selected, the statement in the script will check if the motor is running or not, and if it isn't, will launch the module that starts it. Notice that the module is launched implicitly because it is called from inside of a script. If that module is already running it will stopped by the Slay .


SocketAttribs

(Engine-Level Function)

Description: | Returns information about a TCP/IP socket's attributes.
Returns: | Text or Buffer (see comments)
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | ClientSocket | CloseStream | ServerSocket | SocketAttribs | SocketServerEnd | SocketServerStart | SocketWait | SRead | StreamEnd | SWrite | LargeSocketWrite
Format: | SocketAttribs(Stream, Option [,FilterID, Opcode , Data])
Parameters: |
Stream
Required. Any stream expression for the socket. If this isn't a socket stream, invalid is returned.
Option
Required. Any numeric expression for the desired attribute:
Option | Attribute
0 | Remote (text) workstation name
1 | Remote port number
2 | Remote workstation IP
3 | Local machine name
4 | Local machine IP
5 | Number of bytes currently in the output buffer
6 | Remote (text) workstation name (buffered)
7 | Remote workstation IP (buffered)
8 | Local machine name (buffered)
9 | Local machine IP (buffered)
10 | Remote machine Name (for incoming UDP datagrams)
11 | Remote Port (for incoming UDP datagrams)
12 | Remote IP (for incoming UDP datagrams)
13 | Activate optional filters specified in ClientSocket() Supported only by TLS/SSL and WebSockets. For WebSockets, use "WSKT" as the protocol filter. No user action is required for TLS/SSL.
14 | UDP local port number
15 | Socket type (0 TCP, 1 UDP)
16 | UDP destination IP
17 | UDP is broadcast flag
18 | Structure containing counters and timestamps of bytes transmitted and received.
19 | Protocol filter control. With option 19, the FilterID and Opcode must be present. Depending on the FilterID and Opcode, additional Data may need to be provided.
20 | Will return the current output buffer limit size, in bytes.
FilterID
Optional text. Set to "WSKT" for WebSockets.
OpCode
Optional numeric. Refer to the list in the comments.
Data
Optional text. Refer to the list in the comments.
Comments:

Used to determine the size of the output buffer limit on a socket, modify it and obtain the amount of data currently in the output buffers (i.e. not transmitted).

Outbound buffers on a socket are limited to a maximum of 64Mb (the default).

Writing a large volume of data to a socket faster than the socket can be drained could result in excessive memory usage, so exceeding the socket output buffer limit will result in the socket being closed and the memory being released.

Note that the output buffer limit is NOT the same as the transmit buffer size parameter on a SocketServerStart or ClientSocket statement. Those parameters control the size of the buffers that the operating system uses for socket data transmission.

The return value for options 0 and 6 is the machine name stored as a text value. If the name cannot be found it will return the internet address of the socket as a text string.
Options 6 through 9 differ from options 0 and 2 through 4 only in the fact that they are buffered. This means that an initial inquiry will be made to the operating system and stored in a buffer, and after that, all inquiries will be handed the value stored in the buffer. This makes options 6 through 9 significantly faster than the other options, however, any online changes to the workstation's attributes will be not be discovered by options 6 to 9, only 0 and 2 to 4 would return the new values.

If using option 13 to activate optional filters, note that (as of VTScada version 12.1) TLS/SSL and WebSocket are the only ones supported.

Option 19 provides control operations for protocol filters that support this:

FilterID = "WSKT"

Opcode == 0 (Activate).
Data is ignored, if present.

Opcode == 1 (Max Rx Time).
Data is an integer number of seconds allowed between the start of a WebSocket protocol frame and its end (range 1-65535). This is to prevent a malicious actor from holding the port open. Defaults to 60 seconds.

Opcode == 2 (Ping time).
Data is an integer number of seconds during which if there is no communication on the connection, a WebSocket protocol PING frame will be transmitted (range 0-65535). A value of zero disables the PING. Defaults to zero.

Opcode == 3 (Close time).
Data is an integer number of seconds to wait after issuing a WebSocket protocol CLOSE frame before closing the connection (range 3-65535). This is to allow the remote end to transmit its CLOSE frame in response and is provided to prevent the remote end from refusing to send a CLOSE frame and hold the connection open. Defaults to 3.

Opcode == 4 (Tx Max Frame Size).
Data is an integer number of bytes that will be contained in a transmitted WebSocket protocol frame. Messages to be transmitted that are longer than this will be fragmented into multiple frames. Defaults to 4096. Note: Do not use an excessively large number, even though this is a 32-bit quantity.

FilterID = "RAW"

Opcode == 0

Data == Maximum size of the output buffer for the socket, in bytes. If more data than this is pending transmission from the output buffer, the socket will be closed and the stream will go Invalid.


SocketPingSetup

(Engine-Level Function)

Description: | Starts the transmission of automatic keep-alive "ping" messages through a socket stream.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | BuffStream | ServerSocket | ClientSocket
Format: | SocketPingSetup(SocketStream, PingStream, TimeInterval)
Parameters: |
SocketStream
Required. Any valid socket stream, typically obtained from a ClientSocket or ServerSocket.
PingStream
Required. A stream which contains the "ping" packet to be transmitted.
TimeInterval
Required. The interval, in seconds, between transmissions.
Comments: SocketPingSetup is used to enable the regular transmission of a small packet (a "ping") down a socket stream. The ping is only transmitted if there has been no other transmission for the specified time interval. Pinging continues automatically until the socket stream is closed. This function is useful for keeping a connection open which may be closed by the computer operating system due to inactivity.

Examples:

Init [
  If 1 Wait;
  [
    Socket = ClientSocket(0, TargetMachine, Port, TransmitLen,  ReceiveLen, 0);
  ]
]
Wait [
  If PickValid(ValueType(Socket == 8 {stream}, 0) Open;
  [
    SocketPingSetup(Socket, BuffStream("ping"), 10);
  ]
  If PickValid(ValueType(Socket != 8{stream}), 0) Retry;
]
Open [
  .
  .
  .
]

This will open a socket stream and, when the stream is open, enable the automatic transmission of the text message "ping" after every 10 seconds of no other transmission being sent.


SocketServerEnd

(Engine-Level Function)

Description: | Ends a TCP/IP socket server.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | ClientSocket | CloseStream | ServerSocket | SocketAttribs | SocketServerStart | SocketWait | SRead | SWrite | LargeSocketWrite
Format: | SocketServerEnd(Handle)
Parameters: |
Handle
Required. Any numeric expression for the socket server handle as returned from a SocketServerStart.


SocketServerStart

(Engine-Level Function)

Description: | Starts a TCP/IP or UDP socket server and returns a handle to it.
Returns: | Handle
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | ClientSocket | CloseStream | ServerSocket | SocketAttribs | SocketServerEnd | SocketWait | SRead | SWrite | LargeSocketWrite
Format: | SocketServerStart(Family, Port, TransmitLen, ReceiveLen, NoDelay[, ProtocolFilter] )
Parameters: |
Family
Required. Any numeric expression for the protocol family
Family | Description
0 | TCP/IP
1 | UDP
Port
Required. Any numeric expression for the port number to offer.
TransmitLen
Required. Any numeric expression for the number of bytes to buffer when transmitting. The value must be a signed long integer, where only positive values are useful.
If the application is running on a operating system of Windows 7 / Server 2008 R2, or later, and the value is set to zero, then Windows will manage the appropriate buffer size for the link speed and latency.
If you set the buffer size, the value should match or be larger than the largest message that is expected.
A high bandwidth / high latency link will require a larger size to achieve optimum efficiency, but the exact size can be determined only by empirical testing..
ReceiveLen
Required. Any numeric expression for the maximum number of bytes to buffer by VTScada when receiving. Additional buffering will be handled by WinSock.
The value must be a signed long integer, where only positive values are useful (an error will be returned if the value is not greater than zero). The value should match or be larger than the largest message that is expected.
A high bandwidth / high latency link will require a larger size to achieve optimum efficiency, but the exact size can be determined only by empirical testing.
NoDelay
Required. Any logical expression. If true, anything written to a socket started by this server will be flushed immediately. If false, packets are coalesced into larger packets to reduce network loading. This parameter should normally be false.
ProtocolFilter

An optional array that specifies what filtering should be applied to socket connections. The order in the ProtocolFilter array determines priority.

Each filter item consists of two elements where the first is the filter type ("SSL", "VIC", "NULL" and "PROXY") The second is a value dependent upon the filter type, noting that there is no second value for "VIC" and "NULL" types. The certificate subject name is not normally used on a client connection.

Examples:
For TLS/SSL the value is the subject name in the certificate, given as "CN=host.example.com".
For PROXY it is a string.

PFilter = New(2);
PFilter[0] = New(2);
PFilter[0][0] = "SSL";
PFilter[0][1] = "CN=host.example.com";
PFilter[1] = New(2);
PFilter[1][0] = "NULL";
PFilter[1][1] = "";

Comments:

If the parameters are all valid and the socket function fails a negative error code is returned. Error codes can be found in ClientSocket.

If the handle to the socket is orphaned, the equivalent to a SocketServerEnd is performed
RecieveLen and NoDelay apply to streams created by inbound connections (TCP) or datagrams (UDP), not to the listener.
The handle returned can be used by the SocketWait or SocketServerEnd functions.


SocketWait

(Engine-Level Function)

Description: | Wait for Socket Connect. This function returns true when a client connects to a socket offered by a socket server.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Stream and Socket
Related to: | ClientSocket | CloseStream | ServerSocket | SocketAttribs | SocketServerEnd | SocketServerStart | SRead | SWrite | LargeSocketWrite
Format: | SocketWait(Handle)
Parameters: |
Handle
Required. Any numeric expression for the socket server handle as returned from a SocketServerStart.
Comments: For a TCP connection, SocketWait triggers each time a new inbound connection is made. For UDP, SocketWait triggers each time a new datagram arrives for which there is no existing stream to store it in. A UDP datagram is stored in an existing stream if it is from the same IP and if it is received on the same port as the other datagrams in that stream. The UDP stream can be empty (having been drained) but still be regarded as ‘belonging’ to the IP that instantiated the stream.


Sort

(Engine-Level Function)

Description: | Allows the sorting of an array subsection according to the order of another array.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Array
Related to: | PlotXY | TextSearch | SortArray
Format: | Sort(KeyArrayElem, SortArrayElem, N, Descending [, TypeText, CaseInsensitive, Locale, CmpFlags])
Parameters: |
KeyArrayElem
Required. An element of the array to be used as the reference for the sort. This array is copied into temporary memory space. The copy is then arranged in order along with the SortArray, but the original copy of the key array is left unchanged after the sort unless it is the same array as SortArray.
If the key array contains text strings, the TypeText parameter should be set to true (non-0) to enable alphabetical ordering, otherwise each element will be converted to a number before use as a sort key.
SortArrayElem

Required. Any array element giving the starting point in the array for the reordering. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
The new order for SortArray will be according to the order of the ordered copy of KeyArray. The values in this array may be of any type.

N

Required. Any numeric expression giving the number of array elements to use in the sort. If this number is greater than either of the two array sizes, the number of elements used in the sort will be the lesser of the two array sizes. The maximum value for N is the size of the array.

If the sum of N plus the starting element is greater than the size of the array, this computation will "wrap-around" and resume at element 0. For example if you sort 1,3,2 in ascending order starting at element 2 with an N equal to 3, the result would be 3,1,2.

Demo[0] = 1; Demo[1] = 3; Demo[2] = 2;
Sort(Demo[0], Demo[2], 3, 0);

This may be useful in rare circumstances.

Descending
Required. Any numeric expression that indicates the ordering sequence to use in the sort. If it is true (non-0), the sort will be in descending (decreasing) order. If it is false (0), the sort will be in ascending (increasing) order.
TypeText

Optional. A numeric expression that controls the type of sort according to the following table. Defaults to zero - numeric sorting.

TypeText | Sort Performed
0 | Numeric sort
1 | Alphabetic sort
2 | Tag hierarchy sort (Sorts tag names based on hierarchy rather than using a pure alphabetic sort.)
3 | Lexicographical sort. If set, consider also setting a locale (7th parameter) or linguistic CmpFlag.
4 | Tag hierarchical, lingual sort
CaseInsensitive
An optional parameter that accepts any logical expression. If CaseInsensitive resolves to true (1), the key array is treated as holding case-insensitive strings, thus allowing the caller to sort alphabetically instead of lexically. The default behavior is to sort case-sensitive (lexical sort). This parameter is ignored if TypeText is false (0).
Locale

Optional. A valid locale name (en-US or fr-FR). Additional modifiers are also allowed such as zh-CN_stroke (Chinese sorting using stroke order)

The case insensitive flag ignored if doing a locale sort. As an alternative, set one of the following in the ComparisonFlags parameter: #LINGUISTIC_IGNORECASE or #NORM_IGNORECASE.

CmpFlags

A set of flags directing how the comparison should be done, as described in https://docs.microsoft.com/en-us/windows/desktop/api/stringapiset/nf-stringapiset-comparestringex

Supported flags include:

#NORM_IGNORECASE

#NORM_IGNORENONSPACE

#NORM_IGNORESYMBOLS

#LINGUISTIC_IGNORECASE

#LINGUISTIC_IGNOREDIACRITIC

#NORM_IGNOREKANATYPE

#NORM_IGNOREWIDTH

#NORM_LINGUISTIC_CASING

#SORT_DIGITSASNUMBERS

#SORT_STRINGSORT

Comments:

Sort allows the re-ordering of a group of related arrays according to the order of a key array. If KeyArray and SortArray are the same array, the array is arranged in order.

Be aware that sorting is a relatively time-consuming operation. It should not be active during time-critical control, etc.

Do not mix sorting modes. Some code may rely on sorting to be basic case-insensitive alphabetical (non-locale-aware) order, while other code may expect it to be locale-aware. Mixing these is likely to produce errors.
In particular, if you Sort an array and then use TextSearch on it, you must ensure that each uses the same sorting mode with the same locale.

This statement performs a "partition sort", using an element of the array as the dividing point, such that all other elements are divided into those greater than and less than the dividing element. Each partition is then recursively sorted. As of VTS version 7.5, the first and middle elements of the array are swapped, making the middle element the partitioning element. This has increased performance gains for arrays whose sizes reach 100,000 or more elements.

This statement is useful when used with PlotXY. For example, if there are two arrays, one having X-value and the other Y-values, of 100 data values that need to be viewed plotted against each other, the Sort statement could re-order the arrays so that the X values increased from left to right and the Y values stayed with their corresponding X values (see example).
The order of the statements is significant. If the sort of the X array were done first, the sort of the Y array would have no effect since the X array would already be in order. In general, the key array should be sorted last.

The statement uses a minimum of eight bytes of temporary memory for each numeric array element in the sort, or more if the element has been declared to be text. This means that at least 8 * N bytes of memory is required, which may be of concern if N is large and the amount of free memory is minimal.
Invalid array entries in the key array are grouped to the end of the array.

Example 1:

If MatchKeys(2, "sort");
[
  Sort(X[0], Y[0], 100, 0) { Sort the Y values first };
  Sort(X[0], X[0], 100, 0) { Sort the X values };
]

The two arrays mentioned in the previous section are sorted in preparation for plotting by the script, which is executed when the user types in "sort" from the keyboard.

Example 2:

Perhaps you have one array of tag names (N) and another array of matching tag descriptions (D). You want to sort both according to the descriptions. These arrays are shown in the following table in order to simplify the example:

N | D
B | 7
D | 1
A | 3

[
  Sort(D[0], N[0], 3, 0);   { sort entries in Names according to a sorted version of Descriptions }
  Sort(D[0], D[0], 3, 0);   { sort descriptions }
]

The result is:

N | D
D | 1
A | 3
B | 7


SortArray

(Engine-Level Function)

Description: | Sorts an array of arrays based upon the key information provided by the second parameter. The array is sorted in-place.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Array
Related to: | Sort
Format: | SortArray(array, [control, start, end]);
Parameters: |
Array

Required. The array to be sorted.

The array must contain values, each of which must be either an array of simple values (numbers or text), or a record in the form of an array itself.

Control

Optional. Sets the column to be sorted and the type of sort to be performed. See the Examples section of this topic.

System.SortKeys Struct [
 Column;
 Type;
 Descending;
];

Defaults to, Column: 0, Type: Numeric, Descending: FALSE

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Start
Optional. The array index where sorting is to begin. If not specified, array is sorted from the first element.
End
Optional. The last array element to sort. If not specified, array is sorted to the last element. No sorting will be done if End comes before Start.
Locale

Optional. A valid locale name (en-US or fr-FR). Additional modifiers are also allowed such as zh-CN_stroke (Chinese sorting using stroke order)

The case insensitive flag ignored if doing a locale sort. As an alternative, set one of the following in the ComparisonFlags parameter: #LINGUISTIC_IGNORECASE or #NORM_IGNORECASE.

CmpFlags

A set of flags directing how the comparison should be done, as described in https://docs.microsoft.com/en-us/windows/desktop/api/stringapiset/nf-stringapiset-comparestringex

Supported flags include:

#NORM_IGNORECASE

#NORM_IGNORENONSPACE

#NORM_IGNORESYMBOLS

#LINGUISTIC_IGNORECASE

#LINGUISTIC_IGNOREDIACRITIC

#NORM_IGNOREKANATYPE

#NORM_IGNOREWIDTH

#NORM_LINGUISTIC_CASING

#SORT_DIGITSASNUMBERS

#SORT_STRINGSORT

Comments:

This function rapidly sorts vectors of records based upon one or more keys that can be distributed across the records.

The Array parameter cannot be a multi-dimensional array. No sort will happen if you attempt to process a multi-dimensional array.

The elements of SortKeys are as follows:

{0} Column. The field index where the key is located within each record.

{1} Type:

0 => Numeric,
1 => Case insensitive text
2 => Case sensitive text or raw binary.

3 => Locale sort

{2} Descending: TRUE to sort from greatest to least. FALSE to sort from least to greatest.

The value in a field is cast to the selected Type for the purposes of the sort, but is unchanged in the resulting array.

The SortKeys parameter may be an array of SortKey structures. In this case, the array is sorted by multiple keys simultaneously, with the first SortKeys element representing the highest-priority key and so on. This is shown in the third example.

Invalid Data[i][Column] values would be sorted to the end (i.e. higher index values) regardless of the value of Descending.

Examples:

Sort on column 0 of each element of the Data array in numeric ascending order.

SortArray(Data);

Sort on column 0 case-insensitive, binary comparison, in ascending order:

SortArray(Data, System.SortKeys(0, 2, FALSE));

Sort on column 0 numerically in descending order as primary key and secondarily sort numerically on column 1 in ascending order

SortInfo = New(2);
SortInfo[0] = System.SortKeys(0, 0, TRUE);
SortInfo[1] = 1;
SortArray(Data, SortInfo);


Sound

(Engine-Level Function)

Description: | Plays a multimedia sound file as installed in the operating system.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Speech and Sound
Related to: | Beep | ModemDev | Play
Format: | Sound(File, Option [, DevID])
Parameters: |
File
Required. Any text expression giving the file name to play. If the extension is omitted, the default extension ".WAV" is added. If an empty string is provided here, then any currently playing sound is stopped.
Option
Required. Any numeric expression, which indicates how to play the file. Option is found by adding together numbers from the following table.
Option | Bit No. | How to play file
1 | 0 | Play asynchronously (don't wait)
2 | 1 | Don't use default sound if file missing
4 | 2 | Reserved for future use
8 | 3 | Loop the sound until next Sound function executed
16 | 4 | Don't stop any currently playing sound

If Option is 0, VTScada will halt all execution until the sound is finished (this isn't recommended). Add 1 to avoid this.

DevID
An optional parameter. This parameter is required when it is desired to play a sound through other than the system default audio device. The function ModemDev can return the identifier of the wave device for a voice modem. If it is required to stop a sound playing through a specific DevID, then the value returned by the Sound function when the sound was started must be given here.
Comments: This statement may only appear in a script.
When a sound is started using the DevID parameter, only option value 8 is significant.
If a sound is started using the DevID parameter, then the return value from the function is required to stop that sound.

Examples:

Sound("TRAIN", 1);

This statement plays the sound file TRAIN.WAV on the system default audio device.

Sound("", 1);

This statement stops any sound currently playing on the system default audio device.

SoundHandle = Sound("Irritating Music", 8, ModemDev(MStream));

This statement plays the sound file IRRITATING MUSIC.WAV through the audio channel of the modem whose open stream is MStream. The sound will play until stopped.

Sound("", 0, SoundHandle);

This example stops the Irritating Music sound started by the previous example


Spawn

(Engine-Level Function)

Description: | Runs another Windows™ program.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Software and Hardware
Related to: | DLL
Format: | Spawn(Command)
Parameters: |
Command

Required. The text string that will launch a program. If the name of a file is provided, the program associated with the given file extension will be launched. Similarly, if a URL is provided, a web browser will be launched.

Command should also contain any parameters necessary for the execution of the program. These parameters must be delimited from the command and other parameters by one or more space characters. If the command contains spaces, the command must be surrounded in double quote characters. (see examples).

If you wish to include environment variables in your command, you must spawn the command processor, CMD to run that command.

Comments:

Using the Spawn statement does not stop the execution of VTScada.

Within an Anywhere Client session, this function can be used to open a web link but not launch a program.

Examples:

Spawn("C:\Test Code\RunMe.BAT 1 2");

will be interpreted as the command C:\Test with the parameters Code\RunMe.BAT, 1 and 2.

Spawn("""C:\Test Code\RunMe.BAT"" 1 2");

will be interpreted as the command "C:\Test Code\RunMe.BAT" with the parameters 1 and 2.

Spawn("cmd /c ""dir 2>&1 >%TEMP%\Dirlist.txt"" ");

will redirect the directory contents of the current folder to a file named Dirlist.txt in the Windows temp folder, with errors (2) redirected to stdout (&1).

  GUITransform(243, 273, 326, 252,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "DrawingTools", TRUE)\ProgramSpawn(
                                              "https://www.vtscada.com",
                                              "Trihedral"));

This will add a button to a page, labeled "Trihedral", which will open the Trihedral website using the default browser when clicked.


Speak

(VoiceTalk Module)

Description: | Executes on the speech thread to speak the supplied text through a specified SAPI text-to-speech stream.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Speech and Sound
Related to: | Configure | GetDevices | GetVoices | Reset | ShowLexicon | VoiceTalk
Format: | VoiceTalkStream\Speak(Text [, Flags])
Parameters: |
VoiceTalkStream
Required. A speech stream returned from VoiceTalk that you wish to speak the given phrase.
Text
Required. Any text expression that will be spoken on a specified stream.
Flags
An optional parameter to specify speaking flags to the stream. All text will be spoken asynchronously (i.e. the function will not wait for the speech to complete speaking). Flags can be used to specify other parsing of the text. The values for Flags can be any combination of the following:
Flags | Meaning
0 | Use default settings (speak asynchronously)
1 | Speak asynchronously.
2 | Purge speaking queue before speaking text. This cancels all pending and current speech, and then immediately begins speaking the new text.
4 | Regard the Text parameter as a filename, and speak the contents of that file.
8 | Parse text for XML markup.
16 | Do not parse text for XML markup.
32 | Any XML state changes in the text will persist across any future VoiceTalk\Speak calls.
64 | Punctuation characters should be spoken (i.e. "Hello, there." would be spoken as "Hello comma there period").

(As indicated above, an Invalid value, or a value of "0" or "1" for the Flags parameter will have the same result.)

Comments: This function returns the error code resulting from issuing the command to the speech engine, or zero if no error was encountered.
This function will execute and immediately return, sending the text to the speech engine to be spoken asynchronously. Asynchronous speech will not block the calling thread. You can determine when a section of text has completed speaking by inserting bookmarks into the text that can then be watched for in the VoiceTalk BookmarkNum parameter.
Multiple VoiceTalk\Speak statements can be issued on SAPI text-to-speech streams without blocking. The text will be queued up and will be spoken in the order it is submitted. The text speech queue will be terminated immediately if the SAPI text-to-speech stream is closed.
If speaking simultaneously on several streams, all to the same output device, the thread that is currently speaking will continue to do so until all its queued text has been spoken, even if the other thread issues VoiceTalk\Speak calls during this time.
The text string spoken can optionally contain embedded "control tags" that affect the way that the text is spoken. These control tags are in the form of embedded XML. For example, <EMPH> and </EMPH> emphasizes the words between the tags, and <BOOKMARK MARK="32"/> sets the SAPI text-to-speech stream current bookmark number to 32. In order for embedded XML to be parsed, either the text stream must be enabled to process XML (by passing a value for Flags that includes the value 8), or the text string itself must begin with an angle bracket (<).
For a complete list of embedded control tags, please refer to the Microsoft SAPI 5.1 speech documentation.

Example:

sHandle = \VoiceTalk();
If Valid(sHandle) && ZButton(10, 40, 110, 10, "Talk", 1);
[
  sHandle\Speak("<P>Mary had a <EMPH>little</EMPH> lamb</P>");
]

This will speak the supplied text with emphasis on the word "little".

sHandle = \VoiceTalk();
If Valid(sHandle) && Value < 0 Warning;
[
  sHandle\Speak("The value has fallen below zero", 1+2 {synchronous & purge});
]

This will immediately stop any current speech, begin speaking the warning to the user, and continue on right away to the state Warning.


SpeakToFile

(VoiceTalk Module)

Description: | Executes on the speech thread to speak the supplied text to a .wav format audio file.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Speech and Sound, File I/O
Related to: | Configure | GetDevices | GetVoices | Reset | ShowLexicon | Speak | VoiceTalk
Format: | VoiceTalkStream\SpeakToFile(Phrase, Flags, Filename, Quality[, Result])
Parameters: |
VoiceTalkStream
Required. A speech stream returned from VoiceTalk that you wish to speak the given phrase.
Phrase
Required. Any text expression that will be spoken on a specified stream.
This is limited to the number of characters specified by MaxSpeakToFileLength, defaulting to 1000.
Flags
Required. A parameter to specify speaking flags to the stream. All text will be spoken asynchronously (i.e. the function will not wait for the speech to complete speaking). Flags can be used to specify other parsing of the text. The values for Flags can be any combination of the following
Flags | Meaning
0 | Use default settings (speak asynchronously)
1 | Speak asynchronously.
2 | Purge speaking queue before speaking text. This cancels all pending and current speech, and then immediately begins speaking the new text.
4 | Regard the Text parameter as a filename, and speak the contents of that file.
8 | Parse text for XML markup.
16 | Do not parse text for XML markup.
32 | Any XML state changes in the text will persist across any future VoiceTalk\Speak calls.
64 | Punctuation characters should be spoken (i.e. "Hello, there." would be spoken as "Hello comma there period").

As indicated above, an Invalid value, or a value of "0" or "1" for the Flags parameter will have the same result.

Filename
Required. The name of the .wav file to speak into (e.g. "c:\folder\file.wav")
Quality
Required. The format quality to use, as defined by the following table:
Quality | Format | Quality | Format
-1 | SAFTdefault |  |
4 | SAFT8kHz8BitMono | 5 | SAFT8kHz8BitStereo
6 | SAFT8kHz16BitMono | 7 | SAFT8kHz16BitStereo
8 | SAFT11kHz8BitMono | 9 | SAFT11kHz8BitStereo
10 | SAFT11kHz16BitMono | 11 | SAFT11kHz16BitStereo
12 | SAFT12kHz8BitMono | 13 | SAFT12kHz8BitStereo
14 | SAFT12kHz16BitMono | 15 | SAFT12kHz16BitStereo
16 | SAFT16kHz8BitMono | 17 | SAFT16kHz8BitStereo
18 | SAFT16kHz16BitMono | 19 | SAFT16kHz16BitStereo
20 | SAFT22kHz8BitMono | 21 | SAFT22kHz8BitStereo
22 | SAFT22kHz16BitMono | 23 | SAFT22kHz16BitStereo
24 | SAFT24kHz8BitMono | 25 | SAFT24kHz8BitStereo
26 | SAFT24kHz16BitMono | 27 | SAFT24kHz16BitStereo
28 | SAFT32kHz8BitMono | 29 | SAFT32kHz8BitStereo
30 | SAFT32kHz16BitMono | 31 | SAFT32kHz16BitStereo
32 | SAFT44kHz8BitMono | 33 | SAFT44kHz8BitStereo
34 | SAFT44kHz16BitMono | 35 | SAFT44kHz16BitStereo
36 | SAFT48kHz8BitMono | 37 | SAFT48kHz8BitStereo
38 | SAFT48kHz16BitMono | 39 | SAFT48kHz16BitStereo
Result
Required. A pointer to a flag to set when done. This should be 0 for OK or 1 for an error.
Comments: The text may include embedded XML tags as described in the documentation for the SAPI speech engine being used.
Multiple calls to this function will be queued.
Calls to this module will fail if the VoiceTalk instance was not configured for VTSFileOutput.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


SpinBox

(System Library)

Description: | Draws a spinbox with optional label.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SplitList | TextBox | ToolBar | VScrollbar
Format: | System.Spinbox(X1, Y1, X2, Y2, Variable, Label, BoxOnLeft, Alignment, NumChars, LowLimit, HighLimit [, CanEdit, FocusID, TextOption, TextValue, Trigger, BGColor, FGColor, WidthOut])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the spinbox and its label.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the spinbox.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the spinbox and its label opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the spinbox, whichever is the opposite to Y1.
Variable
Required. The variable whose value is set by the spinbox.
Label
Required. Any text expression to be used as a label with the spinbox.
BoxOnLeft
Required. Any logical expression. If true (non-0) the spinbox will appear to the left of the label, if false (0) it will be to the right. If this value is invalid, a default value of true will be used.
Alignment
Required. Any numeric expression that sets the alignment of the spinbox and its label according to one of the following options: The default value is 0.
Alignment | Horizontal | Vertical
0 | Left | Top
1 | Right | Top
2 | Full | Top
3 | Left | Centered
4 | Right | Centered
5 | Full | Centered
6 | Left | Bottom
7 | Right | Bottom
8 | Full | Bottom
NumChars
Required. Any numeric expression that gives the number of digits wide to make the spinbox. A value of 0 or invalid results in the spinbox being automatically sized to fit the widest number (or text string if TextOption and TextValue are set).
LowLimit
Required. Any numeric expression giving the lowest permissible value. If the spinbox is editable and a value less than LowLimit is entered, it will revert to the LowLimit value.
HighLimit
Required. Any numeric expression giving the highest permissible value. If the spinbox is editable and a value greater than HighLimit is entered, it will revert to the HighLimit value.
CanEdit
An optional parameter that is any logical expression. If true (non-0), the number in the field may be edited directly, if false (0), it may not. The default value is false.Note that the value of this parameter directly affects the TextOption and TextValue parameters' effectiveness. If CanEdit is true, both are ignored.
FocusID
An optional parameter that is any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the spinbox will display its current setting, but the value will not be able to be set and the spinbox field will appear grayed out.If this parameter is omitted, keyboard input (such as the arrow keys) will be ignored. The default value is 1.
TextOption
An optional parameter that is any text expression used to replace a certain value (expressed by TextValue) in the spinbox field. This parameter will be ignored if CanEdit is true.
TextValue
An optional parameter that is any numeric expression for the value in the spinbox that is to be replaced by the text string in TextOption. This parameter will be ignored if CanEdit is true.
Trigger
An optional parameter that is a numeric expression. The value in Trigger will become 0 if the user changes the internal buffer (i.e. when the value of the WinEditCtrl as logged in the variable Change transits from invalid to zero).

If the user presses any of Enter, the spin box arrows or the arrow buttons on the keyboard, Trigger becomes 1. If the spinbox loses focus, the value of Trigger becomes 2.
BGColor
Optional. Any numeric expression for the background color of the control. No default value.
FGColor
Optional. Any numeric expression for the foreground color of the control. No default value.
WidthOut
Output. The overall width required for the control. Includes space required for the displayed characters, borders and spin button.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The size of the spinbox is constant, with X1, Y1and X2, Y2 defining the position of the check box and its label.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.
The trigger parameter provides an indication that something has changed and therefore the user should be prompted to save changes before exiting.

Example:

System.Spinbox(200, 70, 360, 30 { Location of spinbox },
               Retries { Variable to change },
               "Number of retries"{ Label },
               Invalid { Defaults to box on left },
               6 { Left, bottom align },
               4 { Field width in chars },
               0, 100 { Low, high limits },
               0 { Not editable },
               3 { Focus ID },
               "None" { Text replacement },
               0 { Use text in index 0 });


SplitList

(System Library)

Description: | Draws a split list (listbox with two columns) with a scrollbar if required and indicates the selected item.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | TextBox | ToolBar | VScrollbar
Format: | System.SplitList(X1, Y1, X2, Y2, Title1, Title2, Data1, Data2, Index, Picked[, Flat, DoubleClick, MaxLen, Offset, FocusID, AlignTitle, Multi, PickList, SplitPos, ShrinkData1CBContext, ShrinkData1Callback, BGColor, FGColor])
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the listbox.
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the listbox.
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the listbox opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of the top or bottom of the listbox, whichever is the opposite to Y1.
Title1
Required. Any text expression giving the title to display above the first column of the split list.
Title2
Required. Any text expression giving the title to display above the second column of the split list.
Data1
Required. An array of data to display in the first column of the split list. This array must be the same size as Data2.
Data2
Required. An array of data to display in the second column of the split list. This array must be the same size as Data1.
Index
Required. Any variable whose value will be set to the index of the highlight.
Picked
Required. A variable whose value will be set true (1) when an item is chosen in the split list. The setting of Index by an external source will not trigger Picked.
Flat
Any logical expression. If true (non-0) the border of the split list will be a single black line, if false (0) it have the look of two indented windows. Defaults to 0.
DoubleClick
An optional parameter that is a variable whose value will be set to true (1) when an item has been double-clicked upon.
MaxLen
An optional parameter that is any numeric expression giving the maximum length of the data lists. If omitted, the maximum list length is given by the size of the arrays Data1 and Data2.
Offset
An optional parameter that is any numeric expression giving the starting offset in the list. The element indicated by this index will be the one initially shown at the top of the list (unless too few elements follow this one to fill the display area).
FocusID
An optional parameter that is any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is 0, the split list will not accept keyboard input, although mouse input will still be recognized. The default value is 1.
AlignTitle
An optional parameter that is any logical expression. If true (non-0) the title is drawn within the split list's boundaries, if false(0) the list fills its bounding area and the title is added at the top (i.e. it extends past the top boundary). The default is true.
Multi
An optional parameter that is any logical expression. If true (non-0), multiple items may be selected in the list. The default is false.
PickList
An optional parameter that is a variable whose value is set to the list of items selected if Multi is true (1). If invalid, no items are selected. This variable may initially be set to a dynamically allocated array (one created with the New function) containing items to be highlighted/selected upon the startup of the split list.
SplitPos
An optional parameter that is a variable that will contain the pixel position of the split bar. If initially valid, the split bar will be in the middle of the SplitList. The default will center the split bar.
ShrinkData1CBContext
Context for callback to shorten Data1 text
ShrinkData1Callback
Callback(Text, AvailWidth, Font)
BGColor
Optional. Any numeric expression for the background color of the control. No default value.
FGColor
Optional. Any numeric expression for the foreground color of the control. No default value.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

If Multi is true, multiple items in the list may be selected by using the <Shift> or <Ctrl> keys along with mouse input. If <Ctrl> is held while an item is clicked on by the mouse, it will become selected (or deselected if it is already selected) and will be added to the list of chosen items. If <Shift> is held while an item is clicked on by the mouse, all items from the last selected item to the currently selected item will be selected. All other items outside of this list will be deselected. If both <Ctrl> and <Shift> are held while an item is clicked on by the mouse, all items from the last selected item to the currently selected item will be set to the state of the last selected item.
For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Examples:

System.SplitList(20, 325, 340, 50 { Outline of splitlist },
                 NameLabel { Column 1 title },
                 TypeLabel { Column 2 title },
                 NameTable { Column 1 data },
                 TypeTable { Column 2 data },
                 Index { Highlighted element },
                 0 { Picked not required },
                 0 { 3D look },
                 DClick { Set for double click },
                 Invalid { Use default max length },
                 0 { Start at top of list },
                 3 { Focus ID },
                 0 { Title extends past top });


SplitListSelector

(System Library)

Description: | Draws a split view comprising two GridLists separated by control buttons. Items listed on the left may be selected to be transferred to the right. Items on the right may be returned to the left so long as they were originally listed on the left. Scrollbars will be drawn if required.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | SplitTagSelector | GridList
Format: | System.SplitListSelector(InitKeyArray, DestKeyArray[, LeftLabel, RightLabel, NumCols, Titles, ColWidthPercents, DestMax, EnableParm])
Parameters: |
InitKeyArray
Required. An array of items passed in to form the initial list on the left.
DestKeyArray
Required. An array of destination items. Any items initially in the array will be displayed in the list on the right.
LeftLabel
Optional label for the left list.
RightLabel
Optional label for the right list.
NumCols
Number of columns for each list. Defaults to 1 if not specified.
Titles
Optional array of titles for both lists. The number of titles must match the number of columns. If this parameter is not specified, then no titles will be displayed for the columns.
ColWidthPercents
Optional array of column width percentages for both lists. Defaults to equal widths if not specified. The size of the array must match the number of columns. The array elements will hold normalized values. For example:

ColWidths = New(3)

ColWidths[0] = .3 {30%}

ColWidths[1] = .2 {20%}

ColWidths[2] = .5 {50%}

DestMax
Maximum number of destination items. The default is invalid which is taken to mean unlimited.
EnableParm
Flag to enable controls. Defaults to 1 if not specified
Comments: A tool intended to provide a user interface for selecting items from a list on the left and transferring them to the right. The InitKeyArray may be an array of arrays. i.e. each element of the main array may be a sub-array which will make up the columns. If an array of arrays is specified, the DestKeyArray must also be of the same format.
The first column (the first element of every sub-array making up a row) will be regarded as the unique key for comparison purposes. The items on the left will be updated if the InitKeyArray changes in size.
When items are moved from the right to the left, they are inserted into the left only if they exist in the InitKeyArray. If not, they are simply removed from the right list.
The SplitListSelector should be called from within a GUITransform as shown in the following example.

Examples:

GUITransform(30, 270, 470, 90,
             1, 1, 1, 1, 1 { Scaling              },
             0, 0          { Movement             },
             1, 0          { Visibility, scaling  },
             0, 0, 0       { Selectability        },
             System.SplitListSelector(InitResourceList,
                               SelectedResources,
                               \GetPhrase("AvailableResourcesLabel"),
                               \GetPhrase("SelectedResourcesLabel")));


SplitPath

(Engine-Level Function)

Description: | Breaks up a file path name into its components.
Returns: | Nothing (path components are returned in the parameters)
Usage: | Script or steady state.
Function Groups: | File I/O
Related to: | Dir | FileFind
Format: | SplitPath(FullName, Drive, Path, File, Extension)
Parameters: |
FullName
Required. Any text expression giving the full path name.
Drive
Required. Any variable, which is set to the drive letter in FullName, plus a colon. If FullName doesn't contain a drive specification, Drive is a null string. If this information is not required, a constant may be used for this parameter.
Path
Required. Any variable, which is set to the directory path in FullName, ending in a backslash. If FullName doesn't contain a path specification, Path is a null string. If this information is not required, a constant may be used for this parameter.
File
Required. Any variable, which is set to the file name in FullName. If FullName doesn't specify a file name, File is a null string. If this information is not required, a constant may be used for this parameter.
Extension
Required. Any variable, which is set to the file extension in FullName, including a period). If FullName doesn't specify a file extension, Extension is a null string. If this information is not required, a constant may be used for this parameter.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Examples:

SplitPath("C:\MyApps\App1\Info.TXT", drv, pth, fName, ext);

The values of drv, pth, fName and ext will be "C:", "\MyApps\App1\", "Info" and ".TXT" respectively.

SplitPath("D:\Apps\Profiler\GDI.WIF", drv, pth, 0, 0);
appPath = Concat(drv, pth);

Note the use of "0" for parameters that are not required.


SplitString

(System Library)

Description: | Splits a string into separate array elements using a given delimiter to mark the breaks between elements in the string.
Returns: | Array
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | JoinStrings
Format: | System.SplitString(String, Delimiter)
Parameters: |
String
Required. Text containing a list of words separated by a delimiter. Digits are treated as characters and are not converted to numbers in the array.
Delimiter
Required text. The character (or characters) marking the boundary between words that will become array elements.
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Example:

[
  SomeArray         { Array of words                     };
  SomeText          { comma delimited list               };

]
Init [ If 1 Main;
  [
    SomeText = "One, Two, Three";
    SomeArray = SplitString(SomeText, ", ");
  ]
]

SomeArray will contain the following:


SplitTagSelector

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Draws a split view comprising two GridLists separated by control buttons. Tag names listed on the left may be selected to be transferred to the right. Each GridList will have two columns: the name and the description of each tag in the list. Scrollbars will be drawn if required.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | SplitListSelector | GridList
Format: | \SplitTagSelector(InitTagArray, DestTagArray[, LeftLabel, RightLabel, DestMax, EnableParm])
Parameters: |
InitTagArray
Required. An array of tag names passed in to form the initial list on the left.
DestTagArray
Required. Array of destination tag names. Can be an array of tags passed in to form the initial list on the right.
LeftLabel
Optional label for the left list.
RightLabel
Optional label for the right list.
DestMax
Maximum number of destination tag names. The default is invalid which is taken to mean unlimited.
EnableParm
Flag to enable the controls.
Comments: A tool intended to provide a user interface for selecting tags from a list on the left and transferring them to the right.
Both GridLists have two columns, the name and the description of the tags. The InitTagArray is an array of Tag names.
The DestTagArray is an array of selected Tag names. The Tag names are used as keys for comparison purposes. The tags on the left will be updated if the InitTagArray changes.
When tags are moved from the right to the left, they are inserted in the left only if they exist in the InitTagArray. If not, they are simply removed from the DestTagArray.
The SplitTagSelector should be called from within a GUITransform as shown in the following example.

Examples:

GUITransform(30, 270, 470, 90,
             1, 1, 1, 1, 1 { Scaling              },
             0, 0          { Movement             },
             1, 0          { Visibility, scaling  },
             0, 0, 0       { Selectability        },
             \SplitTagSelector(InitResourceList,
                               SelectedResources,
                                 \GetPhrase("AvailableResourcesLabel"),
                                 \GetPhrase("SelectedResourcesLabel")));


SQLQuery

(VTSSQLInterface library)

Description: | A launched module that executes an SQL query on data in a VTS application. For queries of external databases, refer to the ODBC Manager Service
Returns: | Nothing (The parameters will be populated with pointers to the returned information)
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Related to: | RegisterCustomTable | GetTagHistory
Format: | \VTSSQLInterface.SQLQuery(QueryString, &Results, &FieldNames, &FieldTypes, &ReturnCode, &ErrorMsg[, &ParamInfo, &PageInfo, &PageStatsInfo])
Parameters: |
QueryString
Required. Any text expression containing a valid SQL select statement. Not all selection clauses are supported.
Results
Required. A pointer to a variable which will hold the results array.
FieldNames
Required. A pointer to a variable that will hold the field names array.
Field names are typically "Value" for most tag values.
FieldTypes

Required. A pointer to a variable that will hold the field types. The types will be returned as SQL data types according to the following table:

Field Type | SQL Data Type
1 | SQL_CHAR
4 | SQL_INTEGER
5 | SQL_SMALLINT
8 | SQL_DOUBLE
9 | SQL_DATETIME
12 | SQL_VARCHAR
ReturnCode

Required. A pointer to a variable that will hold the return code. The code will be one of the following:

Return Code | Meaning
0 | #SUCCESS
1 | #SYNTAX_ERROR
2 | #TABLE_NOT_FOUND
3 | #COLUMN_NOT_FOUND
4 | #ILLEGAL_JOIN
ErrorMsg
Required. A pointer to a variable that will hold a textual error message. Valid only if ReturnCode is not zero.
ParmInfo
Optional. A pointer to a variable that will hold parameter information.
PageInfo
Optional. A pointer to a variable that will hold a PageInfoStruct structure, used to support pagination.
PageStatsInfo
Optional. A pointer to a variable that will hold a PageStatsInfoStruct structure, used to support pagination.
Comments:

Only selection queries are supported. SQL statements for data manipulation will do nothing. If tag filtering or realm-area filter is in effect, this function will retrieve data only from tags the currently logged-on user is permitted to access.

When retrieving historical data, SQLQuery is essentially a wrapper for GetTagHistory. It takes an incoming SQL query, and makes one or more calls to GetTagHistory to retrieve the results. SQLQuery may also be used to retrieve current tag values and other custom tables (such as alarm data).

Legacy tables made it look like tag values were stored in separate tables and used the time stamp of the current server. These legacy tables still exist but are hidden by default, using the property: SQLQueryHideLegacyTables. Newer code should query all tag values from the table, "History", or from a ":TPP"derivative such as "History:1d". See the links for further information.

Supported SQL syntax is as follows:

SELECT [DISTINCT | ALL] columnspecifier-1, columnspecifier-2, ...

FROM tablename-1, tablename-2, ...

[WHERE where-expression]

[ORDER BY columnspecifier-1 [ASC | DESC], columnspecifier-2, ...]

[LIMIT [offset,] row_count]

  • Columnspecifier is either [table-name.]'*' to indicate all columns in a table or a specific column-name in the form: [table-name.]column-name
  • Tablename is either the table name or 'table-name [[AS] alias-name']
  • Quotes may be used around table or column names, and must be used if the names contain special characters. When an alias-name is specified it may be used in place of the table-name in the column specifier.
  • When more than one table is specified, the tables are automatically joined based on their Timestamp columns and MUST have matching "TPP"s. A join expression may be used in place of a table list, but it is only parsed to extract the tables specified. The actual join expression is ignored.
  • Where-expression is an expression to be used to filter the result data.
  • It may contain references to columns, use comparison operators, use functions ABS, LENGTH, UPPER, LOWER, CONCAT, CASE, SQRT, INTEGER, and use keywords AND, NOT, and OR.
  • Use the LIMIT clause to specify a limit to the number of rows that will be returned, and optionally an offset (0-based) which allows pagination. LIMIT is applied after WHERE filtering and after sorting.
  • If there is no explicit LIMIT clause in the query there is an implicit "LIMIT SQLQueryMaxResultRows" (Settings.Dynamic setting) added.

Each logged tag corresponds to one table in the VTS database schema.

Every logged variable within the tag is one column.

In addition, a "TPP specifier" may be appended to a tag name to utilize GetTagHistory's ability to retrieve data over time periods. The TPP specifier is a colon followed by a number and an abbreviation for various time periods. The recognized time period abbreviations are (case-insensitive):

  • MS - milliseconds
  • S - seconds (this is the default, therefore the S may be left out)
  • M - minutes
  • H - hours
  • D - days
  • W - weeks
  • Y - years

For example, the table 'ai1:2D' can be used to retrieve data from tag ai1 with a TPP of 2 days.

A TPP may only be specified for a tag that has at least one numeric logged variable. When a TPP is specified, the available columns are:

  • Timestamp
  • VarName:Average
  • VarName:Minimum
  • Varname:Maximum
  • VarName:Delta
  • VarName:ValueAtStart
  • VarName:TimeOfMin
  • VarName:TimeOfMax
  • VarName:ZToNZCount
  • VarName:NonZeroTime
  • VarName:Total
  • VarName:Interpolate

... where VarName may be replaced by any numeric logged variable from the tag.

The current values of a tag may be retrieved using a table name with the format "TagName_Current". This table will have one row whose columns are Timestamp (the current time) and the current values of each logged value in the tag.

Bit-Wise queries can be created, similar to modes 12 and 13 of calls to GetTagHistory(). To specify a bit-wise summary, use either:

  • Tag Name:Value:BitwiseOR
  • Tag Name:Value:BitwiseAND

For example:

Select Timestamp, as1:value:average, as1:value:BitwiseOR from History_1h where Timestamp >= '2017-10-02 00:00' and Timestamp <= '2017-10-02 23:59'

Related information:

VTScada SQLInterface Module

SQL: Reference and Examples


Sqrt

(Engine-Level Function)

Description: | Returns the square root of a number.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math
Related to: | Exp | Ln | Log | Pow
Format: | Sqrt(X)
Parameters: |
X
Required. Any numeric expression giving the number to take the square root of.
Comments: If X is less than zero, the result is invalid.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

rootNum = Sqrt(25);

The variable rootNum will be set to 5.


SRead

(Engine-Level Function)

Description: | Reads values from a formatted stream and returns the number of values not read.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | BuffRead | CloseStream | FileSize | FileStream | FRead | GetStreamLength | StreamEnd | SWrite
Format: | SRead(Stream, Format, V1, V2, V3, ... )
Parameters: |
Stream
Required. Any expression that returns the stream to read.
Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be read.
This format is similar, but not identical, to the C language format string for the scanf function, whereby each of the % format specifications assigns a value to one of the Vn parameters in the statement in the order in which each appears in the list.
Note that like a standard text string, these format specifiers must also be enclosed by double quotes. If a format specification appears for which there are no remaining V parameters, the format specification value is read and discarded.

For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[*][width]type

Where…

%

Is a mandatory character

*

The optional asterisk causes the read to occur as per the format specification, but suppresses any assignment to the Vn parameters.

width

Width is optional, specifying the maximum number of characters to read.

type

The specifications for type are listed in the following table:

Format strings are case insensitive. Additionally, specifying a character for a type that is not in this list results in all the characters following the % up to that point to be read exactly as they appear in the Format string and discarded.

Type | Meaning
Nb | Binary format, where n is a number indicating the type of value (see below)
c | Single ASCII character (byte)
d | Signed decimal 64-bit integer
e | Signed exponential
f | Signed floating point
g | e or f formats
i | Signed decimal integer
l | Line of characters terminated by a carriage return, line feed, or both
n | Present offset in the buffer
o | Signed octal, 32-bit default*
s | Text string
t | Counted string
u | Unsigned decimal 64-bit integer
x | Signed hex integer using "abcdef", 32-bit default*
znnn | Escape character where nnn is the 3-digit ASCII code

%x and %o will treat values as 32-bit integers by default unless the %ll modifier is used. %llx and %llo will read values in 64-bit.

for %u, when reading an unsigned 64bit integer greater than 9223372036854775807 (the largest signed 64bit integer), the value will be read in as the bit-equivalent signed 64bit integer. (eg. 9223372036854775808 is read in as -9223372036854775808.)

nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.

n value | Type
0 | Byte
1 | Short integer (2 bytes, low byte first)
2 | Long integer (4 bytes, low bytes first)
3 | IEEE single precision float (4 bytes)
4 | <obsolete>
5 | IEEE double precision float (8 bytes)
6 | <obsolete>
7 | Binary unsigned short (2 bytes, low byte first)
8 | Unsigned 32-bit integer
9 | 64-bit FileTime. This reads or writes a 64 bit time value in the Microsoft FileTime format. When reading, the value is converted from the FileTime epoch and units (100 nanosecond intervals since Jan 1, 1601) to the VTS epoch and units (seconds since 1/1/1970) any times earlier than this will result in a value of 0. When writing, the value is converted from the VTS epoch and units to the FileTime epoch and units.

c, ASCII character type: Unlike BuffWrite this type deals with characters in a string; each character being equal to one byte. Unlike the %s option, which reads only up to the first white-space character, the %c option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, a single character is read.

d, Signed decimal integer

e, Signed exponential

f, Signed floating point

g, e or f formats

i, Signed decimal integer type: This option normally reads a decimal integer; however, if a leading "0b" is encountered, the number will be interpreted as binary. If a leading "0" (zero only) is encountered, the number will be interpreted as octal. If a leading "0x" is encountered, the number will be interpreted as hexadecimal. For decimal, values will be read as 64-bit integers, but hex, octal and binary will be treated as 32-bit integers unless the %lli modifier is used, which will cause the %i format to treat hex, octal and binary as 64-bit.

l, Line of characters: This option reads a line of characters terminated by a carriage return, a line feed, or both (in either order). The carriage return and line feed will be discarded, and the next character read will be the first character on the next line. The maximum number of characters read is 2GiB (2^30 bytes) or less if the width option is used.

n, Buffer offset: This option does not read a value, but returns the present offset in Buffer and can be useful in subsequent reads.

o, Unsigned Octal

s, Text string type: Text in the string is read up until a white-space character is encountered, or the specified width has been read, whichever is smaller. Square brackets enclosing a character, group of characters, or a caret and a group of characters used in the format string reads strings not delimited by spaces. This is a substitute for the %s format specification. The input is read up to the first character that does not appear inside the square brackets (note that this is case-sensitive). A dash may be used to specify a range of characters. For example, the following format specifier:

% [A-Fa-f]

will read a string up to the first which is not an A, B, C, D, E, or F both upper and lower case.

t, Counted string type A counted string is encoded as a sequence of UTF-8 characters without a null terminator and preceded by the length in bytes.

The length in bytes is encoded as Int32, i.e. a "%2b". A value of −1 is used to indicate an invalid string, a value of 0 indicates a null ("") string.

Do not apply width or precision modifiers to a "%t" counted string.

The caret symbol ^. If the first character inside the square brackets is a caret ( ^ ), the read progresses up to, but not including, the first character that appears inside the square brackets:

%[^X-Z]

This would read a string up to, but not including, the first X, Y or Z (upper-case only); if the string were terminated by an X, the next character read would be that X. Inside the square brackets, the backslash is used as an escape character - any character following a backslash (such as a caret, dash, or backslash) is taken as that character without special meaning. For example:

%[^X-Z\^]

would behave as described previously, except that the string would now be read up to but not including the first X, Y, Z, or ^.

Because format specifications for the Vn parameters are indicated by a percentage sign, to read (and discard) an actual percentage sign as part of the text string, precede it with a backslash character (i.e. \%). Also, since the backslash character is used in this manner, as well as with special control characters such as line feed, carriage return and form feed, to read and discard a backslash, use two backslash characters (i.e. \\).

x, Hexadecimal characters: the %x option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, it will continue reading all bytes that can be recognized as hexadecimal characters. For example, given the string "…= 3D", %[^=]=%2x would read the hedadecimal value, 3D (decimal value, 61).

znnn, Escape characters: This specifies an escape character that will be thrown away when read, where nnn is a 3-digit number giving the ASCII character code of the escape character. This option is generally used as the sole format specifier that reads an entire string, spaces included, discarding every single occurrence of an escape character, or the first occurrence of every pair of escape characters. For example, if the string to be read looked like:

abXc dXXfghiXXXjXXXXkl mX Xn o

and the format specifier indicated that the ASCII code for 'X' (88) was to be the escape code:

%25z088

then the variable that this was read into would contain:

abc dXfghiXjXXkl m n o

Notice that for each occurrence of X, the character immediately following it is saved, even if it is itself an escape character. Then the next occurrence of the escape character is discarded, with the character following it being saved, regardless of what it is, and so on. The width field specifies the maximum number of bytes to place in the output string; if this number is smaller than the input string (less the offending escape characters), the string will be truncated. If no width is specified, a single character will be read.

Control characters: In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result. Please note that the letters must be lower case.

Code | Meaning
\b | Backspace
\f | Form Feed
\n | Line Feed
\r | Carriage Return
\t | Horizontal Tab
\v | Vertical Tab

In addition to the predefined codes, an alternate form may be used:

\nnn: where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

V1, V2, V3, ...
These parameters are the variables to be read in the form described by the Format parameter. Expressions are not allowed. Each of the Vn parameters is read in the order in which each appears in the parameter list. V1 has the format given by the first % sequence in the Format parameter, V2 has the second, and so on..
Comments:

This function is useful for reading formatted streams. Data exchange between many formats is possible if the formats are known. The return value is optional and is the number of Vn parameters NOT read. This can be used as an error flag.

Strings are limited to 2GiB (2^30 bytes)

Examples:

If ! Valid(err);
[
  err = SRead(recipeStream, "%f%f%f",compoundA, compoundB,
  resin);
]

This reads three ASCII format floating-point numbers, from the current position in the stream in the variable recipeStream. The three numbers are placed in compoundA, compoundB and resin, respectively. If the read were successful, err is 0. Otherwise err is the number of items which were not read.

streamData = "Hello!World!How!Are!You!";
If ! Valid(notRead);
[
  notRead = SRead(streamData, "%[^!]!%[^!]!%[^!]!%[^!]!%[^!]!",
  word1, word2, word3, word4, word5);
]

This is an example of multiple fields delimited by the same character, in this case an exclamation point, that can be read by using the %[ ^ aCharacter] format. Notice the exclamation point following each format character - this causes the string read into each of the variables to be without its trailing exclamation point.


Start

Description: | Starts an application
Returns: | Nothing
Usage: | Script only.
Function Groups: | Configuration Management
Related to: | GetLoadedAppInstance | AppIsRunning | AppIsStarted | AppIsStarting |
Format: | Layer.Start()
Parameters: | none.
Comments: | To use, gather the "Layer Root" of an object from the System.GetLoadedAppInstance function. Has no effect if the application is already running.

Examples:

The following snippet will start the legacy Completed Tutorial application.

[
  TutGUID = "db53f244-90ef-4628-bdf6-2d53794a2079";
]
Main [
  If WinButton(232, 148, 412, 100, 0, "Start app", 1);
  [
    LayerToStart = System.GetLoadedAppInstance(tutGUID);
    LayerToStart.Start();
  ]
]


StartTag

Deprecated. Do not use in new code.

Use ModifyTags for all new code.

Description: | Used to create tags by starting new instances of the tag type specified in the parameter list. When creating an application that requires child tags, it is recommended that this function be used in place of the older ChildLaunch function. StartTag can also be used to stop or to modify an existing tag.
Returns: | Numeric (0)
Usage: | Script Only.
Function Groups: | Advanced Module
Related to: | ModifyTags | OpChange | SimpleOpChange
Format: | StartTag(Parent, Flags, TagType, ParameterList )
Parameters: |
Parent
An object that gives the parent for this new child tag. Defaults to VTSDB if invalid. See note in Comments section.
Flags
Bitwise expression indicating operational options.
Bit # | Operation
0 | Add or change if TRUE. Delete if FALSE.
1 | Persist change if TRUE. The tag will be output to the tag file.

If Bit 0 is FALSE, it is not strictly relevant whether Bit 1 is TRUE or FALSE. The tag will be deleted both in memory and on disk. Regardless of this, it is good form to set bit 1 to TRUE when deleting a tag.

When using StartTag to generate child tags, do not set bit 1 to TRUE.

Flags should be set such that when the tag is stopped, StartTag is called with the a value of zero in the second parameter. This can be done using the expression, Valid(Root\Name).

(See: Bitwise Parameters & Operations)

TagType
Required. The name of the tag type to be used for the tag. If modifying or deleting an existing child tag, you may set this parameter to invalid.
ParameterList
Required. All the parameters required by the child tag should be provided here. The child tag's parameter names and matching values may be supplied in any one of the follow forms:

- As a comma-separated list of up to 256 name-value pairs.

- As a two dimensional array of name-value pairs

- As two arrays, the first containing the parameter names and the second parallel array, containing the matching values.

- As a dictionary.

- As a one-dimensional array of values. The order must match the order of parameters in the tag type, with no gaps or spaces. Note that there is no guarantee that the parameter order will remain the same in future versions - use of a dictionary is preferred.

While there is no requirement that the child parameters must be given in the order that they are defined in the child tag, better performance will be obtained by matching that order. It is necessary to know the names of the parameters.

Comments: When used to create a child tag, the name of that new child tag will always be unique since it will be a combination of the parent tag's name and the new child name in the format "ParentName\ChildName".
If the first parameter (Parent) is not VTSDB, then it should be a tag object (the parent tag), and the StartTag call should only be made from that parent tag's Refresh module.
When this function is used to create an ordinary tag, as opposed to a child tag, it is the responsibility of the programmer to ensure that a unique name is used for each new tag.
  • If the tag does not exist and bit 0 of Flags is TRUE, then the tag is launched.
  • If the tag exists and bit 0 of Flags is TRUE, then the tag's parameters are changed if necessary. Note that, if a new TagType is provided, then the existing tag will be deleted and a tag of the new type created.
  • If the tag exists and bit 0 of Flags is FALSE or the tag's parent's Name is Invalid indicating that the tag is being stopped, then the tag is removed.

Because of configuration management and the version control system, it is possible for a child tag have both temporary parameters (those created by code in the parent and existing only in memory) and a sub-set of permanent parameters in the tag files. These latter values are used to record user-overrides of the parameter values. If the application restarts, the child tag will be re-loaded from code and the overrides made in an earlier session will be read from the tag files. Permanent parameter values will always take precedence over temporary values.

There are several ways that the tag's parameters can be passed to this module:

  • Only one additional parameter which is an array of parameter values, a tag, or a tag mirror structure(*). In the case of a parameter value array the values must match to tags parameters in order, but may be fewer in number, allowing just the name to be passed, for example.
  • Only one additional parameter which is a dictionary of parameter values keyed by parameter name.
  • A pair of arrays is passed, with the first array being the array of parameter names and the second, parallel array, being the values for those named parameters. The "Name" parameter must be present, and the order of the pairs is not significant, other than matching the formal parameter ordering gives some efficiency gains.
  • A list of parameter name and value pairs of parameters. This is typically used by ChildLaunch calls. Again "name" must be present and the ordering is only a small consideration for efficiency.

(*) A tag mirror is a structure that has one element for each of a tag’s parameters, accessible by that parameter name (e.g. MyTag\IODevice). These should only be used by advanced VTScada programmers.

In all examples, ParentRoot is assumed to be a pre-existing tag object with name "Something".

Examples:

Example 1 - Creating a child tag by supplying a series of name, value pairs.

   \Code.StartTag(ParentRoot, 0b11, "AnalogStatus",
          "Name",         "CylinderVolume"
          "Area",         Area,
          "Description",  Concat(Name, ": Cylinder Volume"),
          "DeviceTag",    PollDriverName,
          "Address",      "F8:0",
          "ScanRate",     Invalid,
          "UnscaledMin",  0,
          "UnscaledMax",  100,
          "ScaledMin",    0,
          "ScaledMax",    100,
          "Units",        "gal",
          "AlarmLo",      Invalid,
          "AlarmHi",      Invalid,
          "PriorityLo",   Invalid,
          "PriorityHi",   Invalid,
          "InhibitLo",    1,
          "InhibitHi",    1,
          "AlarmSound",   Invalid,
          "ManualValue",  Invalid,
          "Threshold",    1,
          "Questionable", 0,
          "Quality",      Invalid,
          "DisplayOrder", 1,
          "HelpKey",      Invalid);

This creates a child analog status tag named SOMETHING\CylinderVolume.

Example 2 - Creating a persistent tag by supplying a series of name, value pairs.

   \Code.StartTag(CodeVTSDB, 0b11, "AnalogStatus",
          "Name",         "CylinderVolume"
          "Area",         Area,
          "Description",  "My Cylinder Volume"),
          "DeviceTag",    PollDriverName,
          "Address",      "F8:0",
          "ScanRate",     Invalid,
          "UnscaledMin",  0,
          "UnscaledMax",  100,
          "ScaledMin",    0,
          "ScaledMax",    100,
          "Units",        "gal",
          "AlarmLo",      Invalid,
          "AlarmHi",      Invalid,
          "PriorityLo",   Invalid,
          "PriorityHi",   Invalid,
          "InhibitLo",    1,
          "InhibitHi",    1,
          "AlarmSound",   Invalid,
          "ManualValue",  Invalid,
          "Threshold",    1,
          "Questionable", 0,
          "Quality",      Invalid,
          "DisplayOrder", 1,
          "HelpKey",      Invalid);

This creates a persistent analog status tag named CylinderVolume.

Example 3 - creating a child tag using a dictionary of parameters.

    ParmsDict = Dictionary();
    ParmsDict["Name"]        = "P1";
    ParmsDict["Area"]        = "West";
    ParmsDict["Description"] = "P1 West";
    ParmsDict["IODevice"]    = "Mod1";
    ParmsDict["Address"]     = 100;
    Code\StartTag(ParentRoot, 0b11, "Parent", ParmsDict);

Example 4 - creating a child tag using an array of parameters:

    ParmsArray = New(7);
    ParmsArray[0] = "P2";
    ParmsArray[1] = "East";
    ParmsArray[2] = "P2 East";
    ParmsArray[3] = "Mod1";
    ParmsArray[4] = 200;
    ParmsArray[5] = 2;
    \Code.StartTag(ParentRoot, 0b11, "Parent", ParmsArray);

Example 5 - Creating a child tag using parameters in an array of names and an array of values

    ParmNames     = New(5);
    ParmNames[0]  = "Area";
    ParmNames[1]  = "Name";
    ParmNames[2]  = "Description";
    ParmNames[3]  = "Address";
    ParmNames[4]  = "IODevice";
    ParmValues    = New(5);
    ParmValues[0] = "North";
    ParmValues[1] = "P4";
    ParmValues[2] = "P4 North";
    ParmValues[3] = 400;
    ParmValues[4] = "Mod1";
    \Code.StartTag(ParentRoot, 0b11, "Parent", ParmNames, ParmValues);

Example 6 - Creating a child tag using parameter Name/Value pairs (parms out of order)

    \Code.StartTag(CodeVTSDB, 0b11, "Parent",
                  "IODevice",    "Mod3",
                  "Area",        "Central",
                  "Name",        "P5",
                  "Description", "P5 Central",
                  "Address",     500,
                  "NotAParm",    0);


StateList

Description: | Returns a list of states for a module.
Warning: | This function should be used by advanced users only.
Returns: | Array
Usage: | Script Only.
Function Groups: | Compilation and On-Line Modifications, State
Related to: |
Format: | StateList(Module, Option)
Parameters: |
Module
Required. Any expression for the module or object.
Option
Required. Any numeric expression which indicates the data to list
Option | List Data
0 | Name
1 | Code value


StatementInstance

(Engine-Level Function)

Description | Takes a given code value and object and returns a code pointer value for that instance.
Warning | This function should be used by advanced users only.
Returns | Code Pointer
Usage | Script Only.
Function Groups | Compilation and On-Line Modifications, State
Related to: |
Format: | StatementInstance(Object, Statement)
Parameters |
Object
Required. Any object expression.
Statement
Required. Any code value expression for the statement.


StateName

(Engine-Level Function)

Description | Returns the text name of the given state.
Warning | This function should be used by advanced users only.
Returns | Text
Usage | Script Only.
Function Groups | Compilation and On-Line Modifications, States
Related to: |
Format: | StateName(State)
Parameters |
State
Required. Any code value expression for the state.


StaticSize

(Engine-Level Function)

Description: | If the variable provided in the parameter is static, this will return the size of that variable.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Variable Functions
Related to: |
Format: | StaticSize(Var)
Parameters: |
Var
Required. Any variable to test.
Comments: If the variable is not static, this function will return Invalid.

Examples:

varSize = StaticSize(myVar);


StatsWin

(ODBC Manager Library)

Description | Called to display a window showing current ODBC driver statistics for both the main driver and any user-selected IO device addresses
Returns | Nothing
Usage | Steady State only.
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin TableSynch | Transaction | TransactionCached
Format: | \ODBCManager\StatsWin( Enable, X, Y, ConnectionName)
Parameters |
Enable
Required. Set to true to display the statistics window
X
Required. The screen X position of the window
Y
Required. The screen Y position of the window
ConnectionName
Required. The name of the database connection to be shown.
Comments This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.
The statistics shown in the window include the following:
Data Source | DSN
db State | dbState
Last Execution Time | ExecTime
Last Execution Date | ExecDate
Connection Time | Condt
Execution Time | Cmddt
Sem Q Time | Qdt
Average Execution Time | ACmddt
Average Sem Q Time | AQdt
Execution Count | ExecCount
Error Count | ErrCount
Recovery Count | RecoveryCount
db Open Count | OpenCount
db Close Count | CloseCount
Semaphore Count | SemCount
Error Code | Error
Error | Error
Error Time | ErrorTime
Error Date | ErrorDate
Error Query | ErrorQuery
ODBC Error Code | ODBCErrorCode
ODBC Error Current | ODBCErrorMsg
ODBC SQL State | ODBCSqlState
Last Error Code | LastError
Last Error | LastError
Last Error Query | LastErrorQuery
Last ODBC Error Code | LastODBCErrorCode
Last ODBC Error Current | LastODBCErrorMsg
Last ODBC SQL State | LastODBCSqlState


Step

(Engine-Level Function)

Description: | Transforms a continuous value into discrete steps.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Rounding Math
Related to: | Abs | Ceil | Int | Scale
Format: | Step(X, Size, Increment)
Parameters: |
X
Required. Any numeric expression giving the value to reduce to discrete steps.
Size
Required. Any numeric expression giving the size of the steps in the X input parameter.
Increment
Required. Any numeric expression giving the size of the step in the result.
Comments:

The return value is arrived at by dividing X by Size and taking only the portion before the decimal point, then multiplying by Increment. Note that negative numbers are taken down to the next lower number (e.g. -0.1 becomes -1). If any parameters are invalid, the return value is invalid.
This function is useful for determining the coordinates for menu highlight bars and for rounding numbers to the nearest multiple of another value.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Examples:

p = Step( 4, 1.5, 2);
q = Step( 2.31, 2, 10);
r = Step(10, 100, 0.25);

The values for p, q and r will be 4, 10 and 0 respectively.


Stop

(Engine-Level Function)

Description: | Causes the immediate termination of VTScada, closing all windows.
Returns: | Nothing (optional return parameter may be used)
Usage: | Script Only.
Function Groups: | Software and Hardware
Related to: | Slay | WindowClose |
Format: | Stop([ExitValue])
Parameters: |
ExitValue
An optional parameter that can be used to return a value to the calling program or batch file when VTScada exits. If not specified, the exit value from VTScada is 0, indicating "normal exit".
Comments:

Not recommended in general, and especially not recommended for use in page code, where it may cause an untidy exit.

Shutdown resulting from the Stop() function may take a long time complete.


StopPage

(Display Manager Library)

Description: | Subroutine to close all instances of a page.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics
Related to: | ShowPage | ClosePopUp
Format: | \DisplayManager.StopPage(Pagename[, WindowsOnly]);
Parameters: |
PageName
Required. The name of the page to be stopped.
WindowsOnly
Optional. Boolean, defaults to FALSE. Set TRUE to stop only Windowed pages.
Comments:

If the target page is on display, then a switch to the default page is arranged

Examples:

  If Cancel;
  [
    \DisplayManager.StopPage("ThisPageModule", TRUE);
  ]


StrCmp

(Engine-Level Function)

Description: | Performs a case sensitive comparison of two text expressions and returns an indication of whether the first string is greater than, less than or equal to the second.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | StrLen
Format: | StrCmp(String1, String2)
Parameters: |
String1
Required. Any text expression giving the first string to be used for the comparison.
String2
Required. Any text expression giving the second string to be used for the comparison.
Comments: When one string is referred to as greater than or less than another, it means each character has been converted to its ASCII value and the two strings have been compared character value by character value. In ASCII, the alphabet is numbered in ascending order, and uppercase letters are listed first, so their values are less than lower case letters.
This function returns the following values:
Value | Meaning
-1 | String1 is less than String2
0 | String1 is equal to (identical to) String2
+1 | String1 is greater than String2

Examples:

p = StrCmp("ABC", "abc");
q = StrCmp("AbC", "ABc");
r = StrCmp("ABC", "ABCD");
s = StrCmp("ABC", "ABC");

The values for p, q, r and s will be -1, 1, -1 and 0 respectively.


StreamEnd

(Engine-Level Function)

Description: | Returns whether a stream is at the end.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | BuffStream | ClientSocket | FileStream | GetStreamLength | PipeStream | ServerSocket | LargeSocketWrite
Format: | StreamEnd(Stream)
Parameters: |
Stream
Required. Any stream to test.
Comments: This function returns true (1) if the current stream pointer for Stream is at the end of the stream and false (0) otherwise.

Example:

If MatchKeys(2, "r");
[
  SRead(file1, "%d%n", val, filePos);
  end = StreamEnd(file1);
]
ZText(10, 30, Concat("At end of file ? ", end), 11, 0);
ZText(10, 40, Concat("Position in file = ", filePos), 11, 0);
ZText(10, 50, Concat("The value is ", val), 11, 0);

In this example, every time the user presses the letter r on the keyboard, a new data value is read and a check is done on whether the end of the file has been reached. All of these values are written to the screen. Note that the position in the file (filePos) that is displayed by the ZText command is the position after the read has taken place.


StrICmp

(Engine-Level Function)

Description: | Case Insensitive Text Comparison
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | String and Buffer
Purpose: | This function performs a case insensitive comparison of two text expressions and returns an indication of whether the first string is greater than, less than or equal to the second.
Related to: | StrCmp | StrLen
Format: | StrICmp(String1, String2)
Parameters: |
String1
Required. Any text expression giving the first string to be used for the comparison.
String2
Required. Any text expression giving the second string to be used for the comparison.
Comments: When one string is referred to as greater than or less than another, it means each character has been converted to its ASCII value and the two strings have been compared character value by character value. In ASCII, the alphabet is numbered in ascending order, and uppercase letters are listed first, so their values are less than lower case letters.

This function returns the following values:

Return Value | Meaning
-1 | String1 is less than String2
0 | String1 is equal to (identical to) String2
+1 | String1 is greater than String2

Lower case letters are considered to be the same as the corresponding upper case letters. For example, "VTS" and "vts" are considered to be identical.

Examples:

p = StrICmp("ABC", "AbC");
q = StrICmp("ABC", "ABCD");
r = StrICmp("ABCE", "abcde");

The values of p, q and r are 0, -1 and 1 respectively.


StrictlyEqual

Description: | Will return TRUE if the parameter values are of the same type and also are equivalent, or if both are invalid.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | StrictlyNotEqual | IsEqual
Format: | StrictlyEqual(Parm1, Parm2);
Parameters: |
Parm1
Required. Any value, to be compared to parameter 2.
Parm2
Required. Any value, to be compared to parameter 1.
Comments:

Will return either True or False. Will never return Invalid.

X | Y | X == Y | X != Y | StrictlyEqual (X, Y) | StrictlyNotEqual (X, Y)
Invalid | Invalid | Invalid | Invalid | TRUE | FALSE
Invalid | 1 | Invalid | Invalid | FALSE | TRUE
1 | Invalid | Invalid | Invalid | FALSE | TRUE
1 | 1 | TRUE | FALSE | TRUE | FALSE
\AS_1 | \AnalogStatus | FALSE | TRUE | FALSE | TRUE
\AnalogStatus | \AS_1 | TRUE | FALSE | FALSE | TRUE
2 | "2" | TRUE | FALSE | FALSE | TRUE
"2" | 2 | TRUE | FALSE | FALSE | TRUE

Note 1: AS_1 is an object; an instance of the module \AnalogStatus

Note 2: For text to number comparisons, VTScada will attempt to cast the number to text, then perform a case-sensitive comparison. The order of the operands does not matter.

Examples:

Increment NumberOneCount whenever a numeric 1 comes through, and TextOneCount whenever a text "1" comes through.

If Watch(1, Input);
[
  IfThen(StrictlyEqual(Input, 1),
     NumberOneCount++;
  );
  IfThen(StrictlyEqual(Input, "1"),
    TextOneCount++;
  );
]


StrictlyNotEqual

Description: | Returns TRUE if the values are not the same, or if the types are not the same, or if only one operand is Invalid.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | StrictlyEqual
Format: | StrictlyNotEqual(Parm1, Parm2);
Parameters: |
Parm1
Required. Any value to be compared to parameter 2.
Parm2
Required. Any value to be compared to parameter 1.
Comments:

Will return TRUE or FALSE. Will never return Invalid.

StrictlyNotEqual(X, Y) yields the same result as !StrictlyEqual(X, Y).

Equivalent to:

If A != B || Valid(A) != Valid(B) || ValueType(A) != ValueType(B)
X | Y | X == Y | X != Y | StrictlyEqual (X, Y) | StrictlyNotEqual (X,Y)
Invalid | Invalid | Invalid | Invalid | TRUE | FALSE
Invalid | 1 | Invalid | Invalid | FALSE | TRUE
1 | Invalid | Invalid | Invalid | FALSE | TRUE
1 | 1 | TRUE | FALSE | TRUE | FALSE
\AS_1 | \AnalogStatus | FALSE | TRUE | FALSE | TRUE
\AnalogStatus | \AS_1 | TRUE | FALSE | FALSE | TRUE
2 | "2" | TRUE | FALSE | FALSE | TRUE
"2" | 2 | TRUE | FALSE | FALSE | TRUE

Note 1: AS_1 is an object; an instance of the module \AnalogStatus

Note 2: For text to number comparisons, VTScada will attempt to cast the number to text, then perform a case-sensitive comparison. The order of the operands does not matter.

Examples:

Increment Changed whenever NewValue changes. Supports Invalid values. This is much like a Watch(), but allows you to change states and come back without losing track of the last value of NewValue.

If StrictlyNotEqual(NewValue, LastProcessedValue);
[
  Changed++;
  LastProcessedValue = NewValue;
]

Value gets set to Input1 or Input2 whenever they change. Supports Invalid values. Increment counters to see how often you get value from one or the other. It would take much more code to do the following with just Watch().

If StrictlyNotEqual(Value, Input1);
[
  GotInput1++;
  Value = Input2 = Input1;
]
If StrictlyNotEqual(Value, Input2);
[
  GotInput2++;
  Value = Input1 = Input2;
]


StrJustify

System Module

Description: | Performs a word-wrap such that the string will break on or before each multiple of the maximum line length.
Returns: | Text
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | StrLen
Format: | System.StrJustify(Str [, Width])
Parameters: |
Str
Required. The string to be formatted.
Width
An optional parameter indicating the maximum width for line length. If Width is Invalid, the width will be taken from the PrintWidth Setup.ini variable (see "Setup.ini [SYSTEM] Section Variables").
Comments: Inserts CR LF characters (0D 0A), either at each multiple of Width characters or after the first space (20) preceding Width characters.

Examples:

If Watch(1);
  [
    var1 = "AllDayLong";
    var2 = System.StrJustify(var1, 6);
    var3 = "AllDay Long";
    var4 = System.StrJustify(var3, 6);
    var5 = "All Day Long";
    var6 = System.StrJustify(var5, 6);
  ]

After running, the byte codes of var1 through var 6 are:

var1:   41 6C 6C 44 61 79 4C 6F 6E 67
var2:   41 6C 6C 44 61 79 0D 0A 4C 6F 6E 67
var3:   41 6C 6C 44 61 79 20 4C 6F 6E 67
var4:   41 6C 6C 44 61 79 0D 0A 20 4C 6F 6E 67
var5:   41 6C 6C 20 44 61 79 20 4C 6F 6E 67
var6:   41 6C 6C 20 0D 0A 44 61 79 20 0D 0A 4C 6F 6E 67


StrLen

(Engine-Level Function)

Description: | Returns the length of a text string
Returns: | Numeric
Usage: | Script or Steady State
Function Groups: | String and Buffer
Related to: | CharCount | Concat | Replace | SubStr
Format: | StrLen(String)
Parameters: |
String
Required. Any text expression.
Comments: This function does not return the number of characters in String, but rather, the number of bytes, including 0 (NULL) bytes. May be done on a stream value, but if the stream is longer than the maximum signed integer (2^31) characters, the return value will be 2^31.

Example:

v = StrLen("ABCDEF");
w = StrLen("ABC_DEF");
x = StrLen("ABC DEF");

The values of v, w and x are 6, 7 and 7 respectively.


Struct

(Engine-Level Function)

Description: | Creates a new dictionary and loads it with the keys listed in the parameters.
Returns: | Dictionary structure
Usage: | Script Only.
Function Groups: | Variable Functions
Related to: | Dictionary | MetaData
Format: | Struct(A, B[, C ...]);
Parameters: |
A
The first value to add to the dictionary.
B, C, etc.
Subsequent values to be added.
Comments: The dictionary created by this function is case insensitive and has a root value of NULL. The keys are assigned W_LONG values incrementing from zero that match their parameter positions. All of this is done with the idea that the resulting dictionary can then be used as a structure definition.

Examples:

S = Struct("A", "B");


SubStatementIndex

(Engine-Level Function)

Description: | Returns the index of a function within the statement where it is called.
Warning: | This function should be used by advanced users only.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, States
Related to: |
Format: | SubStatementIndex(CodePointer)
Parameters: |
CodePointer
Required. Any code pointer value expression for the function.
Comments: This function returns 0 if CodePointer is a statement.


SubStr

(Engine-Level Function)

Description: | Returns a string that is a portion of another string.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | Concat | StrLen | Replace
Format: | SubStr(String, Start[, Length])
Parameters: |
String
Required. Any text expression giving the original string to extract the sub-string from.
Start
Required. Any numeric expression giving the character offset from the start of String of where to start the resulting string. A value of 0 refers to the first character in String. If the Start is past the end of String, the result is invalid.
Length
Optional. Any numeric expression giving the number of characters to include in the resulting string starting with Start. Defaults to string length.
Comments: If any parameter of this function is invalid, the return value is invalid. If length exceeds the remaining number of characters in the string past Start, then only the remaining characters will be returned.

Examples:

piece1 = SubStr("ABCDEF", 2, 3);
piece2 = SubStr("ABCDEF", 3, 4);

The values of piece1 and piece2 are "CDE" and "DEF" respectively.


Sum

(Engine-Level Function)

Description: | Returns the arithmetic sum of all the valid array elements in a specified portion of a numeric array.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array, Generic Math
Related to: | AMin | AValid | FiltHigh | FiltLow | FitOffset | FitSlope | Mean | SDev | SumBuff | Variance
Format: | Sum(ArrayElem, N)
Parameters: |
ArrayElem
Required. Any array element giving the starting point in the array. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
N

Required. Any numeric expression giving the number of array elements to use, starting at the element given by the first parameter. N cannot be greater than the array size.

If the sum of N plus the starting element is greater than the size of the array, this computation will "wrap-around" and resume at element 0, until N elements have been processed.

Comments: Invalid array elements are not included in the calculation. The function returns an invalid result if either of its parameters is invalid, if there are no valid numerical array elements in the specified range, or if the number of elements to use is 0.

Example:

data[0] = 1;
data[1] = Invalid();
data[2] = 1.5;
data[3] = 3;
data[4] = 100;
dataSum = Sum(data[0], 4);

The value of dataSum is 5.5.


SumBuff

(Engine-Level Function)

Description: | Returns the summation of bytes in a buffer.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Generic Math, String and Buffer
Related to: | BuffOrder | BuffRead | BuffStream | BuffToArray | BuffToParm | BuffToPointer | BuffWrite | Sum
Format: | SumBuff(Buffer, Offset, N, Increment)
Parameters: |
Buffer
Required. Any text expression giving the buffer to sum.
Offset
Required. Any numeric expression that gives the buffer offset from 0 to start the sum.
N
Required. Any numeric expression that gives the number of bytes to sum. If N is negative, the absolute value of N is used, but the operation is changed from summation to XOR (each successive byte is XORed with rather than added to the first byte).
Increment
Required. Any numeric expression that gives the incremental step of the sum in bytes.
Comments: This function returns the 32 bit sum of N bytes in Buffer, starting at Offset and stepping by Increment bytes. This function is useful for computing checksums for serial communications.

Examples:

Given that myBuff is length 256, and values are the bytes from 0 to 255:

sum1 = SumBuff(myBuff, 0, 256, 1);

sum1 would add 0 + 1 + 2 + ... + 254 + 255

sum2 = SumBuff(myBuff, 5, 100, 1);

sum2 would add 5 + 6 + 7 + ... + 103 + 104

sum3 = SumBuff(myBuff, 1, 100, 2);

sum3 would add 1 + 3 + 5 + ... + 197 + 199

To compute a 16 bit checksum which adds 16 bit words in a 100 byte buffer with the low byte first:

serCheckSum = And(SumBuff(buff2, 0, 50, 2) +
256 * SumBuff(Buffer, 1, 50, 2), 0xFFFF);


SWrite

(Engine-Level Function)

Description: | Performs a formatted write of text or binary data to a pre-existing stream and returns the number of data items not written.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: | BuffWrite | FileSize | Format | FWrite | GetStreamLength | Print | PrintLine | Redirect | Save | SRead | StreamEnd
Format: | SWrite(Stream, Format, V1, V2, ...)
Parameters: |
Stream
Required. A stream as returned from BuffStream or FileStream.
Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be written. This format is similar, but not identical, to the C language format string for the printf function, whereby each of the Vn parameters in the statement is assigned to a % format specification in the order in which each appears in the list.

Note that like a standard text string, these format specifiers must also be enclosed by double quotes.

If a format specification appears for which there are no remaining V parameters, the format specification characters themselves are output to the stream exactly as they appear in the Format.

For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[-][+][SPACE][#][width][.precision]type

where

% (percent sign) is mandatory;

- (minus sign) (optional) causes the data to be left justified within the field (for binary types b and ASCII character types c, this option is ignored);

+ (plus sign) (optional) causes positive numbers to be prefaced with a + sign (negative numbers are unaffected). This allows easy alignment of positive and negative numbers in a printed column of numbers. For binary types b and non-numerical types, this option is ignored;

space represents the single space character, and is similar to the [ + ] option but places a single space rather than a plus sign in front of positive numbers (negative numbers are still unaffected). This allows alignment of a column of numbers without having to show all signs. For binary types b and non-numerical types, this option is ignored;

# (hash mark) When used with the o , x , or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.

width is a number that specifies the minimum number of characters to output. Numbers that require more characters than specified by the width value are truncated on output. If the number of characters in the number or string is less than width, blanks will be added to the left or right, depending upon whether the output is left or right justified (i.e. whether the [ - ] option has been specified) until the width is reached. For binary types b and ASCII character types c, this option is ignored;

precision has a different meaning for each of the type options as follows:

  • Integer types d, l, u, o, x, and X precision specifies the minimum number of digits to output. If the number contains fewer digits, leading zeroes will be added to the left of the number. If precision is 0, omitted, or if the decimal point appears without a number following it, the precision defaults to 1. The number is not truncated.
  • Floating point types e and E precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision in this case is 6. If the precision is 0 or if the decimal point appears without a number following it, no decimal point appears in the output.
  • Floating point type f precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision is 0. If the precision is explicitly 0, no decimal point is output. If a decimal point is output, at least one digit will be placed before the decimal point.
  • Floating point types g and G precision specifies the maximum number of significant digits to be output. If no precision is specified, all significant digits are written.
  • String type s precision specifies the maximum number of characters of the string to be output. If the string contains more characters than specified by the precision, the string is truncated and only the first characters are written. If the precision is not specified, all of the string characters are output.
  • Byte type c The precision option is ignored.
  • Binary type b The precision option is ignored.

type is mandatory. The type specification must be one of those listed below.

Note: The case of the letter is important. Specifying a character for the type that is not in this list will result in all the characters following the % up to that point to be output exactly as they appear in the Format string.

Type | Meaning
nb | Binary format; where n is a number indicating the type of value (see below).
c | Single character (byte values from 0 to 255)
d | Signed decimal 64-bit integer, 64-bit output by default
e | Signed exponential; exponent key is "e".
E | Signed exponential; exponent key is "E".
f | Signed floating point.
g | e or f format, whichever is shorter.
G | E or f format, whichever is shorter.
h | Handle to a window.
i | Signed decimal 64-bit integer, 64-bit output by default
o | Unsigned octal integer. Default 32-bit integer. Use %llo to output 64-bit value.
p | Pointer to a buffer.
s | Text string.
t | Writes a utf-8 string as used by OPC UA binary TCP: a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string
u | Unsigned decimal 64-bit integer, 64-bit output by default
x | Unsigned hex integer using "abcdef". Default 32-bit integer. (See following note.)
X | Unsigned hex integer using "ABCDEF". Default 32-bit integer. (See following note.)

When writing negative values using either x or X format codes, the output will use a minimum of 32 bits because that is the smallest possible size to display the full information. Defining a format string such as "%4X" will not reduce this to 16 bit output for negative values. To output 64-bit values, use the modifier ll. %llx and %llX output 64-bit values.

nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.

n | Value Type
0 | Byte, unsigned
1 | Signed short integer (2 bytes)
2 | Signed long integer (4 bytes)
3 | IEEE single precision float (4 bytes)
4 | <obsolete>
5 | IEEE double precision float (8 bytes)
6 | <obsolete>
7 | Unsigned short integer (2 bytes)
8 | Unsigned long integer (4 bytes)
9 | Writes a time in Microsoft FILETIME format, which contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).
10 | Outputs signed 64-bit integers in binary form.

Note: Other options such as width and precision do not apply to the b type.

c, Byte type: This type is not representative of a single character in a string, but rather, represents single bytes. Input values (the Vn parameter to which this format specification applies) must be integers in the range of 0 to 255. Strings are not acceptable input values. Note that the %c format specifier behaves differently when used in an output statement such as BuffWrite than when used in an input statement, such as BuffRead. Some UTF-8 characters can require multiple bytes. Values from 0-127 are consistent between the traditional ASCII encoding and the UTF-8 encoding.

d, Signed decimal 64-bit integer:

e, Signed exponential: Exponent key is "e"

E, Signed exponential: Exponent key is "E"

f, Signed floating point

g, e or f formats: Whichever is shorter

G, E or F formats: Whichever is shorter

h, Window handle type: This type is used for building structures to be handed to DLLs and should be used by advanced users only.

p, Buffer pointer type: This type is also used for building structures to be handed to DLLs and should be used by advanced users only.

s, Text string type:

t, Writes a utf-8 string as used by OPC UA binary TCP:
a 32-bit signed count of the length (-1 for an invalid string, 0 for an empty string), then the string

u, Unsigned decimal 64-bit integer,

x, Unsigned hex integer using "abcdef": 32-bit value by default. Use modifier %llx for 64-bit value output.

X, Unsigned hex integer using "ABCDEF": 32-bit value by default. Use modifier %llX for 64-bit value output.

SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Plain text Text in the Format parameter is written exactly as it appears, with three exceptions:

  • Percentage sign (%) Because format specifications for the Vn parameters are indicated by a percentage sign, to include an actual percentage sign as part of the Format parameter, precede it with a backslash character (i.e. \%).
  • Backslash character (\) Because this is used to indicate special control characters such as line feed, carriage return, and form feed, to write a backslash as part of the Format parameter, use two backslash characters (i.e. \\).
  • Quotation marks (") The entire test string is delimited by quotation marks, so to include a set of quotation marks as part of the Format parameter, use a set of quotations marks (i.e. "").

Control characters In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result (notice that the letters must be lower case):

Code | Meaning
\b | Backspace
\f | Form feed
\n | Line feed
\r | Carriage return
\t | Horizontal tab
\v | Vertical tab

\nnn In addition to the above predefined codes, \nnn may be used, where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

znnn Escape character where nnn is the 3-digit ASCII code
For example: SWrite(Strm, "%z92", "Something \to\ be escaped");

Gives the output: Something \\to\\ be escaped

Offset is any numeric expression giving the starting buffer position in bytes for the write, starting at 0.

V1, V2, ...
Required. Any expressions giving the values to be output in the form described by the Format parameter. Each of the Vn parameters is evaluated and written in the order in which each appears in the parameter list. The way in which they are formatted is dictated by the % format specifications. V1 is formatted by the first % sequence in the Format parameter, V2 by the second, and so on. If there are more V parameters than % sequences in the Format string, the remainder are ignored. If there are fewer V parameters than % sequences in the Format string, the remaining % sequences are written literally without any translation.
Comments:

If using this function in any code that may write to a USB-to-Serial device, you must make allowances for deficiencies in those devices as follows: the device will ignore everything following the text in the first %s. All text to be written must be in a single parameter passed to a single %s.

SWrite(Strm, "%s\r", "AT");
  { Only the "AT" is received by a USB-to-Serial device }
SWrite(Strm, "%s%s", "AT", \CR);
  { Only the "AT" is received by a USB-to-Serial device }
SWrite(Strm, "%s", Concat("AT", \CR));
  { this will succeed if written to a USB-to-Serial device }

You cannot write to a read-only file. You may use GetFileAttribs and SetFileAttribs to get/set the read-only attribute.
If one of the values to be written is outside of the range of the type indicated by the format specifier, a "0" is written.
If the value to be written is invalid, nothing is written for most format specifiers, except for %nb, which will write a "0" in the place of the invalid. Please note that an invalid output does not prevent the execution of the SWrite function.

This function returns the number of Vn parameters not written to the stream. A 0 return value indicates success. Variables that contain invalid values that were not written due to their invalidity do not increment this count. An invalid return value indicates an error with one of the parameters.

As of version 12.0, VTScada expects all strings to be encoded using UTF-8.

Examples:

If MatchKeys(2, "W");
[
  b = MakeBuff(16, 65) { Create buffer; fill it with A's },
  buff = BuffStream(b) { Create the stream },
  SWrite(buff { Write to the stream },
         "A=%d B=%4.2d C=%5.2f\r\n%s\r\n" { Format },
         1, 2, 2/3, "Hello World" { Output values });
]

This statement would write the following two lines of text to the stream buff :

A=1 B= 02 C= 0.67
Hello World

If you replaced the third line of the script with the following:

SWrite(buff { Write to the stream },
       "\072\105\n%c%c%c" { Format },
       77, 111, 109 { Output values });

The following two lines would instead be written to buffer stream buff:

Hi
Mom


SystemSelf

(Engine-Level Function)

Description | Returns the object value of the system module for the given application.
Returns | Object value
Usage | Script or steady state.
Function Groups | Basic Module
Related to: | Self
Format: | SystemSelf(Object)
Parameters |
Object
Required. Any object value expression for any module instance in the application.
Comments There is one and only one instance of the system module for each application.


T Functions

The sections that follow identify all VTScada functions beginning with "T".


TableInterpolation

(Function Library)

Description: | Given a graph described by a CSV file containing X and Y values, this function will interpolate a Y value for any provided X value within the range of the graph.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Oil & Gas
Related to: | ShellTemperatureCorrection
Format: | TableInterpolation(FileName, Input, Mode[, ErrorTag])
Parameters: |
FileName
Required text. The path and name of the CSV file containing X and Y values for a graph.
Input
Required numeric. An X value, for which this function will return an interpolated Y value. This value must be within the range of X values found in the given CSV file.
Mode

Required numeric. Sets the type of interpolation to use.

Set to 0 for linear interpolation.

Set to 1 to return the Y value associated with the closest X value.

ErrorTag

Deprecated - for diagnostics at configuration time only, not for operations.

Optional tag object. If provided, this must be an analog tag (typically an I/O tag in Analog mode). The value of that tag will be set according as follows:

Value | Meaning
0 | Success
1 | No file
2 | Bad file (Includes a header or does not hold X,Y data points sorted by ascending X value .)
3 | Input exceeds the maximum X value in the CSV file
4 | Input is less than the minimum X value in the CSV file
5 | Input value not provided
6 | Mode not set to 0 or 1
Comments:

This function will read a table from a CSV file at the specified location and perform the selected type of interpolation for the Input value, returning the result. Returns Invalid if a result cannot be found.

Each line of the CSV file must contain two values: The X and Y coordinates for a point on the graph. No header should be included. The data must be sorted from top to bottom within the file in order by ascending X values.

An optional error tag can be provided for which an error value will be set.


TableSynch

(ODBC Manager Library)

Description: | Synchronizes the fields matching a specified criteria within matching tables in two databases. Should be run as a called module, waiting for completion. Do not call as a subroutine.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | ODBC
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | Transaction | TransactionCached
Format: | \ODBCManager\TableSynch( DSNSource, DSNDest, TableName, WhereFields, WhereOperators, WhereValues, WhereSQLDataTypes, WhereAND, SourceUsername, SourcePass, DestUsername, DestPass, [ TransObj,] NRecords, CurrRecord)
Parameters: |
DSNSource
Required. Data source name of the database to retrieve data from.
DSNDest
Required. Data source name of the destination database to send data to
TableName
Required. Table name to read/write in both databases
WhereFields
Required. A text array of field names to select using an SQL WHERE clause
WhereOperators
Required. A text array of operators to use when selecting fields using an SQL WHERE clause
WhereValues
Required. A text array of values to use when selecting the above fields using an SQL WHERE clause
WhereSQLDataTypes
Required. Values indicating the data type of the Where values. Should be a simple value or an array matching the WhereFields parameter. Refer to Data Type Codes used in the ODBC Manager for a list of the codes.
WhereAND
Required. Set to true (1) if the fields in the SQL WHERE clause are to be AND'ed. Otherwise, OD'ed
SourceUsername
Required. User name for source db
SourcePass
Required. A password for source db
DestUsername
Required. A user name for destination db
DestPass
Required. A password for destination db
TransObj
The object value of transaction
NRecords
Required. A number of records to synchronize
CurrRecord
Required. Current record being written
Comments: This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.


Tag

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Returns a Tag value, which works like (and in place of) a Normalize value.
Returns: | Tag
Usage: | Steady State only.
Function Groups: | Graphics, Generic Math, Variable
Related to: | Normalize | Rotate | Scale | Trajectory
Format: | Tag(Value, LowInput, HighInput, LowScale, HighScale, Mode, Freq)
Parameters: |
Value
Required. Any numeric expression to be normalized.
LowInput
Required. Any numeric expression, which represents the lowest normal input value of Value. This is not a limit.
HighInput
Required. Any numeric expression, which represents the highest normal input value of Value. This is not a limit.
LowScale
Required. Any numeric expression, which represents the lowest normal scaled value of Value. This is not a limit.
HighScale
Required. Any numeric expression, which represents the highest normal scaled value of Value. This is not a limit.
Mode

Required.

Any numeric expression. Deprecated, but must be present and valid.

Freq

Required.

Any numeric expression. Deprecated, but must be present and valid.

Comments:

This function scales an expression from the low and high input range to between low and high values. The return value is a Normalize value.
If a Tag value is used in an expression, it will return the scaled value.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

pumpFlow = Tag(rawPumpFlow, 0, 4095, 0, 150);

This sets the variable pumpFlow to a Tag value. The variable rawPumpFlow is scaled from between 0 to 4095, to between 0 and 150. This Tag value might be used to scale a rectangle (to show a bar graph of the pump flow), as shown:

GUIRectangle(0, 100, 100, 0 { Rectangle bounding box },
             1, 1, 1, pumpFlow, 1 { Scale top of bar only },
             0, 0 { No trajectory, rotation },
             1, 0 { Visible; reserved },
             0, 0, 0 { No focus, selection },
             12, 15 { Lt red, white outline });

The variable pumpFlow could also be reused in other expressions, graphics functions, rotations, or trajectories.


TagIconMarker

Description: | Draws an "IconMarker" in the center of its transform area, and optionally shows a blank icon when in editing mode.
Returns: | Object
Usage: | Steady State only.
Function Groups: | Graphics
Related to: |
Format: | TagIconMarker(TagReference[, ShowInConfigParm])
Parameters: |
TagReference
Required. A reference to the tag for which the unlinked widget, questionable, manual or dummy tag indicator should be shown.
ShowInConfigParm
Optional Boolean. If TRUE, the marker will be visible (but blank) in the Idea Studio. Defaults to FALSE.
Comments:

Examples:

  GUITransform(94, 105, 105, 94,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Variable("Code\Library")\TagIconMarker(\Root));


Tan

(Engine-Level Function)

Description: | Returns the trigonometric tangent of an angle in radians.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Trigonometric Math
Related to: | ACos | ASin | ATan | Cos | Sin
Format: | Tan(Angle)
Parameters: |
Angle
Required. Any numeric expression giving the angle in radians.
Comments:

The returned value is a number in the range of -1.00 to +1.00. To convert an angle from degrees to radians multiply by \pi / 180 or (approximately) 0.0174533.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

x = Tan(45 *  \pi / 180);

The value of x will be 1.


Target

(Engine-Level Function)

Description: | Returns an indication of whether the locator (e.g. mouse) is within a specified screen area.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Locator
Related to: | Click | Pick | SetXLoc | SetYLoc | XLoc | YLoc | GUITransform
Format: | Target(X1, Y1, X2, Y2)
Parameters: |
X1
Required. Any numeric expression giving the X coordinate on the screen of one side of the screen area ("target").
Y1
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the screen area ("target").
X2
Required. Any numeric expression giving the X coordinate on the screen of the side of the "target" opposite to X1.
Y2
Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the target, whichever is the opposite of Y1.
Comments:

This function returns true if the locator position is within the boundaries of the "target" ((X1,Y1) - (X2,Y2)). If the locator is not installed, the function will return false (0).

Note: This function is disabled when using a GUITransform as a GUIStrectch.

Example:

If Target(120, 50, 220, 80);
[
   ...
]

This statement will cause the script to execute whenever the mouse passes over the target area.


TempFileStream

(Engine-Level Function)

Description: | Creates a temporary file on disk and connects a stream to the temporary file. The temporary file is removed when the stream is closed or no longer referenced or if the VTScada process is terminated.
Returns: | Stream
Usage: | Script or steady state.
Function Groups: | File I/O, Stream and Socket
Related to: | BlockWrite | BuffStream | ClientSocket | CloseStream | FileStream | GetStreamLength | PipeStream | SRead | StreamEnd | SWrite
Format: | TempFileStream(Buffer)
Parameters: |
Buffer
Required. Any text or buffer expression. This serves as the initial content of the stream.
Comments: This function returns a stream connected to a temporary disk file with the contents of Buffer, which is the pointer at which an action (read or write) begins will be at the start of the stream. Writing to this stream can overwrite or expand (or both,) the size of this initial stream and file.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

Stream = TempFileStream("0123456789");

The variable stream would contain "0123456789".


Text

Deprecated. Do not use in new code.

(Engine-Level Function)

Description | Displays text in a window.
Returns | Nothing
Usage | Steady State only.
Function Groups | Graphics
Related to: | GUIText | Output | TextAttribs | ZText
Format: | Text(X, Y, Value, Foreground, Fill, Background, Size, Obsolete)
Parameters |
X
Required. Any numeric expression giving the X screen coordinate of the lower left corner of the text on the screen.
Y
Required. Any numeric expression giving the Y screen coordinate of the lower left corner of the text on the screen.
Value
Required. Any text expression giving the value to display.
Foreground
Required. Any numeric expression giving the color of the characters to display.
Fill
Obsolete - set to zero.
Background
Required. Any numeric expression giving the color of the background area for the output characters.
Size
Required. Any numeric expression giving the height of the characters in units of Y screen coordinates. If this value results in a specification of less than 12 screen pixels high, the text will be the small text (8 pixels high). Otherwise, the text will be the large text. If Size is negative, it will be interpreted as a dot text output of size equivalent to the absolute value of the size. The number will be displayed to the nearest multiple of the base 8 pixel by 8 pixel text. This produces faster, non-destructive large characters than the normal large text characters.
Setting size greater than 12 results in non-XOR drawing.
Obsolete
No longer used, but is maintained for backward compatibility with previous versions of VTScada. Set to 0.
Comments

This statement has been superseded by the GUIText and ZText statements and is maintained for backwards compatibility only.
As of version 11, this is now drawn in the same z-order as other graphics, making it similar to the z-graphics functions.

Within an Anywhere Client session, this function does nothing.


TextAttribs

(Engine-Level Function)

Description: | Returns graphic-related information about a text, given a font.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | GUIText | Output | ZText
Format: | TextAttribs(Text, Font, Option)
Parameters: |
Text
Required. Any text expression.
Font
Required. Any font expression.
Option
Required. Any numeric expression for the desired parameter:
Option | Parameter
0 | Width of text in pixels
1 | Height of text in pixels

Example:

width = TextAttribs("Testing" { Text to display },
                    Font("ARIAL", 0, 16, 0, 5, 0, 0) { Font },
                    0 { Width in user coordinates });

The value of width will be 61, which is the width of the given text string in the given font.

Pixels are assumed to have a dpi size of 96.


TextBox

(System Library)

Description: | Displays a text string, breaking it into multiple lines at space or CRLF.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | ToolBar | VScrollbar | GUIText
Format: | System.TextBox(X1, Y1, X2, Y2, Msg, FontVal, Style, BevelTitle [,BackColor, BodyTextColor, HorizontalAlign, VerticalAlign, Height, SearchString, SearchCaseSensitive, SearchColor])
Parameters: |
X1
Required. The left side coordinate.
Y1
Required. The bottom side coordinate.
X2
Required. The right side coordinate.
Y2
Required. The top side coordinate.
Msg
Required. The message buffer to display.
FontVal
Required. The font to use (defaults to \_DialogFont).
Style
Required. The bevel/border/wordwrap requirements. This can be one of:
Bit 0 | Draw a bevel at X1/Y1/X2/Y2. An 8-pixel margin will be added when determining the text rectangle. The default is TRUE.
Bit 1 | Draw a border around the text rectangle. A further 4-pixel margin will be added. The default is TRUE.
Bit 2 | Word wrap text. The default is TRUE.
Bit 3 | Transparent background. Can be clicked-through to the controls beneath. Default is FALSE
Bit 4 | Disables the vertical scroll bar when TRUE. Default is FALSE
Bit 5 | Disables the horizontal scroll bar when TRUE. Default is FALSE.

(See: Bitwise Parameters & Operations)

BevelTitle
Required. The title to display for the bevel (if relevant).
BackColor
An optional parameter specifying the background color Defaults to #SYS…BUTTONFACE.
BodyTextColor
An optional parameter specifying the text color. Defaults to 0, black.
HorizontalAlign
An optional numeric value, specifying the horizontal alignment of the text.
0 == Left,
1 == Center,
2 == Right.
Defaults to 1, Centered.
VerticalAlign
An optional numeric value, specifying the vertical alignment of the text.
0 == Top,
1 == Center,
2 == Bottom.
Defaults to 1, Centered.
Height
Optional Numeric. The height of the text, not including borders and bevels will be returned to the caller in this parameter.
SearchString
Optional text. A highlight color will be added to that portion of the text matching this string.
SearchCaseSensitive
Optional Boolean. Applies only if SearchString is used. When TRUE, a highlight is added only if a case-sensitive match to SearchString is found.
SearchColor
Optional color value. The highlight color to use for the portion of the text matching SearchString. Defaults to yellow (14).
Comments: If the current text cannot be accommodated by breaking at a word boundary, then the word will be hyphenated (not grammatically). A vertical scrollbar will be automatically added if required.


TextEncode

Description: | Takes text in the local code page and converts it into UTF-8 encoded text where a suitable conversion exists.
Returns: | String
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: |
Format: | TextEncode(InputText[, ErrMsgOut, InputCharacterSet, OutputCharacterSet]);
Parameters: |
InputText
Required text. The information to be encoded.
ErrMsgOut
Optional return parameter. If provided, this will be set to a text representation of the error.
InputCharacterSet
Optional text. The IANA character set name to use. Defaults to the character set given by the local system code page.
OutputCharacterSet
Optional text. The IANA character set name to use for output. Defaults to "UTF-8".
Comments:

The return value will be the input string encoded as UTF-8, unless there are any sequences of bytes in the input string that cannot be represented as UTF-8, in which case the return value will be invalid.

If converting from ISO-8859-1 to UTF-8, you must make two conversions: first from ISO-8859-1 to UTF-16, then from UTF-16 to UTF-8. The intermediate step may also be required for other conversions to UTF-8.

Examples:

<
{=========================== TextEncodeTest =============================}
{ Example code to demonstrate TextEncode().                                 }
{========================================================================}
TextEncodeTest
[
  Protected Input             { Input string in local code page          };
  Protected UTF8Result        { Input encoded as UTF-8                   };
]

Main [
  If Watch(1);
  [
    Input = "This is a string in Windows-1252 encoding with symbols: £©";

    UTF8Result = TextEncode(Input);
  ]
]

{ End of TextEncodeTest }
>

If the system code page is configured as Windows-1252 by selecting "English (United States)" as per Using a Non-English Character Set, the UTF-8 result would contain "£" encoded as the bytes [0xC2, 0xA3] and "©" as [0xC2, 0xA9].

Example 2

(showing only the call to TextEncode)

 { Convert text encoded as utf-8 to utf-16 big-endian }
utf16result = TextEncode(Input, ErrorMessage, "UTF-8", "UTF-16BE");


TextIP2Bin

Deprecated. Maintained for backward compatibility. Do not use in new code.

Instead, refer to MakeIPMask, CheckIPMask, IPMaskToText

(RPC Manager Library)

Description: | Returns the Binary representation of the specified IP.
Returns: | Text
Usage: | Script Only.
Function Groups: | String and Buffer, Network
Related to: | BinIP2Text
Format: | \RPCManager\TextIP2Bin(IP)
Parameters: |
IP
Required. The IP that you want converted to Binary format. Formatting example 192.168.0.200.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
If you have an IP of the format 192.168.0.200/24, the /24 will be ignored.


TextOffset

(Engine-Level Function)

Description: | Returns the character offset to the definition text of a desired item.
Warning: | This function should be used by advanced users only.
Returns: | Numeric
Usage: | Script Only.
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextSize
Format: | TextOffset(CodeValue, Type)
Parameters: |
CodeValue
Required. Any code value expression for the item.
Type
Required. Any numeric expression for the value type of CodeValue.


TextSearch

(Engine-Level Function)

Description: | Returns the array index of the first occurrence of the given text key in an alphabetically ordered array.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array, String and Buffer
Related to: | ArrayStart | ArraySize | LookUp
Format: | TextSearch(ArrayElem, N, Text, Case, TypeText, Locale, CmpFlags)
Parameters: |
ArrayElem
Required. Any array element giving the starting index for the array operation. The index for the array may be any numeric expression.
If processing a multidimensional array, only the right-most dimension is used.
N

Required. Any numeric expression for the number of array elements to search.

If N plus the starting element is larger than the size of the remaining array, then this function will "wrap around" to restart at the first element. For this to have any useful result, the array would need to be sorted to match before running TextSearch.

Text
Required. Any text string to search for. Does not take an expression.
Case
Required. Any logical expression. If true, the search is case-sensitive. Otherwise, the search is case-insensitive.
TypeText

Optional. A numeric expression that controls the type of sort according to the following table. Defaults to zero - numeric sorting.

TypeText | Sort Performed
0 | Reserved
1 | Alphabetic sort
2 | Reserved
3 | Lingual sort
4 | Reserved
Locale

Optional. A valid locale name (en-US or fr-FR). Additional modifiers are also allowed such as zh-CN_stroke (Chinese sorting using stroke order)

CmpFlags

A set of flags directing how the comparison should be done, as described in https://docs.microsoft.com/en-us/windows/desktop/api/stringapiset/nf-stringapiset-comparestringex

Supported flags include:

#NORM_IGNORECASE

#NORM_IGNORENONSPACE

#NORM_IGNORESYMBOLS

#LINGUISTIC_IGNORECASE

#LINGUISTIC_IGNOREDIACRITIC

#NORM_IGNOREKANATYPE

#NORM_IGNOREWIDTH

#NORM_LINGUISTIC_CASING

#SORT_DIGITSASNUMBERS

#SORT_STRINGSORT

Comments:

If the key is not found in the array, the function returns invalid. Notice that the array (or the elements being searched in the array) must be in ascending alphabetical order for this statement to return a valid value.

Do not mix sorting modes.
In particular, if you Sort an array and then use TextSearch on it, you must ensure that each uses the same sorting mode with the same locale.

Example:

index = TextSearch(dataArray[0] { Start of search in array },
                   ArraySize(dataArray, 0)
                   { Search all elements },
                   "green" { Text string to search for },
                   0 { Case insensitive search });

Given that dataArray is an array of text strings of various color names, index will be set to the subscript of the array element whose entry is "green".


TextSize

(Engine-Level Function)

Description: | Returns the size in characters of the definition text of a desired item.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | AdjustCode | GetModuleText | GetOneParmText | GetParmText | GetStateText | GetTransitText | GetVariableText | SetModuleText | SetOneParmText | SetParmText | SetStateText | SetTransitText | SetVariableText | TextOffset
Format: | TextSize(CodeValue, Type)
Parameters: |
CodeValue
Required. Any code value expression for the item.
Type
Required. Any numeric expression for the value type of CodeValue.
Comments: This function may only appear in a script.


TGet

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | This threaded function reads an array of historical data from a file (written by Save or SaveHistory) and returns an indication of parameter errors.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Log, File I/O
Threaded: | Yes
Related to: | TGet | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords | Get | GetHistory | GetLogInfo | Save | SaveHistory
Format: | TGet(Array, N, File, FieldNum, StartDate, StartTime, TPP, Mode [, ErrorCode, StaleTime, PathPrefix])
Parameters: |
Array
Required. A variable which will be set to an array upon completion of the data retrieval.
N
Required. Any numeric expression giving the number of array entries to create.
File
Required. Any text expression giving the file name for the historical data file. The file extension should not be added to the name since the default of ".DAT" is automatically added.If the file name is prefixed with a period, the path will be to the directory the module is contained in.
FieldNum
Required. Any numeric expression giving the field number to be read from the file. The value number for the actual data starts at 0 and corresponds to the columns specified in Save or SaveHistory. It is also possible to retrieve time data associated with each record by setting this parameter to a negative value.Time options are:
FileNum | Time Option
-1 | Time of day only
-2 | Date only
-3 | Time since January 1, 1970

It is possible to retrieve more than one field in a single TGet statement. To do this, pass an array of values in as the FieldNum parameter.

StartDate
Required. Any numeric expression giving the date to search for in the file as the starting date for the data. This date is expressed as the number of days since January 1, 1970. If StartDate is less than zero, it indicates the relative file position to read rather than the date.

A -1 indicates the last entry in the file. A -2 the second last and so on.

It is important to note that in cases where Save has been used with a non-negative Buffers parameter, the last entry in the file will be invalid (a fact that is useful in data logging). In cases such as this, the first valid entry will be indicated by -2, the second by -3 and so on.
StartTime
Required. Any numeric expression giving the time of day on StartDate to search for in the file as the starting time for the data. This time is expressed as the number of seconds since midnight on StartDate.

It is legal for StartTime to be greater than one day. It is legal for StartTime to be negative, where data will start the previous day at (86400 - StartTime) seconds after midnight. If StartDate is less than zero, StartTime is ignored.
TPP
Required. Any numeric expression giving the time span in seconds for each array entry. Each array element will contain the data which correspond exactly to this time period which corresponds to 0 or more data points in the file. If TPP is positive and FieldNum selects a text value, the first entry which falls in a time is read, and Mode is ignored.

If TPP is equal to 0, the data is read from the file and placed in the array on a one to one basis.

If TPP is less than 0, the data is read on a one to one basis from the StartDate and StartTime for (negative) TPP seconds, TPP places an upper limit on the time span to read. In both of these cases, the Mode parameter is ignored.
Mode
Required. Any numeric expression giving the method of handling the data. If TPP is greater than 0, the values that fall in each time span will be represented as follows:
Mode | Time Span Representation
0 | Time weighted average
1 | Minimum in range
2 | Maximum in range
3 | Change in value over the range
4 | Value at start of range
5 | Time of minimum in range (in seconds since Jan 1, 1970)
6 | Time of maximum in range (in seconds since Jan 1, 1970)
7 | Count the total number of zero to non-zero transitions within each TPP period.
8 | Totalizes, for each TPP, the amount of time when the value is non-zero (Invalid is counted as zero).
9 | Totalizes, for each TPP, the arithmetic sum of the recorded values.
10 | Interpolates between values.

In the case of modes 5 and 6, FieldNum should still be set to indicate the field number on which the mode is to act. The return values will be times indicating the maximum or minimum in that field for each time span.

If TPP is less than or equal to 0, Mode is ignored. If the data is text, the first entry in a given time range is used for the array entry and Mode is ignored.

It is possible to retrieve more than one mode in a single TGet statement. To do this, pass an array of values in as the Mode parameter.

ErrorCode
An optional parameter that is any variable which will be set to a valid value upon completion of the TGet. Its meaning is as follows:
Value | Error
0 | No error
1 | Parameter values out of described range
2 | File could not be opened
3 | Corrupted .DAT file
4 | Field requested could not be found

If ErrorCode is not required but either StaleTime or PathPrefix is, then ErrorCode should be given as an Invalid value.

StaleTime
An optional parameter that sets a maximum validity duration for data elements that are being TPP processed. Normally, every data point is treated as remaining valid until the next data point. If a valid StaleTime parameter is given, then any data point will be treated as invalid StaleTime seconds after the recorded time. If TPP is less than or equal to 0, StaleTime is ignored. If StaleTime is not required but PathPrefix is, then StaleTime should be given as either an Invalid value or a constant zero.

It is possible to specify more than one stale time in a single TGet statement. To do this, pass an array of values in as the StaleTime parameter.
PathPrefix
An optional text expression parameter that enables and controls the retrieval of data from across a set of files. No default.
Comments: This function is similar to Get except that it runs in its own thread - it is typically used when a large amount of data is being read. When the TGet is executed in its script, it starts its own thread and VTScada will continue executing. When it is finished executing, it will set the data in Array. Note that Array will not be initially invalidated upon execution of this statement. This means that if Array already contained data when the TGet was executed, that data will remain untouched until all of the data requested by TGet has been amassed, at which time Array will be set to its new value.

There is a return value for this function that indicates if any of its parameters are invalid. The function will immediately return a value of false (0) unless a parameter was invalid, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in its thread.
If StartDate is given a negative value, indicating that a particular entry is to be retrieved, it must be stressed that the file being read by the TGet may or may not contain an invalid record at the end of the file. If the Save that created the file was given a negative number for its Buffers parameter, the invalid record would not have been written to the file, however, a zero or positive value for Buffers will mean that the last record of the file will be one whose fields are all invalid and whose time and date stamp reflect the cessation of writing to the file by the Save.

If FieldNum is an array with more than one element, then TGet will retrieve multiple fields from the file. In this case, ArrayElem must represent an array with at least two dimensions. The requested values will be returned in a manner analogous to GetHistory, with the data for a column in the rightmost dimension, and the column index in the previous dimension.

When FieldNum is specified as an array, Mode or StaleTime, or both, may be specified as either a single value or an array of values. If a single value is specified, that value will be used for each of the fields specified in FieldNum. If an array of values is specified, the first element in the array will be applied to the first element of FieldNum, and so on.

If PathPrefix is specified, then this changes the interpretation of the File parameter. In this case, the referenced file is not the source of the data, but a file containing references to other files which are the data sources. This file should be in standard VTScada logfile format and should contain a file reference as the first text value of each record (other values are ignored). The records should be in the correct time order with respect to the data files. The value of the PathPrefix is a string, which when prefixed to one of the file references, will yield a full pathname to the target file. If no prefix is required, but expansion of the dataset is required, then PathPrefix should be an empty string.

If a filename entry does NOT begin with a "\" or "<drive letter>:\", then the PathPrefix will be prepended to the filename.

If a filename entry DOES begin with "<drive letter>:\", then the PathPrefix will NOT be prepended to the filename.

If a filename entry does begin with a "\", then the "<drive letter>:" from the PathPrefix will be prepended to the filename. If there is no "<drive letter>:" in the PathPrefix then the "<drive letter>:" from the path of the File parameter will be used instead.

PathPrefix would normally be the application path.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

Init [
  If 1 Main;
  [
    TGet(trend { Destination array },
         100 { Get 100 array elements fr file },
         "G:\mix\mixtrend" { path and file name },
         0 { Read first 'column' from file },
         Today() { Starting today },
         Seconds() - 3600 { Starting 1 hour ago },
         18 { Each element covers 18 secs },
         0 { Time weighted average });
  ]
]
Main [
  If Valid(trend) DoneReading;
  ZText(10, 20, "Reading Data", 10, 0);
]

This reads a half hour of data from a file, starting one hour ago. Note that just after midnight, the expression Seconds( ) - 3600 may be negative; the TGet statement interprets this as before midnight on the previous day (which is correct). X is set to the record following the last record read from the file. Note also that a full path name may be specified, including network drives. Also note that it is irrelevant when data were logged to the file; the Save statement trigger could have been a regular timer (such as AbsTime), or an event (such as Change(level, 1)).


Thread

(Engine-Level Function)

Description: | Launches a module in its own separate thread.
Returns: | The object value of the instance of the module that is launched into the new thread.
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | Call | FindVariable | Launch | LoadModule | ThreadHistory | ThreadList | ThreadName
Format: | Thread(Module, Parent, Caller, Name, P1, P2, ...)
Parameters: |
Module
Required. A module pointer or a text expression giving the module to run. If the module is in scope, the text expression giving its name may be used, otherwise the module pointer returned from either a LoadModule or FindVariable statement is typically used.
Parent
Required. The object value of the module where Module is to resolve its global variable references. If a valid non-object value is supplied Module will resolve its global variable references to the scope defined by the first parameter. If this is invalid, the module will still run, but global references will be invalid.
Caller
Required. The object value of the window to draw in. This specifies the module instance where Module acts as if it were called from. If this is invalid, the module will still run but will not stop without a Slay. If it is valid, the module will stop when the Caller module instance stops or when a Slay is executed upon it.
Name
Required. Any text expression giving the name that is to be associated with this particular thread. This is the name that will be returned by the ThreadList function.
P1, P2, ...
Required. Are any expressions which will be supplied as parameters to the module.
Comments: This function behaves similar to Launch except that a separate thread is created in which the module is executed. This means that it will not block execution of other modules; the CPU time will be divided equally amongst threads of equal priority. Great care should be exercised when using this function since each thread created by Windows™ uses certain system resources and will by its very existence slightly slow the running of the application. In general, the Thread function should only be used when a module would otherwise monopolize system resources to such an extent that other critical modules would be severely hampered in their execution.

This function returns an object value of the newly started module, in the same way that Launch does. This means that parameters are passed to the module as a value only, and if the module instance changes one of their values, its value will not change outside of the scope of the threaded module. Variables external to the module that the module itself will be required to alter should reside within the scope of Parent and be set directly, rather than passed as parameters.

Example:

If ! Valid(ptr);
[
  ptr = Thread("CheckTank" { Module to launch },
               Self(), Self() { Parent and caller },
               CheckTankThread { Name },
               pressure1, pressure2, level { Parameters });
]


ThreadHistory

(Engine-Level Function)

Description: | Returns in an array, the history of execution for all threads.
Returns: | Multidimensional Array
Usage: | Script Only.
Function Groups: | Basic Module
Related to: | Thread | ThreadList | ThreadName |
Format: | ThreadHistory(Unused, ArrayToPopulate, NumRecords)
Parameters: |
Unused
Reserved. Should be set to Invalid.
ArrayToPopulate
Name of the array. See comments.
NumRecords
Defaults to 10,000 if not specified.
Comments:

The return value for ThreadHistory is a listing of the last 8192 operations on the thread (max) with five data points per operation. This array should be interpreted in the format, [column][row].

The five rows (data points per operation) are as follows:

0 = Time of execution
1 = Module, State and Statement (type 13) for the operation
2 = State name where the operation is located
3 = Statement number of the operation
4 = Object value for the owning module instance

The second parameter is typically populated by using the result of calling ThreadHistory once with an empty array. For example, if you want to obtain the execution history every 5 seconds, you might use the following code to save having to build a 10000-element array every time:

If TimeOut(1, 5);
[
  ExecuctionHistory = ThreadHistory(Invalid, ExecutionHistory, 10000);
]

The first time the above is called, ExecutionHistory will be Invalid so ThreadHistory will build, populate, and return a multi-dimensional array with 10000 elements.

The second time it is called, ExecutionHistory will have been set to the array of the right size / dimensions. ThreadHistory will populate the array it was given and return it, rather than creating a new array.


ThreadIdle

(Engine-Level Function)

Description: | Returns TRUE when the ToDo list for a given thread is empty.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Basic Module
Related to: | Thread | ThreadHistory | ThreadList | ThreadName |
Format: | ThreadIdle(ObjectValue)
Parameters: |
ObjectValue
Required. The object value of the thread to monitor.


ThreadList

(Engine-Level Function)

Description: | Returns a two dimensional array containing the name and statement last executed by each VTScada thread.
Returns: | Array
Usage: | Script Only.
Function Groups: | Basic Module, Software and Hardware
Related to: | Thread | ThreadHistory | ThreadIdle | ThreadName |
Format: | ThreadList()
Parameters: | None
Comments: This function returns an allocated array such that the first row of the array (array[0][n]) contains the name of each thread, while the second row (array[1][n]) contains the statement most recently executed statement in that thread. The threads are ordered in the array in chronological order with the most recently started thread is at the beginning of the array.

Example:

If MatchKeys(1, "thread");
[
  allthreads = ThreadList();
]


ThreadName

(Engine-Level Function)

Description: | Returns the name of a thread.
Returns: | Text
Usage: | Script Only.
Function Groups: | Basic Module, Software and Hardware
Related to: | Thread | ThreadList | ThreadIdle
Format: | ThreadName(Instance)
Parameters: |
Instance
Required. Any object value designating the thread for which the name is required.
Comments: This function returns the name of the thread in which Instance is executing.

Example:

If ! Valid(myThread);
[
  myThread = ThreadName(Self());
]


ThreadPriority

(Engine-Level Function)

Description | Allows advanced users to set a specified thread to one of six priorities, ranging from idle to time critical.
Warning: | This statement is recommended for advanced users only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Basic Module
Related to: |
Format: | ThreadPriority(ObjectReference, Priority)
Parameters: |
ObjectReference
Required. Indicates the thread to be modified.
Priority
Required. A value from -3 to 3 that indicates the priority of the thread. This may be one of:
Priority | Description
-3 | THREAD_PRIORITY_IDLE
-2 | THREAD_PRIORITY_LOWEST
-1 | THREAD_PRIORITY_BELOW_NORMAL
0 | THREAD_PRIORITY_NORMAL (Default)
1 | THREAD_PRIORITY_ABOVE_NORMAL
2 | THREAD_PRIORITY_HIGHEST
3 | THREAD_PRIORITY_TIME_CRITICAL
Comments: All threads default to THREAD_PRIORITY_NORMAL. The operating system will place priority on threads operating at higher priorities over threads operating at lower priorities. The responsiveness of higher priority threads is therefore improved (at the expense of lower priority thread responsiveness).
Threads that share information amongst themselves may see performance drop if they don’t all operate at the same priority. Similarly high priority threads that perform extended operations may prevent lower priority threads from operating at all. Use of high priority threads is typically appropriate to short operations that need to be performed without delay or to processes that are intolerant of interruption.


Time

(Engine-Level Function)

Description: | Returns a formatted string for a time of day.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | Date | Now | Seconds
Format: | Time(Sec, TimeForm [, Flags, Locale])
Parameters: |
Sec
Required. Any numeric expression giving the number of seconds since mid night. The function, Now(1), is commonly used as it returns the current time of day, expressed in seconds.
TimeForm

Required. Any numeric expression giving the option for the time Time Formatting Codes. Will also accept a time locale such as "us-en" matching the Windows locale.

If TimeForm is numeric, the format for the time will be interpreted.
If TimeForm is a text value that does not resolve to a numeric, it is interpreted as a time formatting string as follows.

String | Example | Description
h | 9 | Hours with no leading zero for single-digit hours. 12-hour clock.
hh | 09 | Hours with leading zero for single-digit hours. 12-hour clock.
H | 21 | Hours with no leading zero for single-digit hours. 24-hour clock.
HH | 21 | Hours with leading zero for single-digit hours. 24-hour clock.
m | 7 | Minutes with no leading zero for single-digit minutes.
mm | 07 | Minutes with leading zero for single-digit minutes.
s | 12 | Seconds with no leading zero for single-digit seconds.
ss | 12 | Seconds with leading zero for single-digit seconds.
f | .1 | Tenths of a second
ff | .01 | Hundredths of a second
fff | .001 | Milliseconds
t | P | One character time-marker string, such as A or P.
tt | PM | Multi-character time-marker string, such as AM or PM.

In the event that the TimeForm parameter does not resolve to either a numeric or text value, the system-configured time format, as specified through the Windows Control Panel, is used. In this case, the Flags parameter is used to select from a number of options for the time.

Flags
An optional parameter that is only used in the event that the TimeForm parameter does not resolve to a numeric or a text value. The Flags parameter may be set as follows to adjust the format of the date.
Value | Description
1 | Do not generate minutes or seconds.
2 | Generate minutes, but do not generate seconds.
8 | Force 24-hour time format.

The format string characters are case-sensitive. If you wish to include one of the formatting characters in your output string, then you must surround it with single quotation marks. For example, "h'h'" would display the current hour number in 12-hour clock format, with a lowercase h suffixed to it.

Locale
Optional text. May be used to specify a locale for which to format the time. Use Windows-standard locale strings, such as "en-us".
Comments: The Sec parameter may be negative, in which case it specifies the time before midnight. If greater than 86400, it specifies the time in the next day. The text string returned is at most 11 characters long.

Examples:

ZText(10, 10, Time(Now(1), 2), 0, 0);
time1 = Time(28800, 2);
time2 = Time(28800, 7);
time3 = Time(now(1), "m");

The first statement will display the current time in the upper right corner of the window in the form "08:24:13", and will update every second. The value of time1, time2, and time3 will not be displayed, but will be set to "08:24:00", "08:24 AM" , and "24" respectively.


TimeArrived

(Engine-Level Function)

Description: | Indicates whether a given time has occurred.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Time and Date
Related to: | CurrentTime | TimeOut
Format: | TimeArrived(TriggerTime)
Parameters: |
TriggerTime
Required. A UTC timestamp, specifying when the TimeArrived function will become true..

Example:

  If TimeArrived(Timestamp);
  [
    Timestamp = Invalid;
     ...
  ]

This statement will trigger when the current time reaches the specified timestamp (Timestamp must be changed or invalidated in the corresponding script, otherwise the statement will trigger repeatedly). This example is exactly equivalent to the hypothetical statement:

   If CurrentTime(1) >= Timestamp;

Except that CurrentTime may not be used in steady state.


TimeOut

(Engine-Level Function)

Description: | Returns true when the uninterrupted time that an expression is true reaches the specified value.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Time and Date
Related to: | AbsTime | Now | RTimeOut | TimeArrived
Format: | TimeOut(Enable, Time)
Parameters: |
Enable
Required. Any numeric expression giving the condition that results in the timer counting. When this parameter is true (not 0), the timer is "running." When this parameter is false (0), the timer stops and the timer is reset to 0.
Time
Required. Any numeric expression giving the time-out limit in seconds. When the cumulative time that Enable is true reaches this value, the function becomes true (1). If this value is 0 the function will trigger immediately and will continue to trigger as long as the state containing this function is active.
Comments:

This function is reset when either parameter becomes invalid, the Enable becomes false, or when the state containing the function is started. When the function is reset, counting starts at 0 and the returned value is false (0).
Note that this function is reset automatically when it occurs in a true action trigger or function parameter of a function which resets its parameters after evaluation (e.g. Latch, Toggle & Save).

VTScada includes an application property at the \Code level named SecondFlasher. The value of this property changes from 0 to 1 once a second, as near as possible to the change of the second. In most cases, it is better to watch for the change of \SecondFlasher than to burden the system with an additional function to calculate one-second intervals.

Example:

A common usage of the TimeOut function is as an action trigger for a script:

  If TimeOut(1, 5) NextState;
  [
     ...
  ]

This script will be executed 5 seconds after entering the state, and then a state change to NextState will occur.

  ZText(10, 10 { Lower left corner of text },
        "Emergency!" { Text to display },
        Cond(Toggle(TimeOut(1, 0.5)), 12, 4 { Toggle light red/dark red every 0.5 secs }),
        0 { Default font });

This displays a message that flashes bright red and dark red every 0.5 seconds. Note that this example makes poor use of system resources and should not be copied into production applications. It is here for illustrative purposes only.

Related Functions:

Latching and Resetting Functions


TimestampParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper of ParameterEdit which makes for easy addition of a ParameterEdit control to a panel for selecting text.
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | ParameterEdit | ColorParameterEdit | NumericParameterEdit | TagParameterEdit | TextParameterEdit | DurationParameterEdit
Format: | \TimestampParameterEdit(Left, Bottom, Right, Top, ParmVal, ParmCodePtr, Title, TitleWidth, PTypeIdx, PtrWaitClose, DialogRoot, InitialTime, 24HourEditing, ID, ToolTitleWidthOut[, Description, TimeOnly, VariableName])
Parameters: |
Left
Required. Any numeric expression for the left edge of the object.
Bottom
Required. Any numeric expression for the bottom edge of the object.
Right
Required. Any numeric expression for the right edge of the object.
Top
Required. Any numeric expression for the top edge of the object.
ParmVal
Required. The parameter value to be altered.
Typically, one element of the array of Parms passed to the panel.
ParmCodePtr
Required. The code pointer to the parameter.
Typically, one element of the array of parameter definition structures.
Title
The title to display
TitleWidth
Width allotted for the Title
PTypeIdx
Index of the Parameter type selection
PtrWaitClose
Wait to close
Typically provided by the panel module.
DialogRoot
Root dialog calling this control
Typically provided by the panel module.
InitialTime
(Optional) Initial time to display in number of seconds since January 1st 1970 00:00:00. Unix time. Default = current time.
24HourEditing
(Optional) Flag - TRUE for 24 hour clock. Default = FALSE
ShowDrawnTagProperty
Optional Boolean. Set true to show "Drawn Tag Property". Defaults to TRUE
ID
Focus ID
ToolTitleWidthOut

[OUT] Width of ParmEdit's tool and title

Description
Optional text describing this parameter
TimeOnly
(Optional) Flag - TRUE to display time controls only. Default = FALSE
VariableName
(Optional) Page variable name, will display ParmEditPageVar snap-in if specified
Comments:

...

Example:

PEObj[3] = TimestampParameterEdit(0,
                PEBot[3],
                PanelWd,
                PEBot[2] + Space,
                Parms[#StartTime],
                ParmDefs[#StartTime],
                GetPhrase("StartTimeLabel"),
                TitleWd,
                0, &(SubWaitClose[3]) { Starting index, PtrWaitClose      },
                Invalid               { DlgRoot                           },
                Invalid, FALSE, 1)    { Initial time, 24-hour editing, ID };


TimeUtils

TimeUtils is a library that exposes a dictionary of time periods and a subroutine to calculate relative time periods. Both the dictionary and the subroutine are described here.

\TimeUtils.Periods

Description: | Dictionary containing time periods.
Returns: | Timestamp
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | CurrentTime
Format: | \TimeUtils.Periods["PeriodName"]["BoundaryName"]
Parameters: |
PeriodName

Text. May be any of the following:

  • CurrentDay
  • CurrentMonth
  • CurrentQuarter
  • CurrentWeek
  • CurrentYear
  • PreviousDay
  • PreviousMonth
  • PreviousQuarter
  • PreviousWeek
  • PreviousYear
BoundaryName

Text. Specifies the start or end boundary of the period, in either UTC or local time. May be any of the following:

  • EndTimeLocal
  • EndTimeUTC
  • StartTimeLocal
  • StartTimeUTC

Comments:

Periods update each time a new period begins. Note that UTC time is adjusted for the local time zone. For example, in Atlantic Daylight Time (GMT - 3), the start of the CurrentDay when this text was written is returned as April 19, 2018, 03:00:00.00

Example:

\TimeUtils.Periods["CurrentWeek"]["StartTimeUTC"]

returns: 1523847600 (April 16, 2018, 03:00:00.00), when run on April 19th, 2018 in Atlantic Daylight Time.

\TimeUtils.GetPeriods

Description: | Subroutine that calculates time periods relative to a given time stamp.
Returns: | Dictionary
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: |
Format: | \TimeUtils.GetPeriods(PeriodName[, ReferenceTimestamp, WeekStartDay, WholePeriod])
Parameters: |
PeriodName

Text. May be any of the following:

  • CurrentDay
  • CurrentMonth
  • CurrentQuarter
  • CurrentWeek
  • CurrentYear
  • PreviousDay
  • PreviousMonth
  • PreviousQuarter
  • PreviousWeek
  • PreviousYear
ReferenceTimestamp

Optional Numeric. Local time, for which relative periods are to be calculated. Defaults to current time.

WeekStartDay
Optional numeric. Specifies which day a week is considered to start on. 0 for Sunday, 1 for Monday, etc. Defaults to the value of the application property, \StartOfWeek.
WholePeriod
Optional Boolean. If TRUE, the EndTime is the end of the full period rather than the ReferenceTime. Defaults to FALSE.

Comments:

The returned dictionary contains all four boundaries of the specified period: "EndTimeLocal", "EndTimeUTC", "StartTimeLocal", "StartTimeUTC".


TimeZone

(Engine-Level Function)

Description: | Returns information on the current time zone setting of the machine.
Returns: | Varies
Usage: | Script only.
Function Groups: | Time and Date
Related to: | Date | DateNum | Day | Month | Now | Seconds | CurrentTime | SetClock | Time | Today | Year | ConvertTimeStamp | TimeZoneList
Format: | TimeZone(Option)
Parameters: |
Option
Required. Any numeric expression giving the information to return as follows:

Option

Returns

0

Time displacement in seconds to UTC

1

Name of time zone (maximum of 32 characters) in "Daylight Time" or "Standard Time", which ever is applicable. The language used will match the user's locale as configured in Windows.

2

Name of time zone (maximum of 32 characters) in "Standard Time" only. The name is given in English only, making this suitable as an input to ConvertTimestamp.

Commonly used for display purposes.

3

A structure of time zone information:
StdTimeZone (Standard time zone)
ObservesDST (Boolean indicating Daylight Savings Time usage when true)

The time zone name is returned in English only, making this suitable as an input to ConvertTimestamp.

Comments: Note that the first two options take account of whether daylight savings is in effect (assuming that that option has been selected on the machine). This means that not only the numeric time displacement, but also the name ("Daylight Time" versus "Standard Time") will vary according to the current date.
The output from the third option (2) is commonly used as an input to the ConvertTimestamp function since that function cannot use the adjusted timezone string from TimeZone(1). Only English is recognized.

Example:

If 1 Main;
[
  msg = Concat("It is now ", CurrentTime(), " ", TimeZone(1));
]


TimeZoneList

(Engine-Level Function)

Description: | Returns a list of time zones.
Returns: | Array of text
Usage: | Script Only.
Function Groups: | Time and Date
Related to: | ConvertTimeStamp | TimeZone
Format: | TimeZoneList()
Parameters: | None
Comments: Entries in the returned list may be used as parameters for the ConvertTimestamp function.
TimeZoneList produces a list of time zones in English, even on non-English versions of Windows.

Example:

Init [
  If 1 Main;
  [
    { Get a list of time zones }
    TZList = TimeZoneList();
  ]
]


Today

(Engine-Level Function)

Description: | Returns the current number of days since January 1, 1970.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | Date | DateNum | Day | Month | Now | Seconds | Year
Format: | Today()
Parameters: | None

Example:

ZText(10, 10 { Lower left corner of text },
      Date(Today(), 4) { Display in Mmm dd, yyyy format },
      0 { Black color },
      0 { Default font });

This displays today's date in the upper left corner of the screen in the format "Mar 18, 1996".


TODBC

(Engine-Level Function)

Description | Performs an ODBC command. Similar to ODBC except that it runs in its own thread (see "Comments" section for differences).
Returns | Nothing (see parameters)
Usage | Script Only.
Function Groups | Database and Data Source, ODBC
Threaded | Yes
Related to: | ODBC | ODBCConfigureData | ODBCConnect | ODBCDisconnect | ODBCSources | ODBCStatus | ODBCTables | TODBCConnect | TODBCDisconnect
Format: | TODBC(DB, SQLCommand, Attrib, Result, ErrorMsg, SQLState, ErrorCode [, QueryTimeout])
Parameters |
DB
Required. An ODBC value for the ODBC database as returned by TODBCConnect or ODBCConnect.
SQLCommand
Required. Any text expression for the SQL command to perform on the ODBC database driver.
Attrib
Required. Any variable that will be set to an array that gives certain information regarding the table returned in the next parameter. The first dimension of the array contains the name of the column in the return table, while the second dimension contains the type - 0 for character data, 1 for numeric data.
Result
Required. Any variable that will be set to an array containing the data resulting from the SQL command. The format for the array is Result[Field][Record].
ErrorMsg
Required. Any variable that will contain the last error message returned by the function. If no errors occurred this parameter will be set to 0 to indicate the termination of the thread.
SQLState
Required. Any variable that will contain the SQL state that the statement was in when the last error occurred.
ErrorCode
Required. Any variable that will contain the native error code for the given driver and an error condition for the last error that occurred.
QueryTimeout
An optional parameter that sets the period (in seconds) which the driver will wait for a query request to complete. The default value of "0" indicates that there is no timeout. Please note that not all ODBC drivers support the optional QueryTimeout parameter. In particular, the Microsoft Access (.mdb) driver. If the driver does not support this option, then an error message will be returned by the statement. If this occurs, then the parameter should be left as Invalid to allow the statement to proceed.
CellLimit

Optional. If provided, returns number of cells to CellLimit.

  • If less than 0 or higher than the total cells, all data is returned.
  • If equal to 0 or less than the number of columns, no data is returned.
  • If CellLimit is not a multiple of the number of columns, partial rows will not be included in the returned data.
HasMoreCells
Optional output parameter. Indicates that more data was available than returned. If the CellLimit is not provided OR is less than 0, all data is returned and the flag updates to FALSE.
Comments This command will require a knowledge of SQL (Structured Query Language).
This function is typically used when a large amount of data is being processed. When TODBC is executed in its script, it starts its own thread and VTScada will continue executing. When the TODBC statement is finished executing, it will set the data in Attrib, give the resultant table in Result and set ErrorCode. Some SQL statements, such as the one for inserting a record into a table, do not return any data, in this case the only indication that the thread has terminated will be that ErrorCode will be set to a valid value - 0 if no errors occurred.
Notice that unlike ODBC, the resultant table is returned in one of the parameters, rather than as a return value and the last three parameters are not optional.
If any error, no matter how minor, occurs as a result of the SQL command having been executed, and the TODBCConnect or ODBCConnect that connected to the database had its Disconnect parameter set true, the value of DB will become invalid (i.e. the connection to the database will be dropped). This includes such trivial indiscretions as using an incorrect table name in the SQL command.

Differences between blocking and non-blocking ODBC calls:
  • Prior to VTS version 10.0, executing one of the following blocking ODBC operations - ODBC, ODBCTables, ODBCConnect, ODBCDisconnect, ODBCBeginTrans, ODBCCommit or ODBCRollback would cause all VTScada script code execution and window painting to suspend until the operation was complete. From VTS 10.0 onwards, only the VTScada script thread making the call is suspended. All other threads and window painting continue to function.
  • Prior to VTS version 10.0, a non-blocking ODBC operation was used to avoid this issue (same set of operations with a 'T' prepended). This leads to more complex script code insofar as you have to initiate an operation in a script and wait for completion in steady-state, but did allow script threads and window painting to continue. However, the Txxx operations were more time consuming to execute, as they each spin up a thread to execute the operation asynchronously. From VTS 10.0 onwards, these operations are more efficient - there is now no performance difference between the Txxx non-blocking variants and the blocking ones. As blocking ODBC calls no longer suspend all other threads, the only reason for using a Txxx variant call is where you wish to allow other script code statements in the same VTScada script thread to execute while the ODBC operation is processing.

Example:

If TimeOut(1, 3) { Execute SQL command every 3 seconds };
[
  TODBC(ODBCHandle { Handle to database },
        "SELECT ALL * FROM LogTasks" { SQL command },
        Attrib, ReturnArray { Results of command },
        ErrMsg, ErrState, ErrCode { Error details });
]


TODBCBeginTrans

(Engine-Level Function)

Description: | Indicates to an ODBC-compliant database that a transaction is to be started. TODBCBeginTrans is similar to ODBCBeginTrans, except that it runs in its own thread (see the Comments section for differences).
Returns: | Nothing (see parameters)
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Threaded: | Yes
Related to: | ODBCBeginTrans | ODBCCommit | ODBCRollback | TODBCCommit | TODBCRollback
Format: | TODBCBeginTrans(DB[, ErrorMsg, SQLState, ErrorCode])
Parameters: |
DB
Required. A n ODBC value for the specified ODBC database as returned by ODBCConnect.
ErrorMsg
A parameter that will contain the last error message returned by the function.
SQLState
A parameter that will return the SQL state that the statement was in when the last error occurred.
ErrorCode
A variable that will contain the native error code for the given driver and an error condition for the last error that occurred.
Comments: TODBCBeginTrans indicates that a transaction is to be started on the specified ODBC database. The statement executes in its own thread, and completion is indicated by the ErrorCode parameter being set to a valid value, or to "0" in the case of no errors.
If any error, no matter how minor, occurs as a result of the statement, and the TODBCConnect or ODBCConnect that connected to the database had its Disconnect parameter set to true, the value of DB will become invalid (i.e. the connection to the database will be dropped).

Example:

StartBegin [
  If Condition WaitBegin;
  [
    TODBCBeginTrans(DB, Invalid, Invalid, ErrCode);
  ]
]
WaitBegin [
  If ErrCode WaitWork;
  [
    { Check Error code }
    …
    ErrCode = Invalid;
    { Do some transaction work }
    …
  ]
]
WaitWork [
  If ErrCode WaitCommit;
  [
    ErrCode = Invalid;
    TODBCCommit(DB, Invalid, Invalid, ErrCode);
  ]
]
WaitCommit [
  If ErrCode Done;
]


TODBCCommit

(Engine-Level Function)

Description: | Indicates to an ODBC-compliant database that a transaction is to be committed. TODBCCommit is similar to ODBCCommit, except that it runs in its own thread (see the Comments section for differences).
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Threaded: | Yes
Related to: | ODBCBeginTrans | ODBCCommit | ODBCRollback | TODBCBeginTrans | TODBCRollback
Format: | TODBCCommit(DB [, ErrorMsg, SQLState, ErrorCode])
Parameters: |
DB
Required. An ODBC value for the specified ODBC database as returned by ODBCConnect.
ErrorMsg
A parameter that will contain the last error message returned by the function.
SQLState
A parameter that will return the SQL state that the statement was in when the last error occurred.
ErrorCode
A parameter that is a variable that will contain the native error code for the given driver and an error condition for the last error that occurred.
Comments: Commits a transaction defined as all the SQL statements since the transaction began. The statement executes in its own thread, and completion is indicated by the ErrorCode parameter being set to a valid value, or "0" in the case of no errors.
If any error, no matter how minor, occurs as a result of the statement, and the TODBCConnect or ODBCConnect that connected to the database had its Disconnect parameter set to true, the value of DB will become invalid (i.e. the connection to the database will be dropped).

Example:

StartBegin [
  If Condition WaitBegin;
  [
    TODBCBeginTrans(DB, Invalid, Invalid, ErrCode);
  ]
]
WaitBegin [
  If ErrCode WaitWork;
  [
    { Check Error code }
    …
    ErrCode = Invalid;
    { Do some transaction work }
    …
  ]
]
WaitWork [
  If ErrCode WaitCommit;
  [
    ErrCode = Invalid;
    TODBCCommit(DB, Invalid, Invalid, ErrCode);
  ]
]
WaitCommit [
  If ErrCode Done;
]


TODBCConnect

(Engine-Level Function)

Description: | Forms a connection to an ODBC database. Similar to ODBCConnect except that it runs in its own thread (see "Comments" section for differences)
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Threaded: | Yes
Related to: | ODBC | ODBCConfigureData | ODBCConnect | ODBCDisconnect | ODBCSources | ODBCStatus | ODBCTables | TODBC | TODBCDisconnect
Format: | TODBCConnect(DSName, UserName, Password, DB, ErrorMsg, SQLState, ErrorCode [, Disconnect, LoginTimeout, ConnectionTimeout])
Parameters: |
DSName
Required. Any text expression for the ODBC data source name, as configured in the ODBC setup menu under Microsoft Windows™.
UserName
Required. Any text expression for the ODBC login user name.
Password
Required. Any text expression for the ODBC login password.
DB
Required. An ODBC value for the ODBC database after a connection has been established.
ErrorMsg
Required. Any variable that will contain the last error message returned by the function. If no errors occurred this parameter will be set to 0 to indicate the termination of the thread.
SQLState
Required. Any variable that will contain the SQL state that the statement was in when the last error occurred.
ErrorCode
Required. Any variable that will contain the native error code for the given driver and an error condition for the last error that occurred.
Disconnect
An optional parameter which is any logical expression that determines how errors are to be handled. If true (non-0), the connection to the database will be disconnected should any error (no matter how minor) occur; if false (0) an error will not cause a disconnect to occur. The default value is false.
LoginTimeout
Sets the period (in seconds) which the driver will wait for a login request to complete. The default value of "0" indicates that there is no timeout.
ConnectionTimeout
Sets the period (in seconds) which the driver will wait for any request other than a query or login on the connection to complete. The default value of "0" indicates that there is no timeout.
Comments: When TODBCConnect is executed in its script, it starts its own thread and VTScada will continue executing. This is similar to ODBCConnect except that execution of the application is not suspended while waiting for the connection to the database (i.e. waiting for the return value to be set). Instead, execution continues and sometime in the future when the connection to the database is established, DB will be set to the ODBC value for the database. If any errors occurred, the error parameters, ErrorMsg, SQLState and ErrorCode, would be set at that time to indicate the nature of the error. ErrorCode will be set to zero if no error occurs.
64-bit VTScada. 64-bit VTScada is able to connect to either 64-bit or 32-bit ODBC data sources. ODBCConnect will first try to connect to the database through a 64-bit ODBC driver. If this fails for any reason it will then try the connection through a 32-bit ODBC driver. This means that any ODBC code that worked under 32-bit VTScada should not need to be modified for use with 64-bit VTScada, but 64-bit VTScada has the extra ability of being able to use 64-bit ODBC drivers.

Example:

Init[
If 1 Wait;
[
TODBCConnect("VTS_data" { Driver name },
" "," " { No user name or password },
ODBCHandle { Handle to use },
ErrMsg, ErrState, ErrCode { Error details });
]
]
Wait[
If TimeOut(1, Retry) Init { Retry ODBC every Retry seconds };
If Valid(ODBCHandle) Main { If valid connection go to Main };
]


TODBCDisconnect

(Engine-Level Function)

Description: | Stops a connection to the ODBC database. Similar to ODBCDisconnect except that it runs in its own thread (see "Comments" section for differences).
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Threaded: | Yes
Related to: | ODBC | ODBCConfigureData | ODBCConnect | ODBCDisconnect | ODBCSources | ODBCStatus | ODBCTables | TODBC | TODBCConnect
Format: | TODBCDisconnect(DB)
Parameter: |
DB
Required. An ODBC value for the ODBC database as returned by TODBCConnect or ODBCConnect.
Comments: When TODBCDisconnect is executed in its script, it starts its own thread which will not stop execution of VTScada, and which will exist until the connection to the database has been broken.

Example:

Main [
  If 1 Idle;
  [
    TODBC(ODBCHandle { Handle to database },
          "SELECT ALL * FROM Table1" { SQL command },
          Attrib, Result { Results of command },
          0, 0, 0 { No err details req'd });
  ]
]
Idle [
  If Valid(Result) Done;
  [
    TODBCDisconnect(ODBCHandle);
  ]
]


TODBCRollback

(Engine-Level Function)

Description: | Indicates to an ODBC-compliant database that a transaction is to be discarded. TODBCRollback is similar to ODBCRollback, except that it runs in its own thread (see the Comments section for differences).
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Database and Data Source, ODBC
Threaded: | Yes
Related to: | ODBCBeginTrans | ODBCCommit | ODBCRollback | TODBCBeginTrans | TODBCCommit
Format: | TODBCRollback(DB[, ErrorMsg, SQLState, ErrorCode])
Parameters: |
DB
Required. An ODBC value for the specified ODBC database as returned by ODBCConnect.
ErrorMsg
A parameter that will contain the last error message returned by the function.
SQLState
A parameter that will return the SQL state that the statement was in when the last error occurred.
ErrorCode
A variable that will contain the native error code for the given driver and an error condition for the last error that occurred.
Comments: Discards a transaction defined as all the SQL statements executed on a database since the transaction began.
If any error, no matter how minor, occurs as a result of the statement, and the TODBCConnect or ODBCConnect that connected to the database had its Disconnect parameter set to true, the value of DB will become invalid (i.e. the connection to the database will be dropped).

Example:

StartBegin [
  If Condition WaitBegin;
  [
    TODBCBeginTrans(DB, Invalid, Invalid, ErrCode);
  ]
]
WaitBegin [
  If ErrCode WaitWork;
  [
    { Check Error code }
    …
    ErrCode = Invalid;
    { Do some transaction work }
    …
  ]
]
WaitWork [
  If ErrCode WaitEnd;
  [
    { Check error code, rollback if bad }
    IfElse(ErrCode != 0, Execute(
      ErrCode = Invalid;
      TODBCRollback(DB, Invalid, Invalid, ErrCode);
    );
    { Else } Execute(
      ErrCode = Invalid;
      TODBCCommit(DB, Invalid, Invalid, ErrCode);
    ));
  ]
]
WaitEnd [
If ErrCode Done;
]


Toggle

(Engine-Level Function)

Description: | Returns its previous status value except when its parameter changes from a false to a true, in which case it changes its value.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Variable
Related to: | Latch
Format: | Toggle(X)
Parameters: |
X
Required. Any numeric expression giving the status value to use to cause the function value to change state.
Comments: This function starts in a state with its return value being the same as its parameter. If the parameter X changes from an in valid value to a valid false, the return value will be 0. If the parameter X changes from an invalid value to a valid true, the return value will be 1.
This function resets its parameters after they evaluate to true. This is significant only for functions which can be reset such as MatchKeys, TimeOut, Intgr and RTimeOut.

Example:

on = Toggle(MatchKeys(2, "A"));

The variable on begins set to 0. Pressing the "A" key will change it to 1; pressing "A" again will change it back to 0. Pressing "A" a third time will change it to 1 again, and so on.

Related information:

Latching and Resetting Functions


ToggleVal

(Function Library)

Description: | Toggles between TRUE (1) and FALSE (0), once each given period.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Variable
Related to: |
Format: | \FunctionLib.ToggleVal(Value)
Parameters: |
Value
Specifies the length of the period for each TRUE / FALSE cycle in seconds.
Comments:

This module is a member of the Function Library, and must therefore be prefaced by \FunctionLib as shown in the "Format" section.

Example:

\FunctionLib.ToggleVal(10)

Will return TRUE for five seconds followed by FALSE for five seconds, completing a cycle every ten seconds.


ToLower

(Engine-Level Function)

Description: | Returns a text string with all the characters converted to lower case.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | ToUpper
Format: | ToLower(String)
Parameters: |
String
Required. Any text expression giving the string to convert to all lower case characters.
Comments: The return value will contain all the same characters as the original string, except each character which is an upper case letter will be replaced with the corresponding lower case letter. All other characters remain unchanged.

Example:

lowerString = ToLower("Hello, Chum");

Upon execution of this statement, lowerString will contain the string "hello, chum".


ToolBar

(System Library)

Description: | Draws and maintains a toolbar and its buttons.
Returns: | Object Value
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | TextBox | VScrollbar
Format: | System.Toolbar(Left, Top, Right, Data [, ParOffset, ParHasBevel])
Parameters: |
Left
Required. The coordinate of the left edge of the toolbar.
Top
Required. The coordinate of the top of the toolbar.
Right
Required. The coordinate of the right edge of the toolbar.
Data
Required. A 2-dimensional array of button information.
ParOffset
An optional parameter that is the data index at which to start. The default for ParOffset is 0.
ParHasBevel
An optional parameter that can be set to FALSE (0) to draw a bevel around the toolbar, or TRUE (1) to inhibit bevel drawing. The default for ParHasBevel is 1.
Comments: Toolbar returns its object value when ready.


ToUpper

(Engine-Level Function)

Description: | Returns a text string with all the characters converted to upper case.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | String and Buffer
Related to: | ToLower
Format: | ToUpper(String)
Parameters: |
String
Required. Any text expression giving the string to convert to all upper case characters.
Comments: The return value will contain all the same characters as the original string, except each character which is a lower case letter will be replaced with the corresponding upper case letter. All other characters remain unchanged.

Example:

upperString = ToUpper("Bye-bye Birdie");

Upon execution of this statement, upperString will contain the string "BYE-BYE BIRDIE".


Trajectory

(Engine-Level Function)

Description: | Move a Layered Graphic and return a Trajectory value.
Returns: | Trajectory
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Normalize | Path | Point
Format: | Trajectory(Normalize, Path)
Parameters: |
Normalize
Required. Any expression that returns a Normalize value. This gives the low and high scales for the animation.
Path
Required. Any expression which returns a Path value, which specifies the path along which the object moves.
Comments:

A Trajectory is a combination of a Normalize value and a Path value, used to move a layered graphic statement along a path. When the Normalize value takes on its low scale value, the layered graphic statement appears at the beginning of the Path. When the Normalize value takes on its high scale value, the layered graphic statement appears at the end of the Path.

This function must be called from within a window. For example, within a script application, it must be within the Graphics submodule.

Example:

bucketTraj = Trajectory(Normalize(bucketPos, 0, 100),
                        bucketPath);

If this Trajectory value is used in a Point, or in a layered graphics function, that graphic will move along the path bucketPath. If bucketPos is 0, the graphic will be displayed at the beginning of bucketPath. If bucketPos is 100, the graphic will be displayed at the end of bucketPath.


Transaction

(ODBC Manager Library)

Description: | Launches a transaction in the specified database connection. The transaction takes care of its own shut-down process.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | ODBC
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction TransactionCached
Format: | \ODBCManager\Transaction( TransObjPtr, ReadyPtr, TErrorPtr, CallerObj, UseTrans, DSN, UserName, Password)
Parameters: |
TransObjPtr
Required. A Pointer to the transaction object
TReadyPtr
Required. A Pointer to a variable, used to set the ready status
TErrorPtr
Required. A Pointer to a variable, used to set the error status
CallerObj
Required. The object value of the original calling module
UseTrans
Required. Set to true (1) to use BEGIN and END of transaction
DSN
Required. DSN of the database to start transaction within
UserName
Required. User name, if required by the database
Password
Required. Password, if required by the database
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.

The only way to ensure that a long running (or faulty) query does terminate is to set appropriate values for both the parameters ExecutionTimeout and UseDriverTimeout. Modules executing queries are designed to be run as launched modules and will remain active until complete.


TransactionCached

(ODBC Manager Library)

Description: | Launches a transaction in the specified database connection. The transaction will be cached locally if it fails and then sent to the database after the next successful transaction. This module is designed to provide logging of values that must not be lost.
Returns: | Returns an object value for the transaction.
Usage: | Script Only.
Function Groups: | ODBC
Related to: | AddConnection | BuildDelete | BuildInsert | BuildSelect | BuildUpdate | ConvertToDbDate | ConvertToDbTime | ConvertToDbTimeStamp | ConvertToVTSDate | ConvertToVTSTime | ConvertToVTSTimeStamp | CopyRecords | DBDropList | DBGridList | ErrMessage | ExecuteQuery | ExecuteQueryCached | FlushCache | FormatBatchQuery | GetConnList | ResultFormat | StatsWin | TableSynch | Transaction
Format: | \ODBCManager\TransactionCached( ErrorPtr, CmdStr, DSN, UserName, Password[, BatchSize])
Parameters: |
ErrorPtr
Required. A Pointer to the error status. Always set valid on completion.
CmdStr
Required. The SQL command to be processed within the transaction.
DSN
Required. DSN of the database within which to start the transaction.
UserName
Required. A user name, if required to connect to the database
Password
Required. A password, if required to connect to the database
BatchSize
Obsolete.
Comments:

This module is a member of the ODBCManager Library, and must therefore be prefaced by \ODBCManager\, as shown in "Format" above.

The only way to ensure that a long running (or faulty) query does terminate is to set appropriate values for both the parameters ExecutionTimeout and UseDriverTimeout. Modules executing queries are designed to be run as launched modules and will remain active until complete.


TransferFields

Deprecated. Do not use in new code. (Alarm Manager module)

Description | The TransferFields subroutine will transfer the values for each field into the returned FieldValues array. The values are found in the scope passed in using the variable names found in the FieldNames array.
Returns | Numeric
Usage | Script Only.
Function Groups | Alarm
Related to: |
Format: | \AlarmManager\TransferFields(AlarmObject);
Parameters |
AlarmObject
Required. The scope to use when searching for the variables to transfer.
Comments TransferFields always returns "0".


TreeControl

(System Library)

Description | Implements a tree control similar to that used by the Microsoft Windows Explorer folder panel.
Returns | Reference to self(). Tree control is ready when return value is valid.
Usage | Steady State only.
Function Groups | Graphics
Related to: | DropTree | GridList | ImportAPI
Format | System.TreeControl(Tree[, GrayOutTextParm, EnableKeyboardControl, NodeCallBackScope, NodeCallBackName, LeftParm, BottomParm, RightParm, TopParm, BackColorParm, TextColorParm, RowHeight)
Parameters |
Tree
Required. Pointer to a structure defining the tree to be displayed. See comments for the structure definition.
GrayOutTextParm
Optional Boolean. True to gray-out text. Default:FALSE
EnableKeyboardControl
Optional Boolean. True to enable keyboard control. Default:FALSE
NodeCallBackScope
Optional object reference. The scope in which to find the callback module. See comments.
NodeCallBackName
Optional text. Name of the callback module for drawing.
LeftParm
Optional numeric. Will default to window dimensions
BottomParm
Optional numeric. Will default to window dimensions
RightParm
Optional numeric. Will default to window dimensions
TopParm
Optional numeric. Will default to window dimensions
BackColorParm
Optional background color.
TextColorParm
Optional text color.
RowHeight
Optional numeric to override the row height.

Comments:

The first parameter describes the tree structure. The structure can be modified at any time, and the TreeControl will faithfully follow it. You can call Refresh at any time to invoke a full rebuild of the tree.

Structure definition:

    NodeStruct Struct [
      Key             { The Key value is user-defined, and must be a value for
                         which the == operator is meaningful. It identifies
                         which node the caller refers to when calling helper
                         subroutines.                                           };
      Label           { Text value displayed. It can be any VTScada value that
                         has a valid textual representation.                    };
      SubTree         { This is a reference to an array of subordinate nodes
                         that are of the same format as this node.              };
      MapIdx          { MapArray entry index.                                   };
      Flags           { Various flags... definitions follow                     };
      Icon            { ICON graphic for the node. Defaults to Folder icon.     };
      Tooltip         { Tooltip text. Defaults to blank.                        };
      Data            { Custom data managed by caller                           };
    ];

For legacy applications, you may continue to use the constants shown in the following table for the tree array. Used this way, the array must be two dimensional, with each row (first subscript) describing a node at the same level in the tree. Each field in the row describes the node further. The first six fields must be the following. Additional fields may be added as needed. In the following table, [n] refers to the row number and #TI_xxx refers to a defined constant within the TreeControl module. These constants are:

  • [n][#TI_KEY]
  • [n][#TI_TEXT]
  • [n][#TI_SUBTREE]
  • [n][#TI_FLAGS]
  • [n][#TI_ICON]
  • [n][#TI_TOOLTIP]

Node attributes to assign to Flags

  • Constant #TIF_EXPANDED = 1 { Flag - true if expanded };
  • Constant #TIF_CANEXPAND = 2 { Flag - true if able to expand };
  • Constant #TIF_NOFOLDER = 4 { Flag - true if not display folder bmp };
  • Constant #TIF_GREYTEXT = 8 { Flag - true if grey this option };
  • Constant #TIF_HIDDENROOT = 16 { Flag - true if root is a hidden root };
  • Constant #TIF_TITLEDTIP = 32 { Flag - true to use titled tooltips };
  • Constant #TIF_POPUPTIP = 64 { Flag - true to NOT use in-place tooltips };

To use the control, the caller (not the parent) can provide the following subroutine modules, which will be called by TreeControl in response to specific events:

OnLeftClick(Node, X, Y, RelX, RelY)
Called when the left mouse button is released over a tree node. Node is the tree node, while X and Y are the coordinates of the mouse. RelX and RelY are the coordinates of the mouse relative to the Line.
OnRightClick(Node, X, Y, RelX, RelY)
Called when the right mouse button is released over a tree node. Node is the tree node, while X and Y are the coordinates of the mouse. RelX and RelY are the coordinates of the mouse relative to the Line.
OnDoubleClick(Node, X, Y, RelX, RelY)
Called when the left mouse button is double-clicked over a tree node. Node is the tree node, while X and Y are the coordinates of the mouse. RelX and RelY are the coordinates of the mouse relative to the Line.
This callback is always proceeded by OnLeftClick() and any node expansion is done prior to calling OnDoubleClick(), but after OnLeftClick().
CreateSubtree(Node)
Called when a tree node has its #TIF_CANEXPAND flag set, but the #TI_SUBTREE member of the node has not yet been constructed. The callee is expected to construct an array of nodes and store them in the node supplied to CreateSubtree.
ExpandTreeToNode(Key)

A sort of superset of CreateSubtree. It is called in response to a call to SetSelected() to command the caller of TreeControl to make all the tree nodes necessary to allow the node containing the Key to be expanded. The caller of TreeControl should call ExpandNode as needed for each node. When this callback returns, the tree will be positioned at the node that contains Key.

The (rough) logic of ExpandTreeToNode is:

Recursively walk up the tree by recursing this subroutine until you get to the tree root. The reverse recursion path is the shortest route from the root back to the node. Unwind the recursion, creating sub-trees as necessary and calling ExpandNode() for any that are not expanded.

OnJunctionSelect(Node)

Called when a node is collapsed only if the currently selected node existed in Node's subtree. When this happens the collapsed node will take the selection. Node is the newly selected (now collapsed) node.

Click events on the junction are handled internally, and no callback is made.

When using callbacks on the selected node, the click detection is still done by the tree itself. You can use ExpandNode or SetSelected if you might prefer a different behavior. The selected node highlight is not done by the Tree Control and needs to be done in a callback, which is defined as follows:

CallBackScope\CallBackName(
                 Left   { },
                 Bottom { },
                 Right  { },
                 Top    { Drawing coordinates (not transformed) },
                 Node   { Array for this Node },
                 Offset { Pixel offset from left coordinate where the text or image will be drawn. });

Public API

TreeControl makes the following API available to any module that calls the ImportAPI function. To do so use:

Init [
  If 1 Main;
  [
    System.ImportAPI(\System.TreeControl);
  ]

{***** Indices into the Tree array nodes *****}
  [ (API)
    {***** Modern node structure to use instead of legacy arrays *****}
    NodeStruct Struct [
      Key                          { "Key" value...see heading comment      };
      Label                        { Text value to be displayed             };
      SubTree                      { Subordinate tree below this node       };
      MapIdx                       { MapArray entry index                   };
      Flags                        { Various flags...see definitions        };
      Icon                         { Icon for node. Default to Folder icon. };
      Tooltip                      { Tooltip text. Default to Label.        };
      Data                         { Custom data managed by caller          };
    ];

    {***** Legacy indicies for a tree node array ***** }
    Constant #TI_KEY           = 0 { "Key" value...see heading comment      };
    Constant #TI_TEXT          = 1 { Text value to be displayed             };
    Constant #TI_SUBTREE       = 2 { Subordinate tree below this node       };
    Constant #TI_MAPARRAYIDX   = 3 { MapArray entry index                   };
    Constant #TI_FLAGS         = 4 { Various flags...see definitions        };
    Constant #TI_ICON          = 5 { ICON graphic for node..folder is default };
    Constant #TI_TOOLTIP       = 6 { In-place tooltip text - #TI_TEXT default };
    Constant #TREE_MINNODESIZE = 7 { Minimum compulsory node size           };

    {***** Node attributes to assign to Flags *****}
    Constant #TIF_EXPANDED   = 1   { Flag - true if expanded                };
    Constant #TIF_CANEXPAND  = 2   { Flag - true if able to expand          };
    Constant #TIF_NOFOLDER   = 4   { Flag - true if not display folder bmp  };
    Constant #TIF_GREYTEXT   = 8   { Flag - true if grey this option        };
    Constant #TIF_HIDDENROOT = 16  { Flag - true if root is a hidden root   };
    Constant #TIF_TITLEDTIP  = 32  { Flag - true to use titled tooltips     };
    Constant #TIF_POPUPTIP   = 64  { Flag - true to NOT use in-place tooltips };
  ]

Public Variables

TreeControl makes the following variables available for you to examine:

[
  Height            { Total number of NODES high.                 };
  Width             { Total number of PIXELS wide.                };
  LineHt            { Height of one line of text in PIXELS        };
  Started  = 0      { Flag - True when internal TreeWin is valid  };
]

Public Subroutines

Refresh
No parameters. Should be called upon building the tree and upon change.
CollapseNodes(Node)
Differs from CollapseNode. Collapse the entire sub-tree below the specified node. This can be done at any time and will not destroy the expanded state of subordinate tree nodes, allowing a subsequent expand to restore the state of the tree as it was before the collapse. This must be called if you want to delete the nodes below a specific point and rebuild them. Failure to call this before deleting nodes will have unpredictable results.
CollapseNode(ItemIndex)
Differs from CollapseNodes. Collapses a MappingArray entry if not already collapsed. This operation recursively destroys any MappingArray entries for each child of the identified item. Does not affect the expanded or contracted indication in the node tree. This allows a subsequent expansion of this node to display itself in it's previous expansion state.
DeleteNode(Node)
Deletes the specified node and its subtree.
ExpandNode(Node)
Expand the indicated node if there are child nodes and if not already expanded.
FindNode(Key, CurrentNode)
Given the "Key" value, returns the node containing that (unique) key. Returns Invalid if none found. WARNING: This subroutine may require significant system resources or time.
InsertNodes(Node, StartIndex, NumNewNodes)

Node { Tree node having its subtree expanded } StartIndex { Start index in its subtree-inserts after this } NumNewNodes { Number of new nodes added }

Note that Node must already be expanded. Also, you cannot add a node to an empty Node. Build the node data and call ExpandNode instead.

SetSelected(TreeObject)

Provide the "Key" value to programmatically select a tree item. The tree will be positioned at the new selected item, expanding if needed.

Example of TreeControl:

{================================= System ====================================}
{=============================================================================}
(
  System                        { Provides access to system library functions };
  Layer                         { Provides access to the application layer    };
)
[
  Graphics               Module { Contains user graphics                      };
  Var                           { Value of element in tree that has been
                                  clicked                                     };
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         "Window Title",
         0, 1);
]
<
{=================================== Graphics ================================}
{ This module displays the graphics for the application.                      }
{=============================================================================}
Graphics
[
  DrawTree Module             { Draws the tree                                };
  SelectedElement             { Selected element                              };

  LHS = 10                    { Left hand side of window                      };
  TOP = 59                    { Top of window                                 };
  Trigger                     { Set when var changed                          };
  Constant HelpID = 1234;
  XPos                        { Window X Location                             };
  YPos                        { Window Y Location                             };
  Width  = 800                { Window width                                  };
  Height = 600                { Window height                                 };
]

Init [
  If 1 Main;
  [
     { If a value that should be selected in the tree has been passed in, use it }
    IfThen(Valid(Var),
      SelectedElement = Var;
    );
  ]
]

Main [

   { Update the window position once it has stopped moving }
  If TimeOut(Watch(0, VStatus(Self, 15), VStatus(Self, 16), VStatus(Self, 11),
                   VStatus(Self, 12)), \DialogMoveTime);
  [
     { Save the current position of the dialog (if it isn't minimized or
       maximized). Only do this if the dialog has moved and after a timeout. }
    XPos   = VStatus(Self, 28) || VStatus(Self, 29) ? XPos   : VStatus(Self, 15);
    YPos   = VStatus(Self, 28) || VStatus(Self, 29) ? YPos   : VStatus(Self, 16);
    Width  = VStatus(Self, 28) || VStatus(Self, 29) ? Width  : VStatus(Self, 11);
    Height = VStatus(Self, 28) || VStatus(Self, 29) ? Height : VStatus(Self, 12);
  ]

   { Draw the tree }
  Window(LHS, TOP,
         Width - 2*10, 0 { View area    },
         Width - 2*10, 0 { Virtual area },
         DrawTree(),
         { 98765432109876543210 }
         0b10000010001000001100,
         "Tree Window Label", "<00000000>", TRUE);

   { OK button }
  If WinButton(Width - 11*10,
               Height - 2*10,
               Width - 6*10,
               Height - 5*10,
               0, "Ok", 1 { FID }, \_DialogFont);
  [
    Var = SelectedElement;
  ]
]

<
{============================ Graphics\DrawTree ==============================}
{ Draws the TreeControl that shows the tree structure of the data. If the     }
{ user selects a node in the tree, that node's value will be used.            }
{=============================================================================}
DrawTree
[
   { Public callback modules }
  OnLeftClick   Module          { Callback for the TreeControl                };
  CreateSubTree Module          { Callback for the TreeControl                };

   { Public working variables }
  HasFocus                      { Expected callback variable for TreeControl  };
  Ready                         { Is the tree control ready to go?            };
  I                             { Counter                                     };

   { Private working variables }
  PROTECTED TreeData            { Data structure for use by Tree Ctrl         };
  PROTECTED TreeCtrlObj         { Tree control instance                       };
  PROTECTED NodeDict            { Used to create the subtree                  };

   { Each folder of the tree object }
  Children1;
  Children2;

   { Array that stores children of the root }
  NodeCategories;
]

Init [
  If 1 ShowTree;
  [
     { Import the Tree Control API }
    System.ImportAPI(\System.TreeControl);

     { Root node of tree (hidden) }
    TreeData = \NodeStruct(Invalid, "RootNode",Invalid, Invalid,
                          \#TIF_EXPANDED + \#TIF_HIDDENROOT,
                           Invalid, Invalid);

     { Put nodes into array }
    Children1 = System.MakeArray(
      \NodeStruct(
                   "Child1Value",
                   "Child1Label",
                   Invalid, 0, \#TIF_NOFOLDER , Invalid, Invalid
                  ),
      \NodeStruct(
                   "Child2Value",
                   "Child2Label",
                   Invalid, 1, \#TIF_NOFOLDER, Invalid, Invalid
                  ),
    );

     { Put nodes into array }
    Children2 = System.MakeArray(
      \NodeStruct(
                   "Child3Value",
                   "Child3Label",
                   Invalid, 0, \#TIF_NOFOLDER , Invalid, Invalid
                  ),
      \NodeStruct(
                   "Child4Value",
                   "Child4Label",
                   Invalid, 1, \#TIF_NOFOLDER, Invalid, Invalid
                  )
    );

     { Put all the children into 1 array so we know how many children
       the root node should have }
    NodeCategories = System.MakeArray(
                                        Children1,
                                        Children2,
                                      );
     { Used to make the subtree }
    NodeDict = System.MakeDictionary(
                                      "Folder1", Children1,
                                      "Folder2", Children2
                                    );

    CreateSubTree(TreeData);
  ]
]

ShowTree [
  Return(Self);

  SizeWindow(Self, width-2*10, height-10-13*10);

   { We're ready whenever our Tree Control is valid }
  Ready = Valid(TreeCtrlObj);

   { When the TreeCtrlObj becomes ready, expand the tree to the selected node }
  If Watch(0, Ready) && Ready;
  [

    IfElse(Valid(SelectedElement),
       { If a value that should be selected in the tree has been passed in, use it }
      TreeCtrlObj.SetSelected(SelectedElement),
       { Example of selecting a node in the tree }
      TreeCtrlObj.SetSelected("Child2Value")
    );
    TreeCtrlObj.ExpandNode(TreeData.SubTree[0]);
  ]

   { The tree control looks at our HasFocus variable to see if it
     has focus. We have focus if our calling module has focus. }
  HasFocus = ActiveWindow() == Caller(Self);
  TreeCtrlObj = System.TreeControl(&TreeData);

   { Rebuild the Tree Control's map array, anytime we build a new Tree Control }
  If Watch(1, Valid(TreeCtrlObj));
  [
    IfThen(Valid(TreeCtrlObj),
        TreeCtrlObj.Refresh();
    );
  ]
]

<
{====================== Graphics\DrawTree\CreateSubTree ======================}
{ Callback for creating a sub tree.                                           }
{=============================================================================}
CreateSubTree
(
  Node                        { Node that needs a sub-tree                    };
)
[
  Key                         { Key of new child node                         };
  Folders                     { Folder   names                                };
]

CreateSubTree [
  If 1;
  [
    IfThen(!Valid(Node.SubTree),
      Folders   = ListKeys(NodeDict);
      Node.SubTree = New(ArraySize(NodeCategories));

      I = 0;
      WhileLoop(I < ArraySize(Folders),
        Key = NodeDict[Folders[I]];

        { Key for folders will start with '_' because an element in the
             subtree may have the same name as the folder which will cause
             both elements to be selected if either of them are clicked }
        Node.SubTree[I] =
          \NodeStruct(Concat("_", Folders[I]), Folders[I], Key, Invalid,
                      \#TIF_CANEXPAND, Invalid, Invalid, Invalid);
        I++;
      );
    );
    Return();
  ]
]

{ End of Graphics\DrawTree\CreateSubTree }
>

<
{=============== Graphics\DrawTree\OnLeftClick ==============}
{ Callback when node is clicked                                               }
{=============================================================================}
OnLeftClick
(
  Node     { Node that was clicked                                           };
)

OnLeftClick [
  If 1;
  [
    SelectedElement = Valid(Node.SubTree) ? "" : Node.Key;
    Return();
  ]
]

{ End of Graphics\DrawTree\OnLeftClick }
>
{ End of Graphics }
>
>


TriggerCounter

(Function Library)

Description: | Returns a count of zero-to-non zero transitions during the current session.
Returns: | Integer value.
Usage: | Script or steady state.
Function Groups: | Variable
Related to: |
Format: | \FunctionLib.TriggerCounter(Value)
Parameters: |
Value
A Boolean value (0 or 1).
Typically the value of a digital tag would be used.
Comments:

This module is a member of the Function Library, and must therefore be prefaced by \FunctionLib as shown in the "Format" section.

Example:

\FunctionLib.TriggerCounter([Pump 1])

Will return the number of times that Pump 1 starts, during the current session.

The count is not retained.


TrimSpaces

System Module

Description: | Returns text with leading and trailing spaces removed.
Returns: | Text
Usage: | Script or steady state.
Function Groups: | String and Buffer
Format: | System.TrimSpaces(TextValue)
Related to: | StrJustify
Parameters: |
TextValue
Required. The string to be trimmed.
Comments: Spaces within the text are left untouched.

Example:

CleanText = System.TrimSpaces(" The quick brown fox ");

CleanText will contain "The quick brown fox".


Trip

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Tell the Alarm Manager that a trip alarm event occured. This subroutine will signal an alarm as unacknowledged.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Alarm
Related to: | Register (Alarm Manager) | CurrentTime
Format: | \AlarmManager\Trip(AlarmObject[, EventTime]);
Parameters: |
AlarmObject
Required. The object value for the alarm that was passed to the Register subroutine.
EventTime
Optional. The time stamp to use when adding this event to the alarm lists. If invalid or not defined, the default is CurrentTime().
Comments: The Trip subroutine always returns "0".


True

(Engine-Level Function)

Description: | For use in expressions that perform Boolean logic. Using "TRUE" will make your code easier to read than using "1".
Returns: | With no parameters, returns the value, 1. If given a parameter, this function will return a 1 or 0 depending on whether the parameter evaluates to TRUE or FALSE. Always returns 0 if the parameter is Invalid.
Usage: | Script or steady state.
Function Groups: | Logic Control
Related to: | False
Format: | True[(TestExpr)]
Parameters: |
TestExpr
Optional. Any expression that evaluates to a 1 or 0 value. If no parameter is provided, then there is no need to include the parentheses.
Comments:

This function exists to make your code more readable. It is equivalent to

PickValid(Cast(Parameter, 0) == 1, 0);

For compatibility with the VTScada style guide, use all caps (TRUE and FALSE) when used as a constant. Capitalize only the first letter when used as a function call: True(test expression) and False(test expression).

Examples:

Given the following code in a simple page:

[
  Title = "OverviewLabel";
  Color = "<FFFFFFFF>";
  Y;
]

Main [
  ZText(100,100,Y ? "Y is true": "Y is false", 0,0);
  ZText(100,120,True(Y) ? "Y is true": "Y is false", 0,0);
  Return(Self);
]

Only the text at 100,120 will be shown. In the first call to ZText, Y is Invalid and therefore neither true nor false. The use of True(Y) in the second call to ZText ensures that the test always evaluates to true or false.


TServerList

Deprecated. May not work with newer applications or networks. Use GetAllWorkstationNames in new code.

(Engine-Level Function)

Description: | Executes in its own thread and creates a pointer to an array of all servers visible from this workstation. Returns a flag indicating its status upon completion.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Database and Data Source, Network
Related to: | ServerList | WKStaInfo
Format: | TServerList(Result, Domain)
Parameters: |
Result
Required. Any variable in which the resultant one-dimensional array of servers or an error code will be returned.
Domain
Required. Any text expression for the domain. If this is invalid, the current domain will be used.
Comments: When TServerList is executed in its script, it creates its own thread and VTScada continues executing. When it is finished executing, it will store resultant data in Result (unlike ServerList which returns its result). Result will be set to an error code if any network problems were encountered, or if Domain was not found on the network.
This function returns 1 if the thread was successfully started and 0 otherwise.

Example:

If ! Valid(serverArray) Wait;
[
  started = TServerList(serverArray, WkStaInfo(2));
]


U Functions

The sections that follow identify all VTScada functions beginning with "U".


UIErrorToText

Security Manager Module

Description | Returns a text string corresponding to the error code provided.
Returns | String
Usage | Script or steady state.
Related to: | GetAccountID | GetAccountInfo | GetFullName | GetGroupName | GetUserName | IsLoggedOn | IsSecured | IsSuspended | SecurityCheck |
Format: | \SecurityManager\UIErrorToText(ErrCode)
Parameters |
ErrCode
One of the #SMAPIErrxxx error codes.
Comments None.

Related information:

Security Manager Return Codes


UnEscape

(System Library)

Description: | Decodes a string that was URL-encoded.
Returns: | Text
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | EncodeURIComponent
Format: | System.HTTPServerInst.UnEscape(Input)
Parameters: |
Input
Required text. The string to be decoded.
Comments:

This function will remove any HTML escape sequences, convert any '+'s to spaces and convert any %nn encodings to the raw character value, reversing the effects of EncodeURIComponent.

Example:

  IF Watch(1);
  [
    InStr = "Hello(there) And.<testing>";
    OutStr = System.HTTPServerInst.EncodeURIComponent(InStr);
     { OutStr now contains "Hello(there)%20And.%3Ctesting%3E" }
    Reversed = System.HTTPServerInst.UnEscape(OutStr);
     { Reversed now contains "Hello(there) And.<testing>" }
  ]


Unpack

(Engine-Level Function)

Description: | Unpacks a set of values from a stream into a single dimensional array or a set of variables referenced by object parameters, and returns the number of items unpacked.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Array, Stream and Socket
Related to: | Pack
Format: | Unpack(Data, Start, End, Stream[, TruncateAt, DataLength, MirrorKey])
Parameters: |
Data
Required. An object value or an array containing the data or the object value of the module whose parameters address variables into which to store the data.
For example, if you have 5 numeric values to unpack, you would allocate a 1-dimensional array, 5 elements in length. You would pass this array to Unpack's Data parameter, and specify that you wish to unpack from subscript 1 to 5. Refer to the example section for more information.
Start
Required. The starting array index (zero-based), or parameter number (one-based) of the data to unpack.
End
Required. The last array index, or parameter number of the data to unpack.
Stream
Required. A variable holding the stream that contains the data to be unpacked. The stream must have been generated with the Pack function.
TruncateAt
An optional parameter. If present specifies that all text values and stream values unpacked from the stream will be truncated after the number of bytes specified in this parameter.
DataLength
An optional parameter. If present, specifies an array into which will be stored the length of each text and stream value unpacked from the source stream.
Each length is stored at the array index corresponding to the index of the value itself. For example, if the value that would go in the destination array at index 5 were a text value, its length would be stored at index 5 in the array addressed by this parameter.
Unpacked values of numeric type have Invalid stored in their entry in this array.
MirrorKey

Optional. A dictionary mapping integers to structure names. Must be used if the data was packed using a KeyDictionary.

There is no requirement for the Pack KeyDictionary parameter and the Unpack MirrorKey parameter to have the same number of elements. All that is required is that the Unpack MirrorKey dictionary has all of the structures that are in that particular packed stream. If the KeyDictionary doesn’t have the structure that was packed, the returned data is a simple array rather than a structure.

Comments:

This function returns the number of values unpacked.
If the Data parameter is an array, the data from the stream will be unpacked into that array.
If the Data parameter is an object value, the parameters of that object must contain pointers to variables into which the data from the stream will be unpacked.

If the Pack function used the optional parameter, Key, to pack a record into a smaller stream, then Unpack must be able to provide a mirrored version of that dictionary to access the data in the structure.

Example:

If you wish to pack 2 3-dimensional arrays, you would allocate a 1-dimensional array, 2 elements in length. You would then assign the 3-dimensional arrays to the 1-dimensional array elements, and then Pack the 1-dimensional array.

For example:

Array1D = New(2);
Array1D[0] = Array3D_1;
Array1D[1] = Array3D_2;
Pack(Array1D, 0, 1, &Stream);

Unpacking this is almost an identical operation:

Array1D = New(2);
UnPack(Array1D, 0, 1, Stream);
Array3D_1 = Array1D[0];
Array3D_2 = Array1D[1];

All you need to know is how many things you wish to pack and unpack, not the sizes or types of the things (a ValueType(Array1D[0]) will tell you the type). As the stream position is moved after each pack or unpack, you can simply unpack one item at a time and check the return value of UnPack.

Example 2:

In this example, the presence of a Key parameter allows the example to be packed into a stream that is less than half the size that would be obtained without the Key parameter. (Exact number depending on the names used in the structure definitions.)

"Record", "Values", and "AA_Info" are all STRUCTs.

Rec = Record( GetGUID(1)             { GUID       },
              1                      { Priority   },
              Values(87, 54, "feet") { Values     },
              System.MakeDictionary("AA",
                             AA_Info("AAData1", 2)) { Extensions });

{ Omitted: Place record in ArrayToPack }

Key = System.MakeDictionary("Record", 0,
                             "Values", 1,
                             "AA_Info", "AA")

Pack(ArrayToPack, 0, 0, &PackStream, Key);

{ Omitted: Rewind stream }

MirrorKey = System.MakeDictionary("0", Record,
                                   "1", Values,
                                   "AA", AA_Info));

UnPack(UnpackedArray, 0, 0, PackStream, Invalid, Invalid, MirrorKey);


UnpackData

(RPC Manager Library)

Description: | This method unpacks a stream into an array or set of module instance parameters. Subroutine call only.
Returns: | Nothing (see parameters)
Usage: | Script Only.
Function Groups: | Array, Stream and Socket
Related to: | Pack | Unpack
Format: | \RPCManager\UnpackData(Source, Start, End, Stream [, TruncLen, DataLen]));
Parameters: |
Source
Required. The array to contain the data or the object value of the module whose parameters address variables into which to store the data.
Start
Required. The starting array index or parameter number of the data to unpack (zero-based).
End
Required. The last array index or parameter number of the data to unpack (zero-based).
Stream
Required. The stream that contains the data to be unpacked. The stream must have been generated with the PackData function.
TruncLen
An optional parameter that specifies that all text values and stream values unpacked from the stream will be truncated after the number of bytes specified in this parameter.
DataLen
An optional parameter that specifies an array into which the length of each text and stream value unpacked from the source stream will be stored. Each length is stored at the array index corresponding to the index of the value itself.
For example, if the value which would go in the destination array at index 5 were a text value, its length would be stored at index 5 in the array addressed by this parameter.
Unpacked values of numeric type have Invalid stored in their entry in this array.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.SRC.
The stream contents to be unpacked by the UnpackData method must have been packed by the PackData method.
If the Source parameter is an array, the data from the stream will be unpacked into that array. If the Source parameter is an object value, the parameters of that object must contain pointers to variables into which the data from the stream will be unpacked.
From VTS 5.20 onwards, this method is a wrapper for the Unpack() statement. Prior to that release, the Unpack() statement was effectively coded in script by this method. New code should use the Unpack() statement, rather than this method.

Related information:

RPC Manager Service


UnpackParms

(RPC Manager Library)

Description: | This method unpacks a stream into the supplied parameters. Subroutine call only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Network, Stream and Socket
Related to: | PackParms
Format: | \RPCManager\UnpackParms(Stream [, &P1, &P2, …]);
Parameters: |
Stream
Required. A stream produced by PackParms.
P1, P2, …
Optional parameters that are pointers to variable instances into which the values that were packed into the stream will be unpacked. Up to 100 parameters are allowed.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.SRC.
The stream contents must have been packed by the PackParms method.

Related information:

RPC Manager Service


Unregister

Viewing: Reference > Function Reference > U Functions > Unregister

Unregister (Alarm Manager)

Deprecated. Do not use in new code.

(Alarm Manager module)

Description: | Notify the Alarm Manager that an alarm has been removed. This will not generate an alarm. It only removes it from the list of all configured alarms.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Alarm
Related to: |
Format: | \AlarmManager\Unregister(AlarmObject);
Parameters: |
AlarmObject
Required. The object value of the alarm to remove from the Alarm Manager database.
Comments: The Unregister subroutine always returns "0".


UnselectGraphics

(Engine-Level Function)

Description: | Will deselect all of the graphics in the specified window.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Graphics, Window
Related to: | SelectArea | SelectDAG | SelectGraphic | UnselectObject
Format: | UnselectGraphics(Window)
Parameters: |
Window
Required. Any expression which gives the object value of any module instance which is drawn in the window.

Example:

If ZButton(30, 100, 130, 70, "Deselect", 1);
[
  UnselectGraphics(Self());
]

If the button that is displayed in the upper left corner of the window is pressed, all graphic objects I that window that were selected will become deselected.


UnselectObject

(Engine-Level Function)

Description: | Will deselect a statement in the context supplied.
Returns: | Nothing
Usage: | Script or steady state.
Function Groups: | Graphics
Related to: | SelectArea | SelectDAG | SelectGraphic | UnselectGraphics
Format: | UnselectObject(Object, Statement)
Parameters: |
Object
Required. Any expression which gives the object value for the instance where the graphic is to be deselected.
Statement
Required. The value of the statement which is to be deselected.


UnTransform

(Engine-Level Function)

Description: | Will undo a previous transform so that the module instance and everything it has called will not be transformed.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics, Advanced Module
Related to: | GUITransform | GetXformRefBox
Format: | Untransform(Object)
Parameters: |
Object
Required. Any expression which gives the object value for the instance to be untransformed.
Comments: This function is used to allow a module instance to draw in the default window coordinates even if the instance is contained within a transform.
This statement may only appear in a script.

Example:

Suppose that the System module calls module Pump inside of a transform as follows:

GUITransform(0, 90, 90, 0 { Bounding box for transform },
             1, 1, 1, 1, 1 { No scaling },
             0, 0 { No trajectory or rotation },
             1, 0 { Graphics visible; reserved },
             0, 0, 0 { Cannot be focused },
             Pump() { Module to transform });

Now let us further suppose that Pump calls a module named Reservoir. This module will also be affected by the transform of its caller unless it uses Untransform to nullify the effects of the transform performed on Pump. The following is the first state of module Reservoir:

Init [
  If 1 Main;
  [
    Untransform(Self());
  ]
]

With this as its first state, Reservoir will now be drawn in the window as if it were called directly from System, that is to say, it will not be affected whatsoever by the transform that resizes its caller, Pump. Notice that the Untransform function need only be called once; no matter what further state changes occur within Reservoir, it will remain unaffected by the transform that affects Pump.


UnTypedParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper for ParameterEdit, add a control to a panel without requiring a type.
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | ParameterEdit| ColorParameterEdit | DurationParameterEdit | NumericParameterEdit | TextParameterEdit | TimestampParameterEdit | TagParameterEdit
Format: | UntypedParameterEdit(Left, Bottom, Right, Top, ParmVal, ParmCodePtr, Title, PtrWaitClose, DialogRoot, PTypeIdx[, TitleWidth, ShowDrawnTagProperty, ID, Translate, ToolTitleWidthOut, Description, NLines, MinLimit, MaxLimit, IsSpinBox, DroplistChoices])
Parameters: |
Left
Required. Any numeric expression for the left edge of the object.
Bottom
Required. Any numeric expression for the bottom edge of the object.
Right
Required. Any numeric expression for the right edge of the object.
Top
Required. Any numeric expression for the top edge of the object.
ParmVal
The parameter value to be altered.
Typically, one element of the array of parameters passed to the panel.
ParmCodePtr
The code pointer to the parameter.
Typically, one element of the array of parameter definition structures that correspond to the ParmVal.
Title
The title to display.
PtrWaitClose
Wait to close.
The parameter edit module will set the value of this pointer to true when the caller should wait to close. For example, if the parameter edit is displaying a dialog, or completing a calculation.
DialogRoot
Root dialog calling this control.
Typically provided by the panel module.
PTypeIdx
Index of the Parameter type selection.
TitleWidth
Optional, number of pixels allotted for the width of the title.
ShowDrawnTagProperty
Optional Boolean, set to TRUE to show "Drawn Tag Property". Defaults to TRUE.
FocusID
Optional value from 0 to 32767 for the focus ID of this control.
Translate
Optional. How text option translation is handled
0 - Use text as it is entered
1 - Use PhraseID Wrapped in GetPhrase() (Default)
2 - Use PhraseID not wrapped in GetPhrase()
ToolTitleWidthOut
Optional numeric output value. Holds the width of the parameter edit's tool and title.
Description
Optional text describing this parameter.
NLines
Height of the edit field of the text option. Default = 2 lines
MinLimit
Minimum limit of the selection.
MaxLimit
Maximum limit of the selection.
IsSpinBox
Optional Boolean. When TRUE the numeric option is displayed as a spin box.
DroplistChoices
Optional. Dynamic array. Contains the array of labels for a droplist. If it is valid, the UnTypedParamterEdit's value will be displayed as a droplist.
Comments:

Automatically determines what module to use for display and entry of the existing value.

Supports text, numeric, tag, parameter, tag property, text expression, and expression options.

If DroplistChoices is valid, the numeric option value will be displayed as a droplist, with the first entry setting the value to 0, the second to 1, and so on.

Example 1:

ParmEditObj = \UntypedParameterEdit(0, 2 * (EditHt + Space), PanelWd, 0,
                          Parms.StatusMessage       { The Parameter value to alter                },
                          ParmDefs.StatusMessage    { The code pointer to the parameter           },
                          \GetPhrase("StatusLabel") { The title to display                        },
                          &SubWaitClose             { Wait to close                               },
                          DialogRoot                { Root dialog calling this control            },
                          0                         { Index of the Parameter type selection       },
                          Invalid                   { Width alloted for the Title                 },
                          True                      { True to show "Drawn Tag Property"           },
                          1                         { Focus ID                                    },
                          0                         { Use text as it is entered                   },
                          Invalid                   { [OUT] Width of ParmEdit's tool and title    },
                          Invalid                   { Optional text describing this parameter     },
                          1                         { Height of the edit field of the text option });

Example 2:

ModeOptions[0]      = GetPhrase("OffLabel");
ModeOptions[1]      = GetPhrase("OnLabel");
ModeOptions[2]      = GetPhrase("AutoLabel");
ModeOptions[3]      = GetPhrase("ManualLabel");

{***** OperatingMode *****}
ParmEditObj[0] = \UntypedParameterEdit(Left                                   { Placement coordinate                          },
                                       Bottom                                 { Placement coordinate                          },
                                       Right                                  { Placement coordinate                          },
                                       Top                                    { Placement coordinate                          },
                                       Parms[#OperatingMode]                  { The Parameter value to alter                  },
                                       ParmDefs[#OperatingMode]               { The code pointer to the parameter             },
                                       "Operating mode"                       { The title to display                          },
                                       &(SubWaitClose[0])                     { Wait to close                                 },
                                       DialogRoot                             { Root dialog calling this control              },
                                       1                                      { Index of the Parameter type selection         },
                                       TitleWidth                             { Width alloted for the Title                   },
                                       Invalid                                { True to show "Drawn Tag Property"             },
                                       1                                      { Focus ID                                      },
                                       Invalid                                { How text option translation is handled        },
                                       Invalid                                { [OUT] Width of ParmEdit's tool and title      },
                                       Invalid                                { Optional text describing this parameter       },
                                       Invalid                                { Height of the edit field of the text option   },
                                       0                                      { Minimum limit of the numeric option           },
                                       3                                      { Maximum limit of the numeric option           },
                                       False                                  { TRUE to display the numeric option as spinbox },
                                       ModeOptions                            { Valid to display the numeric option as a droplist });


UpdateCoordinates

(Engine-Level Function)

Description: | Will update a graphic statement's coordinates to the document file in which it is specified.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Graphics, Advanced Module
Related to: |
Format: | UpdateCoordinates(Statement)
Parameters: |
Statement
Required. Any expression which gives a statement pointer or code value for the graphic statement which is to be updated.
Comments: It should be noted that after this graphic statement is recompiled that any new instances of that statement will have the new coordinate information stored in them.


UserCredChange

Security Manager Module

Description: | The return value will increment each time there is a change in the user session’s logged-in user or their password.
Returns: | Integer
Usage: | Steady State only.
Related to: | AlternateLogoff | AlternateLogon | Authenticate | LogOff | QuietLogon | UserLogonDialog
Format: | \SecurityManager\UserCredChange(Session);
Parameters: |
Session
The object value of the user session.
Comments: Initially returns zero
For VIC sessions, this additionally increments its return value at twice the rate specified by the SessionTokenTimeout configuration setting. This is used by internal system components to refresh a VIC’s security session token.


UserLogonDialog

Security Manager Module

Description: | Launches the Sign in dialog
Returns: | Nothing
Usage: | Script Only.
Related to: | AlternateLogoff | AlternateLogon | Authenticate | LogOff | QuietLogon | UserCredChange
Format: | \SecurityManager\UserLogonDialog([Device, Namespace, Center, Embed, DialogX, DialogY, DialogDirection, pULDObj, AppLayer]);
Parameters: |
Device
Name of device signing in.
NameSpace
Default setting for the realm name (optional)
Center
TRUE to center dialog on screen (default=0).
Embed
TRUE to draw the dialog embedded in a page

FALSE to show the dialog in a window (default)

DialogX
X coordinate to base dialog position upon.
DialogY
Y coordinate to base dialog position upon.
DialogDirection
Numeric code giving the direction from (DialogX,DialogY) to displace:
Code value | Direction to displace
0 | Down and Right
1 | Down and Left
2 | Up and Right
3 | Up and Left
pULDObj
Returns a pointer that is set to the sign in dialog.
AppLayer
Layer value of the calling Layer.
Comments: None


V Functions

The sections that follow identify all VTScada functions beginning with "V".


Valid

(Engine-Level Function)

Description | Returns true if the parameter is any value other than Invalid.
Returns | Boolean
Usage | Script or steady state.
Function Groups | Variable
Related to: | Invalid
Format: | Valid(X)
Parameters: |
X
Required. Any expression to be tested for validity.
Comments This function always returns a valid value.

Examples:

  A = Valid(1.23);
  B = Valid("Help");
  C = Valid(Invalid);
  D = Valid(12.3 / 0);

The values for A, B, C and D will be 1, 1, 0 and 0 respectively.

A common use for this function is as an action trigger to prevent "if 1" conditions:

  If !Valid(StartTime);
  [
    StartTime = Seconds();
  ]

This will cause the script to execute once and once only. StartTime will be set to the time (in seconds since midnight) that the script was executed.


ValidateEmailAddrs

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | This subroutine validates a string of email addresses, and returns TRUE if the email addresses in the string are syntactically valid, or FALSE if they are not.
Returns: | Boolean
Usage: | Script or steady state.
Function Groups: | Email
Related to: | SendMail
Format: | \ValidateEmailAddrs(EmailAddress)
Parameters: |
EmailAddress
Required. The string of email addresses to check.
Comments: Multiple addresses are assumed to be separated by semi-colons in the input string. This subroutine returns TRUE if the email addresses in the string are syntactically valid, otherwise, FALSE is returned.

ValidateEmailAddrs checks that each address has an @ symbol that is not the first or last character, and that each address has a dot appearing at least 2 characters after the @ symbol, with no dot appearing immediately after the @ sign, and no dot as last character.


ValueType

Viewing: Reference > Function Reference > V Functions > ValueType

Concepts:

Value Types

Parameter and Variable Type Checking

Reference:

VTScada Value Types

Variable Class Definitions

Variable Storage, Retention, Access

ValueType

(Engine-Level Function)

Description: | Returns the type of value passed to it.
Warning: | This function should be used by advanced users only.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Variable
Related to: | Cast
Format: | ValueType(Val)
Parameters: |
Val
Required. Any expression.
Comments: This returns the type of the value passed in the parameter

Example:

type = ValueType(2.31);

The value of type will be 3.

Related information:

VTScada Value Types


VarAttributes

(Engine-Level Function)

Description: | Returns the attributes bit field of a variable.
Warning: | This function should be used by advanced users only.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Compilation and On-Line Modifications, Variable
Related to: |
Format: | VarAttributes(Variable)
Parameters: |
Variable
Required. Any variable value expression.
Comments: The return value indicates the attributes of the variable by setting certain bits in the value as follows:
Return Value | Bit No. | Attribute
1 | 0 | Array
2 | 1 | Shared
4 | 2 | Persistent
8 | 3 | Module
16 | 4 | Parameter
32 | 5 | Constant
64 | 6 | <obsolete>
128 | 7 | <obsolete>
256 | 8 | Temporary
512 | 9 | Protected

(See: Bitwise Parameters & Operations)


Variable

(Engine-Level Function)

Description: | Accesses a variable by its text name. The return value is optional.
Returns: | Varies - see comments
Usage: | Script or Steady State
Function Groups: | Variable
Related to: | FindVariable | Scope | SetDefault
Format: | Variable(Name)
Parameters: |
Name
Required. Any text expression giving the name of the variable.
Comments:

This function can be used on the left side of an assignment, in which case the value will be assigned to the variable named in the Name parameter. This function can be used for debugging, or to create sophisticated data logging and monitoring packages which access any variable by its typed-in name.
Note that the string containing the name may not contain leading or trailing spaces, or square brackets [ ].

This function is the same as the '\' operator, when the '\' operator is before a single operand. (\Member).

This function is able to resolve variables that have the PROTECTED attribute.

LocalVariable

A related function, LocalVariable() exists, but will be used rarely. No documentation is provided beyond the following note:

LocalVariable(Name) is the same as Scope(Self, Name, TRUE). This expression is useful only in the case that there is a value containing the name of a variable, which is added after the module is compiled and is referenced within the local module. LocalVariable is the same as the '.' operator.

.Member (i.e. without an object before the dot) compiles to LocalVariable("Member"), which is the equivalent of Variable("Member", TRUE).

Example:

trendValue = Variable(trendPointName);

The variable trendValue is set equal to the value of the variable named by variable trendPointName. The variable trendPointName is a text variable, which might hold the text name of a point entered by the operator from the keyboard.

Variable(motorSPName) = newSP;

This shows how to set the value of a variable given its text name. The variable motorSPName is a text variable that holds the name of the destination variable.


VariableClass

(Engine-Level Function)

Description: | Returns the class of a variable.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Variable
Related to: | SetVariableClass
Format: | VariableClass(Variable)
Parameters: |
Variable
Required. Any expression for the variable value.
Comments: This function may only appear in a script.

Example:

The following sets the variable "class" to the class of variable newVar.

If ! Valid(class);
[
  class = VariableClass(FindVariable("newVar", Self(), 0, 1));
]

Find the class of Alarm Priority tags:

Class = VariableClass(FindVariable("AlarmPriority", \Code, 0, 0));


Variance

(Engine-Level Function)

Description: | Returns the statistical sample variance for a subsection of an array.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Array, Generic Math
Related to: | AMax | AMin | AValid | FiltHigh | FiltLow | FitOffset | FitSlope | Mean | SDev | Sum
Format: | Variance(ArrayElem, N)
Parameters: |
ArrayElem
Required. Any numeric array element giving the starting point in the array for the computation. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to compute. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Comments:

The invalid parameters are not skipped over, but they are not included in the calculation. The function returns an invalid result if either of its parameters is invalid or if there are less than two valid numerical array elements in the specified range.

This function does calculations with double-precision floating point values and does not support 64-bit integers computations.

Example:

weight[0] = Invalid();
weight[1] = 0;
weight[2] = 1;
weight[3] = 3;
weight[4] = 1;
weight[5] = 5;
prodVariance = Variance(weight[4] { Starting array element },
4 { No. of elements to use });

The variable prodVariance will be the variance of elements 4, 5, 0 and 1 of the array weight, which is 7. Because element 0 is an invalid element, the variance will be calculated using only the 3 valid elements.


Version

(Engine-Level Function)

Description: | Returns the version number of the copy of VTScada currently running.
Returns: | Text
Usage: | Script or Steady State
Function Groups: | Software and Hardware
Related to: | SerialNum | VersionRequired | GetRemoteVersion
Format: | Version([MiniDumpHandle, InfoType])
Parameters: |
MiniDumpHandle
For advanced use only. If provided, will return information about the version number or bit-width of a mini dump file. Data is stored in a MiniDumpHandle (value type: 42)

It is recommended that you simply use INVALID as a placeholder for this parameter when the second parameter is required.
InfoType
If 0 or omitted, Version simply returns the VTScada version number.
If 1, will return 32 for 32-bit VTScada or 64 for 64-bit VTScada, instead of the version number.
Comments: This function can be used to perform various tasks based on the version number of VTScada.

Example:

ZText(10, 10, Concat("VTScada version ", Version()), 0, 0);

This displays the version number of VTScada.


VersionRequired

(Engine-Level Function)

Description: | Returns the version number of VTScada that is required to execute any .RUN files loaded since the last execution of this statement.
Returns: | Text
Usage: | Script only.
Function Groups: | Software and Hardware
Related to: | Version
Format: | VersionRequired()
Parameters: | None
Comments: This function returns the minimum version of VTScada required to execute any and all modules (.RUN files) loaded since the last call to this function, or if no other call was made, since startup. After the call is made to this function, it will reset the version to invalid until another module is loaded.

Example:

If 1 Next;
[
  minVersion = VersionRequired();
  IfThen(minVersion > Version(),
  msg = Concat(".RUN files require version ", minVersion);
  msgOpen = 1;
  );
]

This script tests the version number of VTScada required to execute .RUN files loaded prior to this point in the application and executes a series of statements if they are greater than the version of VTScada that is currently running.


Vertex

(Engine-Level Function)

Description: | Returns a Vertex value, which is a collection of 3 points and a mode.
Returns: | Vertex
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Path | Point
Format: | Vertex(Mode, CenterPoint[, InHandlePoint, OutHandlePoint])
Parameters: |
Mode
Required. Any numeric constant that specifies the behavior of the handle points, as shown in the following table
Mode | Handle Point Behavior
0 | Rectangular - handles are ignored
1 | Cusp - no restrictions on handle points
2 | Reserved for future use
3 | Reserved for future use
4 | Manhattan Closed Meaning that all lines are horizontal or vertical. Inspired by a skyline of tall, rectangular buildings. - handles are ignored. Right angles between this vertex and neighboring vertices are preserved, enforcing horizontal or vertical lines.
CenterPoint
Required. Any expression that returns a point object. This is the center point and location of this Vertex.
InHandlePoint
Optional. Any expression that returns a point.
OutHandlePoint
Optional. Any expression that returns a point.
Comments:

A vertex describes a group of up to three point values. The first sets the location. The following two are used when drawing curves and should be set invalid otherwise.

Vertex values are grouped to form paths.

For each vertex, the center point defines a point on the path. Each line segment or Bezier curve along the path is defined by two vertices, one at each end. The vertices' center point is the end point of the Bezier curve. The OutHandlePoint of one vertex and the InHandlePoint of the other vertex define the Bezier curve shape points. So, each Bezier curve is defined by 4 points: the two end points, and two 'handle' points.
Vertex values are also used in the graphics functions GUIArc, GUIChord, and GUIPie to determine the start and end angles for those graphics functions. The angle from the center point to the InHandlePoint defines the starting angle. The angle from the center point to the OutHandlePoint defines the ending angle

Example:

GUIArc(10, 100, 100, 10 { Bounding box for the arc },
       1, 1, 1, 1, 1 { No scaling },
       0, 0 { No trajectory or rotation },
       1, 0 { Arc is visible; reserved },
       0, 0, 0 { Cannot be focused/selected },
       Pen(12, 1, 1) { Solid lt red line, 1 pixel wide },
       Vertex(0 { Rectangular mode },
       Point(50, 50, Invalid, Invalid) { Arc center },
       Point(50, 0, Invalid, Invalid) { Start angle },
       Point(0, 50, Invalid, Invalid) { End angle }));

The Vertex function in this case defines the center, starting angle and ending angle for the arc. The center point is (50, 50); the starting angle is defined by the center point and a point that lies directly above it, and the ending angle is defined by the center point and a point that lies directly to the left of it. The result is a small arc that starts at the 12 o'clock position and runs counter-clockwise to the 9 o'clock position.


VICInfo

(Engine-Level Function)

Description: | Provides information about the VTScada Internet Clients connected to the machine where this code is run.
Returns: | Array - see comments
Usage: | Script only.
Function Groups: | VTScada Internet Client
Related to: | VICMessage
Format: | VICInfo()
Parameters: | None
Comments: The return value of VICInfo is an array of information. Each row [leftmost subscript] contains the information for one session, and each column within the row contains the fields of session information, as follows:

[n][0] Object value of the root (BrowserClient) module instance for this session.

[n][1] VIC process session ID [a 16-byte binary GUID]. This is guaranteed to be unique per VIC process. i.e. two sessions from the same VIC process will have the same VIC instance ID.

[n][2] IP of the remote computer, from the server's point of view [note this may be the IP of a gateway or proxy that the remote computer connects via].

[n][3] Total bytes transmitted to the VIC in this session.

[n][4] Total bytes received from the VIC in this session.

[n][5] Approximate round trip time to the VIC, in milliseconds.

[n][6] Uncompressed bytes transmitted to the VIC.

[n][7] Session identifier for the connection to the server.


VICMessage

(Engine-Level Function)

Description: | Transmits a message to one or all currently connected VTScada Internet Client sessions. The message is displayed in a dialog box on the VIC computer.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | VTScada Internet Client
Related to: | VICInfo
Format: | VICMessage(Object, Message)
Parameters: |
Object
Required. Object value of the root (BrowserClient) module instance for the VIC session to receive the message. If this parameter is not a valid object value, the message is broadcast to all VIC sessions.
Message
Required. The textual message to be sent to the VIC recipients.
Comments: There is no return value for this statement.
The Object value is typically retrieved from the return value of a VICInfo statement.


VICSmartcardMonitor

Description: | Enables and disables smart card monitoring on a VIC and outputs authentication information received from the VIC when a smart card is used.
Warning: | This statement should be used by advanced users only.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Security
Related to: | VICSmartcardResponse
Format: | VICSmartcardMonitor(SmartcardRemoved, SecurityContext, UPN)
Parameters: |
SmartcardRemoved
Required. A variable whose value is set to TRUE if the smart card has been removed, else FALSE.
SecurityContext
Required. A variable whose value is set to the Kerberos Security Context for the user attempting to sign in on the VIC using a smart card.
UPN
Required. A variable whose value is set to the User Principal Name (e.g. user@example.com) for the user attempting to sign in on the VIC using a Smartcard.
Comments:

This is a reset-able function whose initial return value is FALSE. The function will be triggered by a message from the VIC indicating either an attempt to sign in using a smart card or a removal of the smart card and then the return value is TRUE.


VICSmartcardResponse

Description: | Returns the result of the Kerberos Security negotiation after processing a sign in attempt on the VIC.
Warning: | This statement should be used by advanced users only.
Returns: | Nothing. Result returned via the parameter
Usage: | Script Only.
Function Groups: | Security
Related to: | VICSmartcardMonitor
Format: | VICSmartcardResponse(NegotiateResponse)
Parameters: |
NegotiateResponse
Required. The Kerberos Security Context return value, may be a null string, to be sent to the VIC in response to a login attempt.
Comments:

None


VoiceTalk

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Opens and returns a handle to a SAPI text-to-speech stream.
Returns: | Stream handle
Usage: | Steady State only.
Function Groups: | Speech and Sound
Related to: | Configure | GetDevices | GetVoices | Reset | ShowLexicon | Speak
Format: | \VoiceTalk([SpeakCount, BookmarkNum])
Parameters: |
SpeakCount
An optional parameter that is any variable in which the number of outstanding VoiceTalk\Speak requests (those that have not yet finished speaking) on this stream will be maintained.

When this parameter is set to zero, this SAPI text-to-speech stream is not speaking (i.e. it is initially set to zero). If this parameter is omitted or Invalid, no speak count will be maintained.

Note that SAPI could still be speaking on another stream when this count is zero on one stream.
BookmarkNum
An optional parameter that is any variable that will be set to the value of the last text bookmark encountered by the speech engine on this stream (a bookmark is denoted by the XML tag <BOOKMARK MARK="bookmark"/>). It is initially set to Invalid.
Comments: This function returns the error code resulting from issuing the command to the speech engine, or zero if no error was encountered.
This function is not threaded, however, it creates a thread inside of which the handle referring to the text-to-speech stream is accessed. All other speech functions on this stream do not create their own thread, but will execute in the thread created by this function. This thread will exist for as long as the VoiceTalk statement remains active (i.e. until a state change occurs). For this reason, the state containing the VoiceTalk call must remain active until all other speech statements have finished executing. There can be multiple SAPI text-to-speech streams open at any time.

Example:

speechHandle = \VoiceTalk();

This will create a SAPI text-to-speech stream that will maintain neither speak count nor bookmark positions.

speechHandle = \VoiceTalk(sCount, bNum);

This will create a SAPI text-to-speech stream that will maintain both a speak count and bookmark positions.

speechHandle = \VoiceTalk(invalid, bNum);

This will create a SAPI text-to-speech stream that will maintain bookmark positions only.

The following list consists of the methods that a VoiceTalk stream provides for external use.


VScrollbar

(System Library)

Description: | Draws a vertical scroll bar and returns its position.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | TextBox | ToolBar
Format: | System.VScrollbar(Left, Bottom, Height, Steps, PageLen[, Position, StepSize, MouseWheelInputObj])
Parameters: |
Left
Required. Any numeric expression for the left side coordinate of the scrollbar.
Bottom
Required. Any numeric expression for the bottom coordinate of the scrollbar.
Height
Required. Any numeric expression for the height of the scrollbar in pixels.
Steps
Required. Any numeric expression giving the number of steps in the scrollbar.
PageLen
Required. Any numeric expression giving the number of steps in each page.
Position
Optional numeric. This variable may be used to monitor or set the current scroll position.
StepSize
Optional. Any numeric expression giving the number of lines to scroll through when the user clicks on an arrow. Defaults to 1 if not specified.
MouseWheelInputObj

The Window object that should capture mouse wheel messages for this VScrollbar. Every VScrollbar module requires a unique source window in order for mouse wheel scrolling to function properly. On the server and the VIC, this parameter is used so that scroll wheel events that happen over MouseWheelInputObj's window are redirected to the VScrollbar.

On the Anywhere Client, in addition to redirecting scroll wheel events as above (if the client's platform happens to have a mouse), this parameter is also necessary to redirect vertical touch panning events over a given region to the VScrollbar. This is of increased importance because on most touch screen devices, you cannot touch and drag the scrollbar directly, so this kind of touch redirection is often the only way to scroll a VScrollbar.

Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Steps can be calculated by subtracting the number of visible items from the total number of scrollable items.

PageLen is equal to the number of visible items.

Items can be thought of as rows, where a row will have a height of N pixels. As an example, consider an Alarm Page that is showing 50 alarms, where only 20 of them are visible. The operator needs to click the down arrow on the scrollbar 30 times to reach the bottom of the alarm list, so Steps would be set to 30. If the operator clicks on the scrollbar area other than the tab, they expect to see it scroll by a "page", which in this example is 20 rows. PageLen would therefore be set to 20. In some situations you may want the down arrow to move more than one row at a time, say 3 rows, so you would set StepSize to 3. Note that there is no need to provide the width of the row in pixels to VScrollbar.

Custom script graphics using the VScrollbar module directly need to pass in a window object to serve as source for the mouse wheel messages. Typically this would be the window that the VScrollbar module is controlling. Note that the VScrollbar module itself uses a native windows scrollbar, which will therefore work automatically without any script changes, so long as the mouse pointer is over the actual scrollbar.

Example:

System.VScrollBar(VStatus(Self, 11) - VStatus(Self, 21)
                 { Left },
                 VStatus(Self, 12) - 1 { Bottom },
                 VStatus(Self, 12) { Height },
                 Length - LinesVisible { Total steps },
                 LinesVisible { Steps in page },
                 Position { Thumb tab pos });


VStatus

(Engine-Level Function)

Description: | Returns the video board and screen characteristics for VTScada.
Returns: | Varies - see table in Option parameter
Usage: | Script or steady state.
Function Groups: | Software and Hardware, Window
Related to: | Coordinates | PalStatus | GetDisplayRoot
Format: | VStatus(Window, Option)
Parameters: |
Window
Required. The object value of the window to request information on. This may be invalid and is therefore ignored for Options which do not depend upon a particular window.
Option
Required. Selects the video characteristic to return, as shown in the following table.

Option

Video Characteristic

0

Reserved for future use

1

Reserved for future use

2

Reserved for future use

3

X Coordinate of left side of the window. This is the client area of the window and does not include the title or borders.

4

Y Coordinate of bottom side of the window. This is the client area of the window and does not include the title or borders.

5

X Coordinate of right side of the window. This is the client area of the window and does not include the title or borders.

6

Y Coordinate of top side of the window. This is the client area of the window and does not include the title or borders.

7

Number of horizontal pixels of resolution of the virtual client area of the window. This doesn’t include the window border. Shrinking the window to make scroll bars appear doesn’t affect this number.

8

Number of vertical pixels of resolution of the virtual client area of the window. This doesn’t include the title or border of the window. Shrinking the window to make scroll bars appear doesn’t affect this number.

9

Number of color indexes available in the palette for the window. This is always 256.

10

Background color of the window as an RGB color string. Any areas of the window which are not drawn appear as this color.

11

Number of horizontal pixels currently visible in the client area of the window. This doesn’t include the window borders. Shrinking the window to make scroll bars appear decreases this number.

12

Number of vertical pixels visible in the client area of the window. This doesn’t include the window title bar or borders. Shrinking the window to make scroll bars appear decreases this number.

13

Window width in pixels including the window borders.

14

Window height in pixels including the title bar and borders.

15

Current coordinates of left side of window on the screen. The coordinates used are in pixels and relative to the screen where 0, 0 represents the upper left corner of the screen. The position referred to is the upper leftmost corner of the window title bar.

16

Current coordinates of top side of window on the screen. The coordinates used are in pixels and relative to the screen where 0, 0 represents the upper left corner of the screen. The position referred to is the upper leftmost corner of the window title bar.

17

Current coordinates of left side of visible area taking into account the position of the horizontal scroll bar.

18

Current coordinates of top side of visible area taking into account the position of the vertical scroll bar.

19

Window title bar height in pixels.

20

Horizontal scroll bar height in pixels.

21

Vertical scroll bar width in pixels.

22

Window thick border width in pixels. This border type may or may not be used in the present window. This information is a general property of the desktop configuration of the user and can be acquired without a valid first parameter to VStatus.

23

Window thick border height in pixels. This border type may or may not be used in the present window. This information is a general property of the desktop configuration of the user and can be acquired without a valid first parameter to VStatus.

24

Window thin border width in pixels. This border type may or may not be used in the present window. This information is a general property of the desktop configuration of the user and can be acquired without a valid first parameter to VStatus.

25

Window thin border height in pixels. This border type may or may not be used in the present window. This information is a general property of the desktop configuration of the user and can be acquired without a valid first parameter to VStatus.

26

Width of full screen in pixels. Consider using option 35 instead.

27

Height of full screen in pixels. Consider using option 35 instead.

28

1 if window is minimized.

29

1 if window is maximized.

30

Maximum horizontal scroll position.

31

Maximum vertical scroll position.

32

Number of horizontal pixels offset from the left outside edge of the window border and the first usable pixel in the client area of the window.

33

Number of vertical pixels offset from the top of the window title bar and the first usable pixel in the client area of the window.

34 Ribbon height
35

The dimensions of the display device, or monitor, of the window that WindowObj is running in.

Returns an eight-member structure with the following members:

  • Left, the left co-ordinate of the monitor, which can be negative
  • Top, the top co-ordinate of the monitor, which can be negative
  • Bottom
  • Right
  • Width, for convenience, since this can be calculated using Left and Right.
  • Height
  • CenterX, the horizontal center of the monitor, for convenience
  • CenterY, the vertical center of the monitor.
36

The dimensions of the virtual display.

Returns a structure with the same members as option 35, but with values that reflect the entire Windows desktop.

Example:

ZGrid(VStatus(Self(), 3) { Left edge of window },
      VStatus(Self(), 4) { Bottom edge of window },
      VStatus(Self(), 5) { Right edge of window },
      VStatus(Self(), 6) { Top edge of window },
      12 { Grid is red },
      10, 10 { X and Y spacing });

This draws a 10 by 10 red color dotted grid in the entire area of the current window.


W Functions

The sections that follow identify all VTScada functions beginning with "W".


Watch

(Engine-Level Function)

Description: | Watches its parameters and returns true when any of their values change.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Variable
Related to: | Change | Edge | WatchArray
Format: | Watch(Start[, Parm1 [, Parm2, ...])
Parameters: |
Start
Required. Any expression which evaluates to a false (0) or true (non-0) value. This will be the initial return value of the function.
Parm1, Parm2, ...
Are any number of optional variables that are to be monitored by this function.
Comments:

This is a reset-able function whose initial return value will be set by the first parameter. This parameter is ignored after the initial evaluation of the function.
The Watch function will not be triggered by a variable whose value has been set to its existing value. That is to say, if a variable has a value of 3 and it is set in the code again to a value of 3, then there is no change and this function will not be triggered.
Only the first parameter (Start) is mandatory. Use Watch(1) to trigger a script once only on the first entry to a state.

A change in type (from 5 to "5") will also trigger the Watch.

In accordance with the VTScada Coding Standards, do not use Watch(0, ...).
Either use Watch(1, ...) or capture the values of the watched values before entering the state and check if they have changed.
Watch(0, ...) has the potential to miss a change that occurs after starting a state but before Watch(0, ...) runs.

Examples:

  If Watch(1);
  [
    ...;
  ]

This script will be executed once only, following which the function will be reset to false (i.e. the script will not again execute unless the module or the containing state is stopped and restarted).

  If Watch(1, Xvalue);
  [
    ...;
  ]

This script will be executed once during the initial run-through of the state and then again whenever Xvalue changes by any amount, unless the function is used inside a call to Latch.

Note that the behavior will differ depending on whether you use this function in a script code module or in a tag expression. In script code, the function will be reset as described, and will wait for the next trigger to occur.
In a tag expression, this function will not be reset after triggering.

Related information:

Latching and Resetting Functions


WatchArray

(Engine-Level Function)

Description: | Watches an array and returns true if any of its elements' types or values change.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Array, Variable
Related to: | Change | Edge | Watch
Format: | WatchArray(Start, ArrayElem, NumElem)
Parameters: |
Start
Required. Any expression which evaluates to a false (0) or true (non-0) value. This will be the initial return value of the function.
ArrayElem
Required. Any numeric array element giving the starting element of the group of elements to watch. The subscript for the array may be any numeric expression. If processing a multidimensional array, only the right-most dimension is used.
NumElem
Required. Any numeric expression giving the number of array elements to watch. If NumElem extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been located.
Comments: This is a resettable function whose initial return value will be set by the first parameter. This parameter is ignored after the initial evaluation of the function.

Example:

If WatchArray(0, dataArray[0], 10);
[
  ...;
]

This script will be executed if any of the elements from 0 to 9 inclusive experience a change by any amount, if they become invalid, or if their type changes.

Related information:

Latching and Resetting Functions


WatchForTagChanges

Deprecated. In new code, use WatchTags.

Description: | Watches for tag changes, either external or local
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Variable
Related to: |
Format: | \WatchForTagChanges();
Parameters: | None
Comments: | To prevent multiple rapid external changes from causing heavy execution, a slight delay, during which there must be no changes, occurs between triggers


WatchTags

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Watches for tag changes, either external or local
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Variable
Related to: |
Format: | \WatchTags([Context, TypeOrGroup]);
Parameters: |

Context
Optional. An instance of a container tag object. If provided, WatchTags will trigger if the Context or any of its descendents are refreshed, and will ignore changes to any other parts of the tag hierarchy.
If not provided, WatchTags triggers on any tag change.
TypeOrGroup
Optional. At present, only the group name "Container" is supported. If provided, WatchTags will trigger only when a tag in the matching group is changed. Type names are not supported.

Comments: WatchTags() will trigger immediately, much like a Watch(1).

Examples

If WatchTags(); { Will trigger when any tag in the application is added/modified/deleted.
                  Will also trigger initially. }
[
  TagList = GetTagList();
]

If WatchTags(Site1Obj); { Will trigger whenever Site1 or its descendents are changed }

If WatchTags(EastObj, "Container");
{ Will trigger whenever any container tags (e.g. context tags and station tags) are changed under
  the East folder }


WCSubscribe

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Working Copy Subscribe. After this function has been called, any configuration change will result in the specified callback subroutine being called.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Basic Module, Variable
Related to: | ReadConfiguration | ModifyConfiguration
Format: | \WCSubscribe(SubscriberObj[, CallbackModuleName])
Parameters: |
SubscriberObj
A required object, in which the callback module will be called. Often, Self().
CallbackModuleName
An optional text value which is the name of the callback object to be launched into the subscriber object. If invalid or not provided, there must be a submodule in the code, named Notify(), which will be used by WCSubscribe.
Comments:

This function is commonly used in conjunction with ReadConfiguration(). The callback() will be notified when a particular file has changed and will trigger another module to call ReadConfiguration() to read the changes from that file.

"ChangedFiles" contains absolute file paths.

Example:

Init [
  If 1 Main;
  [
    \WCSubscribe(Self(), "ChangeNotification");
    ConfigChanged = 1                       { Cause initial read of files };
  ]
]

Main [
  If ConfigChanged;
  [
    ConfigChanged = 0;
    \ReadConfiguration("ConfigReader");
  ]
]

<
{============================ \ChangeNotification ========================}
{=========================================================================}
ChangeNotification
 (
  ChangedFiles                { Dictionary of changes files               };
)

Main [
  If 1;
  [
    IfThen(ChangedFiles["MyConfigFile.txt"],
      ConfigChanged = 1;
    );
    Return(Invalid);
  ]
]
>


WebBrowser

Description: | Displays a web browser at the given position in the current VTScada window.
Returns: | Web Browser Handle (#VTypeWebBrowser)
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | WebBrowserNavigate
Format: | WebBrowser(Left, Bottom, Right, Top[, InitialURL, ProfileID, PrivateMode, EnableJavaScript, EnableContextMenu, AllowedURLs])
Parameters: |
Left
Required numeric. The left edge of the web browser window.
Bottom
Required numeric. The bottom edge of the web browser window.
Right
Required numeric. The right edge of the web browser window.
Top
Required numeric. The top edge of the web browser window.
InitialURL

Optional text. The initial website address to display when the browser is initialized.

Not steady state responsive (the value is used only when the web browser is initialized).

ProfileID

Optional text. Data folder name for the current WebView2 profile. Defaults to "Default". Recommended setting is a combination of application GUID and account ID so each user has their own profile.

Not steady state responsive.

PrivateMode

Optional Boolean. Specifies whether a private WebView2 profile should be used. If ProfileID is invalid this is forced to TRUE. If ProfileID is valid, defaults to FALSE.

A profile folder will be created under the ID even if this parameter is set TRUE, but that profile will not be used for the web browser instance. Has no effect on the Anywhere Client. Not steady state responsive.

EnableJavaScript

Optional Boolean. Enables or disables JavaScript. Defaults to FALSE (disabled).

Not steady state responsive.

EnableContextMenu

Optional Boolean. Enables or disables the default context menu on the VIC or thick client. Defaults to FALSE (disabled).

Has no effect on the Anywhere Client. Not steady state responsive.

AllowedURLs

Optional, a list of domains and paths that are permitted to be displayed in the web browser.

The entries in the list must include the protocol, likely "https://www." for most sites, and a trailing '/' (ex: https://www.mysite.com/). The list is line-delimited with CRLF line endings. Any paths defined under the most general specified entry will be allowed (ex: https://www.mysite.com/some/path/ will be accepted if the earlier example allowing the root path is in the Allowed URLs list).

Not supported on the Anywhere Client. Updates in steady state.

Comments:

This is used by the Web Browser widget.

To use this tool on either a thick client (workstation) or the VIC, the workstation requires the optional WebView2 component, which is built on the Edge browser from Microsoft. (The Anywhere Client does not require WebView2 to be installed.)
If WebView2 is not installed, it can be obtained by running the VTScada or VIC installer and selecting the option to install WebView2. Alternatively it can be downloaded from Microsoft, via the Evergreen Bootstrapper Installer or via the Evergreen Standalone Installer for machines with restricted access to the Internet.


WebBrowserNavigate

Description: | Call this to cause a WebBrowser to change pages.
Returns: | Boolean
Usage: | Script Only.
Function Groups: | Graphics
Related to: | WebBrowser
Format: | WebBrowserNavigate(BrowserHandle, URL)
Parameters: |
BrowserHandle
Required Web Browser Handle (#VTypeWebBrowser) - Web Browser instance whose page you want to change.
URL
Required text. The URL that the Web Browser should navigate to.
Comments:

Returns TRUE if the browser is running and FALSE otherwise.


WebSktSubscribe

(System Library)

Description: | Registers a module with the VTScada HTTPServer to listen for WebSocket connections.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Stream and Socket
Related to: |
Format: | System.HTTPServerInst.WebSktSubscribe(Application-GUID, Address[, Authenticate, CallbackScope]);
Parameters: |
Application-GUID
Required text. The 36-byte textual GUID of the application registering with HTTPServer.
Address
Required text. The consumer’s addressing string defining the tail of the Request-URI match, for which this consumer wishes to be called-back.
Authenticate

Optional Boolean. If TRUE, VTScada's HTTP server will authenticate the request. If FALSE or Invalid, HTTPServer performs no authentication, leaving this to the consumer.

Should be left Invalid if CallbackScope is also Invalid.

CallbackScope

Optional object reference. Specifies an object value, immediately subordinate to which are a set of subroutines that will receive various call-backs from HTTPServer, as follows.

Providing Invalid for this parameter removes any previous registration for the Application-GUID and Address.

Comments:

The account being used to authenticate the WebSocket request needs to have "Thin Client Access" privilege.

Once registered, HTTPServer will call the NewRequest and NewWebSocket subroutines in the CallbackScope object every time a new request to create a WebSocket is received. Templates for NewRequest and NewWebSocket follow.

NewRequest(Request, Headers, Protocol, Identifier)

This user-defined subroutine is called when a WebSocket upgrade request is received from the remote entity and has passed HTTPServer’s initial checks.

Create this module with the following parameters:

Request

This is a structure of information about the HTTP request. From this you can obtain the string holding the Request-URI from the WebSocket upgrade request.

Headers

This is a dictionary, keyed by header name, holding the complete set of HTTP headers provided in the WebSocket upgrade request.

Of note are the Authorization, Origin and Sec-WebSocket-Protocol headers.

The Authorization header should be validated to carry an acceptable authentication token, unless HTTPServer has been requested to validate this. In either case, the consumer should validate that the authentication token identifies an account with authorization to upgrade to a WebSocket. Authentication may be carried out by the consumer of the connection or by HTTPServer invoking SecurityManager. The authentication source is determined by the consumer.

Protocol

This is a pointer to a value in HTTPServer that receives the selected protocol if the consumer is going to accept the connection.

The Sec-WebSocket-Protocol header should be validated by the consumer to ensure it contains a protocol identifier that is supported by the consumer. If it does, the protocol that the consumer wishes to use is stored in the value addressed by this parameter.

Identifier

This is a pointer to a value in HTTPServer that receives a unique identifier for this connection. This identifier is passed into the NewWebSocket call-back. If the consumer accepts the upgrade, the identifier must be set.

The consumer must also decide whether to accept the request based on the number of open connections it currently has.

Return Value:

The consumer returns an integer HTTP status code from this call-back method, as follows:

  • 101 - The upgrade is to be accepted. The Protocol and Identifier values addressed by the corresponding parameters must be set.
  • 401 - Authentication required but not supplied.
  • 403 - Forbidden.

HTTPServer will complete the handshake with the remote entity (in the case of a 101 response) as per RFC 6455, activate the WebSocket filter and call the next call-back, NewWebSocket. Error codes will cause HTTPServer to respond with the appropriate status code.

NewWebSocket(Identifier, Stream)

NewWebSocket is a user-defined module, called after a NewRequest call-back returns with a status code of 101, accepting the WebSocket upgrade request.

Create this module with the following parameters:

Identifier

The unique identifier that was provided by the consumer in the NewRequest call-back. The consumer can use this to identify which NewRequest call-back this call-back corresponds to.

Stream

This is a bi-directional stream that communicates with the remote entity using WebSocket protocol.

Ownership of the WebSocket stream belongs to the consumer and HTTPServer will take no further part in processing the stream.

When the consumer no longer requires the stream, it should be closed off, either by invalidating the last reference to the stream (resulting in a graceful close of the socket) or by CloseStream, where there is an option to forcibly close the stream via a TCP RST.

Note that data arriving at this socket from the remote entity are presented as complete messages to the stream – i.e., message fragments received from the remote entity are reassembled into a complete message before being presented to script code. Similarly, writes to this stream must be complete messages.

Like UDP, the length of the stream reported by the engine is the number of unread bytes in the current message. Messages are queued and once a message has been entirely read, the length of the stream reported by the engine will be the length of the next message (if any).


WhileLoop

(Engine-Level Function)

Description: | Repeatedly executes its parameters while a condition is true.
Returns: | Nothing
Usage: | Script only.
Function Groups: | Logic Control
Related to: | Case | Cond | DoLoop | IfElse | IfThen
Format: | WhileLoop(Condition, Function1, Function2, ...)
Parameters: |
Condition
Required. An expression that will be evaluated to determine if the Function parameters should be executed. If it is true, the Function parameters will be executed and then Condition will be re-evaluated and the process repeated until Condition is either false or invalid.
Function1, Function2, ...
Required. These are any expressions that are to be executed while Condition is true. The Function parameters are executed in order.
Comments: No other statement will execute as long as Condition is true. Care must be taken that the statement terminates since it has the potential of locking up the system if it does not exit.

While the WhileLoop statement has its place in VTScada programming, it should be noted that speed can be enhanced by a factor of approximately 5 through the use of array processing functions. Refer to ArrayOp1 and ArrayOp2 for further details.

Example:

  ...
  If 1 Main;
  [
    I = 1;
    WhileLoop(I < 100 { Looping condition },
              ArrayEven[i] = i * 2     { Store even numbers };
              ArrayOdd[i]  = i * 2 - 1 { Store odd numbers  };
              I++);
  ]

This causes all even numbers from 0 to 198 to be stored in ArrayEven and all odd numbers from 0 to 198 to be stored in ArrayOdd.


WinButton

(Engine-Level Function)

Description | Windows native button.
Returns | Integer
Usage | Steady State only.
Function Groups | Graphics, Window
Related to: | ZButton
Format: | WinButton(X0, Y0, X1, Y1, Style[, Text, FocusID, Font, ToggleVal, Bitmap, BitmapJustify])
Parameters |
X0, Y0, X1, Y1
Required. Any four numeric values, locating the edges of the button in the window. To ensure consistent sizing, these parameters should be set using constants. A commonly-seen example follows:

WinWd-2*BtnWd-2*Space, WinHt-Space, WinWd-BtnWd-2*Space, WinHt-BtnHt-Space

Style
Required. Defines the button's appearance. A binary OR operation is done with a style number and the extra style bits shown in the following table.
If the style number is 0, the button will have a normal appearance. If the style number is 1, the button will be a toggling button. Further style refinements are as follows:
Value | Meaning
0x00000100 | orient text to the left
0x00000200 | orient text to the right
0x00000400 | orient text to the top
0x00000800 | orient text to the bottom
0x00002000 | allow multiple lines of text on button
0x10000000 | make the button invisible, but still respond to clicks. (Not supported on Anywhere client.)

(See: Bitwise Parameters & Operations)

Text

An optional expression for text to display on the button. Use the \GetPhrase function for multilingual applications.

Will not display tab characters.

FocusID
An optional parameter from 0 to 32767 indicating the focus id. If Invalid or "0", no user interaction is permitted.
Font
An optional parameter specifying the font to use for text.
Note that underlining is not supported.
ToggleVal

An output value, whose meaning depends on the button style.

  • In a toggling button, ToggleVal is set to the toggle state of the button - 1 for pushed-in and 0 for not-pushed-in.
  • For this button style, ToggleVal can also be used to change the state of the button programmatically.
  • In a normal button, ToggleVal is purely an output parameter, indicating whether the button is currently being pressed. NOTE: This behavior does not apply on the Anywhere client, where ToggleVal will not be set.
Bitmap
An optional parameter specifying an image to use on the button. May be used with or without a value for the Text parameter. See example.
BitmapJustify
An optional numeric value, specifying how the image is aligned on the button. Possible values are as follows:
Value | Meaning
0 | align image to the left (default)
1 | align image to the right
2 | align image to the top
3 | align image to the bottom
4 | align image to the center (not a valid option if text is also provided for the button)
Comments:

Example:

Examples often use English text in labels so that you can make a copy as a starting point when building your own version.
Better practice is to replace the text with phrase keys, and the \GetPhrase() function.

Plain button, with monitoring of the current toggle state.

  If WinButton(232, 148, 412, 100,
               0                      { normal appearance },
               Concat("Press Me ", ButtonPresses) { label },
               1                { focus id enables button },
               0                    { default system font },
               ToggleVal                  { monitor state});
  [
    ButtonPresses++;
  ]

Button with image

  MyImage    = MakeBitmap("..\Bitmaps\warning symbol.bmp", 12, 9);
  If WinButton(232, 148, 412, 100,
               0                      { normal appearance },
               Concat("Press Me ", ButtonPresses) { label },
               1                { focus id enables button },
               0                    { default system font },
               Invalid                { no ToggleVal used },
               MyImage     { image displayed in the button});
  [
    ButtonPresses++;
  ]


WinComboCtrl

Programmers are encouraged to use System.DropList instead.

(Engine-Level Function)

Description: | Windows native "combo" control. A "combo" control is an enhanced form of drop list. Displays a child window containing a Windows combo control.
Returns: | Numeric. See comments.
Usage: | Steady State only.
Function Groups: | Graphics, Window
Related to: | DropList | Edit | WinEditCtrl
Format: | WinComboCtrl(X0, Y0, X1, Y1, Style, Data, DataTrigger, Index [, FocusID, MaxCharacters, Font, BackgroundColor, ForegroundColor])
Parameters: |
X0, Y0, X1, Y1
Required. Coordinates.
Style

Required. Comprised of a combination of bit values to yield the desired effects.
Bits 0 and 1 define mutually-exclusive styles of operation. They can be set to one of the following values. If neither is set, the result is a Listbox with selected item above it.

(See: Bitwise Parameters & Operations)

Bit Number | Definition
0 | Droplist. The current droplist selection is editable.
1 | Droplist. The current droplist selection is not editable.

Bits 2 and 3 define input character handling. They can be set to one of the following values:

Bit Number | Definition
2 | Input is converted to all uppercase.
3 | Input is converted to all lowercase.

Bit 4 controls list sorting

Bit Number | Definition
4 | List is presented to the user in alphanumerically sorted order.

Bits 5 through 8 are reserved.

Bit 9 Specifies that the size of the combo box is exactly the size specified by the application when it created the combo box. Normally, the system sizes a combo box so that it does not display partial items.

Bit Number | Definition
9 | Enable application-defined geometry.
Data
Required. The one-dimensional array of data to display.
Trigger
Required. Can be set to non-zero to cause control data to refresh. WinComboCtrl will set this parameter back to zero after the data has been refreshed.
Index
Required. The current selection index in the data array.
FocusID
An optional parameter from 0 to 32767 indicating the focus id. If Invalid, negative, or zero, no user interaction is permitted.
This value is stored in a short.
MaxCharacters
An optional parameter indicating the maximum number of characters permitted for input. Can not exceed 65535 or be less than 0.
Font

Optional Font value. Defaults to the Windows System font.

Note that underlining is not supported.

BackGroundColor
An optional numeric parameter specifying the background color. Uses an unsigned integer, therefore system colors with negative values may not be specified here.
ForegroundColor
An optional numeric parameter specifying the foreground color. Like BackgroundColor, may not be negative.
Comments:

The return value for WinComboCtrl can be one of the following values:

Invalid - Nothing happened or there is a problem with the control.

0 Internal buffer changed

1 Selection made from list or Enter key pressed

2 Focus has been lost.

Data must be a one-dimensional array of text values. Index is a variable that receives the current selection array index, or the text value if the droplist has an editable selection and new text is entered that does not match any item in the array. If FocusID is Invalid or less than or equal to "0", the current selection cannot be modified.

VTScada's native WinCtrls do not behave the same way that they do in other programming languages. These events are only registered in conjunction with an internal buffer change.
ie. a <CR> press or a focus lost is only registered after a change in the data parameter (internal buffer)


Window

(Engine-Level Function)

Description: | Opens a new window, starts a module inside, and eventually returns the module's value.
Returns: | Module Instance
Usage: | Steady State only.
Function Groups: | Basic Module, Window
Related to: | SizeWindow | MoveWindow | VStatus | WindowClose | WindowOptions
Format: | Window(Left, Top, ViewWidth, ViewHeight, VirtualWidth, VirtualHeight, Module, Style, Title, Color, Enable [, HelpFileName, HelpContext, enableDynamicPositioning])
Parameters: |
Left
Required. Any numeric expression that gives the left coordinate of the new window. If the new window is a child window, Left is the user coordinate within the window of the calling module. If the new window is not a child window, Left is the number of pixels from the left of the screen.
Top
Required. Any numeric expression that gives the top coordinate of the new window. If the new window is a child window, Top is the user coordinate within the window of the calling module. If the new window is not a child window, Top is the number of pixels from the top of the screen.
ViewWidth
Required. Any numeric expression that gives the window width in pixels. The minimum width allowable is based on the operating system in use and the style options of the window (see the Comments section for more details).
ViewHeight
Required. Any numeric expression that gives the window height in pixels. This value must be greater than or equal to 0.
VirtualWidth
Required. Any numeric expression that gives the width inside the new window in user coordinates (which may be pixels). If VirtualWidth is larger than the client area specified, a horizontal scroll bar appears.
VirtualHeight

Required. Any numeric expression that gives the height inside the new window in user coordinates (which may be pixels). If VirtualHeight is larger than the client area specified, a vertical scroll bar appears.

If VirtualWidth and VirtualHeight are both set to 0 (zero) the effective virtual size of the window becomes the size of the monitor the window is within, varying dynamically.

Module
Required. Any expression that uses a module call. The module will start, and all graphics in the module will draw in the new window.
Style

Required. Any numeric expression that gives the style of the window when it opens. This parameter has no effect after the window has opened. Style is formed by adding together bit values from the table below.

This parameter can be overridden by the variable PageWinOpt within a page's source code.

(See: Bitwise Parameters & Operations)

Bit Number | Description
0 | Enable system close button (if bit 1 is set)
1 | Show title bar
2 | Thick border, not resizable
3 | Thin border, not resizable
4 | Enable minimize button (if bit 1 is set )
5 | Enable maximize button (if bit 1 is set)
6 | Create window minimized
7 | Create window maximized (full virtual size)
8 | Disable scroll bars
9 | Child window
10 | Always on top
11 | Reserved for future use
12 | Modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. window (like dialog box)
13 | Use pixel coordinates in window (otherwise user coordinates)
14 | Use Load statement to size window. Not supported by the Anywhere client.
15 | Owned window
16 | Initially inactive window
17 | Invokes "automatic" alpha blending, where the window is set to be 50% translucent when inactive and opaque when active. Not supported by the Anywhere client or on child windows (bit 9 is set).
18 | Window is to be rendered as transparent, with whatever color is specified as the background color being the transparent color. Not supported by the Anywhere client or on child windows (bit 9 is set)
19 | Indicates that a WindowClose statement will be associated with this window. See "WindowClose" for more details.
20 | Force the window to remain at a fixed aspect ratio
21 | Reserved.
22 | Window may serve as a drop target for GUITransforms dragged from a palette. Not supported by the Anywhere client.
23 | Window may serve as a palette, from which GUITransforms may be dragged. Not supported by the Anywhere client.
24 | If set along with bit 23, the window that is the source of the object being dragged will hide itself automatically during the drag operation.
25 | Hide horizontal scrollbar
26 | Hide vertical scrollbar (Setting both bits 25 and 26 is the same as setting bit 8, disable scroll bars)

Notes on the style settings:

  • The default window (if Style is set to 0) has a thick border and is resizable.
  • If bit 1 is not set, the title bar is not shown, and bits 0, 4 and 5 have no effect.
  • If bits 2 and 3 are both set, there will not be a border unless bit 1 is set, in which case there will be a thin border. If neither bit 2 nor bit 3 is set, the border will be a resizable thick border.
  • Bits 4 and 5 specify whether minimize and maximize buttons are disabled, rather than specifying whether they are visible (both the minimize and maximize buttons will be either visible or not visible). Furthermore, these options have no effect without bit 0 being set (except under Windows NT 3.51). The system close button must be enabled for the user to have any control over the minimize and maximize buttons.
  • Setting bit 8 disables the scroll bars that are normally shown if the window has been resized (smaller). In this case, the entire window must be enlarged to its original size if you wish to view its contents.
  • Bit 9 (child window) specifies a "window within a window". The new window is another graphic object within the calling window and is truncated by the borders of the parent window. This means that as the parent window is dragged, the child stays on top of the parent window in the same position within and relative to the parent's borders. If the parent window is minimized, then the child window is also minimized. Child windows do not produce status line title-windows. It is impossible to make a window a child window if the Window statement is in a module that isn't running in a window already. A child window is always an owned window.
  • Setting bit 12 means that the window will take all of the input until closed. Care should be taken when using this option in conjunction with bit 14 (size based on load). A problem will occur if the load file cannot be found, and the window will not show up but will still be modal. The result is that the system will take no input until the window is closed.
  • Setting bit 14 hides the window until a Load statement is executed in Module. The window is then opened in the size required to display the loaded image.
  • Bit 15 (owned window) creates a window that is always in front of the calling window. Unlike child windows, which are controlled by their parents, owned windows are not restricted by their owner's boundaries, nor does the movement of the parent window change their position. The exception to this, however, is that if the owning window is minimized, the owned window will also be minimized. Owned windows do not produce status line title-windows. Although all child windows are owned, not all owned windows are child windows.
  • Bit 17. An alpha-blended window is one that has an alpha channel set up in the final renderer, resulting in a translucent effect to the window (i.e. it behaves like a normal window, except that you can see through the window to some degree. The degree of translucency ranges from zero (invisible) to 255 (completely opaque, just like a normal window). Setting bit 17 on your Window statement invokes "automatic" alpha blending, where the window is set to be 50% translucent when inactive and opaque when active. This is useful for dialogs that are non-modal and always on-top, so that when another window is active, you can see through to the underlying windows. If you need a finer degree of control on this, do not set bit 17, but use a new value for the "Option" parameter of WindowOptions (9) and set the WindowOptions "OptValue" parameter to the degree of alpha-blending that you wish (0 to 255). Note that these effects DO NOT work with child windows. Also note that these effects are NOT designed for animation purposes are not sufficiently efficient for this. The amount of processing power required to redraw one of these windows depends on the rating of the graphics card in your machine. The newer and faster the better.
  • Bit 18. A transparent window is one that has a transparent background. The intended use for this is to allow the display of non-rectangular windows, by rendering the background as transparent and allowing mouse messages (movement and clicks) to "drill-through" the transparent area. The simplest way to create a transparent window is to specify a background color less than zero (-1, for example). The underlying implementation, however, requires that a specific color is used as a "key" color. All pixels of that color in the otherwise rectangular screen area that the window occupies are rendered as transparent. Using a background color of < 0 results in the key color being black [i.e. RBG(0, 0, 0)] and the window background being set to that color. It may well be that you wish to have black as a color in your window, however. Therefore, setting bit 18 in the Window statement also announces that this window is to be rendered as transparent, with whatever color is specified as the background color being the transparent color.
  • A WinXLoc/WinYLoc statement for the new window registers the values for the parent window when the mouse is over the parent and not itself, and will register the values for itself when the mouse is over it. The same is also true for the parent (it will see the values for the child window when the mouse is over the child).
  • Bits 22 and 23 are mutually exclusive. A window cannot be both a palette and a drop-target.
Title
Required. Any text expression that gives the window title.
Color
Required. Any numeric expression that gives the background color of the window's client area when the window opens.
If set to -1, then the resulting window will be transparent, as will anything drawn in black (RGB 0, 0, 0) upon it. Not supported by the Anywhere client or on child windows (bit 9 is set).
This parameter has no effect after the window has opened.
Any of the following may be used:
  • a palette index VTScada Color Palette
  • a Constants for System Colors
  • an RGB string in the format, "<RRGGBB>"
Enable
Required. Any logical expression. If true, the window opens and Module starts. If false, the window is closed and Module is stopped.
HelpFileName
Optional file name of the help file to use if the user presses F1 while this window is the active window. If absent or invalid when the user presses F1, the parent window will be checked for a file name. This continues recursively until the top of the window tree is reached.

If no help file name is found, the default help file is used. The default help file can be set through the Setup.ini variable WEBHelp, or by using the EnableHelp statement.
HelpContext
Optional help context. If absent or invalid, but the HelpFileName is valid, then the "finder" dialog for help is displayed when the user presses F1. If valid and numeric, the help file is searched for a matching topic number and help is displayed for that topic.
If valid and textual, the help file is searched for an exact match on the text string among the topic index of the help file. If there is more than one text match, the index is positioned at the first partial string match.
If valid but a topic match is not found (neither textual nor numeric), the same action as an Invalid HelpContext is taken. If the HelpFileName parameter is Invalid, this parameter is ignored.
enableDynamicPositioning
An optional parameter that, when set to TRUE, will cause the window position to be updated if the window is a child window inside a GUITransform that moves, or if the LEFT or TOP parameters change. Set to FALSE by default.
RibbonName
Optional text string, identifying the ribbon. See comments.
RibbonState

Optional. A retained variable name, holding the persisted state of the ribbon. The persisted state is an XML snippet generated internally by the Microsoft ribbon API and is opaque to VTScada script code.

The retained variable is typically set in the destructor for the module instance the Window statement runs.

Comments:

This function returns the value returned by Module.

When a window is maximized, its maximized size is not based on the size of the screen, although for many commercial applications the two are the same, but rather, its full size is defined by the fifth and sixth parameters, namely virtual width and height. If the view area and the virtual area of the window have been defined to be the same, selecting the maximize button will appear to have no effect.
The minimum size of a window is based on the operating system under which the application is running, as well as the attributes of the window itself as defined by the Style parameter. The width need only be greater than or equal to 0. Window heights similarly need only be greater than or equal to 0.
GUITransform functions may make use of VStatus to inquire about the boundaries of the window they are within.

A window can be turned into a drag and drop target by adding the callback modules, OLEDrag and OLEDrop. Further details can be found in the chapter, Create Windows & Use Graphics Functions.

If a ribbon is to be associated with this window, then the ribbon must be instantiated at the same time that the window is created, using the two optional parameters, RibbonName and RibbonState.

Ribbons are compiled into resources, using Microsoft Visual Studio. The resources can then be linked directly into VTS.EXE (Trihedral use only) or into an external DLL. This allows multiple ribbons to be provided in separate DLLs. You can have more than one ribbon in VTS.EXE or a DLL.

RibbonName is of the form "dllname|ribbonname", being the name of the DLL, a vertical pipe symbol and the name of the ribbon resource within the DLL. If the ribbon is compiled into VTS, the dllname and the pipe separator character are omitted.

If adding a ribbon to a window, and if there is a chance that the window will be maximized, you should use the window's virtual width and virtual height as follows:

Window(0, 0, 1024, 768,
       VStatus(Self(), 26), VStatus(Self(), 27) + VSTatus(Self(), 23), ...

The virtual height in particular is important as otherwise there will be a gap at the bottom of the window (normally, eight pixels) that is the size of the frame height.

Example:

  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
         {65432109876543210}
        0b00010000000110011, "Sample Window", 0, 1);

This statement will open a window, and run the module Graphics() in it.

Related information:

Windows, Pages, and Graphics - A collection of best practices and related information.


WindowClose

(Engine-Level Function)

Description: | Returns true if an attempt is made to close the window.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Window
Related to: | VStatus | Window | WindowOptions
Format: | WindowClose(Object)
Parameters: |
Object
Required. Any expression that returns the object value of any module instance drawn in the window.
Comments:

Only one WindowClose() should run with a window at a given time.
WindowClose() can be used inside a window that you opened with a Window() call.
For any page or widget, or other window do not use WindowClose because you cannot know if WindowClose is already being used with that window (as is likely the case).

If this function is active when an attempt to close a window is made, the window will not close, and the module(s) in that window will not stop. It is up to the calling module to close the window and stop the module(s) by switching to another state.
This function may be used to control what happens when a window is closed (or to prevent it from being closed). When the attempt is made to close the window, an action (or actions) can be triggered. For example, this might write some data to file. Then a variable could be set (or a value could be returned by the module) which signals the calling module to switch states, which closes the window and stops the module(s) inside.

Notes on closing a window:

When WindowClose behavior is active, the typical way to close a window is by making one of the following happen:

  • The Enable parameter to the Window() function changes to false.
  • The state where the Window() function is running in steady state stops. This is typically achieved by doing one of two things:
    • The calling object's state changes away from the state containing the Window() function.
    • The calling object is slain.

Calling Slay on the root object of the window does not work. (For example, calling Slay(Self) from the window's root object.) The root object of the window is called in steady-state, from the Window function's 7th parameter. Slaying an object that has been called in steady-state does nothing because it does not affect the calling object: the calling object would still be in it's same state with that same Window() call running, and therefore the called Window module cannot be permitted to stop.

If the calling object is launched, then a common approach is to slay that calling object. For example, Slay(Caller(Self)) rather than Slay(Self) may work, depending on how the object was launched.

It is possible for a WindowClose statement to be associated with a window, but to not yet be running when the attempt to close the window is made. If this happens the slay of the module running in the window will continue up the module tree until a running WindowClose is found, or the top of the tree is reached. This behavior may be undesirable. The scenario can be avoided by setting bit 19 of the Style option in the Window statement. Doing so will warn VTScada that a WindowClose statement will be associated with this window.

Example:

  If WindowClose(Self()) CloseEverything;

This statement causes a state change to CloseEverything if the user attempts to close the current window. It is then up to code in CloseEverything to perform any necessary clean-up tasks and close the window.


WindowOptions

(Engine-Level Function)

Description: Alters the options on a window after it has been opened.
Returns: Nothing
Usage: Script or Steady State
Function Groups: Window
Related to: MoveWindow | SizeWindow | Window | WindowClose
Format: WindowOptions(Object, Option, OptValue);
Or
WindowOptions(Object, 15, Width, Height);
Parameters:
Object
Required. Any expression that returns the object value of any module instance drawn in the window.
Option
Required. Any numeric expression that specifies which option for the window to alter. Step options 1-4 should be used by advanced users only as these should be used only by VScrollbar and HScrollbar.
Option | Attribute to alter
0 | Visibility of the window
1 | Horizontal scroll line step size
2 | Horizontal scroll page step size
3 | Vertical scroll line step size
4 | Vertical scroll page step size
5 | Set Horizontal Scroll position. Has no effect in an Anywhere client.
6 | Set Vertical Scroll position
7 | Locator reporting rate from the VIC is accelerated. Typically this would be used when fast, dynamic feedback of mouse movement from the VIC is required for a rapid, interactive response. CAUTION: Unnecessary use of this option can seriously degrade the VTScada window update rate on the VIC. Not supported by the Anywhere client.
8 | Locator reporting rate from the VIC is returned to normal. Locator position reports are only sent when the VIC considers them significant. This is the default mode of operation. Not supported by the Anywhere client.
9 | Sets the level of alpha-blending (window translucency) of the window. OptValue determines the level of alpha-blending from 0 (completely transparent) to 255 (completely opaque). An OptValue of 128 would give 50 percent translucency. Not supported by the Anywhere client.
10 | Set background color of tooltips. Must be provided as a palette color. You may set the option value to -1 to use default colors or -2 (the default) to use parent window settings. Will work only when visual themes are disabled in Windows. Not supported if running in Windows 7 or later. Not supported by the Anywhere client.
11 | Set tooltips text color. Must be provided as a palette color. You may set the option value to -1 to use default colors or -2 (the default) to use parent window settings. Will work only when visual themes are disabled in Windows. Not supported if running in Windows 7 or later. Not supported by the Anywhere client.
12 | Not supported if running in Windows 7 or later. Set tooltips show delay. Will work only when visual themes are disabled in Windows. Not supported by the Anywhere client.
13 | Set tooltips show duration. This value is limited by the operating system to less than 33 seconds. Will work only when visual themes are disabled in Windows. Not supported if running in Windows 7 or later. Not supported by the Anywhere client.
14 | Set tooltips neighbor re-show delay. Will work only when visual themes are disabled in Windows. Not supported if running in Windows 7 or later. Not supported by the Anywhere client.
15 | Sets the minimum window width and height, using two option value parameters instead of one, e.g. WindowOptions(Self(), 15, Width, Height);
16 | The Source window will redirect its mouse wheel messages to the Destination window. A source window can only have one redirect at a given time. The first parameter specifies the source window and the third parameter specifies the destination window. In an Anywhere Client with touch screen, this will redirect vertical panning. For advanced users only.
17 | Reserved.
18 | Turn alignment cue drawing and behavior on or off. Not supported by the Anywhere client.
19 | Set the color of the alignment snaps. Not supported by the Anywhere client.
20 | Set the color of the distance snaps. Not supported by the Anywhere client.
21 | Set the color of the spacing snaps. Not supported by the Anywhere client.
22 | Set the color of the sweep area border. Not supported by the Anywhere client.
23 | Set the color of the sweep area fill. Not supported by the Anywhere client.
24 | Dark color of the bounding box edges in a selection. Not supported by the Anywhere client.
25 | Handle inner fill color. Not supported by the Anywhere client.
26 | Snap sensitivity in pixels. Not supported by the Anywhere client.
27 | Drag sensitivity in pixels. Not supported by the Anywhere client.
28 | X translation of the window. Not supported by the Anywhere client.
29 | Y translation of the window. Not supported by the Anywhere client.
30 | Set the size of distance snaps. Not supported by the Anywhere client.
31 | Set the background color of the window.
32 | In an Anywhere Client with touch screen, this will redirect horizontal panning. For advanced users only.
OptValue
Required. Any numeric expression that specifies the value to set the given option to.
For an Option of 0 (visibility), OptValue produces the following effects:
OptValue | Effect
0 | Activate and display in current position
1 | Bring to foreground without activating
2 | Maximize and activate
3 | Minimize. Deactivate if active
4 | Hide
5 | Similar to OptValue 0, but the graphic editing window in-use is not modified.
Width
Required. Used when the Option value is 15. Sets the minimum window width
Height
Required. Must be present and valid when the Option value is 15. Sets the minimum window height.
Comments: This statement will alter the attributes of the window as it is running. The values that the given options can be set to are from -32763 to 32763.
When the option value is set to 15, the function requires four parameters, all of which must be valid. The last two set the minimum width and height

Example:

If MatchKeys(2, "I");
[
  WindowOptions(Self(), 0, 3);
]

If an "I" is pressed on the keyboard, the window that this module is running in will be minimized.

If ZButton(10, 50, 110, 80, "SetSize", 2, System.DefFont);
  [
    WindowOptions(Self(), 15, 200, 150);
  ]
  If ZButton(10, 90, 110, 120, "ClearSize", 3, System.DefFont);
  [
    WindowOptions(Self(), 15, 0, 0);
  ]


WindowsLogon

(Engine-Level Function)

Description: | Authentication request to Windows Authentication services.
Returns: | Boolean to indicate success or failure
Usage: | Steady State only.
Function Groups: | Security
Related to: |
Format: | WindowsLogon(Username, Password[,LogonError])
Parameters: |
Username
Required. The account name to authenticate.
Password
Required. The password, required to authenticate the given account.
LogonError
Optional. Output parameter that sets an error code (non-zero integer) in case of login failure or sets 0 in the case of a successful login.
Comments:

This function should not be used for VTScada-based authentication.

Note that this function may take some time to complete and will block the caller until it does. Other threads in the VTScada system will continue to run while this function is executing.


WindowSnapshot

(Engine-Level Function)

Description: | Creates an image file containing a screen capture of the specified window.
Returns: | Boolean indicating success (TRUE) or failure of the operation.
Usage: | Script Only.
Function Groups: | Window
Related to: |
Format: | WindowSnapshot(Filename, WindowObj, MimeType[, Left, Top, Right, Bottom] );
Parameters: |
Filename
Required. Any expression that is a string, or an array of strings containing the full filename(s) to which the screen capture should be saved.
WindowObj
Required. An object (often, "Self()") specifying the window to be captured.
MimeType
Required. Any expression that is a string, or an array of strings specifying the mime type(s) to be used for the image.
Left, Top, Right, Bottom
Optional. Short integer values, providing the bounding area of the region to be captured within the window. If any one of these parameters is provided, all four must be provided. If not provided, a snapshot will be taken of the entire window.
Comments:

Available mime types include image/bmp, image/jpeg, image/gif, image/tiff, image/png.
Note: Runs asynchronously from a VTScada Internet Client. In this case, the return value is meaningless.

Within an Anywhere Client session, this function does nothing.

Example:

[
  Mimetypes                   { Set of mime types we can snapshot to            };
  Filetypes                   { Corresponding file types (extensions)           };
  SelectedMimetype            { Work var - iterator through above arrays        };
  Constant #NUM_TYPES = 5     { Number of entries in the above arrays           };
]
Init [
  {***** Allow enough time for the window to paint *****}
  If Timeout(1, 1) TakeSnapshots;
  [
    Mimetypes = New(#NUM_TYPES);
    Mimetypes[0] = "image/bmp";
    Mimetypes[1] = "image/jpeg";
    Mimetypes[2] = "image/gif";
    Mimetypes[3] = "image/tiff";
    Mimetypes[4] = "image/png";
    Filetypes = New(#NUM_TYPES);
    Filetypes[0] = "bmp";
    Filetypes[1] = "jpg";
    Filetypes[2] = "gif";
    Filetypes[3] = "tiff";
    Filetypes[4] = "png";
    SelectedMimetype = 0;
  ]
]

TakeSnapshots [
  {***** Snapshot the window for each mime type *****}
  If SelectedMimeType < #NUM_TYPES;
  [
    WindowSnapshot(Concat(PathString, "\Lighthouse.", FileTypes[SelectedMimetype]),
                   Self(),
                   Mimetypes[SelectedMimetype]);
    SelectedMimetype++;
  ]


WinEditCtrl

(Engine-Level Function)

Description: | Windows native edit control. This function returns a value indicating the status of an edit field.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | DropList | Edit | WinComboCtrl | ZEditField
Format: | WinEditCtrl(X0, Y0, X1, Y1, Style, Data [, FocusID, MaxCharacters, Font, BackgroundColor, ForegroundColor, PlaceholderText])
Parameters: |
X0, Y0, X1, Y1
Required. Coordinates.
Style

Optional. Default 0. Comprised of a combination of bit values to yield the desired effects. Note that some combinations should not be used as they could be mutually exclusive. For example converting input to all uppercase and to all lowercase (bits 2 and 3 both set).

Bits 0 and 1 are reserved for bit compatibility with WinComboCtrl, and should be set to "0".

Bits 2, 3 and 4 define input character handling. It is reasonable to set bit 2 and 4 or 3 and 4, but not bits 2 and 3. If not set, input is used exactly as typed.

(See: Bitwise Parameters & Operations)

Bit Number

Definition

0 | Reserved for compatibility with WinComboCtrl, and should be set to "0"
1 | Reserved for compatibility with WinComboCtrl, and should be set to "0"

2

Input is converted to all uppercase

3

Input is converted to all lowercase

4

Input is masked. Any characters typed will appear as asterisks. (useful for password fields)

Will not work in combination with bit 5, multi-line editing.

5

Multi-line editing. When set, this bit causes a typed Enter key to be interpreted as "move to the start of the next line".

Text that contains carriage-return & line-feed characters has a line break inserted at each set.

6 | Forces the background color to continue being used when the control is disabled, rather than allowing it to gray as it otherwise would.
7 | Not used
8 | Reserved
9 | Reserved
10

Bits 10 and 11 control horizontal alignment as follows:

Bit 10 | Bit 11 | Alignment
0 | 0 | Left (default)
1 | 0 | Center
0 | 1 | Right
1 | 1 | Do not use
11
Data
Required. The data to display and possibly edited.
FocusID

An optional parameter from 0 to 32767 specifying the focus id. If Invalid, negative, or zero, no user interaction is permitted. This value is held in a short.

MaxCharacters

An optional parameter specifying the maximum number of characters permitted for input. Can not exceed 65535 or be less than 0. Defaults to 32767.
Note that this property is not obeyed in a VTScada Internet Client.

Font
An optional parameter specifying the font to use.
Note that underlining is not supported.
BackGroundColor
An optional numeric parameter specifying the background color. Uses an unsigned integer, therefore system colors with negative values may not be specified here. May be any of:
  • a palette VTScada Color Palette
  • a Constants for System Colors
  • an RGB string in the format, "<RRGGBB>"
ForegroundColor
An optional numeric parameter specifying the foreground color. Like BackgroundColor, may not be negative.
PlaceholderText
Optional text that will be shown in the control as a prompt to the user. Vanishes when the user begins entering a value.
Comments: The return value for WinEditCtrl can be one of the following:
Return Value | Meaning
Invalid | Nothing happened or there is a problem with the control
0 | Internal buffer changed or selection made from list.
1 | <CR> (Enter or Return pressed). Only applies to single-line edit controls.
2 | Focus has been lost.

If FocusID is Invalid or less than or equal to "0", the current selection cannot be modified.

VTScada's native WinCtrls do not behave the same way that they do in other programming languages. These events are only registered in conjunction with an internal buffer change.
ie. a <CR> press or a focus lost is only registered after a change in the data parameter (internal buffer)


WinLocSwitch

(Engine-Level Function)

Description: | Returns the current status of the locator (mouse) buttons in a certain window and its ancestors.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Locator, Window
Related to: | Click | LocSwitch | SetXLoc | SetYLoc | Target | WinXLoc | WinYLoc | XLoc | YLoc
Format: | WinLocSwitch(Object)
Parameters: |
Object
Required. Any expression that returns the object value of any module instance drawn in the window.
Comments: If the mouse isn't over the specified window or one of its ancestors, the function returns the mouse button status for the last time it was over the window (or ancestor). If the locator is not installed, the function returns 0. Otherwise, the return value has the following significance:
Return Value | Mouse Button(s) | No. of Clicks
0 | No buttons | -
1 | Right button | Single
2 | Middle button | Single
3 | Right and middle buttons | Single
4 | Left button | Single
5 | Left and right buttons | Single
6 | Left and middle buttons | Single
7 | All three buttons | Single
8 | No buttons | -
9 | Right button | Double
10 | Middle button | Double
11 | Right and middle buttons | Double
12 | Left button | Double
13 | Left and right buttons | Double
14 | Left and middle buttons | Double
15 | All three buttons | Double

It cannot be over-emphasized that this function looks at the status of the mouse over not only the window indicated by Object, but all ancestral windows of Object as well. That is to say, any of its children, grandchildren, parents, grandparents, etc. For example, a WinLocSwitch statement in a certain module, we'll call it ModA, and a WinLocSwitch statement in a child module of ModA, call it ModB, will both return a value of 4 if the left mouse button is pressed over either one of them. If this action is not what is required for your application, the LocSwitch function may be more appropriate, since it will return a value of 4 only if the left mouse button is pressed while over the same window containing the module with the LocSwitch statement in it. From the previous example, this means that ModA's function will return the expected value only when over the window containing that module, not when the mouse is over ModB's window, and vice versa.

Example:

If WinLocSwitch(Cond(CurrentWindow() != secondaryWin,
                CurrentWindow(),
                Invalid())) == 4 TestDraw;
[
  ...
]

This statement will check the status of the left mouse button if its current window is not the one called secondaryWin. If there has been a change over any of the windows but secondary window, the script will execute and a change of state to TestDraw will occur. At some point prior to this, secondaryWin would have been set to a module instance inside the desired window.


WinLocWheel

(Engine-Level Function)

Description: | WinLocWheel returns TRUE when the mouse wheel is rolled while the mouse is over the specified window with the specified modifier key held down. This allows it to be used within a predicate.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Window
Related to: |
Format: | WinLocWheel(Object, ModifierKey, ScrollChange);
Parameters: |
Object
Object is a module instance that is running inside a window.
ModifierKey
Defines the key that must be held down to activate the function. Either 4 (Shift) or 8 (Ctrl).
ScrollChange
Set to the direction and magnitude of the wheel movement.
Comments:

The function looks for mouse movements while the cursor is within the bounds of the object window.

The modifier key values come from the Win32 definitions of MK_SHIFTKEY(4) and MK_CTRLKEY(8).

When the mouse is over the window and the modifier key is held down, one mouse wheel "roll-click" will cause ScrollChange to be set to -1 or 1, depending on the direction of the roll.

On a very busy system, it is possible for multiple wheel rolls to be captured in one trigger of the statement, so ScrollChange may be any integral number but usually each roll-click results in a single trigger with ScrollChange set to -1 or 1.

Example:

If WinLocWheel(Obj, #CtrlKeyModifier, CtrlCounter);
[
  TotalScrollClicks += CtrlCounter;
]


WinMatchKeys

(Engine-Level Function)

Description: | Returns true if the specified keyboard keys have been pressed in the sequence given, in another window.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Keyboard
Related to: | MatchKeys
Format: | WinMatchKeys(Object, Enable, Keys)
Parameters: |
Object
Required. Any expression which gives the object value of any module instance which is running in the window.
Enable

Required. Any numeric expression giving an enable for the function. Testing of keyboard input is enabled when this parameter is true (not 0). If this parameter is false(0), the function's value is false(0).

In addition, the Enable parameter controls the type of comparison done. If the Enable is 1, a case-sensitive match is made. If the Enable is 2, then the match is not case-sensitive.

(Any non-zero value other than 2 will cause a case-sensitive match. The use of 1 and 2 is recommended for clarity.)

Keys

Required. A text expression giving the key sequence to watch for. The case of individual letters may be significant, depending on the Enable parameter. For example:

  PageUp    = Concat(MakeBuff(1, 253), MakeBuff(1, 0x49));
  F2        = Concat(MakeBuff(1,253), MakeBuff(1,60));
  F3        = Concat(MakeBuff(1,253), MakeBuff(1,61));
  CtrlZKey  = MakeBuff(1, 26);
Comments:

The Object is used to determine which window to watch for the keystrokes in.
The Enable is a status expression controlling the comparison. The comparison starts after the Enable becomes true. If the Enable becomes false, the function's value becomes false and the comparison starts at the beginning of the Keys string again after the Enable becomes true. This feature is useful for resetting the WinMatchKeys function after an action using the function's result has been performed.

The WinMatchKeys function is also reset automatically when it occurs in an action trigger that becomes true.
The function's result is automatically set to false(0) when the state containing the function is entered. After the function becomes true, it remains true as long as the state does not change and the Enable remains true.
Any key sequence may be used for the Keys parameters including the function keys. Note that the WinMatchKeys function is case sensitive (upper and lower case letters are treated as different characters) when the Enable is an odd number. Often only one key is included in the Keys string. Several keys may be used in the Keys string and function as a password. The keys typed are not displayed on the screen by this function. Several WinMatchKeys functions may be active at any time, each comparing the keyboard input against their own Keys parameter.

Buffer constants for ASCII codes
Name of Constant | Contents | Description
BS | MakeBuff(1, 8) | Backspace key
CR | MakeBuff(1, 13) | Carriage return
CRLF | Concat(CR, LF) | CR/LF pair
ESC | MakeBuff(1, 27) | Escape key
FF | MakeBuff(1,12) | Form feed
LF | MakeBuff(1, 10) | Line feed
NULL | MakeBuff(1, 0) | Null byte
TAB | MakeBuff(1, 9) | Tab key
CtrlBraceOpen | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBC)) | Ctrl and [
CtrlBraceClose | Concat(MakeBuff(1, 253), MakeBuff(1, 0x39)) | Ctrl and ]
UpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x48)) | Up arrow key
DownArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x50)) | Down arrow key
LeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4B)) | Left arrow key
RightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4D)) | Right arrow key
AltLeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9B)) | Alt and left arrow
AltRightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9D)) | Alt and right arrow
SUpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB8)) | Shift and up arrow
SDownArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xC0)) | Shift and down arrow
PageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0x49)) | Page up key
PageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0x51)) | Page down key
HomeKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x47)) | Home key
EndKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4F)) | End key
DeleteKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x53)) | Delete key
SPageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB9)) | Shift and page up
SPageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0xC1)) | Shift and page down
SHomeKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB7)) | Shift and home
SEndKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBF)) | Shift and end
CtrlPageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0x84)) | Ctrl and page up
CtrlPageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0x76)) | Ctrl and page down
CtrlHome | Concat(MakeBuff(1, 253), MakeBuff(1, 0x77)) | Ctrl and home
CtrlEnd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x75)) | Ctrl and end
CtrlBKey | MakeBuff(1, 2) | Ctrl and B
CtrlCKey | MakeBuff(1, 3) | Ctrl and C
CtrlDKey | MakeBuff(1, 4) | Ctrl and D
CtrlIKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB5)) | Ctrl and I
CtrlMKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBA)) | Ctrl and M
CtrlPKey | MakeBuff(1, 16) | Ctrl and P
CtrlSKey | MakeBuff(1, 19) | Ctrl and S
CtrlTKey | MakeBuff(1, 20) | Ctrl and T
CtrlUKey | MakeBuff(1, 21) | Ctrl and U
CtrlVKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x06)) | Ctrl and V
CtrlXKey | MakeBuff(1, 24) | Ctrl and X
CtrlYKey | MakeBuff(1, 25) | Ctrl and Y
CtrlZKey | MakeBuff(1, 26) | Ctrl and Z
Buffer constants for non-ASCII codes
AltEnter | Concat(MakeBuff(1, 253), MakeBuff(1, 0x32)) | Alt and Enter
AltUpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x98)) | Alt and up arrow
SLeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBB)) | Shift and left arrow
SRightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBD)) | Shift and right arrow
F2 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3C)) | F2
F3 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3D)) | F3
F4 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3E)) | F4
F5 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3F)) | F5
ShiftF2 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x55)) | Shift and F2
ShiftF3 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x56)) | Shift and F3
ShiftF4 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x57)) | Shift and F4
ShiftF5 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x58)) | Shift and F5
STab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x09)) | Shift and Tab
CtrlTab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x94)) | Ctrl and Tab
CtrlShiftTab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9C)) | Ctrl, Shift and Tab
CtrlMinus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2A)) | Ctrl and -
CtrlPlus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2D)) | Ctrl and +
CtrlShiftMinus | MakeBuff(1, 0x1F) | Ctrl, Shift and -
CtrlShiftPlus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2E)) | Ctrl, Shift and +
CtrlNumAdd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x90)) | Ctrl and Numpad +
CtrlNumSubtract | Concat(MakeBuff(1, 253), MakeBuff(1, 0x8E)) | Ctrl and Numpad -
CtrlNumMultiply | Concat(MakeBuff(1, 253), MakeBuff(1, 0x36)) | Ctrl and Numpad *
CtrlShiftNumAdd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9A)) | Ctrl, Shift & Numpad +
CtrlShiftNumSubtract | Concat(MakeBuff(1, 253), MakeBuff(1, 0x96)) | Ctrl, Shift & Numpad -
AltNumMultiply | Concat(MakeBuff(1, 253), MakeBuff(1, 0x37)) | Alt & Numpad*
WinContext | Concat(MakeBuff(1, 253), MakeBuff(1, 0xE8)) | Context Menu Key
CtrlTilde | Concat(MakeBuff(1, 253), MakeBuff(1, 0x26)) | Ctrl and ~
CtrlShiftBraceOpen | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBE)) | Ctrl, Shift and [
CtrlShiftBraceClose | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3A)) | Ctrl, Shift and ]
Ctrl0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x72)) | Ctrl and 0
CtrlNum0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x92)) | Ctrl and Numpad0
Alt0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x81)) | Alt and 0
AltNum0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9E)) | Alt and Numpad0
CtrlShiftNKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x08)) | Ctrl, Shift and N
CtrlShiftVKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x05)) | Ctrl, Shift and V

Comparisons exceeding 256 bytes (source string) is not supported and will return FALSE. Note that this is not the number of characters but the underlying bytes. Characters can be between 1 to 4 bytes since UTF-8 is supported.

Multi-character String comparison is not supported on VIC.

Example:

If WinMatchKeys(secondaryWin, 2, "go");
[
  ...
]

This statement will wait until the window designated by secondaryWin is active and then will further wait until the keys "go" (in any case, upper or lower) is entered at the keyboard. At that point the function will return true and the script will execute.

Related information:

Latching and Resetting Functions


WinShiftKeys

Deprecated. Works only on VTScada servers, not on Internet clients. Use WinMatchKeys for new code.

(Engine-Level Function)

Description: | Returns a value which contains the current status of the Shift, Control and Alt control keys.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Keyboard
Related to: | WinMatchKeys
Format: | WinShiftKeys(Object)
Parameters: |
Object
Required. Any expression that gives the object value of any module instance which is drawn in the window.
Comments:

The return value will be a sum of the individual key values (i.e. each key has a bit which when set indicates that the key is currently pressed)

(See: Bitwise Parameters & Operations)

Return Value | Bit No. | Key
1 | 0 | Shift
2 | 1 | Control
4 | 2 | Alt
8 | 3 | Caps lock (locked on)
16 | 4 | Num lock (locked on)
32 | 5 | Scroll lock (locked on)
64 | 6 | Left arrow
128 | 7 | Down arrow
256 | 8 | Right arrow
512 | 9 | Up arrow
1024 | 10 | Page down
2048 | 11 | Page up


WinTooltipCtrl

(Engine-Level Function)

Description: | Windows native "tooltip" control. A "tooltip" is a pop-up text window that provides operational hints to users when the mouse pointer is rested over a tool or object.
Returns: | Invalid
Usage: | Steady State only.
Function Groups: | Graphics, Locator
Related to: | WindowOptions
Format: | WinTooltipCtrl(X0, Y0, X1, Y1, Style, Text [, Title, IconIndex, Enable, Font])
Parameters: |
X0, Y0, X1, and Y1
Required. Coordinates of a rectangular screen area. When the mouse enters that area (the "hit area"), and stops moving for a time, the pop-up tooltip will be displayed.
Style
Required. One or more of the following bit flags, used to control the style of the tooltip:
  • 1 - If set, the tooltip will respond to the mouse in the hit area regardless as to whether the containing window is the active window. If clear (default), the tooltip only responds if it is the active window.
  • 32 - If set, fading of the tooltip is disabled. If clear (default), the tooltip fades in and (under some circumstances) out.
  • 64 - If set, the tooltip is displayed as a balloon. If clear (default), the tooltip is displayed as a rectangular window.
  • 128 - If set, the tooltip is displayed in-place (i.e. over the top of the hit area). This is most useful when the hit area is occupied by clipped text and the tooltip contains the full text, so that hovering over the clipped text shows the full text in a tooltip window positioned over the top of the clipped text. Note: System.ListBox uses this ability.

(See: Bitwise Parameters & Operations)

Text
Required. Any expression yielding a simple text value or a 1-dimensional array of text values. If this yields a simple text value, the text value is displayed in the tooltip control, interpreting any carriage return/line feed pairs (CRLF) as a line break, causing what follows to display on the following line. If this yields an array, each element of the array is displayed in a new line of the tooltip control. Text is limited to 1000 characters.
Title

An optional parameter that can be any expression yielding a simple text value. The text value is displayed in the tooltip control as a title (emboldened at the top of the tooltip).

Titles are limited to 100 characters. Windows will blank any tool tip title longer than 100 characters.

IconIndex
Selects an optional icon to display to the left of the title:

Invalid or 0 - No Icon

1 - Information Icon

2 - Warning Icon

3 - Error Icon

Note that while the operating system may define other icons for other values of this parameter, these are not defined at the present, and are hence subject to change.

Enable
An optional parameter that if non-zero enables the popping-up of the tooltip. If Invalid, the default is true (i.e. pop-up enabled).
Font

An optional parameter that can be set to a font value for the font to be used by the tooltip. If Invalid, the default system font is used.

Note that underlining is not supported.

Comments: This statement returns Invalid.
The background color, text color, and delay timings are set on a per-window basis using the WindowOptions statement.

Detailed information about native Windows tooltip support is provided in "Common Tasks: Native Windows Tooltip Support".


WinXLoc

(Engine-Level Function)

Description: | Returns the X coordinate of the locator (mouse) for a window.
Returns: | Numeric
Usage: | Script or steady state.
Related to: | WinLocSwitch | WinYLoc | XLoc | YLoc | GUITransform
Format: | WinXLoc(Object)
Function Groups: | Graphics, Locator, Window
Parameters: |
Object
Required. Any expression that gives the object value of any module instance which is drawn in the window.
Comments:

Returns the location of the mouse for a particular window. If the mouse is not over that window, it retains the value from the last time that the mouse was over that window. If the window that the mouse is over is a child window, a WinXLoc/WinYLoc statement in the parent will register the same values as one in the child. That is, the coordinate position in the child window. Similarly, when the mouse is moved over the parent, the values for WinXLoc/WinYLoc in both the parent and child windows will be the same. That is, the location of the mouse in the parent window.

Note: This function is disabled when using a GUITransform as a GUIStrectch.

Example:

If Change(WinXLoc(myWin), 0) || Change(WinYLoc(myWin), 0);
[
  ...
]

This statement checks for any movement of the mouse in the window designated by myWin and executes the script when it occurs.


WinYLoc

(Engine-Level Function)

Description: | Returns the Y coordinate of the locator (mouse) in a window.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics, Locator, Window
Related to: | WinLocSwitch | WinXLoc | XLoc | YLoc | GUITransform
Format: | WinYLoc(Object)
Parameters: |
Object

Required. Any expression that gives the object value of any module instance which is drawn in the window.

Note: This function is disabled when using a GUITransform as a GUIStrectch.

Example:

ZBar(10, 500, 100, WinYLoc(myWin), 14);

This statement draws a yellow bar on the left side of the window whose top follows the movement of the mouse in the window designated by myWin.


WKSList

(Engine-Level Function)

Description: | Generates a list of sub-paths from the query returned by the WKSPath function.
Returns: | Array
Usage: | Script Only.
Function Groups: | Network
Related to: | WKSPath | WKSStatus
Format: | WKSList(QueryPath)
Parameters: |
QueryPath
Required. A query path as generated by WKSPath. Due to the complexity of the included symbols and formatting rules, this path should not be hand-coded.
Comments: Returns an array of sub-paths that are a refinement of the query path returned from WKSPath. If the query path provided is a broad category, the resulting array may be quite large.
Returns a Windows™ PDH error code upon failure. This is a long integer containing a 32-bit code.


WKSPath

(Engine-Level Function)

Description: | Given set of path components, generates a query path for use in the WKSStatus command.
Returns: | Text
Usage: | Script Only.
Function Groups: | Hardware and Software, Network
Related to: | WKSList | WKSStatus | WKStaInfo
Format: | WKSPath(MachineName, ObjectName[, InstanceName, ParentInstance, InstanceIndex, CounterName)
Parameters: |
MachineName
Required. The name of the computer to query. Can be obtained dynamically using the function call, WkStaInfo(0);
ObjectName

Required. The system object to query. (corresponds to the objects in the top list in the provided image). "Processor" is an example.

The ObjectName must be in the locale language (the language that the user account is in). For example, using an English string on a French user account will return an error.

InstanceName
The name of the instance of the system object to query. The wildcard, * may be used to query all instances.
ParentInstance
The name of the parent instance of the system object. The wildcard, * may be used to query all parent instances.
InstanceIndex
An integer assigned to the system object, if unnamed.
CounterName
The name of the data item to query from the system object. The wildcard, * may be used to query all sub items of the system object.
Comments: If the optional parameters are to be included but not specifically set, then wildcard values must be provided. For text parameters, use the asterisk *, and for numeric parameters, use -1.
The output from WKSPath will usually be passed to WKSList for further processing, then to WKSStatus to use to query workstation status. The parameters to this function and the resulting query path are best understood in the context of the Windows™ Performance Monitor.
Returns a Windows™ PDH error code upon failure. This is a long integer containing a 32-bit code.

Example:

  If 1 Main;
  [
    MachineName    = WkStaInfo(0);  { Set up some defaults }
    ObjectName     = "Processor";
    InstanceName   = "*";      { These last four match the
                                 native defaults of the WKSPath function }
    ParentInstance = "*";
    InstanceIndex  = "0";
    CounterName    = "*";
  ]
]

Main [
  If ZButton(10, 70, 950, 50, "Create Query", 7);
  [   { Converts a set of parameters into a query string }
    Query = WKSPath(MachineName, ObjectName, InstanceName,
                    ParentInstance, InstanceIndex, CounterName);
  ]


WKSStatus

(Engine-Level Function)

Description: | Sends a query to the Windows™ Performance Monitor interface (see image in WKSPath) and returns the result as a query handle.
Returns: | Handle
Usage: | Script Only.
Function Groups: | Hardware and Software, Network
Related to: |
Format: | WKSStatus(Query, OperationType)
Parameters: |
Query
Required. The query to be sent to the Performance Monitor. The query path should be built using WKSPath, possibly refined by being passed through WKSList.
OperationType
Required. Controls the operation according to the following values:
OperationType | Action
0 | Get value
1 | Get error value.
2 | Generate handle (QueryHandle must be a path)
3 | Clear handle
Comments:

Returns a number of type double as a result of the query provided. Upon error, the result will be invalid. The operation type can be set to 1 to obtain the error code. Note that some queries must be checked multiple times before a result will be produced, therefore not all error codes are critical.

The WksStatus function can report values greater than 100% for percentage counters such as "\\@\Process(VTS)\% Processor Time" when (for example) a total of more than one CPU core is being used by the process.

Related Functions:

WKSPath | WKSList

Example:

handle = WKSStatus("\\MyPC\Processor(_Total)\% Processor Time", 2);
{ get a handle that will query total processor time }
IfThen(status = WKSStatus(handle, 1), { do a test for errors }
… error …
{ error code zero means things are okay,
everything else is a fault code }
);
value = WKSStatus(handle, 0);
{ make a priming read - some queries require two reads before
producing data }
… wait one second …
{ let some time pass before the second read }
value = WKSStatus(handle, 0); { read some data }
IfThen(status = WKSStatus(handle, 1),
{ before using the data make sure there weren't any problems }
… error …
);
WKSStatus(handle, 3);
{ close the handle when done, note that the same handle can be
reused as long as needed. }
{ A new handle is not necessary for each read }


WKStaInfo

(Engine-Level Function)

Description: | Returns the characteristic information about this workstation.
Returns: | Text
Usage: | Script only.
Function Groups: | Network, Hardware and Software
Related to: | VStatus | Platform | BuffToHex |
Format: | WKStaInfo(Option)
Parameters: |
Option
Required. Selects the characteristic to return, as shown in the following table
Option | Return characteristic
0 | Workstation name
1 | User name
2 | Domain name
3 | Unique Machine Identifier
4 | Returns TRUE if the local machine is configured to resolve names using DNS.
5 | Returns the domain name of the computer.
6 | Returns the activation code if that code can be validated to match the machine ID.
7 | Returns the installation timestamp.
8 | Returns the fully qualified distinguished name. example: "CN=Jeff Smith, OU=Users, DC= Engineering, DC=Com"
Comments:

If looking for the workstation name, it is more efficient to use the \RPCManager variable WkStnName rather than call this function. (\RPCManager.WkStnName)
Variables available in \RPCManager

This function will only return a valid value if the machine has a workstation name assigned to it (i.e. if network services have been installed). If network services have not been installed it will return invalid.
Option 3, the unique machine identifier, returns a 6-byte binary buffer. Use the function System.BuffToHex on the returned value if you would like to use the MachineID as a Hex string.

VTScada relies on a Windows function call to obtain the NetBios name of workstations. That function will truncate names that are longer than 15 characters. You are advised to limit workstation names to be 15 characters or less.


WrapText

(Engine-Level Function)

Description: | Breaks a text string based on given font and width and returns the text segments in an array.
Returns: | Array of text
Usage: | Script Only.
Function Groups: | String and Buffer
Related to: | BuffToArray | Font
Format: | WrapText(String, Font, Width[, GetSpaceLen])
Parameters: |
String
Required. The text to be wrapped.
Font
Required The font to use for the width calculation, as returned by a call to theFont function.
Width
Required numeric. The maximum number of pixels to be occupied by any line of the wrapped text.
GetSpaceLen
Optional Boolean. Set TRUE to return a 2D array, the first column (left-most) will contain wrapped text, and the second (right-most) will contain the trailing whitespace length. Set FALSE to return a one-dimensional array that contains only the wrapped text. Defaults to FALSE.
Comments: Pixels are assumed to have a dpi size of 96.


Write

(VTSDriver Library)

Description: | Used by a tag to create a write request to a driver address.
Returns: | Object value of underlying write module if called on a Server. Returns Invalid when called on the client.
Usage: | Script Only.
Function Groups: | String and Buffer, Stream and Socket
Related to: | AddRead
Format: | …\Driver\Write(Address, N, Val[, DType, TagName, Success])
Parameters: |
Address
Required. The starting address to write the data to.
N
Required. The number of elements to write.
Val
Required. The data to be written. If Val is a single value or a statically-declared array, it should be preceded by a pointer reference (&). Do not use the pointer reference if passing a dynamically-declared array of values.
DType
No longer used. Was: the data type to be written to the I/O device.
TagName
The name of the tag that is writing the data.
Success

Pointer to a Boolean, used to pass success/fail information.

Success is not set if Write is called on a client.

Comments:

Allows the writing of a specific address on demand. The resulting data will be sent only to the requesting machine.

Write returns Invalid when called on the client. Only when running on the server does it return an object that can be used to tell if the write is done.

The object value of the underlying read module is returned from the function. When the write finishes, the returned object’s value will go to Invalid, signaling the end of the write operation.

Example:

{ Simple variable example - writes a value of 12 to address 49500 }

WriteData = 12;
\Root\Driver\Write(49500, 1, &WriteData, Invalid(), Invalid(), &Success);

{ Multi-variable (array) example - writes 12, 14, 30123 to addresses 40001, 40002, & 40003 respectively }

WriteData = New(3);
WriteData [0] = 12;
WriteData [1] = 14;
WriteData [2] = 30123;
\Root\Driver\Write(40001, 3, WriteData, Invalid(), Invalid(), &Success);


WriteHistory

(Historian Manager Library)

Description: | Interface to write tag history.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | Log
Related to: | GetTagHistory
Format: | \HistorianManager.WriteHistory(TagObj[, TimeStamp, Data, HistorianObj, BroadcastMode])
Parameters: |
TagObj
Required. The tag instance for which the data is to be written
TimeStamp
Optional UTC timestamp.
If invalid, a timestamp will be generated using the current time.
If the number of records to be written is 1 then this should be a simple value.
If several records are to be written, this should be a simple array having a size that matches the number of records.
Data
Optional data values to record.
If invalid, current values from TagObj will be used. Otherwise, this may be:
  • A simple value to log a single variable.
  • A simple array, the size of which must match the number of records to write if the number of variables for each record is 1. Otherwise, this must match the number of logged variables for each record.
  • If logging attribute data, this must be an array of Value and Value!, where Value! is a bitwise value specifying attributes such as Manual Data and Questionable. Refer to

Data from an I/O and Calculations tag will always include attribute data and must always be provided as an array of Value and Value!.

  • An array of arrays - to be used only if the number of logged variables for each record (NumLogVars) is > 1 and the number of records to record (NumRecords) is > 1. The containing array size must match NumLog Vars and the nested array size must match NumRecords. See examples.
HistorianObj
An optional instance of the Historian tag used to log this value. If invalid, TagObj\HistorianName will be used.
BroadcastMode
An optional Boolean value. If TRUE, then the history is automatically relayed to all Historian-potential servers. Defaults to FALSE.
Comments:

In order to ensure that the history is successfully written, this function must be called with the same data on all Historian-potential servers, (which can be done by calling it on all workstations,) unless BroadcastMode is TRUE, in which case it need only be called on exactly one workstation (any workstation).

Possible return values are as follows:

-1 if the number of timestamps passed in does not match the number of data entries passed in.

0 otherwise. This does not indicate that the data was written, just that the above condition on the parameters held true.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Examples:

Simple case:

\HistorianManager\WriteHistory(TagObj, TimestampInUTC, Value);

More complex use case:

Given a tag with two logged variables, defined as:

Value(5)
Comment(6)
\HistorianManager\WriteHistory(TagObj, TimestampsInUTC, DataArray);

Note that, when building the array of arrays, the order is important. The values should correspond to the variable declared alphabetically by variable class type. Thus, Value(5) comes before Comment(6). See: Data Logged or Trended Variables in Tag Modules.


WriteINI

Access to configuration files is not reliable unless the caller holds the working copy lock. Acquiring the lock is a steady-state only operation, and therefore legacy operations that used script-mode access to these files are deprecated or no longer supported (see comments)

(System Library)

Description: | This subroutine writes a variable's value to a configuration file or a buffer containing one and returns its error code. Will not access .Startup or .Dynamic files.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | File I/O
Related to: | CheckFileExist | CheckPathExist | ReadINI | ReadSectINI | WriteSectINI
Format: | System.WriteINI(File, Section, VarName, Value [, UseBuff])
Parameters: |
File
Required. Any text expression giving the absolute path and file name of the Settings file or a pointer to the buffer containing its contents, depending on parameter UseBuff.
Section
Required. Any text expression giving the name of the section in the file. This should not include the square brackets delimiting the section.
VarName
Required. Any text expression giving the name of the variable for which the value is to be set.
Value
Required. Any giving the value to be assigned to variable VarName.
UseBuff
An optional parameter that is any logical expression. If true (non-0) the value of File must be a pointer to a buffer, if false (0) it is a file that is to be used. The default used if this parameter is omitted is false.
Comments:

For developers the lock means that access to VTScada working copy files, both reading and writing, should not be done without having the lock. The lock is across all applications and system layer VTScada code. The lock prevents two different piece of code from changing the same code such that one piece of code sees inconsistent data while the other code is in the middle of changing it.

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The subroutine returns true (1) if the write was successful and invalid otherwise. If the Settings file, the section, or the variable does not exist, they will be created.
Searches performed by this function are case insensitive. Alignment of equal signs in the file is preserved.

Example:

If 1 Main;
[
  System.WriteINI("C:\VTScada\Setup.ini"){filename},
                  "System " { Name of section },
                  "OrderlyShutdown" { Name of variable },
                  10 { Value of variable },
                  0 { Write file format });
]

This assigns a value of 10 to the variable OrderlyShutdown in the System section of the Setup.INI file.


WriteINIProperties

Description: | Writes properties to the local layer's various settings files in one operation.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Configuration Management
Related to: | WritePropertiesFile |
Format: | Layer\WriteINIProperties(INIProperties[, ExternalLock])
Parameters: |
INIProperties
Required. A dictionary containing the properties and values to be written. This dictionary must have the same structure as that returned by ReadINIProperties.
ExternalLock
Optional Boolean. Set to TRUE if you do not want to acquire and release the lock. Defaults to FALSE.
Comments: This function is the opposite of ReadINIProperties.
In nearly all cases, it is recommended that WritePropertiesFile be used in place of this function.

Examples:

none


WriteLock

(RPC Manager Library)

Description: | This subroutine attempts to require a Write lock for the specified service. Subroutine call only.
Returns: | Nothing
Usage: | Script Only.
Function Groups: | Network
Related to: | ReadLock
Format: | \RPCManager\WriteLock(ActivePtr, Service [, OptGUID]);
Parameters: |
ActivePtr
Required. A reference to a variable that will be set to "1" when the Read lock is obtained.
Service
Required. The name by which the service is known.
OptGUID
An optional parameter indicating the GUID of the application in which the service instance is located. The default is the application to which the caller belongs.
Comments: This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.SRC.

Related information:

RPC Manager Service


WritePropertiesFile

(System Library)

Description: | Write a single Settings file according to the properties in an INIFile structure. Replaces WriteINI and WriteSectINI
Returns: | Boolean indicating success or failure.
Usage: | Script Only.
Function Groups: | Configuration Management, File I/O
Related to: | ReadPropertiesFile | GetINIProperty | SetINIProperty
Format: | System.WritePropertiesFile(INIData, TargetDirectory[, IsBuffer, Flushing])
Parameters: |
INIData
Required. An INIFile data structure, containing the file name to write to and the application properties to be written. Created as follows... IniData = System.INIFiles();
See the Comments section for a description of the INIFile data structure.
TargetDirectory
A text expression providing a directory name to be concatenated in front of the FileName provided by the INIData parameter. If left blank, a base path to the VTScada install directory will be appended to the what is in the FileName member of the INIFile structure.
IsBuffer
An optional logical expression. Set TRUE if the TargetDirectory parameter is a buffer, which will receive the output of the function. Defaults to FALSE (0).
Flushing
Optional Boolean. Set TRUE to force flushing of data to storage immediately after the write This reduces the chance of data loss if the writing operation is interrupted. Defaults to FALSE.
Comments: Many properties can be modified with a single call to WritePropertiesFile.

The INIFile structure is as follows:

INIFiles Struct [
  FileName    { File name to the settings file. Path may be included,
                 but is better specified in the TargetDirectory
                 parameter.                                         };
  OEM         { TRUE if an OEM layer file                             };
  Workstation { Name of the workstation or invalid if global          };
  Layer       { Instance of application layer owning the file         };
  Dynamic     { TRUE if a dynamic property                            };
  Sections    { Dictionary of sections each element of which
                is an array of Property structures         };
  Changed     { User sets to true if the file has been changed,
                initialized to false                                  };
 ]

The INIProperty structure is…

INIProperty Struct [
    Name        { Variable name in the .startup/.dynamic file  };
    Value       { Simple value                                 };
    Comment     { Text comment if present in the file          };
    Hidden      { TRUE if not visible in Edit Properties GUI   };
  ];

Note that if your intention is to write to a configuration file, this function should be called from within a ReadConfiguration callback or a ModifyConfiguration callback.

Example:

A System.INIProperty() structure is used in the INIFIles\Sections

    { Setup the INIFiles Struct }
    INIData = System.INIFiles();
    INIData\FileName    = Concat(ProfileName, ".ini");
    INIData\Workstation = Invalid;
    INIData\Dynamic     = 0;
    INIData\Sections    = Dictionary();
    INIData\Changed     = 0;
    { Now write to the .ini file }
    System.WritePropertiesFile(INIData, "MyProject\Profiles\");


WriteSectINI

(System Library)

Description: | This subroutine writes an entire section to a configuration file or a buffer containing one and returns its error code. Will not access .Startup or .Dynamic files. Access to configuration files is not reliable unless the caller holds the working copy lock. Acquiring the lock is a steady-state only operation, and therefore similar legacy operations that used script-mode access to these files are deprecated or no longer supported (see comments)
Returns: | Numeric
Usage: | Script Only.
Function Groups: | File I/O
Related to: | CheckFileExist | CheckPathExist | Edit | Folder | ReadINI | ReadSectINI | WriteINI
Format: | System.WriteSectINI(File, Section, VarList [, UseBuff])
Parameters: |
File
Required. Any text expression giving the absolute path and file name of the Settings file or the name of the buffer containing its contents.
Section
Required. Any text expression giving the name of the section in the file. This should not include the square brackets delimiting the section.
VarList
Required. A 2 dimensional array containing the variables and their values to write to the file. The first row, VarList[0][N], contains the variable names, while the second row, VarList[1][N] contains their values.
UseBuff
An optional parameter that is any logical expression. If true (non-0) the value of File must be a pointer to a buffer, if false (0) it is a file that is to be used. The default used if this parameter is omitted is false.
Comments:

WriteSectINI is a subroutine, and as such it needs to return quickly. It therefore cannot wait for a lock. For developers the lock means that access to VTScada working copy files, both reading and writing, should not be done without having the lock. The lock is across all applications and system layer VTScada code. The lock prevents two different piece of code from changing the same code such that one piece of code sees inconsistent data while the other code is in the middle of changing it.

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

The subroutine returns true (1) if the write was successful and invalid otherwise. If the Settings file or the section does not exist, they will be created. If the VarList parameter is invalid, a blank section will be created. This is a destructive write. That is to say, the entire section of the file is overwritten by the new section, regardless of the contents of either.
Searches performed by this function are case insensitive. Alignment of equal signs in the file is preserved.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.

Example:

If 1 Main;
[
  Vals[0][0] = "OrderlyShutdown";
  Vals[1][0] = 1;
  Vals[0][1] = "ShdownOnLowBattery";
  Vals[1][1] = 1;
  System.WriteSectINI("C:\VTScada\Setup.INI" { Name of file },
    "System" { Name of section },
  Vals { Arrays of data },
  0 { Write file format });
]

This causes the variables OrderlyShutdown and ShutdownOnLowBattery in the System section of the Setup.INI file to have their values set to 1 and 1.


X Functions

The sections that follow identify all VTScada functions beginning with "X".


XLoc

(Engine-Level Function)

Description: | Returns the X window coordinate of the locator (mouse).
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics, Locator, Window
Related to: | SetXLoc | SetYLoc | WinXLoc | WinYLoc | YLoc
Format: | XLoc()
Parameters: | None

Example:

ZBox(10, YLoc(), XLoc(), 10, 11);

This statement will draw a box in the window whose upper left corner is fixed at (10, 10), but whose lower right corner follows the mouse.


XMLAddSchema

(Engine-Level Function)

Description: | Adds a schema to an XML Processor.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | XML
Related to: | XMLParse | XMLProcessor | XMLWrite | XMLCloneNode | XMLCreateNode | XMLDeleteMember | XMLGetNode | GetXMLNodeArray
Format: | XMLAddSchema(XMLProcessorHandle, NamespaceURI, URL[, ErrorMessageOut])
Parameters: |
XMLProcessorHandle
Required. A valid processor, as returned by the function XMLProcessor.
NamespaceURI
Required. A URI that specifies the namespace that the schema represents.
URL
Required. The URL to fetch the schema from.
ErrorMessageOut
An optional text parameter that allows an error message to be returned from the function.
Comments: Each schema will be validated for standards conformance before being added to the cache. Returns 0 if it succeeds, otherwise it returns a numeric specifying a Windows error code and sets the variable named in the optional ErrorMessageOut parameter to a text error message. If the schema load succeeds, the types identified by the schema are added to the factory.


XMLCloneNode

(Engine-Level Function)

Description: | Clones an existing XMLNode, optionally adding additional members.
Returns: | The cloned XMLNode, with any additional members supplied.
Usage: | Script Only.
Function Groups: | XML
Related to: | XMLParse | XMLProcessor | XMLAddSchema | XMLWrite | XMLCreateNode | XMLDeleteMember | XMLGetNode | GetXMLNodeArray
Format: | XMLCloneNode(XMLNode [, MembersDictionary])
Parameters: |
XMLNode
Required. A valid XMLNode.
MembersDictionary
An optional dictionary containing additional members to be added to the cloned node.
Comments: If the optional member dictionary parameter is supplied, any additional members will be added to the cloned node in the same order that they were added to the dictionary.

Example:

MembersDict = Dictionary(0);
MembersDict["ISBN"] = XMLCreateNode("01234567890");
MyNode = XMLCloneNode(XMLNode\catalog\book, MembersDict);


XMLCreateNode

(Engine-Level Function)

Description: | Creates a new XMLNode.
Returns: | An XMLNode.
Usage: | Script Only.
Function Groups: | XML
Related to: | XMLParse | XMLProcessor | XMLAddSchema | XMLWrite | XMLCloneNode | XMLDeleteMember | XMLGetNode | GetXMLNodeArray
Format: | XMLCreateNode([Contents, AttributesDictionary, Namespace, MembersDictionary])
Parameters: |
Contents
A text value to be placed in the #content member of the XMLNode.
AttributesDictionary
A dictionary containing attributes for the XMLNode
Namespace
A text value containing the namespace for the XMLNode.
MembersDictionary
A dictionary containing additional members to be added to the XMLnode.
Comments: If the optional member dictionary parameter is supplied, any additional members will be added to the XMLNode in the same order that they were added to the dictionary.
If the #comment or #cdata members require values, they can be assigned after the node has been created.

Example:

AttribsDict = Dictionary(0);
AttribsDict["id"] = 42;
MembersDict = Dictionary(0);
MembersDict["Item1"] = XMLCreateNode("01234567890");
MyNode = XMLCreateNode("abc", AttribsDict,
                      https://vtscada.com/XML", MembersDict);

Creates the following XMLNode:


XMLDeleteMember

(Engine-Level Function)

Description: | Deletes a member from an XMLNode in-place.
Returns: | Nothing.
Usage: | Script Only.
Function Groups: | XML
Related to: | XMLParse | XMLProcessor | XMLAddSchema | XMLWrite | XMLCloneNode | XMLCreateNode | XMLGetNode | GetXMLNodeArray
Format: | XMLDeleteMember(XMLNode, MemberName)
Parameters: |
XMLNode
Required. The XMLNode to delete the member from.
MemberName
Required. The name of the member to delete.
Comments: The deletion of the member is done "in-place".


XMLGetNode

(Engine-Level Function)

Description: | Returns an XMLNode from a tree.
Returns: | The XMLNode specified.
Usage: | Script Only.
Function Groups: | XML
Related to: | XMLParse | XMLProcessor | XMLAddSchema | XMLWrite | XMLCloneNode | XMLCreateNode | XMLDeleteMember | GetXMLNodeArray
Format: | XMLGetNode(XMLNode)
Parameters: |
XMLNode
Required. The XMLNode to return.
Comments: When isolating a particular XMLNode, to pass to a subroutine for instance, the automatic subscripting of an XMLNode to provide the value in its #content member means that this is passed to the subroutine.
Thus,
   GoodXML = Valid(XMLGetNode(XMLData));

Is not equivalent to

   XMLObject = XMLGetNode(XMLData);
   GoodXML  = Valid(XMLObject);

To defeat the automatic subscripting, use this function.

See notes in VTScada Engine XML API for a discussion of how to address arrays within an XML node.

Example:

Given an XMLNode named "MyNode" as created with the following code:

AttribsDict = Dictionary(0);
AttribsDict["id"] = 42;
MembersDict = Dictionary(0);
MembersDict["Item1"] = XMLCreateNode("01234567890");
MyNode = XMLCreateNode("abc", AttribsDict,
                       "http://trihedral.com/XML", MembersDict);

Then calling a subroutine as follows will pass the value of the #content member to the subroutine, in this case: "abc":

MySub(MyNode);

To pass the actual node use the following construct:

MySub(XMLGetNode(MyNode));

Note that a similar construct uses the address-of operator (&) but then the subroutine will have to de-reference the parameter (using the * operator) on every use.


XMLParse

(Engine-Level Function)

Description: | Parses the supplied XML using the specified XML Processor.
Returns: | Numeric error code
Usage: | Script Only.
Function Groups: | XML
Related to: | XMLProcessor | XMLAddSchema | XMLWrite | XMLCloneNode | XMLCreateNode | XMLDeleteMember | XMLGetNode | GetXMLNodeArray
Format: | XMLParse(XMLProcessorHandle, XMLin [, ErrorMessageOut, XMLNodeTreeOut, NamespaceDictionary ])
Parameters: |
XMLProcessorHandle
Required. A valid processor, as returned by the XMLProcessor function.
XMLin
Required. The XML text to be parsed. May be either text or a valid stream. If the text supplied (either in the text value or the stream) is identifiable as a URL, the XML is fetched from that URL.
ErrorMessageOut
A text parameter into which a return error message may be placed.
XMLNodeTreeOut
Must be a variable into which the XMLNode tree, created by parsing the XML successfully, will be placed.
NamespaceDictionary
(Return value) A dictionary of namespaces and prefixes found in the parsing of the XML.
Comments:

The XML may be either a stream or a text value. Returns 0 if it succeeds. Otherwise returns a numeric specifying a Windows error code and sets the variable named in the optional ErrorMessageOut parameter to a text error message.

Passing a very large text value to the function will result in an error. To avoid this, convert the text value to a stream using BuffStream().

In versions of VTS prior to release 10, it is necessary to explicitly slay the XMLNodeTree (the XMLNodeTreeOut parameter to XMLParse) when you are finished with it

The output parameter, XMLNodeTreeOut, will receive a valid XMLNode tree from a validating processor even if validation fails, so long as the XML can be parsed. A valid "XMLNodeTreeOut" with a valid "ErrorMessageOut" indicates a parse-able message that fails validation.

A helper function, GetXMLNodeArray, can be used on the result to extract an array of XMLnodes matching a given type name.


XMLProcessor

(Engine-Level Function)

Description: | Creates a new XML Processor.
Returns: | XML Handle
Usage: | Script Only.
Function Groups: | XML
Related to: | XMLParse | XMLAddSchema | XMLWrite | XMLCloneNode | XMLCreateNode | XMLDeleteMember | XMLGetNode | GetXMLNodeArray
Format: | XMLProcessor(SchemaCacheDictionary)
Parameters: |
SchemaCacheDictionary
Required. Must be a variable to hold the Schema Cache Dictionary. All the data types specified by the schemas in the cache will be added to this cache. Provide "Invalid" for a non-validating processor.
Comments: If SchemaCacheDictionary is a valid variable, the XML Processor will be a validating processor, otherwise it will be a non-validating processor. To destroy an XML Processor, invalidate the last reference to it.


XMLWrite

(Engine-Level Function)

Description: | Converts the instance of a type, as specified by XMLNodeTreeIn, into XML.
Returns: | Numeric
Usage: | Script Only.
Function Groups: | File I/O, XML
Related to: | XMLParse | XMLProcessor | XMLAddSchema | XMLCloneNode | XMLCreateNode | XMLDeleteMember | XMLGetNode | GetXMLNodeArray
Format: | XMLWrite(XMLProcessorHandle, XMLNodeTreeIn, XMLOut, ErrorMessageOut[, NamespaceDictionary, XSLTString])
Parameters: |
XLProcessorHandle
Required. A valid processor, as returned by the function XMLProcessor.
XMLNodeTreeIn
Required. An XMLNodeTree such as would be created by XMLParse (XMLNodeTreeOut parameter).
XMLOut
Required. A stream variable where the XML text will be placed. See comments.
ErrorMessageOut
Required. A text parameter into which any return error message is placed.
NamespaceDictionary
An optional dictionary of namespaces and prefixes such as would be created by XMLParse (NamespaceDictionary parameter).
XSLTString
An optional string containing an XSLT (extensible style sheet language transform) to be applied to the output XML.
Comments: The XML is in the form of a stream and is inserted to the stream passed in XMLOut, starting at its current position. If XMLOut does not contain a stream, a new BufferStream is created and returned in XMLOut. Returns 0 if it succeeds. Otherwise returns a numeric specifying a Windows error code and sets the variable named in the optional ErrorMessageOut parameter to a text error message.
If XSLTString is not a valid XSLT transform, the XML out will not be transformed, but ErrorMessageOut and the return value will be set to indicate the transform failure.

This function is session non-aware, meaning it works on the server's file system even with an active remote connection established. This function is also blocking, all concurrent thread operations will be paused until its execution has concluded.


XOr

(Engine-Level Function)

Description: | Returns the bitwise exclusive OR of its parameters.
Returns: | Signed 64-bit integer
Usage: | Script or steady state.
Function Groups: | Bitwise Operation
Related to: | And | Not | Or
Format: | XOr(Parm1, Parm2)
Parameters: |
Parm1, Parm2
Required. Any numeric expressions. If floating point values are supplied, they will be truncated to integers.
Comments:

This function compares the corresponding bits of two values. The result bit is 1 if exactly one of the two bits is 1. The result bit is 0 if both bits are the same (either both 1 or both 0).

This function takes signed 64-bit integers values. If a number is passed outside the range of a signed 64-bit integer, then the function will return invalid. If Value is invalid, the return value is invalid.

(See: Bitwise Parameters & Operations)

Example:

var1 = XOr(0b1100, 0b1010);

The value of var1 will be 0b0110.

A common use of XOr is to reverse the bits. To reverse the bits of a 64-bit signed integer:

64bitReverse = XOr(Input, -1);

To reverse the bits of a 32-bit integer (signed or unsigned):

32bitReverse - XOr(Input, 0xFFFFFFFF);


Y Functions

The sections that follow identify all VTScada functions beginning with "Y".


Year

(Engine-Level Function)

Description: | Returns the year for a given date number.
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Time and Date
Related to: | Date | DateNum | Day | Month | Today
Format: | Year(Date)
Parameters: |
Date
Required. Any numeric expression giving the number of days since January 1, 1970.
Comments: This function works in conjunction with the Day and Month functions to decompose a date number into the corresponding day, month and year.

Example:

whatYear = Year(8394 { 25 December 1992 });

The value of whatYear will be 1992.


YLoc

(Engine-Level Function)

Description: | Returns the Y window coordinate of the locator (mouse).
Returns: | Numeric
Usage: | Script or steady state.
Function Groups: | Graphics, Locator, Window
Related to: | SetXLoc | SetYLoc | WinXLoc | WinYLoc | XLoc
Format: | YLoc()
Parameters: | None

Example:

If Change(YLoc(), 10);
[
  ...
]

The action trigger will become true when the Y-coordinate of the mouse changes by more than 10 pixels, and the script will then execute.


Z Functions

The sections that follow identify all VTScada functions beginning with "Z".


ZBar

(Engine-Level Function)

Description: | Draws a layered bar in a window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bar | Box | GUIRectangle | ZBox
Format: | ZBar(Left, Bottom, Right, Top, Color)
Parameters: |
Left
Required. Any numeric expression for the left side coordinate of the bar.
Bottom
Required. Any numeric expression for the bottom side coordinate of the bar.
Right
Required. Any numeric expression for the right side coordinate of the bar.
Top
Required. Any numeric expression for the top side coordinate of the bar.
Color
Required. May be any of the following:
  • An RGB string in the form, "<RRGGBB>"
  • A Constants for System Colors
  • A VTScada Color Palette number from the palette.
  • -1 (transparent)
Comments: Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only.

Example:

  ZBar(50, 100, 250, 50, "<FF00FF00>");

A simple example that draws a green bar.

  ZBox(10, 200, 210,
       10 { Bounding box for box },
       0 { Box is black });
  ZBar(10, 200, 210, Limit(Scale(Fluid,
                                 0    { min },
                                 2000 { max },
                                 200  { scaled min },
                                 10   { scaled max }),
                           10  { Min value from Scale },
                           200 { Max value from Scale }) { Bounding box for bar },
       10 { Color of bar });

A complex example that represents a changing value (not a tag) using a bar.

These two statements simulate a tank that is outlined in black (using ZBox) and whose changing fluid level is represented in the ZBar statement by scaling and limiting the value of fluid. Notice that the Scale function converts (and inverts) the value from a real world fluid level to window coordinates. Because its return value is not limited by any of its parameters, the Limit function is used to declare absolute limits. Even if the value of fluid goes beyond its limits, the bar will not be drawn outside of the box.


ZBox

(Engine-Level Function)

Description: | Draws a layered box in a window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Bar | Box | GUIRectangle | ZBar
Format: | ZBox(Left, Bottom, Right, Top, Color)
Parameters: |
Left
Required. Any numeric expression for the left side coordinate of the box.
Bottom
Required. Any numeric expression for the bottom side coordinate of the box.
Right
Required. Any numeric expression for the right side coordinate of the box.
Top
Required. Any numeric expression for the top side coordinate of the box.
Color
Required. May be any of the following:
  • An RGB string in the form, "<RRGGBB>"
  • A Constants for System Colors
  • A VTScada Color Palette number from the palette.
  • -1 (transparent)
Comments: Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only.

Example:

  ZBox(10, 110, 220,
       10 { Bounding box for box },
       12 { Box is red });

This statement draws a (hollow) box in the window.


ZButton

(Engine-Level Function)

Description: | Draws a layered button in a window and returns true when selected.
Returns: | Boolean
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUIButton
Format: | ZButton(Left, Bottom, Right, Top, Label, FocusID [, Font])
Parameters: |
Left
Required. Any numeric expression for the left side coordinate of the button.
Bottom
Required. Any numeric expression for the bottom side coordinate of the button.
Right
Required. Any numeric expression for the right side coordinate of the button.
Top
Required. Any numeric expression for the top side coordinate of the button.
Label
Required. Any text expression for the button label. Will not display tab characters.
FocusID

Required. Any numeric expression from 0 to 32767 for the focus ID number. This is used to force the focus to this item. If this value is 0, the button text will be grayed, the button cannot be focused and will not respond to mouse clicks. Values above or below zero allow the control to be used.

This value is stored in a short.

Font
An optional parameter that is any expression for the font value to use. If this value is omitted, the default value of system font is used.
Comments: Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only. The colors for this graphic are taken from Microsoft Windows™.
This function behaves like a Pick with the pressing of the left mouse button being the button combination to be detected. It will return 1 on the pressing of the left mouse button.

Example:

If ZButton(10, 70, 110, 40 { Bounding box for button },
           "OK" { Text label on button },
           1 { Focus ID })
           DoneState;
[
  ...
]

This action trigger will become true when the left mouse button clicks on the button drawn in the window. At that point the script will execute and then there will be a state change to DoneState.


ZColorChange

(Engine-Level Function)

Description: | Changes one color within a region to another color. This is an older function, intended for use on objects that used a color range, such as pipes prior to release 11 of VTScada.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Color, Graphics
Related to: | GetSystemColor | PixelColor
Format: | ZColorChange(Left, Bottom, Right, Top, Original, New)
Parameters: |
Left
Required. Any numeric expression for the left side coordinate of the change region.
Bottom
Required. Any numeric expression for the bottom side coordinate of the change region.
Right
Required. Any numeric expression for the right side coordinate of the change region.
Top
Required. Any numeric expression for the top side coordinate of the change region.
Original
Required. Any one of the colors of the existing region.
New
Required. Any one of the colors which will replace the old.
Comments: Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only. A solid pattern should be used if you wish to change the color back to its original color.

The order of graphics statements are an important factor in determining which objects will have their color changed. The ZColorChange function affects all objects underneath it, which means, any object whose graphic statement is before the ZColorChange statement (including images that are displayed using a Load statement). Any object whose statement follows the ZColorChange statement will be unaffected. The background color will also be affected by ZColorChange.

Example:

ZBar(100, 500, 500, 40, 12 { Draws a large red bar });
ZColorChange(10, 210, 210, 10 { Bounding box for change },
             12, 14 { Change all red in to yellow });
ZBar(20, 60, 60, 20, 12 { Draws a small red bar });

The ZColorChange statement here will cause the upper left corner of the first large bar to be yellow, while the rest of the bar (outside the bounding box for ZColorChange) will remain red. The second bar, although drawn inside of the ZColorChange's bounding box, will be drawn in red, not yellow, because its statement follows the statement that effects the color change.


ZEditField

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Draws a layered text edit field in a window and returns a status value. Not editable when viewed on a VTScada Thin Client.
Returns: | Numeric
Usage: | Steady State only.
Function Groups: | Editor, Graphics
Related to: | Cast | WinEditCtrl
Format: | ZEditField(Left, Bottom, Right, Top, TextVar, Length, Font, FocusID)
Parameters: |
Left
Required. Any numeric expression for the left side coordinate of the field.
Bottom
Required. Any numeric expression for the bottom side coordinate of the field.
Right
Required. Any numeric expression for the right side coordinate of the field.
Top
Required. Any numeric expression for the top side coordinate of the field.
TextVar
Required. Must be a variable. The result of the text editing will be stored here. The value in this field will be automatically inserted into the field.
Length
Required. Any numeric expression for the number of characters allowed in this field.
Font
Required. Any expression for the font value to use.
FocusID

Required. Any numeric expression from 0 to 32767 for the focus ID number. This is used to force the focus to this item. Values below zero will render this control invisible. A value of zero makes this control visible, but not editable. With values above zero, the control will be editable.

Comments: Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only. The colors for this graphic are taken from Microsoft Windows™.
The return values for this function are as follows
Return Value | Meaning
0 | Internal buffer changed
1 | <CR> pressed
2 | Focus has been lost

Although data may be entered in the field, TextVar is not set until <RETURN> is pressed, or a change in focus occurs. This is crucial when setting other variables based on TextVar. As their values may not be set prior to a state change if <RETURN> has not been pressed.

This function does not check the input type, but converts all data to text. Data that is required to be of a type other than text must be converted to that type using the Cast function.

Within an Anywhere Client session, this function does nothing.

if the application is to be used on a VTScada Internet Client, WinEditCtrl should be used instead of ZEditField.

Example:

ZEditField(100, 500, 200, 470 { Bounding box for field },
           inputVal { Input value },
           3 { Max chars allowed in input },
           0, 1 { Default font and focus ID });

This statement will accept up to 3 characters of input and store it in inputVal. If inputVal has a default value, that value will be shown in the white edit field box until it is changed.


ZGrid

(Engine-Level Function)

Description: | Draws a layered point grid in a window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | Grid
Format: | ZGrid(Left, Bottom, Right, Top, Color, XSpace, YSpace)
Parameters: |
Left
Required. Any numeric expression for the left side coordinate of the grid.
Bottom
Required. Any numeric expression for the bottom side coordinate of the grid.
Right
Required. Any numeric expression for the right side coordinate of the grid.
Top
Required. Any numeric expression for the top side coordinate of the grid.
Color
Required. May be any of the following:
  • An RGB string in the form, "<RRGGBB>"
  • A Constants for System Colors
  • A VTScada Color Palette number from the palette.
  • -1 (transparent)
XSpace
Required. Any numeric expression giving a positive integer value for the spacing of the x-grid.
YSpace
Required. Any numeric expression giving a positive integer value for the spacing of the y-grid.
Comments: Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only.

Example:

ZGrid(100, 200, 200, 100 { Bounding box for grid },
      12 { Grid is light red },
      5, 5 { X and Y spacing for grid });

This places a light red 5x5 point-grid on the screen in the area bounded by the first four parameters.


Zip

(System Library)

Description: | Generates a zip archive of a file stream.
Returns: | Error on failure / Invalid on successful completion (Zip file returned via the second parameter)
Usage: | Script only.
Function Groups: | Stream and Buffer
Related to: |
Format: | \System.Zip(FileDictionary, OutputStream)
Parameters: |
FileDictionary

Required Dictionary. This contains a key and one value:

Key: The relative file path. May be a single value or an array of file paths.

Value: An associated FileData structure for each key.

  FileData Struct [
    FileStreamData    { File Stream };
  ];.
OutputStream
Required. A stream that will contain a zipped version of the specified file(s).
Comments:

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Work is done in-memory. This function can take either a file or a BuffStream as input. The output is generated in memory and must be written to storage by your code.

Example:

The following creates three zip files, illustrating three ways to use the function.

[
  FStream;
  FStream2;
  FStream3;
  FileData Struct [
    FileStreamData;
  ];
  FileDic                           { Dictionary to test with                 };
  FileDic2;
  FileDic3;
  MyZipFile                         { Output zip streams                      };
  MyZipFile2;
  MyZipFile3;
  Constant 1MiB = 1024 * 1024;
  temp;
]

Main [
  If Watch(1);
  [
    MyZipFile = BuffStream("");
    MyZipFile2 = BuffStream("");
    MyZipFile3 = BuffStream("");

     { Test a simple two-file zip }
    FileDic = Dictionary();
    FileDic["File1.txt"] = FileData(BuffStream("This is File1"));
    FileDic["File2.txt"] = FileData(BuffStream("This is File2"));
    \System.Zip(FileDic, MyZipFile);

     { Test nested directories }
    FileDic2 = Dictionary();
    FileDic2["Folder1/File1.txt"]                 = FileData(BuffStream("This is Folder1/File1"));
    FileDic2["Folder1/Folder2/File2.txt"]         = FileData(BuffStream("This is Folder1/Folder2/File2"));
    FileDic2["Folder1/Folder2/Folder3/File3.txt"] = FileData(BuffStream("This is Folder1/Folder2/Folder3/File3"));
    \System.Zip(FileDic2, MyZipFile2);

     { Large file test }
    FileDic3 = Dictionary();
    FileDic3["File1.txt"] = FileData(BuffStream(MakeBuff(1MiB*1024, 0x41)));
    \System.Zip(FileDic3, MyZipFile3);

    FStream = FileStream("C:\Path\To\MyZip\MyZip.zip");
    FStream2 = FileStream("C:\Path\To\MyZip\MyZip2.xlsx");
    FStream3 = FileStream("C:\Path\To\MyZip\MyZip3.zip");
    BlockWrite(FStream, MyZipFile);
    BlockWrite(FStream2, MyZipFile2);
    BlockWrite(FStream3, MyZipFile3);
    Return();
  ]
]


ZLine

(Engine-Level Function)

Description: | Draws a line between given x and y coordinates in a window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUIPolygon | Line
Format: | ZLine(X1, Y1, X2, Y2, Pen)
Parameters: |
X1, Y1
Required. Any numeric expressions for the X and Y coordinates of the first endpoint of the line.
X2, Y2
Required. Any numeric expressions for the X and Y coordinates of the second endpoint of the line.
Pen
Required. Any expression that returns the PEN object to use to draw the line.
A color value is also acceptable here, which may be any of the following:
  • An RGB string in the form, "<RRGGBB>"
  • A Constants for System Colors
  • A VTScada Color Palette number from the palette.
  • -1 (transparent)
Comments: Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only.

Example:

  ZLine(0, 0     { First endpoint for line  },
        799, 599 { Second endpoint for line },
        14       { Line is yellow           });

This statement draws a yellow line diagonally from the upper left corner to the lower right corner of the window.


ZPipe

Deprecated. Do not use in new code.

(Engine-Level Function)

Description: | Draws a layered three-dimensional pipe in a window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUIPipe | Pipe
Format: | ZPipe(XArrayElem, YArrayElem, N, LowIndex, HighIndex, PixelWidth)
Parameters: |
XArrayElem
Required. Any numeric expression that specifies the starting array element. The array contains the X coordinates of the path along which to draw the pipe. If processing a multidimensional array, only the right-most dimension is used.
YArrayElem
Required. Any numeric expression that specifies the starting array element. The array contains the Y coordinates of the path along which to draw the pipe. If processing a multidimensional array, only the right-most dimension is used.
N
Required. Any numeric expression giving the number of array elements to use to define the path of the pipe.
LowIndex
Required. Any numeric expression specifying the low index into the current color palette. It is used in conjunction with the next parameter to adjust the brightness and contrast of the shading.
HighIndex
Required. Any numeric expression specifying the high index into the current color palette. It is used in conjunction with the previous parameter to adjust the brightness and contrast of the shading.
PixelWidth
Required. Any numeric expression specifying the width of the shaded pipe in pixels and is subject to applicable scaling factors.
Comments: Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only.
The pipe will be drawn with a miter effect, such that pipe segments meet at 45-degree angles.

Example:

ZPipe(x[0], y[0] { First endpoint for pipe },
      8 { Number of vertices },
      176, 239 { Very dark gray to very light gray },
      24 { Width of pipe in pixels });


ZText

(Engine-Level Function)

Description: | Draws a layered text label in a window.
Returns: | Nothing
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | GUIText | Format
Format: | ZText(Left, Bottom, Value, Color, Font)
Parameters: |
Left
Required. Any numeric expression for the left side coordinate of the text.
Bottom
Required. Any numeric expression for the bottom side coordinate of the text.
Value
Required. Any text expression to display on the screen.
Color
Required. May be any of the following:
  • An RGB string in the form, "<RRGGBB>"
  • A Constants for System Colors
  • A VTScada Color Palette number from the palette.
  • -1 (transparent)
Font
Required. Any expression for the font value to use. A numeric zero (0) may be used to get the default system font.
Comments:

Although this is a layered graphic, it cannot be edited using the Idea Studio. It is for use within text mode editing only.

Will not display tab characters.

Examples:

  ZText(100, 100 { Lower left corner of text },
        "Hello World" { Text to display },
        2 { Text is green},
        0 { Use default font });

This places the string "Hello World" on the screen at (100, 100) with white text in the system font.

  ZText(500, 100 { X, Y coordinates },
        Format(0, 2, DeadBand(Pressure, 5)) { Displayed value },
        0, 0);

This displays the value of variable, "Pressure" on the screen. However, the display is only updated when pressure changes by more than 5 (higher or lower) from the last update.


Defined Constants for Buffers

As of release 12.0, VTScada has full support for Unicode (UTF-8). ASCII constants remain supported for legacy purposes.

The following constants are defined at the \System layer. In code that parses user-input strings, you should use these constants rather than creating your own buffers for common key values or key combinations.

Buffer constants for ASCII codes
Name of Constant | Contents | Description
BS | MakeBuff(1, 8) | Backspace key
CR | MakeBuff(1, 13) | Carriage return
CRLF | Concat(CR, LF) | CR/LF pair
ESC | MakeBuff(1, 27) | Escape key
FF | MakeBuff(1,12) | Form feed
LF | MakeBuff(1, 10) | Line feed
NULL | MakeBuff(1, 0) | Null byte
TAB | MakeBuff(1, 9) | Tab key
CtrlBraceOpen | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBC)) | Ctrl and [
CtrlBraceClose | Concat(MakeBuff(1, 253), MakeBuff(1, 0x39)) | Ctrl and ]
UpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x48)) | Up arrow key
DownArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x50)) | Down arrow key
LeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4B)) | Left arrow key
RightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4D)) | Right arrow key
AltLeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9B)) | Alt and left arrow
AltRightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9D)) | Alt and right arrow
SUpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB8)) | Shift and up arrow
SDownArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xC0)) | Shift and down arrow
PageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0x49)) | Page up key
PageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0x51)) | Page down key
HomeKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x47)) | Home key
EndKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x4F)) | End key
DeleteKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x53)) | Delete key
SPageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB9)) | Shift and page up
SPageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0xC1)) | Shift and page down
SHomeKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB7)) | Shift and home
SEndKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBF)) | Shift and end
CtrlPageUp | Concat(MakeBuff(1, 253), MakeBuff(1, 0x84)) | Ctrl and page up
CtrlPageDown | Concat(MakeBuff(1, 253), MakeBuff(1, 0x76)) | Ctrl and page down
CtrlHome | Concat(MakeBuff(1, 253), MakeBuff(1, 0x77)) | Ctrl and home
CtrlEnd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x75)) | Ctrl and end
CtrlBKey | MakeBuff(1, 2) | Ctrl and B
CtrlCKey | MakeBuff(1, 3) | Ctrl and C
CtrlDKey | MakeBuff(1, 4) | Ctrl and D
CtrlIKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xB5)) | Ctrl and I
CtrlMKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBA)) | Ctrl and M
CtrlPKey | MakeBuff(1, 16) | Ctrl and P
CtrlSKey | MakeBuff(1, 19) | Ctrl and S
CtrlTKey | MakeBuff(1, 20) | Ctrl and T
CtrlUKey | MakeBuff(1, 21) | Ctrl and U
CtrlVKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x06)) | Ctrl and V
CtrlXKey | MakeBuff(1, 24) | Ctrl and X
CtrlYKey | MakeBuff(1, 25) | Ctrl and Y
CtrlZKey | MakeBuff(1, 26) | Ctrl and Z
Buffer constants for non-ASCII codes
AltEnter | Concat(MakeBuff(1, 253), MakeBuff(1, 0x32)) | Alt and Enter
AltUpArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0x98)) | Alt and up arrow
SLeftArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBB)) | Shift and left arrow
SRightArrow | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBD)) | Shift and right arrow
F2 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3C)) | F2
F3 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3D)) | F3
F4 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3E)) | F4
F5 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3F)) | F5
ShiftF2 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x55)) | Shift and F2
ShiftF3 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x56)) | Shift and F3
ShiftF4 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x57)) | Shift and F4
ShiftF5 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x58)) | Shift and F5
STab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x09)) | Shift and Tab
CtrlTab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x94)) | Ctrl and Tab
CtrlShiftTab | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9C)) | Ctrl, Shift and Tab
CtrlMinus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2A)) | Ctrl and -
CtrlPlus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2D)) | Ctrl and +
CtrlShiftMinus | MakeBuff(1, 0x1F) | Ctrl, Shift and -
CtrlShiftPlus | Concat(MakeBuff(1, 253), MakeBuff(1, 0x2E)) | Ctrl, Shift and +
CtrlNumAdd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x90)) | Ctrl and Numpad +
CtrlNumSubtract | Concat(MakeBuff(1, 253), MakeBuff(1, 0x8E)) | Ctrl and Numpad -
CtrlNumMultiply | Concat(MakeBuff(1, 253), MakeBuff(1, 0x36)) | Ctrl and Numpad *
CtrlShiftNumAdd | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9A)) | Ctrl, Shift & Numpad +
CtrlShiftNumSubtract | Concat(MakeBuff(1, 253), MakeBuff(1, 0x96)) | Ctrl, Shift & Numpad -
AltNumMultiply | Concat(MakeBuff(1, 253), MakeBuff(1, 0x37)) | Alt & Numpad*
WinContext | Concat(MakeBuff(1, 253), MakeBuff(1, 0xE8)) | Context Menu Key
CtrlTilde | Concat(MakeBuff(1, 253), MakeBuff(1, 0x26)) | Ctrl and ~
CtrlShiftBraceOpen | Concat(MakeBuff(1, 253), MakeBuff(1, 0xBE)) | Ctrl, Shift and [
CtrlShiftBraceClose | Concat(MakeBuff(1, 253), MakeBuff(1, 0x3A)) | Ctrl, Shift and ]
Ctrl0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x72)) | Ctrl and 0
CtrlNum0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x92)) | Ctrl and Numpad0
Alt0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x81)) | Alt and 0
AltNum0 | Concat(MakeBuff(1, 253), MakeBuff(1, 0x9E)) | Alt and Numpad0
CtrlShiftNKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x08)) | Ctrl, Shift and N
CtrlShiftVKey | Concat(MakeBuff(1, 253), MakeBuff(1, 0x05)) | Ctrl, Shift and V


VTScada Color Palette

Colors in VTScada have been specified using RGB values since the release of version 10.2. In this format, colors are written as a set of four pairs of hexadecimal numbers within both quotation marks and angle brackets: "<FF00FF00>" { green }. The first pair sets the opacity (alpha channel), followed by Red, Green, Blue.

Prior to version 10.2, the color palette (shown following) provided the full range of colors available for use.

All VTScada functions that require a color value will still recognize numbers from the color palette. Use the following chart as a guide when selecting which number to use.

VTS color palette


VTScada Constants and Public Variables

The following constants and public variables may be used in your code where convenient. To use, precede with a backslash (\pi).

Public Variables (Read-Only)

\AppTitle | The title of the application.
\AreaList

A dictionary of all tag areas in use. Note the following:
- Area names are stored as the keys of the dictionary, not the values.
- The list is not limited by realm filtering; the dictionary includes all areas in the application.
- Areas no longer in use are not removed from the list until the application restarts.

\RunOnly | True if this is a run-time only application.
\ActiveTheme | The name of the active color theme. (For example, "Electric Blue")
\OEMGUID | GUID for this application's OEM layer.
\AppStartupComplete | TRUE when the application has completely loaded and is running normally.
\DataPath | Full path to the application's Data folder.
\TraceFilesPath | Full path to the folder holding the application's trace files.
\WorkingCopyPath

Full path to the application's source or configuration files under version control, which should not be directly modified without using the correct configuration management APIs. This is usually the ".sync" folder within an application's folder structure.

The folder holding the application can be obtained by removing the "\.sync" portion of the string returned by this variable.

Constants

Geometry
Constant PI = 3.14159265358979; |
Text
Constant CR = MakeBuff(1, 13); | Carriage return
Constant LF = MakeBuff(1, 10); | Line feed
Constant CRLF = Concat(CR, LF); | CR/LF pair
Constant ESC = MakeBuff(1, 27); | Escape key
Time |
Constant SecInMin = 60; | Number of seconds in a minute
Constant MinInHr = 60; | Number of minutes in an hour
Constant SecInHr = 3600; | Number of seconds in an hour
Constant MinInDay = 1440; | Number of minutes in a day
Constant SecInDay = 86400; | Number of seconds in a day
Constant SecInWeek = 86400*7; | Number of seconds in a week

This is a partial list; the full list is not documented.


Color Theme Definition

You can add your own color themes to VTScada. These are stored in the Setup.INI file, within the [Themes] section.

Themes are defined by numeric values for Hue, Saturation, Brightness and Contrast in that order, following the theme name. The scale for those values is based on the tools that were available at the time that themes were introduced, and do not use plain HSL values. For reference, note that the Plum theme with values of 0,1,1,1 is the base color.

White is not an available option for any theme. Beyond the technical challenge of configuring a white theme, there is also the fact that many fonts used in relation to the theme are hard-coded as white and therefore would be invisible against a white background.

For example:

[Themes]
Theme = Gray,0,0,1.1,1
Theme = Navy,-15,2,0.7,1
Theme = Burgundy,110,2,0.5,1

Hue ranges from -180 to +180 and represents the departure from the color <FF343468> (a shade of purple).

Color saturation, brightness and contrast all range from zero to four.

The following example describes the best available method for defining a new theme.

  1. Open the Idea Studio and add a grayscale image to the page.
    The choice must be an image, not a widget or shape.
  2. Open the properties dialog for the image.
  3. Click the Adjust button to open the Adjust Image dialog.
  4. Use the Colorize control to set the base color of the image to RGB value FF343468. (Red 53, Green 52, Blue 104, Opacity 255)
  5. Drag the Hue and Saturation sliders until the color of the sample image changes to approximately what you want.
  6. Drag the Brightness and Contrast sliders to make fine adjustments to the sample image.
  7. Note the values for Hue, Saturation, Brightness and Contrast in order.
  8. Edit your Setup.INI file to add a new entry.

Remember that you will need to stop all your applications and restart VTScada itself before changes to Setup.INI take effect.

Dialog appearance may change slightly over time.
The fundamental controls remain the same.

For example, after adding the following line to Setup.INI and restarting VTScada

Theme = AutumnGlow,151.5,3.72,1.58,2.18

The new theme will look like so:

VAM using a new theme

The resulting theme.


Constants for System Colors

The following constants should be used in place of their numeric values for any function that will accept a system color designation. To use, add \System\ before each:

 ztext(50,60, "Hello",\System\#SYSCOLOR_ACTIVETEXT, 0);
Constant | Value
#SYSCOLOR_SCROLLBAR | -2
#SYSCOLOR_DESKTOP | -3
#SYSCOLOR_ACTIVEBAR | -4
#SYSCOLOR_INACTIVEBAR | -5
#SYSCOLOR_MENUBACK | -6
#SYSCOLOR_WINBACK | -7
#SYSCOLOR_WINFRAME | -8
#SYSCOLOR_MENUTEXT | -9
#SYSCOLOR_WINTEXT | -10
#SYSCOLOR_ACTIVETEXT | -11
#SYSCOLOR_ACTIVEBORDER | -12
#SYSCOLOR_INACTIVEBORDER | -13
#SYSCOLOR_MDIBACK | -14
#SYSCOLOR_SELECTEDBACK | -15
#SYSCOLOR_SELECTEDTEXT | -16
#SYSCOLOR_BUTTONFACE | -17
#SYSCOLOR_BUTTONSHADOW | -18
#SYSCOLOR_GRAYEDTEXT | -19
#SYSCOLOR_BUTTONTEXT | -20
#SYSCOLOR_INACTIVETEXT | -21
#SYSCOLOR_BUTTONHLITE | -22


Custom Help Files

You might want to provide your own documentation for pages, tags and widgets that you create. There are three ways to do this:

  • Create a CHM file using any help authoring tool. CHM files are generally considered a deprecated technology but they still work.
  • VTScada's documentation sets aside 100 help key references that you can use by creating your own UserHelp101.htm topics. These must be created in a text editor using a template supplied with the VTScada documentation.
  • You can purchase a copy of Madcap Flare and create your own documentation.

Limitations:

  • The VTScada documentation will not see your documentation. It is not possible to add links from our documentation to yours. It is not possible for our search to find your topics.
    You are welcome to add links from your topics back to the VTScada documentation, which can be done simply by pointing a URL at the file location: C:\VTScada\VTSHelp\Default.htm

Process for using Madcap Flare:

  1. Obtain a copy of Madcap Flare and use it to build your help project, with the output type set to HTML5. A SideNav template is recommended.
  2. As you create CSH values in your project's alias file, create mapping IDs that are between 5000 and 10000. This will avoid conflicts with VTScada's help ID numbering system.
  3. After building your project, copy the output folder structure to the VTScada installation folder.
    (For example, if your project is named "CustomHelp", copy the output to "C:\VTScada\CustomHelp".)
  4. Open the Application Configuration dialog to the Edit Properties tab, Advanced Mode and add the following.
    Note that the value must match your folder name followed by the key word \MadCapWebHelp as shown.

  5. Click OK to save OEMHelp.
  6. Search for the property, HelpFile.
  7. Copy that property to your application, changing the value to CustomHelp\MadCapWebHelp.
    ("CustomHelp" is the example used here - use the name of your own folder.)
  8. Save the property and close the Application Configuration dialog.

Custom Help from a page

  9. To call your documentation from a page add the following line to the Main state of that page (using a text editor to edit the source code of that page. See: Scripting)
  • SetHelp(Self(), \OEMHelp, 101);
  • Where 101 is replaced by your help ID number.
  10. In the VAM, select Import File Changes for your application. Import File Changes Tool
  11. Open your page. Press F1. View your documentation topic.

Custom Help from a tag

  12. For any tag that should use a page from your documentation, open the properties dialog and set the Help Search Key value to the appropriate CSH value from your documentation project.

Custom Help from the properties dialog of a custom widget

You have two options for adding custom documentation to a widget. You can either hardcode a direct reference in the widget's .SRC file using the constant #HelpFileName or you can define an application property and reference this property in the .SRC file of the widget. This second option is more flexible when working with multiples.

Option 1 - #HelpFileName

  13. Go to the .SRC file of the custom widget. This is located in .../VTScada/YourAppName/Widgets. Open this file in a text editor.
  14. You must define two new constants in the parameter field. To do this you will type in two lines of code and save the changes:
constant #HelpID = 1234;
constant #HelpFileName = "YourHelpFolderName\MadCapWebHelp";

where #HelpID = the appropriate CSH value from your documentation project and #HelpFileName is your folder name followed by the key word \MadCapWebHelp as shown.
Yours may look something like this:

The image displays text widget code with two added constants declared.
In this example, the additions are indicated by a green bar, lines 9 and 10.

Option 2 - #HelpFileSetting

  13. Navigate to your application configuration, Edit Properties > Advanced. Insert a new property. Give the property a name of your choosing and set the value as your folder name followed by the key word \MadCapWebHelp:

    Click OK
  14. Go to the .SRC file of the custom widget. This is located in .../VTScada/YourAppName/Widgets. Open this file in a text editor.
  15. You must define two new constants in the parameter field. To do this you will type in two lines of code and save the changes:
  16. constant #HelpID = 1234;
constant #HelpFileSetting = "YourPropertyName";

  17. where #HelpID = the appropriate CSH value from your documentation project and #HelpFileSetting is the Application property you have added.
    Yours may look something like this:

In this example, the additions are indicated by a green bar, lines 9 and 10.

Technically, you do not need to configure OEMHelp and HelpFile to add custom help to a custom widget. It doesn't hurt, but it isn't necessary. If you are ONLY adding custom help to a custom widget, you can skip those initial steps.

You can also addWinButton calls to your page, coded to call the SetHelp function when selected.

Process for using the 100 ID values in the VTScada documentation:

Overview:

One hundred mapping ID values have been set aside in the VTScada help system, which you can use to link to topics you create. You can use these ID values with your pages or with individual tag instances. When an operator presses F1 while viewing your page, or right-clicks on a tag-linked widget and opens the Help option, your topic is displayed.

You must create the topic files, using the provided template as a guide. Working within the VTSHelp\Content\UserTopics folder, copy CustomHelpTemplate.txt to CustomHelp100.txt. Each copy must be named according to the pattern, "CustomHelp100.txt" where the numeric portion of the name (100 in this example) matches the ID value set aside for the topic. You will use that ID number for your page or tag. One hundred ID values have been set aside, therefore your topics will be named, "CustomHelp100.txt" through "CustomHelp199.txt".

While you can have any heading that you like within your topic, the menu system will continue to show the existing names. There is no way to change this that is both easy and failure-proof.

Your content cannot be added to the search feature of the documentation.
Your topics are displayed only in response to an F1 request.

Edit your topic files:

  1. Assuming that you have installed VTScada in the folder, C:\VTScada, navigate to the folder, C:\VTScada\VTSHelp\Content\UserTopics.
  2. Copy the file, UserTopicTemplate.htm to UserTopicN.htm where N is a number from 100 to 199.
    Start with UserTopic100.txt and work through the set in order.
  3. Use a text editor, or a web page editor to open the new file, UserTopic100.txt
    Do not use MS Word, or any other word processing program that will add its own formatting characters.
  4. Search for the keyword, "+++Start"
    The first 300 or so lines in the topic are required to load the CSS files, JavaScript, menu and other parts of the VTScada help system. Do not edit anything before "+++Start".
  5. Replace the text between the <H1> header tags. Do not use headers other than <H1>.
  6. The content that you are replacing includes HTML tags and CSS style tags that show styles used in the VTScada help system. You should use these as needed for your own text and images.
    All the text from "+++Start" through to "end---", should be replaced.
    "+++Start" and "end---" should be removed.
  7. Save your file.

To link a tag to a user topic you created:

  1. Select the topic file and note the numeric portion of the name.
  2. Open the tag properties dialog and enter the number from the topic into the Help Search Key field of the ID tab.
  3. Close the tag properties dialog.
  4. To test, right-click on any widget linked to the tag, then click on "Help" in the menu that opens. The matching topic should open in your default browser.

To link a page to a user topic:

  1. Select the topic file and note the numeric portion of the name.
  2. Open the source code of the page to link to this topic.
  3. In the Main state, add the following line of code, replacing the number with the one from the file.
SetHelp(Self(), \DevHelpFile, 101);
  4. Click the Import File Changes button for this application in the VAM.

If creating a custom CHM-format help file:

You will need to obtain a third-party help authoring tool that can produce .CHM format help files.

Topic mapping ID values are created within that help authoring tool and assigned to topics there. VTScada's numbering system begins at 10,000. In addition, values 100 through 5000 are reserved. To avoid any conflict with the VTScada ID values, create mapping IDs that are between 5000 and 10000.

  1. Copy the .CHM file to the VTScada installation folder, not to the application folder.
  2. Use the advanced mode of the Edit Properties dialog to create a local copy of the property, HelpFile.

Link tags to topics in a custom CHM-format help file:

  • Open the properties dialog of a tag instance.
  • Set the Help Key property to the value of topic mapping id withing your help file, matching a topic to the tag.

Operators can now right-click on widgets linked to that tag, then click Help in the menu that appears, to view your topic.

Link pages to topics in a custom help file

To create a link between your page and a topic in a custom help file, edit the page's source code, then import file changes. You can define the help file and a specific topic for any page by adding the following line within the module's Main state:

SetHelp(Self(), Help File Name, Mapping ID value);

Replace the parameter, "Mapping ID value" with the ID value in your help file that matches the topic to open when an operator presses F1. Replace the help file name parameter using the same rules as for the HelpTopic application property:

  • If using the CHM format, set the parameter to the name of the file, including the extension. It is assumed that you will store the file in the VTScada installation folder, not in the application folder.
  • If using the Dot-Net help format, set the parameter to "MyHelpFolder\NetHelp", replacing "MyHelpFolder" with the name of the folder you created to store the help files within. Include the quotation marks.
  • If using the HTML5 format, set the parameter to "MyHelpfolder\MadCapWebHelp", again replacing "MyHelpFolder" with the name of the folder you created to store the help files within. Include the quotiation marks.
  • If using a UserTopic that you have edited in the VTScada help system, set the parameter to \DevHelpFile. Do not add quotation marks.


Override Help Calls for VTScada Pages

Refer to Custom Help Files for notes on how to use your own documentation with your applications.

You can override the default F1 call from most VTScada pages by setting an application property with an alternate ID for each page. When set, the help call will look first in your linked documentation for that ID value.

Any or all of the following properties can be added to the [System] section of your Settings.Dynamic file. They have no default values.

Page | Application Property
Alarm Page | HelpIDOverrideAlarmPage
Historical Data Viewer Page | HelpIDOverrideHDVPage
Lift Station Page | HelpIDOverrideLSPage
Operator Notes Page | HelpIDOverrideOperatorNotesPage
Recipes Page | HelpIDOverrideRecipePage
Reports Page | HelpIDOverrideReportPage
Services Page | HelpIDOverrideServicePage
Site Details Page | HelpIDOverrideSiteDetailsPage
Site List Page | HelpIDOverrideSiteListwMapPage
Site Map Page | HelpIDOverrideSiteMapPage
Thin Client Monitor Page Also overrides the help call from the Thin Client Monitor application. | HelpIDOverrideVICMonitorPage


User Topic Template

+++Start User Topic Template

Copy this template to a new file. Name that new file, UserTopicN.htm, where N is a number between 100 and 199. You are advised to start with 100 and proceed in order as you create new topics.

Using a text editor, or a webpage editor, remove the first header (User Topic Template) and replace all the text between (and including) "+++Start" and "end---" with your own. The three plus signs before start and the three minus signs after end can be used as markers to help you locate the section to replace. Do not change anything before "+++Start". Do not edit your file with a word processing program such as Word®, because those will add their own formatting codes.

For the header, use only the H1 style, not H2, etc.

The help ID that maps to this topic matches the number in file name. Thus, if this is UserTopic101.htm, the help ID is 101. You can use that number in the Help Search Key field of any tag, or you can add it to a page using the following code:

SetHelp(Self(), \DevHelpFile, 101);

Your topics will not be found by a search, nor will they be added to the index or the table of contents. The search engine uses java script file snippets, which are stored in the Data folder. There is no method for adding new topics to that folder of the VTScada Help system after it has been installed.

Examples of the CSS markup styles that are often used in the VTScada help system are provided:

This is a note.

This is a code example.
Use HTML line breaks <br /> between lines of code rather than paragraph marks. <p>...</p>
      Indents can be achieved with ordinary spaces.

This is a link to the Find Help page, Find Help. Note the relative path used in the link.

This is a sub heading.

Images should be stored in the folder ..\Content\Resources\Images. In general, image file names should correspond to the .HTM file in which they be displayed. Use an expanding image only where the image size is large enough to interrupt the flow of text on the screen.

Description using class "Figure".
It and the image are in a div named "ImagesNoFloat".
"div.ImagesFloatLeft" and "div.ImagesFloatRight" are also available.

Descriptive Lists

Thing 1

Description of thing 1

Thing 2

Description of thing 2

Tables use a style named "ClearTbl"

Title 1 | Title 2 | Title 3
First row | First row | First row
Alternate row | Alternate row | Alternate row

End---


Database Type Codes used in the ODBC Manager

The following numeric values are used by various functions in the library to select formatting characteristics appropriate to each database type.

Value | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase


Date Formatting Codes

Viewing: Reference > Date Formatting Codes

Concepts:

Time and Date

VTScada and Time Zones

Reference:

Date Formatting Strings

Time Formatting Codes

Time Formatting Strings

Date Formatting Codes

Use any of the following numeric date codes to format a data as shown. If you require a custom format, you can build one using the text codes shown in Date Formatting Strings.

Dates using these codes will always be displayed in English, regardless of system configuration.

All examples showing Monday, August 13, 2012.

Use only the number in the first column - the second two describe the result of the code in the first column. They are not codes that you can use in the function.

Date Code | Example | Description
0 |  | no date
1 | 120813 | yyMMdd
2 | 08/13/12 | MM/dd/yy
3 | 08-13-12 | MM-dd-yy
4 | Aug 13, 2012 | MMM d, yyyy
5 | August 13, 2012 | MMMM d, yyyy
6 | 13 Aug 12 | dd MMM yy
7 | 13 Aug 2012 | dd MMM yyyy
8 | 13/08/12 | dd/MM/yy
9 | 13-08-12 | dd-MM-yy
10 | 13Aug12 | ddMMMyy
11 | 13Aug2012 | ddMMMyyyy
12 | Aug 13/12 | MMM d/yy
13 | 20120813 | yyyyMMdd
14 | 08/13 | MM/dd
15 | 08-13 | MM-dd
16 | 08/12 | MM/yy
17 | 08-12 | MM-yy
18 | 08/2012 | MM/yyyy
19 | 08-2012 | MM-yyyy
20 | Aug 13 | MMM d
21 | August 13 | MMMM d
22 | Aug 2012 | MMM yyyy
23 | August 2012 | MMMM yyyy
24 | 13/08 | dd/MM
25 | 13-08 | dd-MM
26 | Aug | MMM
27 | August | MMMM
28 | 12-08-13 | yy-MM-dd
29 | 12/08/13 | yy/MM/dd
30 | 2012-08-13 | yyyy-MM-dd
31 | 2012/08/13 | yyyy/MM/dd
32 | 12-W35-01 (1) | yy-WeekOfYear-DayOfWeek (2)
33 | 12/W35/01 | yy/WeekOfYear/DayOfWeek
34 | 2012-W35-01 | yyyy-WeekOfYear-DayOfWeek
35 | 2012/W35/01 | yyyy/WeekOfYear/DayOfWeek
36 | 12226 | yyDayOfYear
37 | 2012226 | yyyyDayOfYear
38 | 12-226 | yy-DayOfYear
39 | 12/226 | yy/DayOfYear
40 | 2012-226 | yyyy-DayOfYear
41 | 2012/226 | yyyy/DayOfYear
42 | Mon, 13 Aug 2012 | ddd, d MMM yyyy

(1) Week Of Year is preceded by the character W.

(2) "DayOfWeek" and "WeekOfYear" are descriptions rather than format codes that you could use.
Day of week always counts 1 for Monday and 7 for Sunday. There are no properties to change this.

Related information:

Time Formatting Codes - Use for displaying time.

Date - The function that uses the codes listed above.


Date Formatting Strings

Viewing: Reference > Date Formatting Codes > Date Formatting Strings

Concepts:

Time and Date

VTScada and Time Zones

Reference:

Date Formatting Codes

Time Formatting Codes

Time Formatting Strings

Date Formatting Strings

To build a custom data format, assemble the following format codes into text strings. Format codes are case-sensitive. Text strings are always enclosed in double quotation marks.

Dates using these formatting strings will be displayed in the language of the user's locale.

Before building a date format with these strings, review the list of Date Formatting Codes.

Format Code | Description
"d" | Day of month as digits with no leading zero for single-digit days.
"dd" | Day of month as digits with leading zero for single-digit days.
"ddd" | Day of week as a three-letter abbreviation.
"dddd" | Day of week as its full name.
"g" | B.C. or A.D.
"M" | Month as digits with no leading zero for single-digit months.
"MM" | Month as digits with leading zero for single-digit months.
"MMM" | Month as a three-letter abbreviation.
"MMMM" | Month as its full name.
"y" | Year as last two digits, but with no leading zero for years less than 10.
"yy" | Year as last two digits, but with leading zero for years less than 10.
"yyyy" | Year represented by full four digits.

Example:

Date(Today(), "dddd MMM dd, yyyy")

... yields, "Thursday Aug 28, 2008"

Related information:

Time Formatting Strings - Use for displaying time.

Date - The function that uses the codes listed above.


Date and Time Phrase Keys

Language file phrase identifier keys for date and time labels

DateFmtFileName | yyyy-MM-dd
DateFmtFullNumeric | yyyy-MM-dd
DateFmtFullWritten | "MMM d, yyyy"
DateFmtFullWrittenWithDOW | "ddd MMM dd, yyyy"
DateFmtMonthDay | MMM d

TimeFmtFileName | HH-mm-ss
TimeFmtHM12Hour | hh:mm tt
TimeFmtHM24Hour | HH:mm
TimeFmtHMS12Hour | hh:mm:ss tt
TimeFmtHMS24Hour | HH:mm:ss
TimeFmtMS | mm:ss
TimeFmtWithMilliseconds | HH:mm:ss.fff


Event Log Messages - Event ID 1001

VTScada can write to the Windows Event Log when needed. The following table contains a complete list of the defined messages.

Type | Terminal? | Message
Info | N | VTS Service successfully installed.
Warning | N | %s certificate error 0x%08X detected
Warning | N | %s TLS error 0x%08X detected (%d) for IP %s
Warning | N | A collision has been detected. The tag "%0" already has a variable "%1".
Warning | N | A module or variable with the same name already exists
Warning | N | A temporary cache cannot be loaded from persistent records
Warning | N | A temporary cache cannot be saved to persistent record
Warning | N | Addition of account failed
Warning | N | Alarm notifications may not occur since this workstation isn't on the AlarmNotification server list
Warning | N | An external update changed data in the current dialog - dialog has been closed, losing any unsaved changes.
Warning | N | An external update changed the page/widget being modified. The ""Group"" action has been aborted
Warning | N | Application Conversion Failure.
Warning | N | Application is not currently allowing editing.
Warning | N | Attempt to start an editing module while another editing module is running.
Warning | N | ChangeSet cannot be applied to this application as it came from a different application.
Warning | N | ChangeSet reading error.
Warning | N | Compilation error attempting to copy OEM page source to application.
Warning | N | Compilation error attempting to copy widget source to application.
Warning | N | Compilation error in tag parameter snapshot expression
Warning | N | Conflict encountered during repository merge.
Warning | N | Could not apply ChangeSet
Warning | N | Could not create ChangeSet.
Warning | N | Could not integrate changes into running application.
Warning | N | Could not persist tag changes
Warning | N | Could not read ChangeSet file
Warning | N | Could not read repository file.
Warning | N | Could not start the application due to repository corruption in its OEM layer.
Warning | N | Could not start the application due to repository corruption.
Warning | N | Deletion of account failed
Warning | N | Duplicate Parameter Name
Warning | N | Duplicate Section in Settings file
Warning | N | Duplicate View Name
Warning | N | Error creating application directory
Warning | N | Error creating application directory backup during repository clash recovery.
Warning | N | Error creating type
Warning | N | Error encountered writing to file.
Warning | N | Errors found while Reading Language File
Warning | N | Failed to add OAuth 2.0 Grant
Warning | N | Failed to add OAuth 2.0 Provider
Warning | N | Failed to create a ChangeSet
Warning | N | Failed to create application from ChangeSet
Warning | N | Failed to delete OAuth 2.0 Grant
Warning | N | Failed to delete OAuth 2.0 Provider
Warning | N | Failed to get UDP extension
Warning | N | Failed to load application test's layer.
Warning | N | Failed to load group file
Warning | N | Failed to modify OAuth 2.0 Grant
Warning | N | Failed to modify OAuth 2.0 Provider
Warning | N | Failed to save group file
Warning | N | Failed to set variable in page or widget file.
Warning | N | Failed to update parameter list.
Warning | N | Failed to update widget tag type list.
Warning | N | Failed to write records for %s
Warning | N | Failure to apply a directly deployed change
Warning | N | Failure to discard User Copy changes.
Warning | N | Failure to import changes from the User Copy.
Warning | N | Failure to import tag database
Warning | N | Failure to revert the local change set.
Warning | N | File cannot be opened/is read-only
Warning | N | File protection failure: Unable to resolve a protected file
Warning | N | Get from workstation failed. Workstation could not complete transfer of application.
Warning | N | Hash checksum failed for
Warning | N | Illegal attempt to change the hash count on a tag type
Warning | N | Illegal View Name
Warning | N | Import Error
Warning | N | Incomplete Parameters
Warning | N | Invalid class
Warning | N | Invalid path name
Warning | N | Invoked Unsupported System: Edit Lockout Manager.
Warning | N | Layer GUID not found
Warning | N | Layer has been prematurely activated
Warning | N | Layer settings load failure
Warning | N | Layer state inconsistent
Warning | N | License does not support RPC servership - client connection rejected.
Warning | N | Merge of a repository revision vector failed
Warning | N | Microsoft Excel was not detected on the host machine
Warning | N | Missing or damaged file in repository.
Warning | N | Missing or damaged file in repository.
Warning | N | Missing or damaged file in repository.
Warning | N | Modification of account failed
Warning | N | Module "HandleLayerEvent" needs a Return statement.
Warning | N | MultiSpeak Registration Failed
Warning | N | Nested SetEditing call.
Warning | N | New tag type not properly counted
Warning | N | ODBCTables failed to retrieve a table list.
Warning | N | OEM Not Found
Warning | N | Only one driver type with a unique challenge is allowed per application.
Warning | N | Operational Change Failed.
Warning | N | Phrase ID Has No Translations
Warning | N | PIN for SIM card failed
Warning | N | Platform information failed to record
Warning | N | POINTS Database failed to load.
Warning | N | POINTS Database failed to write.
Warning | N | Property recording failure.
Warning | N | Reload failed - error retrieving application from other machine.
Warning | N | Repository corruption detected, attempting repair.
Warning | N | Repository file corrupted.
Warning | N | Repository revision not found
Warning | N | RPC service lists in INI files are no longer supported. RPC service disabled.
Warning | N | SCT Database failed to load.
Warning | N | Security provider application not found.
Warning | N | Server communication failure. Get From Workstation aborted. Is workstation still reachable?
Warning | N | Set property failure.
Warning | N | SIM card PINs appear misconfigured
Warning | N | SNMP Agent Configuration Warning
Warning | N | Tag Address Error
Warning | N | Tag exceeds VTScada's tag nesting limits - tag will not run
Warning | N | Tag Export Failed - Could not find a data conversion table for this DSN
Warning | N | Tag Import Failed - Could not find a data conversion table for this DSN
Warning | N | Tag Import Failed - Database improperly formatted
Warning | N | Tag Import Failed - Invalid parameters
Warning | N | Tag internal ID collision
Warning | N | Tag name collision
Warning | N | Tag name duplicates a module or a variable name
Warning | N | Tag name length exceeds limit of 253 characters
Warning | N | Tag Recording Failure.
Warning | N | Tag Start Failure
Warning | N | Tag Storage Failure.
Warning | N | Tag type module lacks a Refresh function
Warning | N | Tag unique ID collision
Warning | N | Temporary tags cannot be persisted to disk
Warning | N | The application automatic deploy setting could not be set.
Warning | N | The attempt to update the user copy failed.
Warning | N | The maximum number of tags permitted by this VTScada installation is %0.
Warning | N | The parent parameter provided is not a tag object
Warning | N | The Restricted Tag code is incorrect for this workstation.
Warning | N | The server list file for this application is corrupt
Warning | N | The tag cache cannot reset because the application is not allowing editing.
Warning | N | This ChangeSet contains source code but the application is RUN file only.
Warning | N | This function should only be called when the Working Copy lock is held by the caller, see help for details
Warning | N | Tried to load an Application with the same GUID as an existing Application.
Warning | N | Type cannot be updated to include children of its own type. Tag(s) not included in update.
Warning | N | Type contains disallowed variable or parameter name. Remove specified variable or parameter or use an earlier version of VTScada.
Warning | N | Unable to generate report
Warning | N | Unable to open the requested document file for editing.
Warning | N | Unable to start: Application may have been modified using an evaluation license
Warning | N | Undo record prepared but not committed. Undo history for edited file has been discarded.
Warning | N | Ungroup failed.
Warning | N | Unsupported module
Warning | N | Working copy lock not acquired with write permission.
Warning | N | Working copy lock released when not acquired.
Warning | N | WorkingCopy.version file corrupted. Attempted automatic repair.
Error | N | Allocation failure during COM processing:
Error | N | Attempted to operate on a COM object before system initialization
Error | N | Attempted to operate on a COM object before system initialization
Error | N | Click Target Failure\nUnable to generate COM handling procedure
Error | N | COM Initialization Failure. Code: 0x
Error | N | COM STA Thread exception
Error | N | Deeply nested internal value truncated
Error | N | Deeply nested variable %s truncated
Error | N | Error converting size_t to DWORD when writing to registry
Error | N | Exception from DefWindowProc
Error | N | Exception when attaching event sink:
Error | N | Exception when creating AX object:
Error | N | Exception when getting property:
Error | N | Exception when getting type info:
Error | N | Exception when invoking:
Error | N | Exception when releasing AX object
Error | N | Exception when releasing COM object
Error | N | Exception when releasing event sink:
Error | N | Exception when setting property:
Error | N | Exception while processing COM message
Error | N | Failed to allocate COM worker thread
Error | N | Failed to connect to COM Object:
Error | N | Failed to create COM object instance. Error Code: 0x"
Error | N | Failed to gather type information from the COM Object. Error Code 0x
Error | N | Failed to resolve CLSID for COM Object:
Error | N | Failure to allocate COM wrapper object:
Error | N | Function no longer supported: MakeFixedBuff
Error | N | Object Capture Failure\nCOM object unload exception - OS resources lost
Error | N | Out of Memory: Image data transfer failed.
Error | N | Stream length down-cast overflow
Error | N | Text Render Failed [hr=%X]
Error | N | The performance counter registry hive is corrupted. Some WorkstationStatus functions may not work.
Error | Y | "%s" not found in Printer List
Error | Y | AVL Tree Bad Balance Factor
Error | Y | AVL Tree Unbalanced
Error | Y | bad count
Error | Y | COM worker reference error
Error | Y | DDE getSchedulerLock() called without DDESema held.
Error | Y | Exceeded limit on number of handles
Error | Y | Failed to create SQL environment
Error | Y | Failed to install VTScada Service - conflicting service is already registered and could not be removed.
Error | Y | Failed to install VTScada Service - could not connect to Service Control Manager.
Error | Y | Failed to install VTScada Service - could not locate executable.
Error | Y | Failed to install VTScada Service - could not register service process.
Error | Y | Failed to install VTScada Service - could not set service start delay.
Error | Y | Failed to install VTScada Service - the user could not be given service logon privilege
Error | Y | Failed to instantiate VTScada service.
Error | Y | Failed to load %s. %s
Error | Y | Failed to register ODBC Window class
Error | Y | Failed to register PPP Window class
Error | Y | Failed to register VTScada service message handler.
Error | Y | Failed to set Ivona Voice Automation DCOM permission, this component may not operate for the VTScada service.
Error | Y | Failed to set Trihedral VTS OPC Server DCOM permission, this component may not operate for the VTScada service.
Error | Y | Failed to set Trihedral VTS OPC Server DCOM service, this component may not operate for the VTScada service.
Error | Y | Failed to set VTSODBC32 DCOM permission, this component may not operate for the VTScada service.
Error | Y | Historian Schema Limit
Error | Y | ID: 0xXXXX - Deleting Free Memory
Error | Y | ID: 0xXXXX - Deleting Unallocated Memory
Error | Y | ID: 0xXXXX - Out of Memory
Error | Y | ID: 0xXXXX - Used memory in free list
Error | Y | Illegal value attributes setting Array
Error | Y | Illegal value attributes setting Retained
Error | Y | Illegal value attributes setting Shared
Error | Y | Image data deleted with a negative reference count
Error | Y | Image data deleted with references pending
Error | Y | Invalid runfile path in rootdir:
Error | Y | LOAD variable reference too long
Error | Y | Lost VTable pointer during breakpoint
Error | Y | Modifying orphans list without lock
Error | Y | PARAMETER::save - Unknown WEB op code
Error | Y | Path name too long:
Error | Y | Run file cannot be opened:
Error | Y | SAVE variable reference too long
Error | Y | Task not found
Error | Y | Text Services Failed to Start [%X]
Error | Y | Thread allocation failed.
Error | Y | Trying to create an unknown DAG
Error | Y | Trying to create DAG opcode 0
Error | Y | Unable to allocate Scheduler TLS storage
Error | Y | Unable to allocate WEB_THREAD* TLS storage
Error | Y | Unable to determine Operating System
Error | Y | Unable to get Scheduler data from TLS
Error | Y | Unable to get Scheduler data from TLS on STA thread marking
Error | Y | Unable to get Scheduler data from TLS on thread termination
Error | Y | Unable to start in single copy mode
Error | Y | Unable to store Scheduler data in TLS
Error | Y | Unknown default value type
Error | Y | Unknown message sent to VTScada Service: 0x
Error | Y | Unknown WEB parameter op code


Fill Patterns

The following numbers may be used in functions requiring a fill pattern value.

Index | Pattern | Example
1 | Solid |
2 | Even color mix |
3 | Dominant background color mix |
4 | NW-SE diagonals |
5 | NE-SW diagonals |
6 | Vertical lines |
7 | Horizontal lines |
8 | Vertical squiggles |
9 | Horizontal squiggles |
10 | Vertical jagged lines |
11 | Horizontal jagged lines |
12 | Diagonal jagged lines |
13 | Vertical crosshatch |
14 | Vertical and angled crosshatch |
15 | Angled crosshatch |
16 | Uneven crosshatch |
17 | Hollow connected squares |
18 | Checkerboard |
19 | Vertical arrows |
20 | Horizontal arrows |
21 | Angled checkerboard |
22 | Large dots |
23 | Thick connected squares |
24 | Squares with tiny dots |
25 | Bricks |


Font Character Sets

Returns the VTScada character set as an actual charset code. You may disregard these legacy presets and use the actual codes directly (see wingdi.h for list).

0 | ANSI_CHARSET
1 | DEFAULT_CHARSET (Current system charset. Typically, the same as ANSI_CHARSET)
2 | SYMBOL_CHARSET
3 | SHIFTJIS_CHARSET
4 | OEM_CHARSET (System specific)
5 | RUSSIAN_CHARSET
6 | BALTIC_CHARSET
7 | CHINESEBIG5_CHARSET
8 | EASTEUROPE_CHARSET
9 | GB2312_CHARSET
10 | GREEK_CHARSET
11 | HANGUL_CHARSET
12 | MAC_CHARSET
13 | TURKISH_CHARSET
14 | VIETNAMESE_CHARSET


GUI Object Return Codes

Objects created using the GUIx commands will return a value when selected by the mouse or the enter button, according to the following table:

Return Value | Mouse Button(s)/Key | No. of Clicks
0 | Invalid response | -
1 | Right button | Single
2 | Middle button | Single
3 | Right and middle button | Single
4 | Left button | Single
5 | Left and right button | Single
6 | Left and middle | Single
7 | All three buttons | Single
8 | Invalid response | -
9 | Right button | Double
10 | Middle button | Double
11 | Right and middle button | Double
12 | Left button | Double
13 | Left and right button | Double
14 | Left and middle | Double
15 | All three buttons | Double
16 | <ENTER> key | -

These are built from the following bit-wise values:

Bit | Meaning
0 | TRUE: Right button clicked
1 | TRUE: Middle button clicked
2 | TRUE: Left button clicked
4 | TRUE: Double-click, FALSE: Single-click
5 | TRUE: Enter key presses (all other bits will be zero)


Historian Error Codes

Historian functions will return a zero on success. On error, they will return either a numeric value or a STRUCT, where the structure is more common. The STRUCT will contain the following:

ErrorCode\ErrorCode - the numeric error code
ErrorCode\ErrorText - Optional text describing the error
ErrorCode\ErrorTime - UTC timestamp when the error was generated

The caller of the Historian function should wait for Valid(ErrorCode). The typical coding pattern is as follows:

HistorianSomeFunction(....., ErrorCode);
...
If Valid(ErrorCode);
[
  IfElse(True(ErrorCode == 0),
    ... success
  { Else }
    ... fail - error number is PickValid(ErrorCode\ErrorCode, ErrorCode)
  );
]

Defined error codes:

Constant | Value | Notes
HISTORIAN_SUCCESS | 0
HISTORIAN_ERROR_INVALID_PARAMETER | 1
HISTORIAN_ERROR_UNKNOWN_CONNECTION_TYPE | 100001
HISTORIAN_ERROR_ILLEGAL_GETDATA_QUERY | 100002
HISTORIAN_ERROR_STORAGE_LOCKED 100003

The account under which you are now running VTScada does not have the permissions granted to the account under which you were previously running VTScada.

Use Windows tools to change ownership of the locked files. This is most likely to happen when storage is located in a folder outside the VTScada installation.

HISTORIAN_ERROR_RECORDS_DO_NOT_EXIST | 100004 | the records requested do not exist in storage according to the sequence counters
HISTORIAN_ERROR_CONNECTION_FAILED | 100005
HISTORIAN_ERROR_RECORD_READ_FAILURE | 100006 | the records requested should exist in storage, but there was an error retrieving them
HISTORIAN_ERROR_RECORD_WRITE_FAILURE | 100007
HISTORIAN_ERROR_STORAGE_INCONSISTENT_WITH_SEQUENCE_COUNTER | 100008
HISTORIAN_ERROR_FIELD_DOES_NOT_EXIST | 100009
HISTORIAN_ERROR_RECORD_DELETION_FAILURE | 100010
HISTORIAN_ERROR_INITIALIZATION_FAILURE | 100011
HISTORIAN_ERROR_SCHEMA_PERSIST_FAILURE | 100012
HISTORIAN_ERROR_FAILED_TO_LAUNCH_THREAD | 100100


Known Path Aliases for File-Related Functions

Known Path Alias | Location
:{CommonProgramFiles} | Common program files (varies for 32-bit and 64-bit operating systems)
:{Fonts} | Fonts folder
:{ProgramFiles} | program files directory (varies for 32-bit and 64-bit operating systems)
:{System} | Windows System folder (varies for 32-bit and 64-bit operating systems)
:{SystemX86} | Windows System folder (32bit)
:{Windows} | Windows folder
:{ResourceDir} | Windows Resources folder
User Specific |
:{UserAdminTools} | Admin tools (start menu)
:{UserRoamingAppData} | Roaming app data
:{UserCDBurnArea} | Local pending CD to burn
:{UserCookies} | IE cookies
:{UserDesktop} | Desktop folder
:{UserFavorites} | IE favorites
:{UserHistory} | IE history
:{UserInternetCache} | Temporary internet files
:{UserLocalAppData} | Localized app data
:{UserDocuments} | Documents folder
:{UserMusic} | Music folder
:{UserPictures} | Photos folder
:{UserVideos} | Videos folder
:{UserNetHood} | Network Places shortcut folder
:{UserPrintHood} | Printer shortcut folder
:{UserProfile} | Users profile folder (root of users folders)
:{UserPrograms} | Programs (start menu)
:{UserRecent} | Shortcuts to recently viewed documents
:{UserSendTo} | Items in the 'Send To' context menu
:{UserStartMenu} | Start menu root
:{UserStartup} | Start menu startup folder
:{UserTemplates} | Document templates
All Users share the following: |
:{CommonAdminTools} | admin tools (start menu)
:{CommonAppData} | app data storage
:{CommonFavorites} | IE favorites folder
:{CommonOEMLinks} | OEM Links
:{CommonPrograms} | start menu program list
:{CommonStartMenu} | start menu root
:{CommonStartup} | start menu startup folder
:{CommonTemplates} | templates folder
:{PublicDesktop} | desktop folder (shared icons, etc...)
:{PublicDocuments} | documents folder
:{PublicMusic} | music folder
:{PublicPictures} | photos folder
:{PublicVideos} | video folder


Line Types

The following numbers may be used in functions requiring a line style value.

Index | Style | Example
0 | Invisible |
1 | Solid |
2 | Dashed |
3 | Dotted |
4 | Dot-dashed |
5 | Dot-dot-dashed |


ParameterEdit Snap ins

Viewing: Reference > ParameterEdit Snap ins

ParameterEdit Snap-ins

These modules are accessories toParameterEdit

ParameterEdit is used for handling the value of a parameter in the user interface. Snap-Ins are modules that can be paired with ParameterEdit to identify the type of parameter value to be edited along with parameters specific to that use case.

How to Use Snap-Ins

  1. Use the name of the snap-in module in the Modules Array parameter of ParameterEdit.
    (such as, Modules[0] = "ParmEditColor")
  2. Parameters needed for all uses of ParameterEdit (like ParmVal, ParmPtr, Enable) are to be configured in ParameterEdit. Do not include them in your array.
  3. Parameters specific to the snap-in go into the Parameters array.

The Parameters array might look something like this:

Modules[1] = "ParmEditExprNoNormalize";
Parameters[1] = New(4);             {allocates memory for an array, specifies a size 4, for 4 parms}
Parameters[1][0] = 0b1001;          {MenuEnables}
Parameters[1][1] = ContainerInfo;   {ContainerInfo}
Parameters[1][2] = #VTypeFont;      {TargetType}
Parameters[1][3] = "FontValue";     {TargetSubType}

The first 11 parameters in the snap-in (Expr, ParmPtr, Enable, Left, Bottom, Right, Top, LabelWidth, LabelHeight, PtrWaitClose, DlgRoot) are configured in ParameterEdit so they are no included in the array.

ParameterEdit Wrappers

VTScada has a growing catalog of ParameterEdit Wrappers. These are modules that are like ParameterEdits that have already been partially configured. Before making your own customized ParameterEdit-- Check out our wrapper options!

AlignmentParameterEdit | NumericParameterEdit
ColorParameterEdit | TagParameterEdit
DurationParameterEdit | TextParameterEdit
MultiCheckboxParameterEdit | TimestampParameterEdit
Closed ParmEditColor - Choose a Color

First, check out the wrapper ColorParameterEdit. It might save you some leg work!

Description | Used for choosing a color as your parameter value.
Required Parameters | None
Parameters | Color - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - (Unused) Root of the edit dialog. ID - Focus ID QuoteTrueColor - Deprecated DisableAlpha - Flag TRUE to disable alpha field
Closed ParmEditColorNone - Choose Invalid for Color
Description | Used for choosing an Invalid color as your parameter value.
Required Parameters | None
Parameters | Color - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width HideTitle - TRUE to hide the title over the control PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - (Unused) Root of the edit dialog. ID - Focus ID
Closed ParmEditColorSS - For Displaying a Color from a StyleSetting Tag
Description | Used to display a color from a Style Setting tag
Required Parameters | None
Parameters | Color - Parameter value ParmDef - Parameter defining structure Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width HideTitle - TRUE to hide the title over the control PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - (Unused) Root of the edit dialog. ID - Focus ID StyleSettings - StyleSettings tag object StyleSettingName - Name of the style setting to use
Closed ParmEditDateTime - Choose a Timestamp Value
Description | Used for choosing a time stamp value. It expects and returns timestamps in UTC, and converts them to the clients local time zone for display and edit.
Required Parameters | None
Parameters | TimestampVal - Parameter value (expected in UTC) ParmDef - Parameter definition structure Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width HideTitle - TRUE to hide the title over the control PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - (Unused) Root of the edit dialog. ID - Focus ID InitialTime - Optional. The number of seconds since midnight of Jan 1, 1970. Default = current time. 24HourEditing - Optional. True for 24 hour clock. Default = False. TimeOnly - Optional. When set to TRUE, only time will be displayed. Defaults to FALSE
Closed ParmEditDuration - Choose a Duration of Time
Description | Used for choosing a duration of time as your parameter value. It consists of a numeric entry field to enter a multiplier, and a drop-list of time units (Days, Weeks, Months, etc) to choose from.
Required Parameters | None
Parameters | DurationVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width HideTitle - TRUE to hide the title over the control PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - (Unused) Root of the edit dialog. ID - Focus ID DefaultMultiplier - Default multiplier DefaultUnit - Default unit SingleValueParm - TRUE to display a Single Value option. Default = TRUE AllowInvalidParm - TRUE to allow an invalid entry (no duration entered, "Set Duration" button will be displayed). Default = FALSE MaxFiveYearsParm - TRUE to limit duration values to five years. Default = TRUE
Closed ParmEditDroplist - Choose a Value Using a Droplist
Description | Allow a value to be changed using a droplist.
Required Parameters | None
Parameters | ParmVal - Parameter value ParmDef - Parameter definition structure Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width HideTitle - TRUE to hide the title over the control PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - (Unused) Root of the edit dialog. ID - Focus ID ParmValues - List of values ParmLabels - List of labels or PhraseIDs IsText - TRUE if the values are text, FALSE if numeric (Default).
Closed ParmEditExprMovement - Choose an Expression for a Movement Parameter
Description | Used for choosing an expression as your parameter value for a movement parameter
Required Parameters | DropListLabel0, DropListLabel1, ContainerInfo, DefMin, DefMax
Parameters | Expr - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) DropListLabel0 - Label 0 for the Movement direction drop-list DropListLabel1 - Label 1 for the Movement direction drop-list ContainerInfo - Information structure for Container and its parameters DefMin - Default minimum value DefMax - Default maximum value
Closed ParmEditExprNormalize - Choose an Expression, Wrapped in Normalize
Description | ParameterEdit module for choosing an expression as your parameter. The result is wrapped in a Normalize.
Required Parameters | MenuEnables, ContainerInfo
Parameters | Expr - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) MenuEnables - Bits to enable options for expression editor bit 0 - Tag Browser bit 1 - Color Selector bit 2 - Gradient Selector bit 3 - Function Selector and Editor ContainerInfo - Information structure for Container and its parameters
Closed ParmEditExprNoNormalize - Choose an Expression, Without Normalize
Description | Used for choosing an expression as your parameter. Note that, the result is not wrapped with a Normalize.
 | MenuEnables, ContainerInfo, TargetType, TargetSubType
Parameters | Expr - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) MenuEnables - Bits to enable options for expression editor bit 0 - Tag Browser bit 1 - Color Selector bit 2 - Gradient Selector bit 3 - Function Selector and Editor ContainerInfo - Information structure for Container and its parameters TargetType - Optional value type allowed for this parameter. Defaults to double. TargetSubType - Optional list of subtypes for Object type.
Closed ParmEditFont - Choose a Font

ParmEditFont differs from others. You will need to add an element to your Modules array with the value of "ParmEditFont".
The Parameters array can have an Invalid entry for the matching element.

Description | Used by the ParameterEdit to choosing a Font as your parameter value. See note at the beginning of this article.
Required Parameters | BrowserObj
Parameters | FontVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID BrowserObj - Output: Set to the instance of the Tag Browser opened by the SelectObject control.
Closed ParmEditHorizAlign - Choose a Horizontal Alignment
Description | ParameterEdit module for choosing horizontal alignment as your parameter value.
Required Parameters | None
Parameters | HAlign - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID
Closed ParmEditLineStyle - Choose a Line Style
Description | ParameterEdit module for choosing a line style as your parameter value
Required Parameters | None
Parameters | Style - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID
Closed ParmEditLineWidth - Choose a Line Width
Description | ParameterEdit module for choosing a line width as your parameter value
Required Parameters | None
Parameters | Width - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID
Closed ParmEditNum - Choose a Numeric Value

First, check out the wrapper NumericParameterEdit. It might save you some leg work!

Description | ParameterEdit module for choosing a number as your parameter value
Required Parameters | TypeOfValue, MinVal, MaxVal, IsSpinBox
Parameters | NumVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) TypeOfValue - Optional, VTScada value type required MinVal - Optional, Min value allowed (Max also required) MaxVal - Optional, Max value allowed (Min also required) IsSpinBox - Optional, set TRUE to display as a spinbox.
Closed ParmEditNumSlider - Configure a Numeric Slider Bar or Optional Edit Field
Description | ParameterEdit module for choosing a number as your parameter value using a slider bar or optional edit field.
Required Parameters | MinVal, MaxVal, EnableEditField
Parameters | NumVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width HideTitle - set TRUE to hide the title over the control PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID MinVal - Optional, Min value allowed (Max also required) Default 0 MaxVal - Optional, Max value allowed (Min also required) Default 100 EnableEditField - Optional, set FALSE to disable the edit field. Default TRUE.
Closed ParmEditParmMovement - Get Info for Displaying the Movement Parameter
Description | ParameterEdit module for choosing a container's parameter as a value. Used for displaying the Movement parameter. Has all the additional information needed for the Movement GUI call
Required Parameters | ContainerInfo, DropListLable0, DropListLabel1, DefMin, DefMax
Parameters | ParmVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ContainerInfo - Info struct for the container and its parameters DropListLabel0 - Droplist label 0 DropListLabel1 - Droplist label 1 DefMin - Default minimum value DefMax - Default maximum value
Closed ParmEditParmValue - Choose a Container's Parameter as a Value

Due to the introduction of PickValids for default parameters, this selector must appear in the modules array before any of the expressions.

Description ParameterEdit module for choosing a container's parameter as a value.
Required Parameters ContainerInfo, TargetTypeLo, TargetTypeHi, SubTypeList, Scaled, DefaultValue, DefaultNoParm, TargetMin, TargetMax, Translate
Parameters ParmVal - Parameter value
ParmPtr - Parameter pointer
Enable - Show the graphics for editing the parameter value
Left - Left coordinate
Bottom - Bottom coordinate
Right - Right coordinate
Top - Top coordinate
LabelWidth - Label width
LabelHeight - Label weight
PtrWaitClose - TRUE to tell caller to wait to close
DlgRoot - Root of the edit dialog (for sizing)
ContainerInfo - Info struct for container and its parameters
ValueTypeLo - Min value type allowed for this parameter. Note - If ValueTypeHi is invalid, then this is the only value type allowed.
ValueTypeHi - Max value type allowed for this parameter
SubTypeList - Optional list of subtypes for object type
Scaled - Optional Boolean to indicate whether the data be in a "Scale" expression. The default is FALSE
DefaultValue - Optional. The default value if the parameter's value is invalid
DefaultNoParm - Optional. The default value if no parameter is selected
TargetMin - Target minimum value
TargetMax - Target maximum value
Translate - Boolean. Set TRUE if the output should be wrapped in \GetPhrase.
Closed ParmEditPageVariable - Get a Variable Name
Description | ParameterEdit module takes a variable name as a parameter and proffers it when selected.
Required Parameters | None
Parameters | VariableVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width HideTitle - TRUE to hide the title over the control PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID VarName - The name of the page variable to use.
Closed ParmEditPattern - Choose a Fill Pattern as a Parameter Value
Description | ParameterEdit module for choosing a fill pattern as your parameter value
Required Parameters | NoTransparentBrush
Parameters | Brush - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID NoTransparentBrush - Boolean. Set FALSE to show a "no pattern" selection. Defaults to TRUE.
Closed ParmEditPipeColor - Choose a Pipe Color as a Parameter Value
Description | ParameterEdit module for choosing a pipe color as your parameter value
Required Parameters | None
Parameters | HighColor - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID
Closed ParmEditPipeWidth - Choose a Pipe Width as a Parameter Value
Description | ParameterEdit module for choosing a pipe width as your parameter value
Required Parameters | None
Parameters | PipeWidth - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID
Closed ParmEditTag - Choose a Tag as a Parameter Value

First, check out the wrapper TagParameterEdit. It might save you some leg work!

Description | Parameter Editing module for choosing a tag as your parameter value
Required Parameters | PointType, BrowserObj, DefaultText, MissingText
Parameters | TagParm - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the Parameter Value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label weight PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) PointType - Point Type allowed for this parameter BrowserObj - Output: Set to the instance of the Tag Browser opened by the SelectObject control.
Closed ParmEditTagMovement - Choose a Tag Value for a Movement Parameter
Description | Parameter Editing module for choosing a tag value as your parameter value for a Movement parameter
Required Parameters | DropListLabel0, DropListLabel1, PointType, DefMin, DefMax, BrowserObj
Parameters | TagMoveVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) DropListLabel0 - Label 0 for the movement direction drop-list DropListLabel1 - Label 1 for the movement direction drop-list PointType - Point Type allowed for this parameter DefMin - Default minimum value DefMax - Default maximum value BrowserObj - Output: Set to the instance of the Tag Browser opened by the SelectObject control.
Closed ParmEditTagProperty - Choose a property of a Drawn Tag

Due to the introduction of PickValids for default parameters, this selector must appear in the Modules array BEFORE any of the Expressions

Description | ParameterEdit module for choosing a property of the drawn tag.
Required Parameters | ContainerInfo, TargetTypeLo, TargetTypeHi, TargetSubTypes, Scaled, DefaultValue, DefaultNoTag, TargetMin, TargetMax
Parameters | ParmVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (for sizing) ID - Focus ID ContainerInfo - Info struct for container and its parameters TargetTypeLo - Min value type allowed for this parameter. If TargetTypeHi is Invalid, then this is the only value type allowed. TargetTypeHi - Max value type allowed for this parameter TargetSubTypes - Optional list of subtypes for object type Scaled - Should this value be scaled? DefaultValue - Optional, default value if the tag's value is invalid DefaultNoTag - Optional, default value if user selects 'No Property Selected' TargetMin - Target minimum value TargetMax - Target maximum value
Closed ParmEditTPMovement - Choose a Container's Parameter as a Value
Description | ParameterEdit module for choosing a container's parameter as a value
Required Parameters | DropListLabel0, DropListLabel1, ContainerInfo, DefMin, DefMax
Parameters | ParmVal - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (for sizing) DropListLabel0 - Label 0 for the movement direction drop-list DropListLabel1 - Label 1 for the movement direction drop-list ContainerInfo - Info structure for container and its parameters DefMin - Default minimum value DefMax - Default maximum value
Closed ParmEditTagValue - Choose a Tag Value as a Parameter Value
Description | ParameterEdit module for choosing a tag value as your parameter value
Required Parameters | PointType, Scaled, DefaultValue, DefaultNoTag, TargetMin, TargetMax, BrowserObj
Parameters | TagParm - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) PointType - Point type allowed for this Parameter Scaled - Optional Boolean value indicating whether the data should be in a Scale expression. Default = true DefaultValue - Optional, default value if the tag's value is invalid DefaultNoTag - Optional, default value if no tag is set
Closed ParmEditVertAlign - Choose a Vertical Alignment
Description | ParameterEdit module for choosing vertical alignment as your parameter value.
Required Parameters | None
Parameters | VAlign - Parameter value ParmDef - Parameter defining structure Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width HideTitle - TRUE to hide the title over the control PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID Mode - 0 = values are 0, 3, 6 (Default). 1 = values are 0, 1, 2
Closed ParmEditText - Choose Text as a Parameter Value

First, check out the wrapper TextParameterEdit . It might save you some leg work!

Description | ParameterEdit module for choosing a text string as your parameter value
Required Parameters | Translate, PageName
Parameters

TextMsg - Parameter value
ParmPtr - Parameter pointer
Enable - Show the graphics for editing the parameter value
Left - Left coordinate
Bottom - Bottom coordinate
Right - Right coordinate
Top - Top coordinate
LabelWidth - Label width
LabelHeight - Label height
PtrWaitClose - TRUE to tell caller to wait to close
DlgRoot - Root of the edit dialog (UNUSED)

FocusID - Focus ID
Obsolete - No longer used.

Translate - Integer indicating whether the output should be wrapped in \GetPhrase.
0 - Use text as it is entered
1 - Use PhraseID wrapped in GetPhrase()
2 - Use PhraseID not wrapped in GetPhrase()

PageName - Which page we set this text parameter for. Mandatory for editing a subordinate page (name in the form of <SubordinateApplicationTagName\PageNameOnSubordinateApp>) so that any text parameter entered can save its phrase identifier key on subordinate application.
Leave INVALID when editing the parameters of a widget.

Closed ParmEditTextExpression - Choose an Expression to Return Text as a Parameter Value

Related to ParameterPanel, described elsewhere in this topic.

Description | ParameterEdit module for choosing an expression that returns text as the parameter Value.
Required Parameters | MenuEnables, ContainerInfo
Parameters | Expr - Parameter value ParmPtr - Parameter pointer Enable - Show the graphics for editing the parameter value Left - Left coordinate Bottom - Bottom coordinate Right - Right coordinate Top - Top coordinate LabelWidth - Label width LabelHeight - Label height PtrWaitClose - TRUE to tell caller to wait to close DlgRoot - Root of the edit dialog (UNUSED) ID - Focus ID MenuEnables - Bits used to enable options for the expression editor bit 0 - Tag Browser bit 1 - Color Selector bit 2 - Gradient Selector bit 3 - Function Selector and Editor ContainerInfo - Info structure for Container and its parameters

Parameter Panel

The parameter panel is a generic panel that will handle the setting of Parameters for an object that does not have its own panel.

The object can be a page or a widget. If available, hints are taken from the typing information of the object parameters and suitable Parameter Value choosers are offered.

If the immediate container has parameters then, these too are considered as actual value candidates. However, if there is type information on the object or the container, then these hints are used to filter the set of options, possibly resulting in an empty set.

This panel is designed to be callable from several sources, such as the VGE and the Display Manager.

Closed ParameterPanel Parameters

This is not a snap-in. It is a wrapper of ParameterEdit.

Parameters ObjModule - Object module that is to have its parameters modified
pObjParams - Pointer to an array of the object's parameter values
PtrWaitClose - TRUE when window closed or cancel pressed
CodePtr - CodePtr so that the parameter value can be read
Left - Left position of the window
Bottom - Height of window
Right - Width of the window
Top - Top position of the window
HandleScrollBar - Flag - TRUE for this module to use a scrollbar if required
ContainerInfo - Information about container and its parameters
SelectedParms - Boolean array of selected parameters to make editable
DialogRoot - The calling dialog window
GetWidthFromDescriptions - Optional. If TRUE, the larger of Description or Name is used to determine the space required.
AllowAdvancedParams - Optional. Allows advanced parameter configuration. This will change which options are available for editing parameters.
PageName - Which page the parameter is set for. Mandatory for editing a subordinate page (name in the form of <SubordinateApplicationTagName\PageNameOnSubordinateApp>) so that any text parameter entered can save its phrase identifier key on subordinate application. Leave invalid when editing the parameters of a widget.


Report Types Described

VTScada provides a variety of predefined report types, which you can use to analyze the performance of the equipment comprising your physical system. Your application might also have been created with additional, customized report types.

Use the Report Type drop-down list at the top of the Report page to select one of the options listed here. After you choose a report type, the filters in section (2) of the Report page will automatically adjust to display only the type of tags that can be included in the selected report type.

Closed Analog Summary Report

An Analog Summary Report displays the average, minimum, maximum, and total values for a set of selected analog tags within a configured time period.

When using this report to summarize flow data, set the Application Property, AnalogSummaryReportTimeUnits to the time unit used to measure the flow. If flow is measured in units per second, the property must be set to 1. If flow is measured in units per minute, the property must be set to 60.

When this report is selected, the tag list will be filtered to include only Analogs.

The Analog Summary Report includes the following information:

  • The station number associated with each tag in the selected set.
  • The description configured for each tag in the selected set.
  • The I/O address for each tag in the selected set.
  • The average of the tag's data within the duration set for the report.
  • The minimum tag data reading within the duration set for the report.
  • The maximum tag data reading within the duration set for the report.
  • The total tag data reading within the duration set for the report.
Closed Daily Snapshot Report

A daily snapshot report displays a "snapshot" of the value of each included tag, at the time you specify, on the dates you select.

When a daily snapshot report is generated, it contains a report header that identifies the report as a daily snapshot report, and indicates the duration or time period you configured for the report. For example, if at 2:00 pm you select a series of tags, set the time period to Last Week, and run the report, the daily snapshot report will display the value of each tag at 2:00 pm for the last 7 days.

The daily snapshot report will include:

  • The date at which the data for each tag was read
  • The time at which the data for each tag was read
  • The subsequent columns provide a snapshot of the value for the tags you selected for inclusion in this report at the corresponding date and time

For example:

Sample daily snapshot report

Closed Daily Total Report

A daily total report displays the sum of the values accumulated for each member of a selected set of tags each day within the time period you specify. The key word is "accumulate". Do not use with analogs that measure fluctuating values such as flow rates or levels. A better choice is a counter that increments whenever an event occurs such as a pump start or rain-gauge tip.

If the count restarts or rolls over each time a maximum value is reached (the bucket is filled and then empties to fill again) the total will be the number of rollovers times the maximum value, plus the difference between the last value recorded and the first value recorded.

The report has no way to specify that maximum or rollover value, therefore it is essential that it be configured correctly in all the tags included in the report. Typically, the report uses the tag's ScaledMax parameter as the rollover value. However, if it is an IO tag, the Display Range Max is used if it is valid, defaulting to ScaledMax otherwise. If it is an Analog Status tag, the High Scale Value is used if it is valid, defaulting to ScaledMax. Note that an IO tag in Calculation mode always has an invalid ScaledMax, so Display Range Max must be set.

The report header identifies this as a daily report and includes the duration or time period of the report. Information included in the report includes:

  • The date on which the data for each tag was read
  • The time at which the data for each tag was read
  • The subsequent columns display the total data accumulated for each tag you selected for inclusion in this report at the corresponding date and time
Closed Derived Flow Report

A Derived Flow Report displays the number of cycles for a driver, along with the inflow, outflow, and total flow for the station.

For this report, the tag selection area will be filtered to include drivers. The report must be run on a Polling Driver or Data Flow RTU, with at least one Pump Status tag. Tied to the Polling Driver, there must be an Analog Status with a description of "Well Volume" measured in gallons, that the well pumps in each cycle. This is usually the volume between the lead and stop float switches. This data must be entered in the manual data field of the Analog Status tag.

  • Information in the Derived Flow Report includes:
  • The station number associated with each VTScada driver tag.
  • The description configured for each VTScada driver tag.
  • The number of cycles for each VTScada driver tag.
  • The inflow for each station.
  • The outflow for each station.
  • The total flow for each station.

The Derived Flow report requires a measurement of the volume of the station (i.e. the total volume (in gallons) that the well pumps in each cycle.

Closed Detail Report

A Detail Report shows the values recorded for each selected tag, within the given time period.

For this report, the tag selection area will be filtered for the type, Loggers.

The Detail Report includes the following information:

  • A date and time stamp for each tag's data.
  • The name of each tag.
  • The value of each tag.
  • The description of each tag.
Closed Driver Communication Error Detail Report

A driver communication error detail report shows driver error activity, recorded over a specified time period.

Information included in this report includes:

  • The date at which the error was read.
  • The time at which the error was read.
  • The % quality of data for each driver within the specified time period.
  • The delta success for each driver within the specified time period.
  • Any error values for each driver within the specified time period.
  • Any error messages for each driver within the specified time period.

Note that this report does not allow you to select multiple time periods.

If you select multiple tags, the report for each will be saved to a separate sheet if Excel is used for the output format.

Further information about these values is included elsewhere in this guide, see Communication Driver Log-Enabled Variables.

Closed Driver Communication Summary Report

A driver communication summary report provides a history of driver activity for a specified time period.

For this report, the Types drop-down list filters to display Drivers.

This report includes three groups of information:

  • Driver quality information
    • The % minimum quality of data for each driver within the specified time period.
    • The % maximum quality of data for each driver within the specified time period.
    • The % start quality of data for each driver within the specified time period.
    • The % end quality of data for each driver within the specified time period.
    • The tag name for each driver tag included in the report.

Quality is calculated based on a weighted time interval. Communications closer to the present have more importance than those further in the past. The quality is a running analog value that can be trended on the historical data viewer. Sudden dips in the graph indicate periods where problems occurred. By comparing the % start quality to the % end quality for a given time frame, you can determine whether events that occurred during that time improved or damaged communication quality.

  • Communication timing information.
    These three values provide an indication of communications lag time and can be used to identify bandwidth issues that may be present.
    • The average Response time (i.e. the time between successive messages) for each driver within the specified time period.
    • The minimum Response time for each driver within the specified time period.
    • The maximum Response time for each driver within the specified time period.
  • Communication count information.
    These four values are actual counts recorded during the time frame. Unlike the quality information, these values ignore communications that occurred before the time frame.
    • The number of failed data transmissions for each driver within the specified time period.
    • The number of failed reattempts at data transmissions for each driver within the specified time period.
    • The number of successful attempts at data transmissions for each driver within the specified time period.
    • The % success for each driver within the specified time period. This is calculated as: (success counts) / (failed counts + success counts). The counts begin at the start of the given time frame, thus this value can be useful for hour to hour or day to day comparisons.

Note: The Delta time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Closed Hourly Snapshot Report

An hourly snapshot report displays a "snapshot" of the value of each included tag, repeated every 60 minutes within the time period you specify.

Information included in the report is as follows:

  • The date at which the data for each tag was read
  • The time at which the data for each tag was read
  • The subsequent columns indicate a "snapshot" of the value for the tags you selected for inclusion in this report at the corresponding date and time

For example:

Sample hourly snapshot report

Closed Hourly Total Report

An hourly total report displays the sum of the values accumulated for each member of a selected set of tags each hour within the time period you specify. The key word is "accumulate". Do not use with analogs that measure fluctuating values such as flow rates or levels. A better choice is a counter that increments whenever an event occurs such as a pump start or rain-gauge tip.

If the count restarts or rolls over each time a maximum value is reached (the bucket is filled and then empties to fill again) the total will be the number of rollovers times the maximum value, plus the difference between the last value recorded and the first value recorded.

The report has no way to specify that maximum or rollover value, therefore it is essential that it be configured correctly in all the tags included in the report. Typically, the report uses the tag's ScaledMax parameter as the rollover value. However, if it is an IO tag, the Display Range Max is used if it is valid, defaulting to ScaledMax otherwise. If it is an Analog Status tag, the High Scale Value is used if it is valid, defaulting to ScaledMax. Note that an IO tag in Calculation mode always has an invalid ScaledMax, so Display Range Max must be set.

The report header identifies this as an hourly report and includes the duration or time period of the report. Information included in the report includes:

  • The date on which the data for each tag was read
  • The time at which the data for each tag was read
  • The subsequent columns display the total data accumulated for each tag you selected for inclusion in this report at the corresponding date and time
Closed Overall Total Report

An overall total report displays the sum of the values accumulated for each member of a selected set of tags within the full time period you specify. The key word is "accumulate". Do not use with analogs that measure fluctuating values such as flow rates or levels. A better choice is a counter that increments whenever an event occurs such as a pump start or rain-gauge tip.

If the count restarts or rolls over each time a maximum value is reached (the bucket is filled and then empties to fill again) the total will be the number of rollovers times the maximum value, plus the difference between the last value recorded and the first value recorded.

The report has no way to specify that maximum or rollover value, therefore it is essential that it be configured correctly in all the tags included in the report. Typically, the report uses the tag's ScaledMax parameter as the rollover value. However, if it is an IO tag, the Display Range Max is used if it is valid, defaulting to ScaledMax otherwise. If it is an Analog Status tag, the High Scale Value is used if it is valid, defaulting to ScaledMax. Note that an IO tag in Calculation mode always has an invalid ScaledMax, so Display Range Max must be set.

The report header identifies this as an overall total report and includes the duration or time period of the report. Information included in the report includes:

  • The date on which the data for each tag was read
  • The time at which the data for each tag was read
  • The subsequent columns display the total data accumulated for each tag you selected for inclusion in this report at the corresponding date and time
Closed Pump Activity Report

The Pump Activity Report displays summarized values for the Pump Status tags in your application, enabling you to determine overall pump activity.

When you select Pump Activity Report, the list of tags available will include only the Pump Status tags in your application.

Information included in the Pump Activity Report includes:

The station to which the pump belongs.

  • A description of the pump.
  • The number of times the pump started for the duration set for the report.
  • The average time the pump ran within the duration set for the report.
  • The total time the pump ran within the duration set for the report.
Closed Pump Discrepancy Report

The Pump Discrepancy Report is designed to help you spot instances of pumps that should be identical in behavior, but are not. This report shows only the pumps that have a 20% or greater difference in running time or have more than 1 start count difference.

When this report is chosen, the Types drop-down list is filtered to include only Pump Status tags.

Information included in the Pump Discrepancy Report:

  • The station to which the pump belongs.
  • A description of the pump.
  • The number of times the pump started for the duration set for the report.
  • The average time the pump ran within the duration set for the report.
  • The total time the pump ran within the duration set for the report.

Only the Polling Driver tag and the Dataflow RTU Driver tag have a native field to define which station to which the pump belongs (Station Name). To run a Pump Discrepancy Report for tags nested under any other driver, you must add a custom Station Name property to a parent tag.

There are two methods for adding an inheritable custom property to a parent tag:

Add a property to a parent context tag

This is the simplest method. Create a parent context tag, navigate to the settings tab. Add a property named "stn" with the label "Station Name". Give it the value to be inherited by all child tags.

Create a custom tag type

This takes a few more steps but it is especially useful if you want to use an expression in the Station Name field.
You will need the user privilege "Manage Tag Types".
Create a context tag, give it a Name and give it a Type label like "StationParent".
Navigate to the Settings tab, and add a property named "stn" with the label "Station Name". Click OK. Right-click the tag in your tag browser and select "Create New Type"
A dialog will pop up. Keep all the defaults and click OK.
Add a new tag to your tag browser. You will find your new tag type in Containers or under All Tag Types.
You will find a Station Name field in the Other Parameters tab. All children of this tag will inherit the value of this property.

Closed Rainfall Report

The Rainfall Report provides a per-tag summary of totals within the time period configured for the report, enabling you to determine the total rainfall for selected tags in a given period.

The most common configuration is to use a Data Flow Pulse Input tag where each pulse recorded from the rainfall measuring equipment signifies a predefined depth measurement.

A Rainfall Report includes:

The station number associated with each tag.

The description given each tag.

The total rainfall for each tag.

Closed Standard Report

A standard report shows all the values logged for a tag over a chosen time span.

When using this report, it is important to choose only one tag at a time. The reason has to do with the difference between how the information is stored (a database) and how the report presents it (a spreadsheet format). For example, given two tags, A and B: values will always be logged a few milliseconds apart. The report will include a row for each unique timestamp found. However, it will not leave the column for tag A blank when showing the value logged for tag B and vice-versa. When displaying the value logged for tag A, the last value known for tag B will also be included at that timestamp. When displaying the value logged for tag B, the last value known for tag A will be included at that timestamp. For any given tag, it can be very difficult to separate the actual logged values from the carry-over to the other tag's row.

You avoid this problem by running the standard report for only one tag at a time.

Included information:

  • The date on which the value for each tag was read.
  • The time at which the value for each tag was read.
  • The raw timestamp for when the tag was read.
  • The value logged.

Related information:

Report Formats and Destinations - Output options.


Preset Time Periods for Reports

The Reporting Period section of the Reports page includes a Presets drop-down list, containing the following time periods:

Preset | Description
Last 60 minutes before trigger time | The report will include all data that has been collected over the last hour time period, ending with the current time.
Last 2 hours before trigger time | The report will include all data that has been collected over the last two-hour time period, ending with the current time.
Last 4 hours before trigger time | The report will include all data that has been collected over the last four-hour time period, ending with the current time.
Last 12 hours before trigger time | The report will include all data that has been collected over the last twelve-hour time period, ending with the current time.
Last 24 hours before trigger time | The report will include all data that has been collected over the last twenty-four-hour time period, ending with the current time.
Last 2 days before trigger time | The report will include all data that has been collected over the last forty-eight-hour time period, ending with the current time.
Last 4 days before trigger time | The report will include all data that has been collected over the last ninety-six-hour time period, ending with the current time.
Last 7 days before trigger time | The report will include all data that has been collected over the last week, ending with the current time.
Previous calendar day | The report will include all data that has been collected for the previous day, starting at midnight yesterday, and ending at midnight on the current date.
Previous calendar week | The report will include all data that has been collected for the previous week, starting at midnight seven days previous, and ending at midnight on the current date.
Previous calendar month | The report will include all data that has been collected for the previous month, starting at midnight on the first day of the previous month, and ending at midnight on the first day of the current month.
Previous calendar quarter | The report will include all data that has been collected for the previous four months, starting at midnight on the first day four months previous, and ending at midnight on the first day of the current month.
Previous calendar year | The report will include all data that has been collected for the previous year, starting at midnight on the first day of the previous year, and ending at midnight on the first day of the current year.
Current Day | The report will use all data collected from midnight until the current time today.
Current Week | The report will use all data collected from Midnight Sunday of this until the moment that the report is run.
Current Month | The report will use all data collected so far during the current calendar month.
Current Quarter | The report uses all data collected so far during the three months making up the current quarter of the year.
Current Year | The report uses all data collected so far this year.
Custom | Automatically set when you use the date or time selectors.


Specialty Pages

Pages described in this section are not included in the default VTScada menu configuration, but may be relevant to your installation.

Related information:

Communications Data Page

Lift Station Page

Station Page (Legacy)


Communications Data Page

The purpose of the Communications Data page is to display information transmitted and received between the VTScada application and the DataFlow RTUs for your entire system.

As shown, the Communications Data page displays packets of message code sent from the VTScada application to the DFS RTUs (preceded by "Send" and colored blue), and from the DFS RTUs to the VTScada application (preceded by "Reply" and colored green), along with the date and time at which each signal was transmitted or received.

Depending upon your application's configuration, the display of data on the Communications Data page may scroll quite rapidly. The Freeze/Continue toggle button at the top of the Communications Data page enables you to freeze the display so that you can have a closer look at the communications data. When you are finished reviewing the frozen display, you can hit the button again to unfreeze the display.

If you wish to view communications data for individual RTUs, click the Comm button appearing on the appropriate RTU's station page. (To open a station page, click the appropriate station symbol on the Overview page.)

Information in the Communications Data Display

The information in the Data Display follows the DFS protocol. For every blue Send message, there should be one or more green Reply messages. A Send message without a matching Reply is a clear indication of a problem preventing the station from answering.

The following figure shows an example of one Send/Reply transaction:

As shown, each Send message will be bracketed by two non-printing characters (the square boxes). Each Reply ends with a single box symbol. You should disregard these non-printing characters in the following guide to the codes.

The first two characters in each message are the address of the DFS RTU. (Again, disregard the boxes.) Looking at the examples, you should see that for every Reply following a Send, these two leading characters match.

One exception to the above is the case of a "ZZ" command in the Send message. This indicates that a group poll is being requested, starting at the address appearing in the 5th and 6th character places of the Send field. The following Replies can be seen to include a series of RTU addresses.

A second exception to the above is the case of a station with a Digipeat path. In this case, the Send will start with the address of the station it is repeating through, followed by ‘RD’ and then the station address of the RTU being polled.

The third character in the Send message is the module number. Here, "1" will mean module A, "2" means module B and so on, except for "R" which indicates a Radio module.

There is one exception to this pattern: A "0" in the third character position of the Send indicates that a Full Station Read is being requested. All modules in the station should reply with their status, where an "x" will indicate "No Change" and a "y" will indicate "Change".

Normally if a reply indicates that there has been a change, a Send request will go to that module to request its new value.

The final character in either a Send or Reply is a check-bit. This may be any printing character, including punctuation. This is the only character in either the Send or Reply that should ever have punctuation: a character other than a letter or number in any other position is a sign of communication errors.

Freezing the Communications Data Display

To temporarily freeze the communications data displayed on the Communications Data page, simply click the Freeze button. A hold will be placed on the data being displayed. This enables you to review the data closely. The Freeze button will now be labeled, "Continue". Clicking the Continue button will remove the hold from the data and cause it to revert to its regular display.

Clicking the Freeze button does not stop data from being communicated, it merely freezes the display for closer scrutiny. Data continues to be transmitted and received while the Freeze button is depressed.


Lift Station Page

This page will use the information from a Station tag to create complete monitoring and control displays for your pumping stations. The lift station page is normally opened by clicking a Site Draw widget that is linked to a station tag. The contents of this page will vary according to the type of station tag linked to it. This page may also be referred to as the Station Details Page.

If you choose to add a menu item for a Lift Station page, you must configure three parameters:

  • The station tag that will be linked to the component widgets.
  • Whether the application's color theme will be applied to the page.
  • The color to use for labels. This may be an RGB value in the form, <RRGGBB>, or it can be a numeric value as specified in the VTScada color palette.

The Station page is an assembly of various monitoring and control drawing methods for the associated station tag. Each component is described in the following sub-topics. The specifics will vary according to whether the station is a MultiSmart, MPE SC series or MPE Duplexer, but most components of the pages will be found for all types of station tag.

Closed Well Details

Includes the Well Flow and Well Plot drawing methods.

The number of pumps displayed will match the configuration of the associated Station tag. When a pump is running, it will be shown in green.

The current water level is represented by the shaded background and the numeric display. High and low alarm setpoints for the pumps are shown by the red lines with matching numeric values.

The current flow, both in and out, is displayed as well as a trend of the past 24 hours, showing well level and alarm levels.

Closed Pump Control

Provides a Hand-Off-Auto control for each pump in the station.

The label indicates whether the pump is running (displayed in green), stopped (gray) or if it will be the next to run (yellow).

Closed Station Summary

The Station Summary varies according to the type of station tag.

MultiSmart Station Summary:

For the MultiSmart Station, six operational profiles may be defined in the Setpoints tab. Profiles are used to store lead and lag setpoints to be used under varying operating conditions such as storms, drought, etc. The profile selection in the summary page shows which is active and select which to use.

If your station uses the Modbus protocol, only the profile number will be shown. If using the DNP3 protocol, you will see the profile description displayed.

Operating notes may be added using the + button. This opens the standard VTScada notebook dialog. Use these to create a permanent record of operational and maintenance tasks.

For comparison, the station summary pages for the MPE Duplexer Station and the MPE SC Station are shown in the following images. Note the lack of a Setpoints tab for the MPE Duplexer Station. The MPE SC Station has a Setpoints tab, but only a single profile.

MPE Duplexer Station Summary:

MPE SC Station Summary:

Closed Station Alarm List

Shows all current faults in the station. You may acknowledge or silence alarms with the buttons provided. A blinking indicator shows that the alarm has not received a reset, sent from the Faults tab.

Closed Station Statistics

An extensive collection of statistics is collected and displayed for each individual pump, the station as a whole, and the well.

Tabs across the top of the display provide access to different sets of statistics. The number of tabs and the statistics gathered will vary with the type of station controller.

Within any tab, statistics are grouped by item of equipment (pumps, well, station as a whole). The number of equipment items shown will vary depending on your screen size. If there is not enough room to show all items, a scroll bar will be provided so that you can select which set of statistics to view.

Closed Station Faults and Fault Reset

There are two pages within the faults tab: a list of faults, grouped by component and a set of fault reset controls.

Indicators will show red when a fault is present and green otherwise. After a fault has been reset, the corresponding alarm must still be acknowledged in VTS.

Closed Station Inputs

Provides a list of all input tags associated with the station. The list is divided into two pages - digitals and analogs (digitals shown below analogs). For the digitals, a color dot indicates the tag's value: green is used for zero, red for one and gray indicates 'no data'. The analog tags are shown with their current value.

Closed Station Controls

The station controls page provides access to all output tags in the station, grouped by digitals and analogs.

To operate a digital control, click the corresponding button. To operate an analog control, click in the appropriate field as shown, then type the new value that should be written to the station.

Closed Station Setpoints

For MPE SC Stations and MultiSmart Stations. Sample image shows the MultiSmart's Station Setpoints display.

Set the lead and lag setpoints for the pumps. One profile can be set for the MPE SC Station, while six profiles may be created for the MultiSmart, each with a different configuration of setpoints. These are provided to allow operators to quickly switch operating parameters in response to changing conditions such as an approaching rainstorm, etc. The various profiles are used only for changing the pump lead and lag setpoints. Alarm setpoints are accessed only through the Current tab of the display.

For reference, the display also shows the current depth of water in the well as a blue background.

You can adjust the setpoints using the sliders, or for greater accuracy, you may type values into the fields above each setpoint slider.

Related information:

Site Draw Widget


Station Page (Legacy)

The station page is considered obsolete, having been replaced by the newer Site Details Page.

If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your application's Settings.Dynamic file, and set the value of that property to "1".

Each time you create a new Polling Driver or a new Data Flow RTU driver tag for your application, VTScada automatically creates a station page for the new station.

Station pages are launched when the station symbol for the Polling Driver or Data Flow RTU driver tag is clicked. You may change the page that is launched when a station symbol is clicked (i.e. you may open a custom page you have created for the station) by changing the station symbol's configuration.

The following images are from VTS version 10.2. Support for legacy station pages under VTScada 11 and later is not guaranteed.


Sample Pages

VTScada comes with several sample pages. These are a set of widgets without tag links, drawn on a background of borders and tiled images.

All can be opened for editing in the Idea Studio. You can examine these pages to learn how they were built and to gain inspiration. You can also copy sections for use in your own pages.

Dashboard A

Dashboard B

Dashboard C


SQL Data Types

Viewing: Reference > SQL Data Types

SQL ODBC Types

Type Indicator | SQL Data Type
-10 | SQL_LONGUNICODE
-9 | SQL_NVARCHAR
-7 | SQL_BIT
-6 | SQL_TINYINT
-5 | SQL_BIGINT
-4 | SQL_LONGVARBINARY
-3 | SQL_VARBINARY
-2 | SQL_BINARY
-1 | SQL_LONGVARCHAR
0 | SQL_UNKNOWN_TYPE
1 | SQL_CHAR
2 | SQL_NUMERIC
3 | SQL_DECIMAL
4 | SQL_INTEGER
5 | SQL_SMALLINT
6 | SQL_FLOAT
7 | SQL_REAL
8 | SQL_DOUBLE
9 | SQL_DATE
10 | SQL_TIME
11 | SQL_TIMESTAMP
12 | SQL_VARCHAR


Time Formatting Codes

Viewing: Reference > Time Formatting Codes

Concepts:

Time and Date

VTScada and Time Zones

Reference:

Date Formatting Codes

Date Formatting Strings

Time Formatting Strings

Time Formatting Codes

Use any of the following numeric time codes to format a time as shown. If you require a custom format, you can build one using the text codes shown in Time Formatting Strings.

Time Code | Example | Description
0 |  | no time
1 | 103211 | HourMinuteSecond
2 | 10:32:11 | hour:minute:seconds
3 | 10321100 | HourMinuteSecondHundredth
4 | 10:32:11:00 | hour:minute:seconds:hundredths
5 | 10:32 | hour:minute
6 | 10:32:11 AM | hour:minute:seconds AM or PM
7 | 10:32 AM | hour:minute AM or PM
8 | 103211000 | hour minute second thousandths
9 | 10:32:11.000 | hour:minute:second.thousandths

Related information:

Time Formatting Strings - Used to display a time value.

Time- Function that uses the codes listed above.


Time Formatting Strings

Viewing: Reference > Time Formatting Codes > Time Formatting Strings

Concepts:

Time and Date

VTScada and Time Zones

Reference:

Date Formatting Codes

Date Formatting Strings

Time Formatting Codes

Time Formatting Strings

All examples display 9:07:12 p.m.

String | Example | Description
h | 9 | Hours with no leading zero for single-digit hours. 12-hour clock.
hh | 09 | Hours with leading zero for single-digit hours. 12-hour clock.
H | 21 | Hours with no leading zero for single-digit hours. 24-hour clock.
HH | 21 | Hours with leading zero for single-digit hours. 24-hour clock.
m | 7 | Minutes with no leading zero for single-digit minutes.
mm | 07 | Minutes with leading zero for single-digit minutes.
s | 12 | Seconds with no leading zero for single-digit seconds.
ss | 12 | Seconds with leading zero for single-digit seconds.
f | .1 | Tenths of a second
ff | .01 | Hundredths of a second
fff | .001 | Milliseconds
t | P | One character time-marker string, such as A or P.
tt | PM | Multi-character time-marker string, such as AM or PM.

Example:

Time(now(1), "hh.mm.ss tt")

... displays: 09.07.12 PM

Related information:

Time Formatting Codes - Used to display a time value.

Time - Function that uses the codes listed above.


VTScada and Time Synchronization

The following information is of concern only if you are not already maintaining time synchronization between servers and if it is important to your operation to maintain synchronization of clocks between servers.

VTScada includes code that will maintain time synchronization between networked servers. Due to security settings in Windows, the Time Synchronization Service will work only if VTScada is started with an account that has the SE_SYSTEMTIME_NAME security flag set. The Windows Administrator account will generally have this privilege, but you can also set it for other user accounts.

To do so, you must set the user privilege, "Change the System Time" to true using the Windows Group Policy Management Editor. Please refer to Microsoft’s documentation for instructions on using this system tool.


Using a Non English Character Set

Viewing: Reference > Using a Non English Character Set

Using a Non-English Character Set

VTScada supports Unicode (UTF-8). The information in this topic is no longer relevant except in the (unlikely) case of code that uses the TextEncode() function with no input parameter.

To display non-English characters in VTScada, you may to do the following: (Steps describe how to use a Chinese character set.)

  1. Update your Windows to include Chinese character set if you haven't done that when you install your Windows.
  2. Go to Control Panel -> Clock, Language, and Region -> Region and Language Setting.
  3. Select 'Administrative' tab and click on the "Change system Locale..." button.
  4. If the client is from Main land China, select "Chinese (Simplified, PRC)" from the droplist.

If the client is from Hong Kong, select Chinese (Traditional, Hong Kong S.A.R) and so on. The screen should look like the following after your selection.

Windows will ask you to restart your system.

  5. If you want to input Chinese characters in VTScada, you need to go to Control Panel -> Region and Language setting, select 'Keyboards and Languages" tab and click on "Change keyboards..." button.
  6. In the "Text Services and Input Languages" dialog, Add Chinese input in the "Installed services" and keep English as Default Input Language.
  7. Run VTScada and you can edit text messages, button labels or Page Notes in Chinese.

Note: tag names do not support Chinese characters.


Scripting

VTScada includes (and is largely built using) its own programming language. You can use this language to create tools for your application development work, including custom tags, reports, drivers, script applications and wizards. You can also use it to modify your application pages, user-defined tags, and user-defined widgets.

All the features you would expect in a programming language are supported, as well as many more that are unique to VTScada.

Read Me First!
From time to time, a new VTScada user (especially one coming from a programming background) will turn directly to script code to build features. The result is usually that they spend a large amount of time attempting to recreate features that already exist. As the adage says, "don't reinvent the wheel".

Even though this documentation tells you how, there are several reasons why you should NOT try to write code. In fact, the engineers at Trihedral are discouraged from using custom code in their applications unless they absolutely must. This is because applications built with standard features can be maintained by anyone forever. The responsibility of maintaining custom code falls on the person who wrote it. Forever.

It takes a significant amount of time and effort to learn to use this language well. Code written without the benefit of experience and a friendly mentor is much more likely to contain bugs or security flaws. Proceed if you will, but you have been warned.

A few notes about the VTScada language:

It is a language that makes it easier to write SCADA software. Every page, widget, tag, and tool that you've used in VTScada was written in that language. The following are a few key facts about this language:

It's an object-oriented, state-based, reactive, programming language.

That sounds like a lot of jargon, but it's not intended as a marketing pitch or to sound intimidating. Once you get the hang of it, the language is quite intuitive to read. It helps you get things done very easily that in other languages would require a lot more awkward setup and code structure.

Object-oriented

The processes that a SCADA system monitors are composed of a lot of physical things that often have similar properties and logic associated with them. For example, similar sensors or pumps. Tags are objects. An object-oriented language is a natural fit for working with physical objects.

State-driven

These objects often have continuous processes associated with them. In VTScada script, those processes match defined states. Therefore, in addition to properties and methods, our objects have a state.

These objects tend to have different behaviors under different conditions. Any object might have a set of states that it can inhabit. For example, a pump may be running or it may be stopped. When a pump is running, you need to worry about different things than when the pump is not running. Starting and stopping might be two more states. Or, a driver may be in the process of connecting to a piece of equipment, it might be fully connected, or it might be unable to connect. This is matched in code by the object inhabiting a different state for each physical circumstance.

In other languages, you may have had objects with a status variable indicating its state. Our states are not just a status variable. What is special about our states, is that each state has its own code and only one state can be active at a time within a module. It just makes things simpler to code.

Reactive

In VTScada script, it is very easy to write code that reacts to an object changing. That is what SCADA systems need to do. You could also call this event-driven, or "report by exception".

Objects in VTScada script seem more like living things compared to other languages. They almost always have a life of their own. They aren't just repositories of properties and methods. They usually are paying attention to the system around them and reacting to it.

Part of the reason for this is that we want to avoid polling. Polling is inefficient and slow. When something changes, we want to react to it as soon as possible rather than wait for a polling interval. That said, there is a lot of hardware that does not support report by exception, so a driver might need to poll that equipment. But from that point on, we can write code that reacts only to changes to that value and does so as soon as possible.

Is the VTScada scripting language "weird"?

That depends on your point of view. A line of code that begins "IF 1... " might seem unusual until you know how that function works in this language. But it still supports typical imperative, step-by-step code like you see in most other languages. For a lot of problems, most of the code is imperative, and it is also (reasonably) easy to write.


Resources, Terms, Definitions

In addition to this reference guide, the following resources are available to help you learn to write VTScada script code:

  • F1 integration and syntax highlighting are features that you should look for when selecting an editor. For example, several editors allow you to link to an external CHM help file.
    A .CHM format version of the VTScada documentation is available from Trihedral by request. With this feature configured, you can highlight any word and press F1 to open the reference notes for that word. (So long as the word is found in the index.)
  • The ability to refer to working source files for examples. Several example modules are provided for use with the VTScada scripting course.

Terms and Definitions

Comment

A comment is an explanation added to code by the programmer to clarify its purpose. Comments are used to explain why code was written the way it was or to clarify what each individual piece of a complicated block of code is for.

Comments are enclosed in braces { } and may appear anywhere. They may appear in the middle of a statement without affecting the execution of that statement. A common use of comments is to describe the purpose of each parameter in a long function call:

ZPipe(x[0], y[0] { First endpoint for pipe },
      8 { Number of vertices },
      176, 239 { Very dark gray to very light gray },
      24 { Width of pipe in pixels });

Variable, Constant

In simple terms, a variable is a named location in your PC's memory where a value can be stored. The term "variable" is used, as the value stored in the named storage location can change over time (i.e. the stored value is variable or changing).

A "constant" is exactly the same thing as a variable, except that it is defined in a way such that, after being set, it cannot be changed by later code.

Variable names can be up to 256 characters in length to allow descriptive labeling of the information that they contain. In earlier versions of VTScada, there was a limit of 16,384 variables in any given module. The limit is currently 4,194,304 variables per module.

All of the data in VTScada is stored in variables. Data values come in a variety of different types, the most common being numbers and text. VTScada also uses many other data types such as Boolean values, pointers, streams, objects and graphic values. A variable can also represent an entire collection of values stored as an array or as a dictionary.

An example showing values being assigned to variables is displayed below:

Title = "Station 009";
Color = 15;

In the preceding example, the variables specify the text and background color for a system page.

Unlike many programming languages, VTScada variables are not declared to have a specific data type. The data type is associated with the value stored by the variable so that the type can change as the value changes. This feature is called "dynamic typing". This allows you to create programs that are flexible and can simplify object-oriented coding. In a static programming language, a programmer must declare the type of each variable before compiling the code, thus making the code less flexible. The benefit of dynamic typing is that there is no need to deal with data whose type cannot be determined at compile time.

To use the value contained in a variable in a statement, you simply need to provide the name of the variable. VTScada also supports references to variables (pointers), but more about that later.

Expression

An expression is a unit of code that can produce a value. You can use the word expression to mean a statement, or a sub-unit of code within a statement. 2 + 2 is an expression.

Expressions can be created with the user-interface tools of VTScada for tag configuration parameters, the properties of graphic objects, the title of a page and more.

Statement

A statement is a command that signals VTScada to perform an action in an application, such as drawing graphics, doing mathematical functions, communicating, raising an alarm, logging data or trending. Statements are not used for tag configuration parameters, or the properties of graphic objects. They are written using a text editor when changing the code for a page, a widget, or a custom tag.

A simple statement might look like:

A = 5;

This statement sets the value of the variable "A" to "5".

Other statements have the form:

Beep(1000);

This statement passes the "Beep" function a parameter value of 1000, thereby generating a 1000 Hz tone in the internal speaker of the computer.

Statements always end with a semi-colon. They need not be written on a single line. For example, the following are two perfectly valid statements:

A = {setting the value of "A" … }
5   { … to five. };
GUIRectangle(236, 180, 280, 236,
             1, 1, 1, 1, 1 { Scaling },
             0, 0 { Movement },
             1, 0 { Visibility, scaling },
             0, 0, 0 { Selectability },
             Brush(0, 0, 1), Pen(0, 1, 1));

State

A state is a collection of statements that are grouped together within square brackets and given a name. The following is an example of a state named "Main" taken from the code for a page. When you are viewing the page, you are "in" that state.

Main [
  GUIRectangle(236, 180, 280, 236,
               1, 1, 1, 1, 1 { Scaling },
               0, 0 { Movement },
               1, 0 { Visibility, scaling },
               0, 0, 0 { Selectability },
               Brush(0, 0, 1), Pen(0, 1, 1));
  GUITransform(232, 236, 288, 180,
               1, 1, 1, 1, 1 { Scaling },
               0, 0 { Movement },
               1, 0 { Visibility, scaling },
               0, 0, 0 { Selectability },
               Variable("AI20_1")\TopBar(222, 0, 100));
  Return(Self);
  GUITransform(164, 256, 336, 168,
               1, 1, 1, 1, 1 { Scaling },
               0, 0 { Movement },
               1, 0 { Visibility, scaling },
               0, 0, 0 { Selectability },
               Variable("Library")\Bitmap(
               "Bitmaps\Tanks\Tank06.bmp", -1));
]

This particular state draws a rectangle, an analog input tag as a Top Bar, and a bitmap of a tank on a system page.

It is important to note that the order of the statements in a state does not imply the order in which they are executed. When a state becomes active, all statements within it are executed exactly once. If a value within a statement changes, that one statement will run again. For example, a tag's value increases and in response, the widget displaying that tag updates to show the new value. While the state is running (the page is visible or the pump is in a running state) all statements in a state can execute as needed in response to changing values. When the state stops running (the page is closed or the pump is stopped) those statements do not run.

Steady State

All statements within a state remain active as long as the state is active. Whenever an included variable's value changes, all statements within the state that use this variable will be re-evaluated. This condition is referred to as being in "steady state".

Because statements run only when triggered by a changing value, their order within the state generally does not matter. The order of statements in a state is significant only for pages, where the visual layering of images matches the order of the statements. Do not attempt to force an order on statement execution within a state - it's meant to work this way. However, it does take some care: X = X + 1; is effectively an infinite loop in steady state. (Each time the value of X changes, the statement containing that variable runs again.)

The statements within the state are referred to as "steady state statements". This is an important distinction when referring to VTScada's extensive function library. Many functions can only be used in steady state, while others cannot ever be used in this mode.

Note that all functions that can be used in Steady State can also be used in a tag expression, although many are not useful there.

Script Blocks

A script block is a collection of statements that are executed in order from first to last (or according to loops and conditions) and do not re-evaluate when variables referenced in the statement change. This is in contrast to statements in steady-state. In a script block, X = X + 1; just adds 1 to the value of X.

Scripts are created by enclosing a set of statements within a "script block" (indicated by square brackets) that in turn are preceded by an If statement. The If statement and the logical expression that it evaluates, serve as the trigger for the script. When the logical condition evaluated by the If statement becomes true, the statements with the script block will be executed once, in order as they are written.

If test_expression; { This line is called the action statement. }
    { The action statement triggers the script when the test    }
    { expression is true                                        }
[              { The square bracket marks the script beginning }
  Statement 1; { The statements with the brackets are referred }
  Statement 2; {   to as the script statements.                }
  Statement 3;
]              { This bracket marks the script end.            }

If the test expression is still true when the last statement within the script is evaluated, and if there is no provision to transfer execution to another state, then the script will run again. Take care to ensure that you do not create a continuously repeating loop. There are two ways to stop the script from repeating:

  • Ensure that one of the statements within the script updates the conditions of the test expression so that it will become false.
  • Provide for a state change by adding the name of another state to the action statement that triggers the script. When the script completes, execution passes to the named state.

Script blocks are found within states. The following example shows a typical state structure:

Main [
  Steady state statement;         { active while Main is active }
  Another steady state statement; { active while Main is active } If <test_expression>  State2;  { active while Main is active }
  [  { this block active only when test_expression becomes true }
     Script statement 1;
     Script statement 1;  { last statement of the script.       }
  ]                       {  end of script section.   }
  Another steady state statement; { also active, just like the  }
                                 { ones before the script block }
]
State2 [
  Another steady state statement; { active if State2 is active }
  Another steady state statement; { active if State2 is active }
]

Execution begins with state Main active. All statements within it, including the one beginning with If are in Steady State and therefore are active as long as Main is active.

When the test expression becomes true, the script statements run in order. Because the script's action statement ends with another state name (State2), control transfers from Main to State2 when the script finishes.

The statements within a script are referred to as "script statements". This is an important distinction when referring to VTScada's extensive function library. Many functions can only be used in a script, while others can only be used in steady state.

Note also that functions that can only be used in a script cannot be used in a tag expression.

Module

A module is a collection of states, variables declarations, parameters (if needed) and possibly, other modules. Modules are separate tasks that are run simultaneously in the system. Similar to a class in other programming languages.

Any given module may be run any number of times (limited only by system resources). Each running copy of a module is called an instance, and has its own set of variables and conditions. Each instance of a module runs independently of all others. For example, every I/O tag in your application is a separate instance of the module that defines how an I/O tag works.

When designing a system, it may be helpful to assign each physical entity of the system to a particular module, and to make the states of that module correspond with the physical entity's actual physical state. For example, your system might have a module called Turbine, with four states, SpoolingUp, SpoolingDown, Running and Stopped. Physical entities composed of other smaller objects may be represented by a module that contains other modules inside of it, such as a module called Pump that has two child modules called Valve and Motor. Between child and parent modules, there exists a powerful relationship known as inheritance, whereby child modules may share some or all aspects of their parent's character, such as variables, or characteristics that the parent module has inherited from its parent. The concept of inheritance applies to all ancestors of a module, not simply its immediate parent.


Style Guide for VTScada Code

Developers at Trihedral use this style guide to create consistent and easy-to-read VTScada code. If you obey the recommendations in this guide, it will be easier for others to read your code and for you to read others' code.

Notation:

$$$ means you must obey this rule

$$ means you should obey this rule, but there is some leeway

$ means that this is a guideline

General organization

A module is the main unit of design and each logical module shall be in its own source file named after the module with a .SRC suffix.

Prologue and Epilogue

  1. $$$ Each module shall have a prologue that consists of a multi-line, 80 characters-per-line comment describing the purpose of the module. The first line of the comment must contain the name and ancestry of the module, centered between lines of equal signs:
{====== MyService.MyModule ======}
{ Description of module          }
{================================}

Note that the number of equal signs varies - whatever is required to pad out the comment to 80 characters (the closing parenthesis should be in column 79). The last line of the comment should be strictly equal signs, used to mark the end of the comment.

Note that much of the existing code uses a \ between the module names in the first line. New code shall make use of the . (local scope) separator in keeping with the intended default preference for . as the scope operator.

  2. $ With module declarations, align all “Module” keywords in the same column when possible.
  3. $ Module declarations with file names should align the file names in the same column.
  4. $ Consider moving a sub-module to its own file if it exceeds 500 lines of code. Avoid small files whenever possible. There should be a good balance between overly lengthy source files that are unwieldy to navigate through, and many small files that make it difficult to follow the code without opening dozens of files.
  5. $$$ The beginning < of a module must be followed by a comment block describing the module.
  6. $$$ The closing > of a module and the opening < of another module must be separated by a blank line.
  7. $$$ The closing angled brackets for a module must be preceded by a comment indicating the end of the module. It is acceptable to have an blank line between the closing ] and the opening {.
...
]
{ End of MyService.MyModule }
>

Comments

  1. $$ Full line comments (on their own line) that are used to describe the action of statements, etc. should have a single space before and after the opening bracket, and a space before the closing bracket:
{ This is a comment }
X = 1;
  2. $ If you are editing an existing module that uses a different style of comments (e.g. the five asterisk style), continue using that style within that module for the sake of consistency. You may consider changing the existing style if there aren't many instances of it or if there is an inconsistent mixture of styles.
  3. $$ Comments generally begin with a capital letter, however, single or few word comments may or may not use capitalization, as appropriate.
  4. $$ Multi-line comments should use a single set of braces. The text should be left aligned.
{ This comment has multiple lines
  and should be left aligned }
  5. $$ All variable and parameter comments should start in the same column (preferably column 31) and end at the same column (preferably column 79, with the semi-colon in column 80).
  6. $$$ Any code which is inserted for testing or for other temporary purposes must have a comment that includes two consecutive question marks { ?? }, which can be rapidly located before code is shipped.
  7. $ Multiple in-line comments appearing on multiple lines should be aligned, especially for parameter comments in a module call. Padding out the right brace is preferred as well.
    IfThen(X == Y { First two are equal       } ||
           X == Z { First and last are equal  } ||
           Y == Z { Last two are equal        },
      ...
    );

Variables and Parameters

  1. $$$ Start parameters with an opening bracket in the leftmost column on the line immediately following the module name.
  2. $$$ Indent all variable and parameter definitions two spaces (except when appearing in a class-block, in which case extra indentation is required).
  3. $$$ All variables and parameters must have a comment.
  4. $$$ Use descriptive names for variables and parameters.
  5. $$$ Variable and parameter names must begin with a capital letter. The exception is a variable or parameter which is a pointer, such as pResult.
  6. $$$ Place the semi-colon for the variable or parameter declaration after the comment on the same line. This associates the comment with the variable declaration, which will get the correct highlighting for code coverage in the Source Debugger.
  7. $$ For default values, align all = in the same column when possible.
  8. $ Blank lines may be placed between variable groups that have different purposes. A comment identifying the purpose of the group would be useful.
  9. $ A blank line is not required between the end of the parameters and the beginning of the variables, though either is acceptable.
  ...
)
[
  ...
  10. $ Constants may be declared with all upper case names, as appropriate.
  11. $ Constants used for indices in arrays used as records should begin with the # character.
  12. $ The keywords CONSTANT, PROTECTED, RETAINED, SHARED, MODULE and STRUCT should be uppercase, though mixed or lowercase is acceptable. The case should be consistent amongst all variable declarations in a module. Since Module and Struct appear differently in the code, adopting a different, but consistent, style for those keywords is acceptable.
  13. $$$ Structure definitions must indent their field names two spaces and should include comments for each field.

States

  1. $$$ State declarations should have a blank line before them but not after them.
...
]

NextState [
  If X Done;
]
  2. $$$ State name declarations must not be indented.
  3. $$$ State names must begin with a capital letter.
  4. $$$ The square bracket beginning the state declaration must be on the same line as the state name, separated from the name by one space.

Statements

  1. $$$ Statements in a state must be indented by two spaces. Your editor should be configured to use two spaces instead of a tab when you hit the TAB key.
  2. $$$ “If” statements (predicate conditions) with attached script blocks must have the beginning [ and ending ] each on their own lines at the same indentation as the “If” statement.
  3. $$$ “If” must be written with the mixed capitalization.
  4. $$$ Indent statements within script blocks an additional two spaces. Statements nested within other statements carry on in this fashion, increasing indentation by two spaces at a time.
  5. $$$ Do not use spaces on either side of the opening parenthesis for a function or module call. The exception, if desired, is IfElse (, IfThen (, WhileLoop (, and DoLoop (.
  6. $$$ All commas must be followed by a space except when appearing at the end of a line (as in the condition for an IfThen/IfElse statement).
  7. $$ Where multiple = statements are listed together, align the = in the same column when possible. This is especially valuable where several related assignments are referencing the same array or structure. It helps to highlight the similarity and differences between such lines of code.
  8. $$$ Semicolons terminating a statement must follow immediately at the end of the line without any preceding or trailing spaces.
  9. $$ Your editor should be configured to automatically trim trailing spaces when the file is saved.
  10. $$$ Parameters to functions, such as IfThen and IfElse, must be considered as if they are independent statements, following the same rules such as those for indentation and semicolon use.
  11. $$$ No more than one statement may appear on a line.
  12. $ Long assignment statements can wrap to the next line at approximately column 80. Each line should start in the same column as the initial assignment. Non-terminated lines should end with an operator. Alignment of statements that span several lines should not be random, but aid in the readability of the code, as illustrated in this example.
X = Parm1 + Parm2 + Parm3 +
    Parm4 + Parm5;
  13. $$ When working with UI controls that require coordinates, use the global constants EditHt, DropHt, BtnWd, etc, rather than hardcoded coordinates.

Operators

  1. $$$ Place a space before and after the operators = == != += -= *= /= %= && || ^ @ < > <= >= ? : >> and <<.
  2. $$$ Do not place a space before or after the [ ] ++ and –- operators.
  3. $$$ When ++ or –- are being used, and there is no functional difference, they should come after the variable, not before, e.g.
I++;
  4. $$ Spaces around the + - * / and % operators are preferred, but can be omitted where clarity is not sacrificed. They can be helpful in complex statements, but take up unnecessary space in simple ones.
  5. $$$ The prefix operators ! & and * must not have a space after them.
  6. $$$ The scope operators \ and . must never have a space between themselves and their variable.
  7. $$ Always use the local scope operator (.) unless you intentionally mean for the scope to be global (\).
MyTag.Name
  8. $$ The operators <> and >< are discouraged. Use != instead.
  9. $$ The operator ~ is discouraged. Use ! instead.
  10. $$ The operators => and =< are discouraged. Use >= and <= instead.
  11. $$ The operators | and & are discouraged. Use || and && instead.

Function calls

  1. $$$ Start all function calls with an upper case letter.
  2. $$$ Functions with long lists of parameters or conditions can wrap to the next line at approximately column 80. The parameters should start in the same column. There is a balance as to which column the line break should occur. Statements that span multiple lines are sometimes harder to read, while statements that extend beyond the visible area of a text editor are also a problem. Try to keep a statement on a single line if only a small portion would get split out to the following line.
MyModule(Parm1, Parm2, Parm3,
         Parm4, Parm5);
  3. $$$ Except for the condition (if they have one), WhileLoop, DoLoop, IfThen, IfElse, CriticalSection, Execute and Case must terminate all internal statements with semi-colons, not commas, even though they are technically parameters.
  4. $$ The functions WhileLoop, DoLoop, IfThen, IfElse, CriticalSection, Execute and Case do not need an ending comment such as { End WhileLoop }, except in cases of extreme complexity or length. Modern editors and proper indentation easily identify the end of such statements for you.

WhileLoop & IfThen

  1. $$$ Place the condition on the same line as the WhileLoop/IfThen.
  2. $$$ Indent all internal statements two spaces from the WhileLoop/IfThen.
  3. $$$ Terminate the statement with the ); on a separate line aligning it in the same column as the WhileLoop/IfThen.
    WhileLoop(I < N,
      ...
      I++;
    );

DoLoop

  1. $$$ Start the DoLoop statement with no parameters on the first line.
  2. $$$ Indent the internal statements of the loop two spaces from the DoLoop.
  3. $$ Terminate the loop with the comment { While } at the same column position as the DoLoop, followed by the condition on the next line (indented by two spaces), followed by the ); on the next line aligning it in the same column as the DoLoop. It is acceptable, however, to put the condition on the same line as the { While }.
    DoLoop(
      ...
    { While }
      !Valid(X);
    );

IfElse

  1. $$$ Place the condition on the same line as the IfElse.
  2. $$$ If an Execute is required for the TRUE case, it is placed on the first line as well, with its opening bracket immediately following it (no space) and its closing bracket on its own line in the same column as the IfElse. This avoids gratuitous indentation of the body of the condition and makes IfElse and IfThen statements look very similar in construction with all of their statements indented by two spaces from the condition and the closing of the block always aligned with the start of the block.
  3. $$$ The FALSE case should be started with a comment { Else } in the same column as the IfElse. If it requires an Execute, the same guidelines are followed as described previously, except that the closing brackets for the Execute and the IfElse are kept together on the last line with no space in between.
  4. $ An IfThen can be used in place of an Execute where applicable.
  5. $$ Simple IfElse conditionals should be represented using ? : conditional syntax in favour of a more verbose IfElse. Use your judgement to decide which syntax is clearer. Generally if it all fits on one source code line, the ? : syntax is preferred.
  6. e. $$ Multiple nested IfElse statements should all start in the same column if they represent multiple mutually exclusive choices. Avoiding extra indentation will help with the readability.
IfElse(X,
  Y = 1;
{ Else }
  Y = 2;
);

IfElse(X == 0, Execute(
  ...
);
IfElse(X < 10, Execute(
  ...
);
{ Else } Execute(
   ...
)));

Case

  1. $$$ Place the condition on the same line as the Case.
  2. $$ Identify the integer value of each internal statement with a comment. The comment should be indented two spaces from the Case.
  3. $$ Simple Case statements should appear on the same line as their comment, whereas complex Case statements that use Execute should appear on a separate line indented two spaces from the beginning of the comment.
  4. $$$ The closing bracket should be on its own line in the same column as the Case
X = Case(FirstVar,
      { 0 } A;
      { 1 } B + C;
      { 2 } 2*A + B/2 + Min(C, D%5);
    );

Case(SecondVar,
  { 0 - This}
    DoThis();
  { 1 - This & That } Execute(
    DoThis();
    DoThat();
  );
  { 2 - The other thing }
    Other();
);
  5. $$ All function calls should have a set of parentheses, regardless of whether they require parameters. This makes it easy to differentiate between a function and a variable. The exceptions are Invalid, Self, TRUE and FALSE, which do not need parentheses.
  6. $ If a module does not need or have a valid return value, Return() is preferred over Return(Invalid).
  7. $$ When True(X) and False(X) are used with parameters, they require parentheses and should have only the first letter capitalized. If they are being used as constants, they should be all uppercase without parentheses: TRUE and FALSE.


Best Practices for Coding

Separate the user interface (UI) from implementation.

This is an example of the Single Responsibility Principle where each section of the code should fulfill a clear requirement. Separating concerns such as UI and logic allows for easier testing.

All variables and modules should be declared by default as PROTECTED.

This gives a visual guide as to which elements of a module are not intended for public use. Note that PROTECTED does not actually restrict the calling of Modules. To inform others, declarations that are intended to be public should have a { PUBLIC } comment prefix.

Subroutines shall preferably have one exit point at the end of the script block.

This prevents code not running due to an earlier return. Note that this can also complicate code. For example, parameter error handling must be propagated down to the final return statement.

Don’t use !False() to validate arguments.

The logical contortions required to understand the effect are too confusing.

Use True(X) instead of PickValid(X, False).

Simpler and clearer.

Restrict usage of InsertArrayItem for large numbers of inserts.

InsertArrayItem has performance of O(n) as it has to create a new larger array and copy the existing values from the old array into the new one; performance suffers when items are continuously inserted and the array size grows. Items can be accumulated into a dictionary (O(log n)) using an increasing integer for the “key” and then converted to an array if required.

Don’t use Watch(0, …).

Either use Watch(1, ...) or capture the values of the watched values before entering the state and check if they've changed. Watch(0, ...) has the potential of missing a change that occurs after starting a state but before Watch(0, ...) runs.

Don't prefix references to Code, VTSDB, or System with a leading Scope operator \.

They are statically defined in AppRoot and the leading \ adds additional code and execution time unnecessarily.

Exceptions apply. To reference the Code object itself, use \Code. To reference a system library module or variable use \System.ModuleName.

Don't pre-increment or pre-decrement the loop index in a WhileLoop.

Doing so is simply over-complicated.

Don't use the same variable for two (or more) entirely different purposes within the same module.

For example, using I as a loop index in different loops is fine, but also using it to hold text is not.

Always use the trigger parameters on input controls.

This allows for the correct detection of changes to the control.

Do not ignore launched objects.

For example, where the caller doesn't pay attention to the lifetime of the callee.

If the caller should be slain before the callee finishes, then the callee will be slain prematurely. Typically, it is best to watch for the callee's completion unless you have a good reason not to. Typically, this also means that you'll avoid launching two of the callees in parallel, which may also be undesirable.

Avoid data races.

Avoid parallel data flows that ultimately have convergent results, as this is the source of race conditions. For example, if you set some values and they go off to their own script and affect other things, and then the results of both come back together (or perhaps one at a time) to affect something else. Often it is less risky and easier to follow just to serialize actions in a script than to try to run them "in parallel" across multiple steady-state statements and script blocks.

Use ForceState with caution.

This is the equivalent of a GoTo in other languages and should be used with caution for similar reasons. The compiler does no checking of the target state so typos won’t be detected. Note that ForceState does not make an immediate jump; script execution continues to the end of the block, so code that should not be run after the call to ForceState should have suitable guards.

Use care when applying !Valid to the return value of a module call.

The comments of the Return function contain essential information.

For a called module, there is no way to know the return value until the code has time to run. This means that a called subroutine will return Invalid initially. Watching only !Valid(SomeModuleCall()) often just means TRUE. The initial Invalid, meaning "the answer is not yet available", can be mistaken for "done" or "no answer".

One way to avoid this is by using a previously initialized variable rather than the return value.


Expressions

An expression is "any calculation that returns a result". In more practical terms, an expression is something that…

  • can combine or compare multiple tag values for monitoring or reporting.
  • can signal a need for control actions based on any set of system conditions.
  • can get the time, date, signed-in operator, system status, etc.

Why Create an Expression?

As a rule of thumb, expressions are used to "get" things:

  • Calculate values from one or more sources to get a result.
  • Concatenate strings together to get one string.
  • Get the status of something that can be used indirectly to trigger an alarm or event.

Expressions can be instrumental in configuring alarm suppression rules, creating context-sensitive operator instructions, or creating parameterized resources that are scalable and easy to maintain.

Why Not Create an Expression?

The second part of the rule, expressions should not be used to "do" things:

  • Do not set an external value using an expression.
  • Do not acknowledge an alarm by expression.
  • Do not trigger an event directly using an expression.

Expressions get values for tools like Memory tags (which don't count towards your tag count), Multi-Write tags, and Trigger tags to do things with. They are intended to be lightweight and used directly in tags and widgets.

VTScada has been under continuous development for decades and boasts a huge library of easily configurable tools. If you find that, by the logical progression of your application building, your expressions have become quite lengthy and have begun to resemble scripting logic, take a second look at the catalog of available options. It is very likely that there is an existing feature that already has the problem figured out, is scalable and will continue to be supported by VTScada in new versions.

General steps to create an expression:

In any VTScada tag configuration field that has the options, Constant, Expression, Tag...

Expressions are frequently used for tag configuration

  1. Click the Expression option to select it.
  2. Click the expression editor button.
  3. Enter an expression into the editor window.

    The expression editor window can be re-sized as needed.

  4. Click OK to save your work and return to the tag configuration.

The maximum length of an expression is 65535 characters.
If your expression approaches this limit, you should consider whether there might be a shorter way to write it.


Workspace for Expressions

Install a Standard Application

Many of the concepts presented in these notes are accompanied by examples that you can try. For these, you will need an application. (Preferably not one that you use for production work.) The TrainingSimulator, provided with every copy of VTScada, will provide simulated data but because it is a code-free Snapshot, you will not have access to the Idea Studio within it. You can build your own tags, using the Tag Tables for the simulator, which can be found in Appendix A of the Ops & Config course workbook (available from the VTScada website), or you can use the application provided with the Advanced Configuration Course handouts.

These instructions assume that you have a typical VTScada installation, located on your hard drive at C:\VTScada. If not, adjust the file path as required

  1. Expand the main menu in the VAM.
  2. Select Add New Application.
  3. Select the Advanced option.
  4. Select Next.
  5. Select Get from ChangeSet.
  6. Select Next.
  7. Select the Browse button.
  8. Navigate to C:\VTScada\Examples
    This location assumes that you installed to C:\VTScada.
    Use your installation folder if different.
  9. Locate and select the file, Training Simulator.snapshot
    Note: You might also see a legacy application: "CompletedTutorial". We will NOT be using that application. Do not select.
  10. Select Open.
  11. Select Next.
  12. Ensure that the option, Start application now is selected.
  13. Select Finish.

The application will be created and will start. You will be able to exit tags and will have access to the simulation. You will not be able to open the Idea Studio.


Syntax Rules for Expressions

You cannot save an expression that contains a syntax error. For example: unbalanced parenthesis "2 + (2/3" , or using an operator without an operand "2 + ".
It is perfectly legal to save an expression that will have an INVALID result, such as any number divided by zero.

Syntax and notes for expressions:

  • Operators are symbols such as plus and minus signs. Operands are the things being operated on by the operators. In the expression 2 + 2, the digits "2" are operands and the "+" is an operator.
  • Spaces between operators and operands are not required but they are recommended. The spaces will increase the clarity of your code and help you avoid errors.
  • Extra spaces are ignored.

  • Line breaks are ignored, except that they count as a space.

  • There is a precedence to the order in which mathematic operations are performed. For example, multiplication before addition. You can use parenthesis to improve clarity and to control the order of the operations. ((2 + 3) * 5).
  • Close what you open; parenthesis (...), quotation marks "...", etc.
  • Text must be enclosed in double quotation marks.
  • To display a quotation mark in text, use a doubled set of quotation marks:

    "The computer said, ""Hello World"". "

  • Text not enclosed in quotation marks is taken as the name of a variable, such as "2 + X."
    If the variable cannot be seen in the current scope of the expression you will get an error message.
  • VTScada text, such as tag descriptions, etc. is stored in phrases and referenced by phrase identifier key values. If you query a tag's description parameter, you will get the phrase identifier key not the text of the description. See: Multilingual Expressions
  • You cannot declare new variables in expressions or assign values to variables, but you can use existing variables such as tag values and application properties.
  • FALSE is zero. TRUE is any numeric non-zero, usually 1.
  • "Invalid" has a clearly defined meaningin VTScada. It means that there is no value available. Examples include the value of an I/O tag when communications are lost, division by zero, and any variable that is declared but has not had a value assigned. Invalid
    Invalid is neither TRUE nor FALSE. Any calculation with an Invalid operand will return Invalid as a result.


Where to Write Expressions

Expressions can be added to tags and to widgets.

An expression can be used anywhere that you see the option: Constant / Expression / Tag.

Constant / Expression / Tag in a tag configuration parameter

You must open the Expression Editor (button circled in preceding figure) to start typing an expression or to use the function editor.

Create a Calculation tag

  1. Open the Tag Browser and create a Calculation tag at the top level. Name it Demo Calc.
  2. Open the Calc tab, select the Expression option, then click to open the Expression Editor.
  3. Type the following expression to calculate the area of a circle with radius 5.

\pi * pow(5, 2)

  4. Click OK in the expression editor to save your work.
    You will not be allowed to save the expression if it contains a typo.
  5. Deselect the Questionable Data property, and close the properties dialog.
  6. Draw the Calc tag on the Overview page using a Numeric Value widget.
  7. Configure the widget to show two decimal points.

You might have been tempted to look for a function to format the expression to round to two decimal points. It is usually better to calculate mathematic results with full accuracy and use display parameters to adjust how it's presented.

Expressions can be added to any tag parameter:

For any tag parameter, but especially those that don't have the option shown in the preceding figure, you can right-click to create a parameter expression. These are slightly different from the last as they're designed to evaluate only when the tag starts.

If you add an expression for the tag's name parameter, you create what is called a Start Tag expression - one that controls whether the tag should start rather than one that changes the name.

Adding a parameter expression

Parameter expressions give you the option to deselect the option, "Optimize to only evaluate at tag initialization". Deselect that option only if you are certain that you need the parameter to change dynamically while the application runs. Be warned that a non-optimized tag parameter expression will cause that tag (and all of its child tags) to restart every time the value changes. This is not at all the same as an expression in a parameter that gives you the option of Constant / Expression / Tag.

Parameter expressions add extra demands of CPU time and memory. This is especially true for non-optimized tag parameter expressions. The extra load is very small but can add up in larger systems to impair performance.
Use where needed, but only where needed.

Expressions can be used in graphic object properties

For any property of any object drawn in the Idea Studio, you can use an expression.

Setting a rectangle's fill color using an expression

The version of the expression editor that opens with Idea Studio object properties differs from the one in tags. Here, you can type directly in the field rather than opening the editor. Also, you get a tag-picker, allowing you to open a new instance of the Tag Browser and choose a tag for use within your expression.

Expressions can be used in page titles

The title of any page can be configured using an expression to reflect the content when the page opens. In most cases, this is used with parameterized pages and the expression will use one of the page parameters. If the page parameter refers to a tag, then you can use any property of that tag. For example, if you had a parameter named PumpSelection, holding a Pump Status tag then, your page title expression might be, "PumpSelection\ShortName". For anything more complicated you will need to use text handling functions.

Opening the Expression Editor to set a page title


Working in Steady State

Most of the expressions that you create in tags and graphics work in steady state. For example, the code behind any page in VTScada. If none of the tag values change, nothing on the page will change. Deep in the VTScada engine, code is watching for changes to occur, but at the level of your page, all the code is simply sitting there. It does nothing, and takes no CPU time until a change occurs, such as an input tag reporting a new value. This triggers a linked widget to update, showing that value. Only the code for one tag and then one widget is processed. This is an important part of what makes VTScada so efficient. If you write code for a new display feature, it is extremely unlikely that you would need to write a loop to repeatedly check for new values.

Note that there are ways to get into trouble with steady state. For example, perhaps you might create two I/O and Calculation tags, both as analog calculations. You name them Calc1 and Calc2.

In Calc1, you suppose that you have created an expression that uses some other analog tag's value and also the value of Calc2. In Calc2, you have an expression that uses the value from Calc1. If you were working in an ordinary programming language, this would not be a problem. Your code would update Calc1, then Calc2 and then stop. But in steady state, expressions are triggered whenever any of the components change. What will happen in VTScada is:

  1. The analog tag changes value.
  2. This triggers the expression in Calc1.
  3. The change in Calc1's value triggers the expression in Calc2 and so Calc2's value changes.
  4. This triggers the expression in Calc1.
  5. And, so on...

The process will never stop on its own, therefore you must make sure that you never create circular references like the one in this example.

Pegging a CPU

(Do not do this experiment within a production application.)

The following demonstrates how poorly-designed expressions can cause trouble:

  1. Create two numeric calculation tags. Name the first, "Calc1" and the second, "Calc2".
  2. Enter the following expression for Calc1:

[Calc2] + 1

  3. Enter the following expression for Calc2:

PickValid([Calc1] + 1, 0)

  4. Let the system run for a few moments while you check the CPU statistics using the Windows Task Manager.
  5. Delete the tags.
    In an extreme case, you might need to use the Windows Task Manager to stop VTScada.

Mutual refernce calc tags stuck in infinite loop


Function Selection Dialog

Use this to browse a portion of the VTScada function library for code to use in your expressions. The Function Selection dialog is available from any VTScada Expression Editor dialog.

Options depend on where the expression is being created and therefore the value that should be returned.
This example is meant to return a numeric (analog) result.

Function Selection versus Function Editor

  • Function Selection helps you create expressions. Use the this to find and choose both operators and functions. Everything that you add is always appended to what you have already written.
  • Function Editor helps you edit the parameters of the functions and operators you have already added to your expression. Use this after you have an expression containing at least one function or operator, in order to change that part of the expression.

While the Function Selector is helpful, you still need to know how expressions work and have a clear idea of the expression you are attempting to build. It is also helpful to look up the description of each function and its parameters in the VTScada documentation while editing.
* Press F1 while selecting parameters, to see the description of the function you are configuring (as well as suggestions for alternatives).
* Advanced developers can create their own functions for use with the Function Selector. See Add Functions to Your Application's Library

Function Editor / Parameter Assignment

To use the Function Selector:

  1. Begin creating an expression by opening the expression editor.
  2. Place the cursor in your expression where you want to add a function or operator.
  3. Open the Function Selector. (Refer to the first image in this topic.)
  4. Choose your function or operator, then click OK.

If parameters are required (as they almost always are) the function editor dialog will open. The title of this dialog varies because it always includes the selected function followed by the word "Parameters". In the following example, the selected operator was "Divide" (/).

Plan to press F1 at this step. Doing so will open the VTScada documentation to the relevant function or operator, where you can learn more about what is needed for each parameter.

The expression editor will try to simplify your expression as much as possible before saving it. For example, if you type something like Max(1,2,3,4), the expression will be interpreted as a constant “4” and the expression editor will not allow editing.

Example:

Suppose that your intent is to create a expression that returns the integer portion of tag's floating point value. For this, you could use either the Int function, or the Cast function. For the purposes of this example, let's assume that you decide to use Cast.

For the "Value" parameter, you will select the tag. But, what should you provide for the "Type" parameter? You will need to refer to the documentation of this function to discover that the Type must be a number, and further, that number must be 1 in order to cast to an integer. Pressing "F1" will open the relevant documentation topic.

When adding text parameters, do not type quotation marks around the text. For functions with optional parameters, beware of telling the dialog that you want to include an extra parameter and then leaving it unspecified. "Invalid" is the likely result.

Function Selector Description

Search

Type a function (or part of a function) into the search field and press the Enter key on your keyboard. Wild cards are supported and are assumed if not provided.

Filter

The list is prefiltered to functions and operators that can be used in the context of where you are creating your expression. For example, if your expression will run in steady state, script-only functions such as CurrentTime are removed from the list.

You can further filter the list by setting the drop-down selection to any of:

All Keywords

All functions and operators that can be used in the current context.

Alarm

Check whether a given tag has active or unacknowledged alarms.

Counters

Only one: Trigger Counter - watch equipment starts.

Date and Time

Calculate time and date in many ways.

Logical

A large variety of functions to check the status of your application.

Math

Generic, Boolean, and Trigonometric functions.

Mouse

Two functions that return the location of the pointer within the application.

Network

Translate a TCP/IP address to text.

Text

Manipulate and examine text.

Variable

Cast one variable type to another, or specify the scope of an object.

Error: Failed to compile expression

You will see this or a similar message when there is a syntax error in your expression. Refer to the Syntax Rules for Expressions

The dialog indicates only syntax errors. Errors in logic can be saved and will run, but return the wrong result. Write your expressions with care.

Practice using the Function Selector

  1. Create a new I/O and Calculations tag named Level Steps.
  2. Ensure that the data type is Analog and select the Calculation option on the ID tab.
  3. Configure an expression using the Function Selector to use the Deadband function, setting the Delta value to 2. (Hint: Don't forget that you can use F1 to open the documentation.)

(You might want to disable alarm sounds before proceeding with the next part of this exercise. As a reminder, you can find a control for that in the Alarms tab of the Edit Properties dialog.)

  1. Edit the tag, Level, to add a low level alarm. This should have a priority of "Warning" and a setpoint of 10.
  2. Modify the tag, Inflow, to add a similar low level alarm with a setpoint of 25.
  3. Create a new I/O and Calculations tag named Station Alarms
  4. Set the data type to Digital and select the Calculation option.
  5. Use the function selector to create an expression that will be TRUE whenever there is an active alarm on either Level or Inflow. (You will need the OR operator, which is written as two vertical bars: || )

After ensuring that your expression works, feel free to disable those two alarms before proceeding.


"Invalid" in Expressions and Results

"Invalid" is a term used to signify "no possible result". For example, trying to divide a number by zero. If an I/O tag cannot connect to hardware, its value will be Invalid. Any variable that is declared but not initialized with a value, will start out as Invalid.

Invalid is not an error message. It's a perfectly normal value that you can expect to see frequently. It is a unique data type that is not TRUE or FALSE, numeric or text. VTScada will never write an Invalid to I/O. Invalids guard the system from performing control actions based upon erroneous or bad information. And any calculation that includes an invalid value produces an invalid result (with very few exceptions).

Your expressions need to be able to handle the situation when tags or calculations return a value of Invalid. As an example, suppose that you are trying to calculate a running total instead of using the VTScada Totalizer tag. If the tag value you are watching goes to Invalid, your calculation's result would become Invalid as well unless you have code to say otherwise. To avoid this situation, several functions are available:

PickValid()

This takes a list of parameters and returns the first one that has a valid value. In most expressions that include a tag value, you should protect against an Invalid result by wrapping it in a PickValid. For example:

PickValid(X, 0)

If X, whatever that is, has a valid value it will be used. If it doesn't, then 0 will be used.

Valid()

This tests whether a variable holds a valid value.

Valid(X)

If X has a valid value then this will return TRUE (1). Otherwise, FALSE (0).

True()

Returns a 1 or 0 depending on whether the parameter evaluates to TRUE or FALSE. Always returns 0 if the parameter is Invalid.

False()

Returns a 1 or 0 depending on whether the parameter evaluates to FALSE or TRUE. Like True(), this always returns 0 if the parameter is Invalid.

Using PickValid

When a VTScada application starts, it takes a few moments to establish communications and read tag values. This is true even when communicating with a simulator rather than hardware. The following illustrates the point and the importance of using PickValid when referring to a tag value in your expressions.

Preparation:

  1. Open the Application Configuration dialog, then Display tab of the Edit Properties page.
    (This assumes that you are viewing properties using the basic mode rather than the advanced mode.)
  2. Set the First page at startup property to use the Overview page.
  3. Apply the change, then close the Application Configuration dialog.

Now for the expression:

  1. Open the Tag Browser and navigate to Station 1\Level.
  2. Create a new I/O and Calculations tag as a child of Level.
    Name it Demo Calc and set the mode to String Calculation
  3. On the Calculation tab, select the Expression option then click the Expression Editor button.
    The expression editor dialog opens.
  4. Type the following, exactly as shown:
    PickValid([Level], "Not Valid")
  5. Close the expression editor then close the tag properties dialog.
  6. Draw the calculation tag on the Overview page using the Draw Text widget.
    The choice of widget is important. Do not substitute another.
  7. Close the Idea Studio.
    The text should show the current level of the tank. You might want to remove the questionable flag.
  8. Stop and restart the application, watching the text carefully as soon as the page loads.

Bonus question: what would you have seen during startup if the expression used the tag name without wrapping it in a PickValid? If unsure, try it and find out.

Other situations that can generate an Invalid value:

Double Set:

You will see this error only when writing VTScada script modules, not when writing expressions in tags and widgets.

Do not attempt to set a variable's value in two or more lines of code (statements) within the same state, operating in steady-state mode. Typically, you would encounter this if editing the code for a page or widget.

In this situation it is uncertain which value is correct, so the variable will be set to invalid even if both values are the same. This is known as a "double set".

Array subscript out of range:

An array reference that has one of its subscripts out of range will have an invalid value. Some programmable controllers flag inputs when they are out of range - when these values are read by VTScada, they are declared to be invalid.

Invalid mathematic operations:

Division by 0, taking the square root or logarithm of a negative number, and other illegal mathematical operations result in invalid results.

On purpose:

A value can be purposely set to invalid by using the Invalid() function.


Use Tag Values in Expressions

This information applies to expressions created within the Expression Editor.
It does not apply to VTScada script code created in modules such as custom-coded reports.

In expressions, tag names are enclosed in square brackets: [Level] or [<Station 1\Level>]. The first example is an open relative reference to the name and the second is an absolute reference that displays the name but actually uses the tag's unique ID. The tag selector that is built into the expression editor will always return an absolute reference; you may need to shorten that if you need an open relative reference instead.

If you want to see the value of some property of the tag, you must say which property. For example, [Level]\Value, [Level]\ShortName, [Level]\Area. Note the location of the backslash relative to the brackets. Switching the order is a common mistake.

VTScada offers a shortcut for \Value because this is what you will want in most cases: If no property is specified, VTScada assumes that you want the tag's current value. Therefore, [Level] is always taken as [Level]\Value. It will never return a reference to the tag object itself.

Advanced expression writers take note: If you are attempting an expression that builds a tag reference on the fly, [Level] will always be returned as [Level]\Value. To obtain a reference to the tag object itself, your expression must build that as [Level]\Root or Scope(Self, "Level")\Root).
For all readers: the \Root suffix is not needed or used in 99.999% of expressions!

If the tag is not nearby in the hierarchy, you will need to tell VTScada where to find it. For example, given the following tag structure:

Expression to be created in \Station 1 using Level

If you are creating an expression in a tag that is a child of Station 1 and that uses the value of Level, you would write it as [Level], as shown:

[Level] * 2 / 3 ; two thirds of the  value

If you want to refer to a tag that is not an immediate sibling in the tag hierarchy, you will need to provide the address for where to find it.

Let's say that there is also a Station 2 with a level, and you want a calculation to show the average of the two:

([Level] + [Station 2\Level]) / 2 ; the average of two tank values.

Level within Station 1 can be found just by its name, but you must provide a path to the tag named Level in Station 2.

The following tools are available to help you specify tags in the hierarchy. All of these are used inside the square brackets Operatorsthat denote a tag name.

\ | Divider between parent and child tag names.
..\ | Forces VTScada to start searching one level up the hierarchy tree. Always use this when the property you want to refer to in a parent might also exist in the current tag.
Child\GrandChild | To reference a value (or other property) from a child of the current tag, start with the name of the child tag, then a backslash between each subsequent child name.
*TagType ..\*TagType | Ancestor Relative Path, used when selecting a parent tag of a given type. For example, if you want a calculation tag to refer to the first parent that is a driver, use [*Driver]. (*) If you want it to refer to the first parent that has a numeric value, you can use [..\*Numeric]. The ..\ portion is necessary to prevent the calculation tag from finding itself.
<> | Absolute path. The tag name must start immediately below the root level of the tag hierarchy.

(*) Types you are likely to use most often include: *Port, *Driver, and *Numeric.

There are advantages and disadvantages to each method. For each situation, VTScada defaults to what is most likely to be useful in that situation. "Likely" doesn't mean "always".

The Scope Function and Tags

VTScada handles tag addresses differently in different situations. In a tag's configuration, other tags are usually identified using relative addresses, [Tag Name]. In the Idea Studio, widgets link to tags using absolute addresses [<Full Tag Name>].

If you are writing a VTScada script code module, you can't use the square bracket shortcut. Instead, you must use the scope function:

Scope(Self, "Full Tag Name or GUID", TRUE)\Attribute

If providing a full tag name, do not include the brackets. Providing the tag's GUID is equivalent to the short form, [< >]. "Attribute" is not a keyword here; use \Value or \Description, etc. If you don't provide an attribute, then the Scope function returns a link to the tag object itself, not the value.

If adding expressions to tags in an exported Excel file, you cannot use relative references such as [TagName]. All existing expressions are exported using the full syntax and with certain characters doubled: "Scope(Self, "TagName")\\Value". You must do the same.


Other Tag Properties

Tags have other properties that can be read in addition to their values. For example, device drivers maintain seven logged variables that are available to your expressionsUse care with driver properties and expressions: Some are meant to be read once, such as for a report. Reading them continuously in Steady State may slow your application. 1. Access any property of a tag, including its value, by adding a backslash and the property name.

For example:

[Tag Name]\Description

(Returns a phrase identifier key, not the text of the description. Multilingual Expressions)

[Device Driver Name]\Quality

[I/O Tag Name]\HighAlarmUnacked

[I/O Tag Name]\ScaledMax

Remember that expressions can read values and can calculate using values, but they do not write values. To set one of these properties automatically, use a Tag Parameter Expression in the tag's configuration dialog.

You might wonder how to find the property names. There are two methods. The easiest is to use the Idea Studio and linked tag properties. An advanced method is to use the Source Debugger, which provides added information about what the property holds (text, number, array, etc.)

Care is required both when selecting a property and then when using the property.

1) When selecting properties, note that names do not guarantee content. For example, some may have names that look like they hold the information you want, but the property is actually an enumerator rather than storage of whatever property.

2) Some properties hold arrays or object references rather than simple values. Also, different types of tags will use properties as appropriate for that tag, requiring you to look further rather than assume that a property in one tag will be the same as a property of the same name in a different type of tag.

An example of that last point is the property AlarmActive, which in a Rate of Change tag is an array with index 0 corresponding to Low and 1 corresponding to High. But in an I/O tag, the meaning of the AlarmActive array index varies depending on the alarms configured. For this specific example of alarm status, it may be better to use the functions GetAlarmName and IsActive, etc. as appropriate.

Use the Idea Studio to find tag properties:

  1. Open the Idea Studio.
  2. From the file menu, select New >> Tag Widget.
  3. In the Select Tag Types dialog, choose the tag for which you want to discover property names.
    (You are advised to use this technique with only one tag type at a time.)
  4. Accept the default name for the widget.
  5. Drag a square (or any shape) to the widget.
  6. Open the square's properties dialog.
  7. Set the data source of the fill color to Linked Tag Property.

The data source of the fill color can be selected from a color wheel, a tag value, a parameter, a linked property or an expression.

Changing the data source of a square's fill property

  8. Expand the Linked Tag Properties drop-down to browse the parameters list.

The linked tag properties drop-down menu will display all available options

Selecting parameters of a linked tag property

Use the Source Debugger to find tag properties:

The Source Debugger is a very powerful tool for examining applications

To find the names of properties within a tag, follow the numbers in the preceding figure. It will help if the Sort Tree tool is selected in the toolbar as indicated.

  1. Click to select the running application.
  2. This is the "static tree list". Find and select the tag type that you want to examine.
  3. This is the "module content window" with the "local" mode selected. Scroll to view the property names.

Names that begin with a symbol such as # or @ are for use by VTScada. They are unlikely to be useful in your expressions.

The Source Debugger and other diagnostic tools have code-level access to running applications. This is part of the reason the Security Best Practices topic in the VTScada documentation advises you to keep the VAM hidden from unauthorized users while your application runs.

Expressions that use tag properties

  1. On the Station 1 page, create text that uses an expression to combine the words, "Driver status: " with the driver's current quality value.


Multilingual Expressions

In VTScada, all text for the user-interface is stored as phrases, each with a matching phrase key. This is also true for nearly(*) all text that you add to your application including tag descriptions, engineering units, labels and more.

(* Exceptions include tag names, tag areas and user-defined application properties, all of which are stored exactly as written.)

For example, anywhere that displays the English label "1 Day", actually uses the key "1DayLabel". This allows VTScada to translate the user interface to another language such as French.

English and French phrases for the VTScada user interface

1DayLabel as used in a Totalizer tag.

The advantage is clear for those who need a user-interface that can be displayed in a language other than English. But when creating expressions that involve text and any part of the user interface, you must be prepared to work with phrase keys rather than directly with text.

VTScada comes with French, Simplified Chinese and Traditional Chinese phrases for most user-interface text. You must create your own translations for your text.

Get a phrase, given a phrase key

A phrase is one or more words. Because one language may use words in different order compared to another language, it is best to store complete labels as phrases rather than attempt to assemble labels from individual words. For example, for a phrase key such as "GreenButtonLabel", the English phrase might be "The green button", while the French phrase would be "Le bouton vert".
Given a key, you can find the matching phrase in the currently selected language by using the \GetPhrase function like so:
\GetPhrase("GreenButtonLabel")

A parameterized phrase has one or more spots (parameters) in the form %0, %1, etc., that can be replaced on the fly. The advantage is that the parameter placement can be shuffled within each translation. For example, if the expected parameter to ParmButtonLabel is a color name, the English phrase might be "The %0 button", but the French phrase would be "Le bouton %0". In this case, your expression should use the \GetParmPhrase function like so:
\GetParmPhrase("ParmButtonLabel", "GreenLabel")

In both of the examples just shown, the parameters are enclosed in quotation marks because it is the name of the key that is being passed to the function. You could also use variables that hold those names, which would be more typical for the parameter being passed to the phrase.

Phrases in tag parameters

Tag parameters (such as the Description parameter) present a special case: These are typically snapshot expressions that evaluate only when the tag starts or re-starts. Changing from one language to another does not cause your tags to restart.

The solution to this problem is not to deselect the Optimize option in the parameter expression editor. Rather, it is to use a \ParmPhrase structure instead of a \GetPhrase or \GetParmPhrase function. (In situations where a non-optimized tag parameter must be created, use MakeParmPhrase)

\ParmPhrase is not a function and you will not find it in the function reference (other than a page that will tell you "This is not a function"). When a \ParmPhrase structure is used in certain tag parameters, the translation will update automatically whenever you change the current language. This is true for the following:
Description, Units, Position text on the selector switch, Equipment Type, ParameterName, Recipe Tag Mode, Pump OnText and OffText, the PLC alarm tag's PLCType and AlarmType, and the I/O tag mode.

A parameter phrase structure (\ParmPhrase) has a form much like the \GetParmPhrase function. For example, if your tag's description should describe the color of a button, you would create a parameter expression like so:
\ParmPhrase("ParmButtonLabel", "GreenLabel")

If any of the parameters that you pass to \ParmPhrase are not phrase keys, then they are simply passed through and not translated.

Do not use \ParmPhrase structures alone outside of tag parameter configuration.
Elsewhere, a \ParmPhrase structure may be passed to a \GetPhrase or \GetParmPhrase function call in place of a phrase key, but there is seldom an advantage to doing so.

Create phrases and obtain their keys

New phrases and phrase keys are created automatically whenever you save a new phrase, such as a new tag description or a new label on a page. Having created a new phrase, you can then use the Languages page in the Application Configuration dialog to search for the matching key. A more efficient way to create new phrases and keys is to work directly in the Languages page. An example follows:

  1. Open the Languages panel of the Application Configuration dialog.
  2. Ensure that the Key column is displayed.
    Click the View button and select Key from the pop-up dialog if it is not.
  3. Click the Insert button.
    The Phrase Definitions dialog opens.
  4. Click where indicated to add the new phrase.
  5. Place a %0 to mark the position for the first replaceable parameter. (%1 for the second, etc.)

  6. Click where indicated to add a description that will help translators know the meaning of the phrase.
  7. [Optional] If you have added another language to your application, create the phrase in that language now.
  8. Save the phrase.
    Your new phrase should be selected in the list. It will not be saved until you click Apply, but do not click that button yet.
  9. Click the copy tool, to the right of the phrase key.

    The key shown here is an example. Yours will differ.
  10. Use the key in the your expression.
    If creating several phrases, it may be helpful to keep a text editor handy, copying phrases and keys to it as you create them.
  11. Click Apply to save the new phrase and its key.
    Because the list is sorted alphabetically by phrase or key, the new entry is unlikely to be visible on the screen after you click Apply.

Example: A tag description that reflects the parent tag:

This is a relatively common task. You have a tag structure and would like the description of each child tag in each instance to identify which instance it belongs to. Perhaps (for example) you would like the description to read "Primary pump in the XX region" where XX should be the Area name for the tag.

Begin by opening the Language page in the Application Configuration dialog and creating the phrase, "Primary pump in the %0 region", as described earlier. For the sake of this example assume that the assigned key is named "EU43y4gag".

Create translations if required.

Open the tag's properties dialog and create an expression as shown:

"EU43y4gag" will not exist as a key in your application. A tag's Area is never translated.


Use Application Properties

A frequent request is for a way to let an operator change certain properties of tags, but not give that operator Tag Modification privileges. Among other reasons for why you might want to read application properties in your expressions, the following will show you how to achieve this goal.

Expressions can readNo setting of values, at least not in a steady-state expression. The assignment operator, =, is not legal syntax in this context. 1 application properties that are declared in the [System] section. To do so, write:

\PropertyName

in your expression, substituting the actual property name for "PropertyName". For example:

\DispMgrResizable

\DispMgrFullScreen

Properties stored in either the [Application] or the [Layer] sections are also available, but the syntax to retrieve them is somewhat longer:

\AppLayer.LayerSettings.PropertyName

Examples include:

\AppLayer.LayerSettings.Name
\AppLayer.LayerSettings.DefaultLanguage

Moderate your scan intervals

The default scan interval for most tags is one second. That might be right for some equipment (or even too slow), but for most analog values it's far too frequent. Scanning only every two or three seconds (instead of one) might be perfectly adequate most of the time, and will reduce the load on your network traffic and Historian enormously.

But, maybe you want to be able to change the scan rate depending on circumstances. In that case...

  1. Open the Edit Properties page of the Application Configuration dialog.
  2. Ensure that you are viewing the Advanced Mode, not the Basic Mode.
  3. Insert a new property as shown:

Adding a new label property

  4. Save your work and close the Application Properties dialog.
  5. Open the Tag Browser.
  6. Navigate to find \Station 1\Level
  7. Open the properties dialog and the I/O tab.
  8. Right-click on the Scan Interval field to add a tag parameter expression.
  9. Enter the expression as shown. Be sure to deselect the Optimize option.(*)

An expression for the scan interval

  10. Click OK to save your work for the editor, then the tag.
    The Scan Interval field should turn blue and show the number 3.
  11. Close the Tag Browser.
  12. Open the Idea Studio and add an Edit Property widget to the Station Status page.
    Tools >> Standard Library >> Edit Property
    (Typically, you would create a new page for this sort of operational control, but we're saving steps.)
  13. Configure the widget as shown:

Configuration of your Edit Property widget. Note the data type & min and max values.

  14. Save your work and run the application. You should be able to adjust your scan interval as required. (To see the effect, you would need to have the tag's properties dialog open while changing the value, and would need to change back and forth between tabs to see the changed value.)

(*) What you've just seen is potentially dangerous. A tag with a non-optimized parameter expression (and all of its child tags) will restart each time the parameter changes. It also costs slightly more than other tags in terms of memory and CPU load. And, there's a risk that the parameter could be changed to an inappropriate value or changed frequently. A non-optimized parameter expression is valuable in the right circumstances, but use with extreme care!


Examples of Expressions

The following examples may be adapted to your application, or they may spark an idea for what you can achieve using expressions.

Simple math. Add two AI tag values together:

[Valve1Flow] + [Valve2Flow]

Using logic to check conditions. All the tags in this example are Digital Inputs that will be 1 (TRUE) or 0 (FALSE). In this test, we’re checking whether either both of Valves 1 and 2 are open, or else if the overflow valve is open.

( [Valve1Status] && [Valve2Status] ) || [OverflowValveStatus]

Limit a return value to be no less than 0

Max([Valve1Flow], 0)

Are you viewing an object in the Idea Studio or in the Operator View? The following returns TRUE in the Idea Studio and false otherwise.

ParentWindow()\Editing

Write a 1 when a test is true, otherwise write nothing. The following example takes advantage of the fact that VTScada will not write an Invalid.

If the following were being used to control a pump for example, it would turn the pump on when the flow rate went above 1500, but would not turn the pump off.

[Flow] > 1500 ? 1 : INVALID

Conditional math. Add together only the MVAR values (in AI tags) for generators whose breakers are closed (DI tags == 1)

([Gen1Breaker] == 1) * [Gen1Mvar] +
([Gen2Breaker] == 1) * [Gen2Mvar] +
([Gen3Breaker] == 1) * [Gen3Mvar]

Get the value of an INI file variable for display:

Scope(\Code, "MyAppVersion")

Build an English text string based on values in bits of registers read from a PLC.

Bit([AI3], 15) ? "On " : "Off "

Calculate a steam flow from a DP cell reading on an analog tag:

SQRT((([FT-518-RAW])/4095)*100) * 1000

Calculate a steam flow from a DP cell reading on an analog tag. Force to 0 if a digital tag is not on:

[BLR-001]==1 ? SQRT([FT-506-RAW]) * 3000 : 0

Figure out the bit number that is turned on in a word read from a PLC into an AI tag:

Int((Log([AI3] % 65536) / Log(2)) + .5) + 1

Create a time string based on an analog tag, AI3, and replace the 00 hour reading with 24:

Concat("HE ",Replace(Substr(Time((Scope([AMA.STA.MW-TS]) - (9 * 3600)) % 86400, 2), 0,2), 0,2,"00","24"))

Get the name of the PC that the application is running on:

\RPCManager\WkStnName

Get the version of VTScada that is running:

Version()

Create a flag that toggles every 10 seconds

Latch(AbsTime(1, 20, 0), AbsTime(1, 20, 10))

Given a Context-derived tag at the top level of the tag hierarchy named "Station 1", suppose that you want an expression in a calculation tag that will return the total number of unacknowledged alarms in that context. The expression would be:

\AlarmManager\GetContainerNumUnacked([<Station 1>]\Root)

Check if any user is signed in to a client PC. This example returns a message, but you could just as easily return a 1 or 0 to determine whether a control action should proceed. (A unilingual example.)

\SecurityManager\IsLoggedOn() ? "" : "Authorized Access Only. Please sign in."

Get the name of the operator who is signed in:

\SecurityManager\GetUserName()

Given an application with the following set of custom privileges, you want to configure the Push Button widget so that confirmation is required when the button is pressed by anyone whose account does not have the "Confirmation Not Reqd" privilege.

<SECURITYMANAGER-PRIVAPP>
PrivBitsTotal = 3
PrivDesc0 = Page Priv,0
PrivDesc1 = Operational Priv,1
PrivDesc2 = Confirmation Not Reqd,2

Confirmation Not Reqd is enumerated as privilege 2, therefore its index value is 16 + 2 = 18. The expression for the Confirmation Dialog parameter of the widget would be:

1 - PickValid(\SecurityManager\SecurityCheck(18, 1), 0)

In a parameterized page, find the full name of the tag that was used for a given parameter:

\NameOfGivenParameter\Name

In a parameterized page, where a parameter is of type tag, use the name of the tag as part of the title:

concat("Details for: ", \NameOfGivenParameter\ShortName)


Operators and Functions

Operators are symbols used to perform an operation, comparison, or mathematical function such as addition and subtraction. All operators can be used in all expressions.

Example of an operator:

A + B

A function is a named operation that may return a value, perform an operation or both. Where operators require operands, functions require parameters, which are provided in a comma-separated list inside parenthesis that follow the function name. Function names are not case-sensitive in VTScada.

Examples of functions:

Sqrt(10)
Log(X)
Limit(X, 0, 100)

You can create your own functions by writing subroutine modules.


Operators

A list of all VTScada operators.

Spaces

You are advised to separate operators and operands with a space. For example:

X = A + B;

By doing so, you make your code easier to read and make syntax errors less likely. The exception to this recommendation is for operators that come before or after their operands, such as pre-increment and post-decrement. These should never be separated from their operands.

A = ++B  { Example valid only for script code, not expressions. };

Operator Priority in Statements

The order in which the operators are executed is significant. Consider the expression:

1 + 2 * 3

If operators were evaluated from left to right, the value of this expression would be 9, but in reality the value is 7. This is because VTScada, like all programming languages, assigns varying priorities to operators. Operators with higher priority are done first. Multiplication has a higher priority than addition, so in the previous example the correct result is 7.

If the addition were intended to be done before the multiplication, the expression could be written as:

(1 + 2) * 3

Parentheses ( ) have the highest priority of all operators and force the expression within them to be evaluated first.

Some operators have equivalent priorities, such as addition and subtraction. In these cases the evaluation proceeds from left to right.

If you have any doubt as to the order of execution within an expression, add parentheses to state (or control) the order explicitly. They cost nothing in terms of speed or memory requirements.

Operators and Invalid

Any expression that contains an Invalid will return Invalid unless PickValid() is used to substitute a valid value. There are two exceptions to this rule: AND (&&) and OR (||).

Boolean logic dictates that anything AND 0 is always a 0. Likewise, anything OR 1 must return 1.

Operators and Tag Expressions

All operators may be used in script code. Several are not available to, or not appropriate within, expressions written in tags and Idea Studio properties. For example:

  • The assignment operator, =, and any variation thereof such as add equals, cannot be used in a tag expression.
  • In a tag expression, square brackets are used to indicate tag names, and therefore do not work as array index operators.
  • The address and dereference operators are not meant to be used in tag expressions.
  • Pre- and Post- increment and decrement operators are not available for tag expressions.
  • Shift left and Shift right.

Operators, listed by priority

Operator | Symbol | Priority
Parentheses ( ) 1
X = 2 + 3 * 4;
X = (2 + 3) * 4;

Controls the order of execution. In the first example, X will be 14. In the second, X is assigned 20.

Scope Resolution - local . 2
X = .A;

A may be a variable or module. If found in the local scope, it will be assigned to X, otherwise Invalid will be returned. Note that the dot operator will not work in applications created before version 11.2 unless the application property LocalScopeSyntax is set to 1.

Scope Resolution - not local \ 2
X = \A;

A may be a variable or module. VTScada will search through the scope tree starting with the local scope to find the closest variable or module with a matching name.

Index (Array or Dictionary) [ ] 3
X = A[2];

Follows the name of an array or dictionary variable, and specifies which element of the array or dictionary is to be used.

Segment/Offset @ 4

This returns a number which is the real mode address with the segment before the @ and the offset after the @. This value can be used in functions such as MemIn and MemOut.

Dereference
(pointer dereference) 		* 5
A = *X;

The example shows the opposite of the example for the Address operation.

Address & 5
X = &A;

Returns a pointer to the operand. A pointer is the memory address where the operand's value is stored.
To retrieve the value from the memory address stored in X you must dereference the pointer.

Logical Not | ! or ~ | 5
X = !A;

The operand should be a Boolean TRUE or FALSE (1 OR 0). Returns 0 for a logical TRUE operand and 1 for a logical FALSE operand.

Pre-Increment ++ 5
A = 3;
                        X = ++A;

Requires a single numeric operand. The value of the operand will be increased by one before it is used in the expression. If A initially had a value of 3 in the example given, then it would increase to 4 and that number would be assigned to X.

Post-Increment ++ 5
A = 3;
                        X = A++;

Requires a single numeric operand. The value of the operand will be increased by one after it is used in the expression. If A initially had a value of 3 in the example given, then 3 would be assigned to X, following which A would increase to 4.

Pre-Decrement -- 5
A = 3;
X = --A;

Requires a single numeric operand. The value of the operand will be decreased by one before it is used in the expression. If A initially had a value of 3 in the example given, then it would decrease to 2 and that number would be assigned to X.

Post-Decrement -- 5
A = 3;
X = A--;

Requires a single numeric operand. The value of the operand will be decreased by one after it is used in the expression. If A initially had a value of 3 in the example given, then 3 would be assigned to X, following which A would decrease to 2.

Unary negation - 5
X = -A;

Requires a single numeric operand. Returns the negative of the value to the right without changing that value.

Division / 6
X = A / B;

Requires two numeric operands. Returns the result of the first divided by the second.

Modulus % 6
X = A % B;

Requires two numeric operands. Returns the remainder, being the amount left over after the maximum number of times that B can be wholly divided into A. For example, 8.5 % 3 returns 2.5
9 % 3 returns 0.

Multiplication * 6
X = A * B;

Requires two numeric operands. Returns the result of the first multiplied by the second.

Addition / Concatenation + 7
Subtraction - 7
X = A - B;

Returns the numeric result of subtracting B from A.
Operands must be numeric.

X = A + B;

Returns the sum of two numeric operands.
Or, concatenates two strings.

It is risky to use + for concatenation. If one operand can be interpreted as a number, it will not be cast to a string and the operation will fail. Use the Concat function instead.

Shift Left << 8
A = 4;
X = <<A;

Shift bits to the left. In binary, 4 is stored as 00000100. In this example, X will be assigned 00001000, or 8.

Shift Right >> 8
A = 4;
X = >>A;

Shift bits to the right. In binary, 4 is stored as 00000100. In this example, X will be assigned 00000010, or 2.

Greater Than > 9
X = A > B;

This operator returns TRUE (1) if the first argument is strictly greater than the second, otherwise it returns false (0).
If one argument is text and the other numeric, VTScada will attempt to cast to matching types.
If both arguments are text values, the operator returns true if a letter-by-letter comparison of the ASCII codes in the first argument is greater than the second. Thus "B" is greater than "A", but not greater than "a".

Greater Than or Equal To | >= or => | 9
X = A >= B;

The same as Greater Than, but will also return TRUE (1) if the two operands are equivalent. Does not do a test for strict equivalency. Text comparisons are case-sensitive.

Less Than < 9
X = A < B;

This operator returns TRUE (1) if the first argument is strictly less than the second, otherwise it returns false (0).
If one argument is text and the other numeric, VTScada will attempt to cast to matching types.
If both arguments are text values, the operator returns true if a letter-by-letter comparison of the ASCII codes in the first argument is lower than the second. Thus "a" is less than "b", but not less than "B".

Less Than or Equal To <= 9
X = A <= B;

The same as Less Than, but will also return TRUE (1) if the two operands are equivalent. Does not do a test for strict equivalency. Text comparisons are case-sensitive.

Equal To == 10
X = A == B;

Returns TRUE (1) if the two operands are equivalent.
Does not do a test for strict equivalency. VTScada will attempt to cast mismatched types to match.
Text comparisons are case sensitive. Use StrICmp for text comparisons that are not case sensitive.

Not Equal To | != or <> or >< | 10
X = A != B;

Returns TRUE (1) if the two operands are not equivalent.
Does not do a test for strict equivalency. VTScada will attempt to cast mismatched types to match. Text comparisons are case sensitive.

Exclusive Or ^ 11
X = 0 ^ 0; { returns 0 }
X = 1 ^ 0; { returns 1 }
X = 0 ^ 1; { returns 1 }
X = 1 ^ 1; { returns 0 }

This returns the 64-bit, bitwise exclusive OR of the two operands. If either operand (but not both) is TRUE (non-0), the result is TRUE (1). If both are TRUE or both FALSE (0), the result is FALSE.

AND (Logical And) && 12
X = A && B;

Both the & and the && operators(*see note 1) take two arguments and perform the logical AND function upon them. If both arguments are true (non-0), the operator returns a true value; otherwise, a false value (0) is returned. If either argument is a valid false, the function returns false regardless of whether the other argument is valid.

The AND operator performs a bitwise comparison (64-bit).

VTScada does not use short-circuit evaluation. Both parts of the condition will always be checked (and evaluated if required).

Note 1: VTScada supports a logical "&" operator but in practice it is not used, in order to avoid confusion with the C/C++ bitwise comparison operator.

Note 2: To perform bitwise comparisons, use the AND function.

OR (Logical Or) || 13
X = A || B;

The | and || operators(*see note 1) take two arguments and perform the logical OR function upon them. If either argument is true (non-0), the operator returns a true (1) value. If both arguments are false(0), the operator returns a false value(0).

If either argument is a valid true, the function returns true regardless of whether the other argument is valid. If one argument is false and the other invalid, the operator returns invalid.

The || operator performs a 64-bit, bitwise comparison.

VTScada does not use short-circuit evaluation. Both parts of the condition will always be checked (and evaluated if required).

Note 1: VTScada supports a logical "|" operator but in practice it is not used, in order to avoid confusion with the C/C++ bitwise comparison operator.

Note 2: To perform bitwise comparisons, use the OR function.

Ternary Operator (IfElse) | C ? A : B | 14
X = C ? A : B;

Equivalent to the IfElse function. Operands may be variables or expressions.

If the conditional, C, evaluates to TRUE, then expression A will be evaluated and returned. Otherwise expression B will be evaluated and returned. Note that the ? operator has a lower precedence than most other operators. You are advised to use parenthesis to control the order of evaluation if using If Else in a multi-part comparison. For example,

 A < B || C ? D : E

would be evaluated as

 ((A < B) || C) ? D : E

rather than

 (A < B) || (C ? D : E)

which is more likely what was intended.

Note that a deeply-nested set of IfElse operations can usually be replaced by simpler programming technique. Refer to the comment section in the function,IfElse

Add Equals += 15
X += A;

X and A must be numeric. Adds the value of A to the value of X.

Assignment = 15
X = A;

Assigns the value of the expression on the right side of the operator to the variable on the left.

Divide Equals /= 15
X /= A;

Requires two numeric operands. X is given the value of X / A.

Modulus Equals %= 15
X %= A;

Requires two numeric operands. X is given the remainder of X % A.

Multiply Equals *= 15
X *= A;

Requires two numeric operands. X is given the value of X * A.

Subtract Equals -= 15
X -= A;

X and A must be numeric. X is given the value X - A.


Comparisons: Operators || Functions

Boolean. Noun, always capitalized. A binary variable having two possible values, either true or false. Named for George Boole.

You will often want to choose between actions based on the current situation. For example, if the room is too cold, increase the heat, otherwise reduce it. If the system is down for maintenance, disable the alarms, otherwise leave them enabled.

Typically, test expressions use conditional operators such as:

> | Greater than
>= | Greater than or equal to
< | Less than
<= | Less than or equal to
== | Equal to
!= | Not equal to
Multiple Comparisons
&& | And
|| | Or

The function to choose between two options based on a comparison is IfElse and there are two ways to write it:

IfElse(Comparison-Expression, Expression if TRUE, Expression if FALSE)

Comparison-Expression ? Expression if TRUE : Expression if FALSE

Functionally, these are identical. It's your choice as to which form you prefer to use, but in general the IfElse form is recommended when there is a choice between running one expression and another:

IfElse([Pressure] > \Setpoint), {Do this... }, {Otherwise do this})

or returning the appropriate message:

Concat("The pressure is ", [Pressure] > \Setpoint ? "high" : "low")

Any expression that will return either a 0 (FALSE) or 1 (TRUE), can be considered to be a test expression. (Any numeric other than zero is considered TRUE, but 1 is typically used by convention).

If your goal is a form of trigger, there's no need to write IfElse( Comparison-Expression, TRUE, FALSE). Simply write Comparison-Expression. The result of the comparison is returned as TRUE or FALSE, therefore you don't need to write extra code to return those values.

Situational Message or Instructions

You can use the MultiText widget to display a message that varies according to a changing value. But, what if it also makes a difference whether equipment is running or an alarm is active? Further, what if you want the text of the message to include data calculated from two or more other tags? For this, you're going to need an expression.

  1. Open the Idea Studio.
  2. Working on the Overview or Station Status page, draw text (plain text from the ribbon, not a text widget) on the page.
  3. Open the Edit Text dialog and change the data source to Expression.

  4. Create an expression so that when the Level value is more than 50%, the message is "Level exceeds safe amount". When the Level is less than 50% the message should be "Safe level".
  5. [Optional] Adjust the message to tell your operators the percentage by which the level exceeds the safe amount.

If you knew the math behind the system, you could create a message that tells operators how to adjust the pump or valve to balance the flow rate, or predict when the tank will empty or fill.

Keep the Else's under control !

Writing long "If Else - Else - Else ... " expressions is not efficient and can be avoided. To prevent excessively nested expressions, the property MaxNestedExpressionDepth limits you to 200 function calls (including IfElse) within a single expression. There is no need to test this limit, regardless of the complexity of your application.

Alternatives to nested IfElse structures:

A common task is to build a string based on the current value of a tag (or several tags). For this example, suppose that you need to build a message or address that varies with a tag's current state. A long and inefficient method might be to write:

[SomeTagName] == 0 ? "Message (or) Address 0"
                   :
[SomeTagName] == 1 ? "Message (or) Address 1"
                   :
[SomeTagName] == 2 ? "Message (or) Address 2"
                   :
 etc. for 100 or more messages...

There are alternatives:

Option 1

A much easier method is to use a CASE statement in steady state. All statements will execute, but only the result of the statement matching the requested index will be returned.

X = Case([SomeTagName],
     { 0 } "Message (or) Address 0",
     { 1 } "Message (or) Address 1",
     { 2 } "Message (or) Address 2",
     { etc });

Option 2

Another option is somewhat more complicated to create, but has the benefit that the messages are stored in application properties instead of code and therefore can be added to or edited by anyone with the Configuration privilege. It is not necessary to write more code when messages change or new messages are created.

1. Create a set of application properties for each situation:

 Situation0         = Message or Address 0
 Situation1         = Message or Address 1
 Situation2         = Message or Address 2
   (etc.)

2. Write an expression that uses the Variable function to concatenate the tag value onto the prefix "Situation" to return the appropriate property value.

 Variable(Concat("Situation",[<SomeTagName1>]))

No comparisons or If-Else statements are required. This single line of code can return any message that you have created. For more complicated situations, use Concat to build the appropriate property name or combine several values into one message or address.


Using Functions

Functions perform tasks such as returning the absolute value of a number or retrieving data from the Historian. In the VTScada documentation, each function description includes information that you will need to use the function correctly. Look for the following:

Library Name

Not all functions are part of a library, but for those that are, you must scope Closed v. Find or provide path to a function or variable. n. The path to a function or variable. to the library to use the function. Use the backslash operator before the library name and the dot operator before the function: System.Bevel(). The backslash scope operator means (roughly) "keep looking until you find this" while the dot scope operator means "look only within this specific library".

Returns

Used most often by functions that are subroutines. For many functions (example: GetTagHistory) data is returned through parameters that are passed by reference, rather than as a return value from the function.

Usage Rules - Script or Steady State

VTScada code runs in two modes: Script or Steady State. Many functions will work in only one mode. The "Usage" line in each function description tells you the mode where the function can be used.

Just because a function can be used in a given situation, does not mean that it should be. For example:
* Graphics functions work in steady state but it makes no sense to use one in a Calculation tag's expression. Optimized tag parameter expressions can use script-only functions, but you would never use the speak function there.
* MatchKeys will capture keystrokes only when used in a window or page, not in a service or Calculation tag.

Usage Examples. If you are writing...

General Expressions (Calc. tags)

If you are writing an expression for a Calculation tag, or anywhere that you have the option "Constant / Expression / Tag". Similarly for expressions for image and shape parameters when defined in the Idea Studio.

Constant / Expression / Tag in a tag configuration parameter

If the function is marked as "Script Only" then you cannot use it here.

If the function works in Steady State, then it will compile when used in a Calc tag expression, but it may or may not be useful there. For example, any of the functions that display a graphic object are not useful as a tag parameter.

Tag Parameter Expressions - Optimized

Only functions that can be used in Script may be used for optimized tag parameter expressions. These expressions are evaluated as the tag is initialized, either on start-up or whenever the tag or one of its parents is re-initialized. You cannot use Steady State-only functions in this situation.

Tag Parameter Expressions - Not Optimized

Only functions that can be used in both Script and Steady State may be used for non-optimized tag parameter expressions. These expressions are re-evaluated whenever any of the values referenced by the expression change. This means that the tag (and all of its child tags) will refresh each time a parameter value changes. (A somewhat heavy process of running code that assembles parameter values, and detects and reacts to parameter changes.) You cannot use Script-only functions in this situation.

Page Code, Services, Reports, etc.

These are full VTScada modules, declared in the application's AppRoot file. The full VTScada language and function list can be used in accordance with the rules for a module.

Function Groups

A general classification of functions. Many belong to more than one group, and some are difficult to classify as a member of any. May be helpful when trying to find similar functions.

Related to

A list of similar or complementary functions.

Format and Parameters

The format line for each function description provides an example of how the function is to be used. Optional parameters are shown within square brackets in the format example. You may copy the format example for use within your code, replacing parameters with values as required.

System.Bevel(X1, Y1, X2, Y2 [,Title, AlignTitle, Color])

If your application predates version 11.2, the Settings.Startup property LocalScopeSyntax = 0 will prevent the use of the dot scope operator. If you are sure that you have not used a dot in any tag, widget, page or other name, you can set LocalScopeSyntax to 1 to allow this operator.

Note the use of commas to separate parameters when more than one is required. If a function does not require parameters, you may omit the parenthesis, although this is discouraged as a matter of practice. If a function has optional parameters, you can omit them from the call. If you need to provide only the nth optional parameter, use Invalid as a place-holder for each optional parameter you are not specifying, filling from left to right.

Most parameters to functions can be expressions including other functions. While there is no limit to how deeply these can be nested, you should avoid making your code difficult to follow by nesting too many levels deep.

Parameter Descriptions

A description of each parameter used by the function, identifying whether it is required, the data type, and relevant notes.

Break the Steady-State Rule for Expressions

The rule is that you must use Steady State functions in your expressions, excepting optimized Tag Parameter expressions. What if you need a script function, like CurrentTime? Then you can take advantage of a useful hack.

The Workstation Status driver tag provides a way to process script functions and display them in a steady-state page. It was given this feature originally because the memory information from the operating system is not an accurate reflection of memory in use. To obtain an accurate value, it was necessary to use the VTScada Memory() function, which runs only in script mode. A side benefit of this enhancement to the Workstation Status driver is that you can now use nearly any script-mode function with the Workstation Status tag and retrieve a result. Additionally, that result will update on a set schedule, almost as if it were running in Steady State.

For further information, refer to: Workstation Status Driver I/O Addressing


Bitwise Parameters & Operations

When doing bitwise comparisons, always use the AND and the OR functions, never the && or the || versions.

Several functions have bitwise parameters, meaning that every bit value in the parameter has its own meaning. You can change the behavior of the function or switch features on and off by setting each matching bit to 1 or 0.

For example, the Style parameter of the Window function is described (in part) as follows:

Required. Any numeric expression that gives the style of the window when it opens. This parameter has no effect after the window has opened. Style is formed by adding together bit values from the table below

Bit Number

Description

0 | Enable system close button (if bit 1 is set)
1 | Show title bar
2 | Thick border, not resizable
3 | Thin border, not resizable
4 | Enable minimize button (if bit 1 is set )

... etc.

In use, the code might look like the following: (Style parameter in bold under a bold comment line.)

  Window(  0,   0           { Upper left corner   },
         300, 70            { View area           },
         300, 70            { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}0b00010000000110011, WinTitle, 0, 1);

Note the "0b" beginning the set of 0's and 1's, specifying that this is to be read as bits, not a base-10 integer value.

The comment line is added as a convenience to help the reader count bits. Note that the count does not start at 6, it starts at the right-most 0. In VTScada and most other programming languages, bitwise values are read from right to left ↤, always starting with zero (0). When you reach the second 0 from the right, read that as 10, followed by 11, 12, etc. Thus in this example, there are 17 bit positions shown, numbered from 0 to 16.

We refer to a bit being "set" when its value is 1. If a bit position holds a 0, then that bit is "not set". Referring back to the example and the table before that, we see that bits 0 and 1 are set, therefore the window will have a system close button and a title bar. Bit 4 is set, therefore there will be a minimize button. For the remainder, refer to the documentation for the Window function.

All values of every type are stored as bits, whether represented in a bitwise format (0b...), as an integer, a hexadecimal value, or any other format. In VTScada (and most other programming languages) it is common to use an integer or hex value for brevity when specifying bitwise parameters. The following table provides an example using one byte. (You need only provide as many bits as you want to set, but it's standard practice to use a minimum of 8, or one byte.)

As shown, if your goal is to set bits 0, 1, and 3, it's shorter to write "11" or "0xB" than "0b00001011".

Bitwise value | Decimal value | Hexadecimal value
0b00000000 | 0 | 0
0b00000001 | 1 | 1
0b00000010 | 2 | 2
0b00000011 | 3 | 3
0b00000100 | 4 | 4
... | ... | ...
0b00001010 | 10 | A
0b00001011 | 11 | B

To check whether a particular bit is set, use the AND function to compare against a mask. (A "mask" is just a value that has set only the bits you want.) The AND function (but not && operator) will compare each bit in one value to each matching bit in the next, setting bits in the result to 1 only if both are set in the values being compared. For example if you are interested in knowing whether bit #3 is set, an AND comparison of 0b00001000 and 0b10101100 will return 0b00001000, which is TRUE. If you checked bit 1 (0b00000010) the return would be 0b00000000, which is FALSE.

Related Functions

And

Or

Bit

SetBit

Ones


Math in Expressions

The symbols on your keyboard to use for the basic math functions are as follows:

+ addition

- subtraction

* multiplication

/ division

There are rules of precedence to control which operations are done first. For example, multiplication and division happen before addition and subtraction. You may wish to use parentheses to override the rules or to make your intentions clear.

4 + 3 * 2 : 10
(4 + 3) * 2 : 14

There is no limit to how many sets of nested or consecutive parentheses you can use. Just be sure that for every opening parenthesis, there is a matching one in the right place to close.

The following are a few of the mathematic functions available to your expressions. For a complete list, see Math functions in the VTScada Function Reference. (All math functions can be used in any expression.)

Max(X, Y, Z, …) | Returns the variable having the largest value.
Pow(X, Y) | Returns the value of X raised to the power of Y.
Sqrt(X) | Returns the square root of the value in X.
Int(X) | Returns the number with any digits following the decimal point truncated.
Sin(X) | Returns the trigonometric sine of X, where X is measured in radians.
Cos(X) | Returns the trigonometric cosine of X.

Related Functions:

Math - Generic

Math - Rounding

Math - Trigonometric


Text Functions in Expressions

Expressions can be used to display calculated text as well as numeric values. For example, you might use the Concat() function to join the value of a tag or the result of a calculation to a sentence.

A few of the string handling functions in VTScada are as follows. See String And Buffer Functions for complete descriptions of these and other functions. (Note: many string functions cannot be used in Steady State, and thus cannot be used in an expression.)

\GetPhrase & \GetParmPhrase | Note the backslash that begins each of these functions. Given a phrase key, or a parameterized structure (\ParmPhrase) of phrase keys, this will return the matching phrase(s) in the current language.
Concat(a, b, c…) | Concatenates any number of sub-strings into one sentence. Works in only one language at a time. Concat("Level of Tank 1: ",[TankLevel_1], "%") Returns (for example): "Level of Tank 1: 30.35552%" Concat(" Viewing Station: ", StationNumber) Example shows how to set the title of a parameterized page, where StationNumber is a text or numeric parameter of that page.
Format(width, precision, value) | Turns a numeric value into a text string, having the specified width and precision (number of decimal points). Format(5, 2, [TankLevel_1]) Returns (for example): "30.36"
Replace(sentence, start, length, find, replace) | Searches the sentence, beginning at the Start character and continuing for Length characters, looking for every instance of Find and replacing it with Replace. Note that character counting begins with 0. Replace("This is good", 1, 12, "is", "was") Returns: "Thwas was good" (Note that every instance of "is" is replaced. This may have unintended consequences.)
SubStr(sentence, start, length) | Returns a substring of Sentence, beginning with the Start character and running for Length characters. Substr("on a Halifax pier", 5, 7) Returns: "Halifax"

Examples: Text Functions in Expressions

Concat

One of the most frequently used functions is Concat(). This combines several bits of text together into one sentence. If any of the parameters is a number, it will be converted to text for use in the sentence.

Concat() can take any number of parameters. Don't forget to include spaces unless you want to join parameters together into a single word. Parameters may be expressions. Numeric values will be translated into strings.

Concat("This ", "and ", 3/4, " of that.")

returns "This and 0.75 of that."

As of version 12, you should create \ParmPhrase structures rather then use Concat to generate all user-interface text.

StrLen

Returns the length of a text string measured as the number of bytes. This can be useful to know when you need to find some portion of text.

StrLen("Welcome to VTScada")

will return 18.

SubStr

Returns a portion of a text string, starting at a specified number of characters from the left. Be careful: counting starts at zero.

Providing the length (number of characters) to return is optional. If you don't, you'll get everything from the nth character to the end.

This function has the form:

SubStr(String, Start[, Length])

Those square brackets have a meaning: they enclose parameters that are optional. Do not type the square brackets when writing a function in your expressions.

SubStr("Good morning to you.", 5)

Will return, "morning to you."

SubStr("Good morning to you.", 5, 7)

Will return, "morning"

Locate

This function locates a substring within a longer line of text, returning the location of that substring as the number of bytes from the beginning. Counting begins at zero, therefore if the substring is at the beginning of the longer string, 0 is returned. If no match is found, then -1 is returned.

You can specify a start point, which is useful if the substring occurs several times and you want to find all of them. You just have to run the function several times, starting one character to the right of each successive match.

You can also specify whether you want a case sensitive match or not. (Case sensitive is the default.)

Locate("Big haystack with a needle", 0, "needle")

returns 20

Locate("Big haystack with a needle", 0, "Needle")

returns -1

Locate("Big haystack with a needle", 0, "Needle", 1)

returns 20

Practice with text expressions

This is a moderately advanced example, but classroom experience indicates that it's almost always the first thing that people attempt to do with the information presented so far. Someone will want to use a text function to generate any given tag name on the fly within an expression. Something like...

Concat("[AlarmPriority", x, "]\Description")

...to retrieve the description of a given Alarm Priority tag. This doesn't work.

Fortunately, there's another way to specify a tag. You can use the Scope() function, which takes any expression that evaluates to a tag name. You may have already encountered Scope() if you had a typo in a tag name when trying to refer to that tag. [Typo Tag Name] is replaced by Scope(Self, "Typo Tag Name")\Value. "Scope" means "Look", the first parameter says "where", and the second parameter says what to look for. "Self" simply means "here", which might not work in all situations, so you can be more precise by specifying the top-level container for all tags, which is \VTSDB. In the context of an expression written within a tag, the backslash is required in front of VTSDB in order to step out of the tag and look for the parent object.

So, for example,

Scope(\VTSDB, "AlarmPriority0")\Description

The quotation marks are around the tag name to tell VTScada that this is the text to look for, not the name of some variable containing the text to look for. If you use a function that returns text (like Concat does), you don't need to wrap extra quotation marks around it. It's text.

Concat("AlarmPriority", X)

Assuming that x is a variable containing a number from 0 to 4, this will return the name of an AlarmPriority tag as text, which is what the LocalScope function needs for a parameter.

However, there's still a problem... What you'll get won't be the description of the tag, it will be the phrase identifier key for the description. You'll need to do a look-up on that key to get the description by calling \GetPhrase(). (Note the backslash in front of \GetPhrase.)

  1. Create an I/O tag named X using the Discrete data type and with a Scaled Process Data Max set to 4. No I/O device or I/O address will be used.
  2. Draw X on the Overview page as a Numeric Entry widget.
  3. Create another I/O tag using the String Calculation data type.
  4. Give it an expression that returns the description of any specified Alarm Priority tag.
    Your expression should use [X], created in step 1, to get the priority number.
  5. Draw the tag on the Overview page using a Draw Text widget, placing it near the Numeric Entry widget.
  6. Switch to operator mode and put numbers 0 through 4 in the numeric input widget.


Time and Date Functions in Expressions

You might use time and date functions for many reasons: as part of a display, to act as a trigger, or to query history. The following is offered as a guide, without listing all the available Time And Date functions.)

In code, VTScada uses numeric timestamps that represent the number of seconds since January 1, 1980 (known as the Unix epoch). For any given time, note that there is both a UTC value and the local time zone value. Any operation that reads from or writes to the Historian must use UTC. You and your operators will probably prefer working with local time, expressed in a form such as "Friday, February 13, 2026 at 9:58 am. Tools are available for all formats.

If your expression needs to find the current time or date, use one of:

Now(interval) | Returns the number of seconds elapsed so far today, updated every (interval) seconds.
Time(seconds, format) | Formats the number of seconds since midnight into a form that's easier for a human to read and understand. For example, Time(Now(1), 4) The format codes can be found in the reference section of the documentation.
Today() | Returns the number of days since January 1, 1970.
Date(days, format) | Translates the number of days since Jan 1, 1970 into a human-friendly format. For example, Date(Today(), 4)

The function, CurrentTime(), will return the total elapsed time in seconds to three decimal points since January 1, 1970. You can control whether the return value uses the local time or the UTC time with an optional parameter, where the default is to return the local time. Again, all Historian operations must use UTC time exclusively.

But note that CurrentTime() works only in script mode and not in steady state. There are two options for obtaining the current time when working in steady state. The first method is to calculate it to the nearest second:

Today() * 86400 + Now(1)

The second method is to create a Workstation Status Tag and below that add an I/O and Calculations tag in analog mode, with the address Expression:CurrentTime() The scan interval of the I/O tag will set the frequency at which the expression is refreshed, but note that this will be relative to whenever the tag is restarted, not a even interval of seconds.

When creating expressions for reporting purposes, including work with the HDV, it is common to require start time and end time boundaries. For these you should consider using the TimeUtils library, which works in both script and steady-state.

To create a time-based trigger, consider using any of:

AbsTime(enable, interval, offset) | Becomes TRUE when any repetition of intervals since midnight, plus an offset, is reached.
TimeArrived(timestamp) | Returns TRUE when the specified UTC timestamp is reached.
TimeOut(enable, seconds) | Returns TRUE when the enable parameter has been TRUE for an interrupted number of seconds.
RTimeOut(enable, seconds) | Returns TRUE when the enable parameter has been TRUE for a cumulative number of seconds.

More About Formatting

Having the number of elapsed seconds since a given reference point is useful to a computer, but not easy for humans to read. The Time() and the Date() functions are available to turn those seconds into a more friendly form. To use them, you will need to refer to a table of available formats to select the one you want.

In general, the Time() function looks like so: Time( Timestamp, Format Flag)

To obtain the current time, you could use any of the following (examples assume that it's 9:35 p.m.)

Time( Now(1), 2) ---> 21:35:00

Time( Now(1), 7) ---> 09:35 PM

The formatting codes and formatting strings can be found in the reference section of the documentation.

Examples:

Assuming that today is Monday, Aug 13th, 2012, then:

Date(Today(), 3)

... yields, "08-13-12"

Date(Today(), "dddd MMM dd, yyyy")

... yields, "Monday Aug 13, 2012"

Turn a timestamp into a human-friendly date and time

An example earlier in this topic showed how to calculate a timestamp with Today() and Now(). To convert in the opposite direction to turn a timestamp into a date and a time, you need to know how many times 86400 goes evenly into the number. Simple division, truncating to the nearest integer will give you that.

Int(SomeTimestamp/86400)

You also need to find out how many seconds remain for the portion of time measured into the day. You can do that with the modulus division operator, %, which returns the remainder. For example...

SomeTimestamp % 86400

...returns the number of seconds into the current day, much like the Now() function.


Triggers in Expressions

The AbsTime() function (for example) will return a TRUE value when a given time interval has passed. This is a handy feature if you want to schedule an event to occur every hour on the hour, or perhaps every morning. Note that, when used in an expression (as opposed to a VTScada script module), the AbsTime function does not reset itself to false.

The format for the AbsTime() function is:

AbsTime(Enable, Interval, Offset).

  • The first parameter, Enable, allows you to switch the function on and off. If Enable evaluates to FALSE, then the AbsTime function will be switched off. Otherwise, it will be on.
  • The second parameter, Interval, gives the time in seconds to wait between events. Note that this is an absolute time, not an elapsed time. (Hence the name of the function.)
    If you want an expression to run every 24 hours, you would set the interval to 86400. If hourly, set the interval to 3600. In any case, the interval must be greater than 0.
  • The third parameter is an offset, measured in seconds to wait after the interval has been reached. If you want your expression to run at five minutes past the hour, every hour, then you would set the interval to 3600 and the offset to 300.

Resetting functions in expressions

AbsTime (and other triggering functions) would be much more useful in expressions if you could make them reset automatically. Fortunately, there's an way to do that: Enclose the trigger within a Latch() function.

The Latch() takes two parameters. When the first parameter becomes TRUE, the overall Latch function becomes TRUE. When the second parameter becomes TRUE, the overall Latch function, including both parameters, resets to become FALSE.

Example:

Latch( AbsTime(1, 10, 0), AbsTime(1, 10, 5) )

On any ten-second mark (0, 10, 20, 30 ...) the first parameter will become TRUE. Latch will become TRUE. On any ten-second mark, offset by five seconds (5, 15, 25, 35 ...) the second parameter will become TRUE. This will reset the Latch to FALSE. The result is a metronome of sorts, toggling on and off every five seconds.

If using an expression that sets opacity to zero, it may be helpful to also check whether you're viewing that object in the Idea Studio or in the operator view. Do so with ParentWindow()\Editing For example:
ParentWindow()\Editing || Latch(AbsTime(1, 1, 0), AbsTime(1, 1, .5))

Strobe Light

  1. Draw a filled circle on a page.
  2. In the properties dialogue for that circle, open the Opacity option.
  3. Use an expression similar to the earlier example that will make the opacity toggle between true and false.

Noticing when a value changes - Watch()

A very common situation is that an expression needs to react when a change occurs. The "log on change" feature of the logger tag is an example of this at work.

The Watch() function provides you with a means to do this in your calculation tags. The format is as follows:

Watch( InitialValue, Parameter1, …)

You can watch as many parameters as you need. The InitialValue is the only mandatory parameter, and is commonly set to either 1 or 0 to specify the Watch function's initial state. For most expressions outside of a VTScada script code module, the initial value is typically set to 0.

Whenever any of the watched values change, the Watch() function will return True.

It's important to understand that there is no built-in deadband for specifying that a value must change by a certain amount before a Watch() is triggered. Even the smallest change will count.

Note that, as seen with the AbsTime function, the value does not automatically re-set back to its initial value when used in an expression. The Watch() function is best used in combination with the Latch() function, described earlier.

The Watch() function makes a very useful trigger, as it allows you to monitor any other tag (or expression, or ...) anywhere in your application.


Add Functions to Your Application's Library

The Function Selection Dialog, which helps you build expressions in tags and widgets, comes with several functions that are not part of the VTScada library. Advanced developers can create their own functions, which will then be available in the Function Selection dialog.

To write new functions, you will need an understanding of the VTScada scripting language that goes well beyond the expressions used in tags and widgets. You must know and understand features such as states, launched versus called modules, action triggers and more. Review Scripting Fundamentals (Hello World!) and (in particular) Launched Versus Called Modules before proceeding.

A poorly-crafted function, if it works at all, can consume excessive amounts of CPU and memory resources.

Preparation: Add an empty source file to your application.

Follow these steps to create a stub for your new function and declare it within the application. After successful completion of these steps you can focus your effort on writing your function.

The steps will vary depending on whether your application was created before or after the release of VTScada version 12.1. Newer applications will have a (FUNCTIONS) class within AppRoot.SRC. If working in an older application, you must add that class to your AppRoot.SRC file.

  1. Start your favorite text editor and create a new file.
  2. Add a comment line to the top of the file as follows:
{====================== NewFunctionName ================================}
  3. Save the file to your application folder, naming it whatever you want to call your function, with a ".SRC" extension.
    (Optional: you might choose to create a subfolder, in which to store your functions. Not shown in this example.])
  4. Use your text editor to open the file, AppRoot.SRC, found within your application's folder structure.
  5. If the application was created using VTScada version 12.1 or later, locate the class section, [(FUNCTIONS)]
    If the application was created before version 12.1, create the class section as shown in the following example.
  6. Declare your new function within the (FUNCTIONS) class as per the following example.
    If you saved your function within a subfolder, include that path with the file name.
[(FUNCTIONS)
  NewFunctionName   Module  "NewFunctionName.SRC";
]
  7. Save the file.
  8. Open the VTScada Application Manager and use the Import File Changes tool.
  9. Ensure that your source file is selected to be added.
    If not, check that the file is not empty (this is why you added a comment) and that the file has the extension, ".SRC".

Write Your Function

For guidance on how to write clear and easy-to-maintain code, refer to the Style Guide for VTScada Code, provided within the documentation.

Step 1:

All VTScada modules should begin with a comment block that describes its purpose. You are strongly advised to add one, referring to the Style Guide for VTScada code.

Step 2:

Declare any parameters that will be needed. You may attach metadata to each parameter to control how VTScada will prompt for it. For example, this prompt for Substring parameters asks for text, a number, and an optional numeric.

Metadata can contain any of the following keywords:

Units

Must be a phrase key such as "secondsUnitsLabel"

Qualifier

Only one qualifier is available: "Optional".

Type

Any of:

  • Status (ie Boolean)
  • Short
  • Long
  • Double
  • Text
  • Object

If a type is not defined either in the parameter declaration or the metadata, the function editor will impose the desired parameter type of the calling function on it, which can yield unexpected results.

It is strongly recommended that defining a type in a custom function be considered non-optional.

Subtype

Adds clarity to the type definition. For example, to provide a color, the type is text in the form, "<FFFFFFFF>". You would want to show the color picker tool rather than a text edit tool in this case, therefore you must specify that this text is a color using the subtype. Similarly for tags, you might specify the Type as "object", but to only allow Digitals (group) or font tags (tag type) these can be specified in the subtype. For a list of tag types, it is possible to specify an array here as well.

Specifying Subtype:Color for Type:Text and Subtype:TagType/TagTypes/Group for Type:Object are the the most common uses of subtype.

Example 1: Single keyword

Parm1 <:”Optional”:>

Example 2: Multiple keywords must use JSON formatting

Parm1 <:"{""Units"":     ""secondsUnitsLabel"",
          ""Qualifier"": ""Optional"",
          ""Type"":      ""Object"",
          ""SubType"":   [""IO"", ""Drivers""]}":>

Step 3:

Declare any variables that will be needed. These will include the following required and optional declarations for user-defined functions.

❯ (Required) Add the following shared variable:

Shared FunctionLib(LIBRARIES);

❯ (Required) Use the Languages panel of the Application Configuration dialog to create a phrase for the function label, and copy the resulting phrase key. Use that phrase key to declare the label for your function as follows:

Constant DrawLabel = "CopiedPhraseKey";

❯ (Required) Declare and initialize the constant, FunctionUsage. This is a bitwise parameter that controls the whether your function appears in the function selector for a given context. (Script, steady state or tag configuration.) Being a bit-wise value, you may set any combination of bits in this constant.

  • Bit 0 - Script
  • Bit 1 - Steady State
  • Bit 2 - Tag Context (tag properties dialogs)

Importing changes to functions that operate in script may have unexpected results, therefore an application restart is required. Steady state functions will update immediately, therefore functions defined with steady state usage and no script usage can be modified without requiring an application restart. FunctionUsage is relevant only to the Function Library.

Constant FunctionUsage = 0b111 { Available in all contexts. };

❯ (Optional) To ensure that your function is included in the correct filter groups of the Function Selection dialog, add the relevant labels as follows:

{ Function keyword(s) }
[(1)
  TextLabel;
  MathLabel;
]

The existing labels for the filtering groups are as follows.

  • AlarmLabel
  • CountersLabel
  • DateAndTimeLabel
  • LogicalLabel
  • MathLabel
  • MouseLabel
  • NetworkLabel
  • TextLabel
  • VariableLabel

You may add your own by creating phrases and using the phrase key within the preceding declaration.

Step 4 :

Write your function.

Your function must work equally well in both Script and Steady State. Referring to the scripting chapters of the documentation, review the topic Launched Versus Called Modules, paying close attention to Callable Subroutines .

Example Functions:

{============================ PercentDifference ==============================}
{ Returns the percent difference between two values                           }
{=============================================================================}
(
  Value1 Double               { First Value                                   };
  Value2 Double               { Second Value                                  };
)
[
   { Function Library required variables }
  Shared FunctionLib (LIBRARIES);
  Constant DrawLabel = "PercentDifferenceLabel";
  Constant FunctionUsage = 0b111 { Available in all contexts. };
   { Function Keyword(s) }
  [(1)
    MathLabel;
  ]
]

Main [
  Return(Abs(Value1 - Value2)/Value2);
]

{================================= ToggleVal =================================}
{ Returns a TRUE or FALSE toggling at a provided period                       }
{=============================================================================}
(
  Period <:"{""Units"": ""secondsUnitsLabel""}":> Double
                                    { period at which to toggle on/off        };
)
[
   { Function Library required variables }
  Shared FunctionLib (LIBRARIES);
  Constant DrawLabel = "ToggleValueLabel";
  Constant FunctionUsage = 0b111 { Available in all contexts. };
   { Function Keyword(s) }
  [(1)
    LogicalLabel;
  ]

  PROTECTED Value = FALSE;
]

Main [
  If AbsTime(TRUE, Period/2, 0);
  [
    Value = !Value;
  ]

  Return(Value);
]


Scripting Fundamentals (Hello World!)

The VTScada programming language lies behind nearly everything that you see in an application. There are many reasons to learn this language, including:

  • To fix damaged pages or widgets.
  • Create a custom configuration panel (properties dialog) for your user-defined tag types.
  • Create new ways to display information.
  • Create new types of report.
  • Create new functions, device drivers, services...

Briefly, code is kept in units called "modules". (Refer to Module Structure for a detailed description of what follows here.) For example, every VTScada page is a module, with each stored in a separate file on disk. So is every tag type, every widget template, every file that ends with the extension ".SRC". Those source code files are compiled into ".RUN" files before being used by VTScada.

The executable code within a module is written as a series of statements. Every statement must end with a semicolon. A single statement may continue over several lines in the source code file and may include many expressions as well as comments.

Here is how to write "Hello World!" using a single statement that represents text created using the Idea Studio:

GUIText(144, 151, 304, 131,
        1, 1, 1, 1, 1 { Scaling              },
        0, 0          { Movement             },
        1, PickValid(\ScaleDisplayContent, 0) { Vis., Font Scaling },
        0, 0, 0       { Selectability        },
        Brush("<00000000>", 0, 1), Pen("<FF000000>", 1, 1),
        Scope(VTSDB, "LabelFont", TRUE)\Value,
        3, 4,
        "%s",
        "Hello World!");

Statements must be placed in a named block called a "State". VTScada uses state-based logic, meaning that while one state is active (the pump is stopped) a certain set of statements run. When the state changes (the pump starts), a different set of statements run. Navigating from one tab to another in a configuration dialog is also an example of changing states.

Comments

Comments are enclosed in braces {curly brackets}. If inserting a comment within a statement, it is standard practice to keep it near to the variable or parameter to which it refers, placing any punctuation that divides one parameter from the next after the comment. For example, here is an example of variable declarations taken from a typical script application. Note that the semicolon is placed after the comment.

  System        { Provides access to system library functions };
  Layer         { Provides access to the application layer    };

Where to write code

This depends on the purpose for your code. Expressions, which are fragments of script code, can be added to tag and widget parameters while working inside the VTScada user interface. New code is often added to old code to extend an existing feature. For example, if you are building a new report, driver or service, you will create a new text file and put your code there. If you want to add new features directly to a page, or a widget, you would open the matching .SRC file and start typing, although take note that the code you add might not be compatible with the Idea Studio.

To ensure compatibility, ensure that your editor is set to save using UTF-8 encoding.

When creating new modules, you must declare them in the application's AppRoot.SRC file. If you are creating a new stand-alone utility, you might create a script application and write code in its AppRoot.SRC file.

Some of the examples in the following pages show code being added to a page (Overview.SRC) in a standard application.
Do not assume from this that pages are the natural home for all new code. When an operator closes a page, all code within it stops. If you are creating something that should run continuously while the application runs, do not put your code in a page.
The examples are designed to illustrate concepts as simply as possibly.

Hello World

(Do not experiment within a production application.)

  1. Using a text editor, find and open the file Overview.SRC, within your application's folder.
    (C:\VTScada\YourApplication\Pages\Overview.SRC)
  2. At the first line below Main [ add the following:
ZText(400, 100, "Hello World!", 3, 0);

Detail from Overview.SRC after adding step 2

  3. Save the file.
  4. In the VAM, click the Import File Changes tool for the application.
    If a prompt notifies you of a syntax error, repair it and try again.
    Always close the error dialog between attempts, otherwise older errors will continue to be shown after being fixed.
  5. Run the application and open the Overview page. The greeting should be displayed.
  6. Take a moment now to read the description of ZText.
    These notes could describe the parameters of the function, but that won't help you learn this language nearly as well as developing the habit of turning to the function reference.

ZText or GUIText? The Z-functions are fine when learning the language because they're simple to write. But when developing applications, you are advised to use the newer GUI-functions, which are compatible with the Idea Studio and far more powerful.


Script Applications

Most of the applications that you see listed in the Application Manager of a fresh VTScada installation are script applications. These are utilities that programmers use for examining, testing, and debugging their code.

Script applications do not have access to the user-interface tools of a standard application such as the Tag Browser, tag types, libraries, and the features of the display manager. Those come only with the VTScada Library layer. All standard applications are built on top of a layer that was created with the language described in this manual.

Script applications can be created by using the Advanced option of the Add New Application wizard in the VAM and setting the type to Script Application. You might create one when you might need a stand-alone utility without the features of a standard application. They are also very useful when learning the VTScada scripting language.

When working in a script application, it is common to write some or all of the code in the file AppRoot.SRC. Note that you would never do this in a standard application where AppRoot is used only to declare constants and modules. In a new script application, AppRoot will look like the following:

{============================ System ===============================}
{===================================================================}
(
  System             { Provides access to system library functions };
  Layer              { Provides access to the application layer    };
)
[
  Graphics      Module { Contains user graphics                    };
  WinTitle = "User Application" { Window title                     };
  RunningOnVIC       { TRUE if this is a VIC session               };
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);
]

<
{======================= System\Graphics ===========================}
{ This module handles all of the graphics for the application       }
{===================================================================}
Graphics

Main [
]

{ End of System\Graphics }
>

The primary module of this application has one state, Main. This calls the Window function, which displays a window on the screen having the properties defined in the function call.

One submodule is defined: Graphics. The Window function in the primary module calls this submodule. Any graphics code that you write in the Graphics submodule will be displayed in the window.


Workspace for Script Applications

Many of the concepts presented in these notes are accompanied by examples that you can try. Depending on the example, you will need either a script application or a standard application to work within. Instructions are provided here for preparing a script application. These instructions assume that you have a typical VTScada installation, located on your hard drive at C:\VTScada. If not, adjust the file path as required.

To create a standard application for use with some examples, refer to Workspace for Expressions

Create a Script Application

  1. In the VTScada Application Manager, start the Add Application Wizard.
  2. Select the Advanced option and click Next.
  3. Ensure that Create New is selected and click Next.
  4. Name the application. (Script 1 is suggested.)
  5. Use the drop-down type selector to select Script Application, then click Next.
  6. Deselect the Start Application Now check box before clicking Finish.
    For each example, you will need to edit code before running the application.

Check that the icon matches. If not, you missed step 5.

Your application will be created. Most examples will ask you to use a text editor to modify the file AppRoot.SRC, which can be found at C:\VTScada\Script1, assuming that Script 1 is the name that you gave this application.

The default window background color is black. Black is also the default color of text in several user-interface tools that you might display in that window. Therefore, you might want to change the window color to gray VTScada supports three different methods of specifying a color. Although uncommon, you can refer to Windows system colors to make your graphics match Windows dialogs. There is a color palette of 255 shades, each of which can be specified by number. And, you can use aRGB values, where the transparency and the color are set using four pairs of hexadecimal values, always written within quotation marks and angle brackets. 1. Do so by modifying the Window call as follows:

Setting the window color to gray

The 7 comes from the VTScada Color Palette, which dates from a time when only the most expensive graphics cards supported a full 256 colors. While you are likely to use "<alpha-RGB>" colors in most situations, the palette remains a useful tool.

When making changes to a script application, you must stop, recompile, and then restart the application each time to see the changes. In a standard VTScada application, you may or may not need to restart the application, but you will always need to import file changes. When a restart is necessary, you will be prompted.

Write Code

  1. Using a text editor, open the file AppRoot.SRC within the application folder. (C:\VTScada\Script1\AppRoot.SRC)
  2. Modify the code to add a ZText function at about line 38 - just within the declaration of the Main state.
    Note that this is being added within the Main state of the Graphics submodule. More about submodules soon.
Main [
   ZText(100, 100, "Hello World!", "<FF000000>", 0);
]
  3. Change the title from "User Application" to "Greeting Application".
    Part of the exercise is to identify the line where this change is to be made.
  4. Use the Import File Changes in the VAM to recompile the application and then start it.

Take a minute to learn a bit about how VTScada displays text and graphics. Continuing in the same application, change the statement as follows.

  5. Delete the ZText statement and replace it with a ZBar statement as follows:
ZBar(100, 200, 150, 50, "<FF0000FF>" { Blue });
  6. Stop the application, "Import File Changes", then restart.
  7. Change the color of the bar to green.
  8. Draw a second rectangle so that the two together make a plus sign +.
    (Hint: This is just a matter of changing the four coordinates. But you will have to refer to the documentation for ZBar to understand how those coordinates work.)
  9. Remove the second rectangle and draw a ZBox that will create a red border around the first rectangle.

Key Points

  • Script applications are especially useful when learning the VTScada script language. They give you a simple module structure, a window, and the rest is yours to create.
  • While the code in AppRoot.SRC of a script application is minimal, it is also a complete example of how every module throughout VTScada is built.
  • Changes to VTScada code must be imported and compiled.
  • The documentation is your friend when using functions.


Module Structure

Executable lines of code are called "statements". These can be written over several lines of the file, but always end with a semi-colon. Statements must be written inside the brackets that enclose one of the following sections of a module: parameters, variables or states.

Here is an example showing the structure of a module with comments but no code. Descriptions of each numbered item follow the example.

{========================== MyFile.src ============================}
{ 1. This is a sample module                                       }
{==================================================================}
(
  { 2. Parameter section: }
)
[
  { 3. Variable declarations. }
]

State1 [
  { 4. State section. All the executable code in a module lives
      inside states. The first state encountered will run. }
]
{ This line is outside any state. Write no code here.      }

State2 [
  { 4. Another state. Will run only if control is passed to it. }
]

< {5. Submodule starts }
MySubModule
{ Content as above. }
>
{======================= End of File ========================}
  1. A comment section, describing the module.
    While not strictly part of the module's definition, and containing no statements, the comment block is a vital component from the point of view of good coding practice. Comments are enclosed in braces, also referred to as curly brackets {}. You may scatter comments throughout your code.
  2. Parameter section, enclosed in parentheses ( ).
    These are referred to as the "declared" or "formal" parameters. Parameters used in the call to the module are referred to as the actual parameters. Actual parameters are matched to declared parameters in order from left to right.
    If the call to a module has fewer actual parameters than declared parameters, the extra declared parameters will be set to Invalid. If there are more, you can access those parameters within your module by using the Parameter() function, even though there were not declared as part of the module's formal parameter set.
    Declared parameters can be given default values using an initialization state in the module definition, via a PickValid() call. Attempting to set a default value for the declared parameter when declaring it is regarded as bad form. Behavior in that case will differ depending on whether the actual parameter was missing or provided as a variable with an Invalid value, which is likely to cause confusion and errors.
    Parameters are passed by value or by reference according to how the module is started. (Launched Versus Called Modules).
    You can assign metadata to module parameters when declaring them. See: Parameter Metadata
    You can also enforce value types for parameters. See: Parameter and Variable Type Checking
  3. Variable section, enclosed in brackets [ ].
    All variables and submodules used in the module must be declared here. Data types are attached to whatever value is stored within the variable rather than to the variable itself, therefore there is no need to specify data types as part of the declaration. The exception is the declaration of submodules. These should be declared in the variable section and should be followed by the keyword "Module". Additionally, if the submodule is stored in another file, that file name must be provided. As with parameters, you can enforce type checking. See: Value Types and Variable Storage, Retention, Access
  4. State Sections.
    Each state in the module begins with the name of the state, followed by brackets that enclose the code of the state. The first state found in the module will always be the first state to run. It is commonly called "Init" or "Main", but the name has no special meaning. Those words are simply used by convention to increase readability.
  5. Submodules (optional), enclosed in angle brackets < >.
    These are also referred to as "child modules". The first module within any file should not be enclosed in angle brackets, but each child module within the same file must be. Within each submodule, the structure is the same as described in the preceding points.

Not shown:

  • Reference box coordinates. Used only in modules that define graphics such as widgets. The reference box coordinates are placed before the parameter section in the module file and will contain four numeric constant values in the form:

(Left, Bottom, Right, Top)

If the purpose of a module is to display a graphic object, it is useful to define a reference box. This defines the rectangle to be occupied by all graphics drawn by the module, possibly including a margin around those objects. If a reference box is not defined, then VTScada will automatically calculate one based on the graphics being displayed. Leaving the reference box to be calculated automatically can have a negative effect if the module contains various states with different graphic statements. If VTScada must re-calculate the reference box as the module changes from state to state, transformations applied to the display can be affected.


Parameter Metadata

You can assign metadata to module parameters when declaring them. This technique is used to ensure that extra information about the parameter is assigned when the module opens and before any of the state code runs.

Parameter metadata is declared using the metadata assignment operators:

<:  :>

For example, given the module MyModule, with parameter A, a metadata value could be assigned as follows:

<
MyModule
(
  A  <: 5 :>;
)

The function of the assignment operators is similar to that of the SetVarMetaData() function. The values can be read using GetVarMetaData().

The most common use of parameter metadata is found in tag modules. The SQL data type of each parameter is assigned in the parameter declaration section:

(
  Name        <:TagField("SQL_VARCHAR(255)", "Name",        0 ):> };
  Area        <:TagField("SQL_VARCHAR(255)", "Area",        1 ):> };
  Description <:TagField("SQL_VARCHAR(255)", "Description", 2 ):> };
)

The SQL database conversion data for each parameter is recorded by instantiating TagField structures and assigning them in the parameter declaration section.


Parameter and Variable Type Checking

If you need to ensure that the value passed to a parameter or a variable has only a certain type, you can do so. Values that are not of the correct type will be cast if possible, otherwise set to Invalid.

To enforce type checking, include the required type as part of the declaration. For example:

<
SubmoduleWithTypeChecking
(
  String1 Text;
  String2 Text;
  Short1 Short;
)
...

If this module is called with values as follows:

Main [
  SubModuleWithTypeChecking("ABC", 123, "DEF", 456);

then String1 will be set to "ABC", String2 will be set to "123", Short1 will be Invalid and Short2 will be 456. The number 123 can be cast to text, but "DEF" cannot be cast to a short.

The compiler will accept the following value types for your declarations:

  • Status (ie boolean)
  • Short
  • Long
  • Double
  • Float (same as double, deprecated)
  • Text
  • Buffer (same as text, deprecated)
  • Object
  • Reference (has no effect, deprecated)

Object-type variables / parameters can be further narrowed-down to objects whose modules have a name within a specified set of names. For example:

MyAnalogTag Object<AnalogInput, AnalogStatus>;


Store and Declare Modules

Modules are stored in text files, each ending with the extension ".SRC". As part of compilation, a .RUN file will be created for each .SRC file.

The most important module file is AppRoot.SRC. A file with this name will exist in every VTScada application. In script applications, AppRoot can (and often does) contain executable code. In a standard application, AppRoot never contains executable code. It's role is to be a starting point, containing the following:

  • Declarations of the global constants and variables.
  • Optional structure definitions.
    (For example, tag parameter metadata is typically defined in AppRoot.)
  • Declarations of modules local to this application.
    This includes all of the application pages, user-defined tags and widgets, custom services, drivers, reports and more.

When you create new modules for a standard application, you must declare them in AppRoot. The form of that declaration has four parts:

  1. The group within which the module is being declared. Modules that are pages go into the [(PAGES) ... ] group. Modules that are reports go into the [(PLUGINS) ... ] group.
    Most modules that you write will be either plugins or services.
  2. The name to be assigned to that module. Any legal name may be used.
  3. The keyword, Module.
  4. The path to (and name of) the .SRC file containing the module's code. This is a text value and therefore must be enclosed in double quotes. The path is always relative to the application folder.

Like all statements in the VTScada language, this declaration must end with a semicolon.

Use care when naming your modules. Try to avoid any VTScada names like AnalogInput.

Add a New Module to an Application

Preparation: You will need a module. Create a text file named ColorCycle.SRC in main folder holding your application, then copy or type the following into it:

{=========================== ColorCycle.SRC ==================================}
{ A simple demonstration module. Displays a message that changes              }
{ color every two seconds                                                     }
( {Parameters...}
  Message             { Optional paramter for the text to display             };
  Xcoord              { Optional X & Y location for the message               };
  Ycoord;
)
[ {Variables...}
  NextColor = 0       { Next color to use from the VTScada palette.           };
  LocX                { Local storage of the coordinates                      };
  LocY;
]

Init [  { Set defaults for the parameters}
  If 1 Main;
  [
    Message = PickValid(Message, "Hello World!");
    LocX    = Max(10, PickValid(Xcoord, 100))  { >= 10 pixels from the edge   };
    LocY    = Max(55, PickValid(Ycoord, 100))  { Room for the title bar       };
  ]
]

Main [
  ZText(LocX, LocY, Message, NextColor, 0);
  If Watch(1, \TwoSecondFlasher);
  [
    NextColor++;
    IfThen(NextColor > 255,
      NextColor = 0;
    );
  ]
]

This extremely simple module can be added to the code of any page, where it will display a message. The default message is "Hello World!", located at 100, 100, but you can provide your own message and coordinates as follows: ColorCycle("My message", XLocation, YLocation);

If you get an error message when running the Import File Changes command, check your file changes carefully for punctuation and placement. Ensure that you did not skip a step.

Add a module to a standard application:

  1. Open AppRoot.SRC of your application in a text editor.
  2. Within the square brackets of the Plugins group, add the following line:
  ColorCycle         Module "ColorCycle.SRC" { Display a message       };

(If this were a page, you would add it to the [ (PAGES) group. If a Widget, the [ (65282) group. This module does not qualify as either of those, or any other group designation, therefore Plugins is the best choice.)

Example:

  [ (PLUGINS)       {===== Modules added to other base system modules =====}
    ColorCycle  Module "ColorCycle.SRC";
  ]
  3. Save AppRoot.SRC and close your text editor.

For the next two steps, if either the Pages folder or Overview.SRC (or both) does not exist, run the application, open the Idea Studio, then close the Idea Studio. The folder and file will be there.

  4. Navigate to the Pages folder of the application.
  5. Use a text editor to open the file, Overview.SRC
  6. Within the Main state block, add the following line:
  ColorCycle();

(You might choose to add your own message and coordinates, as described in the exercise preparation notes.)

Example:

Main [
  Return(Self);
  ColorCycle("This is a message", 300, 200);
  7. Save the file.
  8. In the VTScada Application Manager, select the Import File Changes button for this application.
  9. Select "Yes" when prompted to import ColorCycle.SRC.
  10. Run the application.


Class Declarations for Modules in AppRoot

Modules are declared within class groups in AppRoot.SRC. These control how the module will be treated by the application. For example, all pages must be declared within the [ (PAGES) ...] class. All user-defined tag-types are declared in the [ (POINTS)... ] class, where "point" is another term for "tag".

Use the following list to decide where to declare your new modules. In each case, the text in bold should be used as the class designation, according to the following example:

[ (PAGES)
  Overview Module "\Pages\Overview.SRC";
]

(CONTRIBUTORS)

Modules that plug into this one.

(CONTAINERS)

Modules that this one plugs into.

(PRIORITYSTART)

Items that are pre-started

(FUNCTIONS)

Modules included in the function library

(65282)

User-Defined widgets. VTScada will populate this list automatically with each new widget that you create.

(POINTS)

User-defined tag templates. Similar to user-defined widgets, each time that you run Create New Type on a Context tag, a new module declaration will be added to this class for you.

(GROUPS)

Modules that are collections of tag types such as "Analogs" and "Digitals". It is extremely unusual to declare your own tag groups, but if doing so, the module for that group definition must be declared in this class.

(LIBRARIES)

Modules that contain a listing (library) of widgets. This is a legacy feature. Rather than explore it, you are advised to use custom folders in the Widgets palette.

(GRAPHICS)

Modules that are shared widgets for tag types. Trihedral does not document how to create custom widgets from code. You are advised to create custom widgets using the Idea Studio, then modify the resulting .SRC file if needed.

(PAGES)

Application pages. VTScada will automatically add a module declaration to this class for every new page that developers create in the application.

(SERVICES)

Service modules start when the application starts, and then run continuously. As an example, a custom security service would be declared in this class. See: HideVAM Based on Security Privileges

(PLUGINS)

By far, the most commonly used class for user-defined modules. Examples include custom reports, custom tag configuration panels, modules for use with Script tags, etc.

(PRIORITYSTART)

Modules that are to be started before the application loading process finishes. The VTScada Time Synchronization Service is an example. It is unlikely that you will have a reason to add modules to this class.

(SESSIONSTART)

Each SESSIONSTART module is launched using the user's session object as its parent / caller. That means that any windows created from that SessionStart object will display on the UI where the session is being displayed: on the machine running VTScada, a VIC, or an Anywhere Client. (See also: ActiveWindow)

(SHUTDOWN_HOOK)

Any module in this class will run automatically when during the application shutdown process. These may be used to write extra information to disk, send a notification, or perform any other task before the shutdown process completes.

Note: In the case of a shutdown caused by the time limit of a trial license expiring, the shutdown_hook module can delay shutdown by up to ten minutes, but cannot prevent that shutdown.

(TSERVICES)

Modules that are to be run as threaded services. For use only by advanced VTScada programmers.


States and Steady State

The executable code of a module must be contained within one or more named states. A state is a named block of executable code.

A module may contain many states but only one state in a module can be active at any time. Code in other states does not run until execution is passed from one state to another. You have seen this in action when configuring VTScada tags. Each tab within the configuration dialog represents a separate state. When you open a tab, execution changes to the matching state, drawing the contents for that tab. The content of the other tabs / states is not seen because those states are not active.

TCP/IP Port tag - connection tab

The Connection state is active.
States for ID, TLS and Display are not and therefore are not seen.

State Naming Rules

All states must have a unique name. The name may be the same as the module's name.

  • State names must be a single word with no spaces.
  • Use an underscore or PascalCase (also called UpperCamelCase) to indicate multiple words
  • State names may not include most symbols, such as #&-+=<>{}[](), etc.
  • State names are not case-sensitive. "Main" is the same as "main".
  • State names may be numeric, so long as you do not include a negative sign.

In general, state names should be:

  • Short
  • Descriptive - of the state's purpose
  • Verbs - when the state performs a task

You will often see modules that contain states named "Init" and "Main". There is no functional significance to these names, but by custom, Init is used for initialization tasks and Main is used for the state that forms the main body of the module.

State Structure

A state is defined using a formal structure as follows. Note the square brackets that enclose the body of the state.

StateName [
  Statement1 { a line of executable code };
  Statement2 { another line of code      };
]

Order of execution - Steady State

When a module starts, the first state within that module will become active and each statement within it will run once. The order of the statements is relevant only for page and widget modules, where the last statement drawn appears on top of the graphics from earlier statements. This can be seen by examining the code of a page before and after changing the order of graphics in the Idea Studio. If you send something to the back, its statement will be shuffled to the beginning of the state. If you send something to the front, its statement will be shuffled to the end of the state.

After the initial run-through, and assuming that control is not then passed to another state, the currently active state enters a mode termed "steady-state". In essence, this is a form of event-driven programming and results in VTScada being extremely efficient. If a variable changes in value (perhaps a tag records a new value) then statements containing that variable will execute, but no others. This does not change the display order of graphics.

The module may contain other states, but these will never run until control is passed to them. When that happens, the previously running state ends, along with all submodules that were called into that state.

Other than for the display order of graphics, the order of statements within a state does not matter. For example, given a script application with the following code in its Graphics() submodule:

Graphics
(
  X = 2 { value to display  };
)

Main [
  X = 4;
  ZText(100, 100, Concat("The value of X is ", X), "<FFFFFFFF>", 0);
]
{ End of System\Graphics }
>

The message will read, "The value of X is 4".

But, if you change the order of the statements in Main as follows:

Main [
  ZText(100, 100, Concat("The value of X is ", X), "<FFFFFFFF>", 0);
  X = 4;
]

The message will still read, "The value of X is 4". It will not display 2, as you might have expected.

Tracing the order of execution in the second example, what happens is the following:

  1. The ZText displays the initial value of X, which is 2.
  2. X gets set to 4.
  3. This triggers the statement containing X as a variable to run again.
  4. The message now displays 4.

When working in steady-state, never write code that depends on statements running in a given order. You cannot predict the order of execution.

Infinite Loops in Steady State

Consider the following example:

Graphics
(
  X = 2 { a variable       };
  Y = 4 { another variable };
)

Main [
  X = Y + 1;
  Y = X + 1;
]
{ End of System\Graphics }
>

Each statement changes the value of a variable in the other statement, triggering that statement to run again. This is essentially an infinite loop and will "peg" a core of your CPU.

Similarly, the statement:

X = X + 1;

creates an infinite loop when written in steady-state, with X increasing continuously.

Double-Set Values

Because it is not possible to predict the order of execution of statements in steady-state, VTScada does not allow you to write two statements that both set the value of the same variable. For example:

Main [
  X = 1;
  X = 2;
]

This will compile and run, but the value of X will be Invalid rather than 1 or 2. Examined in the Source Debugger, it will appear as "double set", informing you of why it is Invalid. Whenever you have a variable that is set to Invalid when you are sure that it should have a value, look first for a double-set.

There is another way to write a double-set, which to the untrained eye does not look like a double set. Refer to Double-Sets with Called Modules:.

Functions and Steady-State

When selecting functions for use in steady-state code, take note of the "usage" description. If the usage is described as "script only", it cannot be used in steady-state.

Changing States

To move focus from one state to another, you may use either an action trigger or a ForceState() function. Action triggers are the more common of the two.

Build a Simple Script Application

If you have Script 1, from an earlier example, use that and start with step 9. Otherwise, begin with step 1.

  1. In the VAM, click the Add Application Wizard button.
  2. Select the Advanced option and click Next.
  3. Select "Create New" and click Next.
  4. Set the name to "Script 1".
  5. Set the type to "Script Application".
  6. Click Next.
  7. Deselect the Start Application Now button.
    Do not start the application until after the next set of steps.
  8. Click, Finish.

Check that the icon matches. If not, you missed step 5.

  9. Use a text editor to open the file,
    C:\VTScada\Script1\AppRoot.SRC.
  10. Examine this file, in light of what you have learned so far about comments, variables, states and modules.
    1. Identify the start, the name and the end of the submodule.
    2. Identify all states.
    3. Identify all variable declarations.
    4. There is one function call: Window(). Open the documentation for this function and compare the parameters listed there to what you see in AppRoot.SRC. In particular, note the relation of the submodule, Graphics, to the function call, Window
  11. Modify the code as follows. (Changes begin at about line 36.)
<
{======================== System\Graphics ==========================}
{ This module handles all of the graphics for the application       }
{===================================================================}
Graphics
[
  X      { Input value  };
  Color  { Color to use };
]

Main [
   { Enter a value from 0 to 9 using the keyboard }

  X = Keys(1, 1);
   { Check for initial null and substitute a value }
  Color = X == "" || !Valid(X) ? 7 : X;
   { Display greeting with selected color }
  ZText(100, 100, "Hello World", Color, 0);
]

{ End of System\Graphics }
>
  12. Save your work, then in the VAM, click the Import File Changes button.
  13. Provide a comment when prompted.
  14. Run the application.
  15. Tap the number keys from 0 to 9.

This demonstrates steady state. Each key press is caught by the Keys function and changes the value of X. Each change to the value of X causes the ZText function to refresh.


Action Triggers and Script Blocks

As a reminder, steady-state code runs once when the state is first opened, and then statements are triggered to run again when the value of a variable within that statement changes. The order of statements in steady-state code is of little importance.

But there are times when you need code to run in a predictable order; (first read a value, then remove spaces, then store the value, then read a new value...). You also need a way to move from being within one state (perhaps the "stopped" state) to another (perhaps the "running" state).

Both of these tasks are accomplished using the function If, which is an action trigger that can do any of:

  • Cause execution to move from one state to another. (For example, changing tabs in a tag configuration folder.)
  • Cause a script block to start execution. (See following topic.)
  • Execute the statements in a script block once, then move from one state to another.

Being a trigger, it depends on a conditional. The general format is as follows:

If some-expression-becomes-true NewState;
[
  X = X + 1;
]

Note that the If function is called in steady-state and (like all VTScada statements) ends with a semicolon. The square brackets immediately following the If statement mark the beginning and end of a script block. In this example, code within the script block will execute exactly once, then control will transfer to NewState.

When combining conditionals in the action trigger, pay close attention to the rules of operator precedence to avoid unexpected results.

Script Blocks

Code within a script block is not event-driven. Statements here will always run in a predictable order. A change to a variable or parameter within a statement in a script block does not cause that statement to execute again. You have control over the order of script execution using functions such as DoWhile, IfThen and others.

While a script block is active, no instructions outside of the block (but within the same state) will execute. The block will repeat unless there is a state transfer in the action trigger or until the conditional trigger becomes false. Between repetitions, other statements in the state have a chance to run.

Examples:

Change state without running a script block:

If some-expression-becomes-true NewState;

In this example, there is no script block. When the conditional expression becomes true, control moves from the current state to the named destination state.

Run a script block without changing state.

If X < 10;
[
  X = X + 1;
]

In this example, there is only a script block. Code within the block will execute again and again for as long as the action-trigger expression remains true. When writing an action trigger that does not transfer to another state, use great care to ensure that the conditional will change back to false. VTScada includes a set of automatically-resetting functions for use in this situation. For example, if you require a script block that will run a single time without transferring to another state, a common technique is to use the Watch() function as the trigger, with an initial value of 1. Watch(1) resets automatically, meaning that it will change to false after triggering within an If statement.

If Watch(1);
[
 { ...script code to be run once... }
]

Do both.

If 1 Main;
[
  X = 10;
]

Variations on this example are found throughout VTScada. The script block is guaranteed to run because the conditional is TRUE. But, the script block runs only once because there is a branch to another state in the action trigger.

Example: An Initialization State

A common feature of VTScada modules is to have an initialization state that sets values before handing control to a main state that does the work. In the following example, the initialization state obtains the current time for some purpose needed by the main state.

[ { variable declarations }
  TS { A time stamp, set upon startup };
]

Init [
  If 1 Main;
  [
    TS = CurrentTime();
  ]
]

Main [
  { ... code to do something with the start time ... }
]

Note the statement, "If 1 Main;". "If TRUE" is not something you would expect to see in most programming languages, but it makes perfect sense here. The If function is required because it is the bestThere is a function other than If to force a transition from one state to another. It should be used only in exceptional circumstances and is not even being named in this introductory topic. 1 available trigger to run a script block. The TRUE (i.e. 1) is required because the script block must run as soon as the Init state starts. This example is guaranteed to execute the code in the script block once and only once before moving from the initialization state to the main state.

When writing an initialization state such as the previous example, put all of your code into the script block. As soon as the action trigger happens, the script block will run and then control will transfer to the named state. Other steady state statements in the initialization state will stop, therefore there was no point to starting them in the first place. Any following the If are not guaranteed to run at all.

Race Conditions

It is important to watch for possible race conditions. For example, if a state contains two action trigger statements with identical conditionals but different actions:

If HighAlarm Shutdown;
If HighAlarm StartPump;

Both of these actions change to a new state on the same condition. It cannot be predicted which will execute first, and the final state will be either Shutdown or StartPump. This is called a "race condition", because the module depends on which action trigger wins the race.

Functions and Script Blocks

When selecting functions for use in a script block, take note of the "usage" description.

Example from the function reference.

If the usage is described as "steady-state only", it cannot be used in a script block. Note that VTScada contains a number of standard programming functions for control of execution within a script block, such as IfThen, WhileLoop, Case, etc.

Tab-like buttons

In this example, you will create two buttons that behave like a tabbed dialog. With each button press, a different message is displayed. Note that this example has identical code, repeated in several states. That's usually not considered good practice, but for the sake of the exercise we'll let it pass. Use copy-and-paste to save time.

  1. If you have the Script1 application from an earlier example, continue working with it, removing all the code you added earlier. Otherwise, create a new script application.
  2. Use a text editor to open the application's AppRoot.SRC file.
  3. Edit the file as follows:
{================================= System ====================================}
{=============================================================================}
(
  System                       { Provides access to system library functions };
  Layer                        { Provides access to the application layer    };
)
[
  Graphics               Module { Contains user graphics                     };
  WinTitle = "User Application" { Window title                               };
  RunningOnVIC                  { TRUE if this is a VIC session              };
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);
]

<
{============================= System\Graphics ===============================}
{ This module handles all of the graphics for the application                 }
{=============================================================================}
Graphics
[
  Current = 0                                      { Selected message         };
]
Switch [
   { Display the selected message }
  If Current == 0 Message0;
  If Current == 1 Message1;
]

Message0 [
   { Create a background for the message }
  ZBar(50, 550, 750, 50, 30 );
   { Display the message }
  ZText(250, 300, "This is the first message", 0, 0);

   { On button press, switch the message            }
  If WinButton(200, 100, 275, 80, 0, "Message 0", 1, 0) Switch;
  [
    Current = 0;
  ]
  If WinButton(300, 100 ,375, 80, 0, "Message 1", 1, 0) Switch;
  [
    Current = 1;
  ]
]

Message1 [
   { Create a background for the message }
  ZBar(50, 550, 750, 50, "<FFAADDFF>");
   { Display the message                 }
  ZText(250, 300, "This is the second message", "<FF000000>", 0);

  { On button press, switch the message            }
  If WinButton(200, 100, 275, 80, 0, "Message 0", 1, 0) Switch;
  [
    Current = 0;
  ]
  If WinButton(300, 100, 375, 80, 0, "Message 1", 1, 0) Switch;
  [
    Current = 1;
  ]
]

{ End of System\Graphics }
>


Latching and Resetting Functions

All functions and statements are reset when the state that contains them becomes active. Some functions that contain an "enable" parameter will reset when that parameter becomes true. For example, the AbsTime() function will not start counting time until its enable parameter becomes true.

Some functions can reset themselves. For example Latch(). The second parameter to this function is a "reset", which when true, resets the function for the next repetition. Any functions or expressions used for the two parameters to Latch() reset themselves individually when true.

VTScada includes a class of functions referred to as the "automatically resetting functions". These are designed such that their value will latch when set, and will not change with future parameter changes. AbsTime() is an example - after the designated time has arrived and the function becomes true, it will remain true until reset.

The automatically-resetting functions will reset when used as the action trigger of an If statement. For example, in the case of MatchKeys, an action trigger might watch for the operator input of a specific single key. If the intent of such an action is to perform an action once, such as increasing a set point by a fixed amount, then the action trigger must be false before the next time it is tested or else the script will be executed innumerable times for just a single keystroke. Because the MatchKeys function is automatically reset when the If statement containing it becomes true, the action script will execute only once when the key is hit.

Some functions, such as Latch, Toggle and Save, reset their parameters when they change to TRUE. For example,

Latch(TimeOut(TRUE, 10), ...)

will reset the TimeOut parameter after it reaches ten seconds.

You can design your own subroutines to be automatically-resetting or not. The difference is in the use of the Return() function within the subroutine. See the section Advanced Topic: Create Your Own Automatically-Resetting Functions. below for more instruction.

Examples:

LightOn = AbsTime(1, 10, 0)

When the next time interval arrives (any multiple of 10 seconds in this example), the light goes on and stays on.

If AbsTime(1, 1, 0);
[
  LightOn = !LightOn;
]

The light will switch on and off every second since the If statement resets the AbsTime function every time it becomes true. One second later, it becomes true again.

LightOn = Latch(AbsTime(1, 2, 0), AbsTime(1, 2, 1))

This is functionally equivalent to the previous example. The light flashes on and off each second. Note that a Latch can be used in a Calculation tag expression, where an If cannot.

If TimeOut(1, 1);
[
  J++;
]

J will increment once per second, since the Timeout is reset each time it becomes true.

Z = TimeOut(1, 1);
If Z;
[
  J++;
]

J will increment continuously, as fast as your computer will allow.

VTScada Functions That Are Reset Automatically:

AbsTime

Change

DeadBand

Edge

Intgr

Latch

MatchKeys

Now

Pick

RTimeOut

Save

TimeOut

Toggle

Watch

WatchArray

WinMatchKeys

TimeOut versus RTimeOut

The timeout functions are good examples of automatically resetting functions. These two are so similar that it's easy to choose the wrong one in any given situation.

  • TimeOut returns true when the uninterrupted time that an expression is true reaches the specified value.

  • RTimeOut is a cumulative timer. This function returns true when the total time that an expression is true reaches the specified value.

The following exercise will illustrate the difference.

  1. Create a new script application.

For the first example you will use RTimeOut, which counts the cumulative time that its enable parameter is true.

  2. Edit the Graphics submodule in the application's AppRoot.SRC file as follows:
{========================== System\Graphics =============================}
{ This module handles all of the graphics for the application            }
{========================================================================}
Graphics
[
  StartTS                           { timestamp upon beginning           };
  NowTime                           { updated time while running         };
  RunClock = 1                      { Boolean to enable timer            };
]
Init [ If Watch(1) Main;
  [
    NowTime = StartTS = CurrentTime();
  ]
]
Main [
  ZText(100, 100, Concat("Elapsed time: ", NowTime - StartTS), "<FFFFFFFF>", 0);
  ZText(100, 120, Concat("RunClock is ", RunClock), "<FFFFFFFF>", 0);
  If AbsTime(1, 2, 0);
  [
    RunClock = !RunClock;
  ]
  If RTimeOut(RunClock, 4);
  [
    NowTime = CurrentTime();
  ]
]
{ End of System\Graphics }
>
  3. Import file changes and run the application. Because RunClock is FALSE for two seconds out of four, the elapsed timer should update approximately every eight seconds. The fractional milliseconds difference shows the time it takes for code to run.
  4. Stop the application.
  5. Change RTimeOut to TimeOut and save the file.
  6. Import file changes and run the application again. The message will never update. For the TimeOut to trigger, its enable parameter needs to remain true for an uninterrupted time span.
  7. Stop the application.
  8. Replace the first parameter in TimeOut with 1.
  9. Import file changes and run the application again. The message will change every 4 seconds.

Triggers and States

In this exercise, you will build a simple counter that will say "All done" using a fresh state when the counter reaches the specified value. The point of the exercise is that you will need to look up the functions to see what they do and how to use them instead of simply copying code.

The answer code for this application is shown at the end of this topic. Try to avoid looking at it until you have built your own application. You will need to refer to the function reference in the VTScada documentation.

  1. If you have the Script1 application from an earlier example, continue working with it, removing all the code you added earlier. Otherwise, create a new script application.
  2. Use a text editor to open the application's AppRoot.SRC file.
  3. Write a ZText statement to place the word "Value: " in the center of the screen. Set the color to green and use 0 for the font.
  4. Add a variable, X, to the Graphics module, initializing its value to 0. (zero)
  5. Modify the ZText statement to use a Concat function, displaying the value of X after the word "Value: ".
  6. Add an action trigger (If statement) that triggers every second using the TimeOut function.
  7. Add a script block [ ] after the action trigger.
  8. Within the script block, increment the value of X by 1. Run the application to make sure that it works.
  9. Add a WinButton, placing it near the upper right of the window and giving it the label "Reset".
  10. Use the WinButton as a trigger to reset the value of X to zero when pressed.
  11. Again, run the application to make sure that it works.
  12. Add a second variable, MaxCount, which is initialized to 20.
  13. Add an Edit field below the reset button. This should be coded so that the user can change the value of MaxCount.
  14. Create a new state named Done. The Done state should display an "All done!" message to the user.
  15. Create a new trigger so that when X reaches MaxCount, the module will transition to the Done state.
  16. Run the application.
  17. If you coded the reset using the most direct method, there may be a flaw. Try the button a few times to see it. Notice if the transition from 0 to 1 takes less than a second after any given reset. If so, that's the flaw. The TimeOut is unaffected by the reset and will trigger one second after the last TimeOut, regardless of when you press the reset button.
    Fix the flaw. As a hint, think states.

Application for the Trigger and States example.

{================================= System ====================================}
{=============================================================================}
(
  System                        { Provides access to system library functions };
  Layer                         { Provides access to the application layer    };
)
[
  Graphics               Module { Contains user graphics                      };
  WinTitle = "User Application" { Window title                                };
  RunningOnVIC                  { TRUE if this is a VIC session               };
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         "<FFAAAAAA>", 1);
]

<
{============================= System\Graphics ===============================}
{ This module handles all of the graphics for the application                 }
{=============================================================================}
Graphics
[
  X                                              { Counter                  };
  MaxCount = 20                                  { Maximum count            };
]

Init [
  If 1 Main;
  [
    X = 0;
  ]
]

Main [
  ZText(350, 300, Concat("Value: ", X), "<FF007000>", 0) { Display the count};

   { Every second... }
  If TimeOut(1, 1);
  [
     { Increment X }
    X++;
  ]
   { Reset the count }
  If WinButton(700, 100, 750, 80, 0,"Reset", 1, 0) Init;

   { Allow user changes }
  System.Edit(700, 130, 750, 110, "Max", MaxCount, 1);

   { Time to quit }
  If X >= MaxCount Done;
]

Done [
   { Display the count                                                      }
  ZText(350, 300, "All done!", "<FF000070>", 0);
]
{ End of System\Graphics }
>

Advanced Topic: Create Your Own Automatically-Resetting Functions.

A function is a subroutine module, defined as any module that is launched from within a script block and which contains a Return() function. Note that the location of the Return() function within the subroutine makes a significant difference to the behavior. If the following conditions are met, then the subroutine will automatically reset:

  • Return() is located in a script block of the subroutine.
  • The action trigger for that script block includes a transfer to another state. The destination state typically contains no code.
  • The subroutine is used as the conditional to an If statement,

Example: An automatically resetting subroutine

In the following, Check always returns 1. However, this does not create an If 1 condition in the first state since the subroutine resets automatically. The return is within a script block, and the action trigger for that script block includes a transfer to another state.

Main [
  If Check();
  [
    I++;
  ]
]

<
{======================= Check ==============================}
Check

Init [
  If 1 Main;
  [
    Return(1);
  ]
]

Main [
]
>

In this example, Check() - a user-created function - is functionally equivalent to Watch(1).


Monitor Modules and Variables

It is helpful to be able to use the Source Debugger while learning the concepts presented in this chapter. Therefore, this introductory topic describes a few basic tasks that you can accomplish with the Source Debugger without needing to know all the features of that powerful tool.

The Source Debugger application is included with every copy of VTScada and should be available in the VTScada Application Manager. If not, you may need to load it using the Find Existing option of the Add Application Wizard.

Upon starting the Source Debugger, the Summary (Live) screen will take up the main part of the display. The list of running applications will be expanded.

Detail from the Source Debugger

While you can examine any running application including the System Library, the Source Debugger will show source code only if that code is available on your workstation. You can (for example) see how many Analog Status tags are running, and examine the values and parameters within each, but you cannot view the code within the Analog Status tag.

Using the Completed Tutorial application as an example, if you were to click this link in the Summary, the module tree window (left of the System Summary) would be populated with all the modules and submodules used by that application.

Module tree of the Completed Tutorial

The default order is how these are stored within VTScada. It will be easier for you to find any given module if you first sort the tree alphabetically. Note the tool to do this, shown circled in the previous figure.

If, for example, you are interested in the Analog Status tags in the application, then after sorting the module tree, find and click on Analog Status. (The plus beside Analog Status indicates that this module contains submodules, any of which may be examined.)

The Module Content window (bottom left) will be populated with variables found in the Analog Status module.

Variables within one of 15 Analog Status tags in the Completed Tutorial

Note the instance count (top right of this window). This tells you how many instances of the module are running and which one you are examining. Toggle buttons here can be used to step through these instances until you find the one you want to examine in detail.

For every variable in the module, there are two buttons (located to the right). Use these to change the display format of the information (decimal, hex, octal, etc.) or open a pop-up window with further information, if available.

If the module's source code can be found on your workstation, it will be displayed in the same window as the System (Live) view. You can add breakpoints on any line of code to halt execution at that line, then step forward line by line, watching values change as you do so.


Launched Versus Called Modules

There are five ways to run a module. Each has a different behavior and a different effect on your application. Of these five, the most frequently used are called modules, launched modules and subroutines.

Called Modules

Started from steady-state code. For example, displaying a widget on a page or a sub-process that runs while the state is open. An example of the latter would be a driver in its Connected state calling a ReceiveUpdates submodule.

The module is called into the current state and runs only while that state remains active. When control passes to another state, all called modules stop and resources that they were using are freed. It is important to be aware of the timing for when this happens. Given the following example:

If Action_trigger NextState;
[
  { script block }
]

All called modules in the current state stop as soon as action_trigger becomes TRUE. If code in the script block depended on a called module, it will fail because the variable holding that called module is now Invalid.

Parameter values are passed by reference. Any change to the parameter values in the calling or the called module will affect those in the other.

A set of parenthesis must always follow the module call, regardless of whether parameters are included within in them.

The term, "calling state", is used to refer to the state from which the module is called. Called modules may themselves contain module calls but take care not to call the first module from within the second. A circular or a recursive situation will result in the modules calling each other repeatedly until resources are depleted and the application crashes.

A return statement is optional.

Double-Sets with Called Modules:

Use care if you decide to create a called module to change the value of a variable. For example:

X = SomeCustomFunction(X);

When called in steady state, this is a double-set of X, therefore X will be Invalid. The reason is that X is passed by reference, and set within the called module as well as being explicitly set by the return value of the module. In steady state, the following would be better:

SomeCustomFunction(X);

Called Module Template

<
MyCalledModule
(
  { Parameters }
)
[
  { Variables }
]
Main [
   { Steady-state code... }
  Return( { Return value, if any } );
]
>

Example: A called graphics module

The called module in this example is written as a submodule. It will take a value from the calling module and increment it. Both the calling and the called module will display the value.

In the following example the parameter CounterVal is initialized to zero when it is declared in the submodule Counter. This does not prevent a value from being passed to the submodule. The initialization value is used only if no parameter is provided when calling Counter.

  1. Create a new script application and edit the AppRoot.SRC file as follows:
{================================= System ====================================}
{=============================================================================}
(
  System                      { Provides access to system library functions   };
  Layer                       { Provides access to the application layer      };
)
[
  Graphics               Module { Contains user graphics                      };
  Counter                Module { Another module                              };
  WinTitle = "User Application" { Window title                                };
  RunningOnVIC                  { TRUE if this is a VIC session               };
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);
]

<
{============================= System\Graphics ===============================}
{ This module handles all of the graphics for the application                 }
{=============================================================================}
Graphics
[
  X = 10;
]

Main [
  ZText(100, 100, Concat("X = ", X), 2, 0);
  Counter(X);
]
{ End of System\Graphics }
>

<
{============================= System\Counter ================================}
{ A simple called module to increment and display a value                     }
{=============================================================================}
Counter
(
  CounterVal = 1;
)
Main [
  ZText(100, 140, Concat("CounterVal = ", CounterVal), "<FF00FF00>", 0);
  If TimeOut(1, 2);
  [
    CounterVal++;
  ]
]
>

Return statements in called modules:

  1. Continue with the same application...
  2. Add a second variable to the Graphics module, Y.
  3. Add another ZText to display Y below X.
    (After doing so, check the coordinates of all the ZText functions in all the modules to ensure that one does not display in the same space as another.)
  4. In Counter, add a return statement in steady state as follows:
Return(CounterVal * 2);
  5. In Graphics, assign the return value of Counter to Y:
Y = Counter(X);
  6. Run the application and observe the result.
  7. Move the Return statement to the script block in Counter.
  8. Run the application. You might need to start and stop it a few times to notice the difference in behavior. Hint: The script block doesn't run (and therefore nothing is assigned to Y) until the next TimeOut.

State changes and called modules

  1. Continue with the same application...
  2. Working in the Graphics module, add a new state and a trigger to switch to that state as follows: Note the new colors in ZText, to help indicate the new state.
...
  If X >= 15 SecondState;
]
SecondState [
  ZText(100, 80, "Now in the second state", "<FFFF0000>", 0);
  ZText(100, 100, Concat("X = ", X), "<FFFF0000>", 0);
  ZText(100, 120, Concat("Y = ", Y), "<FFFF0000>", 0);
]
  3. Try to answer the following questions:
    What happened to the display of CounterVal?
    Why isn't Y double the value of XX reaching a value of 15 triggers the If statement. Because this involves a state transition, all other code in the state stops and the subroutine never gets a chance to run with the new value of 15. 1?

Use care when applying !Valid to the return value of a module call.

The comments of the Return function contain essential information.

For a called module, there is no way to know the return value until the code has time to run. This means that a called subroutine will return Invalid initially. Watching only !Valid(SomeModuleCall()) often just means TRUE. The initial Invalid, meaning "the answer is not yet available", can be mistaken for "done" or "no answer".

One way to avoid this is by using a previously initialized variable rather than the return value.

Launched Modules

Started from within a script block. For example, launching several Analog Status tags when an application starts. The launched modules have a life that is independent of the state containing the script block and will continue to run and use system resources until they are slain explicitly, or until the caller (not state) stops.

Uses for launched modules include:

  • A code snippet that you want to run once - much like a typical function in other languages.

  • Anything where you need a number of independent instances, such as tags.

  • A sub-process that keeps running even if the calling module changes the active state. Calls to retrieve tag history for a report are a good example, where one state builds and launches the query, then another state waits for the query to finish and processes the result.

  • A sub-process that does an assigned task, then slays itself when finished. The HTTPSend() function is an example.

Parameter values are passed by value, with values that are current at the time the module is launched. It is very common to use pointers to parameters when you need to pass information out of a launched module.

If, in addition to launching the module, you want to create a variable that holds a reference to the object value of that module, use the form, X = MyModule( ); The return value of this function is always the object value of the launched instance.

Launched Module Template

<
MyLaunchedModule
(
  { Parameters }
)
[
  { Variables }
]
Main [
  { Code. Often involves a sequence of
    asynchronous actions over multiple states,
    ending in a Slay(). }
]
>

Launching a module

  1. Continue to work in the same application as for called modules.
  2. Remove all statements that contain the variable Y.
  3. Add an initialization state to the Graphics module as follows:
Init [
  If 1 Main;
  [
    Counter(X);
  ]
]
  4. Remove the Return statement from Counter.
  5. Run the application.
  6. Change the trigger to transition to SecondState in Graphics as follows:
If Timeout(1, 10) SecondState;
  7. Run the application again.

The expected behavior is for X to keep counting up, regardless of the state that the parent module is in.

Subroutine Modules

These look exactly the same as a launched module except that the module in question contains a Return() statement. Execution of the thread that launches a subroutine will stop, waiting for a value to be returned. Subroutines that take time to return can have a severe effect on your applications.

The Return() function will have varying effects on your code depending on how it is used. You should take the time to read the notes for this function carefully before writing subroutines.

A Return() statement in a called module does not have the same effect that it does in a subroutine.

A subroutine may launch another module but note that a subroutine is never considered to be the caller or owner of any module that it launches. Rather, the nearest parent object that is not a subroutine is considered to be the parent of both the subroutine and any subsequent child modules launched. This means that a subroutine may end but any modules that it launches will continue to run until the caller ends or until those modules are slain. Use with care.

An object is slain when its caller is slain, not its parent. If the parent is slain, parentage passes up to the grandparent, if any.

Subroutine Template

<
MySubroutine
(
  { Parameters }
)
[
  { Variables }
]

Main [
  If 1;
  [
    { Script code... }
    Return( { Return value if any } );
  ]
]
>

Callable Subroutines

These are a special case of subroutine in that they work equally well in both script and steady-state

One problem with creating subroutines is that you may not have control over where and when the module may be called. For example, you might write the following, intending that this module be called only from within a script block:

<
ConvertXY
(
  X          { Value to be converted                            };
)
[
  Result     { Calculated result                                };
]

Main [
  If 1;
  [
     { Result = math for the calculation goes here. }
    Return(Result);
  ]
]
>

If this module is called from steady state, you will have an If 1 condition. To avoid this, a watch function can be used to ensure that the code only executes once:

  If Watch(1);
  [
     { Result = math for the calculation goes here. }
    Return(Result);
  ]

While this will prevent the "If 1" condition and work either as a called module or as a subroutine, there is no allowance for its parameters to change when used as a called module. By including these in the watch we now have a universal function that can be called from a script as a subroutine or from a module's active state code where the returned value will change as the calling parameters change

  If Watch(1, X);
  [
     { Result = math for the calculation goes here. }
    Return(Result, FALSE);
  ]

Note the addition of the second parameter in the Return() statement. This should be included unless you intend to create a resettable function such as Watch() or TimeOut(). It's likely that you do not.

Callable Subroutine Template

<
MyCallableSubroutine
(
  { Parameters }
)
[
  { Variables }
]
Main [
  If Watch(1, {, Parameters });
  [
     { Script code... }
    Return( { Return value } );
  ]
]
>

Call a script-only function in steady-state

Building on the information just presented, you can create a subroutine to run a script-only function as needed and use that subroutine in your steady-state expressions within tags and graphics. A common example is to call the CurrentTime() function.

  1. Create the following module as a file in your application:
RightNow.SRC
[
  RightNow;
]

Main [
  If Watch(1);
  [
    RightNow = CurrentTime();
    Return(RightNow);
  ]
]
  2. Declare the module in the Plugins section of your application's AppRoot.SRC:
  [ (PLUGINS)       {===== Modules added to other base system modules =====}
    RightNow    Module "RightNow.SRC";
  ]
  3. Import file changes.
  4. In your application, create an I/O and Calculations tag that uses the Numeric Calculation mode.
  5. In the Calculation tab of your tag, open the Expression Editor and enter the following:
\Code.RightNow()
  6. Note that, much like using an AbsTime() function in an expression, this is evaluated once and then does not update.

Threaded Modules

A threaded module is like a launched module, except each will run in its own thread. Use only when there is a clear need. Each new thread imposes additional overhead on the CPU and RAM. Launching many threaded modules will slow your overall application.

To launch a threaded module, use the Thread() function.

Queued Modules

Like called modules except that only one instance may run at a time, regardless of how many calls are issued. Often used in device driver modules where I/O reads and writes must occur sequentially.

The queued module should be designed to return a value to signal that it has finished. The calling module should be designed to transition to another state upon receiving that signal, thus stopping the first instance and allowing the next in the queue to begin.

Add the keyword "queued" in the module declaration to ensure that it runs as a queued module

{========================== SampleDriver ==========================}
{ This shows the first few variables in a device driver            }
{==================================================================}
[    { Driver modules }
  ErrorMessage  Module { Returns an error message from a code      };
  QUEUED RSem   Module { Read semaphore                            };
  QUEUED WSem   Module { Write semaphore                           };

Queued modules are useful in driver development.

Quick Reference

Type | Start from | Ends when | Parameter values | Effect on application | Called modules
Called | Steady state | Calling state ends | Passed by reference. Changes in value are passed into and out of the running module. | No effect | Belong to this module
Queued | Steady state | Calling state ends | Passed by reference | No effect | Belong to this module
Launched | Script | Calling module ends or Slay is called | Passed by value. Changes in value are not passed in or out unless pointers are used as the parameters | No effect | Belong to this module.
Subroutine | Script | The Return function executes | Passed by value. Changes in value are not passed in or out unless pointers are used as the parameters | Suspends execution of entire thread until subroutine returns. | Belong to the first non-subroutine parent of this module.
Threaded | Script | Calling module ends or Slay is called | Passed by value. Changes in value are not passed in or out unless pointers are used as the parameters | No effect | Belong to this module

Module Do's and Don'ts

Called Modules

Never call Slay() in a called module

Don't change parameter values unless they are output parameters. Doing so sets values passed into the module because they are passed by reference.

Launched Modules

Never call Return(). The presence of Return makes a launched module a subroutine.

Always consider the module's lifetime. It will live as long as its calling module unless it is slain. If it is performing a sub-process that should come to an end, use the Slay() function when the process is complete.

Never stop the caller of a launched module that is performing a sub-process until that process is complete.

Subroutines

Always call Return().

Never have an If statement wait for a condition. Always use If 1 or If Watch(1). In fact, never wait for anything within a subroutine. If you need to wait for something, use a launched module instead of a subroutine.

Callable Subroutine

Never use an If 1. When called in steady state this will consume CPU constantly.


Script Blocks and Called Modules

This was mentioned in an earlier topic but deserves to be emphasized.

If an action trigger statement includes a transition to another state, then any called modules in the current state will be stopped before the script block executes. For example, do not write code like the following:

AState [
  Obj = MyCalledModule(); { the called module does a Return(Self) }
   { When Obj becomes valid, run a subroutine then change states }
  If Valid(Obj) BState;
  [
    Obj.MySubroutine();
   { Too late. MyCalledModule has stopped and Obj is again Invalid }
  ]
]

BState [

]

The preceding example should have been written with an explicit transfer to BState using a ForceState() function in the script block.

AState [
  Obj = MyCalledModule(); { the called module does a Return(Self)   }
  If Valid(Obj);          { no state transfer in the action trigger }
  [
    Obj.MySubroutine();   { Obj still points to the called module }
    ForceState("BState"); { After the subroutine, change states   }
  ]
]

BState [

]

A script may contain more than one ForceState statement, but it is only the last one executed that sets the state to which the module will switch.

This statement does not act as an immediate exit point from the script - the script will still run in its entirety. That said, the first ForceState will cause the current state to end and any reference to objects in that state will fail.
If the script trigger statement did not specify a destination state to transfer to, this function will stop the current state as if one had been specified.

IF statements are the standard tool for specifying the next state. Use ForceState rarely and only when significant effort would be required otherwise to control the flow from one state to another.


Critical Sections

Given the event-triggered nature of statement execution in VTScada, there are times when you will need to ensure that certain tasks are completed before others execute. The CriticalSection() function is provided to achieve this.

A critical section is one whose execution cannot be interrupted by other threads. After being started, it is guaranteed to finish, assuming that your code is correctly written and able finish. When used, critical sections are typically placed in initialization states or in module constructors or destructors. For example:

If 1 Main;
[
  IfThen(Valid(level),
        CriticalSection(temp = a,
                         a = b,
                         b = temp ) );
]

Any number of statements can be passed as parameters to the CriticalSection. Note that, being parameters, these are separated by commas rather than semicolons.

Do not over-use critical sections. Use only when certain processes absolutely must be started or values obtained before continuing.


Module Scope

"Scope" refers to the ability of a variable or named module to be seen by calling code. For example, two modules may both declare a variable named "X". X will have a unique value in each module and will refer to a different memory address. Each version of X is local to the scope of the module where it is declared.

A module may declare and use submodules. For example, the Graphics submodule of a typical script application. Those submodules (child modules) will also be able to see and use the variables of the main module (parent module). The parent is within the scope of the child.

However, variables declared in the child modules are not within the scope of the parent and cannot be used by the parent unless directly referenced with a scope resolution operator "\" or "." (ChildInstance\Variable or ChildInstance.Variable where ChildInstance is a variable holding the child object - you can only scope into objects, not modules.

Use care! Early coders often write Child\Variable where Child is the name of the module, and that is bad code. The compiler turns it into Child()\Variable, thereby launching a new instance of Child (which may live forever or be a memory leak) and then returning the initial value of Variable from that instance.

If a module has two submodules, and each of those has a variable, "X", the parent cannot simply refer to X, but must identify the submodule in which to find a particular version of X. Typically, this is done by storing a reference to the instance when launching the child module:

If SomeCondition;
[
   { Launch an instance of Child and get a reference to it }
  Handle = Child();
]

You may now refer to variables in that instance of Child using Handle\Variable. If Child also launches submodules, the same rules and techniques apply.

If a module needs to access variables or functions of a separate module, it is possible to do this by fully describing the scope of the variable or function being called. (This assumes that the variable or module has not been declared as "Protected".) For example, many of the functions described in the Function Reference will include the name of the library module of which they are a member, and provide an example of how they should be called:

\AlarmManager.Ack(AlarmName, EventTime, Operator);

The following terms are used when describing scope:

Child | A submodule is a child of the module whose source file it is part of. Another term for a child module is a "member module".
Parent | A parent is a module that contains submodules.
Descendant | Submodules may themselves contain their own submodules. A descendant refers to any submodule of a parent.
Ancestor | Like "descendant", but looking in the other direction. Starting with any submodule, an ancestor is any parent module up the declaration chain. The root module is an ancestor of every module and every module is a descendant of the root module.
Member | Any named object - a variable, constant, module, etc.

Scope Resolution Operators

There are two scope resolution operators: the dot (.) and the backslash (\). The dot operator was added with VTScada version 11.2 and should be used when the intent is to reference a value only within the identified reference scope. If no value is found in that scope, Invalid will be returned. This differs from the backslash operator, which will look for a variable with the matching name in all ancestors if none is found in the reference scope.

There is also a Scope() function, which takes an object reference, a member name (variable or submodule to be found in the object reference), and a Boolean that controls whether the search will be limited to the named reference or if it should search up the scope tree for a match.

The dot operator is equivalent to the function call LocalScope(A, "B"). The backslash operator is equivalent to the function call Scope(A, "B").

Scope Operators and Late Binding

The scope operators may also be used to accomplish a feature called "late binding". A variable is a name referring to the memory location where a value is stored.

It is worth noting the difference between referring to a variable as \VarName versus VarName (without the scope resolution operator). \VarName is late binding while VarName is early / static binding. The former will compile even if there is no VarName in the compile-time static scope. (And, since the example shows the backslash operator rather than the dot operator, will always evaluate to the nearest VarName variable in the run-time scope tree). The latter will only compile if there is a VarName in the compile-time static scope (and will only resolve to that static variable at run-time even if another VarName variable is added dynamically in a nearer scope).

The process of "binding" is how the name and the storage location in memory are associated. Late binding (also referred to as "dynamic binding") links a variable or object at run time. In early binding, variable references in code are linked to memory addresses / offsets at compile time.

When a scope resolution operator is placed before a variable or module name used in an executable statement, such as in:

\VarName { or  .VarName }

it is considered the equivalent of writing:

Self()\VarName

but it uses less RAM. Early binding is typically more efficient than late binding because it reduces the amount of time required to set or retrieve a value, whereas late binding consumes more memory, and is slower than a direct variable reference. However, in some instances it is useful to reference modules and variables that are not in scope at compile time, and therefore you must use late binding after they have a chance to start.

Note that if VarName is a protected variable, then Self()\VarName will be Invalid while \VarName will correctly scope to the variable.

Always use VarName if it works, which it should the vast majority of the time. You should only need to use \VarName if "VarName" is something in Code, provided by VTScada.


Configuring a Script Tag

Viewing: Scripting > Scripting Fundamentals (Hello World!) > Configuring a Script Tag

Configure a Script Tag

Script tags are one of the standard types built into VTScada. The script tag links a VTScada script code module to another tag's value. It is used to go beyond the power of in-tag expressions to allow the use of the full VTScada scripting language inside a tag.

The module for a script tag must have two parameters, as follows:

(
  PointObj         { object value of AI to monitor      };
  ScriptObj        { Script Object                      };
)

PointObj is the tag whose value is monitored and used by the Script tag. This matches the first field, "In Tag Scope", found in the Execute tab of the Script tag's configuration panel.

ScriptObj is used internally to link to your script tag. Whatever calculation is performed in your module must assign a value to ScriptObj\value. This enables the module to pass its calculated value back to your Script tag.

Create a filtering tag

A first-order filter is used to smooth out noise from a value that tends not to change rapidly. Over time, it will match the value of whatever tag it is watching. It will lag changes, but transient spikes will have little effect on the value.

In the following example, the parameters PointObj and ScriptObj must be present by definition for use in a script tag. PointObj will match the tag selected for In Tag Scope parameter. ScriptObj points to the script tag that this module will be used in. This provides hooks between the Script tag and your code.

Note that, in this example, the calculation is done every two seconds, and that calculation exists in a script block, therefore running only a single time each two seconds. You could write this as a Watch() on the PointObj tag's value if you wanted code that executed on change rather than on time. Another feature to note is the ability to declare variables, in which you can save information from one iteration to the next.

  1. Copy the following code into a new file.
  2. Save the file as FilterFor.SRC in the SimulatedApp folder.
  3. Declare the module in the Plugins section of the AppRoot.SRC file.
  4. Import File Changes.
  5. Create a new script tag in the application.
  6. When configuring, select a tank level or a pump flow as the scope tag.
  7. Draw your script tag near whatever it is watching. Run the application.
{============================ Filter Module =======================}
{ This module is used to do a First order Filter of an input point }
{ Current Value = .1 * new value + .9 * previous value             }
{ The result is stored into the script point's value variable      }
{==================================================================}
(
  PointObj { object value of AI to monitor };
  ScriptObj { Script Object };
)
[
  PreviousValue { Previous Value };
]
Filtering [
  { ..every two seconds... }
  If AbsTime(1, 2, 0);
  [
    { Ensure there is a valid value first time through }
    PreviousValue = PickValid(PreviousValue, PointObj\Value);
    { Work out filtered value }
    ScriptObj\Value = .1 * PointObj\Value + .9 * PreviousValue;
    { Save for next time }
    PreviousValue = ScriptObj\Value;
  ]
]{ End of Filter Module }

Related information:

Script Tags - Example and details for creating a Script Tag.


Constructors and Destructors

Constructors

Constructors are subroutines that, if present in a module, are called automatically when the module is created. A subroutine becomes a constructor simply by being named "Constructor".

Constructors are useful for initializing variables, opening files, streams and other I/O connections, launching submodules or for registering the module with external services before the module is fully ready for operation.

Constructors differ from initialization states (the first state to run when a module is created) in that they will occur sooner. The constructor subroutine runs immediately as part of the launch, while there may be a delay before the first state in the module runs. Because constructors were introduced as part of VTS 10.1, you may see the use of a "Ready" flag in older code. This was used as a work-around to ensure that the first state in the module had a chance to run before other code that depended on the completion of initialization tasks would begin.

Example: (Where MyModule is a launched module)

<
MyModule
(
 InstanceName;
)
[
  Constructor Module;
  CapsName;
]
Main [
  ...
]

<
Constructor
Main [
  If 1;
  [
    CapsName = ToUpper(InstanceName);
    Return(Invalid);
  ]
]
{ End of MyModule\Constructor }
>
{ End of MyModule }
>

The script code that launches the module might look like:

MyObj = MyModule("MyInstance");
InitCapsName = MyObj\CapsName;

In the above example, InitCapsName will be "MYINSTANCE", as the constructor subroutine is executed as part of the line of script that creates the object and assigns it to MyObj. Remember that subroutines take control of executing code until they are finished, thus guaranteeing that CapsName is set by the time the statement InitCapsName = MyObj\CapsName runs.

Constructors execute inside a CriticalSection, so it is impossible for external code to interact with a partially constructed module.

The parent object and caller object of a Constructor is the module being constructed.

Destructors

Destructors are subroutines that, if present in a module, are called automatically just before a module is slain or otherwise stopped. These ensure that cleanup tasks such as closing files, freeing memory and de-registering a module instance from external services are done even if the module is interrupted unexpectedly. (For example, a user closes a dialog box rather than finishing its task.)

<
MyModule
(
  UniqueName;
)

[
  Constructor Module;
  Destructor  Module;
]
Main [
  ...
]
<
Constructor
Main [
  If 1;
  [
    GlobalDictionary[UniqueName] = Caller(Self());
    Return(Invalid);
  ]
]
{ End of MyModule\Constructor }
>

<
Destructor
Main [
  If 1;
  [ { UniqueName had been added to a global dictionary as part of MyModule.}
    DictionaryRemove(GlobalDictionary, UniqueName);
    Return(Invalid);
  ]
]
{ End of MyModule\Destructor }
>
{ End of MyModule }
>

In this example, GlobalDictionary is a dictionary of all instances of MyModule, keyed by each module instance's UniqueName. The Constructor makes sure that each instance of MyModule is present in that dictionary, and the Destructor removes the instance from the dictionary when the instance is slain.

Destructors execute inside a CriticalSection, so it is impossible for external code to interact with a partially destructed module.

The parent object and caller object of a Destructor is the module being destroyed.


Threading

Viewing: Scripting > Scripting Fundamentals (Hello World!) > Threading

Threads and Bubbles

VTScada provides the ability to have multiple control threads that share a single address space, but appear to behave as if they were separate processes (i.e. the processing time is divided equally among threads of the same priority). This means that those statements that are deemed to be threaded, and any modules that are called in their own thread will not block each other waiting for their turn to execute, but will instead share the processor's time, giving the appearance of simultaneous execution.

Bubbles are similar to threads, except that the code running within a bubble can run completely in parallel with the code that is running outside the bubble, taking better advantage of the CPU resource: code inside the bubble can run on one processor core while the script code running outside the bubble runs on another processor core.

If you do not use additional bubbles and just use threads, your script code can use at most one processor core. Using script threads makes it easier to interleave the execution of multiple processes within VTScada, but the use of bubbles makes it possible for those processes to run fully in parallel across multiple processor cores.

Thread or Bubble?

Bubbles are useful when there are multiple independent processes running at the same time that are CPU-bound. That is, the sum of these processes would consume more than one CPU core for a period of time. If you do not use additional bubbles and just use threads, your script code can use only one processor core. Processes running on different processor cores will not hold each other up as much as when they are all funneled through a single core. Consequently, those processes may complete more quickly and you may be able to run more such processes at once. Also, if a CPU-intensive process has been offloaded into a bubble, then it will not reduce user-interface responsiveness of code running outside that bubble

Interaction between the code running in two bubbles is highly controlled, and only permitted through a messaging interface. As a result, bubbles have the additional feature of isolating code to limit its ability to interact with other code in the system, which can be a useful security feature.

However, there can be significant overhead to starting a bubble as well as communicating data into and out of that bubble. While running, bubbles have significantly more memory overhead than threads. Bubbles work best when the ratio of work to inter-bubble communication is high. Also, certain VTScada features are not supported in user-created bubbles. (List provided later within this topic.)

Using script threads makes it easier to interleave the execution of multiple processes within VTScada, but the use of bubbles makes it possible for those processes to run fully in parallel across multiple processor cores.

Using Threads

A threaded module is like a launched module, except each will run in its own thread. Use only when there is a clear need. Each new thread imposes additional overhead on the CPU and RAM. Launching many threaded modules will slow your overall application.

To launch a threaded module, use the Thread() function.

Any variables set by threaded statements must be checked for validity before proceeding to use them. If order of execution is important and the task to be performed is not an overly long and arduous one, it may be better to use the non-threaded version of a function.

In cases where two versions of the same function exist, one being threaded and the other not, the threaded version will generally have a "T" appended to its name, such as in the case of ODBC and TODBC.

The VTScada Source Debugger and the Thread List Application provide tools to assist you in troubleshooting threading within your applications.

Using Bubbles

VTScada script code is always operating within a bubble, referred to as the system bubble. From this top-most bubble, you can start child bubbles and they can start their own child bubbles, forming a tree of bubbles.

The following VTScada features must run only in the system bubble and are unsupported in child bubbles.

TAPI

Includes the functions, ModemCount, ModemStream, ModemDial, ModemTransfer, ModemList, ModemDev, CallerID, ModemDigits, and ModemMedia

DDE

Client and server, as well as all DDE functions.

VTScada OPC server functions

Includes the functions OPCServer and SetOPCData.

Thin clients

Windows created within a bubble are visible only on the server, never on a thin client.

Thin client management

Includes the functions VICMessage, VICInfo, and SetVicParms.


Callbacks and Subscriptions

Several functions and library descriptions refer to callbacks, subscriptions, or both. The following definitions are offered for those who have not encountered these programming constructions before.

Callback

A callback is a reference to one module, passed to another. For example, you will see the following statement in every new script application:

  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);

Graphics() is a submodule of the application. When the Window function is called, it need to know what to display within its borders. That information comes from the parameter, Graphics(), which executes (calls-back) the display information. So long as the Window remains open (the enclosing state remains active) information coming back from Graphics() will continuously update.

Refer to the GridList function for further examples.

Sometimes, a callback module that you write will need to use objects within the caller. This is achieved using the CallBackScope syntax:

CallBackScope.SubModuleName();

Refer to examples in the GridList function where a callback for the grid titles calls the TitleClicked() submodule of the GridList to initiate the default action when a title is clicked.

Subscribe

Subscribing to something means that you want code to run whenever the value of that something changes. This is the essence of Steady State in VTScada, but there are situations where you need to explicitly state "do A when B" without using a script block triggered by an IF.


Triggers and Related Race Conditions

A race condition happens when two or more processes run at the same time and the final outcome depends on which one finishes first-- something that is unpredictable. The correct use of triggers avoids common race conditions in GUI code.

Common High-Risk Trigger Scenarios

You may recognize some of the following scenarios. These pitfalls and the recommended best practices are transferable to many other similar setups.

Consider ( Edit + Button )

Always check the Trigger before proceeding after an Edit

When using System.Edit, the associated Trigger is 0 while the user is still typing and only becomes non-zero when editing is complete.

The correct course of action is to guard any button logic with

 PickValid(Trigger, 1) ! = 0

In this expression, "Trigger" provides feedback. While editing, the value will be 0. When editing is complete (loss of focus, tab, enter...) the value will change to non-zero: 1 if enter is pressed, 2 otherwise. Invalid typically means that the control has not yet been used. Since the main goal of a trigger is to tell you if a control is currently busy, the Invalid value is typically treated as equivalent to the non-zero values, hence the "PickValid".

This ensures that a button press cannot act on an incomplete input, and prevents the classic race where the user types and immediately clicks "Save" but the old value is stored.

The following example is from a simple script application:

<
{============================= Graphics ======================================}
{ This module handles all of the graphics for the application                 }
{=============================================================================}
Graphics
[
  FirstName = ""              { User's first name                             };
  LastName  = ""              { User's last name                              };
  FullName  = ""              { Store the user's full name                    };
  Trigger                     { Edit's trigger                                };
]

Main [
   { First name }
  \System.Edit(100, 120, 200, 100,
               "First Name: " { Title },
               FirstName, 1 { FocusID }, Trigger);

   { Last name }
  \System.Edit(100, 160, 200, 140,
               "Last Name: " { Title },
               LastName, 1 { FocusID }, Trigger);

   { When the WinButton is clicked, we need to wait for
     the trigger to clear (become non-zero) before using the input. }

  If WinButton(100, 210, 200, 190, 0, "Save", 1) && PickValid(Trigger, 1) != 0;
  [
    FullName = Concat(PickValid(FirstName, ""), " ", PickValid(LastName, ""));
  ]

   { Display the full name and current value of trigger }
  ZText(100, 230, Concat("Full name is: ", FullName), 0, 0);

]

{ End of Graphics }
>

Consider the Config Folder

Use Trigger in reverse when working with *PtrWaitClose in configuration folder

Configuration Dialogs must not close or switch tabs while the user is still typing.

*PtrWaitClose has inverse logic. 1 = busy (and cannot close).

*PtrWaitClose = True( Trigger == 0 )

In this expression, the dialog's close behavior is tied to the Edit's Trigger, blocking premature closure and avoiding lost edits.

Consider Nested Triggers

Propagate nested triggers in order; wait for the inner trigger to complete before updating the outer trigger.

Say you want to create your own input module that presents an edit field and does additional sanitization beyond what System.Edit is capable of (e.g. you want to remove all spaces from the input). Your module will need to have its own trigger (i.e. the "outer" trigger) parameter, partly based on System.Edit's trigger parameter (the "inner" trigger). The code should set the outer trigger to 0 immediately when the inner trigger becomes 0.

Do not pass along the completion value of the inner trigger (1 or 2) until after sanitization has finished. You must not pass your wrapper module's Trigger parameter directly into System.Edit.

Take the following module for example:

<
{============================= NoWhitespaceEdit ==============================}
{ This is a wrapper for \System.Edit that adds additional sanitization.       }
{=============================================================================}
NoWhitespaceEdit
(
  X1                          { Left coordinate   };
  Y1                          { Button coordinate };
  X2                          { Right coordinate  };
  Y2                          { Top coordinate    };
  Title                       { Title of the Edit };
  UserInput                   { User's input      };
  Trigger                     { Outer trigger     };
)
[
  InnerTrigger                { Inner trigger     };
  RawText                     { Original text     };
]

Main[
   { Watch the User input, and update it to the RawText }
  If Watch(1, UserInput);
  [
    RawText = PickValid(UserInput, "");
  ]

  \System.Edit(X1, Y1, X2, Y2,
               Title, RawText,
               1 { FocusID }, InnerTrigger);

   { Watch both InnerTrigger and RawText in case RawText changeswhen InnerTrigger is already non-zero}
   {                         (and the Watch did nothave a chance to notice InnerTrigger becoming 0). }
  If Watch(1, InnerTrigger, RawText);
  [
    IfElse(PickValid(InnerTrigger, 1) == 0,
       { Let the caller know that we're busy accepting/processing input. }
      Trigger = 0;
    { Else } Execute(
       { Sanitize the spaces in input }
      UserInput = Replace(RawText,
                          0,
                          StrLen(RawText),
                          " ",
                          "");
       { Pass through Edit's trigger completion value.                             }
       { This lets the caller know if the user finished input by hitting Enter (1) }
       { or by changing focus to another control (2).                              }
       { Sometimes the caller will want to behave differently in those two cases.  }
      Trigger = InnerTrigger;
    ));
  ]
]

{ End of NoWhiteSpaceEdit }
>

NoWhitespaceEdit has its own trigger parameter, and System.Edit has its own trigger parameter which affects NoWhitespaceEdit's trigger. These are nested triggers.

This ensures that outside logic only sees "edit complete" once the sanitized value is ready, preventing the race where external code consumes data without sanitization.

General Guidance when using Triggers

  1. Don't act on the output of a module while its trigger is 0.
    If you have a WinButton that acts on the output of a trigger, check the trigger to ensure the output parameter is actually set before consuming it.
  2. A trigger becoming 0 is always a temporary situation.
    It will resolve (go to 1 or 2) when the user finishes entering input and the control is done processing such that the output is ready (via either an output parameter or the return value). For an edit field, we detect that the use is done entering input when they hit Enter or switch focus to a different control.
  3. It is best not to assume that every value change is accompanied by a change to its trigger. It's possible for values to change again after the conditions have been met for trigger to equal 1 or 2. For some controls there is no guarantee that trigger will return to 0 as a part of the output changing. It stays "triggered". Triggers do not exist to tell you that an output has changed; they are just there to tell you if the output is in the process of being changed. Watch for changes to both the output variable and the trigger, and do not react to changes in the output variable so long as the trigger = 0.

A real world example of point 3 this can be seen with an editable WinComboCtrl. If you type text and hit enter, it returns 0 and then 1 (it returns the trigger value).
But then, if you select something in its droplist, its value changes while the return value remains 1.

Can the time it takes for a Trigger to become 0 create a race condition?

In the top-most scenario, concerning WinButton logic, you might have wondered, "Isn't there still a race between the Trigger becoming 0 and the WinButton being clicked?"

Triggers are designed with the expectation that the time between a trigger becoming 0 and then the user performing another input action will be long enough for the trigger value of 0 to propagate through the script code.

The time it takes to start editing a text field and then click the button, in a practical sense, will be long enough for the Trigger value to propagate out so that it will affect a WinButton statement.


Value Types

VTScada script is a dynamically typed language (like Python) that allows variables to hold values of any type and that can hold different types during the execution of a script, unlike statically typed languages such as C, C++ and Java that declare the type with the variable and do not allow the type to be changed during program execution.

The VTScada engine always maintains knowledge of the type of the value in a variable, and when comparing values or providing parameters to functions you must ensure that the correct type is used in every instance. (Implicit conversions will be used where possible. For example, the text "42" will be treated as the number 42 if used in an equation and the number 42 can be concatenated into a sentence of text.)

VTScada has 58 different types as listed in the reference section.

VTScada's function library includes TRUE and FALSE, which also serve as constants. DO NOT declare these keywords as constants in your code.

All variables and constants used in a module must be declared, but the intended value type is not part of the declaration. A value may be assigned as part of the declaration. If your code does not assign a value, the VTScada will assign the value, Invalid.

Additionally, there are a number of keywords that can be used in the declaration for variables that need special handling. For example, constants are declared by using the keyword "Constant" before the declared name.

Declaring Constants

CustomControl    { module name }
(
  parm1          { a parameter to the module };
)
[ { start of variable and constant declaration }
  TotalCount                      { variable, defaults to Invalid  };
  CurrentCount = 0                { variable with an initial value };
  Constant #WarningMsg = "Danger" { constant with a text value     };
]

By convention, constants are often declared with a leading "#", but this is only for the sake of identification. The hash mark has no functional significance.

Several commonly used values such as PI are defined in VTScada for your use. See VTScada Constants and Public Variables for a partial list.

Common Value Types

The most common value types are described in the following table. Types that require longer explanations, including arrays, dictionaries and structures, are described in their own topics.

Invalid

An Invalid value is an unknown value that is distinct from all other value types. Invalid guards the system from performing control action based upon erroneous or bad information. Any variable may have an invalid value.

Any calculation that uses an invalid value produces an invalid result (with a few exceptions). Invalid results are not written to output devices. In addition, any graphic statements that contain invalid variables will not produce any output on the screen. In general, any function that uses an invalid value will have no effect and behave as if it did not exist. For functions that have optional parameters, you can use Invalid to specify that the default value should be used. (Typically done only when you wish to specify a value for a later optional parameter.)

Invalid values may result from tags that are not set to any given value, as when VTScada is first starting up. To avoid this situation, programmers use the PickValid() function to provide a default value to expressions until the variable has a valid value.

Invalid values can also result from setting a variable's value in two or more different statements at the same time. In this situation it is uncertain which value is correct, so the variable will be invalid even if both values are the same. This is known as a "double set". An array reference that has one of its subscripts out of range will have an invalid value. Some programmable controllers flag inputs when they are out of range - when these values are read by VTScada, they are declared to be invalid. Division by 0, taking the square root or logarithm of a negative number, and other illegal mathematical operations result in invalid results. An invalid value can even be purposely set as such by using the Invalid function.

Because calculations using invalid values produce invalid results, invalid values can propagate through the system. The setting of a variable to invalid will cause all other variables that depend upon its value either directly or indirectly to become invalid.

Numbers

Numbers are stored internally in the most efficient form for the value provided. When doing arithmetic, if the values provided are all 64-bit signed integers, the operaration will be done using 64-bit signed integers. In an overflow situation, where the product would exceed the signed 64-bit integer range, or if at least one of the values is not within the 64-bit integer range, arithmetic is done with the precision of 8-byte IEEE floating point numbers. The legal value range of values is ±10^308, with a precision of approximately 15 decimal places.

Literals, fixed values directly written into the code without any variable, are compiled as 64-bit signed integers by default unless the value doesn't fit within the 64-bit signed integer range. In that case, the value will be converted to double precision floating point numbers and will not have full precision.

0xFFFFFFFFFFFFFFFF (the largest 64-bit unsigned integer) will be converted to a double precision floating point number, so will not have full precision, unlike 0x7FFFFFFFFFFFFFFF, the largest signed 64-bit integer. So, to get a 64bit integer with all 64 bits set, use -1, not 0xFFFFFFFFFFFFFFFF.

Use a minus sign to indicate negative numbers. A plus sign may not be used in a number. The following formats may be used as needed:

Format | Example | Description
Scientific notation | 23.5e5 | Place the letter "e" or "E" after the number, followed by the number to use for the power of 10. For example, 1.23E3 is the same as 1230.0 and 1.23E-3 is the same as 0.00123.
Binary notation | 0b1100 | Binary integers may be specified using the 0b or 0B prefix and up to 32 digits. Each digit is either a 0 or a 1.
Octal notation | 014 | Octal integers may be specified using a zero prefix and up to 11 digits. Each digit must be in the range 0 to 7.
Hexadecimal format | 0xC | Hexadecimal integers may be specified using the 0x prefix and up to 8 digits. Each digit must be a number or a letter in the range A to F (upper or lower case).

The number -9223372036854775808 (the smallest 64-bit integer) cannot be compiled like that. The coder needs to use -9223372036854775807 - 1. This is because the smallest 64-bit number -9223372036854775808 compiles as the unary minus operator applied to the positive number 9223372036854775808. That positive number is one more than the largest signed 64-bit integer, so it is handled using a double, and hence precision is lost.

Text / String

Text values (also called "text buffers" or "strings") are a series of bytes having a specified length. Text values can hold up to approximately 65,500 characters (just less than 64k characters).

A text value may not hold the ASCII 0 value. To store quotation marks in a text variable or constant, use double-quotes:

Quote = """We lived for days on nothing but food and water."" W.C. Fields";

The term, "null string" refers to a text value having zero characters.

Logical Values

(also, "status value" or "Boolean")

A logical value is a true or false value. A false value is indicated by the number 0 or the function, FALSE. A true value is indicated by any valid number other than 0, (typically a 1) or by the function, TRUE.

In general, it is better coding practice to use the functions TRUE and FALSE than 1 and 0.

Pointers

A pointer is a variable that holds a memory address. A pointer references or "points to" a value in a specific memory location.

A variable that points to an address does not have the properties of the value type in that address and cannot be converted to another value type.

A pointer is made to reference the memory address of a variable by using the Address operator "&". For example:

y = 4;    { y holds the value 4 }
ptr = &y; { ptr holds the memory address where that 4 is stored }

Before the data referenced by a pointer can be used, the pointer must be dereferenced using the "*" operator. See: Dereference (pointer dereference) Dereference (pointer dereference).

x = *ptr  { x holds the value 4 }

Object Variables

The object type is used to access public members of a module instance (aka, "object"). Each object variable references exactly one module instance. Every active module call creates a new separate copy, or instance, of that module and its member variables. Each module instance operates independently of the other instances.

By using an object variable and the scope resolution operator (a backslash character or dot according to your purpose), public functions and variables of the module instance may be accessed. For example:

Obj = Driver();

Obj\Read();

The first line starts the Driver module and assigns its return value to Obj. Note the term "return value". This must be supplied by the module being referenced. This is commonly done by using the Self function. Suppose that the Driver module executes the statement:

Return(Self());

Now Obj has the value referencing the copy of the Driver module that was started in the first line of the example above. The second line uses the scope resolution operator (\) with the Obj variable to indicate that the Read module is inside of Driver. When Read starts, it will inherit the member variables of this instance of the Driver module. This means that all the variables of Driver can be used by Read and the values that this Read will see are those copies that are created by the starting the Driver in the first line of the example.

Further statements using the Obj variable may reference other variables and modules within the Driver module. For example, statements such as:

Obj\Read();

Obj\Write();

Output(0, 0, 1, 0, 0, Obj\Error, 15, 0, 0, 0, 0);

may be added to start additional copies of the modules within the Driver module and to access public variables within the module (such as Error).

Object variables may be assigned to other object variables, passed as parameters to modules or used as return values from modules. For example, assume a second object variable called Second has been defined. The statements:

Second = Obj;
Second\Read();

will copy the reference to Driver held in Obj to Second. The last statement here will start a new copy of Read within the same copy of Driver as started in the first line of the examples. If the assignment to Second were changed to:

Second = Driver();

then, Second would be referring to an independent instance of Driver.

The Launch function will also return the launched object value, which you can assign to a variable.

Object variables are often used as a parameter to a module or function, since this provides a way to pass in a way to access other modules.

Object parameters are unique in that they allow access to actions (modules) that can change from one module call to the next. One example might be in a parameterized module which transmits a packet for an I/O driver. Assume this module is called Communicate. Assume Communicate has an object type parameter called TheCaller. This module might handle all of the communication details but not handle the building of the packets. Read and Write modules calling this module might pass an object parameter Self (Self) to this communications module. Each of these calling modules might contain a child module called Build. Within the Communicate module, a call of the form:

TheCaller\Build();

could be used to access the appropriate packet building module which would be different for Read and Write.

An object value will automatically become invalid if the module instance it refers to stops running. This feature can be used to determine when a launched module stops. Also, when the module instance that generated a particular object value is stopped, all object variables containing that object value become invalid, and all descendant module instances of that module are stopped. All scope resolutions to member variable values will return invalid values.

Object variables cannot be compared or printed. Their actual values are meaningless.

Graphic Variables

VTScada uses a set of variable types for graphics that are unique to VTScada. These value types are used by all layered graphics functions, and by the functions that create them. All of these values are valid only so long as the function that created them is active.

You generally do not want to access these values directly. Instead, (and as an example), it is better to pass Path() calls directly into GUIPolygon, etc.

This set of value types includes Point, Vertex, Path, Normalize, Rotate, and Trajectory Variables

Streams

Stream values are a complex type, which refer to a read/write stream. Streams are a very convenient way of performing formatted input and output. Examples of streams include buffer streams attached to text values, file streams attached to disk files, and pipe streams attached to operating system pipes. There are a wide variety of functions related to streams.

Most streams contain a position pointer that indicates where in the stream the next read or write will take place. This pointer is automatically positioned after a read or write to the stream and may be positioned by the Seek function, which also returns the current position in characters from the beginning of the stream.

Streams also offer faster file access than FRead and FWrite, which open and close the file after every access, because a stream leaves a file open. Another advantage of streams is that you can use the Flush function, which is the recommended way to reduce the chance that a write fails to make it to disk before a power loss or PC crash. The Flush function only works with streams, not with files modified using FWrite.

Many functions are available to help you work with streams. See: Stream And Socket functions.

Value Type Conversions

Occasionally, data may be the wrong type. For example, an addition may be performed on two variables, one containing a number, the other containing a text value. VTScada handles this situation by performing a conversion of the unexpected data to the type of data expected, if possible. The type expected may vary according to the operation.

A = 5;
B = "4";
C = A + B;

In this example, two numbers are expected. One variable is already a number and the other variable containing text is converted by VTScada to a number. This is done by reading an ASCII number from the text. If successful, the converted number is used and if unsuccessful, an invalid value is returned. This process is referred to as "type conversion".

Table of VTScada Value and Type Conversions

Convert From | Convert To | Condition of Original Value | Returned Value
Code Pointer | Module | Valid value | Valid value
 | Module State | Valid value | Valid value
Module State | Statement | Valid value | Valid value
 | Object | Valid value | Valid value
 | Text | Valid value | Name of module
Double | Long | Valid value | Valid value
 | Short | Valid value | Valid value
 |  | Outside of range | Invalid
 | Status | Valid value | Valid value
 | Text | Valid value | String representing numeric value
Edit Block | Stream | May only be used in SRead with % option, or in StrLen | Valid value
Long | Double | Valid value | Valid value
 | Short | Valid value | Valid value
 |  | Outside of range (-32768 to 32767) | Invalid
 | Status | Valid value | Valid value
 | Text | Valid value | String representing numeric value
Module | Text | Valid value | Name of module
Module State | Module | Valid value | Valid value
 | Text | Valid value | Name of module
Module State Statement | Module | Valid value | Valid value
 | Module State | Valid value | Valid value
 | Text | Valid value | Name of module
Normalize | Double | Valid value | The scaled value
 | Long | In the range of -9 223 372 036 854 775 808 to 9 223 372 036 854 775 807 | The value
 | Short | In the range of -32 768 to 32 767 | The value
 |  | Outside of range | Invalid
 | Status | 0 | 0 (false)
 |  | Non-0 | 1 (true)
 | Text | Valid value | String representing scaled value
Object | Module State | Valid value | Module and state in which that object exists
 | Statement | Valid value | Module state and statement number that object is executing
 | Text | Valid value | Name of the module of which that object is an instance
Short | Double | Valid value | Valid value
 | Long | Valid value | Valid value
 | Status | Valid value | Valid value
 | Text | Valid value | String representing numeric value
Status | Double | Unconnected socket | 1
 |  | Connected socket | Invalid
 | Long | Unconnected socket | 1
 |  | Connected socket | Invalid
 | Short | Unconnected socket | 1
 |  | Connected socket | Invalid
 | Status | Unconnected socket | 1
 |  | Connected socket | Invalid
 | Text | Unconnected socket | "1"
 |  | Connected socket | String of stream contents
Tag | Double | Valid value | The scaled value
 | Long | In the range of -9 223 372 036 854 775 808 to 9 223 372 036 854 775 807 | The value
 |  | Outside the range | Invalid
 | Short | In the range of -32 768 to 32 767 | The value
 |  | Outside the range | Invalid
 | Status | 0 | 0 (false)
 |  | Non-0 | 1 (true)
 | Text | Valid value | String representing scaled value
Text | Double | Number string | Number in string
 | Long | Number string | Number in string
 | Short | Number string | Number in string
 | Status | Non-0 number string | 0 (false)
 |  | 0 number string | 1 (true)
Variable | Module | Module variable | The module in which the module variable resides
 | Text | Valid value | Name of variable

Experiment with Variables

Preparation: Create a new script application, but do not run it immediately.

  1. Open the application's AppRoot.SRC file using a text editor.
  2. Edit the Graphics module as follows:
<
{============================= System\Graphics ===============}
{ This module handles all of the graphics for the application }
{=============================================================}
Graphics
( )
[
  X = 2   { one numeric value to display                      };
  Y = 2   { another numeric value.                            };
]
Main [
   ZText(100, 100, X, 15, 0);
   ZText(100, 120, Y, 15, 0);
   ZText(100, 140, X + Y, 15, 0);
]
{ End of System\Graphics }
>
  3. Compile (Import file changes) and run the application.
  4. Try the following values for X and Y. You will need to stop the application, import file changes and restart between each change. Try experimenting with additional types.
  X = 2;
  Y = "2";
  X = "2";
  Y = "2";
  X = 2.01;
  Y = 2;
  X = "two";
  Y = "two";
  X;
  Y = 2;

If X is "2" and Y is "2" the + operator will perform string concatenation and return "22". If you are uncertain about what value type will be passed to your function, it is worth using the Cast() function to try to force it to the correct type.


Variable Class Definitions

The AppRoot.SRC file of each standard VTScada application defines a set of classes that tell the loader how to treat modules declared within AppRoot; this one is a page, that one is a tag.

A variable may be of a defined class if designated by the user. Variable classes are hexadecimal constants, primarily used as a means of grouping associated variables and may be defined as the user requires them. For example, each tag type is defined with a class, thereby making it possible for you to obtain a list of the tags of a certain type.

Variable classes are used by different parts of the code in different ways. In a script application, classes mean only what you define them to mean. In your custom modules of a standard application, you can create classes as needed to group variables. But use caution or avoid creating class definitions in a standard application's AppRoot.SRC file, where VTScada already assigns meaning to a number of class constants, not all of which are shown. (You are free to use the same values in your own modules.)

The class number may be added to the variable's declaration or to the declaration of a group of variables of the same class:

[
  FlowRate = 32 (0x0015);
  PNum (0x0015);
]

In this example, the first two variables have their class designated by the hexadecimal number 15 (0x0015). Because these two variables have the same class designation, they could have been grouped together as follows:

[
  Constant #PUMP = 0x0015;
  [(#PUMP)
    FlowRate = 32;
    PNum;
  ]
]

In this example, the variable class for FlowRate and PNum is a constant called #PUMP whose value has been set at 0x0015 in a previous declaration statement. No matter which method is used, the class definition must be a constant whose value is between 0 and 65 535.

Example:

Each VTScada tag type has a class. This can be used to obtain a list of the tags of a certain type. For example:

If !Valid(MyClass);
[
    { Get the Alarm Tag's class }
   MyClass = VariableClass(FindVariable("AlarmPriority", Code, 0, 0));
    { Find the array of variables that are members of that class }
   PriorityObjs = ListVars(ParentObject(\Code),
                           "*", MyClass, MyClass, 0, 0, 1, 0, 0);
]

If the above were to be added to any page (and the two variables declared), then in the Source Debugger you could examine that page module to find the array of PriorityObjs:

Result of the preceding code example

This example illustrates the use of class definitions. But, to achieve the same result, it would be better to use GetTagList() which is more powerful and takes into account realm / user filtering, etc


Using Pointers

Many VTScada functions require or return pointers. A pointer is a reference to the memory address where a variable's value is stored. You can create a pointer variable by using the & notation in front of an existing variable name.

For example

Y = 7;   { "Y" is a the name of a variable, within which is stored the number "7" }
Ptr = &Y;  { ptr is the name of a variable, within which is stored a pointer to the memory address of Y }

Pointers must be dereferenced before the data they point to can be used. Dereferencing means accessing the value stored in the assigned memory location. A pointer can be dereferenced by placing an asterisk before it. For example:

X = *Ptr + 1;

A dereferenced pointer can be used to store a new value into the location or object at which it is pointing. For example:

Ptr = &Y;
*Ptr = 7;

This is equivalent to the expression "y = 7;".

If the pointer "ptr" is used in any expression requiring a value other than a pointer value (for example, a numeric value), the result is invalid, as "ptr" is a pointer to a value, not a value itself. For example:

W = Ptr + 1

In this example, w is set to invalid, as the pointer "ptr" was not dereferenced. VTScada will not take this to mean the next memory address (VTScada does not support pointer arithmetic). What should have been written is:

W = *Ptr + 1


Arrays

An array is a value type used to group a set of values under one variable name. The individual elements of the array are sequentially numbered, normally starting at zero unless otherwise configured.

Every element in the array can be used as a separate location with its own independent value that may have its own type. To refer to an element in the array, use square brackets enclosing the index or "subscript" value. If A is an array with five elements then A[0] refers to the first element, A[4] is the fifth.

You may use a variable, an expression, or a function as the subscript in your code, to manipulate an array or dynamically access different elements as operating conditions change.

Arrays may be declared either as static or dynamic. If a function specifies one type or the other as a parameter, it is essential that you use only that type.
Use a dynamic array in all cases where a static array is not specifically required.

In data processing, the WhileLoop() and DoLoop() functions certainly have their place, use the array functions when you can, because they are simpler and faster.

Dynamic Arrays

A dynamic array is created by first declaring the name, then using a script block to define the array size using the New() function:

[
  NameArray     { to be used as a one-dimensional array };
]

Init [
  If 1 Main;
  [
     NameArray = New(10);
  ]
]

If you need to initialize the array after creating it, use an ArrayOp() function where possible.

Static Arrays

Static arrays have a fixed size. They are created, and optionally initialized when they are declared:

[
  AStaticArray[10] = 0;
]

Pointers and Arrays

A significant difference between static and dynamic arrays comes from the fact that the New() function returns a pointer. For example:

ArrayPtr = New(10);

Technically, to use an element from "ArrayPtr", you should dereference the element:

(*ArrayPtr)[0] = 5;

Fortunately, dereferencing is done automatically. The array index operator [ ] performs a pointer dereference operation if the variable before the operator has a pointer value. Thus, the expression above can also be written as follows:

ArrayPtr[0] = 5;

The preferred method is to allow the array index operator to perform the dereferencing of the pointer, because it improves the readability of the statement and executes faster.

Many functions specify whether an array parameter should be a static or a dynamic array - use care to provide the correct type.

You can pass a static array into a called module by reference. If you pass a static array into a launched module or subroutine, then only the first value will be passed in, because static arrays cannot be copied. For example, in the case of X = StaticArray; the value gets padded with [0] such that only the first element of the static array is passed in.

Whether or not a variable is passed by value or reference is a factor of the way the module is being called or launched, not a factor of the values in the variables.

For example, if you have the following code:

Main [
  MyCall(StaticArray);
  MyCall(DynamicArray);
  If Watch(1);
  [
    MyLaunch(StaticArray);
    MyLaunch(DynamicArray);
  ]
]

Assume that MyLaunch and MyCall both have one parameter called ArrayParm.

In MyCall, you can use ArrayParm to read and write all values in StaticArray and DynamicArray without issue. If it executes ArrayParm = 3, then DynamicArray would become a simple 3 (the array would be discarded), while StaticArray would remain an array, with only its first element set to 3 (this is the array padding mentioned earlier).

In MyLaunch, you can use ArrayParm to read and write all values of DynamicArray without issue, but not StaticArray. This is because MyLaunch takes its values by value, which means parameter values get copied into the local parameter values in the MyLaunch object. That works for DynamicArray, since DynamicArray contains a pointer value and pointer values can be copied. It doesn't work for StaticArray because static arrays don't get copied. Instead, it only copies the first element of the array into ArrayParm, so ArrayParm is neither an array nor a pointer to an array. If it executes ArrayParm = 3, then this does nothing but set its local ArrayParm parameter to 3; the original DynamicArray and StaticArray that was passed into the parameter are not modified by that assignment.

When you pass values by value (as happens when you pass values into a launched module), they are copied. You cannot pass a static array by value, but you can pass (a pointer to) a dynamic array. If you passed the dynamic array itself (i.e. *DynamicArray), then you would get the same behavior as when you pass a static array.

Multidimensional Arrays

An array that contains an array in each of its elements is defined as follows:

Data = New(5, 10);

This declaration may be read as "Data is an array of 5 elements each of which is an array of 10 values." This is a multidimensional array. Each dimension must appear as a number enclosed in square brackets [ ] that follows the variable name.

The left-most subscript is the "first" or "lowest" dimension of the array. The right-most subscript is the "last", "leading", or "highest" dimension.

It is possible but rather uncommon, to define starting and ending elements for a multidimensional array. To do so, use a static declaration. For example, the following declaration is for a two-dimensional array whose valid elements range from Data[10][-1] to Data[20][6]:

Data[10, 20][-1, 6];

Mismatched Array Dimensions

When using an array in your code, if the number of defined array dimensions does not match what your code attempts to address, the evaluation proceeds anyway, following certain rules. Specified array dimensions are matched to defined array dimensions starting from the right and working towards the left. If more array dimensions were specified than were defined, that array expression is called "over specified". (You are unlikely to encounter this.) If fewer array dimensions were specified than were defined, that array expression is called "under specified".

For under-specified arrays, missing leading (right-most) dimensions will default to zero. Consider the statement:

Data = New(2, 3);
Q = Data[1];

This expression would use Data[1][0]. Do not write code that relies on this - doing so is regarded as poor practice.

The ArrayOp Functions

When working with array values, many programmers will tend to use looping functions to step through the array items. While possible in VTScada, a better option exists for many common array tasks in the form of the ArrayOp functions; ArrayOp1 and ArrayOp2.

The parameters to ArrayOp1 include an array, a scalar value, and a numeric code designating a function to be applied. For example, to initialize an array:

(
  A     { an array };
  S = 2 { a value  };
)

Init [
  If 1 Main;

  [
    A = New(10); { A is a 10-element array}
    ArrayOp1(A[0]  { starting at element 0 of A },
             10    { for all 10 elements        },
              S    { take the value of S        },
              0    { set each element of A to S });
  ]
]

Other function codes could add the value of S to the current value of each element of A, or multiply, apply an AND, OR or exclusive OR (XOR), etc.

ArrayOP2 is similar, but in this case S is another array. The function code directs how elements of S should be applied to matching elements of A.

Many other array handling functions such as ArrayMax(), Sum(), Mean(), etc. are also available.

Practice with arrays

Create a drop list.

Working in a new script application, edit the Graphics module of AppRoot as follows. (Note that the droplist title will be black. You will need to change the window color to read it.)

Hint: You can save time by copying the droplist example from the documentation, then editing parameters to match what's shown here.

Graphics
[
  Options                         { an array of options                };
  Choice                          { user selection from options        };
  Index = 0                       { offset into options                };
  Msg = ""                        { display selection                  };
]

Init [
  If 1 Main;
  [
    Options = New(5);
    Options[0] = "Apple";
    Options[1] = "Cherry";
    Options[2] = "Mango";
    Options[3] = "Peach";
    Options[4] = "Pear";
  ]
]
Main [
  System.DropList(40, 60, 140, 40 { Boundaries of list },
                  Options { Data displayed },
                  "Choose one" { Title },
                  Index { Highlighted index },
                  1, 1 { Focus ID, trigger },
                  FALSE { Editable field },
                  "Apple" { Starting value },
                  Choice { Variable to set },
                  FALSE { No bevel },
                  0 { Align top of list });
   Msg = Concat("Selection is ", Choice, " at index ", Index);
   ZText(150, 75, Msg, "<FFFFFF00>", 0 );
]
{ End of System\Graphics }
>

Create a grid list.

Create a new script application or replace the code in the last with the following. Again, you can save time by copying the sample GridList from the documentation then editing the parameters.

Graphics
[
  Titles                       { column titles               };
  Data                         { data array to fill grid     };
  DataForm                     { formatting code             };
]

Init [
  If 1 Main;
  [
    { initialize the data array }
   Titles = New(5);
   Data   = New(5, 5);

   Titles[0] = "Col 0";
   Titles[1] = "Col 1";
   Titles[2] = "Col 2";
   Titles[3] = "Col 3";
   Titles[4] = "Col 4";

   Data[0][0] = "0";
   Data[1][0] = "1";
   Data[2][0] = "2";
   Data[3][0] = "3";
   Data[4][0] = "4";

   DataForm  = "%s";
  ]
]

Main [
  GUITransform(50, 200, 450, 50  { Reference rectangle         },
               1, 1, 1, 1, 1     { Scale Left, Bottom, Right, Top, Overall },
               0, 0, 1, 0        { No movement; visible; res   },
               0, 0, 0           { Not selectable              },
               System.GridList(Titles  { Titles array         },
                               Data   { Data array           },
                               DataForm { Cell format array   },
                               60     { Column widths array   },
                               3      { # Data rows           },
                               5      { # Data cols           },
                               15, 8  { Grid BGnd, Grid color },
                               1, 1 { Grid line width, line style},
                               30, 30 { Row/Title height      },
                               0, 0 { Horiz/Vert cell padding },
                               0, 0 { Horiz/Vert Scroll position },
                               1, 1 { Disable V/H scroll bars },
                               1    { Disable column sizing   },
                               1    { Disable Sorting         },
                               1    { Disable selected cell   },
                               0, 0 { Enable V/H grid lines  },
                               1    { LockFirstColumn         },
                               Invalid  { Sort                },
                               0       { SelectedRow         },
                               0      { SelectedColumn      },
                               System.DefFont { GridFontParm    }));
]
{ End of System\Graphics }

Experiment with ArrayOp1

Working with the same file as the last example, add a WinEdit control for data entry of a number and a droplist to select an operations code for use with the ArrayOp1 function. Each time that either changes, the second row of the array will be reset to match the first, then the scalar will be applied according to the selected operation.

Graphics
[
  Titles                        { an array of column titles          };
  Data                          { data to display in grid            };
  DataForm                      { formatting of data                 };
  Scalar = 0                    { scalar value                       };
  OpCodes                       { Array of OpCodes                   };
  OpCode = 0                    { Selected OpCode for ArrayOp fcn.   };
  OpCodeDesc                    { Array of OpCode descriptions       };
  nada                          { Text choice of OpCode. Not used    };
]

Init [ If 1 Main;
  [

   Titles = New(5);
   Data = New(5,5);
   OpCodes = New(8);
   OpCodeDesc = New(8);

   Titles[0] = "Col 0";
   Titles[1] = "Col 1";
   Titles[2] = "Col 2";
   Titles[3] = "Col 3";
   Titles[4] = "Col 4";

   Data[0][0] = "0";
   Data[0][1] = "1";
   Data[0][2] = "2";
   Data[0][3] = "3";
   Data[0][4] = "4";

   DataForm  = "%s";

   OpCodes[0] = 0;
   OpCodeDesc[0] = "A = S";
   OpCodes[1] = 1;
   OpCodeDesc[1] = "A + S";
   OpCodes[2] = 2;
   OpCodeDesc[2] = "A - S";
   OpCodes[3] = 3;
   OpCodeDesc[3] = "S - A";
   OpCodes[4] = 4;
   OpCodeDesc[4] = "A * S";
   OpCodes[5] = 5;
   OpCodeDesc[5] = "A / S";
   OpCodes[6] = 6;
   OpCodeDesc[6] = "S / A";
   OpCodes[7] = 7;
   OpCodeDesc[7] = "A % S";

   ArrayOp2(Data[1][0],Data[0][0],5, 0);
  ]
]

Main [
  GUITransform(50, 200, 450, 50   { Reference rectangle         },
               1, 1, 1, 1, 1       { Scale Left, Bottom, Right, Top, Overall },
               0, 0, 1, 0        { No movement; visible; res   },
               0, 0, 0           { Not selectable              },
               System.GridList(Titles  { Titles array         },
                                Data   { Data array           },
                                DataForm { Cell format array   },
                                80     { Column widths array   },
                                2      { # Data rows           },
                                5      { # Data cols           },
                                15, 8  { Grid BGnd, Grid color },
                                1, 1 { Grid line width, line style},
                                30, 30 { Row/Title height      },
                                0, 0 { Horiz/Vert cell padding },
                                0, 0 { Horiz/Vert Scroll position },
                                1, 1 { Disable V/H scroll bars },
                                1    { Disable column sizing   },
                                1    { Disable Sorting         },
                                1    { Disable selected cell   },
                                0, 0 { Enable V/H grid lines  },
                                1    { LockFirstColumn         },
                                Invalid  { Sort                },
                                0       { SelectedRow         },
                                0      { SelectedColumn      },
                                System.DefFont { GridFontParm    }));

  WinEditCtrl(170, 290, 220, 270, 0, Scalar, 1);

  System.DropList(50, 265, 165, 250 { Boundaries of list },
                  OpCodeDesc { Data displayed },
                  "Choose an OpCode" { Title },
                  OpCode { Highlighted index },
                  1, 1 { Focus ID, trigger },
                  0 { Editable field },
                  OpCodeDesc[0] { Starting value },
                  nada { Variable to set },
                  0 { Bevel });
  If Watch(0, Scalar, OpCode);
  [
    ArrayOp2(Data[1][0], Data[0][0], 5, 0);
    ArrayOp1(Data[1][0], 5, Scalar, OpCodes[OpCode]);
  ]
]
{ End of System\Graphics }
>


Comparison of Static and Dynamic Arrays

A static array variable holds a value of type, array. A dynamic array variable holds a pointer to an array value. Thanks to automatic pointer dereferencing and automatic index padding, there is very little difference in the code that you write to use either type of array. What differences do exist can be found in the following technical points.

It is important to note that use of a static array where a function expects a dynamic array, will result in that function failing to work properly.

Use dynamically allocated arrays for all code unless a function reference explicitly states that a static array is expected for one of the parameters.

Static arrays are created in the variable declaration StaticArray[50];, whereas dynamic arrays are created using the New() function within a script block.

Automatic Pointer Dereferencing

Since dynamic array variables are pointers, one might expect to do a lot of pointer dereferencing when using dynamic arrays. For example, to access the fourth element of a dynamic array pointed to by DynamicArray, one might expect to write the following code:

(*DynamicArray)[4] = 0;

While this syntax is correct, it is also redundant; whenever VTScada encounters the [ ] index operator, it automatically dereferences the variable being indexed. This makes the explicit dereferencing unnecessary, so that the above code can simply be written as:

DynamicArray[4] = 0;

By automatically dereferencing an array pointer under these circumstances, VTScada makes accessing an element of a dynamic array look and behave just like accessing an element of a static array.

StaticArray[4] = 0;

Note: VTScada only performs automatic dereferencing when an element is accessed with the index operator. In no other cases is a dynamic array automatically dereferenced.

Automatic Index Padding

Unlike its automatically dereferenced pointers, VTScada's automatically padded indices makes for array-related code that looks the same, but behaves differently, depending on whether a dynamic array or a static array is used. This mismatch between appearance and workings can easily lead to developer confusion, and thus warrants special attention.

VTScada applies automatic index padding whenever an array reference is under-specified. In turn, an array reference is considered under-specified if two criteria are met:

  1. The array reference must involve an array value, as opposed to a pointer to an array value. This is almost the same as saying the array reference must involve a static array variable, as opposed to a dynamic array variable, with two exceptions:
  1. Whenever a dynamic array variable is explicitly dereferenced (*DynamicArray), the result is an array value.

  2. Similarly, whenever a dynamic array is referenced with the [ ] operator, VTScada automatically dereferences the array pointer, and the result is an array value.

  2. An array reference must include fewer [ ] operators than the referenced array has dimensions.
5. StaticArray;        { Under-specified }
6. &StaticArray;       { Not under-specified, not an array value }
7. StaticArray[2];     { Under-specified }
8. StaticArray[1][3];  { Not under-specified }

Lines 2 and 5 show the inconspicuous difference between dynamic and static arrays: VTScada considers line 2 fully specified, but considers line 5 under-specified.

x = StaticArray;        { x = StaticArray[0][0] }
x = &StaticArray;       { x = StaticArray. See Variable Assignment  }
x = StaticArray[2];     { x = StaticArray[2][0] }
x = StaticArray[1][3];  { x = StaticArray[1][3] }

Value Assignment - Static versus Dynamic Arrays

It is not possible to assign a value directly to (or from) a static array variable, and VTScada's automatic index padding ensures that this does not happen. If it ever appears that a static array is participating in an assignment, automatic index padding works to make sure that only an element of the array is involved. The following code shows the automatic index padding at work, with equivalent assignments in comments.

[
   AStaticArray[3] = 1;
   BStaticArray[5][10] = 2;
   SimpleVar;
]
Init [
   If 1 Main;
   [
      SimpleVar = AStaticArray;       { SimpleVar = AStaticArray[0] }
      SimpleVar = BStaticArray[4];    { SimpleVar = BStaticArray[4][0] }
      SimpleVar = BStaticArray[3][1]; { SimpleVar = BStaticArray[3][1]     }
      SimpleVar = &AStaticArray;      { SimpleVar = &AStaticArray }

      AStaticArray = "super";         { AStaticArray[0] = "super" }
      BStaticArray[4] = 3;            { BStaticArray[4][0] = 3 }
      BStaticArray[3][1] = 4;         { BStaticArray[3][1] = 4 }
      &AStaticArray = 0x00008000;     { Error! Not an lvalue }
      AStaticArray = BStaticArray;    {AStaticArray[0] =  BStaticArray[0][0] }
   ]
]

Dynamic-array variables are declared no differently than any other VTScada variable. This similarity carries over to assignment, where assigning a value to (or from) a dynamic-array variable is no different than assigning a value to (or from) any other VTScada variable. Dynamic-array variables can be assigned any scalar value, including another dynamic-array variable (a pointer to an array). The following code shows these assignments.

If 1 Main;
[
   ADynamicArray = 5;                 { a scalar assignment }
   ADynamicArray = New(3, 2);         { a new dynamic array }
   BDynamicArray = ADynamicArray[1];  { under-specified.  ADynamicArray[1][0] is assigned instead }
   BDynamicArray = "super";           { another scalar assignment }
   CDynamicArray = New(10);           { a new dynamic array }
   DDynamicArray = CDynamicArray;     { one dynamic array to another }
   SimpleVar = DDynamicArray;         { a dynamic array to a simple variable }
]

When a dynamic-array variable is assigned to another variable, as in the last two assignments of the previous example, only the pointer is assigned, and no arrays are copied: in the previous example, CDynamicArray, DDynamicArray, and SimpleVar all point to the same dynamically allocated ten-element array.

Note than during these assignments, neither of VTScada's automatic array-related features was invoked: no [] index operators were present and none of the array references were under-specified.

Passing an Array to a Module

Arguments to a Launched Module (or subroutine) are passed by value (i.e. the value of the argument is copied, or assigned, to the module's parameter). For this reason, passing arguments to a launched module is very similar to assigning a value to a variable. It should be no surprise, then, that the rules that govern passing arguments to launched modules are identical to those that govern variable assignment: VTScada uses automatic index padding to ensure that only an element of a static array is passed to a launched module, while passing dynamic arrays to launched modules is less restricted.

When arguments are passed to a Called Module, they are passed by reference (i.e. a called module's parameter is made to refer the argument, and no copy is made). This is the only case when a static-array reference is not index padded by VTScada. When a static array is passed to a called module, the called module's parameter is made to refer to the entire static array, and not just to one particular array element. Consequently, a called module can change the elements of a static-array argument, and any changes will appear outside of the module.

Similarly, when a dynamic array is passed to a called module, the array pointer is not copied to the module parameter, but rather the called module's parameter is made to refer to the array pointer (think of a pointer to a pointer). In this way, a called module can change not only the elements in, but also the size and dimensions of, a dynamic-array argument, and any changes will appear outside of the module.


Dictionaries

A dictionary is flexible data structure. Dictionaries:

  • May optionally have an assigned text value.
  • Hold a flexible set of key-value pairs. Keys are text names.
  • Information is automatically sorted by key, resulting in fast searching and retrieval.
  • Key-value pairs can be added and removed efficiently and without limit.
  • Values may be other dictionaries, allowing you to create complex data structures.

Create a Dictionary Using the Dictionary() Function

In this example ServerLocations is a dictionary of server names and where each is located.

ServerLocations = Dictionary();
ServerLocations["Primary"] = "Cleveland";
ServerLocations["Backup1"] = "Orlando";

In the following example, DriverServers is a dictionary of dictionaries, each holding the names of primary and packup servers.

DriverServers = Dictionary();
DriverServers["Modicon1"] = Dictionary();
DriverServers["Modicon1"]["Primary"] = "ServerX";
DriverServers["Modicon1"]["Backup"]  = "ServerY";

DriverServers["Modicon2"] = Dictionary();
DriverServers["Modicon2"]["Primary"] = "ServerY";
DriverServers["Modicon2"]["Backup"]  = "ServerX";

Within a dictionary, all keys must always be unique by definition. Attempting to create a duplicate key by assigning a new value to a key with a non-unique name will simply result in the original key being assigned the new data value. Dictionaries may be defined such that their keys are case sensitive (in which case "a" will come after "Z") or they may be non case sensitive. Unless otherwise specified, they will not be case sensitive.

Practice with dictionaries

Arrays are useful for storing data in a clearly enumerated order, 0, 1, 2... But often, data is associated with keys that aren't in a tidy order. There are cases where driver error codes provide an excellent example of this.

In this example, you will use an array and listbox to simulate random error codes coming from hardware. A dictionary stores the key-value pairs of defined error codes and matching messages.

Create a new script application and copy the following to the Graphics submodule.

Graphics
[
  ErrCodes                      { a dictionary of error codes          };
  SimErrors                     { array simulating errors received     };
  Choice                        { selection from simulated error array };
  Index                         { offset into array                    };
  Msg                           { message to display                   };
]

Init [
  If 1 Main;
  [
    ErrCodes = Dictionary(1);
    ErrCodes[0x2]  = "No connection";
    ErrCodes[0x4]  = "Missing adapter";
    ErrCodes[0x10] = "Error retrieving value";
    ErrCodes[0x30] = "Command not found";
    ErrCodes[0x92] = "Invalid syntax";

    SimErrors = New(5);
    SimErrors[0] = 0x2;
    SimErrors[1] = 0x4;
    SimErrors[2] = 0x10;
    SimErrors[3] = 0x30;
    SimErrors[4] = 0x92;
  ]
]

Main [
  System.DropList(40, 60, 140, 40 { Boundaries of list },
                 SimErrors { Data displayed },
                 "" { No title },
                 Index { Highlighted index },
                 1, 1 { Focus ID, trigger },
                 FALSE { Editable field },
                 Invalid { Starting value },
                 Choice { Variable to set },
                 FALSE { No bevel },
                 0 { Align top of list });
   Msg = Concat("Error code: ", Choice, " ... Message: ", ErrCodes[Choice]);
   ZText(150, 60, Msg, 12, 0);
]
{ End of System\Graphics }
>

Related information:

Dictionary

MetaData

RootValue


Dictionary Operations

Operations involving dictionaries and other variables:

The result of any operation that uses a dictionary as one of the operands and a non-dictionary as the other will always take the root value of the dictionary as the value to be used for the operation. Note that it is rarely a good idea to assign a root value to a dictionary.

Accessing values in a dictionary:

Values within a dictionary can be accessed using an array-like syntax.

Examples:

X = Dictionary();
X["A"] = 42;
Y = X["A"];   { Y now holds the value 42 }

Retrieving an array of the keys from a dictionary:

The function ListKeys will (by default) return a one-dimensional array of the keys stored in a dictionary

Rval = ListKeys ( dictionary );

Example:

X =  Dictionary();
X["A"] = 15;
X["B"] = 24;
Rval = ListKeys(X);

Rval will now contain a two-element array, containing the values "A" and "B".

Iterate through the elements of a dictionary

The function GetNextKey will return each successive key within a dictionary. If you don't know the first key, then a call to GetNextKey without a key to start from, will return the first key in the dictionary. But, given that the keys in a dictionary are not enumerated like elements in an array, which is the first and how is the order defined? GetNextKey allows you to specify that using an Order parameter, which may be alphabetic or ordinal (by when the key was added), either forward or backward.

Result_str = "";
MyDict = Dictionary();
MyDict["key4"] = "contents4";
MyDict["key1"] = "contents1";
MyDict["key3"] = "contents3";
MyDict["key2"] = "contents2";

CurVal = GetNextKey(MyDict, Invalid, 0, CurKey);
WhileLoop(Valid(CurKey),
  Result_str = Concat(Result_str, " """, CurVal, """");
  CurVal = GetNextKey(MyDict, CurKey, 0, CurKey);
);

Construct an array using a dictionary

If building an array from an external data source, you may not know how many elements there are and therefore will not know how much space to allocate for your array. A solution is to store the incoming elements to a dictionary, then transfer them to an array upon completion. (Or, leave them in the dictionary if that is more convenient for later operations.)

For each element you add to the dictionary, assign a key that is an incrementing number, starting with 0. You can then use ListKeys(Dict, 1, 2) to transfer the values to an array.

Retrieving the root value from a dictionary:

(Note that it is rarely a good idea to assign a root value to a dictionary.)

The root value of a dictionary can be obtained by either of two methods:

Directly:

Y =  X[""];    { where X is a dictionary }

Via a function:

Y =  RootValue( X );

In general, the result will be identical, except for the case where the root value is another dictionary. In such a case, RootValue will traverse the dictionaries until it finds the first root value that is not another dictionary.

In the case where all the root values are other dictionaries (a circle) then RootValue will return a dictionary, selecting the first root value after the one indicated in the command that points to an earlier value.

Advanced Situation - Dictionaries containing dictionaries:

Given three nested dictionaries where:

  • The root of dictionary X is dictionary Y
  • The root of dictionary Y is dictionary Z
  • The root of Z is the integer 42.

If you retrieve the root of x directly:

RVAL =  X[""];

Then, RVAL is now dictionary Y.

If you were to use the RootValue() function instead:

RVAL = RootValue(X);

RVAL is now the integer 42

Assignment operations involving dictionaries

When assigning a dictionary to a variable using the assignment operator (=) , the result is a pass-by-reference, effectively creating an alias for the dictionary rather than a copy.

Example:

X = Dictionary(); { create an empty dictionary }
Y = X;            { assign it to Y }
X["A"] = 42;      { create a node in X with key "A" & value 42 }
Y["A"] == 42;     {  TRUE because Y is an alias for X }

A function exists to do a pass by value, allowing you to create a copy of a dictionary:

RVAL = DictionaryCopy( dictionary,  [deep],  [acyclic],  [lock]);

The three optional parameters, deep, acyclic and lock are each Boolean values with a default of FALSE.

  • Deep If true, all contained dictionaries are copied as well as the dictionary referred to by name. Note that if Deep is set to FALSE, the copied dictionary will not be missing the contained dictionaries - the difference is that in one case, the contained dictionaries are copied as well as the base dictionary, and in the other, the copy of the base dictionary will also include the original, contained dictionaries.
  • Acyclic If true, cyclic links are removed
  • Lock If true, all values in the copy will be locked as constants.

Adding and Removing Keys

Keys and values can be added to a dictionary by simply referencing them like so:

X = Dictionary(); {  creates a new, empty dictionary }
X["A"] = 42;   { adds a new key-value pair to dictionary X }

Keys and their associated values can be removed from a dictionary using the DictionaryRemove() function as follows:

DictionaryRemove(dictionary, key);

The given key, specified in the second parameter, and its associated data will be removed from the given dictionary specified in parameter 1.

Testing whether an object is a dictionary

The ValueType() function will work as expected on a dictionary unless you have assigned a root value, which is rarely done. In the case where there is a root value, ValueType() will return the type of that root value.

The function HasMetaData() will determine whether a value has metadata, unless that value is a dictionary:

Rval  =  HasMetaData(Val);


Structures

Structures allow you to organize information to increase the overall clarity of your code. Much like a structure in C, these are collections of variables and their values, placed under one name.

The use of a structure is illustrated by the following example:

Mod
[
  Dims STRUCT [
    Length;
    Width;
    Height;
  ];
]

Main
[
   …
]

An instance of the structure Dims can now be assigned to a variable as follows:

A = Dims();

You can also assign values to the various nodes in the same statement:

A = Dims(15, 30, 45);

In either, the variable A will now contain a structure that is 3 items long and that can be indexed using the keywords Length, Width and Height as defined.

The values can now be used as shown in the following examples:

Example 1:

Rval  =  A.Width;

Rval now holds the value 30.

Example 2:

A.Length  =  42;

42 is now the value stored in index position 0 of our structure.

You can also use array indexing notation to access the underlying data:

A[1] == 30;

Structures and Dictionaries

It is interesting to note that structures are based on the concepts of VTScada dictionaries and metadata.

The example above will create a variable named Dims. Dims is a constant containing a locked dictionary with a root value of the text "Dims". The underlying structure of Dims can be visualized as follows:

   Dims = Dictionary(Dims)   { dictionary with a root value of Invalid }
   Dims["Length"] = 0        { meta data elements of the dictionary    }
   Dims["Width"]  = 1
   Dims["Height"] = 2

When Dims was instantiated as A in the examples above, A became a one dimensional array containing within it a pointer to Dims. This enables us to reference the contents of A using the keywords Length, Width and Height and get the correct pointers into the array A.

Because of this, it is possible to store additional data of use to the structure within the defining dictionary. In particular, the name of the structure is stored in the dictionary’s root. Thus, to identify an unknown structure, you can use the following expression:

RootValue(Cast(<struct>, 47);

Extending Structures

Structures may be extended as shown in the following example:

 { structure 1, named Y }
Y STRUCT [
  A;
  B;
];

 { structure 2, named X extends Y }
X:Y  STRUCT [
  C;
  D;
];

A = X();    {  variable A now holds a 4 element array,
 where the elements of the array will be in the order A, B, C, D }

Structures can also be compound data structures, containing other structures as well as more basic data types:

Z STRUCT [
  A STRUCT [
    Q;
    R;
  ];
  B;
  C STRUCT [
    S;
  ];
];

Practice with structures

In this example, a structure will be used to store the current time in its separate components. This would be useful if you needed to refer to those time-parts in a variety of places within a module and didn't want to recalculate each instance.

Graphics
[
  StartTime                   { a timestamp                            };
  TimeParts STRUCT [          { structure definition including...      }
    ss                        { Seconds                                };
    mm                        { Minutes                                };
    hh                        { Hours (24)                             };
    dd                        { Day of month                           };
    M                         { Month of year (1-based)                };
    yy                        { Year                                   };
  ];
  TimeStructure               { an instance of the time structure      };
  Constant #SecInDay = 86400  { seconds in a day                       };
]

Init [
  If 1 Main;
  [
   StartTime = CurrentTime();  { Collect the current time stamp }
   TimeStructure = TimeParts(  { break it up, storing each part }
     Time(StartTime % #SecInDay, "ss"  ) { ss },
     Time(StartTime % #SecInDay, "mm"  ) { mm },
     Time(StartTime % #SecInDay, "H"   ) { hh },
     Date(StartTime / #SecInDay, "dd"  ) { dd },
     Date(StartTime / #SecInDay, "MM"  ) { M  },
     Date(StartTime / #SecInDay, "yyyy") { yy });
  ]
]

Main [
   { display values from the time structure            }
  ZText(100, 100, Concat("Year  ", TimeStructure\yy), 5, 0);
  ZText(100, 115, Concat("Month ", TimeStructure\M),  5, 0);
  ZText(100, 130, Concat("Day   ", TimeStructure\dd), 5, 0);
  ZText(100, 145, Concat("Hour  ", TimeStructure\hh), 5, 0);
  ZText(100, 160, Concat("Min   ", TimeStructure\mm), 5, 0);
  ZText(100, 175, Concat("Sec   ", TimeStructure\ss), 5, 0);

]
{ End of System\Graphics }
>


VTScada Value Types

The following table lists the value types used in VTScada. When referring to these in code, you should use the predefined constants rather than the type numbers. The general usage is:

Cast(Val, \#VTypeText)

Type | Constant Name | Name | Description
0 | #VTypeStatus | Boolean | Logical data type, stores two states: TRUE (non-zero, usually 1) or FALSE (0).
1 | #VTypeShort | Short, 16-bit signed | Integer data type storing values from -32768 to 32767
2 | #VTypeLong | Long, 64-bit signed | Integer data type storing values from -9223372036854775808 to 9223372036854775807
3 | #VTypeDouble | Double precision floating point | Values range from about -10^308 through +10^308
4 #VTypeText Text

A sequence of bytes of a specified length. This may be either of:

i) An arbitrary sequence of bytes, of the sort that (for example) MakeBuff generates and BuffRead consumes.

ii) A sequence of bytes consisting of characters of a particular encoding. Since the release of VTScada version 11.5 these normally are encoded in UTF-8, in which case some characters require multiple bytes to encode.

5 | #VTypeVariable | Variable | A handle to the data represented by a variable declaration, not to any particular instantiation of that declaration. Can be used to access variable metadata (type information, for example) or default values.
6 #VTypeFunction Function A pointer to the code for a particular function within a VTScada statement. Used by functions such as GetOneParmText to manipulate the code itself.
Used when compiling and editing script code, not for typical VTScada programs.
7 | #VTypeObject | Object value | An instance of a module
8 | #VTypeStream | Stream | A handle to a stream (of which there are several types). See Streams.
9 | #VTypeModTree | Module tree | A handle to the modules in a state diagram
10 | #VTypeStateDgrm | State diagram | A graphical depiction of VTScada code
11 | #VTypeModule | Module | The code and variables that make up a unit of a VTScada program. See Modules.
12 #VTypeModState Code Value (a)
Module and state 		A handle to a state within a module. See States.
13 #VTypeModStateStmnt Code Value (b)
Module, state, and statement 		A handle to a statement within a state. Cannot refer to any arbitrary function, as type 6 can. See Statements and Graphic Objects.
14 | #VTypeRefParm | Reference parameter | When a steady-state call is made to a module, each of the actual parameters in the call is "bound" to its corresponding formal parameter.
15 <undefined> Array Refers to an entire list of consecutive data values. Each data value has a consecutively numbered index address and may be any VTScada value.
See Array Variables
16 | #VTypePath | Path | A series of vertex values. See Path Variables.
17 | #VTypeTraj | Trajectory | A combination of a Normalize value and a Path value. See Trajectory Variables.
18 | #VTypeRotate | Rotate | Specifies a rotation amount, measured in degrees, around a point. See Rotate Variables
19 | #VTypeBrush | Brush | Brush values are used in layered graphics statements that paint areas of the screen with a uniform color or pattern. See the Brush function.
20 | #VTypePen | Pen | Pen values are used in layered graphics statements that draw lines. Defines the color, style and thickness of a line. See the Pen function.
21 | #VTypeNormalize | Normalize | A graphical scaling value. See Normalize.
22 | #VTypePoint | Point | A location, stored as an (X, Y) pair. See Point.
23 | #VTypeVertex | Vertex | A group of three Point values. See Vertex.
24 #VTypeTransform Transform A transformation matrix, used to map coordinates from one area of the screen to another.
Can only be obtained from the GetTransform function. Used by the GetPathBound function.
25 | #VTypeCodePtr | Code pointer | A handle to an active graphics statement in a particular module or state. Similar to type 13, but with the additional information of the module instance as represented by value type 7.
26 | #VTypePtr | Pointer | Stores data by reference instead of by value, allowing, for example, multiple values to reference the same piece of data as opposed to multiple copies of the data.
27 | #VTypeEditor | Editor | A handle to an editor object, as created by MakeEditor.
28 | #VTypeParseStack | Parser stack | Used by the compiler to allow the compilation to be suspended in the middle of a statement to handle specific code sections such as I/O addresses.
29 | #VTypeTag | Tag | (Unused) Intended to provide engine-level support for scaled variables that could be implemented using a GUI.
30 | #VTypeBitmap | Bitmap | A handle to an image object as returned from MakeBitmap.
31 | #VTypeFont | Font | A handle to a font object, as returned by the Font function.
32 | #VTypeVTSdb | VTScada database | A handle to the VTScada database as returned by the DBSystem function.
33 | #VTypeODBCHndl | ODBC Handle | Provides a connection to an ODBC database.
34 | #VTypeSAPIStrm | SAPI text-to-speech stream | A type of stream for use with Speech Application Programming Interfaces
35 | #VTypeComClient | COM Client Interface | An object that provides an interface to a COM client application
36 | #VTypeCryptoProv | Cryptographic Provider | A handle to the particular cryptographic service provider that includes the key specification to use.
37 | #VTypeCryptoKey | Cryptographic Key | May be either a Session Keys or a Public/Private Key. See Cryptographic Keys.
38 | #VTypeDLLhandle | DLL Handle | A pointer to a structure returned from the LoadDLL function. Used to call functions within the DLL that was loaded. See DLL.
39 | #VTypeDeflateHandle | ZLib Compression Handle | Used by the Deflate function
40 | #VTypeThread | Thread Handle | A script-level hook to the data structure used to represent a thread in a dump
41 | #VTypeBreakWatch | Source Debugger Breakpoint Handle | References a set location in the source debugger. See Working with Breakpoints and Data Breakpoints
42 | #VTypeMiniDumpHandle | Minidump Data Handle | A pointer to a data structure that holds information from a crash dump
43 | #VTypeTimeStamp | Timestamp | A numeric representation of time, measured in seconds since January 1, 1970
44 | #VTypeXMLproc | XML Processor Handle | Serves as a conduit between an XML document and an application. See VTScada Engine XML API
45 #VTypeTypeDefinition
Dynamic Module Definition Deprecated. A handle to the definition of a form of module used as a data container. Created by the MakeType function. This storage is used almost exclusively for handling XML and cannot contain script code (unlike other forms of Module).
46 | #VTypeTypeInstance | Dynamic Module Instance | Deprecated. An instance of a dynamic module, created using the MakeTypeInstance function. This is an object value (type 7) that can only be used to store data - it cannot contain or execute script. Typically these are used when generating module trees for delivery via XML. It is a form of data container, however in general structures (defined by the Struct function) and Dictionaries (type 47) are more efficient and convenient for this role.
47 #VTypeDictionary Dictionary A key-based data container of flexible size, used either on its own to hold volatile data collections or in the definition of structures (see Structures).
ValueType will not return this value unless the dictionary is a "pure" dictionary. A pure dictionary is one for which the root value has not been set. Otherwise, it returns the ValueType of the dictionary's root instead. See Dictionaries
48 | #VTypeComProperty | COM Property | A value exposed by a COM Interface "object". This may be accessed similarly to a typical VTScada value but is maintained by the COM object, not the VTScada engine.
49 <undefined> Module in Context Contains both a module value and an instance of the context module where scope should be resolved.
Normally, scope will be the parent object in which the Module was declared. A Module in Context is used for widgets and plug-ins in VTScada where the widget is declared in AppRoot.SRC, but linked into a tag type such that the widget becomes a Module in Context in the tag instance. References to variables in the widget will then refer to variables in the tag rather than to variables in AppRoot where the widget was declared.
If a Module In Context value is called in steady-state, the parent instance will provide the associated context.
50 | #VTypeHistorianHandle | Historian Connection Handle | For the VTScada proprietary data store, this will be invalidated on an "out of disk space" error, or on loss of access to the file storage. For other databases, this will be invalidated on any connection loss.
51 | #VTypeXMLNode | Dictionary Structure | A WEB_XML_ADDRESS that points to a WEB_XML_NODE. When ValueType() runs against a value and finds a WEB_XML_ADDRESS it treats it the same as a WEB_VALUE_ADDRESS, which sits in front of an array or structure. It then searches through the *_ADDRESS to find what it points to and returns the type of that item, in this case an USER_XML_NODE
52 #VTypePPPHandle PPP Connection Handle. May be passed into the function, PPPStatus() to obtain an information structure.
May be passed to the function, CloseStream() to forcibly close off a connection. Passing it into CloseStream completely invalidates the handle and all data associated with it.(see: PPPStatus and CloseStream)
53 | #VTypeProtobufHandle | Protobuf Handle | Created by the ProtobufParse function and used by the functions ProtobufEncode, ProtobufDecode, and ProtobufInstantiate
54 | #VTypeBubbleHandle | Bubble Handle | Returned by the function, Bubble. Used by a parent bubble to reference its child bubble in calls to BubbleSend, BubbleReceive, and RunInBubble.
55 | #VTypeVOIPAcctHandle | VoIP account handle
56 | #VTypeVOIPCallHandle | VoIP call handle
57 | #VTypeWebBrowser | Web browser | A handle to an embedded web browser.


Value and Type Conversions

The following table shows VTScada value and type conversions.

Value to Convert | Convert To | Condition of Original Value | Returned Value
Code Pointer | Module | Valid value | Valid value
 | Module State | Valid value | Valid value
 | Module State |  |
 | Statement | Valid value | Valid value
 | Object | Valid value | Valid value
 | Text | Valid value | Name of module
Double | Long | Valid value | Valid value
 | Short | Valid value | Valid value
 | Status | Valid value | Valid value
 | Text | Valid value | String representing numeric value
Edit Block | Stream | May only be used in SRead with % option, or in StrLen | Valid value
Long | Double | Valid value | Valid value
 | Short | Valid value | Valid value
 | Status | Valid value | Valid value
 | Text | Valid value | String representing numeric value
Module | Text | Valid value | Name of module
Module State | Module | Valid value | Valid value
 | Text | Valid value | Name of module
Module State Statement | Module | Valid value | Valid value
 | Module State | Valid value | Valid value
 | Text | Valid value | Name of module
Normalize | Double | Valid value | The scaled value
 | Long | In the range of -2 147 483 648 to 2 147 483 647 | The value
 | Short | In the range of -32 767 to 32 767 | The value
 | Outside of range | Invalid |
 | Status | 0 | 0 (false)
 |  | Non-0 | 1 (true)
 | Text | Valid value | String representing scaled value
Object | Module State | Valid value | Module and state in which that object exists
 | Statement | Valid value | Module state and statement number that object is executing
 | Text | Valid value | Name of the module of which that object is an instance
Short | Double | Valid value | Valid value
 | Long | Valid value | Valid value
 | Status | Valid value | Valid value
 | Text | Valid value | String representing numeric value
Status | Double | Unconnected socket | 1
 |  | Connected socket | Invalid
 | Long | Unconnected socket | 1
 |  | Connected socket | Invalid
 | Short | Unconnected socket | 1
 |  | Connected socket | Invalid
 | Status | Unconnected socket | 1
 |  | Connected socket | Invalid
 | Text | Unconnected socket | "1"
 |  | Connected socket | String of stream contents
Tag | Double | Valid value | The scaled value
 | Long | In the range of -2 147 483 648 to 2 147 483 647 | The value
 |  | Outside the range | Invalid
 | Short | In the range of -32 767 to 32 767 | The value
 |  | Outside the range | Invalid
 | Status | 0 | 0 (false)
 |  | Non-0 | 1 (true)
 | Text | Valid value | String representing scaled value
Text | Double | Number string | Number in string
 | Long | Number string | Number in string
 | Short | Number string | Number in string
 | Status | Non-0 number string | 0 (false)
 |  | 0 number string | 1 (true)
Variable | Module | Module variable | The module in which the module variable resides
 | Text | Valid value | Name of variable


Variable Storage, Retention, Access

This topic does not refer to the VTScada Historian or reporting features.

Within a VTScada application, you may need to share values between module instances. You may require values to remain in memory while an application re-starts, or you may want to control how values are shared across the servers running an application. You may also want to restrict access to variables between modules. These tasks are achieved by the use of the following keywords, assigned when defining variables.

  • Network Values - Variables used to update changes on all workstations and servers in a multi-server application.
  • Persistent Variables - Shared variables whose values are kept in a file in addition to RAM so that they can be reset after a server restart.
  • Protected Variables - Variables that cannot be used by modules outside the immediate scope.
  • Retained Variables - A variable that is persisted but not shared.
  • Shared Variables - Values that are shared between modules, but which are not saved to disk.
  • Temporary Variables- Short-lived variables that will disappear when VTScada is shutdown and restarted.

See also: Declaring Constants


Network Values

The purpose of the Network Values service is to update all workstations of a multi-server application when a change to a Network Value variable has occurred. Network Value variables cannot be used in steady state.

If your client is isolated from the server, and changes have occurred to Network Value variables, the client's changes will be overwritten when a reconnection to the server has been made.

Network Value variables are declared within the NetworkValue class,

[(NETWORKVALUE)
    HistoricalLastTS     { UTC Timestamp of last historical data read    };
    NextDailyReportTS    { UTC timestamp of next daily report data read  };
]

and are updated whenever the value for these variables changes on a client or server workstation.

Network Value variables can store any value that you can Pack. (see note) Unlike Retained variables, Network Value variables recognize array element changes, and will update such changes as needed. During startup, only the Network Value variables whose value changed since the last synchronization are obtained.

\NetworkValues.Update

Network Value variables won't see changes within multidimensional arrays. Arrays of Arrays, Structures, Dictionaries, and variables with MetaData must call \NetworkValues.Update after every value change

If using a multidimensional array with NetworkValues, use only dynamic arrays rather than static. You can store dictionaries, but you must use \NetworkValues.Update to update them.

Location and Format Considerations

The values for Network Value variables are stored in a folder named, "NetworkValues" within your application's directory. The name and format of these files is identical to that of the Retained variables (see Retained Variables), however, the extension for NetworkValues files is ".NV", whereas the extension for the Retained variable files is ".VAL". Protected retained variable files have the extension ".VLX".

It is not recommended that you use the Network Values service for tag values, or other constantly changing values (e.g. mouse position). A better use for the Network Values service is for updates to other services.

Network Value Service Subroutines and Modules

In order to make use of the Network Values service, you must first start the service, and then call Register(). An example follows.

If \NetworkValues\Started Main;
[\NetworkValues\Register(Self, "MyModule");
   …
]

NetworkValues\Register

Register(Owner, InstanceName)

Where, Owner is the owner of the variables, and InstanceName is the name of the instance. InstanceName must consist of characters that are valid for file names.

The purpose of the Register module is to allow any module with class NetworkValue variables to retain these variables across instantiations of a module and to have values automatically propagated around the network. If two instances of the same module register with the same instance name, then each of these modules will be affected by the other's changes in values.

In the case of network values being used in a tag, the InstanceName should be the tag's name or Unique ID. If using the Unique ID, use code similar to the following:

\NetworkValues\Register(Self, Replace(\UniqueID, 0, StrLen(\UniqueID), "\", "+"));

Register is a subroutine. After returning, the owner's variables will be set to the current server's version of the values. The caller must wait for NetworkValues\Started to become true before calling the Register module.

\NetworkValues.Update

Not required for most variables. Use only for values in multi-dimensional arrays, dictionaries, structures of structures or combinations of these. (See earlier notes.)

Update(Owner, VarName)

Where, Owner is the owner instance of the variables and VarName is the name of the variables, provided as a text string.

Network Values Service Scheme

The Network Values service is designed to transfer values for any module around the system, and retain those values between starts for the application and instantiations of the module. The scheme used by the Network Values service follows.

  1. DBSystem is created, containing Registered names concatenated with variable names, which are separated by a plus sign (+). The Registered names are also stored in the same DBSystem. Their value is the head of the list of Monitor modules. The values are saved in packed streams in files by the same name as the concatenated name. The retained registered names array also contains the version number for each value. The revision number is always incremented, and is a retained value.
  2. RPC Synchronization is done, and Started is set.
  3. The host module must wait for NetworkValues\Started.
  4. Register(Obj, Name) is a subroutine that launches Monitor. Register performs a ListVars on Obj to get all class variables that will be distributed through remote procedure calls. It then launches sufficient Monitor modules to handle the number of variables. It also sets current values of variables from DBSystem before returning.
  5. Monitor links itself onto a list wherein the registered name is the name of a variable in the RegisterNamesDB containing the object value of the head of the list. The list is self-repairing, and not ordered.
  6. Monitor watches for changes in simple values and 1 dimensional array of values for the variables and then checks if the current value is different from the DBSystem value. If different, an RPC message to the server is sent to set the new value.
  7. The server sends the SetValues message to all clients and itself.
  8. The persistent values are stored in a directory called NetworkValues. Each value has its own file. Each file is a member of a linked list whose head is NetworkHead, and is sorted by the Revision number. This enables the GetServerChanges to easily get the most recent values.
  9. SetValues sets the value in the DBSystem, writes the value to the corresponding file for the name, walks through the list of Monitor modules for the registered name, and sets the variable in each of the registering modules.
  10. If a registering module stops, the Monitor automatically stops since it has been called from the registering module.


Persistent Variables

Normally, variable values are kept in RAM, which means that their value will be lost whenever VTScada is stopped such as in the event of a power failure. This is usually not a problem for most values since they will be read in automatically from the plant I/O devices when the program is restarted. However, certain values such as process setpoints must be maintained, regardless of any interruption. The use of persistent variables solves this problem.

Persistent variables (sometimes referred to as "static" or "persisted" variables) function identically to other variables except that a copy of their value is kept on disk. The file name matches the module name in which the variable is declared, with a .VAL extension. When VTScada is restarted, the persistent values will be read from the .VAL file(s) thereby maintaining the values across restarts.

To define a variable as persistent, add the keyword "Persistent" in the definition:

[
  Persistent LastOKColor     { Last selected OK color              };
  Persistent LastErrorColor  { Last selected Error color           };

]

Persistent variables only get stored to disk when the value is set. A persistent variable with a complex structure (for example, an array or a dictionary) won't be stored when an element changes.
A general workaround is to move the structure in and out of a variable.

For arrays, all elements of the array become persistent values if the array itself is defined to be persistent. But, note that if you have an array (A=New[10];), and one element changes (A[0] = 1;), the modified value will not be written to disk, as "A" itself did not change, but rather its element did.

Also, If A is to be a persistent array, then when defining A as an array with the New function, use the following expression:

A = PickValid(A, New(10);

This allows the persisted values from the last run of the module to be used rather than defining A as a new, empty array.

Use persisted values with caution. Each change in value must be written to disk rather than just to RAM and therefore requires a significantly greater length of time. They should be used only for values that are updated infrequently, such as operator-entered setpoints.

It does not require any additional time to reference or use the value in a persistent variable since a copy of its value is also kept in RAM.

Persistent variables are automatically considered to be shared as well. (See following topic, Shared Variables.)

Any data values supported by Pack may be saved to disk (e.g. arrays, streams, link lists, etc.). Recompiling a module does not delete the persistent variables.

Examples of persistent variables

  1. Create a new script application. (Workspace for Script Applications)
  2. Edit the Graphics module within AppRoot.SRC as follows:
Graphics
[
  Persistent X                  { a persisted variable };
]
Main [
  ZText(100, 100, "Enter a setpoint:", 5, 0);
  ZText(100, 120, "(Press <enter> after typing)", 5, 0);
  WinEditCtrl(220, 105, 280, 85, 0, X, 1);
]
{ End of System\Graphics }
>
  3. Compile and run the run the application.
  4. Type something into the edit field. Be sure to press enter or tab after typing.
  5. Stop the application, then restart. The edit field should show the value you entered earlier.


Protected Variables

On occasion, it may be necessary to limit access to certain variables, preventing access by code outside the variables' scope. This is done by prefacing the variable declaration with the keyword "Protected".

Protected variables (and modules) are not accessible through scope resolution. To put that another way, any variable that is accessible without scope resolution remains accessible, whether protected or not. All use of scope resolution to access a protected variable will fail, even if that variable is accessible without the use of scope resolution. Scope resolution refers to the function, Scope() and the operators "\" and "."

Example:

Using a script application that has one launched module, "LaunchedModule":

{========================== System =================================}
{===================================================================}
(
  System              { Provides access to system library functions };
  Layer               { Provides access to the application layer    };
)
[
  Graphics          Module { Contains user graphics                 };
  WinTitle = "User Application" { Window title                      };
  LaunchedWindow Module "LaunchedWindow.SRC" { launched  child      };
  A = 11;
  Protected B = 22;
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         7, 1);
]
<
{============================= System\Graphics =====================}
{ This module handles all of the graphics for the application       }
{===================================================================}
Graphics
[
  Handle            { object reference to launched submodule       };
  C = 33            { a plain variable                              };
  Protected D = 44  { a protected variable                          };
]

Main [ If ZButton(50, 75, 150, 50, "Launch!", 1);
  [
    Handle = LaunchedWindow();
  ]
  ZText(100, 100,Concat("A is ", PickValid(A, "Invalid")), 5, 0);
  ZText(100, 120,Concat("B is ", PickValid(B, "Invalid")), 5, 0);

  ZText(100, 150,Concat("C is ", PickValid(C, "Invalid")), 5, 0);
  ZText(100, 170,Concat("D is ", PickValid(D ,"Invalid")), 5, 0);

  ZText(100,200,Concat("Self()\C is ", PickValid(Self()\C, "Invalid")), 5, 0);
  ZText(100,220,Concat("Self()\D is ", PickValid(Self()\D, "Invalid")), 5, 0);

  ZText(100,250,Concat("Handle\E is ", PickValid(Handle\E, "Invalid")), 5, 0);
  ZText(100,270,Concat("Handle\F is ", PickValid(Handle\F, "Invalid")), 5, 0);
]
{ End of System\Graphics }
>

And, LaunchedModule as follows:

{=========================== System =================================}
{====================================================================}
(
  System               { Provides access to system library functions };
  Layer                { Provides access to the application layer    };
)
[
  Graphics       Module { Contains user graphics                     };
  WinTitle = "User Application" { Window title                       };
  RunningOnVIC            { TRUE if this is a VIC session              };
  E = 55                     { a plain variable                      };
  Protected F = 66           { a protected variable                  };
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);
]

<
{========================== System\Graphics ========================}
{ This module handles all of the graphics for the application       }
{===================================================================}
Graphics
[
]

Main [
  ZText(100, 100, "Launched window with variables E and F", 5, 0);
]
{ End of System\Graphics }
>

After clicking the Launch! button, the windows will display the following:

Image trimmed to fit this page


Retained Variables

Retained variables can be used when separate instances of a module need to retain a value between instantiations and VTScada executions. Unlike persisted variables, these are not shared. (Persisted variables are equivalent to shared plus retained.)

One application of Retained variables is for user settings, loading all of the new user's customized settings when the username changes. Another is for location coordinates of a dialog box that might be shared by several modules. In this way, you may use Retained variables like a database.

Declaring Retained Variables

Declare a retained variable by using the "Retained" keyword before the variable definition. For example:

Retained My_Retained_Var { Retained Variable };

Assigning Names to Module Instances

Each module instance must be assigned a name. This can be done in one of the following ways:

  • SetInstanceName This function takes two parameters: Instance and Name. Instance is the object value of the module to which the name is to be assigned. Name is the text string name of the instance.

Tags are automatically given a unique name (matching the unique ID) when launched.

  • The name parameter in the Thread function also sets the name of an instance. (All applications are launched in a separate thread with the application name being the thread/instance name.)
  • If an instance name is not explicitly set, an instance name is inherited from the nearest parent's name. If none of the parents have an explicit name, the name "Default" is used.

Setting the instance name will cause all the Retained variables to be reloaded with the values for that instance. Instance names may be changed dynamically.

Retained Variable Value Storage

The values for retained variables are stored in a folder named, "Retained" that exists within your application folder structure. The files containing the retained variable values have the extension ".VAL". The name uniquely identifies the module instance for which the retained value is meant. This is typically done by using the parent-child hierarchy of the module plus a unique identifier created for that module instance. For example, Totalizer tags retain their last logged value. This is stored in a file with the built as System-Code-TotalizerTag-LastLoggedValue+UniqueID.VAL

Retained values are written to disk whenever they change. They are written using the Pack scheme, allowing complex arrays and linked lists to be persisted. Note that any modified values that are indirectly pointed to from the retained value (array elements) will not trigger a rewrite of the retained variable to disk. However, when the instance terminates, either through an instance name change or a stopping instance, the retained values will be written.

This implies that crashes, power failures, etc., can result in the most recent retained values not being on disk if these values contain pointers to values.

Retained Variables and Statically Declared Arrays

Retained variables enable you to specify a default value for a statically declared array. If specified, all the elements of the array will be set to this value when the array is instantiated. For example, an array declaration such as:

[
   Data[10] = 0;
]

will result in all 10 elements of the data array to have the initial value of "0".

If the array with the initial value specified has a default value, the default value will only be used if there is no suitable retained value .VAL file.

Recompiling to change the number or size of dimensions of a retained variable will cause any retained .VAL files previously saved with the old variable format to be ignored.


Shared Variables

When running multiple instances of a module within one application, each will keep a separate copy of its own variables. Prefixing a variable definition with the keyword "Shared" makes that variable a shared variable. When multiple copies of one module are running and using this shared variable, all copies use the same value. For example, if one module writes the value 4 to a shared variable, X, all other copies of that module will see the value 4 in X. X is global to the module instances and only one memory location will be used for all instances of X. Shared variables are deleted only when the application stops running.

Shared variables are not shared across differing modules or across applications.

A common use of Shared is often found within tags when declaring local instances of modules that are plugins, configuration folders, and widgets. By declaring these as shared, you avoid the overhead of creating a fresh instance of each module for each tag instance.

Practice with shared variables

  1. Create a new script application. (Workspace for Script Applications)
  2. Add the following declaration to the variables section of AppRoot.SRC (line 10):
  LaunchedWindow Module "LaunchedWindow.SRC" { a launched  child module  };
  3. Edit the Graphics module within AppRoot.SRC as follows:
Graphics
[
  Shared X              { a shared variable                      };
  Y                     { an unshared variable                   };
]

Main [ If ZButton(50, 75, 150, 50, "Launch!", 1);
  [
    LaunchedWindow();
  ]
  ZText(100, 100, Concat("Edit X. Currently: ", PickValid(X, "Invalid")), 5, 0);
  ZText(100, 200, Concat("Edit Y. Currently: ", PickValid(Y, "Invalid")), 5, 0);
  WinEditCtrl(100, 140, 180, 120, 0, X, 1);
  WinEditCtrl(100, 240, 180, 220, 0, Y, 1);
]
{ End of System\Graphics }
>
  4. Using a text editor, create a new file named LaunchedWindow.SRC. Contents follow. Note that this is very nearly an exact copy and paste from AppRoot.SRC. Variations shown in bold font.
{============================== System =================================}
{=======================================================================}
(
  System                { Provides access to system library functions };
  Layer                 { Provides access to the application layer    };
)
[
  Graphics         Module { Contains user graphics                    };
  WinTitle =      "Launched Application" { Window title             };
  RunningOnVIC            { TRUE if this is a VIC session              };
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         7, 1);
]

<
{============================= System\Graphics ========================}
{ This module handles all of the graphics for the application          }
{======================================================================}
Graphics
[
  Shared X                  { a shared variable                      };
  Y                         { an unshared variable                   };
]

Main [
  ZText(100, 100,Concat("Edit X. Currently: ", PickValid(X,"Invalid")),5, 0);
  ZText(100,200,Concat("Edit Y. Currently: ", PickValid(Y,"Invalid")),5, 0);
  WinEditCtrl(100, 140, 180, 120, 0, X, 1);
  WinEditCtrl(100, 240, 180, 220, 0, Y, 1);

]
{ End of System\Graphics }
>
  5. Compile and run the application.
  6. Click the launch button twice to open two instances of LaunchedWindow. Move the windows so that you can see each.
  7. Enter values for X and Y in each of the windows, noting the results.
  8. Close both the launched windows, then reopen. The value of X should remain.
  9. Stop, then restart the application, launching the windows. X should be Invalid to start.

Shared versus persistent variables.

  1. Edit both AppRoot.SRC and LaunchedWindow.SRC, changing the declaration of X from shared to persistent.
  2. Compile and run, noting any difference in behavior. (There shouldn't be any difference at this point.)
  3. After running, stop then restart the application, reopening the launched windows. Values of X should persist for each of the two modules, AppRoot and LaunchedWindow.


Temporary Variables

In cases where an application is being modified online, it may be useful to create short-lived variables that will disappear when VTScada is shutdown and restarted. These are known as temporary variables. Temporary variables are kept in RAM while VTScada is running, so they will continue to exist even though the application that uses them is stopped and restarted. They are not written to the .RUN files of the application, though, so after VTScada is stopped or the application is recompiled, they will cease to exist. For the application to use them again, it must once more create them using an AddVariable statement.

Temporary variables should not be referenced like other variables, but should be accessed using one of the following functions to reduce potential problems in their use:

  • FindVariable
  • ListVars
  • Scope
  • VarAttributes
  • Variable


Data Sharing in a Client/Server Environment

VTScada benefits from a well-tested Remote Procedure Call (RPC) system, which manages inter-server communications (from one VTScada server to another). Advanced users who are trying to write code to manage I/O synchronization or alarm evaluation are advised to look first to this built-in system.

VTScada is composed of many independent modules that run locally. The RPC system ensures that information about those modules is synchronized between servers and that only a single machine can act as the server for a service at any time.

For example, many modules run as tags. The RPC engine guarantees that their stored parameters are synchronized among the machines in the server list. Variables that are not defined as parameters are not synchronized unless they are registered with their own RPC service or use the service provided by another module such as a driver.

Consider a typical example of an I/O tag as it requests and then displays a value:

  1. The I/O tag asks the attached driver to provide the value associated with a given address.
  2. The driver requests that value using its own process, which is usually a protocol exchange with an external device such as a PLC.
  3. This request operation takes place only in the server currently assigned to the driver’s RPC service. (The current primary server for the driver.)
  4. After the request operation, the driver calls the standard VTSDriver service, which updates the local tag through direct assignment.
  5. The VTSDriver service then sends an RPC update message to the instances of this driver service on all other connected servers.
  6. Those update their local instances of the requesting tag, thus assuring that the same tag reports the same value on all servers.

This process and more is shown in the following illustration. It assumes that one machine is currently the server for all communications, historian and alarms. A dashed arrow means that the request will be usually ignored, while dash-dot means it will be ignored on pure clients:

RPC process for I/O, logging, alarms and alarm notifications

Let's continue this example by considering both logging and alarms.

If the I/O tag has an attached Historian, and if it decides that the new value is to be logged (the change is greater than the deadband or a set time period has elapsed) then the I/O tag will ask the Historian to log the value. Because all instances of the tag, running on different servers, receive the same data, and have no knowledge of the source of that data (direct communication or RPC broadcast), they are all going to request the Historian to store the value and timestamp. Conflicts are avoided because the Historian has an RPC service of its own. It will only perform data authoring if it is running on the current primary server for the Historian service. The action proceeds as follows:

The Historian running on the current primary server will write the data to the configured data store.

Following the write, it will send an RPC broadcast message to all other historian servers, which will store a copy of the written data, rather than the version sent by the local I/O tag. This guarantees that it will be assigned the same timestamp on all servers, thus avoiding duplicate records.

If the new I/O value changes the alarm status, then a parallel task will run, either inside the I/O tag or through a connected alarm tag. This task will evaluate the value locally on all machines by calling the Alarm Manager, which also runs an RPC service.

The alarm status returned by the tag itself will be defined locally. The alarm event will be raised by the Alarm Manager, but only on the current alarm server. Like the Historian, it will record an alarm event to the database and broadcast that to all other servers.

A significant difference from the process used for logging I/O data is that Alarm Historian tags are usually configured to enable Client Storage. This means that all clients act like backup servers, regardless of whether they are included in the server list. They will always receive new alarm records from the current primary server and will try to log those events themselves if unable to communicate with the server.

The VTScada Alarm Notification System also uses its own RPC service and is based on the alarm event records stored by the Alarm Manager. Notification behavior is synchronized across the network based on the status currently defined on the database.

For more information about VTScada's Remote Procedure Call service, see: RPC Manager Service


Control Structures

Here, "control structures" means code to control which statements in a module will run, how many times they will repeat, and the order in which statements will execute.

While true that there is no way to predict (let along control) the order in which steady-state statements will execute, there is still a place for control structures in VTScada code. The first is within a script block where standard control structures such as IfThen and WhileLoop may be used. The second is through the use of steady-state If statements that transfer execution from one state to another, effectively providing state-based control.


Control Structures Within Script Blocks

A script block by itself is a type of control structure. Triggered by an action statement (IF <condition is true> ...) a set of statements will execute in order as written. After a single run-through, the action statement will be checked again and either transfer to another state, repeat the script block if the conditional is true, or remain in steady state if it is false.

Within a script block, the following functions may be used:

Case

Returns the nth parameter of a set, based on a variable index value. Parameters can be expressions.

DoLoop

Executes a set of statements at least once, repeating so long as a conditional parameter remains true. The conditional is checked after the statements run once.

Execute

Executes a group of statements as a single entity in structures that would otherwise allow only one statement to be executed such as Case or IfElse.

IfElse, ?:

Executes one of two parameters based upon a condition parameter. You can use either the IfElse function or the ?: operator, but as a matter of style choose between them as follows:

To control flow, use IfElse:

IfElse(Tired,
  Sleep();
{ Else }
  Work();
);

To return a value or expression conditionally, use the ?: operator:

Mood = IsHungry ? "Sad" : "Happy";

IfThen

Conditionally Execute Statements. This statement executes a statement if the condition parameter is true.

WhileLoop

Executes a set of statements zero or more times, repeating so long as a conditional parameter remains true. The condition is checked before the statements are executed.

Note that there is a significant difference between the following two control structures: Given X, initialized to zero.

If X < 10;
[
   X++;
]

versus

If X < 10;
[
  WhileLoop(X < 10,
    X++;
  );
]

In the first instance, the If statement will be re-evaluated each time X increments and other statements within the state will have a chance to run at that time. In the second, the If statement will not be re-evaluated until after the WhileLoop finishes, holding execution within the script block for all ten increments of X. The point is that a loop that runs a very large number of times within a script can cause the rest of the state to essentially freeze until it finishes. Use loops with care.


States as Control Structures

An action trigger, which begins with an If statement, and the state that will be activated by that trigger, together make a form of control structure. Consider the following two examples:

Tab Selection

Every tag's configuration panel (properties dialog) has a set of tabs. When a user selects the tab, a different set of configuration options is shown.

The IO state is active. States for ID, AlarmSetup, etc. are not and therefore are not seen.

The AlarmSetup state is active.

For every tab of the panel there will be a matching state, within which you will find the following statement:

  If Current != 0 && !*PtrWaitClose Switch;

Current is set by VTScada when the user clicks on a tab. (Tabs are numbered from left to right starting with zero.) PtrWaitClose is not relevant to this discussion but in essence means: "the user hasn't clicked somewhere to close the configuration panel". Switch is the name of the following state, copied directly from the module behind the Digital Status tag's configuration panel.

Switch [
  If Current == 0 ID;
  If Current == 1 IO;
  If Current == 2 AlarmSetup;
  If Current == 3 ExternalAlarms;
  If Current == 4 Quality;
  If Current == 5 Display;
  If Current == 6 Historian;
]

The Digital Status tag's configuration panel contains seven tabs. It would be inefficient to put code into each state to check the value of Current and decide which state to move to. Therefore, upon a change in Current, every state transfers control to Switch, which holds the logic for determining which tab (state) to display next. The Switch state displays nothing and calculates nothing - its role is simply that of control structure.

States that wait

In every module behind a VTScada report, there is logic that takes the operator's selection of tags, date ranges, and other parameters and assembles those selections into one or more calls to GetLog or GetTagHistory, running those functions as a launched module.

  If 1 GetMoreData;
  [
    { Retrieve the first set of data }
    TagObj = LocalScope(\VTSDB, Tags[TagIdx]);
    Fields = ...;
    Modes = ...;
    { Initialize the error and result variables }
    Error = Result = Invalid;

     { Get the data  }
    \HistorianManager.GetTagHistory(&Error, &Result, ...);

It may take time for GetTagHistory to complete. But, since it was launched, it will continue running after this script block finishes and control transfers to the state GetMoreData

GetMoreData [
  If Valid(Error) GetEvenMoreData;
  [
     { Save the returned data }
    Data[0] = PickValid(TagObj.Description, TagObj.Name);
    Data[1] = Result[0][0];

The only steady state statement in GetMoreData is the action trigger. This waits for Error to become valid, which it will when the call to GetTagHistory completes. Then the returned data is processed, and the cycle can repeat until all of the necessary calls to GetTagHistory have completed and the report can be assembled.

The preceding is far more efficient than trying to create a loop or timing structure to watch for GetTagHistory to complete. You simply wait for Error to become valid, using that event as an action trigger to continue building the next part of the report.


Examples and How-To's for Scripting

The range of what you can achieve with the VTScada language is best described by the word "anything". Topics within this chapter will show you how to do basic tasks such displaying graphics and gathering user input, as well as more complex tasks such as building a new type of report or creating a new type of tag.


Script Code Examples

Here, you will find a set of examples of VTScada script code modules that you can add to your applications. In nearly all cases where you want to extend the features of an existing application, you will need to create a new module and declare it in the correct section of your application's AppRoot.SRC file. There are two exceptions that should be noted before starting:

  • Before writing any code, explore the features of VTScada. Many times, people have started to write code only to discover that existing features can be adapted to their needs.
  • If the goal is to add new user interface elements, add your code to the .SRC file of an existing page or custom widget.

Otherwise, if your goal is to extend a VTScada application by adding a new tag, driver, report, data-entry wizard, etc. then do the following:

  1. Using a text editor, create a new file in the application folder.
    The new file should be given a name that matches what you intend to call your module, and must have the extension, ".SRC".
  2. Write your VTScada code in that new file.
  3. Using a text editor, open AppRoot.SRC in the application's folder.
  4. Select the correct class group and declare your module within it as follows. (Class Declarations for Modules in AppRoot)
[ (PLUGINS) {===== Modules added to other base system modules =====}
   MyCustomReport  Module "15MinSnap.SRC";
]
  5. Use the application's Import File Changes tool in the VTScada Application Manager. When prompted, add the new file to your application.

Importing new files


A 15-Minute Snapshot Report

This example shows how to create a new type of report, and how to add a new module to an existing VTScada program. The result will be a snapshot report that works on a fifteen-minute basis rather than hourly or daily.

This is a minimalist example that works by making a small adjustment to existing code. As such, the range of options is limited. For a complete overview of how to create this report from scratch see: Script Custom Reports

  1. Select an existing application, or create a new one.

Do not select or create a script application.

Use great care if attempting this within a running production application. Better to experiment within a test application or a clone.

  2. Using a text editor, create a new file in that application's folder.
  3. Name the file 15MinSnap.SRC
  4. Copy the code following step 10 into that file and save it.
  5. Using a text editor, open the application's AppRoot.SRC file.
  6. Declare the module within the (PLUGINS) section.

The result should appear as follows.

[ (PLUGINS) {===== Modules added to other base system modules =====}
   15MinSnap Module "15MinSnap.SRC";
]

(There will already be a (PLUGINS) section - do not add a second one.

  7. Save the file and click the application's Import File Changes button.
  8. Click OK to import the new module.
  9. Start the application if it is not already running. (It was not necessary to stop it to do the preceding steps.)
  10. Open the Reports page. Your new report should be available in the list of report types.
{============================ 15MinReport ===========================}
{ This plugin modifies the hourly snapshot report to be every        }
{ 15 minutes                                                         }
{ Groups : Loggers                                                   }
{ Areas : All                                                        }
{====================================================================}
(
   Reporter { Object value for call-backs };
   Start { Starting time };
   End { Ending time };
   Tags { List of tag names to report on };
   Vars { List of vars within tags };
)
[
  { Set up this module to become a plug-in for the reports }
   [(POINTS)
      Shared Report;
   ]

   Constant TypeFilter = "Loggers" {type of tags to use in the report};
   Constant ReportName = "15 Minute Snap" {title for the report };
   TimeStamp { Time of last value returned };
   Obj { Instance of report };
]

Init [
   If 1 Wait;
   [                                       { 15 minutes = 900 seconds }
      Obj = \SnapshotReport(Reporter, Start, End, Tags, Vars, 900, ReportName, 4 );
   ]
]
Wait [
   TimeStamp = Obj\TimeStamp; {ensures that the report object was created before this module ends }
   If !Valid(Obj);
   [
      Slay(Self, 0);
   ]
]
Closed Troubleshooting:
  • The application won't compile.

There is a typographic error in your code. Note the line number given in the error dialog. This gives you a starting point for locating the error.

  • The report is not available.

Ensure that you typed the code exactly as shown.

Ensure that the declaration was placed in the existing (PLUGINS) section of AppRoot.SRC, and was placed before the closing square bracket of that section.

Ensure that the Load File Changes button was pressed and no error dialogs opened as a result.


HideVAM Based on Security Privileges

The HideVAM application property can be set true to hide the VTScada Application Manager (VAM) from view. While useful, this is not especially convenient since it depends on having an application set to auto-start, and at least one user account in that application granted the privilege of seeing the VAM.

You can create a service module for any application that, while the application is running, will control the value of HideVAM on a workstation based on privilege or other property of a logged-in user.

The complete text of the module is as follows. It uses the SecurityCheck function to inquire as to whether the signed-in user possesses the Manager privilege (PrivBitManager). HideVAM is then set to the opposite of the test for this privilege (thus the VAM is not hidden if the privilege is set).

You must use HideVAM rather than the older version, HideWAM. HideWAM is now checked only on startup, and is only used to set the initial value of HideVAM.

{========================== HideVAM ==============================}
{ Hides the VTScada Application Manager based on security level   }
{=================================================================}
[
  CanConfigure             { Set if we can view VAM               };
]

Run [

  CanConfigure = PickValid(\SecurityManager\SecurityCheck(
                      \SecurityManager\PrivBitManager, 1), 1);

  If Watch(1, CanConfigure);
  [
     { Set the WAM's visibility based on security manager check }
    \SysLib\HideVAM = !CanConfigure;
  ]
]
{ End of HideVAM }

You may choose any security privilege you wish. Reminder: Privilege numbers can be displayed in the Privileges dialogue. (Protect Pages and Output Tags)

The module must be declared in the [Services] section of the application's AppRoot.SRC file.

When VTScada is run as a Windows service, this setting is ignored.


A First Order Filter for a Script Tag

This example demonstrates how to use Script tags by creating a module to do a first order filter of an analog value. The instructions are written for use with the Training Simulator, but it can be used with any VTScada application that has a tag with an analog value.

A first-order filter is used to smooth out noise from a value that tends not to change rapidly. Over time, it will match the value of whatever tag it is watching. It will lag changes, and transient spikes will have little effect on the value.

(New filter value) = 0.9 * (Old filter value) + 0.1 * (New data source value)

In this example, the parameters PointObj and SciptObj must be present by definition for use in a Script tag. PointObj will be the tag selected for the "In Tag Scope" parameter of the Script tag. (That is, the analog value to be watched.) ScriptObj points is a self reference to the script tag that this module will be used within. This provides the hook between the Script tag and a module.

In this example, the calculation is done every two seconds, and that calculation exists in a script block, therefore running only a single time each two seconds. If you prefer, you could change this to a Watch() on the PointObj tag's value if you wanted code that executed on change rather than on time.

  1. Copy the following code into a new file.
  2. Save the file as FilterFor.SRC in the tutorial application's folder.
    (Or application of your choice.)
  3. Declare the module in the Plugins section of the AppRoot.SRC file.
  [ (PLUGINS)     {===== Modules added to other base system modules =====}
    FilterFor Module "FilterFor.SRC";
  ]
  4. Import File Changes.
  5. Create a new Script tag in the application.
  6. When configuring, select an analog tag such as a tank level or a pump flow as the scope tag.
  7. Type the name you used when declaring your module in AppRoot (FilterFor).
    The tag scope will vary from this example according to your choice of application and tag.
  8. Draw your script tag near whatever it is watching. Run the application.
{============================ Filter Module =======================}
{ This module is used to do a First order Filter of an input point }
{   Current Value = .1 * new value + .9 * previous value           }
{ The result is stored into the script point's value variable      }
{==================================================================}
(
  PointObj    { object value of analog to monitor };
  ScriptObj   { script object                     };
)
[
  PreviousValue { store the last calculated  value };
]
Filtering [
  { ... every two seconds ... } If AbsTime(1, 2, 0);
  [
    { Ensure there is a valid value the first time through }
    PreviousValue = PickValid(PreviousValue, PointObj\Value, 0);
    { Calculate the filtered value }
    ScriptObj\Value = .1 * PickValid(PointObj\Value, 0) +
                      .9 * PreviousValue;
    { Save for the next time }
    PreviousValue = ScriptObj\Value;
  ]
]


A Numeric Widget with Rising / Falling Trend

Level going up: Level going down:

This widget is built using a standard VTScada Numeric Value widget and two arrow images. Code is added to the opacity property of the arrows so that only the appropriate one is visible at any time.

While you might be able to craft an expression for the opacity property in the Idea Studio, it is far easier to add a few lines to the widget's source file. One significant advantage is that in the source code file, you will be able to create a local variable to save older values of the linked tag for comparison to the current value without needing to create a Calculation tag.

Start with a basic widget. This example uses a Numeric Value widget, linking it to the first available Analog Status tag in an application. An up arrow and a down arrow were drawn on top of each other beside the widget. The Numeric Value widget's properties were modified to right-align the text. Following this, the three objects were grouped into a new Tag Widget, and the Tag Icon Marker removed.

We modified the list of Tag Types, adding both Analog Input and Calculation tags to those for which this new widget can be drawn.

Opening the source code file, we see the following. The visibility (opacity) parameter of both arrows is shown in bold.

{================================ Tag Widget =================================}
(
  DisableTrend      Status;
  DisableNavigation Status;
  DisableTooltip    Status;
)
[
  Shared UserMethods (LIBRARIES);

  Shared AnalogStatus (POINTS);
  Title = "k7uU1LO";
  Shared AnalogInput(POINTS);
  Shared Calculation(POINTS);
]

TagWidgetMain [
  If Watch(1);
  [
    DisableTrend      = PickValid(DisableTrend,       0);
    DisableNavigation = PickValid(DisableNavigation,  0);
    DisableTooltip    = PickValid(DisableTooltip,     0);
  ]
  GUITransform(0, 26, 61, 0,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               PickValid(\Root.Number, Scope(VTSDB, ":AnalogStatus", TRUE)\Number)("<FF000000>",
                            1, 1, 2, Invalid, 3, "<00000000>", 3, 1, 0, 0, 0, 0));
  GUITransform(67, 25, 82, 2,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "Library", TRUE)\Bitmap("Bitmaps\Arrows\Larrow8U.bmp"));
  GUITransform(67, 25, 82, 2,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "Library", TRUE)\Bitmap("Bitmaps\Arrows\Larrow8D.bmp"));
  \Common(GetModuleRefBox(Self, 0), GetModuleRefBox(Self, 1),
          GetModuleRefBox(Self, 2), GetModuleRefBox(Self, 3),
          DisableTrend, DisableNavigation, DisableTooltip);
]

The current value of the linked tag is available in \Root.Value. To know whether this is increasing or decreasing, you'll need to compare that to the previous value, therefore you need a variable in which to store that value, code to compare the previous to the new, and code to store the current value as previous, following the comparison.

Let's start with very simple code and then look for ways to improve it.

Add two variables:

LastValue        { store the previous value of the linked tag.                };
TrendDirection   { positive when increasing, negative decreasing, 0 otherwise };

Now for the comparison. LastValue starts as Invalid (and \Root.value) might as well) so the TrendDirection begins as zero.

 If Watch(1, \Root.Value); { initially and on change... }
  [
     TrendDirection = PickValid(\Root.Value - LastValue, 0);
     LastValue = \Root.Value;
  ]

In the up arrow, replace the visibility parameter with a test for a positive TrendDirection:

  GUITransform(67, 25, 82, 2,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               TrendDirection > 0, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "Library", TRUE)\Bitmap("Bitmaps\Arrows\Larrow8U.bmp"));

Similarly, for the down arrow: TrendDirection < 0

Save your code, Import File Changes and try the new widget.

Suggestions for improvement:

  • This example has no allowance for system noise. The arrow will flicker up and down if the value fluctuates by a small value. You might add a deadband to the comparison to filter out noise. But, if doing so, be careful to allow for slowly increasing or decreasing trends as opposed to system noise. Also, if using a deadband, it should be relevant to the scaled range of the linked tag rather than set as a constant. If the widget is for only analog tags, you can use \Root.ScaledMax and \Root.ScaledMin.
  • Small reversals versus overall trends. If the overall trend is up, but the operator glances at the display just after a momentary step down, they might be misled. Rather than compare to the previous value, you might want to compare to a first-order filter of the trend. Refer to the example, A First Order Filter for a Script Tag for relevant code that you might use here.
  • A horizontal arrow might be better than no arrow when the trend is level.
  • You could indicate the magnitude of the trend by rotating a single arrow instead of revealing only an up or down arrow. If doing so, you will need to restrict the angle of rotation between zero and 180, where 90 indicates no change, zero is the largest possible amount and 180 is the largest possible negative rate.

Be careful when comparing values that might be Invalid, such as those coming from I/O tags. Use StrictlyEqual or StrictlyNotEqual rather than simple == or != comparisons if you add code to compare any value to \Root.Value.


Time and Date

Viewing: Scripting > Examples and How-To's for Scripting > Time and Date

Concepts:

VTScada and Time Zones

Reference:

Date Formatting Codes

Date Formatting Strings

Time Formatting Codes

Time Formatting Strings

Time and Date

Within VTScada, all logging is done using UTC timestamps. Most other time-related tasks will use the current time of the server running the application. Code that refers to the time of day will typically use either Now or Seconds, both of which return the number of seconds into the current day in the machine's time zone. Code that refers to a date will typically use the Today function, which returns the number of days (also in the current time zone) since the beginning of the standard Unix epoch (January 1, 1970). Formatting functions are available to translate those values into human-friendly time and date displays. The CurrentTime function returns a combination of the two as a timestamp value, defaulting to UTC time, but available for any time zone.

Recorded timestamps and all internal logic should use UTC, with conversion to the current user's timezone happening at display time. Do not use Now, Seconds, or Today for recorded timestamps or for internal logic.

Time Zones, Daylight Savings Time

Universal Coordinated Time (UTC) is indifferent to time zones and daylight savings time. Time proceeds at the rate of one second per second, and each day begins at midnight Greenwich Mean Time. The ConvertTimeStampfunction is available to help you convert from one time zone to another, including to and from UTC.

Units for Time:

Now() returns an even number of seconds, updating according to the provided numeric parameter. Seconds returns a double value slightly more accurate than 1 microsecond, however, when that value is assigned to a float type variable, it is rounded to about 7 significant digits. This can reduce the accuracy, especially later in the day when the seconds count becomes large. To obtain a reasonably accurate time stamp, the expression Seconds % 1 can be used to return fractions of a second since the last second mark.

These date and time numbers may be manipulated to determine elapsed time between two events simply by taking the difference between the time and date of the two events. One of the more effective ways to accomplish this is by using the CurrentTime function. You can use the single date and time number that is returned by this function to easily calculate the elapsed time between events or to calculate the date and time at a fixed offset.

By using UTC, you also avoid errors if the time interval spans the start or end of daylight savings time in the local time zone. Always use UTC timestamps for internal logic, converting to the user's time zone only for display purposes.

The date and time numbers can be converted into text values for display purposes using the Date and Time functions. The values returned from these functions may have a variety of formats and may be displayed on the screen using a GUIText statement. The Now function can be used in a statement to give the time suitable for a Time function, or to display a simple clock.

Numeric values of the day, month, and year may be extracted from a VTScada date value (number of days since January 1, 1970) using the Day, Month, and Yearfunctions. The reverse process of combining the day, month, and year may be done using DateNum.

Note that Date() expects days since Jan 1, 1970 and that Time() expects seconds since midnight. Given a UTC timestamp (SomeTimestamp) in seconds since Jan 1, 1970 and the fact that there are 86400 seconds in a day, you can format the timestamp as follows:

If ! Valid(LocalNow);
[
  LocalNow = ConvertTimestamp(SomeTimestamp, Invalid, Invalid, 3);
  DisplayNow = concat(Date(LocalNow / 86400, 4), " - ",
                           Time(LocalNow % 86400, 2));
]


VTScada and Time Zones

Viewing: Scripting > Examples and How-To's for Scripting > Time and Date > VTScada and Time Zones

Concepts:

Time and Date

Reference:

Date Formatting Codes

Date Formatting Strings

Time Formatting Codes

Time Formatting Strings

VTScada and Time Zones

VTScada provides three time zone functions:

  • TimeZoneList(): The TimeZoneList() function provides a list of time zones.
  • ConvertTimestamp(): The ConvertTimestamp() function converts a timestamp between different time zones.
  • TimeZone(): The TimeZone() function returns information on the current time zone, such as the time zone name.

Note that TimeZoneList() and ConvertTimestamp() depend on information in the Windows system registry that is not localized on non-English versions of Windows operating systems, however, TimeZone() does. This causes problems when you need to convert a timestamp to or from the local time zone, as the result of TimeZone(2) is not suitable as a parameter to ConvertTimestamp() on non-English systems.

We recommend using TimeZone(3) instead of 0. Using TimeZone(3), the time will be converted to the current timezone of the thin client session if the GUI code is running for a thin client. Using 0 makes it always use the server's timezone.


Timers and Timing

Viewing: Scripting > Examples and How-To's for Scripting > Time and Date > Timers and Timing

Concepts:

Time and Date

VTScada and Time Zones

Reference:

Date Formatting Codes

Date Formatting Strings

Time Formatting Codes

Time Formatting Strings

Timers and Timing

The functions listed here can help you write code that will execute on schedule. Developers who are creating tag-based expressions should note that the Trigger tag is designed for exactly this purpose, and in certain cases may be easier to use than an expression.

VTScada includes an application property at the \Code level named SecondFlasher. The value of this property changes from 0 to 1 once a second, as near as possible to the change of the second. In most cases, it is better to watch for the change of \SecondFlasher than to burden the system with an additional function to calculate one-second intervals.

AbsTime(Enable, Interval, Offset)

When enabled, becomes true when any multiple of Interval seconds since midnight has passed. Times that are not evenly divisible by Interval can be obtained by adding an offset. Because this function is tied into the real time clock, it is not subject to drift as is the TimeOut function. It is useful when you want to tie an event to a particular time of day rather than to a fixed time delay.

CurrentTime(Type)

Returns the number of seconds since Jan 1, 1970. Set Type to 1 for UTC time.

TimeArrived(UTCTime)

Becomes true when the specified time (in UTC format) arrives.

RTimeOut(Enable, NumSeconds)

A cumulative timer. Becomes true when NumSeconds have passed. This is similar to TimeOut, except that it remembers the elapsed time accumulated so far, even when the enable parameter is false. For example, it can be used to test when a certain piece of equipment reaches a specific total cumulative running time.

TimeOut(Enable, NumSeconds)

A continuous timer. Becomes true when an uninterrupted NumSeconds have passed. This function is often used in action triggers to cause an event to occur after a time delay. If the time of the event is meant to be relative to a randomly occurring event, TimeOut would be the most appropriate function to use.

For a complete list of time and date related functions, see the Time And Date subsection of the Function Reference page.


Script Custom Reports

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.


How Reports Collect Data

All reports make use of the GetTagHistory(1) function to query logged data. This function returns a pointer to an array of values from each tag, according to the query parameters. It also returns a pointer to a variable which will contain an error code. That variable will be INVALID until GetTagHistory completes, at which time it will be set to zero for success or a numeric value to indicate the error.

The main query parameters include:

  • The object value of the tag whose data you are querying.
    If querying a set of tags, launch a separate instance of GetTagHistory for each.
  • The start and end times for the query in UTC.
    Note that the report page and report tag present time using the local time format. Your report module must convert that to UTC before running the query.
  • The query mode, specifying whether you want raw data or an aggregation such as minimums or maximums over a time period.
  • The time period to use for aggregations. This is usually not the same as the difference between the start and end times. For example, an operator might want an hourly snapshot report for the previous 24-hour day.

The resulting array of data is then formatted for the report. Note that the following options are available when you write your own reports:

  • You can control launches of GetTagHistory when querying many tags:
    a) A very large number of queries will take time to complete. You can break that into several sets of queries, updating a progress display to inform the operator that the task is underway.
    b) Launching an extremely large number of queries at the same time may over-tax system resources.
  • You can create any title, header, and formatting that you wish, although you are advised to keep the formatting simple.
  • Do post-processing of the returned data.
    You can present the returned arrays exactly as obtained, or you can use VTScada's math libraries to analyze, filter, sort and summarize the data before presentation.

The report generation process

(1)GetTagHistory replaces the older function GetLog. GetLog is still supported and Legacy applications that made use of that function can continue to do so.


Report Formatting

VTScada reports are designed so that they can be sent to a range of output formats including a text document, the system printer, an email, or an Excel spreadsheet. For this reason, they are designed with a minimum of complicated formatting. Each report will contain a title (usually including the date range), rows and columns of data, and very little else.

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.


Type Filters

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.


Query Modes and Time Ranges

When combined, these two parameters determine what report will be generated from a given set of tags. The choice of Mode determines how the raw data will be retrieved. The choice of time range selects the amount of data included in each of Mode's calculations. Each works with the other.

The VTScada Function Reference has the following to say about the Mode parameter in both GetLogand GetTagHistory:

Mode: Required. Indicates the mode of data collection.

Note that the mode is useful only when the TPP(*) parameter is valid and greater than 0. Mode may be one of:

Mode | Data Collection
0 | Time-weighted average
1 | Minimum in range
2 | Maximum in range
3 | Change in value over the range
4 | Value at start of range
5 | Time of minimum in range
6 | Time of maximum in range
7 | Sum of zero to non-zero transitions
8 | Sum of non-zero time
9 | Totalizer
10 | Obsolete. Maps to 4
11 | Difference between the start and end values of a range (see comments in GetTagHistory)

It is possible to retrieve more than one mode in a single GetTagHistory statement. To do this, pass an array of values in as the Mode parameter.

(*) "TPP" in the above description, is the Time Per Point (or Time Per data Point) parameter.

By adjusting these two parameters, and using the example code shown in the topic "Common Features of a Report Module", you can create a wide variety of reports. The following table provides a few suggestions:

Mode | TPP | Report
7 | 3600 (1 hour) | Pump starts per hour
8 | 86400 (1 day) | Daily total running time
9 | 3600 | Hourly totals
1 & 2 in an array | 900 | Minimum and Maximum values each quarter hour


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.


Example: Custom Snapshot Report

Elsewhere in these notes, there is an example of A 15-Minute Snapshot Report that works by modifying the call to the built-in Snapshot report. That example is recommended to readers who are interested in making small adjustments to reports without needing to know a lot about VTScada script code.

This example is for readers who are interested in knowing more about VTScada script code to build complex custom reports.

Of particular interest in this example is the use of arrays. Assume that the operator selects N tags for the report. Correspondingly, the result will have an array of data. Assume also that the operator selects a time span that includes many 15-minute intervals. For each tag in the result array, there will be an array of snapshot data. Read the example carefully to see how those arrays are handled.

  1. Start with a report template:
( { Parameters }
  Reporter        { Object value for call-backs     };
  Start           { Starting time (local, not UTC!) };
  End             { Ending time                     };
  Tags            { List of tag names to report on  };
)
[ { Variables }
  { Set this module to become a plug-in for the reports }
  [(POINTS)
    Shared Report;
  ]
  Constant TypeFilter = "Loggers"   { Tag Type filter  };
  Constant ReportName = "Quarter Hour Snapshot Report" { Title };
]

Init [
  If 1 GetData;
  [
    { Set up the titles and prepare for the loop }

  ]
]

GetData [
  { The "GET..." states pull tag data for use in the report.    }
  { If using this file as a template for new reports, you might }
  { need more states, replacing the code as required            }
  { to retrieve data from your application's tags.              }

  If 1 WriteData;
  [
    { Retrieve the data for the tag }
  ]
]

WriteData[
  { Every report will need a state like this to write the data. }
  { All that will change from one report to the next is the     }
  { formatting and tag names, as appropriate for the data that  }
  { was collected.                                              }

  If 1 { Wait for the next tag data } Done;
  [
    { Output the data                                           }
  ]
]

Done [
  { Clean up and stop.                                          }
  If 1;
  [
    Slay(Self, 0);
  ]
]
  2. Save the file in your application folder.
  3. Declare the module in the Plugins section of your application's AppRoot.SRC.
  4. Import File Changes. Fix any typos. Do not try to run the report yet, as the code must still be written.
  5. Add variables as follows:

  Titles                  { Array of ODBC database field names            };
  Types                   { Array of ODBC column type names               };
  Data                    { Actual data for the body of the report        };
  Formats                 { Array of format strings which will be used
                            in successive SWrites to write Data           };
  TitleStrm               { Stream in which to build the  title line      };
  Fields                  { Array of what to include in the return array  };

  NTags                   { Number of tags selected for report            };
  i                       { Tag counter                                   };
  TagObj            { Current tag object of the (possible) array of tags  };

  NRows                   { Number of rows of returned data               };
                          { depends on the number of snapshots within
                            the selected time frame                       }
  j                       { Row counter                                   };

  TagData                 { Retrieved historical data                     };
  RetCodes                { Array of return codes (errors) from queries   };

  Constant QueryTPP = 900 { This is a quarter-hour snapshot               };
  Constant Mode     = 4   { Mode 4 == Value at start of TPP               };
                          { The mode value of 4 is what makes this a
                               Snapshot-type report.                      }

  UTCStartTime            { Start time of the report in UTC               };
  UTCEndTime              { End time of the report in UTC                 };
  RowTimestamp            { Array with start and end of each snapshot     };
     { This report assumes that the operator gives the start and end
       times of the report using their local time, and that they want
       results for that same local time zone.                             }

  Constant NUMFMT  = "%13.2f";
  Constant TEXTFMT = "%13s";
  6. Save your work so far and Import File changes to ensure there are no typos.
  7. Edit your Init state as follows:

Init [ If 1 GetData;
  [
       { Initialize the arrays for the tags }
    NTags = ArraySize(Tags, 0) { Need to know how many columns };

    { Set up the titles array and prepare for the loop }
      Titles   = New(NTags + 2) { Add two columns for time and date };
      Formats  = New(NTags + 2);
      Types    = New(NTags + 2);
      Data     = New(NTags + 2);
      TagData  = New(NTags);
      RetCodes = New(NTags);
      Fields   = New(2);
     Fields[0] = "TimeStamp";
     Fields[1] = "Value";

    { Historian data is in UTC. Translate from operator's local time    }
    UTCStartTime = ConvertTimestamp(Start, 0, False, Invalid);
    UTCEndTime = ConvertTimestamp(End, 0, False, Invalid);

    NRows = Ceil((UTCEndTime - UTCStartTime) / QueryTPP);

        { Build the title lines }
        TitleStrm = BuffStream("");
        SWrite(TitleStrm, "%s from %s %s to %s %s\r\n\r\n",
                     ReportName { Title for the report },
                     Date(Start / 86400, "MMM d, yyyy"),
                     Time(Start, "HH:mm:ss"),
                     Date(End / 86400, "MMM d, yyyy"),
                     Time(End , "HH:mm:ss"));
              { Add the Headers to the title }

        Titles[0] = "Date";
        Titles[1] = "Time";
        Types[0] =
        Types[1] = "TEXT";
    Formats[0] =
    Formats[1] = TEXTFMT;

     { Set first 2 columns of the title line }
    SWrite(TitleStrm, Formats[0], Titles[0]);
    SWrite(TitleStrm, Formats[1], Titles[1]);

    i = 0; { Remaining column headers are tag names }
    WhileLoop(i < NTags,
      Titles[i + 2] = PickValid(Scope(\Code, Tags[i])\Name, "Unknown");
      Types [i + 2] = "NUMERIC";
      Formats[i + 2] = NUMFMT;
      SWrite(TitleStrm, TEXTFMT, Titles[i + 2]);
      i++; { ensure that the loop counter increments }
    );
    { Add CR, LF to title line, write the titles and reset the stream }
    SWrite(TitleStrm, "\r\n");
    Reporter\ODBCColumns(Titles, Types);
    Reporter\TitleLine(TitleStrm);
    Seek(TitleStrm, 0, 0);
  ]
]
  8. Import File Changes again.
  9. Run the report, selecting one or two tags and displaying the output to the screen. You should get the titles.
  10. Write the GetData state as follows:

GetData [
  If 1 WriteData;
  [
    { Retrieve the data for the next tag          }
    i = 0;
    WhileLoop(i < NTags;

      TagObj = Scope(VTSDB, Tags[i]);
         { Launch GetTagHistory to get the data for the current tag.
           An array index is specified for RetCodes and TagData for each
           launch, so that we don't conflict with results from other tags.  }
         { Note that each element returned in &TagData[i] will itself
           be a two-dimensional array                                       }
      \HistorianManager\GetTagHistory(&RetCodes[i], &TagData[i] { Return code, result  },
                                    TagObj          { Tag Object           },
                                    "Value"         { Field to return      },
                                    UTCStartTime, 0 { Start, End (Ignored) },
                                    QueryTPP, NRows { TPP, Num Entries     },
                                    Mode            { Mode                 });
      i++;  { ensure that the loop counter increments }
    );
  ]
]
  11. Ensure that your code will compile. There is no point running it again at this stage unless you also use the Source Debugger to examine your arrays.
  12. Write the WriteData state as follows.
WriteData [
  { GetData launched NTags instances of GetTagHistory. Wait until all
    have a valid return code before proceeding.                           }
  If AValid(RetCodes[0], NTags) == NTags Done;
  [
     { Set the row counter }
    j = 0;
     { Loop through retrieved data, creating each report row }
    WhileLoop(j < NRows;
       { Loop through TagData array to get the data }
      i = 0;
       { First two columns of the row will be date and time }
      RowTimestamp = Start+ QueryTPP * j;
      Data[0] = Date(RowTimestamp / 86400, 7); { UTC Date at start of TPP }
      Data[1] = Time(RowTimestamp % 86400, 2); { UTC Time at start of TPP }
      WhileLoop(i < NTags;
         { Fill in data array     }
        Data[i + 2] = Cast(TagData[i][0][j], \#VTypeDouble);
        Formats[i + 2] = NUMFMT;
         { Increment loop counter }
        i++;
      );

       { Pass the report line to the VTS Reporter module }
      Reporter\DataLine(Formats, Data);
       { Increment the data time index        }
      j++;
    );
  ]
]
  13. Import file changes and run your report.
  14. Open the Source Debugger and set a breakpoint on the inner WhileLoop of WriteData.
  15. Examine the value of TagData each time the breakpoint is hit. Match what you see in the Source Debugger to the array indexes used in the code.


Example: Maximum Values Report

This example creates a report that shows the maximum values of a set of tags along with the time of those maximums within the start and end times.

( { Parameters }
  Reporter   { Object value for call-backs     };
  Start      { Starting time (local, not UTC!) };
  End        { Ending time                     };

  Tags       { List of tag names in report     };
)

[ { Variables }
{ Set this module to become a plug-in for the reports }

  [(POINTS)
    Shared Report;
  ]

  Constant TypeFilter = "Loggers" { Tag Type filter };
  Constant ReportName = "Max Value Report" { Title  };
  Data       { Array of data to output                 };
  Formats    { Array of formats to apply to the output };
  Titles     { Array of ODBC database field names      };
  Types      { Array of ODBC column types              };
  TitleStrm  { Title Stream                            };
  StartTime  { Start time in UTC                       };
  EndTime    { End time in UTC                         };
  Result     { Result from GetTagHistory               };
  LocalTime  { Result timestamp converted to local     };
  Error      { Error code from GetTagHistory           };
  Fields     { Array of fields for GetTagHistory       };
  Modes      { Array of modes for GetTagHistory        };
  TagObj     { Current tag object                      };
  TagIdx     { Current index                           };
  I          { Counter                                 };
]

Init [
  If 1 Loop;
  [
    { Set up the titles and prepare for the loop }
    { Create the titles array                    }
    Titles = New(3);
    Titles[0] = "Name";
    Titles[1] = "Max Level";
    Titles[2] = "Time of Max";
    Formats = New(3);
    Formats[0] = "%-30s";
    Formats[1] = "%-15s";
    Formats[2] = "%-30s";
    Types = New(3);
    ArrayOp1(Types[0], 0, 3, "TEXT", 0);
    Data = New(3);

    { Build the title lines }
    TitleStrm = BuffStream("");
    SWrite(TitleStrm, "%s from %s %s to %s %s\r\n\r\n",
           ReportName { Title for the report },
           Date(Start / 86400, "MMM d, yyyy"),
           Time(Start, "HH:mm:ss"),
           Date(End / 86400, "MMM d, yyyy"),
           Time(End , "HH:mm:ss"));

    { Add the headers to the title }
    I = 0;
    WhileLoop(I < ArraySize(Titles),
              SWrite(TitleStrm, Formats[I], Titles[I]);
              I++;
    );

    { Output the titles }
    Reporter\ODBCColumns(Titles, Types);
    Reporter\TitleLine(TitleStrm);

    { Get ready to go }
    TagIdx = 0;
    StartTime = ConvertTimestamp(Start, 0, Invalid, Invalid);
    EndTime = ConvertTimestamp(End, 0, Invalid, Invalid);
  ]
]

Loop [
    { More tags to process }
  If TagIdx < ArraySize(Tags) GetTagData;
    { All done }
  If TagIdx >= ArraySize(Tags) Done;
]

GetTagData [
  If 1 ProcessLine;
  [
    { Retrieve the data for the tag }
    { Set the current tag object    }
    TagObj = Scope(VTSDB, Tags[TagIdx], TRUE);

    { Declare the arrays and initialize the error }
    { and result values                           }
    Fields = New(2);
    Fields[0] = "Value";
    Fields[1] = "Value";

    { Declare what retrieval modes will be used }
    Modes = New(2);
    Modes[0] = 2 { Max         };
    Modes[1] = 6 { Time of Max };

    { Reset the error and results for the next query }
    Error = Result = Invalid;

    { Get the data for the Well }
    \HistorianManager\GetTagHistory(&Error, &Result { Return code, result   },
                                    TagObj          { Tag Object            },
                                    Fields          { Fields                },
                                    StartTime, 0    { Start, End (Ignored)  },
                                    End - Start, 1  { TPP, No intervals     },
                                    Modes           { Modes                 });
  ]
]

ProcessLine [
  If Valid(Error) Loop;
  [
    { Save the tag data }
    Data[0] = PickValid(TagObj\Description, TagObj\Name);
    Data[1] = Format(6, 2, Result[0][0]);

    { Convert the UTC timestamp to local time }
    LocalTime = ConvertTimestamp(Result[1][0], Invalid, Invalid, 0);

    { Format for human consumption }
    Data[2] = concat(Date(LocalTime / 86400, 4), " - ",
                     Time(LocalTime % 86400, 2));

    { Output the results for this tag }
    Reporter\Dataline(Formats, Data);

    { Move to the next tag }
    TagIdx++;
  ]
]

Done [
  If 1;
  [
    Slay();
  ]
]


Reporter Module API

The examples shown in this chapter make use of VTScada's Reporter module. You have access to the following subroutines within that module:

Subroutines

ODBCColumns

Description: | Subroutine module called to set column names and types in a report.
Returns: | 0
Usage: | Script Only.
Function Groups: | Reporter module
Related to: |
Format: | \Reporter\ODBCColumns(ColTitles, ColTypes, ColFormats, XLColFormats)
Parameters: |
ColTitles
Required. An array of titles to display above each column in the report.
ColTypes
Required. An array specifying the type of data to be used in each column.
ColFormats

Optional. An array specifying the display format for data in cells within each column. These use standard C++ formatting, as shown in text functions such as SWrite

XLColFormats
Optional. Used only for Excel display via COM objects.
Comments: ODBCColumns is implemented within the module for each output format, varying slightly according to the format.
Example:
Titles[0] = "Date";
Titles[1] = "Time";
Titles[2] = "Raw Timestamp";
Types [0] =
Types [1] = "TEXT";
Types [2] = "NUMERIC";
Format[0] =
Format[1] = "%-14s";
Format[2] = "%14.3f";
ExcelColFmts[1] = "hh:mm:ss.000";
ExcelColFmts[2] = "0.000";

TitleLine

Description: | Subroutine module to render a report title
Returns: | 0
Usage: | Script Only.
Function Groups: | Reporter module
Related to: |
Format: | \Reporter\TitleLine(Title)
Parameters: |
Title
Required. A string containing the title for the report.
Comments: This subroutine is implemented within each VTScada report format. No options are available to modify the format of the title line.

DataLine

Description: | Subroutine module to write a row of data to a report.
Returns: | 0
Usage: | Script Only.
Function Groups: | Reporter module
Related to: |
Format: | \Reporter\DataLine(Format, Data)
Parameters: |
Format
Required. An array of formatting strings. These use standard C++ formatting, as shown in text functions such as SWrite
Data
Required. An array containing the data to be written in one row of the report.
Comments: This subroutine is implemented within each VTScada report format.


Script a Custom View of a Roster

All Roster Tags contain two publicly-accessible arrays describing the contact list. You can use either in an expression to build a customized view of the tag's contact list. This list is not editable. For editing, you must use the properties dialog for each of your Roster tags.

The arrays are named AllContactsand EnabledContacts.

These arrays contain entries for the contacts in your roster (either all or enabled) in the order in which they will be contacted. The same person may appear more than once in the array if the roster order includes repetitions.

For each contact in the array, the following information is available as a structure.

  Contact Struct [
    Name                      { Name of contact                               };
    Number                    { Phone number/email address                    };
    Method                    { 0 Voice
                                1 Pager
                                2 Email
                                3 SMS Text Message
                                4 Compact email                               };
    Enabled                   { TRUE if contact is enabled; FALSE otherwise   };
    Delay                     { Seconds to wait after notifying this contact  };
  ];

Example:

To display the name and number of the first contact in the EnabledContacts array of a Roster tag named MyRoster, use:

Concat([<MyRoster>].EnabledContacts[0].Name, ": ", [<MyRoster>].EnabledContacts[0].Number)

(This example assumes that you are working in the Idea Studio, creating a page or widget, or else creating an expression in an I/O and Calculations tag.)

For further information about working with arrays, including finding the size of the array and stepping through it, refer to Array Functions


Hook for "Go To Page" calls

You can intercept the call to "Go To Page" when issued from a list of alarms or tags. Do so if you have a custom page to display or want to take some action with the tag or tags. See also: Hook for a List of Pages

Procedure:

Create a module within your application named GoToPageHook

When declaring this module in AppRoot.SRC, do not add it to any class. The declaration should immediately follow the list of constant declarations:

  GoToPageHook Module "GoToPageHook.SRC";

The module must take two parameters: TagNames, Popup.

  • TagNames is an array containing the name or names the tag(s) to which you are navigating.
    (Users may select more than one tag before issuing a Go To Page command.)
  • Popup is a Boolean.
    This will be True if the user chose the option to open the page as a pop-up and False otherwise.

The module must have a return value. Return TRUE if the standard "go to page" action should be taken following the code within your hook module. Return FALSE to suppress the standard action, such as when the module is handing page navigation on its own.

Examples:

1. A hook to redirect to a specific page:

(
  TagNames  { Array of one or more selected tag names };
  Popup     { Windowed or not                         };
)
Main [
  If 1;
  [
    { Redirect to a specific page }
    \DisplayManager\ShowPage("CustomPage", Popup);
    Return(FALSE);
  ]
]

2. A hook to prevent Go To Page navigation for a forbidden tag. (This simplified example assumes that the user selected only a single tag before calling Go To Page.

If 1;
[
  IfElse(True(TagNames[0] == "ForbiddenTag"),
     { Don't let user see the forbidden tag }
         Return(FALSE),
     { Else }
         Return(TRUE));
]


Hook for "Go to Page" on Multi-Monitor Setup

GoToPageShowPageHook is a custom hook created to display pages on a specified monitor when the Go To Page operation is performed. It calls its own ShowPage2 by specifying the index number of the monitor to display pages on when Go To Page operation is performed.

Procedure

Create a module within your application and name it as GoToPageShowPageHook.

When declaring this module in AppRoot.SRC, do not add it to any class. The declaration should immediately follow the list of constant declarations:

GoToPageShowPageHook Module "GoToPageShowPageHook.SRC";

The module takes below 4 parameters: PageName, Popup, PageParms, DisplayRoot.

  • PageName - Required. Name of page to be displayed.

  • Popup - Optional Boolean. If TRUE, it requests the page be opened as a pop-up if allowed. Defaults to FALSE.

  • PageParms - Optional. Array of parameters for the Page.

  • DisplayRoot - Optional. Represents the display device instance.

The module must have a return value. Return TRUE if the standard ShowPage2 needs to be called without specifying any DisplayIndex value(means it displays the page on the current display instance or monitor which performs the Go To Page operation). Return FALSE to suppress the standard ShowPage2 call and to make your own ShowPage2 call by specifying DisplayIndex value to display page on specific monitor in a multi-monitor setup.

Examples

  1. A hook to always display page on 3rd monitor when Go To Page operation is performed from any monitor in a multi-monitor setup:

(

  PageName                 { Name of page to be displayed      };

  Popup                        { True, to open page as a popup      };

  PageParms                 { Array of parameters for the Page };

  DisplayRoot               { Display device instance               };

)

Main [

  If 1;

  [

     { Displaying on 3rd monitor by specifying ShowPage2's DisplayIndex paramater value as 3}

    \DisplayManager.ShowPage2(PageName, Popup, PageParms, DisplayRoot, FALSE, 3) ;

    Return(FALSE);

  ]

]

  2. A hook to display page on 3rd monitor only if Go To Page operation is performed from 1st monitor. In all the other cases, it will just return TRUE so that the standard ShowPage2 call will be executed thereby displaying page on the respective monitor on which Go To Page operation is performed in a multi monitor setup.

(

  PageName                 { Name of page to be displayed      };

  Popup                        { True, to open page as a popup      };

  PageParms                 { Array of parameters for the Page };

  DisplayRoot               { Display device instance               };

)

[

  Index                       { Index value of current display instance };

]

Main [

  If 1;

  [

     { Gets the index of the current monitor(root-level display instance) }

    Index = \DisplayManager.GetDisplayIndex();

    IfElse(Index == 1, Execute(

       { Choosing to display page on 3rd monitor only if GoToPage is being called from 1st monitor.

         In all other cases, the page will be displayed on the respective monitor itself }

      \DisplayManager.ShowPage2(PageName, Popup, PageParms, DisplayRoot, FALSE, 3) ;

      Return(FALSE);

    );

    { Else }

      Return(TRUE);

    );

  ]

]


Hook for a List of Pages

This is a user-created module named PageListForGoToPageHook. The purpose is similar to that of GoToPageHook except that this hook will accept a list of pages for a tag. See also: Hook for "Go To Page" calls

If GoToPageHook and PageListForGoToPageHook both exist, GoToPageHook takes precedence and PageListForGoToPageHook does nothing.

Otherwise, this hook will take a tag names and returns a custom list of pages and a Boolean value. The Boolean value tells whether the returned custom list or the default list should be displayed. The custom list can return 100 pages at maximum, and can only return pages. If the returned list contains more than 100 pages, nothing will be displayed. If an item that is not a page is returned, the particular item will be ignored.

Procedure:

Create a module within your application named PageListForGoToPageHook

When declaring this module in AppRoot.SRC, do not add it to any class.

  PageListForGoToPageHook Module "PageListForGoToPageHook.SRC";

The module must take two parameters: TagNames, pPageList .

  • TagNames is an array containing the name or names the tag(s) to which you are navigating.
    (Users may select more than one tag before issuing a Go To Page command.)
  • pPageList is an output parameter and must be a structure specifying the pages to open.

The module must have a return value. Return FALSE if the standard "go to page" action should be taken following the code within your hook module. Return TRUE to suppress the standard action, such as when the module is handing page navigation on its own.

The module works by populating a structure, which is then used to present your selection of pages to the user.

The definition of this structure follows:

  {Public} GetPagesForTagsHookPageInfo STRUCT [
    Name                      { Page name of the custom page                  };
    Parms                     { Parameters needed by the custom page          };
    Label                     { Label of the custom page                      };
  ];

Parms should be a local array holding the parameters that the selected page will need.

Label is a text value. It can be a phrase ID.

You might create both Parms and Label using information from the selected tag. It is common but not necessary to use information from the selected tag to populate both variables.

The maximum number of pages that can be presented is 100. Invalid entries for pages will be ignored.

Example:

(
  TagNames;
  PagesForTagsHook;
)
[
  Name                      { Page name of the custom page                  };
  Parms                     { Parameters needed by the custom page          };
  Label                     { Label of the custom page                      };
]
Main [
  If 1;
  [
    IfElse(TagNames[0] == "MyTag", Execute(
      Parms     = New(1);
      Parms[0]  = MyTag;

      *PagesForTagsHook    = New(3);
      (*PagesForTagsHook)[0] = \PageTagRefMgr.GetPagesForTagsHookPageInfo("MyPumpPage", Invalid, "Custom pump page");
      (*PagesForTagsHook)[1] = \PageTagRefMgr.GetPagesForTagsHookPageInfo("GenericPumpPage", Parms, "Standard Page");
      Return(TRUE);
    );
    { Else }
      Return(FALSE);
    );

  ]
]


Get Tags Displayed Using a Custom Widget

This topic is relevant only if you have created a custom-coded widget that displays tags that are not drawn as linked tag widgets, or not always drawn.

In order for VTScada to provide a Go To Page operation from the alarm page or tag browser, it must have a list of the tags on each page. This is also true if you are using the MIC thin client and need your tag to be included when toggling to the list view for a page.

VTScada will create a list of tags on a page by inspecting all linked tag widgets on that page, recursively. Any linked tag on that page, or within a widget also drawn on the page, will be included in the list. However, if a widget includes information related to a tag, but that tag is not drawn because it is outside a scroll area, or not drawn as a linked tag property, it will not be included in the list unless explicitly added using the GetDisplayedTags module.

You must write the code for this module yourself according to the format described in this topic.

  • GetDisplayedTags must be added to your widget as a submodule and declared using that name.
  • It takes no parameters.
  • It returns an array of tags.

Example:

A widget that draws all the water supply tags in a system with next / previous buttons to scroll through multiple pages as shown following:

If the water supply tanks are drawn as Tag Widgets, the first 6 will be included, but the next 12 (on pages 2 and 3) won't be because they won't be caught when we get the recursive list of all linked tag widgets. A GetDisplayedTags module added to the widget ensures all 18 water supply tags are included in the list of tags drawn by the widget.

<
{============================= GetDisplayedTags ==============================}
{ Used to specify an explicit list of tags displayed by this widget. This is  }
{ necessary when there isn't enough space to draw all the tags at once. Tags  }
{ drawn on other pages also need to be picked up for Go To Page operations.   }
{=============================================================================}
GetDisplayedTags
[
  I                           { Counter                                       };
  Result                      { Return value                                  };
]

GetDisplayedTags [
  If 1;
  [
     { Collect the results in a dictionary to account for empty parameters or duplicates }
    Result = Dictionary();
    I = 0;

    WhileLoop(I < ArraySize(Tags),
       { Add this tag to the list }
      Result[Tags[I].Name] = 1;
      I++;
    );
     { Return as an array of full tag names }
    Return(ListKeys(Result));
  ]
]
{ End of GetDisplayedTags }
>

Example 2

A parameterized widget that draws the Name, Area, Description and Value of the tags passed into up to 8 parameters named Tag1 through Tag8. The fields are drawn as GUIText elements, meaning there are no linked tag widgets in use.

The four tags displayed are not drawn using linked tag widgets therefore they will not be included in the recursive linked tag widget search. A GetDisplayedTags module is needed to ensure they are included in the list of tags for any page that draws this widget. This use case is commonly needed when tags are passed to widgets dynamically using parameters.

<
{============================= GetDisplayedTags ==============================}
{ Used to specify an explicit list of tags displayed by this widget. This is  }
{ necessary because the 8 selected tags aren't drawn as linked tag widgets.   }
{=============================================================================}
GetDisplayedTags
[

  Result                      { Return value                                  };
]

GetDisplayedTags [
  If 1;
  [
     { Collect the results in a dictionary to account for empty parameters or duplicates }
    Result = New(8);

    Result[0] = Tag1.Name;
    Result[1] = Tag2.Name;
    Result[2] = Tag3.Name;
    Result[3] = Tag4.Name;
    Result[4] = Tag5.Name;
    Result[5] = Tag6.Name;
    Result[6] = Tag7.Name;
    Result[7] = Tag8.Name;
    Return(\System.RemoveInvalids(Result));
  ]
]
{ End of GetDisplayedTags }
>


Custom Ownership Mode for Control Tokens

Ownership of Control Tokens is defined by the application property ControlTokenOwnerMode as one of:

  • Session ID
  • Account ID
  • Machine ID
  • or, Custom

(See also: ControlTokenOwnerMode)

When in Custom owner mode, the ownership of a token is determined by custom logic defined by the application as an alternative to SessionID, AccountID and MachineID. Whenever a check is made to see who owns a token, a ControlTokenIsOwnerHook module defined by the application is called. The application's special ownership logic must be defined within this module. Furthermore, the tokens themselves can be made to store a custom identifier that can assist in determining who it is owned by. The custom identifier can be added by a ControlTokenCustomFieldHook module defined by the application.

The ControlTokenIsOwnerHook module must be both script and steady-state compatible. When VTScada tests to see if a token belongs to the current user, this hook will be invoked if it exists. It must return TRUE if the token owner (as defined by the hook) matches the token record and FALSE otherwise.

The ControlTokenCustomFieldHook module must be script compatible. It must return a string that helps identify the owner of a token. When VTScada generates a token record, if this module exists it will be called to generate the custom identifier which then gets stored in the token record.

For example, suppose you have two control rooms (Main and Backup) with several workstations in each (thick clients). The owner grouping goes by control room, so when a workstation from the Main control room requests a token, all the workstations at Main should get access. ControlTokenCustomFieldHook should return "Main" or "Backup" depending on where the workstation is. Once this token has been granted and any user from any workstation attempts to control a tag, the ControlTokenIsOwnerHook checks to see who owns the token based on whether both the token and the user are in Main or Backup.

Writing a custom hook module may require a high degree of proficiency with VTScada scripting.

VTScada will call ControlTokenIsOwnerHook with the following supplied parameters. Your module may make use any of these as appropriate for your definition of ownership.

\ControlTokenIsOwnerHook(Record       { As returned by AlarmManager.GetRecord() },
                         SessID       { The current security session            },
                         MachineID    { Identifies the current machine          },
                         MachID       { The current machine ID                  },
                         Custom       { A custom value that can be any of:
                                          - Invalid (default set by ControlTokenCustomFieldHook)
                                          - a parameter that you pass to the Control Token Manager,
                                          - the value you set for Custom in any of RequestToken, ReleaseToken, DenyTokenRequest and GrantTokenRequest,
                                          - the first valid value of SessionID, AccountID or MachineID });
\ControlTokenIsOwnerHook(Record       { an AlarmRecord structure that contains the token information },
                         SessionID    { the user's current session ID },
                         AccountID    { the user's account ID as returned by \SecurityManager.GetAccountID() },
                         MachineID    { the user's workstation ID as returned by WkStaInfo(3) },
                         Custom       { A custom value that can be any of:
                                          - Invalid (default set by ControlTokenCustomFieldHook)
                                          - the value you set for Custom in any of RequestToken, ReleaseToken, DenyTokenRequest and GrantTokenRequest });

The Custom parameter can be used as another identifier of the user but can also be used to compare against the Custom field of a Record or Token. The default value of Custom is set by , "ControlTokenCustomFieldHook".

 ControlTokenCustomFieldHook(SessionID, AccountID, MachineID)

The purpose of ControlTokenCustomFieldHook is to provide more flexibility when creating custom ownership rules. The return value of ControlTokenCustomFieldHook is used as the default value of the Custom parameter of ControlTokenIsOwnerHook, RequestToken, ReleaseToken, DenyTokenRequest and GrantTokenRequest.


Custom Diagnostic Files

In some VTScada applications, you may decided that there is a requirement for diagnostic files (as an example, an SQL data logger diagnostic file in which all queries to the SQL server are written for later analysis).

The following list contains guidelines and tips on diagnostic files and their storage.

  • Do not add diagnostic files to your application's file manifest. There is seldom, if ever, a good reason to put the diagnostic file under the application's version control system. Further, diagnostic files can become large, making ChangeSets unwieldy.
  • Consider creating a diagnostics folder somewhere outside the application.
  • Create the diagnostics file with a .LOG or .DAT extension as VTScada will not automatically add these files to the application during synchronization.

Related information that you may need:

File I/O


Working with Speech

The following VTScada modules allow you to provide speech features in your applications:

  • Configure: Enables you to define how a speech stream will sound, and where it will be heard.
  • GetDevices: Runs in the VoiceTalk thread and returns a list of devices available on a SAPI text-to-speech stream.
  • GetVoices: Runs in the VoiceTalk thread and returns a list of voices available on a SAPI text-to-speech stream.
  • Reset: Stops a speech stream and cancels any buffered speech.
  • ShowLexicon: Displays a SAPI text-to-speech engine lexicon dialog to permit modification of pronunciation.
  • Speak: Executes on the speech thread to speak supplied text through a specified SAPI text-to-speech stream.
  • VoiceTalk: Opens and returns a handle to a SAPI text-to-speech stream.

Note that the following modules have been obsolete for some time, but are still provided for backward compatibility:

SpeechStream, SpeechEnum, SpeechLexiconDlg, SpeechReset, SpeechSpeak, and SpeechSelect.

Related Functions:

Configure

GetDevices

GetVoices

Reset

ShowLexicon

Speak

VoiceTalk


Interrupt the Shutdown Process

There are two methods to interrupt the shutdown process. Note that neither can be used to delay a shutdown caused by time-limited trial license by more than ten minutes.

Method 1:

Any module declared in AppRoot.SRC as a member of the class (SHUTDOWN_HOOK) will run automatically during the shutdown process. Such a module may be used to write extra information to disk or perform any other task before the shutdown process completes.

Method 2:

If you add a module named "VAMStopAppCheck" to your application, you can interrupt the shutdown process to prompt for confirmation or to give the operator time to perform some task before proceeding with the shutdown. For example, when the TraceViewer is shut down, it will check whether logging is still enabled and if so, ask the operator whether to continue logging.

This does not apply to shutdowns initiated by a low UPS. Those are considered to be both time-sensitive and critical and therefore will not be delayed by a VAMStopAppCheck module.

If adding this module to a script application, define it in the AppRoot.src file of the application. If adding it to a VTScada application, the module must be in it's own file, which is declared in the AppRoot.SRC file. (Note - it should be declared on its own, not within any of the module classes.)

It is sufficient that the module be declared in the AppRoot.SRC file in order for the VAM to call it upon shut-down. This will happen when the user tries to stop the application by using the stop button in the VAM or by stopping the VAM itself. The VAM will not automatically call VAMStopAppCheck when the user closes the application by clicking the X in the corner of the title bar. Script applications can trap for this method of closing the application, but VTScada applications are not.

VAMStopAppCheck should be declared with two parameters:

  • OKStopPtr - a pointer to be set. When *OKStopPtr is set to 1, the application may stop.
  • VTSExit - a Boolean. If TRUE, VTScada is being shutdown. If FALSE, only the application is being stopped.

The general structure of the module will display a dialog to the operator, and wait for a response before continuing.

Example:

<
{============================== VAMStopAppCheck ========================}
{ Module called by VAM when Stop button is pressed. Setting OKStopPtr   }
{ to 0 tells the VAM not to stop the app. Setting it to 1 allows it to  }
{ stop.                                                            }
{=======================================================================}
VAMStopAppCheck
(
  OKStopPtr             { Pointer to set: 1 if ok to stop, 0 if not ok  };
  VTSExit               { Flag - TRUE if VTScada wants to exit; false if app
                          is just being stopped. Default is false. };
)
[
  Close                 { TRUE if user chooses to stop the app          };
  CloseDialog Module    { Presents dialog to user getting confirmation
                          for app stop.                            };
]

Check [
  If 1 Wait;
  [
     { User has attempted to stop the application. Show the close dialog. }
    CloseDialog(&Close);
  ]
]

Wait [
  If Valid(Close);
  [
    IfElse(Close,
      *OkStopPtr = 1;
    { Else }
      *OkStopPtr = 0;
    );
    Slay();   {  In either case, this module is finished. }
  ]
]

>

<
{=============================== CloseDialog ==========================}
{ Launched module presents a dialog to the user when the application   }
{ is stopped                                                           }
{======================================================================}
CloseDialog
(
  AskExitResultPtr            { Pointer to set the result              };
)
[
  AskExitResult               { The user's choice                      };
]

CloseDialog [
  AskExitResult = System.4BtnDialog(\System\Question_Icon,
                                    "Yes", "No", Invalid, Invalid,
                                    "Continue shutdown?", Invalid, Invalid,
                                    1, 0, 1, "Continue with shutdown?",
                                    Invalid, Invalid, Invalid, 2,
                                    Invalid, Invalid);
  If Valid(AskExitResult);
  [
     *AskExitResultPtr = AskExitResult == 1 ? 1 : 0;
     Slay();
  ]
]
>


Obtaining User Input

VTScada provides a range of tools to help you watch for user input, whether to request information or to respond to control events. Choose the appropriate tool for the task. For much application development work, it is far easier to use the widgets in the Idea Studio than to write a user interface from scratch.

As well as considering how to gather user input, think about how that information will be used and if it needs to be saved, then how. Screens for user input, whether pages or custom windows, tend to come and go, meaning that the state and probably the module containing the page or window will end. If the information gathered from the user should persist, the values should be written to I/O tags, stored on disk as persistent variables, written to a file, or (rarely) the variables might be declared in a service that continues to run.

Note that a set of tools exists explicitly for building dialog boxes for tag configuration: These are the so-called, "P-tools", where "P" refers to "parameter editing".

If creating a configuration panel for a tag, use only the P-tools to gather user-input.
For all other purposes, do not use the P-tools.

Tab order between user input controls follows their z-order (that is, the order of the statements within the state), rather than their Focus ID value.

Mouse Input - Buttons, Target, etc.

Several VTScada functions are designed to accept input from the user via the screen pointer (mouse). Some, such as Pick, WinButtonandZButtonare designed to watch for click actions. Others, such as Target, XLocand YLocsimply watch the location of the pointer and can be used to trigger an action when the operator moves the pointer to a defined area.

All the GUI-graphics commands (GUIButton, GUIBitmap, etc.) are designed to watch for mouse input, and will return a numeric value indicating which combination of mouse buttons were used when an operator clicks on the graphic.

To use these functions, they must be placed in a module that is contained in a window, whether that is an application page, or a module of your own creation. They can be used as the trigger condition of an action to allow scripts to be executed when an operator clicks within a specified area.

Example:

If ZButton(10, 70, 110, 40,
           "OK" { Text label on button },
           1 { Focus ID }) ;
[

   ...

]

This statement will cause the script to execute in response to a left-click on a button.

Selection Input

Selection tools are those that provide a set of options to a user. In the Idea Studio, widgets include the Droplist. Options that you can create using code include RadioButtons, DropList , WinComboCtrl and CheckBox , all of which are examples of selection input. Also in this group are tools such as the VTScada ColorSelect , Listbox and SpinBox.

Keyboard Input

Keyboard input may be used to allow an operator to respond Y (Yes) or N (No) in response to a prompt. It is also used whenever there is a need to prompt for a numeric or text value.

The most commonly used keyboard functions are MatchKeys, andWinEditCtrl. MatchKeys is typically used to trigger an action when a specified key or sequence of keys is pressed. It does not display the keystrokes entered.

The ZEditField function is used to accept text entered by the operator. Before typing, the operator must activate the object by clicking on the area of the window where the graphic is displayed, or by pressing the TAB key to set the focus to that input object.


Custom Global Filters for Tags and Areas

Global tag and area filtering is applied on a per-user basis and therefore is also referred to as User Tag Filtering (UTF) or User Area Filtering (UAF).

Global filters are applied on a user-by-user basis to all tags and alarms in the system that a user can see. Whether a user is able to apply a user filter is based on a Global Filtering security privilege and the UserFilterMode configuration setting

The global filters are stored in a UserFilters network value in the session with an instance name based on the realm and account ID. These are retained for the user across a network. The UserFilters network value is a structure with elements Areas and Tags that contains dictionaries of patterns used for global area and tag filtering. Helper functions are available, which can aid in setting the user filters programmatically and which constitute the API for user filtering.

In the following examples, "Session" is an object reference returned by GetUserSession().

Session.IsUserFilterEnabled():

This is a public module to get the current status of user filtering, which returns a structure of Booleans. Its elements are Areas, Tags and Any.

The Areas element is true if there is at least one Global Area Filter active. The Tags element is true if there is at least one Global Tag Filter active. The Any element is true if either filter is active. For example:

\GetUserSession().IsUserFilterEnabled().Any

... will return TRUE (1) if either of an area filter or a tag filter is active.

Session.SetUserAreaFilter(AreaFilterDict):

This module takes in a dictionary of area patterns and assigns it to the UserFilters.Areas NetworkValue. This is the API by which global area filters can be set. It takes a single parameter, which is a dictionary, keyed by Area patterns (e.g. North, South*st, W?st), with values TRUE. Any tag or alarm with an area that passes any of the filters in the set (ORed) will be shown, otherwise they will be hidden. If no areas match the filter, nothing will be shown. To clear the filter (show alarms and tags irrespective of their areas), the call is SetUserAreaFilter(Invalid), which also sets the UserFilter.Areas Network value to Invalid.

Setting any of the filters to "*" is equivalent to showing all areas, and the UserFilters.Areas network value will be set to Invalid.

Session.SetUserTagFilter(TagFilterDict):

This module takes in a dictionary of name patterns and assigns it to the UserFilters.Tags NetworkValue. This is the API by which global tag filters can be set. It takes a single parameter, which is a dictionary, keyed by tag patterns (e.g. Tag1, Tag1\Tag2*, *Pump*, *\Chlorine), with values TRUE if all of the tag's children are to be included, and FALSE if not (this is only necessary for the Global Filter Dialog GUI tool if it is to be used). Any tag or alarm with a name which passes any of the filters in the set (ORed) will be shown otherwise they will be hidden. If no names match the filter, nothing will be shown. To clear the filter (show alarms and tags irrespective of their names), the call is SetUserTagFilter(Invalid), which also sets the UserFilter.Tags Network value to Invalid. Note: Setting any of the filters to "*" is equivalent to showing all tag names, and the UserFilters.Tag network value will be set to Invalid.

Best Practices for User Filters

Special considerations are made for "\" characters. To ensure that parent tags as well as their children are captured by the tag filter, it is required that each filter be followed by a \, and that all \ characters be replaced by \\ for the pattern match. This is handled within the API where, (for example) if dictionary Key "Tag1" is passed into the API, it will be stored as "Tag1\\" in the Network Value. From an efficiency standpoint, the best filters formats (Dictionary keys) are:

  • An exact tag name with no wildcards.
    For example, A\B\C\D for just one tag.
  • An exact tag name followed by "\*".
    For example, A\B\C\D\* for A\B\C\D and all of its children.

In the case where you want to see the parents of A\B\C\D, but not all of their children, the pattern set would be: A\ , A\B\ , A\B\C\ , A\B\C\D\*.

Other patterns are possible and should work, but may be much slower.

Master/Subordinate filters

This is a requirement for filtering alarms. Due to the nature of subordinate applications, when using Realm/User tag filtering it is a requirement that the filters contain the explicit name of the subordinate tag in the master followed by a "backslash character, "\". Do not use wild cards in the subordinate application name, except at the beginning. Following are some examples of filters to be used in the master application, where SubApp is the subordinate tag:

Good examples. The following will work

SubApp\MyAlarms\*

MasterFolder\SubApp\My?Alarms\*MoreTags?\*Wh?*ateverWildcards

*MyAlarms\*

Bad examples. Do not create filters like these.

Master*Folder?\SubApp\MyAlarms\*

MyAlarms\*

*\MyAlarms\*

\*MyAlarms*


Connect JSON/XML Drivers in Parallel

JSON/XML drivers connect sequentially by default. If multiple drivers are connecting to the same service (ie the same domain) it is a best practice to configure your application to fetch data in parallel by specifying the number of drivers connecting.

If multiple JSON/XML drivers are connecting to the same domain with default settings only one may send a request and wait to recieve a response at a time, potentially causing a queue and unnecessary wait times.

You will need to create a domain-specific property to insert into your application configuration. The property name will look something like this:

JSONXML_NConcurrent_MyServerAddress.com = 20

Where JSONXML_NConcurrent_ is concatenated with your domain address. In this example, 20 specifies the number of parallel connections.

An example using IPV6 addressing:

JSONXML_NConncurrent_fe80::d5b0:bf3f:f4e8:ce11 = 13

Where JSONXML_NConncurrent_ is concatenated with your IPV6 address. In this example, 13 specifies the number of parallel connections.

Add JSONXML_NConcurrent_ to your Application Configuration

  1. Navigate to your application configuration and go to advanced mode.

  2. Click "Insert" and a dialog will appear.

  3. Fill in the property values as follows:

Property Name (Required)

Your domain-specific property as described in this topic.

Section

You do not have to make changes to this field.

Value (Required)

This is the number of parallel connections required.

Workstation

You do not need to specify a workstation, this setting is application-wide.

Comment (Optional)

This will appear in the comment section of the properties table. It is a best practice to leave a concise explanation here for future investigations.

  4. Click OK in the dialog and then Apply in your application configuration.


Remote Testing API

Remote testing on VTScada is disabled by default. To allow remote testing, see AllowRemoteTest.

Allowing Remote Testing is less secure. If you allow remote testing and you need to access your machine on an insecure network (such as at an airport, or in a hotel), it is strongly recommended that you set this property to 0 (FALSE).

Remote Test Modules

StartRemoteTestApp

Called in steady-state. Starts the remote test application on a remote machine.

The first time this test is called, this module will stop and delete the remote app on the specified machine, send it the necessary files to perform GetFromServer, and then start the remote app.

Returns 1 when the app has started or an error message if it fails.

StartRemoteTestApp:

(
TargetMachine     { Machine name of where to stop the app };
GUID              { App GUID. Defaults to calling application };
SkipStart         { Just load layer on remote machine - don't start app };
SkipStore         { Default FALSE. };
                  { If TRUE skips the store of the VIC Settings };
)

RemoteTest

Called in steady-state. This module is called on a machine running a test so that it will trigger the running of a test module on a remote machine.

If the test application on the remote machine is not running, it will be re-added and then started automatically.

Returns 1 if the app has started or an error message if it fails.

Test modules have one parameter. If you need more, then use a structure or a dictionary.

RemoteTest:

(
TargetMachine       { Machine name of where to run the test };
Test                { Name of the test module to run };
TestParameter       { Parameter to pass into the test };
)

StopRemoteTestApp

Called in steady-state. Stops a remote test application on a remote machine.

Returns 1 if the app has stopped or an error message if it fails.

StopRemoteTestApp:

(
TargetMachine     { Machine name of where to stop the app };
GUID              { App GUID. Defaults to calling application };
RemoveApp         { Default FALSE. If TRUE, the remote application is removed from the remote WAM. };
RemoveDir         { Default FALSE. If TRUE, the directory for the remote app is deleted. };
SkipReset         { Default FALSE. If TRUE skips the restore of the VIC Settings };
)


Write a JSON/XML Processor

To write data using a JSON/XML driver tag, you must create a processor that defines the data to be written.

Any number of processor modules can be added to an application. The following conditions must be met for each:

  • A processor must be declared as part of the PLUGINS class in your application's AppRoot.SRC file.
  • It must include a constant IsJSONXMLProcessor flag that identifies itself as a processor.
 CONSTANT IsJSONXMLProcessor = TRUE;
  • It must be a subroutine that returns the converted data structure made up of dictionaries, structures, arrays, or a combination of these.
  • It should have a DrawLabel.

The parameters of a processor are:

Data

The data structure after decoding it from the original JSON or XML payload.

UniqueID

(optional) The UniqueID of the calling JSON/XML Driver.

TimeValuePairs

If timestamped values exist in the data, the converted data structure must put those time and value pairs into a structure made up of Value and Timestamp elements.
The input tag must use this structure's address. For example, an address of "Site1.Temperature" would give a tag access to the value in Site1.Temperature.Value and its timestamp in Site1.Temperature.Timestamp.
Sample time/value structure that could be used by the processor to return time/value pairs of data:

TimeValuePair Structure [
  Value;
  Timestamp;
]

After declaring your custom processor module in your AppRoot.SRC file and importing file changes, use the name that you assigned to the module in the Processor parameter of your JSONXML tag.

Example:

{=========================== CustomJSONProcessor =============================}
{ Custom JSON data processor for the JSONXMLDriver                            }
{=============================================================================}
(
  Data;
  UniqueID;
)
[
  CONSTANT IsJSONXMLProcessor = TRUE;
  DrawLabel = "JSONLabel";
  NewData;
  TimeValuePair Struct [
    Timestamp;
    Value;
  ];
]

Main [
  If 1;
  [
    NewData = Dictionary();
    NewData["J1"] = TimeValuePair(Data.DataValues.T1, Data.DataValues.V1);
    NewData["J2"] = TimeValuePair(Data.DataValues.T2, Data.DataValues.V2);
    NewData["J3"] = TimeValuePair(Data.DataValues.T3, Data.DataValues.V3);
    NewData["History"] = TimeValuePair(New(3), New(3));
    NewData["History"].Timestamp[0] = Data.DataValues.T1;
    NewData["History"].Timestamp[1] = Data.DataValues.T2;
    NewData["History"].Timestamp[2] = Data.DataValues.T3;
    NewData["History"].Value[0]     = Data.DataValues.V1;
    NewData["History"].Value[1]     = Data.DataValues.V2;
    NewData["History"].Value[2]     = Data.DataValues.V3;
    NewData["UniqueID"]             = UniqueID;
    NewData["Timestamp"]            = "Not a timestamp";
    Return(NewData);
  ]
]


Write a Custom MQTT Decoder

Three MQTT parsers are included with VTScada: JSONDec, XMLDec, and MQTTPassThruParser.

You specify which to use by naming it in the I/O address for the topic to be read. See: MQTT Client Addressing

If you require custom parsing, you can write your own decoder. As with any VTScada module, the code must be declared in the AppRoot.SRC file and file changes imported.

As a template for you to use, the code for MQTTPassThruParser.SRC is provided here. Note that it runs as a subroutine. (

{========================== MQTTPassThruParser =============================}
{ Returns the payload as is without any parsing. Useful for examining the   }
{ full payload when used with a StringIO tag without any indexing.          }
{===========================================================================}
(
  Payload;  { required parameter }
)
[
]
Only [
  If Watch(1);
  [
    Return(Cast(Payload, \#VTypeText));
  ]
]
{ End of MQTTPassThruParser }

Payload is the value read from the topic address. Presumably, you will know the structure of the data you intend to read before attempting to write a custom parser. Within the body of the If script block, you are free to manipulate it as needed before returning it. There is no requirement that the data be returned as type text.

A generalized example of a parser follows:

{=========================== MQTTExampleParser =============================}
{ Returns a processed value from the MQTT data                              }
{===========================================================================}
(
  Data  { required parameter };
)
[
  ReturnVal  { processed value };
  { Other local variables as needed };
]
Only [
  If Watch(1);
  [
    { ReturnVal = some set of steps to process the data }
    Return(ReturnVal);  { mandatory statement }
  ]
]
{ End of MQTTExampleParser }

If the payload carries a timestamp and we want VTScada to use this timestamp then the decoder must return a structure declared using exactly the following format:

SomeTimeValue Struct [
                       Value;
                       TimeStamp;
                     ];

Example using a timestamp:

{========================== DataParserX ======================================}
{ Returns a final value. No indexing needed since indexing is done here.      }
{ It expects that the payload is 13-byte: 4-byte for a single precision float,}
{ 1-byte for a char, 8-byte for an epoch timestamp.                           }
{ Returns a structure [Value Timestamp] that can be interpreted by VTSRead    }
{=============================================================================}
(
  Data;
)
[
  X; C; TS;
  Measurement STRUCT [
                Value;
                TimeStamp;
              ];
  M;
]

Only [
  If Watch(1);
  [
    BuffRead(Data, 0, "%c%3b%5b", C, X, TS); { "%3b" is for IEEE single precision float (4 bytes)  }
    M = Measurement();
    M\Value     = X;
    M\TimeStamp = TS;
    Return(M);
  ]
]

Write example using a custom encoder:

For custom encoders there are 2 parameters that are passed in - Value and MemAddr. The driver supports writing single values only so the encoder must pass in the value and the address to write and allow the end user to specify how to format the message based on those 2 pieces of information. For example, you could set a specific dictionary entry to be a value and then format that dictionary to meet the needs of the protocol you are trying to work with..

Note: The terms Value and Metric are SparkplugB-specific, where data is stored as Metrics within a Topic, and each metric has a value.

{============================ DataEncoder1 =================================}
{ Returns a final value. No indexing needed since indexing is done here.    }
{===========================================================================}
(
  Data          { A value to be write.                                     };
  MemAddr       { Metric in SparkPlug B.Not used in this example           };

  { The terms Value and Metric are SparkplugB specific where data is stored }
  {   as Metrics within a Topic, and each metric has a value.               }
)
[
  X;
  JsonDict;
]

Only [
  If Watch(1);
  [
    JsonDict = Dictionary();
    JsonDict["V1"] = 51.5; { static value for demonstration purposes only }
    JsonDict["K1"] = Dictionary();
    JsonDict["K1"]["K1_1"] = Dictionary();
    JsonDict["K1"]["K1_1"]["K1_1_1"] = 3;
    JsonDict["K1"]["K1_1"]["K1_1_2"] = "v1_1_2_49";
    JsonDict["K1"]["K1_1"]["K1_1_3"] = New(3); { More demonstration-only values }
    JsonDict["K1"]["K1_1"]["K1_1_3"][0] = 13.50;
    JsonDict["K1"]["K1_1"]["K1_1_3"][1] = 22.88;
    JsonDict["K1"]["K1_1"]["K1_1_3"][2] = 36.09;
    JsonDict["K2"] = Data;
    JsonDict["Timestamp"] = CurrentTime(1); { Now }

    X = JSonEncode(JsonDict);

    Return(X);
  ]
]

This module is declared in AppRoot as:

    { Custom Encoders for MQTT data. }
  DataEncoder1        Module "DataEncoder1.SRC";

Finally, the Write address for the I/O tag is defined as:

VTSDemo/MyTopic+DataEncoder1++1

Where VTSDemo is the name used by the broker.


Write a Custom TagImport API

Write your own custom TagImport module to interface with VTScada's importer. This will allow you to import tags using the Tag Import Selector via the Tag Browser.

Variables

The following variables are part of the API in the module (typically a driver tag type) where TagImport will be run.

Ready

Required. True if the tag is fully set up and ready to accept an import request. Defaults to false.

CannotImportAWC

Optional. True if the import cannot be completed on an anywhere client. Defaults to false.

TagImport Module

The module must be named TagImport.

<
{================================= TagImport ==================================}
{ Module to pass tags to VTScada to import via the Tag Import Selector         }
{==============================================================================}
TagImport

Required. This module is in charge of populating the import data and reporting its status back to VTScada's importer. This is a launched module (and therefore must be slayed at the end). TagImport can have multiple states, allowing for additional user interaction before returning the import tag data structure.

Parameters

  TagData                     { Set of tag data structures to import          };
  pErr                        { Error message to pass back                    };
  pTagCount                   { Tag count to give user progress feedback      };
  pShowProgress               { TRUE to show the progress dialog              };

TagData (Required)

Must be populated with import information. This is a dictionary keyed by tag name and containing Parameter dictionary and Tag Type (by module name) elements. Each TagDataStruct in the TagData dictionary represents a single tag to be passed into the next stage of the import process.

For example, to create the full set of import information required for a tag called “ContextName\IOTagName” with a Read address of “HR1”:

TagData[“ContextName\IOTagName”] = \TagDataStruct();
TagData[“ContextName\IOTagName”].Type = “IO”;
TagData[“ContextName\IOTagName”].Parms = Dictionary();
TagData[“ContextName\IOTagName”].Parms[“ReadAddress”] = “HR1”;

There are no limits of the tag type or parameter names that can be used here; this can be used for custom types as well as VTScada tag types.

The final three parameters to TagImport are optional pointers to return status information about the update.

These must be dereferenced (*pErr = ...) to be set inside the import module.

pErr (Optional)

Error message to pass back. pErr can be set to the following values:

\#TAGIMPORT_ERR_NONE   = 0; - No error
\#TAGIMPORT_ERR_NOT_READY = 1; - The system is not in a state where TagImport can run safely
\#TAGIMPORT_ERR_ABORTED   = 2; - A programmatic or user-issued cancellation of the import

pTagCount (Optional)

The current number of tags we have added to TagData.

pShowProgress (Optional)

TRUE to show the progress bar dialog, FALSE to hide it.

Abort Tag Import Process

Optional. Allows a user to abort fetching the tag data at any point. This module pairs with the TagImport module and is declared in the same place.

 TagImport          Module   { Module to import PLC tags to VTS              };
 AbortImport        Module   { Module to abort the TagImport                 };
{=============================== AbortImport =================================}
{ Aborts the ongoing import process.                                          }
{=============================================================================}
AbortImport

AbortImport [

  If 1;
  [
    AbortTagImport = TRUE;
    Return();
  ]
]
{ End of AbortImport }

The abortion is triggered by the abort button displayed on the dialog during the import and AbortTagImport is consumed by TagImport to prevent the abort from continuing . If used this way, AbortTagImport must be declared in a common scope (e.g. the root tag module)

Related information:

Import Tags from PLCs


WebSocket Support

VTScada provides server-end support for WebSocket connections, compliant with RFC 6455. External clients can create a WebSocket on VTScada but there is currently no support for VTScada to create a WebSocket on an external server.

WebSockets and Security

  • For security, all WebSocket communication must be performed over a secured connection (HTTPS).
  • WebSocket upgrade requests must provide a valid HTTP Origin header that matches the name of the VTScada server the WebSocket is being created on.

A WebSocket upgrade request to a VTScada Internet Server will be permitted only if:

  1. There is a known "consumer" of the connection. (That is, VTScada code that has registered an interest in receiving the WebSocket.)
  2. The WebSocket has an acceptable Sec-Websocket-Version value.
  3. Authentication of the connection is successful.

Authentication is done either by HTTPServer via the VTScada Security Manager, which is used for authenticating users, or by an authentication mechanism provided by the consumer. This does not prevent the consumer from using the Security Manager to authenticate the credentials, rather than HTTPServer.

The size of WebSocket messages is limited by HTTPRequestMaxSize. The default provides security from actors attempting to consume large blocks of memory but the value may need to be increased if your application expects larger WebSocket messages.

Connection Process

The process begins by establishing a connection to a VTScada Internet Server. A request is issued to upgrade that connection to a WebSocket. Once upgraded, only the WebSocket protocol will be supported on that connection for the remainder of the connection's lifetime. WebSocket upgrade requests will be accepted only for subscribed consumers to HTTPServer. As endpoint verification is outside the control of the VTScada HTTPServer, the consumer must perform their own authority verification and sanitization of received data.

A WebSocket is created by the remote entity sending a valid WebSocket upgrade HTTP request with a Request-URI identifying a WebSocket request.

GET /{realm}/{application-GUID}/WEBSOCKET/{consumer-ID} HTTP/1.1

Where:

  • {realm} is a valid, configured realm name that a consumer has registered in interest in.
  • {application-GUID} is the GUID of the application containing the consumer.
  • WEBSOCKET is a literal verb.
  • {consumer-ID} is an identifier provided by the external entity requesting the connection be upgraded to a WebSocket. The format and content of this is determined by the consumer and external entity.

If the WebSocket upgrade request is successful, the consumer of a WebSocket will be presented with a bi-directional stream that encodes and decodes messages to WebSocket protocol without the consumer being required to have any knowledge of the underlying WebSocket protocol. A received set of WebSocket frames will be assembled into one message and presented in the stream to the consumer. Similarly each write the consumer makes to the stream will be transmitted as one WebSocket message, split into frames as required.

The application-GUID and RequestURI provided in the HTTP request to VTScada are used as a key to determine which consumer in VTScada the WebSocket will be passed to.

Write a WebSocket Consumer module

The consumer module within VTScada must register with HTTPServer via the WebSktSubscribe, HTTPServer subroutine. It must also provide a set of callback subroutine modules that are used during setup of a new WebSocket connection. The callback subroutines are described within the notes for WebSktSubscribe.


Services (Alarm, Historian, etc.)

Several core components of VTScada run as services. These include sets of functions and publicly available properties that you may use in your own code. Within this chapter you can find:

Alarm Manager

Configuration Management

Historian - API and Queries

Modem Manager Service

RPC Manager Service

Security Manager

Socket Server Manager

Time Synchronization Manager Service


Alarm Manager Service

Viewing: Scripting > Services (Alarm, Historian, etc.) > Alarm Manager Service

Alarm Manager

The Alarm Manager maintains a record of alarm activity, and keeps track of the current status of all alarms in the system, whether they are active, acknowledged, shelved, etc. This information is stored as records in an alarm database.

To record and store information, the Alarm Manager uses a VTScada Historian. By default, the System Alarm Historian is used, but others may be created and selected as part of application development.

Alarm data and process I/O data should always be stored with separate Historians.

Alarms are linked to Historians via Alarm Database tags. Two Alarm DB tags are standard with every VTScada installation: System Alarm DB is the default for all user-created alarms and events. System Event DB is used for all built-in VTScada events including security logs and operator-control actions. System Alarm DB is the default for alarm tags and alarms integrated into other tags such as I/O & Calculations tags. If you create a new Alarm Database tag, you can link tags to it either by default by making the tags descendants, nephews or siblings of the Alarm Database tag or manually through the properties dialog.

Note that the alarm files, Alarms.DB and Alarms.LOG are obsolete as of VTScada version 11.2. For legacy applications that are upgraded to 11.2 or later, all alarm history will be transferred to Historians as a one-time process. In the event that you intend to add extra Alarm Database tags to your application and store certain alarm information with those custom databases, do so before transferring the alarm history. Notes are provided in the topic, Moving to the Current Version

Programmers can use the Alarm Manager API described in this chapter for the following tasks.

  • Add alarm features to tags that they code from scratch.
  • Customize the columns and other display characteristics of alarm lists.
  • Query alarm status information for use in modules such as custom reports.
  • Query or modify alarm properties to view or change the Alarm Manager configuration.

Add Alarms to Custom Tags

Alarm Functions

Alarm Properties

Alarm Notification System Properties


Alarm API Structure Definitions

The alarm manager defines several data structures.

  • The configuration structure is obtained and populated when commissioning an alarm. Alarm Configuration Structure
  • The status structure may be obtained and monitored to watch for changes to an alarm's state. Alarm Status Structure
  • The transaction structure contains information about an alarm event that is stored to the database including what changed (active state on or off...), the logged-on user, which workstation, etc. Alarm Transaction Structure
  • The record structure is the complete set of information for each entry in the alarm database. This includes both configuration and transaction information. Alarm Record Structure

Alarm Configuration Structure

Every alarm can be described using a known configuration structure. When configuring a new alarm, this structure should be created via a call to \AlarmManager\GetAlarmConfiguration, then populated with the appropriate values before a call is made to \AlarmManager\Commission.

ConfigurationStruct { All Boolean flags default to FALSE }
Name

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

FriendlyName | Display name of the alarm's source. This is only needed for alarms that are not associated with a tag, such as service alarms. Tag alarms will always show the tag's Name as the display name.
Area | Area
Description | Description. See also: NoLegacyAlarmDesc
Priority | Priority. Must be valid to be commissioned. Must be an integer corresponding to the Alarm Priority tag values. A priority of 0 will be treated as an event and will not go on either the Active or Current lists.
Reserved
Disable | TRUE to disable the alarm.
DisableParmName | Name of the tag's disable parameter. Allows you to get the operator name who made the configuration change.
OnDelay | Seconds to delay before activating.
OffDelay | Seconds to delay before clearing.
RearmDelay | Seconds to delay before rearming after acknowledgment.
Setpoint | Setpoint of alarm evaluation. The value is compared against the setpoint.
ValueLabels | Array of labels to display instead of Value or Setpoint. Rarely used by tags other than digitals.
Units | Phrase Key of the setpoint units.
Function | Enumerated function for alarm evaluation. See: Alarm Manager Function Constants
AlarmType | String identifying the type of alarm. Used for display purposes only, in accordance with the ISA18.2 standard. Examples include "Low", "High", "Test".
Trip | TRUE if alarm only becomes unacked not active.
NormalTrip | TRUE if alarm becomes unacked when it clears.
OffNormal | TRUE if alarm only becomes active not unacked.
Deadband | Setpoint deadband.
PopupEnable | TRUE to enable popup display of active alarm.
SoundFile | Filename relative to app path of custom sound.
Custom | Number/String/Array/Dictionary/Structure containing custom data. This information is not shown anywhere on the AlarmPage by default, but could be displayed using a custom column.
AdHoc | TRUE if alarm is ad hoc.
ReactivateOnValueChange | If TRUE, the alarm will reactivate whenever the reported value changes.
DescPhraseID | PhraseID or a ParmPhrase structure to translate the description to current language.
NormalAck | TRUE to auto-ack the alarm when it clears.
Hook

The name of a module you supply, which will be called whenever any alarm event occurs for the given alarm, including events such as active / normal / acknowledge / shelve / disable / commission / etc.

VTScada will look for the callback module starting in the AlarmObject that is provided in the call to Commission(), and will search upwards until it reaches Code level. This gives you flexibility to specify your callback module in your custom alarm tag, or in a custom ancestor tag, or in the application (AppRoot).

The callback module must take a TransactionInfo structure as its only parameter. It is expected to return TRUE or Invalid to allow the transaction to be logged, or FALSE to prevent it.

GetAlarmConfiguration returns only a copy of the alarm's structure, not a reference. To update any property within the structure:

  1. Obtain a copy using GetAlarmConfiguration.
  2. Change values within that copy as required.
  3. Include the copy in a new call to the Commission function.

Related Functions:

GetAlarmConfiguration

Commission

Alarm Status Structure

AlarmStatus Struct
IsActive | TRUE if alarm is on the Active list
IsUnacked | TRUE if alarm is on the Unacked list
IsShelved | TRUE if alarm is on the Shelved list
IsDisabled | TRUE if alarm is on the Disabled list
IsSuppressed | TRUE if alarm is on the Suppressed list
IsSilentlySuppressed | TRUE if alarm is suppressed but not on the Suppressed list

This structure should be used in all new code, replacing the older functions IsActive, IsUnacked, IsShelved and IsDisabled.

Related Functions:

GetAlarmStatus

Alarm Transaction Structure

TransactionInfo Struct
Name | Alarm name
Cfg | Alarm's configuration. Only required to bypass the alarm's commissioned configuration.
Action | Alarm action code that identifies the reason for the transaction. See following list.
Transaction | Alarm transaction string
Timestamp | Alarm timestamp (UTC)
Value | Tag value
Custom | Custom fields. Overrides Cfg\Custom
Reserved |
MachineID | Workstation's MachineID. Defaults to local.
AccountID | AccountID of operator
Device | Name of client device
ExpiryTime | Time the record is to be removed (UTC)
RemovalGUID | Reference GUID for targeted removals
NoteInfo | Structure containing information about a note that has been attached to this transaction. It provides the Timestamp and GUID of this transaction.
IsReevaluation | TRUE if due to a reevaluation
FromPLC | TRUE if the action originated in a PLC's alarm block
Auto | TRUE if the action was automated such as in unshelving on time expiry
UserName | Account name of the security user
SessionID | Current user session ID
DoNormalAck | TRUE if this alarm should be acked when cleared but only if currently shelved/disabled/suppressed

The transaction string takes the form, "ListName+" or "ListName-". Several transactions can be combined in one string. The following example sets both the unacknowledged status and the active status off: "Unacked-Active-".

List names include the following: Active, Unacked, Shelved, Disabled, Configured.

Alarm Action Codes

Relates to "Action" in the Alarm Transaction Structure.
The action code is used for displaying a label in the "Event" column when viewing alarm history, and for filtering on specific kinds of historical events. The code is translated into a label by GetAlarmActionLabel().

The supported action codes are:

  • Ack - alarm acknowledged
  • Active - alarm became active and unacknowledged
  • ActiveAck - alarm became active and acknowledged
  • ClearAck - alarm became normal and acknowledged
  • ClearTrip - alarm became normal and unacknowledged
  • Commission - alarm commissioned
  • Decommission - alarm decommissioned
  • Disable - alarm disabled
  • Enable - alarm enabled
  • Event - an event
  • Modify - alarm modified
  • Notified - alarm notification sent
  • OffNormal - alarm became active without becoming unacknowledged
  • Purge - orphaned alarm purged
  • Rearm - alarm became active and unacknowledged again
  • Recommission - alarm recommissioned
  • Renamed - alarm renamed
  • Shelve - alarm shelved
  • Suppress - alarm suppressed
  • Trip - alarm became unacknowledged
  • Unshelve - alarm unshelved
  • Unsuppress - alarm unsuppressed

Alarm Record Structure

AlarmRecord Struct

TimeStamp | UTC time for the event
GenTimestamp | UTC time when the record was written
GUID | 16 byte unique ID for the event
ReferenceGUID | GUID of original event that this cancels
ReferenceTime | Time when original canceled event occurred
Name | Alarm name, typically the tag name
Area | Alarm area
Transaction | List additions and deletions
Action | Alarm action to display for history event
Priority | Alarm priority (integer)
IsShelved | TRUE if this alarm is shelved
Database | UniqueID of the alarm database tag
Custom | Field to be used by OEM & app code
MachineID | Workstation where record originated
Device | Name of originating client computer
UserID | User associated with the event
Description | Alarm description/message
Reserved
ExpiryTime | Time shelved record is to be removed
OnDelay | Time to wait (seconds) before activating
OffDelay | Time to wait (seconds) before clearing
Value | Tag value at time of alarm event
Setpoint | Alarm setpoint
Units | Setpoint units
Function | Setpoint function. See: Alarm Manager Function Constants
AlarmType | Type of alarm
SetpointLabel | Label to display instead of Setpoint
ValueLabel | Label to display instead of Value
RearmDelay | Rearm delay (seconds)
Deadband | Analog deadband
SeqNum | Sequence Number (for history sort)
Trip | TRUE if alarm was tripped
AdHoc | TRUE if alarm was ad hoc
NoteAttached | TRUE if one of more notes attached to record
IsConfig | TRUE if the alarm configuration is changed
IsReevaluation | TRUE if due to a reevaluation
UTF8 TRUE if the record was stored with UTF8 encoding.
Pre-multi-language records will not have this field in the packed records and this field will always be Invalid for those records.
Used to determine if the record needs to translate fields to UTF8 upon reading.
DescPhraseID PhraseID or a ParmPhrase structure to translate the description to current language.
Pre-multi-language records will not have this field in the packed records and this field will always be Invalid for those records.

The following three fields, TagName, Workstation and UserName are the text (not the ID) versions of the names and are logged for the following reasons:
a) after a tag or workstation or user is deleted, we can no longer convert the ID into a text name
b) for logging to an external SQL database where converting IDs isn't possible
These fields should be ignored unless the ID cannot be converted into a text version of the name.

TagName | Text version of the tag name of alarm (i.e. not the GUID of the tag.)
Workstation | Text version of the workstation where record originated
UserName | Text version of the UserName associated with the event
PopupEnable | TRUE if the alarm is configured as a popup
AckTimestamp | Timestamp when active alarm was acked
NormalTimestamp | Timestamp when unacked alarm went normal


Alarm Manager Function Constants

The Alarm Manager defines the following constants. Use these in custom code that enables the user to choose the trigger for an alarm condition. Constants should be preceded by \AlarmManager\

ALM_FUNC_ON_CHANGE | upon change of value (see following note)
ALM_FUNC_EQUAL | ==
ALM_FUNC_NOT_EQUAL | !=
ALM_FUNC_LESS_THAN | <
ALM_FUNC_LESS_EQUAL | <=
ALM_FUNC_GREATER_THAN | >
ALM_FUNC_GREATER_EQUAL | >=
ALM_FUNC_AND_WITH | &&
ALM_FUNC_OR_WITH | ||
ALM_FUNC_XOR_WITH | ^
ALM_FUNC_NOT_AND_WITH | !(&&)
ALM_FUNC_NOT_OR_WITH | !(||)

An alarm configured with the ALM_FUNC_ON_CHANGE constant is automatically a Trip alarm. As such, it will never appear on the Active list and only appear on the Unacked and Current lists. In order for an alarm to be on the Active list, there needs to be a way for the alarm to become normal, and this is not possible with an alarm-on-change


VTScada Event Logging

An alarm may be described as "A situation to which an operator must respond", while an event is "an action that is recorded, but requires no response." Events differ from alarms only in purpose and notification. For both, a triggering action occurs, and a transaction is recorded of that occurrence.

Many events are built into VTScada. Each change to security configuration is logged as an event recording who, what, when and where (workstation). Operator logons and log-outs are similarly recorded. Each operator-control action is recorded as is each VTScada action such as sending an alarm notification, generating a scheduled report from a Report tag, and more. All of these VTScada-generated events are logged in the Alarm Event DB tag.

All events can be viewed in the History page of any Alarm List.

Logging of Operator Control Actions

Each time an operator performs a control action in an application, such as starting a pump, that action is logged. The record includes the operator name, the workstation used, a timestamp, the name of the output tag, the area of the output tag, the current value, and the value written. If no tag area property is defined or available, then the value defined in the property, OperatorLogArea will be used.

The content of the logged message is controlled by the application property OperatorLogTemplate. Prior to version 11.2, messages longer than 80 characters were trimmed, but this is no longer the case. Other properties (see list of related information) control whether operator logging is enabled and provide default values to be used when none are otherwise available.

Logging of Security Events

Each time a user logs on or logs off, or a manager performs a security-related action such as adding a new user account, details about that action are added to the alarm log.

For each security entry in the History list, the following information is displayed:

  • The name of the workstation on which the security event occurred,
  • The account name of the person who performed the action
  • A time and date stamp,
  • Details about the action performed

Related information:

OperatorLogArea

OperatorLogging

OperatorLogName

OperatorLogTemplate


Querying the Alarm History

Viewing: Scripting > Services (Alarm, Historian, etc.) > Alarm Manager Service > Querying the Alarm History

Query the Alarm History

The History tab of the Alarm Page (or any Alarm List) offers the easiest way to query alarm history with its various filters. Note that you can use the keyboard combination CTRL+C to copy the information from a report (or any alarm list), then paste it into a spreadsheet for further processing.

In custom code, you can build your own alarm lists by using the function GetAlarmList GetAlarmList. This is the function used by the Alarm Page and every Alarm List widget.

You can also query historical alarm data using code via the SQL Interface command, SQLQuery. You may use this function to build SQL statements that can select data directly from the list of active alarms or the alarm history.

Two tables are available for you to query. :Alarms for current alarms and :AlarmHistory for past events. Note the leading colon in both table names.

For example, to query the names and priorities of all active alarms:

SQL_Query = "SELECT Name, Priority FROM :Alarms WHERE Active = 1";
\VTSSQLInterface\SQLQuery(SQL_Query, &Result, &FieldNames, &FieldTypes,
                          &RetCode, &ErrorMessage);

Upon success, the resulting two-dimensional array will be stored in the variable Result. The size of the first dimension is controlled by the number of fields you query for. The size of the second dimension matches the number of rows returned.

In the event of an unsuccessful query, Invalids will be returned in the SQLQuery parameters.

To retrieve all events associated with the operator Bob on April 10, 2008 :

SQL_Query = Concat("SELECT  Timestamp, Name, SubName, Event ",
                   "FROM :AlarmHistory ",
                   "WHERE  Timestamp >= '2008-04-10 0:00:00' ",
                   "AND Timestamp < '2008-04-11 0:00:00' ",
                   "AND Operator = 'Bob'");
\VTSSQLInterface\SQLQuery(SQL_Query, &Result, &FieldNames, &FieldTypes,
                          &RetCode, &ErrorMessage);

To know when the query has finished, watch for RetCode becoming valid.

Available column names to use in your query include:

Timestamp | Name | SubName
Event | Message | Priority
Type | HookPointValue | Area
HookPointUnits | Operator |

Related information:

Alarm Reports - Using the built-in alarm reports

GetAlarmList - VTScada function reference

SQLQuery - VTScada function reference

SQL Queries - Configuration and examples.


Alarm Notification Templates

Templates can be used to define the alarm that is delivered via the Alarm Notification System (voice, email or pager) or via the text-to-speech feature. These templates can use a combination of words and replaceable tokens to define the content of the alarm message. Templates may be up to 128 characters in length.

Alarm Notification Templates and DialerLocation have been moved from Settings.Dynamic to the default languages file (en.csv). To find a template phrase in the Languages panel of the Application Properties dialog, use the View button to display the Key column. Template phrases use the original property names as keys.

You may still use these properties in [System] section of your Settings.Dynamic file, but you must insert them using the Advanced mode of the Edit Properties dialog. The property will take precedence over the phrase in the language file.

Alternatively, you may create localized template values as properties of a parent Context tag.

For more complex templates you can define your own hook module for most of the tokens. Refer to Alarm Notification Template Hooks

Related information:

Separate templates are available for each of:

  • Spoken alarms
    • AlarmSpeechTemplate
  • Dialed voice messages
    • AlarmDialerTemplate
    • AlarmDialerStatusTemplate
  • Emailed alarms
    • AlarmEmailTemplate
    • AlarmEmailAckSubjectTemplate
    • AlarmEmailAckTemplate
    • AlarmEmailStatusTemplate
    • AlarmEmailSubjectTemplate
  • Paged alarm messages
    • AlarmPagerTemplate
    • AlarmPagerStatusTemplate
  • SMS messages
    • AlarmSMSTemplate *Also used for notifications sent as compact email messages.
    • AlarmSMSStatusTemplate
    • AlarmSMSAckTemplate

There are also two template configuration options that set the format used for the date and time if these parameters are used as part of the template.

  • Date Format see: AlarmTemplateDateFmt
  • Time Format see: AlarmTemplateTimeFmt

The complete list of replaceable tokens:

Token | Meaning
%A | Area of the Alarm tag.
%C | Custom data provided by the application. (See following notes.)
%D | Date of the alarm
%F | Full tag name
%H | Short tag name
%K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
%L | Opt-out message. This is be used only with SMS and EMail templates The message is stored with the language phrase key AlarmOptOutMsg and defaults to: Reply with "%0" to stop receiving alarm notifications.
%M | Alarm description
%N | New sentence for email and pager messages.
%O | Operator
%P | Priority of the alarm.
%S | Status of the alarm
%T | Time of the alarm
%U | Units of the Triggering tag.
%V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
%W | Pause for ¼ second. Has no effect on email or pager messages.
%Z | Setpoint.

Value (%V) and Setpoint (%Z) will use the labels corresponding to these values as stored in the record where applicable. If no labels can be found, the raw numbers will be used.

The %C token in a template can only obtain numeric and text values, not complex values. If a numeric or string value that exists inside a complex value needs to be included in an alarm notification, an AlarmTemplateHookC module will need to be created that returns this value. (Alarm Notification Template Hooks)

The Custom field can be set in a variety of ways:

  • In the Commission() call via the Custom field of the Alarm Configuration record.
  • In the EvaluateAlarm() call via the Custom parameter
  • In any Alarm<Action>Hook module by setting the Custom field of the TransactionInfo structure.

Using expressions in alarm notification templates

Before you proceed, take a last careful look at the available tokens. It is very possible that the information you wish to display is already available as a token. You do not need to use an expression to concat a string. All non-token characters used in the Value field of a custom property in a Context tag will be passed along as a string.

To use expressions in an alarm template, you will have to create a custom tag type with a custom property field and then add the expression to that field. To summarize, you will start out by configuring a regular Context tag and then use that to create a new tag type. Similar to a Context tag, all children of this tag type will inherit the custom property value but now you can use an expression in that field.

Follow these steps:

  1. Grant privileges - enable the "Manage Tag Types" privilege for your account. There are no default account types with this privilege, you must add it separately.
  2. Create a Context tag - In the Tag Browser, create a new Context tag and give it a name such as "EmailTemplateExp"
  3. Assign a Type - In the Type field of the ID tab, type the name of the new tag type. For example, AlarmEmailHandler
  4. Configure the custom field - This starts out the same as adding a custom property to a context tag. Navigate to the Settings tab, click Add, fill in a property name and a label. Click OK.

You must add a label. Alarm notification properties are sensitive to GUIDs and, unless specified, the field name will be their default value. For example, without specifying a label, the AlarmEmailTemplate field label becomes:
%D %T%NArea:%A%NName:%F%NDesc:%M.

  5. Create a custom tag type - Right-click on the Context tag you've just made and select "Create New Type". Keep all defaults and click OK. you can now find your new tag type in the tag selector under Containers or All Tag Types.
  6. Create your custom tag and add an expression - Create a new tag, select your new tag type from the selector and give it a name. In the Other Parameters tab, right-click your custom field and select Add Parameter Expression.

A field containing a valid parameter expression will turn blue. If you don't need an expression, you can still type directly in the field and it will behave like the Value field of a custom property in a normal Context tag; it will take tokens and pass all other characters as a string. (You must type %% to pass a percent sign as part of a string.)


Custom Alarm Hook API

To add extra functionality to an alarm action, create an alarm hook module. If your application contains a module with a name that matches one of the hook names defined within the Alarm Manager then your module will be called just before the transaction is logged, allowing you to perform extra work.

An alarm hook may not return INVALID. It should return TRUE to allow the transaction to proceed and be logged. Alarm hooks that return FALSE will stop the transaction from proceeding.

The hook module may be defined with one parameter, which VTScada will use to pass in the fully-populated Alarm Transaction Structure structure.

In versions of VTScada prior to release 11.2, developers who wanted to add custom functionality to an alarm event would override a module of the Alarm Manager to add their code. That technique is now obsolete. Many existing overrides will continue to work, but should be tested before being put into production use with version 11.2 or later.

1) Numbers following a hook name refer to notes that come after the lists.
2) A star ({*}) following a hook name means that it appears in one of the examples later in this topic.

Standard alarm hooks:

These are the most common. All of the standard hooks take an alarm transaction as an argument and return TRUE or FALSE to allow or ban that transaction.

  • AlarmAckHook {*}
  • AlarmActiveHook
  • AlarmCommissionHook
  • AlarmDecommissionHook
  • AlarmDisableHook
  • AlarmEnableHook
  • AlarmEventHook
  • AlarmModifyHook
  • AlarmNormalHook {*}
  • AlarmNormalAckHook {2}
  • AlarmNormalTripHook {2}
  • AlarmOffNormalHook {3}
  • AlarmPurgeHook
  • AlarmRearmHook
  • AlarmShelveHook
  • AlarmTripHook
  • AlarmUnshelveHook

Non-standard hooks:

These must be script safe.

  • AlarmAckAllHook {1}
  • AlarmEnableAckUIHook {5}{*}
  • AlarmEnableShelveUIHook {5}
  • AlarmEnableUnshelveUIHook {5}
  • AlarmPlaySoundFilterHook {4}{*}
  • AlarmPrintListHook {6}

Deprecated hooks:

  • AlarmCellAckHook - Use AlarmEnableAckUIHook instead.
  • AlarmCellUnshelveHook - Use AlarmEnableUnshelveUIHook instead.

{1} AlarmAckAllHook is unlike the other alarm hooks. The other hooks are called at the time the alarm transaction takes place, can alter the transaction structure, and can return true or false depending on whether they want the transaction to be logged or not. The AlarmAckAllHook will be called before the acknowledgment transactions take place. It will not be able to alter any transaction structures. If AlarmAckAllHook returns TRUE or Invalid, the alarms will all be acknowledged. If it returns FALSE, the alarms will not be acknowledged.
Note that AlarmAckAllHook is called only on the workstation where Ack All is pressed. If this needs to be shared via remote procedure calls to a different workstation, then your module to implement AlarmAckAllHook must include that feature.

{2} If AlarmNormalAckHook is not defined, AlarmNormalHook will be called instead.

{3} If AlarmOffNormalHook is not defined, AlarmActiveHook will be called instead.

{4} AlarmPlaySoundFilterHook is run whenever a new alarm comes up. It will run again if the alarm is already sounding, and it will also run if the alarms are muted. It takes an alarm record rather than an alarm transaction, and needs to be script safe.

{5} These disable alarm user interface (UI) actions based on the rules in your module. (One use case might be to disable alarm acknowledgment for someone who does not have the appropriate Control Tokens.) They take an alarm record structure as an argument and return TRUE or FALSE to enable or disable UI for acknowledging, shelving, or unshelving. They must be both script and steady state safe. These will also be called for alarms that are being acknowledged by an Ack All and will be able to stop those alarms from being acknowledged, but they will not be able to disable Ack All buttons.

{6} If AlarmPrintListHook is defined, it will be called by the alarm page printing module. Your hook module must format the entire print output including headers, body and footers. Further notes follow:

Returns:

A Buffer that will be directly written to the printer or chosen file

Usage:

Script Only

Parameters:

RecordArray - An array of AlarmRecord structures to be printed. Labels should have already been translated and processed to contain almost all useful information one might need to know about a record. The records will be the same that the Alarm List would show if it could show all, and they will be filtered according to current filter in the Alarm List.

Comments:

The AlarmPrintListHook module must return a text stream of the entire text to print. The RecordArray is a "friendly" version of an AlarmRecord, useful for displaying or printing alarms. The structure follows:

AlarmRecordInfo Struct [
  Action         { Translated Action };
  AlarmType      { Translated AlarmType };
  Area           { Translated Area };
  Custom         { Custom };
  DateTime       { Formatted date and time in user's time zone };
  Deadband       { Deadband };
  Description    { Translated Description };
  Device         { Device };
  ExpiryTime     { ExpiryTime in user's time zone };
  FriendlyName   { Alarm's friendly name };
  Function       { Function };
  GenTimestamp   { GenTimestamp in user's time zone };
  GUID           { GUID };
  IsActive       { TRUE if alarm is active; When viewing history, TRUE if alarm activated or tripped };
  IsDisabled     { TRUE if alarm is disabled };
  IsHistory      { TRUE if viewing history list };
  IsShelved      { TRUE if alarm is shelved };
  IsUnacked      { TRUE if alarm is unacked };
  MessageID      { OBSOLETE: stores the tag type };
  Name           { Alarm's uniqueID name };
  OffDelay       { OffDelay };
  OnDelay        { OnDelay };
  Popup          { PopupEnable };
  Priority       { Priority };
  PriorityEvent  { TRUE if Priority is 0 };
  PriorityText   { Translated Priority label };
  RearmDelay     { RearmDelay };
  Record         { Original Record };
  RelativeName   { Alarm's friendly name relative to a parent tag};
  Root           { Alarm tag object };
  Session        { User session };
  Setpoint       { Setpoint };
  SetpointLabel  { Translated Setpoint label };
  TagDescription { Alarm tag's current Description };
  Timestamp      { Timestamp in user's time zone };
  Units          { Translated Units };
  UserID         { User's AccountID };
  UserName       { Friendly username };
  ValueLabel     { Translated Value label };
  ValueLabels    { Array of translated ValueLabels };
  Value          { Value };
  Workstation    { Friendly workstation name from MachineID };
];

General Alarm Hook Examples:

Do something extra when the alarm closes:

<
AlarmNormalHook
(
 { parameter not required }
)
[
 { ... local variables ... }
]
Main
[
  If 1;
  [
     { Do something like write out a value to a PLC }
    DoSomething();
     { Returning Invalid or TRUE allows the AlarmManager to log the Transaction when we’re done }
    Return(TRUE);
  ]
]
>

Clear the alarm when it is acknowledged:

<
AlarmAckHook
(
  TransactionStruct { transaction structure };
)
Main
[
  If 1;
  [
     { Acknowledge and Clear the alarm }
    TransactionStruct\Transaction = Concat(TransactionStruct\Transaction, "Active-");
     { The additional transaction text is added to any that already exist. }
    Return(TRUE);
  ]
]
>

Mute a subset of alarms

To mute a subset of alarms, add a hook module named AlarmPlaySoundFilterHook.SRC to your application, declaring it in the AppRoot.SRC file. If this hook module exists in the application, it will be passed an alarm record for every alarm that could potentially be played. If the hook returns TRUE or Invalid, the alarm will be played, so long as the global Mute is not enabled. If it returns FALSE it will not be played. The parameter, Record, is documented in Alarm API Structure Definitions

The test within the hook might resemble the following generic example, where the Area property of the alarm record structure is being examined along with the name of the workstation. Alarms in the West area sound only on Server1 and alarms in the East area sound only on Server2.

<
AlarmPlaySoundFilterHook
(
  Record  { Alarm record };
)
Main
[
  If 1;
  [
    CanPlay = Record.Area == "WEST" && WkStaInfo(0) == "SERVER1" ||
                Record.Area == "EAST" && WkStaInfo(0) == "SERVER2";
    Return(CanPlay);
  ]
]
>

Allow alarm acknowledgment only after 4pm

{============================ AlarmEnableAckUIHook ===========================}
<
AlarmEnableAckUIHook
(
  AlarmRec;
)
[
  AllowAck;
]

Main [
  AllowAck = Now(1) > 16 * 3600 { Only allow acking after 4 PM };

  If Watch(1, AllowAck);
  [
    Return(AllowAck);
  ]
]
>

Related information:

Alarm API Structure Definitions - Includes the transaction structure.


Custom Alarm Context Menu API

To create a custom context menu for an alarm when right-clicked in an alarm list, use the AlarmPanelNavigate module.

This module is steady-state only and is typically declared in AppRoot so that it will apply to all alarms. It works by passing new parameters to the context menu.

AlarmPanelNavigate Parameters

Left, Bottom, Right, Top

Numeric expressions for the left edge, bottom, right edge and top coordinate of the context menu.

SubAlarmIndex

SubAlarmIndex is the portion of an alarm name that comes after the AlarmSeparatorString.

AlarmList

The base for callbacks.

SelectedRecord

The selected alarm record from the AlarmRecord Struct. See Alarm API Structure Definitions for more information.

Permissions

The user must have the related privilege to use the option. You must select one of the following options:

Options | Privilege
AllowAck | Allow alarm acknowledgment
AllowAddNote | Allow adding a note
AllowHelp | Allow opening the related help file
AllowGoToPage | Allow page access
AllowGoToPageAsPopup | Allow pop up access
AllowPlot | Allow plotting in HDV
AllowProperties | Allow opening the tag properties pop-up
AllowShelve | Allow alarm shelving
AllowShowDetails | Allow showing alarm details

Example:

This example is for a panel that will apply to all alarms.

<
{============================= AlarmPanelNavigate ============================}
{ Custom alarm navigation panel                                               }
{=============================================================================}
AlarmPanelNavigate
(
  Left;
  Bottom;
  Right;
  Top;
  SubAlarmIndex;
  AlarmList;
  SelectedRecord;
  Permissions;
)

AlarmPanelNavigate [
  \Code\Navigator(TRUE,
                  Left, Bottom, Right, Top,
                  GetPhrase("PropertiesLabel"),    Invalid,      !Permissions.AllowProperties,                        Invalid,
                  "--",                            Invalid,      0,                                                   Invalid,
                  GetPhrase("AcknowledgeLabel"),   AlarmList,    !Permissions.AllowAck,                               "Ack",
                  True(\AlarmManager.IsShelved(SelectedRecord.Name)) ? GetPhrase("UnShelveLabel") : GetPhrase("ShelveLabel"),
                                                   AlarmList,    !Permissions.AllowShelve,                            "ShelveUnshelve",
                  GetPhrase("AddNoteLabel"),       AlarmList,    !Permissions.AllowAddNote,                           "AddNote",
                  "--",                            Invalid,      0,                                                   Invalid,
                  GetPhrase("ShowDetailsLabel"),   AlarmList,    !Permissions.AllowShowDetails,                       "ShowDetails",
                  GetPhrase("PlotLabel"),          Invalid,      !Permissions.AllowPlot,                              "TrendPicked",
                  GetPhrase("GoToPageLabel"),      AlarmList,    !Permissions.AllowGoToPage,                          "GoToPage",
                  GetPhrase("GoToPopupPageLabel"), AlarmList,    !Permissions.AllowGoToPageAsPopup,                   "GoToPopupPage",
                  "--",                            Invalid,      0,                                                   Invalid,
                  GetPhrase("HelpLabel"),          Invalid,      !Permissions.AllowHelp,                              "HelpLaunch"
                  );
]

{ End of AlarmPanelNavigate }
>

Related information:

Alarm Manager

GetAlarmName

AlarmSeparatorString

Navigator Calls (Shortcut Menu)

Alarm API Structure Definitions


Alarm Notification Template Hooks

You can create a hook module to override the behavior of most tokens used by Alarm Notification Templates
The alarm template tokens that can be overridden are shown in the following list.

Token | Default Meaning
A | Area of the Alarm tag.
C | Custom data provided by the application
D | Date of the alarm
F | Full tag name
H | Short tag name
K | Station number (Part of every Polling driver, and Station type. Context tags used as site must be given a property named "Stn", in which the station number may be stored.)
M | Alarm description
O | Operator
P | Priority of the alarm.
S | Status of the alarm
T | Time of the alarm
U | Units of the Triggering tag.
V | Alarm value (this is the value of the alarm trigger at the time that it triggered the alarm)
Z | Setpoint.

Create an Alarm Template Hook

Alarm template hooks are modules that you add, either to your application as new files or as submodules of custom tag types that you have written.

If creating an alarm template hook for use with any alarm, it should be declared simply as a module in your application's AppRoot and not as a member of any of the classes found in that file. The declared name of the module must take the form:

AlarmTemplateHook?

where ? is one of the tokens in the preceding table. For example, a template hook for a custom alarm description (M) will be declared as:

AlarmTemplateHookM Module "MyCustomMessageHook.SRC";

The code for such a module might take the following form. In this simplified example the alarm description is transformed to upper case letters.

(
  AlarmRecord;
  Language;
)
[
  If 1;
  [
    Return(ToUpper(GetPhraseForLang(PickValid(AlarmRecord.DescPhraseID, AlarmRecord.Description), Language)));
  ]
]

Parameters

The parameters for all AlarmTemplateHook? modules are:

AlarmRecord

An instance of the AlarmRecord structure

Language

A language identifier string that can be passed into GetPhraseForLang().

Return Value

The return value for all AlarmTemplateHook? modules must be a text or numeric value that will be written out in place of the %? token in the template.


Alarm Filter Hook

You can use this custom hook module to filter alarms based on any criteria derived from the alarm record. This module was designed to filter an alarm list whenever a user inputs a search string into the search bar located in the top-right corner and initiates a search. This custom hook allows the user to define custom filtering logic on any criteria derived from the alarm record in their application.

Create an Alarm Filter Hook

Create a module within your application named AlarmFilterHook

When declaring this module in AppRoot.SRC, do not add it to any class. The declaration should immediately follow the list of constant declarations:

AlarmFilterHook Module " AlarmFilterHook.SRC";

Parameters

The module must take two parameters: Record, SearchString.

  • Record (Required) Is an alarm record. The parameter, Record, is documented in Alarm API Structure Definitions

• SearchString - (Required) The search string to match.

Return Value

This module must return a Boolean value. If TRUE is returned, it signifies that the alarm record matches the filter and should be displayed on the alarm list. If FALSE is returned, the alarm record does not fit the filter and should be hidden from the alarm list.

Example

(
  Record                      { An Alarm Record to match against              };
  SearchString                { The search string to match                    };
)

AlarmFilterHook [
  If 1;
  [
    Return(Record.Value > Cast(SearchString, \#VTypeShort));
  ]
]


Ad Hoc Alarms

(Ad hoc, from Latin meaning, "For this". Created solely for a specific purpose.)

Ad hoc alarms are intended for alarm conditions that may not be known ahead of time and thus cannot be commissioned. VTScada provides one example: the Roster check box widget, used for testing a Roster.

Ad hoc alarms may or may not be associated with tags. They are fully functioning alarms that can be activated, cleared, acknowledged, shelved and disabled, but will never appear on the Configured list. It is up to the caller of AdHoc() to manage the life of the alarm. If an ad hoc alarm is activated, it is up to the caller to clear (normalize) the alarm at some point.

Ad hoc alarms can be activated and cleared on client workstations, whereas commissioned alarms are only activated / cleared on the current server for their alarm database, or on an isolated workstation.

Note that ad hoc alarms are never purged.

Ad hoc alarms are evaluated using the function \AlarmManager\AdHocAlarm()

Comparison to regular alarms:

With a regular alarm, all workstations must be aware of the alarm criteria, description, priority, etc, with which they will commission the alarm. All workstations must be aware of the value the alarm is watching, and they must all attempt to evaluate the alarm whenever the value changes. Usually only the primary server's evaluation of the alarm will result in the alarm becoming active or normal, though the backup server would take over this roll if the primary was offline. If any client workstation becomes isolated from the server and it sees the value change, it will be able to activate or clear the alarm, and will eventually synchronize with the server and work out the current state of the alarm.

Any situation that can't meet the criteria of a regular alarm might need to use an ad hoc alarm. This might be the case if a PLC reports alarm events, where each event cannot be associated ahead of time to a particular tag and the alarm needs to be acknowledged by the user.

Another example might be where not all workstations (especially the server) are aware of the value being watched, and thus only a particular client can activate the alarm.


Customize Columns in Alarm Displays

The structure of lists in the Alarm Page and in Alarm List Widgets is controlled by the XML file, C:\VTScada\VTS\AlarmListFormats.XML. You may decide to customize the structure for any of the following reasons:

  • Add or remove columns in a list.
  • Set the default width of columns.
  • Add customized columns to a list.
  • Add a customized list format.

Do not edit C:\VTScada\VTS\AlarmListFormats.XML. Your changes will be lost with your next VTScada update.
Do not copy this file to your application folder. Local definitions of column formats and list formats that you have not customized will prevent updates from taking effect.

To make the customizations described in this topic, create a file named AlarmListFormats.XML in your application folder. The structure must be as described in this topic. You may copy sections of \VTScada\VTS\AlarmListFormats.XML to use as a template, but do not save any definition that you do not intend to customize. Your custom definitions will override or be added to those from the VTScada file.

The structure of the file is as follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
<AlarmList>
<ColumnFormats>
<Format name="SingleSet1">
<Column width="160">AlarmCellTimestamp</Column>
... more column definitions ...
</Format>
... more format definitions ...
</ColumnFormats>

<ListFormats>
<Format name="AlarmStandard" label="AL_StandardFormatLabel">
<list name="History" label="AL_HistoryListLabel">
<Single>SingleSet1</Single>
<Double>DoubleSet1</Double>
</list>
... more list definitions...
</Format>
... more format definitions...
</ListFormats>
</AlarmList>

XML Format Hierarchy:

  • ListFormat definitions are linked to user-interface tools, and are selected according to rules coded into that tool. Examples follow.
  • Within each ListFormat will be one or more lists such as Active, Current, etc.
  • Each list definition within each ListFormat will contain two versions, Single and Double. This selection is controlled by the operator by toggling the Row Height option.
  • The single version and the double version each specify a ColumnFormat.
  • Two ListsFormats may each contain a list with the same name such as "History", but these are separate definitions. Different column formats can be specified for History (and any other list) in different ListFormats.
  • ColumnFormats specify the display modules to be shown in the column cells, the order of the columns from left to right and the default width of each column.

For example, an alarm popup uses the "PopupStandard" list format, which contains only one list: "Unacked". In the Alarm Page, the default is to show the AlarmStandard format, containing History, Active, Unacked, etc, but if an operator chooses to view only the System Event DB, then the "EventStandard" list format will be selected automatically limiting the selection to just the History list.

Application properties are used to set the text used for the labels of lists and columns in the user interface. For example:

AL_HistoryListLabel              = History

The column widths specified in the XML file are the initial default widths only. After the alarm list has been viewed by a user, the widths are retained for that user. Any further modifications to the column sizes in the XML file will affect only new users who have never viewed the alarm list.

To test the column sizes, you muse either sign in as a new user, or delete the retained files and reload the page. To delete the retained files, follow these instructions:

  1. Switch to a different page so the alarm list isn't being displayed
  2. Using a file explorer, navigate to the application's \Data\Retained folder
  3. Filter this folder by *DrawAlarmList-AlarmList-ColWidths*
  4. Delete all the files that match the filter
  5. Switch to the page with the alarm list - the column widths should now match what is in the XML file

Column Format Definitions:

The set of lists shown in the Alarm Page is predefined, but you may alter the appearance of any list.

For each list, History, Active, etc. two sets of column formats are defined. Two are required so that the operator may use the Row Height button to switch between a list with one item per column and a list with (in some cases) two.

In the ColumnFormats section of the XML file, these are given generic names. The display name is set in the second section of the file. An example of the format follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
<AlarmList>
<ColumnFormats>
<Format name="SingleSet1">
<Column width="160">AlarmCellX</Column>
<Column width="26">AlarmCellY</Column>
...
</Format>
<Format name="DoubleSet1">
<Column width="26">AlarmCellX</Column>
...

Each "<Format" section sets the columns to be included. Columns are displayed in the list from left to right in the order found in the Format section.

The width sets the default size to be used by that column. Changes to column widths by the operator are stored on a per-operator, per-session basis, overriding your defaults. There are three ways to specify the width of a column:

  • Column width = "30". Sets the specific number of pixels to be used by the column.
  • Column width = 30%. This column will occupy 30% of the area remaining after the columns with specific width settings have been accounted for. The total of percentages should be 100 or less. See next option.
  • No width specification. All columns with no width specification will share equally the space remaining after columns with a specific or percentage width have been accounted for.

The example text, "AlarmCellX", "AlarmCellY", etc. must be replaced, either by one of the VTScada modules provided to format and display the contents of each cell in an alarm list, or by a module of your own creation. See link under Related Information.

Example 1:

For the standard alarm page display of unacknowledged alarms, move the name and description to the first column.

This will require a change of the ColumnFormat ordering, but the first step is to discover which ColumnFormat is used by the Unacked list in a standard display. Fortunately, the names in the XML file make this easy to find:

Under <ListFormats> find <Format name="AlarmStandard" ...> You can safely assume that this is the standard format. Within that section, find the list named "Unacked":

<list name="Unacked" label="AL_UnackedListLabel">
<Single>SingleSet2</Single>
<Double>DoubleSet2</Double>
</list>

From the above, it is clear that ColumnFormats SingleSet2 and DoubleSet2 are used. These can be copied from the original file, together with enclosing XML specifiers and reordered. The file you save to your application as "AlarmListFormats.XML" should look like the following. Only the two column formats are being overridden in your application. All others will continue to use the default XML file. Don't forget to import file changes to add your version of the XML file to the application.

<?xml version="1.0" encoding="ISO-8859-1"?>
<AlarmList>
<ColumnFormats>
<Format name="SingleSet2">
<Column>AlarmCellName</Column>
<Column>AlarmCellDescription</Column>
<Column width="26">AlarmCellPriority</Column>
<Column width="160">AlarmCellTimestamp</Column>
<Column width="50">AlarmCellAck</Column>
<Column width="18">AlarmCellIcon</Column>
<Column width="80">AlarmCellAction</Column>
<Column width="140">AlarmCellArea</Column>
<Column width="90" extra="1">AlarmCellValue</Column>
<Column width="90" extra="1">AlarmCellSetpoint</Column>
<Column width="70" extra="1">AlarmCellUnits</Column>
<Column width="18">AlarmCellNote</Column>
</Format>
<Format name="DoubleSet2">
<Column>AlarmCellDoubleNameDescription</Column>
<Column width="26">AlarmCellDoublePriority</Column>
<Column width="83">AlarmCellDoubleTimestamp</Column>
<Column width="18">AlarmCellIcon</Column>
<Column width="80">AlarmCellDoubleActionAck</Column>
<Column width="140">AlarmCellArea</Column>
<Column width="90" extra="1">AlarmCellDoubleValue</Column>
<Column width="90" extra="1">AlarmCellDoubleSetpoint</Column>
<Column width="18">AlarmCellNote</Column>
</Format>
</ColumnFormats>
</AlarmList>

The "extra" attribute, when present and set to 1, enables the visibility of the column to be toggled by the Show/Hide Extra Columns tool.

There is also an "alwaysShowShelved" attribute. For example:

<list name="Shelved" label="AL_ShelvedListLabel" alwaysShowShelved="1">

This attribute, when true, enables records that are marked as "shelved" to appear in the list even when the "Show Shelved Alarms" tool is not toggled.

Example 2:

Remove a column from display, such as the device history (AlarmCellDevice) column.

  1. Create an AlarmListFormat.XML in the application
  2. Create empty <AlarmList> and <ColumnFormats> sections.
  3. In the <ColumnFormats> section, copy and paste the SingleSet1 and DoubleSet1 formats from the original
  4. Modify SingleSet1 and DoubleSet1 by removing the AlarmCellDevice column

There is no way to customize the standard Alarm Page on a per-user basis. Instead, to allow admins to see the device column, they will need to draw the Alarm List widget on a page and configure it to use a custom format. They can secure this page so that only admins can see it. To create the custom format, do the following:

  1. Edit the AlarmListFormat.XML in the application
  2. In the <ColumnFormats> section, copy and paste the SingleSet1 and DoubleSet1 formats from the original and rename them, e.g. MySingleSet and MyDoubleSet
  3. Create a <ListFormats> section below the <ColumnFormats> section
  4. In the <ListFormats> section, copy and paste the AlarmStandard format from the original and rename it, e.g. MyAlarmFormat
  5. In the MyAlarmFormat format, for the History list, rename SingleSet1 and DoubleSet1 to MySingleSet and MyDoubleSet

The result will be similar to:

<AlarmList>
  <ColumnFormats>
    <Format name="SingleSet1">
 ...copied from original, but with no device...
    </Format>
    <Format name="DoubleSet1">
 ...copied from original, but with no device...
    </Format>
    <Format name="MySingleSet">
 ...copied from original and including the device...
    </Format>
    <Format name="MyDoubleSet">
 ...copied from original and including the device...
    </Format>
  </ColumnFormats>
  <ListFormats>
    <Format name="MyAlarmFormat" label="Droplist Title">
      <list name="History" label="HistoryLabel">
        <Single>MySingleSet</Single>
         <Double>MyDoubleSet</Double>
      </list>
      <list name="Active" label="ActiveLabel">
        <Single>MySingleSet</Single>
        <Double>MyDoubleSet</Double>
      </list>
      <list name="Unacked" label="UnackedLabel">
        <Single>MySingleSet</Single>
        <Double>MyDoubleSet</Double>
      </list>
      <list name="Current" label="CurrentLabel">
        <Single>MySingleSet</Single>
        <Double>MyDoubleSet</Double>
      </list>
      <list name="Shelved" label="ShelvedLabel" alwaysShowShelved="1">
        <Single>MySingleSet</Single>
        <Double>MyDoubleSet</Double>
      </list>
      <list name="Disabled" label="DisabledLabel" alwaysShowShelved="1">
        <Single>MySingleSet</Single>
        <Double>MyDoubleSet</Double>
      </list>
      <list name="Configured" label="ConfiguredLabel" alwaysShowShelved="1">
        <Single>MySingleSet</Single>
        <Double>MyDoubleSet</Double>
      </list>
    </Format>
  </ListFormats>
</AlarmList>

What is entered in the quotes after 'label=' is the text that will appear in the widget drop list. This is the Phrase ID that will appear in the language file. If there is no entry in the language file the text will show.

In the Alarm List widget drawn on the protected page, select MyAlarmFormat so admins can see the device column that the standard Alarm Page cannot see.

Related information:

Alarm Column Graphics Modules

AlarmListDefaultColumnFormat


Alarm Column Graphics Modules

The following are the names of graphics modules provided by VTScada to display information in Alarm Lists. The file, AlarmListFormats.XML controls which module is used by each column of each alarm display list.

"Double" in a module name signifies that it is designed for use when operators click the Row Height button to switch columns from a single item to doubled items.

AlarmCellAck

AlarmCellAction

AlarmCellAlarmType

AlarmCellArea

AlarmCellDeadband

AlarmCellDescription

AlarmCellDevice

AlarmCellDisabledIcon

AlarmCellDoubleActionAck

AlarmCellDoubleDeadband

AlarmCellDoubleDescription

AlarmCellDoubleExpiryTime

AlarmCellDoubleIconPriority

AlarmCellDoubleNameDescription

AlarmCellDoublePriority

AlarmCellDoubleSetpoint

AlarmCellDoubleTimestamp

AlarmCellDoubleValue

AlarmCellDoubleWorkstationDevice

AlarmCellExpiryTime

AlarmCellIcon

AlarmCellName

AlarmCellNote

AlarmCellOffDelay

AlarmCellOnDelay

AlarmCellOperator

AlarmCellPriority

AlarmCellPriorityColor

AlarmCellPriorityText

AlarmCellRearmDelay

AlarmCellSetpoint

AlarmCellShelvedIcon

AlarmCellTimestamp

AlarmCellUnits

AlarmCellValue

AlarmCellWorkstation

You can override any of these modules with your own versions. The overall structure should be similar to the following example. The content is up to you.

AlarmCellArea(Parms)
[
  Title   = "AL_AreaColumnLabel";
  SortKey = "Area";
]
Main [
  GUIText(…, Parms\TextColor, Parms\Font, Parms\Area);
  WinTooltipCtrl(…);
]

The Parms parameter is a VTScada-supplied structure containing the elements shown in the following table. Information about each alarm that is displayed in the cell, and the defaults for how it is to display are both passed to the module using this structure.

AckedIcon

AckedIconWd

ActiveIcon

ActiveIconWd

Action

AlarmType

Area

ConfiguredIcon

ConfiguredIconWd

Custom

Deadband

Description

Device

DisabledIcon

DisabledIconWd

DrawAlarmList

ExpiryTime

Font

FriendlyName

Function

GraphColor

GrayTextColor

GUID

HasNote

HistoryIcon

HistoryIconWd

IsActive

IsDisabled

IsHistory

IsSelected

IsShelved

IsUnacked

MessageID

Name

NoteIcon

NoteIconWd

OffDelay

OnDelay

Popup

PriorityColor

PriorityEvent

Priority

PriorityText

PriorityTextColor

RearmDelay

Record

RecNum

RelativeName

Root

RowColor

Session

Setpoint

SetpointLabel

ShelvedIcon

ShelvedIconWd

SmallFont

TagDescription

TextColor

Timestamp

Units

UserID

UserName

ValueLabel

ValueLabels

Value

Workstation


Configuration Management

Configuration Management is a term that describes VTScada features related to all configuration changes.

This includes ChangeSet files, the ability to read and write configuration files, the ability to make inquiries about the current Layer object (application) and the Version Control system.

Features of the Configuration Management System:

  • Does not depend on a configuration server.
  • Collaboration not limited by file locking.
  • Not bound to the RPC network
  • Provides a complete audit trail.
  • Easy to detect off-line changes since these must be merged into the system by an authorized user.

For any application, you can discover who has the working copy lock by selecting that application in the VAM and pressing the keyboard combination, "Ctrl-L".


Configuration Management API

The functions that make up the Configuration Management API are as follows.

These functions should be used only by advanced VTScada programmers. Errors in the use of these functions can cause irreparable damage to your application.

Related Functions:

Most of the following functions are called against a Layer object(e.g. \AppLayer\Function()). The Layer object can be acquired using GetAppInstance, GetLoadedAppInstance or GetOEMLayer.

AcquireLock - Subroutine to acquire an exclusive lock on reading/writing working copy files across all applications.

AppIsRunning - Reports whether the application has been started and the start-up process is complete.

AppIsStarted - Returns TRUE if the application has been started.

AppIsStarting - Returns TRUE if the application is in the process of starting.

ApplyChangeSetFile - Apply a named ChangeSet to an application layer.

CaptureSettings - Gathers a single property value or an accumulated section and returns the result in a tabular format.

Combine - Performs a Merge2 operation with automated conflict resolution and change priority.

CommitEditedFiles - This function compiles and commits edited files if the compile succeeds.

DirectApply - Applies a set of changes directly to the repository, without disturbing existing (non-conflicting) changes already on either branch.

EditFile - Informs the configuration management system that a file has been modified in the working copy, typically before making a call to CommitEditedFiles.

GetAppInstance - Asynchronously, retrieves the Layer object (\AppLayer) for a particular application specified by its GUID.

GetCodeObj - Retrieves the "Code" object associated with the layer.

GetINIProperty - Given an array of INIProperty structures, returns the value of a given property from that array.

GetLoadedAppInstance - Synchronously, retrieves the Layer object (\AppLayer) for a particular application specified by its GUID.

GetOEMLayer - Retrieves the layer root module of the OEM layer (should one exist) of the layer this is called against.

GetPlatformInfo - Gathers information about the current application and the workstation it is running on.

GetWCPath- Returns the full working copy path for an application.

GetWCRevision - Returns the revision structure for the repository revision in use by the working copy.

HasCompilationErrors - Reports if the working copy presently has unresolved compilation errors

HasUndeployedChanges - Finds whether the local machine is maintaining changes that have not been deployed, including changes that have been recorded by EditFile but have yet to be committed.

IsAppEditable - Returns TRUE if the application can accept changes without being re-started.

IsOnLocalBranch - Returns TRUE if the local machine is maintaining changes that have not been deployed within the repository.

IsRunOnly - Returns TRUE if the application is a run-file-only app, according to the WC contents.

LayerInUse - Returns true if the application is running, or if there are any applications that depend on this layer, running or not.

Merge - Applies a set of changes (the output of a Diff operation) to a buffer.

Merge2 - Attempts to apply two different Diff buffers to a single origin buffer.

ReleaseLock - Releases a working copy semaphore that was acquired by AcquireLock.

ReadINIProperties - Gathers the sum of all of the properties files in this layer and all of its parents including the local workstation files.

ReadPropertiesFile - Reads a single Settings file and returns an INIFile Structure.

RecordProperty - Helper function used to record settings without needing to explicitly interact with the settings files.

RepoSubscribe - Enables the caller to specify a callback which will be triggered whenever the application’s repository changes.

SetINIProperty - Given an INIFiles structure, this function sets the property with the specified name and section to the specified value

Start - Start an application.

LayerRoot\Stop - Stop an application.

WriteINIProperties - Writes properties to the local layer's various settings files in one operation.

WritePropertiesFile - Write a single Settings file according to the properties in an INIFile structure.


Historian - API and Queries

The Historian Manager is responsible for data logging, the Historian tags for your application, and storage & retrieval of logged tag values. Versions of VTS prior to release 10 used a Log Manager Service, which is now obsolete. This chapter describes the Historian Manager, data storage options for the Historian and how to configure VTScada to read legacy data that was created using the Log Manager service.


Recording Data

The default storage location for logged data is a file database system that was developed by Trihedral Engineering Ltd. Information is stored within the Data folder of your application. An API that provides read and write functions has been provided for use in your custom code.

In addition to, or instead of, the VTScada file database system, you can store data using any of the following database formats.

There is no advantage to be gained in speed or reliability by using a third-party database.

Supported databases:

  • Oracle 10g or later
  • SQLServer 2000 or later
  • MySQL using the MySQL ODBC Connector 5.1.6 or later
  • SQLite using the SQLite ODBC driver version 0.86 or later

The choice of database system to use is controlled by the application property, StorageType.

If using a StorageType other than the default, you must also tell VTScada where to find that database, using the StorageLocation property. Use the interface provided within the Historian tags to set these properties.


Specify the Storage Type for Historian Data

If you are using the default file database system for your data, no configuration needs to be done. If you would like to save data to one of the four supported database system instead, you must set the StorageType property for each Historian tag that will use that system.

The actual name of the property used is a combination of the Historian tag name and the keyword "StorageType". Thus, to set a storage type for the SystemHistorian, you would set a value for "SystemHistorianStorageType". For a tag named HistorianA, "HistorianAStorageType".

This property should not be modified if using the VTScada data store. Otherwise, "ODBC" is to be used for all other database storage formats since the Historian relies on the ODBC for communication with each. The specifics for connecting to a particular database are described in the next section, Specify the Location for Historian Data.


Specify the Location for Historian Data

You may set a specific location for the data and log files for your application using the application property, StorageLocation. Although the names of the properties are given here, these values should be set using the Historian tag's configuration panel.

The actual name of the property used is a combination of the Historian tag name and the keyword " StorageLocation ". Thus, to set a storage type for the SystemHistorian, you would set a value for "SystemHistorianStorageLocation ". For a tag named HistorianA, "HistorianAStorageLocation ".

The default value is "History". If setting an alternate storage location for a file database, you should provide the full path to the folder that you want to use. The most common reason for this is if you want to save data to a disk other than the one on which VTScada is running. This could also be done by mounting an alternate disk to the Data\History path via MS Windows™. The constant disk usage associated with logging data from a large or medium sized application may cause a disk to wear out faster than it otherwise would. By keeping the data store separate from the disk that is running VTScada, and maintaining redundant storage on another server, you can lessen the impact of disk failure on your operations.

In tests, directing the Historian to save data to network share locations proved to be slow. Use caution if you intend to re-direct the location of the VTScada database to a .shared location on your network

If setting an alternate storage location for an ODBC database, you can provide either a Data Source Name (DSN) or a connection string.

The advantage of a DSN is that it is relatively easy to configure using the Microsoft ODBC Administrator™ dialog. The disadvantage is that you or your system administrator must create that DSN on each server that the application runs on.

A connection string is somewhat longer to create, but having been written, it may simply be copied to each server. Connection strings may be easier to maintain over the life of the application.

Support is also provided for FileDSNs.

Example using a DSN:

SystemHistorianStorageLocation = DSN=MyDSN_Name

Example using a connection string:

SystemHistorianStorageLocation = Driver=SQL Server; Server=ServerName;Database=DBName;Uid=user;Pwd=password


Historian Manager API

The Historian Manager is a service that runs in the VTScada layer. It contains two public functions that can be accessed by your VTScada application. Note that script applications, which are not based on the VTScada layer, will not have access to these items.

The GetLog function has been marked as deprecated. All legacy code using that function should be updated to use the Historian functions instead.

Data logging is done through the use of the WriteHistory function. Later retrieval of that data is done using the GetTagHistory function.


Trending and Plotting Functions and Statements

There are two statements within VTScada that perform plot operations: The first is the Plot statement, which plots an array of values against its index. This is the most common plot type and can be used to create a line plot, or a filled or bar plot (these types of plots are useful for filling rectangular tanks with the trend of the recent tank levels as an alternative to just a bar of the current tank level).

The second plot statement is the PlotXY statement, which plots the values in one array against the values in a second array. This can be useful for plotting one plant parameter against another, such as plotting production rate against conveyer speed. One problem arises when plotting such values: Because the values of both parameters normally increase and decrease, the plot will appear as somewhat of a scatter if the X values are not consistently increasing. To solve this problem, use the Sort statement to re-order the arrays so that the Y values correspond to increasing X values.

You can also use the PlotXY statement as an alternative line drawing statement with each of the array elements specifying a line segment endpoint.

VTScada enables you to configure various line styles and fill patterns for bar plots. The plots may also be arranged to plot from left to right, right to left, bottom to top, or top to bottom. There are a total of 8 possible orientations for line plots, and 16 for bar plots. Optionally, plots may be configured to display in a digital or discrete format. Instead of drawing a straight line between two points, a step or square-looking plot is drawn that shows discrete changes in level, rather than continuous changes. Another option enables a given bit number in the array to be plotted - this enables arrays of values that contain status bits packed into short or long values to be plotted directly without having to unpack them. A final option enables groups of consecutive array elements to be averaged and plotted as a single value on the screen. This enables a large amount of data to be plotted on a screen of limited resolution without producing a high degree of apparent scatter in the data and while improving the plot speed.


Logged or Trended Variables in Tag Modules

Any data logged or trended variables in a tag module must be declared with a class in the range of 1 to 6, using syntax similar to the following:

Value (1);

The class specifies the type of data to log, as shown in the following table:

Class: | Data Type:
1 | Bit
2 | Unsigned Byte
3 | 16 Bit Signed Integer
4 | 32 Bit Signed Integer
5 | Double Precision Floating Point
6 | Text or Binary Data

Variables must be declared with an appropriate value or else they will not be logged.

The convention for declaring variables is alphabetically by variable class type. For example, if you were to declare Z(6), Y(2), X(5), A(5), then internally this will map to Y(2),A(5), X(5), Z(6).

After data has been logged by a tag, if you then add, delete or change the type of the variables, the old logged data will become inaccessible (although, it is not deleted). Changing type of logged variables, adding or deleting is similar to creating a new tag for the purposes of the Historian database.

If it is permissible for the data to be trended but not logged, the tag must be added to the "Trenders" tag group. Such tags will show a limited amount of data when viewed via the HDV.

If you have advanced logging requirements and want to integrate logging behavior into your tag, you must do the following:

  • Your tag must have a parameter or variable named "HistorianName". This should be set to the name of the HistorianTag to be used by your tag. It is better to use a parameter than a variable because parameters provide flexibility in configuration.
  • Note that any tag with an HistorianName parameter or variable will be automatically added to the Loggers and Trenders tag groups.
  • You must declare logged variables as stated above.
  • You must call \HistorianManager\WriteHistory() whenever you want to log data.

Related information:

Log Tag Data


VTScada SQLInterface Module

This service provides an SQL interface to VTScada historical data, current tag values, alarm data, or other custom tables on an application-by-application basis.

The interface can be accessed externally using SOAP or ODBC calls, providing support for a subset of SQL Closed Structured Query Language. Within VTScada, you might use the SQLInterface for the convenience that the SQLQuery function provides in some instances, relative to making multiple calls to GetTagHistory.

The SQLQuery function is essentially a wrapper for GetTagHistory. No SQL query parameters are supported other than those that can be performed by one or more calls to GetTagHistory and other VTScada functions. SQL functions that modify data or database structures are not supported.

The interface provides the following two functions:

  • SQLQuery
    Executes an SQL query on data in a VTScada application by turning that query into one or more calls to GetTagHistory.
  • RegisterCustomTable
    Before SQLQuery can be work, RegisterCustomTable must be used to record what information is to be available for a defined table name and how values are to be retrieved. All VTScada tags, notes, and alarm information has already been registered for you. Use this function only for custom data inquiry needs.

SQL queries specify table names where data is to be found. This does not match the system used by VTScada for data storage or retrieval, even if you have configured your Historian to use a third-party SQL database. There is no History table, nor is there an Alarms table, nor any History:TPP tables. But, the SQLQuery function is able to retrieve tag data as if those tables existed because RegisterCustomTable was use to link table names to the instructions for finding relevant data.

Related information:

SQL Queries - Configuration and examples.


ODBC Manager Service

This service module provides a number of useful database access features to free other application layers from having to do this. Modules executing queries are designed to be called as launched modules (in a script) and will remain active until complete.

ODBC Manager Library Startup

On initial startup, the ODBC Manager library waits until the RPC Manager has started (\RPCManager\Started). If this service fails to start, the ODBC Manager library will be prevented from starting.

After the RPC Manager has started, the ODBC Manager library makes a call to a global system function “\ODBCSetup()”. This is not a VTScada module, but rather one that you may choose to create and declare in your AppRoot.SRC file. (It is not mandatory.) Should you choose to create an ODBCSetup module, it may function as either a subroutine or a launched module. The purpose of this module is to perform any application-specific tasks that must occur before the ODBC Manager library is started.

ODBC Manager Logging

On initial startup, the ODBCManager ensures that a subdirectory named ODBCManager exists below the application's directory. The purpose of this directory is to provide a location for the optional log file, ODBCManager.log.

Logging can enabled with a check box in the ODBC Statistics dialog (ODBC Statistics). If logging is enabled, the log file will be created automatically. The log file can also be created if you attempt to view it via the View Log button in the ODBC Statistics dialog before any logging has actually happened to cause the creation of a log file.

The log file is stored as plain text and can be viewed with any editor.

The Clear Log button causes the .log file to be deleted. You will be prompted to confirm that you want to proceed.

Example Module using the ODBC Manager:

Idle[
  If True(SQLRequest) WaitQuery;
  [
    SQLRequest = FALSE;
    ErrorCode = Invalid;                    { Should be invalid before each ExecuteQuery }
    dbQuery    = "SELECT * FROM MY_TABLE";  { Any valid SQL statement }
    DSNString  = "MyDSN";                   { Name of DSN configured in ODBC Data Sources control panel }
    dbUserName = "MyName";                  { Database username }
    dbPassword = "secret"                   { Associated password }
      { ExecuteQuery will implicilty make a connection to the database if there is not an existing one }
    \ODBCManager\ExecuteQuery(&ErrorCode, dbQuery, DSNString, dbUserName, dbPassword, &Result);)
  ]
]
WaitQuery[
    { Need to wait for ErrorCode to become valid (indicates that query is done)}
  If ErrorCode == 0 HandleGoodData;
  If ErrorCode > 0 HandleError;
]
HandleGoodData[
  If 1 Idle;
  [
    { Process query result in Result }
  ]
]
HandleError[
  If 1 Idle;
  [
    { Handle query error }
  ]
]


ODBC Manager Constants

The following public constants are declared in the ODBC Manager:

Standard Error Codes:

Constant | Value | Meaning
#Err_NoError | 0 | No Error
#Err_Invalid | 1 | Invalid Error Code
#Err_Unknown | 2 | Unknown Error Code
#Err_ConnFail | 3 | Failed Connecting To db
#Err_ConnTimeout | 4 | Timed Out Waiting For db Connection
#Err_LostConn | 5 | Lost Connection To db
#Err_ExecTimeout | 6 | Obsolete, no longer used.
#Err_ExecLostConn | 7 | Lost The db Connection Executing Query
#Err_ODBC | 8 | ODBC Error Executing Query
#Err_DelNoWhere | 9 | DELETE Without WHERE Clause
#Err_FieldNum | 10 | Field Count Mismatch On Table Synch
#Err_FieldName | 11 | Field Name Mismatch On Table Sych
#Err_InvalidQuery | 12 | Invalid Query Expression
#Err_InvalidDSN | 13 | Invalid DSN
#Err_TransBegin | 14 | Error On Transaction Begin
#Err_TransEnd | 15 | Error On Transaction End
#Err_UserCancel | 16 | User Cancelled Connection
#Err_ForceDisConn | 17 | Error caused disconnect

Database Type Codes used in the ODBC Manager

The following numeric values are used by various functions in the library to select formatting characteristics appropriate to each database type.

Value | Meaning
0 | MS SQL
1 | MS Access
2 | Oracle
3 | MySQL
4 | SyBase

Data Type Codes used in the ODBC Manager

The following numeric values are used by various functions in the library to indicate the data type of a field.

Constant | Value
#SQL_BIT | -7
#SQL_TINYINT | -6
#SQL_BIGINT | -5
#SQL_LONGVARBINARY | -4
#SQL_VARBINARY | -3
#SQL_BINARY | -2
#SQL_LONGVARCHAR | -1
#SQL_UNKNOWN_TYPE | 0
#SQL_CHAR | 1
#SQL_NUMERIC | 2
#SQL_DECIMAL | 3
#SQL_INTEGER | 4
#SQL_SMALLINT | 5
#SQL_FLOAT | 6
#SQL_REAL | 7
#SQL_DOUBLE | 8
#SQL_DATE | 9
#SQL_TIME | 10
#SQL_TIMESTAMP | 11
#SQL_VARCHAR | 12


ODBC Manager Functions

Functions comprising the ODBC Manager library.

Related information:

ODBCManager Properties

Function | Description
AddConnection | Called to add a new DSN connection or get an existing one
BuildDelete | Builds a DELETE query
BuildInsert | Creates an INSERT query
BuildSelect | Creates a SELECT query
BuildUpdate | Creates an UPDATE query
ConvertToDbDate | Converts VTScada time to db date
ConvertToDbTime | Converts VTScada date to db time
ConvertToDbTimeStamp | Converts VTScada time/date to db time/date
ConvertToVTSDate | Converts db date to VTScada date
ConvertToVTSTime | Converts db time to VTScada time
ConvertToVTSTimeStamp | Converts db time/date to VTScada time/date
CopyRecords | A module for copying a record
DBDropList | Display drop list from db
DBGridList | Display grid list from db
ErrMessage | Converts error codes to ASCII strings
ExecuteQuery | Sends SQL commands & returns results
ExecuteQueryCached | Cache the query locally if it fails & send it to the db after the next successful transaction with the db.
FlushCache | Forces a flush of a cache file
FormatBatchQuery | Assembles array of queries into one
GetConnList | Returns a list of the available connections
ResultFormat | Reformats 2-d arrays
StatsWin | Called externally to show stats window
TableSynch | Synchs data tables in two different db's
Transaction | Starts a transaction within a DSN
TransactionCached | Starts a transaction with cache


Modem Manager Service

The VTScada Modem Manager provides data and voice telephony services for standard VTScada applications.

TAPI - Telephony Application Programming Interface. A component of Microsoft operating systems. The TAPI interface enables the connection of a PC running Windows to telephone services. The TAPI standard supports connections by individual PCs, as well as LAN connections serving many computers. Within each connection type, TAPI defines standards for simple call control and manipulating call content.

The Modem Manager provides services that allow modems connected to different machines to be managed as a common pool.

Key features of the Modem Manager are:

  • Able to control a pool of modems distributed across a number of PCs. Any combination of your modems may be included in or excluded from a given pool. Within a pool, each modem is tried in turn until a call is successful.
  • One more modems can be set aside from the pool, to be used as a preferred route for outgoing calls.
  • Provides control over which modems should be used, and when calls should be made.
  • Call setup, queue information, and progress information are distributed to all copies of Modem Manager on a networked system.
  • Queues and timekeeping use UTC for coordination of modems across multiple time zones.
  • Provides generic audio call handling facilities, including guard tone, DTMF detection, and speech synthesis.
  • Provides a way for you to list the modems in your system.
  • Trihedral provides both a TAPI Service Provider (TSP) and a modem audio driver. These have been developed to overcome limitations that were found in the standard Unimodem V driver from Microsoft.

The Modem Manager interfaces with a Microsoft system component called "TAPI" (see definition box). TAPI enables different modems to be handled in a generic manner, and to be shared between different applications and services (e.g. RAS or FAX). TAPI does not interface directly to the modem since this is the job of the Trihedral Voice Modem Service Provider. You may use the more common Unimodem V, but a Trihedral driver was developed to avoid several problems that have been found with the Unimodem V driver.

Physical modems are associated with modem tags. These hold the configuration details for each modem, and may be monitored for call progress or errors.

Related information:

Modem Tags - Configuration of.


Modem Manager Concepts

Client Server Relationships

The Modem Manager runs as a server on one system and as a client on others. The server and client Modem Managers cooperate to provide modem pool management and to set up data paths between modem users and the allocated modem(s).

Outgoing Calls

When an outgoing call is requested, the Modem Manager selects a free modem, or queues the call until a modem becomes free. When a modem is free, the call is dialed. The selected modem may be on a different PC than that requesting the call. The Modem Manager sets up transparent data paths between the modem and the requestor. In the event that the Modem Manager fails to complete the connection, it can retry the attempt using an alternative modem or modems, if they are available.

Incoming Calls

When an incoming call is received by one of the pool modems, the Modem Manager passes the initial data to objects that have previously registered an interest in incoming calls (discriminator modules).

  • If an object accepts the offered call, then the Modem Manager sets up transparent data paths between the modem and the recipient.
  • If no one accepts the call, then the Modem Manager returns the call to the operating system to allow other applications the opportunity to take the call.

This incoming discrimination can also function with incoming audio calls.

At any time there are three logical PCs involved in a call:

  • The caller or receiver.
  • The Modem Manager server.
  • The owner of the physical modem.

Depending upon the configuration of your system, the roles of these three logical PCs may be played out on one, two, or three physical PCs.


Canonical Address Format

If VTScada is to use the system's modem dialing rules then the phone number to be dialed must be given in canonical format.

The canonical address format is intended to be a universally constant directory number; for this reason, numbers in address books are best stored using canonical format.

A canonical phone address is a text string with the following structure:

+ CountryCode SPACE [(AreaCode) SPACE] SubscriberNumber | Subaddress ^ Name CRLF …

The components of this structure:

Component | Meaning
+ Equivalent to hex 2B. Indicates that the number that follows it uses the canonical format.
CountryCode | A variably-sized string containing one or more of the digits "0" through "9" (hex 30 through 39 inclusive). The CountryCode is delimited by the SPACE that follows it. It identifies the country/region in which the address is located.
SPACE | Exactly one space character (hex 20). It is used to delimit the end of the CountryCode portion of the address.
AreaCode | A variably-sized string containing zero or more of the digits "0" through "9" (hex 30 through 39 inclusive). AreaCode is the area code portion of the address, and is optional. If the area code is present, it must be preceded by exactly one left parenthesis character (28), and be followed by exactly one right parenthesis character (29) and one space character (20).
SubscriberNumber A variably-sized string containing one or more of the digits "0" through "9" (hex 30 through 39, inclusive). It may include other formatting characters as well, including any of the dialing control characters described in the Dialable Address Format
Character | Hex Encoding
! | 20
 | 23
$ | 24
* | 2A
, | 2C
? | 3F
@ | 40
ABCD | 41-44
P | 50
T | 54
W | 77
abcd | 61-64
p | 70
t | 4
w | 9

The subscriber number should not contain the left parenthesis or right parenthesis character (these are used only to delimit the area code), nor should it contain the pipe (|), carat (^), or CRLF characters (which are used to begin following fields).
Most commonly, non-digit characters in the subscriber number would include only spaces, periods (.), and dashes (-). Any allowable non-digit characters that appear in the subscriber number are omitted from the DialableString returned by the LineTranslateAddress function, but are retained in the DisplayableString.

| | Hex (7C). If this optional character is present, the information following it up to the next + | ^ CRLF, or the end of the canonical address string, is treated as sub address information, as for an ISDN sub address.
Subaddress | A variably-sized string containing a sub address. The string is delimited by + | ^ CRLF or the end of the address string. During dialing, sub address information is passed to the remote party. It can be such things as an ISDN sub address or an email address.
^ | Hex (5E). If this optional character is present, the information following it up to the next CRLF or the end of the canonical address string is treated as an ISDN name.
Name | A variably-sized string treated as name information. Name is delimited by CRLF or the end of the canonical address string and can contain other delimiters. During dialing, name information is passed to the remote party.
CRLF | Hex (0D) followed by Hex (0A), and is optional. If present, it indicates that another canonical number is following this one. It is used to separate multiple canonical addresses as part of a single address string (inverse multiplexing).

For example, the canonical representation of the main switchboard telephone number at Trihedral is:

+1 (902) 835-1575


Modem Manager Configuration Variables

Through the following application properties, you have extensive control over how the modem manager operates.

AnswerCalls

CallInterval1 Through CallInterval10

CallOutDelay1

CallOutDelay2

CallOutPriority

CycleDelay

CycleLength

DataIdleTime

DialerSpeechInit

DialResetTime

DialWaitTime

GuardTone

HangUpDelay

HelloPacketLength

InitialDataDelay

InitModemsDisabled

MaxHandOffCount

MinModemsFree

MMCycleTime

MMLogDateFormat

MMLogLevel

MMLogTimeFormat

MMRPCTimeout

ModemAlarm

ModemAutoReset

ModemManagerLogSize

<ModemName>Device

<<ModemName>Disabled

ModemRetries

ModemSpeechTO

ModemTCPIPPort

SiteRetries

SquelchDetectDelay

SquelchIdleTime

SquelchPacketLength

UseSerialAreaInModemCall

UseUnimodem


Sequence of Events for Incoming Calls

The exact sequence of events depends on whether the modem is operating in data mode or in audio mode. This, in turn, is decided by the collective modem media modes specified by the active call discriminator modules.

Modem in Data Mode

The following italicized words are application properties. Information on each of these may be found in "Application Properties for the Modem Manager".

When a call is answered, the Modem Manager starts a configurable noise suppression phase as follows:

  1. Wait for SquelchDetectDelay seconds, then go to step 3. If while waiting, data is received, then go immediately to step 2.
  2. Throw away data until either:
    1. An idle period equal to SquelchIdleTime seconds occurs, in which case go to step 3.
    2. Data received exceeds SquelchPacketLength, in which case the call is disconnected.
  3. Wait for data to start arriving. When it does, go to step 4. If the wait exceeds InitialDataDelay seconds, disconnect the call. Alternatively, if InitialDataDelay1 is specified, go to step 4 after the defined period of time. This allows for RTUs that don't speak until they are spoken to.
  4. Every DataIdleTime seconds, monitor the total amount of data received in this step. If it is at least HelloPacketLength bytes, or does not change between two successive DataIdleTime periods, go to step 5.
  5. Offer the received data packet to each registered driver.
  6. The data is offered to the registered driver(s) by calling the module discriminator in the driver's scope. The data received so far is passed in a buffer as a parameter to the discriminator module. This subroutine examines the data and returns Invalid if the data is not recognized, or the station identifier of the driver instance that should handle the call. If the call is accepted, then Modem Manager will call the driver's Connect() module, passing the station identifier and the stream as parameters.

An example of a data discriminator can be found in Example Data Discriminator.

Factors to Consider for the Configuration of Incoming Calls

  • Will incoming calls be answered (AnswerCalls)?
  • Set up modems (on a per modem basis) to answer on a specific number of rings (see: Modem Tag Type properties Settings Tab).
  • Decide how many modems should be kept free to accept incoming calls (MinModemsFree).
  • Specify noise filtering conditions to ensure that good connections are appropriately detected.
  • Register the driver (provide a module) (see Modem Manager Programming Interface).
  • Decide whether to hand-off unaccepted calls (MaxHandOffCount).

Modem in Audio Mode

An audio discriminator recites voice prompts to the caller, and determines the validity of the caller by received DTMF tones.

When a tag registers an audio discriminator object, that tag should have a DataPort variable and a module called AudioDiscriminator().

When a call is answered, the modem is initially in audio mode. The highest priority AudioDiscriminator() module is called with the tag's DataPort variable set to a useable stream.

  • This is a steady state call that times-out after the period of time specified when the discriminator module was registered.
  • If the discriminator module returns "0", the call is passed to the next discriminator module.
  • If the discriminator module returns a non-zero result, then it is deemed to have accepted the call.

The discriminator may read and write on the DataPort stream.

Any data written to the stream is converted to speech using the voice identified when the discriminator was registered. The speech device is initialized using the string defined by the DialerSpeechInit application property. Data written may include any escape sequences meaningful to the TTS engine.

If a bookmark is set, when the bookmark is reported back to the Modem Manager, a single character equal to 0x45+Bookmark Number is be inserted into the stream, and may be read by the discriminator module.

  • The only other data that can be received are DTMF tones inputted at the remote device (to receive such tones, this requirement must be specified in the media mode for the discriminator). This data appears in the stream as the digits 0..9, the number-hatch character (#), or the asterisk character (*).
  • If the discriminator accepts the call, then DataPort remains as a valid stream, and the tag that owns the discriminator now has control.
  • If the discriminator rejects the call or times out, then the call is passed to the next audio discriminator in priority order. If there are no more audio discriminators, the modem is switched into data mode, and the identification of the call continues as described in Modem in Data Mode (as if a data call had just been received).

Careful consideration needs to be given to the overall time tolerance of this sequence. If, say, a RAS call is received in audio mode, then it must go through all audio discriminators, the switching of the modem to data mode (which typically takes 10 seconds), and all the data discriminators, before the call is handed off to RAS. This is not a deficiency in the Modem Manager, but a necessary consequence of accepting mixed media calls.

An example of an audio discriminator can be found in Example Audio Discriminator.

Factors to Consider for the Configuration of Outgoing Calls

Local telecommunications authorities may have regulations regarding the frequency at which call attempts are made to a particular number. By defining values for the following modem-related application properties, you can set restrictions on redial attempts.

  • CycleLength defines the number of steps in the cycle (with a maximum of 10),
  • CallInterval1 through to CallInterval10 define the delay (in seconds) at each step transition.
  • CycleDelay defines the final delay (in seconds) before the cycle restarts.
  • HangUpDelay indicates the number of seconds to wait before hanging up the modem when there are not active attempts to read or write.
  • DialWaitTime enables you to configure the number of seconds to wait before retrying a failed modem operation after no dial tone or response from the modem has been detected. The default value is 10 seconds. During this time, TAPI sends initialization strings to reset the modem. If not granted an appropriate time interval, the modem will not reset properly.

For a complete listing of the configuration variables related to the Modem Manager, refer to "Application Properties for the Modem Manager".


Sequence of Events for Outgoing Calls

The exact sequence of events depends on whether the modem is calling out using data mode or audio mode.

Data Call

  1. The originating tag calls the Modem Manager's MakeCall() method.
  2. Immediately, the tag's DataPort variable is set to a valid value.
  3. Shortly after, DataPort becomes an integer value >=0.

Should the call fail in any way, then DataPort becomes negative. For further details of these values, see Call Progress and Error Codes.

  4. If the call setup completes successfully, then DataPort changes to a Stream value (ValueType(DataPort)==8).
  5. The call requester may now read and write to that stream to communicate with the called party.
  6. To hang-up the call, you may call CloseStream().

If the other end hangs-up or the call fails, then DataPort becomes Invalid.

If the call setup fails (Step 3), then the call is retried according to the configured retry settings. If the call is retried, then DataPort becomes an array pointer while the call is queued. DataPort will not go Invalid until the call has been abandoned.

Audio Call

  1. The originating tag calls Modem Manager's MakeCall() method with a media value mode indicating an audio call.
  2. Immediately, the tag's DataPort variable is set to a valid value.
  3. Shortly after, DataPort becomes a pointer to an array, indicating that the call is queued.
  4. After call setup is started, DataPort almost immediately becomes a valid stream value.

This is different from data call setup, in that there is no progress indication. Also, although DataPort is a stream value, the call has not actually connected at this stage. This anomaly arises because a modem operating in voice mode cannot acquire and interpret the various tones that indicate the progress of the call - the modem returns connected status as soon as dialing is complete.

The only practical action the caller can invoke is to operate a time-out that allows a typical connect time, before starting to use the stream.

Any data written to the stream is converted to speech using the voice identified when the discriminator was registered. The speech device is initialized using the string defined by the DialerSpeechInit application property. Data written may include any escape sequences meaningful to the TTS engine.

If a bookmark is set, when the bookmark is reported back to the Modem Manager, a single character equal to 0x45+Bookmark Number is inserted into the stream and may be read by the tag.

The only other data that can be received are DTMF tones input at the remote device. In order to receive such tones, this requirement must have been specified in the media mode supplied to MakeCall(). This data appears in the stream as the digits 0..9, or as the number-hatch (#) or asterisk (*) character.

To shut down a call, you can call the CancelCall() method. If the other end hangs up, DataPort will become invalid.


Allocating Modems in a Managed Pool for Outgoing Calls

There are situations that require a caller to indicate that only modems with a specific property should be used when making a call, even though those modems are part of the central managed pool (e.g. where virtual modems have been set up with special initialization strings (e.g. for cellular connection)). The Area parameter for modem tags can be used for this purpose. If a modem tag has an area defined, then it will only be selected for an outgoing call if the call originator has specified the same area name. Additionally, when allocating local modems on a particular system, the allocator will take account of any Area name associated with the modem tag, and use it to map the physical modem. The actual capabilities of a modem (Data, Voice, Fax, etc.) are handled by matching the physical media mode of the modem.

See also: Modem Tags.


Local Modems

Local modems are used in circumstances where you wish to be able to make outgoing calls from a modem that is part of the local PC's setup (in a distributed application, for example).

A local modem is defined by creating a modem tag in which the workstation parameter is blank (i.e. leave the "Workstation Name" field of the modem tag's configuration folder blank). The Modem Manager interprets this to mean that it has to associate this logical modem with the first modem that is not otherwise allocated on the local PC. If there is no such modem, then the local modem is unavailable at that workstation.

If you wish to associate a logical modem with a specific local modem, then include a line similar to the following in the workstation.Dynamic file on the PC.

ModemTagNameDevice = Actual Modem Device Name

Example:

Modem01Device = HSP56 Micro Modem

Please note the following details:

    A local modem is used for outgoing calls only.

    Local modems are only used on specific instructions from the tag that originates the call (see MakeCall()).

Calls scheduled for handling by a local modem are queued on a separate queue at the local PC. If the local PC is shutdown before the call has been made, then that call will not be picked up by another PC and all memory of that call request will be lost.


Modem Manager Alarm and Event Reporting

The Modem Manager maintains the Value parameter of the Modem Tag to indicate overall status. The value may be one of:

0 | Idle
1 | Incoming call
2 | Outgoing call
3 | Error

An alarm may be configured on the Modem tag's value. Configuration of alarm tags on modems is discussed in Modem Tags.

Internal Event Recording

The Modem Manager records events internally at one of four levels of detail. All events may be displayed on-screen using the Modem Tools widget. The default is to display level 0 events only.

  • Level 0 events are selected to be meaningful to normal operations personnel.
  • All level 0 events are distributed across all machines for display purposes.
  • All level 0 events cause an event entry in the system's alarm/event log.

Level 1..3 events are of a diagnostic nature, and it is not recommended that they be displayed on-screen during normal operation.

  • Level 1..3 events are only recorded on the workstations on which they occur.
  • All Modem Manager events are recorded in the system's "VTSTrace.txt" file if recording of Modem Manager events is enabled.

The level of on-screen display and the size of the on-screen display history are customizable using application properties. For a complete listing of the application properties related to the Modem Manager, please refer to "Application Properties for the Modem Manager".

You can disable the logging of modem manager alarms with the configuration variable ModemAlarm.


TAPI and UniModem Considerations

The Modem Manager does not interface directly with modems. Instead, it uses the system-provided telephony interface, TAPI. This enables VTScada to share modems with other TAPI-compliant applications, such as RAS services, FAX services, and so forth.

All TAPI modems share the same driver called UniModem. When a modem manufacturer's driver is installed, what actually happens is that an .inf file is processed, and a number of registry entries, understandable by UniModem, are added.

Modem Initialization Strings

The Modem Manager has no knowledge of modem initialization strings. These come from the system registry where they are entered when the modem manufacturer's driver is installed. The Windows Control Panel's Phone and Modems option (or Modems option) provides a mechanism for adding extra initialization strings.

Baud Rate

At first sight, it would appear from the Modem Manager's MakeCall method that the baud rate and other communications parameters can be set in the parameters to this method. However, what is being set is actually the parameters pertaining to local communication with the modem, not parameters for communication between the local and remote modem.

The only way that particular parameters for the modem - modem link can be set is by setting a specific initialization string for the modem.

If you want to use specific parameters for different destination locations, then it is necessary to define cloned "ghost" modems in the system configuration. This is discussed in the section that follows.

Cloned Modems

It is possible to define multiple modem entries that refer to the same physical modem. Different initialization strings can then be associated with the different clones. Note that if using this method, you probably have to reboot the system after adding each modem before you can add another.

In order to use these cloned modems from VTScada, you have to be able to specify which modem (or type of modem) to use for a particular call. This is achieved using the Area parameter to the modem tag, and the MakeCall method. Normally, the area parameter to a modem tag is unused. If it is used, then the Modem Manager will only select that modem for an outgoing call if the area matches the area parameter supplied to MakeCall.

Note that since a set of cloned modems actually map to one physical modem, only one of them can be in use at any time.

Further, only one of the clones may have incoming calls enabled. Failure to observe this will result in an error opening any of the modems in the clone set.

TAPI Errors

If you find that VTScada reports a modem as permanently unavailable, you may find that the modem event log indicates that a TAPI error is occurring. While a full list of such errors is given in Call Progress and Error Codes, in the vast majority of cases, this will be caused by one of two things:

  • The system has not been rebooted since the modems were last reconfigured. While a reboot is not always required, after some reconfiguration actions the system cannot enumerate the resources correctly until a reboot has occurred.
  • Some non-TAPI-compliant application has opened the serial port associated with the modem. Note that this includes VTScada's ComPort function and the system's HyperTerminal application (commonly used in troubleshooting modems).


Modem Manager API

If you are writing a custom driver to accept incoming modem calls, then you must use the Modem Manager interface. Fundamental tasks include:

Register a modem

You must call the Modem Manager's Register subroutine, passing the driver's discriminator object value, its station number, and a priority relative to other drivers. Here is a sample call with a priority setting of 10:

\ModemManager\Register(Root, Station, 10 { Priority });

Unregister a modem

If a driver needs to change its Station address, it must first unregister. You must call the Modem Manager's Unregister subroutine, passing the driver's discriminator object value, and the station number with which it previously registered.

\ModemManager\Unregister(Discriminator, Station);

Provide a discriminator subroutine

You must provide a discriminator subroutine. The Modem Manager will call this subroutine when it offers you an incoming call. The Modem Manager passes a BUFFER as a parameter. This Buffer contains the initial data received from the line (see HelloPacketLength). You should parse this data and decide whether your driver supports it, and for which STATION it is intended.

  • Return INVALID to reject this call.
  • Return a valid STATION number to accept the call.
  • If you accept the call, then the Port\IsConnected() module will go true. You can then obtain the serial port semaphore \PortManager.PortConnectSem to read and write data via the serial port.
  • If Port\IsConnected() becomes false, the call has been disconnected.
  • If you wish to hang up the call, call the subroutine Port\CallComplete().

Monitor call progress

The Port\DataPort variable is VALID if a call is being setup or is active. At all other times, it is INVALID. During call setup, the value is a SHORT INTEGER indicating the progress of the call, changing to a STREAM when the call connects (this is what IsConnected() indicates).

Related Functions:

ModemStream

Log events

If required, you may insert entries into the Modem Manager's event log. To do this, call the EventLog subroutine as follows:

\ModemManager\EventLog("Text message to be logged");

You should set the application property ModemManagerLogSize to at least 256. Failing to do so will result in the loss of all logging events that occur prior to the first display of the event log.


Required Subroutines in Custom Drivers

The following topics describe the Modem manager subroutines that must be used if you are writing a custom driver to accept incoming modem calls.

Registering a modem

You must call the Modem Manager's Register subroutine, passing the driver's discriminator object value, its station number, and a priority relative to other drivers. Here is a sample call with a priority setting of 10:

\ModemManager\Register(Root, Station, 10 { Priority });

Discriminator

You must provide a discriminator subroutine. The Modem Manager will call this subroutine when it offers you an incoming call. The Modem Manager passes a BUFFER as a parameter. This Buffer contains the initial data received from the line (see HelloPacketLength). You should parse this data and decide whether your driver supports it, and for which STATION it is intended.

  • Return INVALID to reject this call.
  • Return a valid STATION number to accept the call.
  • If you accept the call, then the Port\IsConnected() module will go true. You can then obtain the serial port semaphore \PortManager.PortConnectSem to read and write data via the serial port.
  • If Port\IsConnected() becomes false, the call has been disconnected.
  • If you wish to hang up the call, call the subroutine Port\CallComplete().

Call Progress

The Port\DataPort variable is VALID if a call is being setup or is active. At all other times, it is INVALID. During call setup, the value is a SHORT INTEGER indicating the progress of the call, changing to a STREAM when the call connects (this is what IsConnected() indicates). For details on the integer values, please refer to the ModemStream script function.

Event Log

If required, you may insert entries into the Modem Manager's event log. To do this, call the EventLog subroutine as follows:

\ModemManager\EventLog("Text message to be logged");

You should set the application property ModemManagerLogSize to at least 256. Failing to do so will result in the loss of all logging events that occur prior to the first display of the event log.

Unregister (Modem Manager)

If a driver needs to change its Station address, it must first unregister. You must call the Modem Manager's Unregister subroutine, passing the driver's discriminator object value, and the station number with which it previously registered.

\ModemManager\Unregister(Discriminator, Station);


Modem Manager Functions

The following functions are related to the Modem Manager.

CancelCall | Removes a queued call or abandons a call that is in-progress
Fail | Tells the Modem Manager to abort and retry an established, outgoing call
FindModem | Returns a pointer to one of the Modem Manager's own internal modem objects. This pointer may then be used to access public, read-only properties for display purposes
MakeCall | Queues a call request
ModemCount | Number of available modems
ModemDev | Obtain wave device handle
ModemDial | Initiate an outgoing call
ModemDigits | Monitor a voice call for key presses
ModemList | Enumerate the available modems and their capabilities
ModemMedia | Determine or change the media mode of a call
ModemStream | Prepare to receive an incoming call
ModemTransfer | Transfer a call to another system service
Register (Modem Manager) | Registers a discriminator that accepts incoming calls

Note also, that the Connect() method of the Serial Port tag includes the parameter, ConnectInitString, which can be used to programmatically send an initialization string for any particular connection attempt. If valid, this will override the initialization string configured in the serial port. A "\r" is always appended to this string.


ModemControl Plug-in

The \ModemControl plug-in module expects four parameters as follows:

Function

Identifies the calling condition for the plug-in:

Calling Condition | Definition
0 | about to begin a dial attempt for an outgoing call
1 | completion of a successful outgoing call
2 | failure of an outgoing call
3 | modem is going idle after a call or on exit from a failed mode
4 | modem is being set into a failed mode
Index
The index of this modem device in the list of system modem devices (as returned by the ModemList function).
Tag

The name of the tag that originated the call (functions 0, 1, and 2 only).

UserData
The opaque user data supplied as a parameter to the MakeCall() method (functions 0, 1, and 2 only).


Call Progress and Error Codes

Some values may overlap with Modem Tag Return Values. Use care not to confuse the two.

Values greater than or equal to zero are progress codes, while values less than zero are errors.

Progress Codes

Code | Description
0 | LineIdle Idle (no connection), waiting for call
1 | CallBegins Starting outbound call
2 | RingAnswered Incoming call answered, no connection yet
3 | DialToneOK Dial tone on outbound call
4 | DialingOut Dialing outbound call
5 | RemoteRinging Remote phone ringing on outbound call
6 | RemoteBusy Remote phone busy on outbound call
7 | CallConnected Connected (You should not see this value. A stream value is returned at this point)
8 | HandedOff Another application is handling the call
9 | IncomingCallRQ Incoming call detected
10 | TempProblem Temporary modem problem - hang up and retry
11 | IncomingCall Incoming call accepted

Error Values

Value | Error
-1 | NoModems No modems defined in the system
-2 | NoDialTone No dial tone detected on outbound call
-3 | RemoteBusyErr Remote phone busy on outbound call
-4 | NoAnswer No answer on outbound call
-5 | CallerHungUp Other end hung up an incoming call
-6 | ModemUnavail Modem unavailable
-7 | CallFailure Other call termination condition

TAPI Errors

Errors equal to or less than -101 correspond to the Microsoft Telephony Interface (TAPI) errors, which are normally numbered from 1. Specific errors that may be encountered are:

Code | TAPI error
-101 | TAPI error code 1 (LINEERR_ALLOCATED) - the serial port is in exclusive use by some other process.
-112 | TAPI error code 12 (LINEERR_INCOMPATIBLEAPIVERSION) - the system does not have the required version of telephony support (TAPI 2.0 required).
-115 | TAPI error code 15 (LINEERR_INUSE) - the line device is in use and cannot currently be configured, nor can it allow a party to be added or a call to be answered, placed, or transferred.
-147 | TAPI error code 47 (LINEERR_INVALMEDIAMODE) - the requested media mode could not be accommodated (e.g. voice call request on a non-voice modem).
-167 | TAPI error code 67 (LINEERR_NODEVICE) - the specified device identifier, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized. Alternately, the line device has no associated device for the given device class.
-168 | TAPI error code 68 (LINEERR_NODRIVER) - either TAPIAddr.dll could not be located, or the telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. Use the Telephony Control Panel to correct the problem.
-169 | TAPI error code 69 (LINEERR_NOMEM) - insufficient memory to perform the operation, or unable to lock memory.
-175 | TAPI error code 75 (LINEERR_RESOURCEUNAVAIL) - insufficient resources to complete the operation (e.g. a line cannot be opened due to a dynamic resource over-commitment). Also occurs where a modem is being used by a non-TAPI application.

The full list of possible TAPI error codes:

Error | Code | Error | Code
ALLOCATED | 101 | INVALMEDIAMODE | 147
BADDEVICEID | 102 | INVALMESSAGEID | 148
BEARERMODEUNAVAIL | 103 | INVALPARAM | 150
CALLUNAVAIL | 105 | INVALPARKID | 151
COMPLETIONOVERRUN | 106 | INVALPARKMODE | 152
CONFERENCEFULL | 107 | INVALPOINTER | 153
DIALBILLING | 108 | INVALPRIVSELECT | 154
DIALDIALTONE | 109 | INVALRATE | 155
DIALPROMPT | 110 | INVALREQUESTMODE | 156
DIALQUIET | 111 | INVALTERMINALID | 157
INCOMPATIBLEAPIVERSION | 112 | INVALTERMINALMODE | 158
INCOMPATIBLEEXTVERSION | 113 | INVALTIMEOUT | 159
INIFILECORRUPT | 114 | INVALTONE | 160
INUSE | 115 | INVALTONELIST | 161
INVALADDRESS | 116 | INVALTONEMODE | 162
INVALADDRESSID | 117 | INVALTRANSFERMODE | 163
INVALADDRESSMODE | 118 | LINEMAPPERFAILED | 164
INVALADDRESSSTATE | 119 | NOCONFERENCE | 165
INVALAPPHANDLE | 120 | NODEVICE | 166
INVALAPPNAME | 121 | NODRIVER | 167
INVALBEARERMODE | 122 | NOMEM | 168
INVALCALLCOMPLMODE | 123 | NOREQUEST | 169
INVALCALLHANDLE | 124 | NOTOWNER | 170
INVALCALLPARAMS | 125 | NOTREGISTERED | 171
INVALCALLPRIVILEGE | 126 | OPERATIONFAILED | 172
INVALCALLSELECT | 127 | OPERATIONUNAVAIL | 173
INVALCALLSTATE | 128 | RATEUNAVAIL | 174
INVALCALLSTATELIST | 129 | RESOURCEUNAVAIL | 175
INVALCARD | 130 | REQUESTOVERRUN | 176
INVALCOMPLETIONID | 131 | STRUCTURETOOSMALL | 177
INVALCONFCALLHANDLE | 132 | TARGETNOTFOUND | 178
INVALCONSULTCALLHANDLE | 133 | TARGETSELF | 179
INVALCOUNTRYCODE | 134 | UNINITIALIZED | 180
INVALDEVICECLASS | 135 | USERUSERINFOTOOBIG | 181
INVALDEVICEHANDLE | 136 | REINIT | 182
INVALDIALPARAMS | 137 | ADDRESSBLOCKED | 183
INVALDIGITLIST | 138 | BILLINGREJECTED | 184
INVALDIGITMODE | 139 | INVALFEATURE | 185
INVALDIGITS | 140 | NOMULTIPLEINSTANCE | 186
INVALEXTVERSION | 141 | INVALAGENTID | 187
INVALGROUPID | 142 | INVALAGENTGROUP | 188
INVALLINEHANDLE | 143 | INVALPASSWORD | 189
INVALLINESTATE | 144 | INVALAGENTSTATE | 190
INVALLOCATION | 145 | INVALAGENTACTIVITY | 191
INVALMEDIALIST | 146 | DIALVOICEDETECT | 192
ALLOCATED | 101 | INVALMEDIAMODE | 147


Modem Tag Return Values

Some values may overlap with Call Progress and Error Codes. Use care not to confuse the two.

The modem tag type associates a specific modem on a workstation with a physical phone line. A modem tag can have eight possible return values:

Modem Tag Value | Description
0 | Idle
1 | Modem calling (outgoing call in progress)
2 | Modem answering (incoming call in progress)
3 | General failure (modem failed)
4 | Server unavailable
5 | Workstation owning the modem is unavailable
6 | External failure
7 | Manually disabled

The value of the modem tag can be used with other tags. For example, a modem tag could be selected as the tag to be monitored by an alarm tag. An alarm could be triggered if the value of the modem tag is 3 (modem failed), alerting the users to modem failure.

See: Modem Tags


Modem Manager Constants

The following constants are associated with the media handling properties and requirements of modems, call requests, and incoming discriminators.

    AUDIO 0x08 for use with speech synthesis

    DATAMODEM 0x10 for data transfer

Three additional constants are defined, although the Modem Manager has no specific support for them.

    UNKNOWN 0x02

    VOICE 0x04

    G3FAX 0x20

Additional control properties associated with call handling are:

    NEED_DTMF 0x1000 enable receipt of DTMF tones when handling an audio call

    DTMF_STOPS_SPEECH 0x2000 received DTMF tones interrupt speech


Modem Manager Properties

The following variables may be accessed in read-only mode:

Variable | Description
AvailLinesNumber | Phone lines still operational
CallAttempts | Total call attempts
CallCount | Number of calls placed
CallDelay | Total accumulated delay between call requested time, and actual time handled
ConfigChange | Trigger. Set whenever the modem configuration changes
FailCount | Number of calls that have failed
LocalCallAttempts | Total local modem call attempts
LocalCallCount | Number of local modem calls placed
LocalCallDelay | Total accumulated delay between call requested time and actual time handled (local modems)
LocalFailCount | Number of local modem calls that failed
UsedLines | Number of phone lines in use


Example Audio Discriminator

This example is of source code for a VTScada page that implements a simple voice response system.

[
  Title = "Voice";
  Color = "<E6E6E6>";
  Bitmap;
  SecBit;
  WinFlag = 0;
  AudioDiscriminator Module { Module to receive incoming calls };
  { TAPI Media modes used to select the compatibility of a modem }
  Constant TAPIMEDIATYPE_AUDIO = 0x08;
  Constant TAPIMEDIATYPE_DATAMODEM = 0x10;
  Constant NEED_DTMF = 0x1000 { Enable DTMF when handling call };
  Constant DTMF_STOPS_SPEECH = 0x2000 { Rec'd DTMF stops any speech };
  spVoice = "bf5ead45-9f65-11cf-8fc8-0020af14f271"
  { Voice for telephone modem};
  Constant SMALLPAUSE = "\Pau=250\";
  Constant LONGPAUSE = "\Pau=500\";
  Trig;
  Number;
  Name = "(Phone)";
  DataPort;
  KeyPress;
  BookMark;
  Phase;
  Phrase;
  Incoming = 0;
]
Init [
   If \ModemManager\Started Main;
   [
      Return(Self);
      AddVariable(\Code, Name, 0, 256, 0, 0, 0, 0, 0, 0);
      Scope(Code, Name) = Self();
      Phase = 0;
      \ModemManager.Register(Self(), 1, 1,
      TAPIMEDIATYPE_AUDIO + NEED_DTMF + DTMF_STOPS_SPEECH,
      SpVoice, 30 { Discriminator Timeout }, Name);
   ]
]
Main [
   Return(Self);
   \System.Edit(40, 60, 180, 90, "Number to Call", Number, !Valid(DataPort),
                Trig, Invalid, 4, 1);
   If Trig;
   [
      Trig = Invalid;
      Phase = BookMark = 1;
      CloseStream(DataPort);
      \ModemManager.MakeCall(Number, 110, 8, 1, 0, 5, Name, Invalid,
      TAPIMEDIATYPE_AUDIO + NEED_DTMF + DTMF_STOPS_SPEECH, spVoice);
   ]
   If TimeOut((ValueType(DataPort) == 8) && !Incoming, 6) && Phase == BookMark;
   [
      BookMark = -1;
      IfThen(!Valid(Case(Phase - 1,
                   {0} Phrase = "Hello and welcome. Please press a key to continue.",
                   {1} Phrase = "This is message number 1",
                   {2} Phrase = "This is message number 2",
                   {3} Phrase = "This is message number 3",
                   {4} Phrase = "Goodbye!"
                   )),
                   CloseStream(DataPort)
             );
      SWrite(DataPort, "%s%s\\Mrk=%d\\\r", SmallPause, Phrase, Phase);
   ]
   If SerWait(DataPort, 1);
   [
      KeyPress = SerRcv(DataPort, 1);
      IfElse( PickValid(KeyPress >= 0 && KeyPress <= 9, 0) || KeyPress == "#" ||
              KeyPress == "*", Execute(
      { DTMF from phone - cancels any pending speech }
      Phase++;
      IfThen(KeyPress == "*",
            Phase = 1;
      );
      IfThen(KeyPress == "#",
            Phase = 5;
      );
      BookMark = Phase;
   );
{ Else }
{ Must be a bookmark }
   IfThen(KeyPress == MakeBuff(1, 0x41 + Phase),
      IfThen(Phase > 4,
               Phase++;
            );
           BookMark = Phase;
      );
   );
]
]
<
{==================== Voice\AudioDiscriminator =================== }
{ This module, runs the receive call handling. If a call is not successfully authenticated then the caller
ModemManager) will time out and will then attempt to hand the call off. }
{====================================================================}
AudioDiscriminator
(
   Mode;
)
Check [
   Incoming = 1;
   If TimeOut(1, 7);
  [
    Phase = 1;
    Phrase = "Hello, you have reached the VTScada modem tester.";
    SWrite(DataPort, "%s%s\\Mrk=%d\\\r", SmallPause, Phrase, Phase);
  ]
  If KeyPress == "9" Idle;
  [
    Phase = BookMark = 1;
    Incoming = 0;
    Return(1);
  ]
]
Idle [
]
{ End of Voice\AudioDiscriminator }
>


Example Data Discriminator

The following example displays a minimalist discriminator for the standard Modbus Compatible Device. This code would typically be in a file in the application directory, and referenced in the SERVICES section of the application's AppRoot.src root file.

[
Discriminator Module;
Connect Module;
Root;
Name;
Port;
]
Init [    { This module registers as the discriminator for tag MB01 }
   If \ModemManager\Started Main;
   [
   Name = "MB01";
    Port = Scope(\Code, Name)\Port;
   Root = Self;
   \ModemManager.Register(Root, Name, 10);
]
]
Main [
]
<
{================ ModiconDriver\Discriminator ====================}
{ This module pass in a buffer, return a Station ID if accept the }
{ call. The station address in the incoming message is inspected. }
{ Return invalid if reject the call.                            }
{=================================================================}
Discriminator
(
Buffer;
)
Main [
   If watch(1);
   [
      IfElse(PickValid(GetByte(Buffer, 0) == Scope(\Code, Name)\Station, 0),
      Return(Name),
      { Else }
      Return(Invalid)
      );
   ]
]
{ End of ModiconDriver\Discriminator }
>
<
{===================== ModiconDriver\Connect ====================== }
{ Returns the Workstation name of the driver server. Called by the  }
{ Modem Manager to determine the machine name of the current server }
{ for this driver.                                                }
{================================================================== }
Connect
(
Station;
Stream;
)
Main [
   If watch(1);
   [
      Return(WkStaInfo(0)) ;
   ]
]
{ End of ModiconDriver\Connect }
>


RPC Manager Service

This chapter provides architectural, programming, and configuration information on the VTScada Remote Procedure Call (RPC) subsystem. This section assumes good knowledge of the VTScada scripting language, programming, and familiarity with networking concepts sub-sections:

The following terms and abbreviations are used when referring to the RPC manager and its functions.

FIFO | The FIFO acronym stands for "First-in, First-out", which is a simple queue.
RPC | Remote Procedure Call. A Remote Procedure Call is simply an invocation of a VTScada module (subroutine or launched) on one workstation from VTScada code running on the same workstation or on another workstation. It should be noted that the "RPC" acronym does not pertain to the operating system's remote procedure call mechanism.
RPC Manager | The generic name given to the components comprising the RPC subsystem within VTScada.
Service | An object within a networked VTScada system that has an instance on other workstations on the network.
Service Instance | An instance of a Service. There can be one of these per application per workstation on the network.
Service Synchronization | The ability to ensure that all Service Instances of the same Service are operating on identical copies of the Service's data.
Synchronizable State | The data on which a Service operates, and which must be identically replicated in each instance of that Service within the distributed domain.


Overview of the RPC Manager Service

RPC Manager enables VTScada to operate within a domain distributed across multiple machines, by providing the ability to remotely execute a VTScada subroutine.

The RPC Manager provides the cornerstone of a comprehensive server/client architecture, which enables tags and other VTScada services running on physically separate workstations to coordinate their activities and share data. VTScada contains a number of services, (such as the Alarm Manager, Log Manager, Modem Manager), and enables these services, all of the I/O drivers and other network-aware software components to share their data using the RPC Manager.

A VTScada service is simply a VTScada module that registers itself as a named component with the RPC Manager. A VTScada service encapsulates the data and processing logic that provides a specific function within the application. Each service should be regarded as a separate entity whose service name is unique within the application. Different applications running on the same workstation can contain a service of the same name as a service in another application, That is, two standard VTScada applications will, for example, each contain a service called AlarmManager.

A service running within an application instance is termed a service instance. A distributed system contains many instances of the same service, each one running on a separate physical machine. At any given time, for each service, there is exactly one service instance that has "server" status. All other instances of the same service (running on machines other than the server instance) are either clients to that server or have not yet determined what their status should be. A brief moment may exist when there is no server for a service, but there will never be more than one server.

Server status can shift from one service instance to another at any time. Such shifts are normally the result of some failure of the server or failure of the server to communicate with an external device. When such shifts occur, each service must arbitrate which service instance is going to assume server status. All other service instances must then resynchronize to the new server and so become clients of it.

The RPC Manager provides the code that performs service synchronization and manages servers and service instances. The service code need only provide a few, simple methods that will be invoked by RPC Manager to achieve this. A simple, yet functional service example that supports all the essential RPC Manager methods is discussed in "Create a Simple Service".

RPC Manager also provides a set of methods that provide services with the ability to make RPCs, as well as a number of useful, ancillary methods. All the methods available are documented in the Application Control of Servership

In normal operation, RPCManager controls which service instance is currently the server for a service. The system is simply configured to instruct RPCManager how its servership control algorithms should operate.

In rare cases, it may be necessary to control the servership of one or more services by the application itself. Consider, for example, a system where maintenance of the system is necessary while the application is running. For operational reasons, the system owners do not want a number of key services to have servership held by the machine undergoing maintenance, but do want the application to be running.

In such circumstances the application needs to either be able to disable a particular machine from owning servership of the key services or, more generally, be able to control which machine is the server for those services. More complex situations could arise where, for example, a specific machine does not want to be considered a candidate for servership.

References in this document to version 4 of RPCManager refer to the RPCManager capable of using version 4 RPCManager protocol. This applies to VTS version 10 onwards.


RPC High Level Design

RPC Manager is composed of a number of layers, each consisting of a VTScada object instance. An illustration of the layers of which the RPC Manager follows:

Machines participating in the distributed domain communicate using sockets over TCP/IP. Each machine can be identified by any of the names by which it is known, or any of the IPs by which it can be addressed. RPC Manager on each machine runs a socket server which listens for socket connection requests on a specific port. The port number is configurable and defaults to 5780.

The RPC Manager layer "nearest" the sockets consists of SocketNode object instances. There is one SocketNode instance for each IP address with which the local RPC Manager is communicating. The next layer up consists of a set of MachineNode object instances. There is one MachineNode object instance for each machine participating in the distributed domain. Where all machines within the domain have only one IP address, there will be a one-to-one correspondence between MachineNodes and SocketNodes. However, where a machine has more than one IP address (otherwise known as a multi-homed system), there will be more than one SocketNode for the machine’s MachineNode.

SocketNode provides a reliable error-free transport for RPCs via a specific IP address. MachineNode provides the buffering and routing of RPCs to its sub-ordinate SocketNodes.

On a single-homed system, the RPC transport will fail when a MachineNode’s single sub-ordinate SocketNode is unable to reliably transport RPCs to the intended destination. In a multi-homed system, the RPC transport will fail only when all sub-ordinate SocketNodes are unable to reliably transport RPCs.

To identify the integrity of an RPC transport to higher layers, MachineNode maintains a session identifier (SID) (see Session IDs) for each application instance that is running on the remote machine associated with that MachineNode.

The SID is opaque data. You should not try to interpret the contents of it, just accept that the SID is unique to the reliable RPC transport to/from the multi-server application instance. If the transport fails, the SID will change to a new, unique value. If the multi-server application instance is terminated and a new one started, the SID will change to a new, unique value. If no RPC transport can be obtained to a specified multi-server application instance, (either because the application is not running or communication has failed), the SID will have a unique value, defined by RPC Manager as RPC_NO_SID. That the SID remains at an unchanging, valid value is an absolute guarantee that the same multi-server application instance is being communicated with and that no loss of RPCs is occurring.

The next higher layer, which manages service instances, uses the SID to control service synchronization. A TagNode object instance exists for each service instance that is running on the local machine. Each TagNode has a number of TagServerNode object instances, one for each machine that can be a server for the service (this may include the local machine). The TagServerNode remembers the SID that it obtains when it establishes contact with the corresponding machine and uses any change in the SID to detect loss of reliable communication with the potential server. Any change in SID, for the TagServerNode that corresponds to the server instance, will require the TagNode to initiate service re-synchronization. In this way, any loss of the information flowing via RPCs from a server to a client is detected and the service automatically re-synchronized to ensure that the client is not "out-of-step" with the server. This process is termed "service synchronization".

VTScada contains a variable, located in the root (system) scope that can be used as a prefix to access any of the methods and public data that RPC Manager provides. This variable is \RPCManager. You will see this prefix used repeatedly throughout the remainder of this document.


Remote Procedure Calls RPCs

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Overview of the RPC Manager Service > Remote Procedure Calls RPCs

Remote Procedure Calls (RPCs)

When a VTScada subroutine executes, all other statement execution within the thread that is running the subroutine is suspended. The RPC subroutine is run on the RPC Manager’s thread. This is a deliberate behavior, ensuring that only one RPC subroutine is ever running within an instance of VTScada. This enables the RPC subroutine to access three important variables, which RPC Manager maintains:

  • CurSocketNode - the MachineNode object that exists for the machine that issued the RPC. A MachineNode exists for every machine that an instance of VTScada can communicate with, including the local machine. Note that, before support for multi-homed machines was introduced, this variable did indeed refer to the SocketNode from which an RPC request had been received. Its name has not been changed, to preserve compatibility with existing applications.
  • CurSessionID - the opaque Session ID of the application instance that issued the RPC .
  • CurSourceAppGUID - the GUID of the application that issued the RPC .

The contents of these three variables are valid only for the duration of the execution of the RPC subroutine. When the RPC subroutine returns, these variables are deliberately invalidated and then set to new contents for the next RPC subroutine execution. If you wish to retain the contents of either of these variables, you must make a copy during execution of the RPC subroutine.

If the RPC subroutine is not written as a launched module rather than as a subroutine, then RPC Manager will launch the module, but access to the above variables is not permitted. A module launched in this way will be launched on the thread of the context into which the module is launched (normally the service’s thread).

You should treat RPC subroutines in the same manner as one would treat interrupt service routines. Execution of an RPC subroutine suspends all other RPC activity on the machine executing the subroutine. Therefore, if there is time-consuming work to be performed, it is preferable to have the RPC subroutine launch a worker module into an appropriate context, passing the contents of CurSocketNode and CurSessionID if required, as parameters. For example:

{==================== SampleRPCLaunch ========================}
{ This subroutine is called via RPC and launches off a worker }
{ module to do some time-consuming work.                    }
{=============================================================}
(
  SomeParam           { Parameter to the RPC subroutine             };
)
[
  DoTheWork Module;
]

Only [
  If 1;
  [
    {** Pass the CurSessionID & CurSocketNode to the launched module **}
    DoTheWork(SomeParam, \RPCManager\CurSocketNode, \RPCManager\CurSessionID);
    Return(0);
  ]
]

<
{============== SampleRPCLaunch\DoTheWork ===================}
{============================================================}
DoTheWork
(
  SomeParam             { Same as RPC subroutine                      };
  ClientSocketNode      { Client socket node at time of starting      };
  ClientSID             { Calling client's session ID                 };
)

Init [
  If 1 Main;
  [
    { Typical initialization code here }
  ]
]

Main [
  { Whatever code performs the time consuming work }
  If Finished;
  [
    Slay(Self(), 0);  { Terminate myself }
  ]
]

{ End of SampleRPCLaunch\DoTheWork }
>

Related information:

Cross-Application RPC


Session IDs

RPC Manager maintains a Session ID (SID) for each instance of an application running on a remote machine. This SID should be treated as "opaque" data. It can be tested for equality or inequality with another SID, it can be tested against Invalid and it can be tested for equality or inequality against the constant \RPCManager\RPC_NO_SID.

RPC Manager provides a SID so that your application can ensure integrity with a multi-server application instance. A SID will change value whenever reliable communication, for RPC, can no longer be maintained with a multi-server application instance. This can be caused by:

  • Irrecoverable failure of the communication link to the remote machine. RPC Manager will do its best to recover communication, in the event of transient failure, but there will come a point when RPC Manager determines that RPCs can no longer be reliably delivered to the destination. In this case, the current SID will change to RPC_NO_SID.
  • Termination of the application instance on the remote machine. SIDs will indicate the termination and restart of a multi-server application instance that occurs during a transient network failure. In this case the SID will change to RPC_NO_SID, if no application instance is running, or to a new SID if a new application instance is running.

A SID remaining at the same value guarantees that all RPC requests are being reliably transported to the same target application instance.

A SID can be obtained from a number of sources:

  • \RPCManager\GetSessionID(). This RPC Manager provided module can be called as a subroutine or run in steady state. It takes an application identifier and a machine identifier as parameters and returns the current SID for that application.
  • \RPCManager\GetServerSIDPtr(). This RPC Manager provided module can also be called as either a subroutine or run in steady state. It takes a service name and returns a reference to a variable holding the SID for the application instance that houses the current server for that service.
  • \RPCManager\Send(). This RPC Manager provided subroutine is used to issue an RPC. It will return the SID for the multi-server application instance for directed RPCs, , that was present at the moment the RPC was queued for transmission to the remote machine.
  • \RPCManager\CurrentSessionID. This public variable is only valid during the execution of an RPC subroutine and contains the SID for the application instance that sourced the RPC request.

An application can make use of the SID to ensure that it is still communicating with the same instance of an application as it was at some prior time. RPC Manager uses the SID for just such a purpose when synchronizing services .

Related information:

Types of RPC

Services


Types of RPC

The method used to specify the destination for an RPC can take one of two forms:

  • A directed RPC. This type of RPC specifies that the RPC should be executed on a specific machine, identified by name or IP.
  • A service RPC. This type of RPC specifies that the RPC should be executed on one or more machines that are participating in an application service (see Services), identifying the machines using terms such as "on the server" or "on all clients".

The service RPC is by far the most common. Performing RPC via services is much easier as RPC Manager does all the hard work of tracking which machine is the server and, most importantly, of maintaining synchronization between machines.


Cross Application RPC

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Overview of the RPC Manager Service > Cross Application RPC

Cross-Application RPC

In most applications, RPCs are made between two instances of the same application. By definition, these will be running on different machines. Some system designs, however, are composed of multiple applications and require communication between the different applications. RPC Manager provides the ability to communicate between applications and supports cross-application services and service synchronization, relieving the system developer of the control code necessary to achieve this.


Permitted Data Types in RPC

The following data types can be used in parameters to RPCs:

  • Numerics
  • Text
  • Streams
  • Arrays of the above, up to, and including, a maximum of 3 dimensions.
  • Dictionaries and Structures.

Note that pointers, including arrays of pointers are not supported.


Compression

The parameters to an RPC are automatically compressed to reduce the bandwidth requirements for RPC, however, it is good programming practice to pass large quantities of data as infrequently as possible.


Packed RPC Streams

Each RPC is asynchronous. The delivery order of RPCs is guaranteed to be the same as the order in which they were issued from an individual machine.

There means that there is no guarantee that if machine A issues an RPC to machine C moments before machine B issues an RPC to machine C, that the two RPCs will arrive at C in the order A, then B. However, if machine A issues RPC1 and then RPC2 to machine C, machine C will receive and process RPC1 before RPC2.

Where there is a need to ensure that a sequence of RPCs issued by machine A is either executed in its entirety by machine B, regardless of communication interruptions, or that there is a need to ensure that the sequence of RPCs cannot be interposed by RPCs from another machine, the sequence of RPCs can be "packed" into a stream. This is done using the RPC Manager method "PackRPC".

The stream, so obtained is then used as a parameter to a remote "RunRPC" RPC, a method also provided by RPC Manager.

This facility is commonly used to store a sequence of RPCs that will create a copy of a service’s synchronizable state on a remote machine.


Services

RPC Manager provides the mechanism for ensuring that services remain synchronized across the distributed domain. Each machine participating in the domain runs a copy of the service (a "service instance"). Exactly one service instance has server status and is sometimes referred to as the primary server for the service. All others have client status. Any number of machines can be capable of becoming the server. This list of potential servers is specified in the application’s Servers.RPC file or via the Edit Server Lists panel in the Application Configuration dialog.

For the purposes of synchronization, a service is assumed to contain a set of data that represents the "synchronizable state" of the service. When the service starts up on another machine and wishes to become a client of the server, the synchronizable state is transferred to the client. The service instance in server mode will then issue updates to that set of data. The client receives these updates and processes them to ensure that the service on the client reflects the state of the service on the server.

Likewise, if server status is to be transferred from one machine to another, each client of the new server must synchronize to the new server.

As the reader can probably appreciate, synchronization is a complex process, with many variants, which must be proof against many possible faults, both logic and timing. To have each service provide its own code to achieve this would be a rich source of application faults. Hence, RPC Manager provides all the necessary control logic to achieve service synchronization and requires each service to only provide a set of operations to supply the synchronizable state, sufficient for the service’s needs.


Programming Example Create a Simple Service

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Services > Programming Example Create a Simple Service

Programming Example: Create a Simple Service

To better understand the development of an RPC service, this section contains the VTScada code for a fully functional, yet simple service, which will maintain its synchronizable state correctly under all circumstances.

We will build this code up from scratch, starting with the simplest specification. The code contained within here is complete and fully functional. You can cut and paste the code into source files and use it.

The function of the service is to continually increment one numeric variable, on the server and broadcast the value of that variable to all clients. Each client that receives the new number verifies that it is one greater than the previous one. If it is not, the client increments an error counter.

If the service functions correctly, each client will receive the value of the counter as the synchronizable state, followed by incremental updates to the count, regardless of how many clients there are or at what point in the server’s life they are started.

The code for the main module of the service is quite straightforward. First, we need to register our service with RPC Manager and then enter a state where, if we are the server the counter is incremented and transmitted to all clients, via an RPC.

Here is the main module, in its entirety, along with an RPC subroutine that it calls:

{============================== SampleService ================================}
{ This service maintains a simple synchronizable state and properly supports  }
{ all entry points required by RPC Manager for correct operation.              }
{=============================================================================}
[
  SvcName = "Sample"            { Deliberately different from the module name.
                                  Doesn't have to be different, but this allows
                                  clear distinction in the code between the two};
  RPCStatus                     { Current RPC connect status                  };

  CurrentServer                 { Current server                              };
  ServiceMode                   { Textual description of service mode         };

  {***** The synchronizable state of this service is represented by a simple,
         continually incrementing  numeric. The last value generated by this
         service instance and the last value received by this service instance
         are needed to ensure continuity of count. *****}
  HeartbeatCountIn = 0          { Heartbeat counter                           };
  HeartbeatCountOut = 1         { Heartbeat counter                           };

  {***** Internal variables *****}
  LastHeartbeatCount = 0        { Last Heartbeat count rxd                    };
  SequenceErrors = 0            { Number of periodic event sequence errors    };
  ServerEnable                  { Server enable flag...prevents race condition};

  {***** Regular service RPC modules which are service specific *****}
  PeriodicRPC Module            { Periodic event RPC call module              };

  {***** Required Synchronization modules, which RPC Manager will call *****}
  GetServerChanges  Module;
  SetHeartbeat      Module;

  I;
]

Init [
  If 1 Main;
  [
    {***** Register the sample service with RPC Manager. *****}
    RPCStatus    = \RPCManager\Register(SvcName, Invalid, Invalid,
                                        Invalid, \RPC_SYNC_MODE);
  ]
]

Main [
  {***** Maintain a couple of variables just to show the status of the service.
         These can be displayed on a VTScada page *****}
  ServiceMode = *RPCStatus == 2    { Server status == 2 }
                  ? "Server"
                  : *RPCStatus == 1 { Client status == 1 }
                    ? "Client"
                    : "Unknown"     { Unknown yet == 0   };
  CurrentServer = \RPCManager\GetServer(SvcName);

  If Watch(1, *RPCStatus);
  [
    IfElse (*RPCStatus == 2, Execute(
      {***** Just become server...set the output value to the last received
             input value, plus 1 *****}
      HeartbeatCountOut = HeartbeatCountIn + 1;
      ServerEnable = 1;
    );
    { else } Execute(
      ServerEnable = 0;
    ));
  ]

  {***** While I'm server, periodically increment the heart beat "out" counter
         and update all clients *****}
  If Timeout(PickValid(*RPCStatus == 2, 0) && PickValid(ServerEnable, 0), 1);
  [
    \RPCManager\Send(SvcName             { Service sending the message  },
                     \RemoteGUID         { GUID defining app            },
                     0                   { Cut-off mode - NORMAL        },
                     1                   { Send to server flag - TRUE   },
                     Invalid             { Machine name or IP           },
                     1                   { Send to clients flag - TRUE  },
                     0                   { Execute local flag - FALSE   },
                     1                   { Recursive flag - TRUE        },
                     "PeriodicRPC"       { target RPC module to execute },
                     "SampleService"     { context to execute in        },
                     Invalid             { object for update caching    },
                     Invalid             { InputSessionID               },
                     HeartbeatCountOut++ { RPC module Parameters        }
    );
  ]
]

<
{================================ PeriodicRPC ================================}
{ Periodically RPC, called on the server and all clients, to update the       }
{ heart-beat (synchronized state).                                          }
{=============================================================================}
PeriodicRPC
(
  Sequence                      { Info regarding call                         };
)

PeriodicRPC [
  If 1;
  [
    CriticalSection(
      IfElse ((PickValid(HeartbeatCountIn, 0) != 1) &&
              PickValid(Sequence != HeartbeatCountIn + 1, 0),
        IfThen (PickValid(*RPCStatus != 2, 1),   { No sequence errors on server. }
          SequenceErrors++;                      { It's already bumped the count. }
        );
      { else } Execute(
        HeartbeatCountIn = Sequence;
      ));
      LastHeartbeatCount = Sequence;
    );
    Return(Invalid);
  ]
]

{ End of SampleService\PeriodicRPC }
>

Let us examine the code in a bit more detail:

The first task of the service code is to register itself as a service to RPC Manager:

    RPCStatus    = \RPCManager\Register(SvcName, Invalid, Invalid,
                                        Invalid, \RPC_SYNC_MODE);

The Register() call is passed the name of the service. This must be unique within the application, but can be the same name as a service within another application. The fifth parameter to Register() is the only other one we are using at present and is set to a special constant value \RPC_SYNC_MODE which tells RPC Manager that our service has a synchronizable state. Omitting this parameter, or setting it to zero results in a service that has no synchronizable state. In this case, there is no need to provide any of the synchronization support modules that we will see presently.

Register() returns a reference to a value that RPC Manager maintains on behalf of the service. The value that RPCStatus addresses (*RPCStatus) will be set by RPC Manager to one of three values:

  • 2 - If the service instance is the server.
  • 1 - If the service instance is a client.
  • 0 - If the state of the service instance has not yet been decided.

The remainder of the code in state Main uses *RPCStatus to determine what to do. ServiceMode and CurrentServer are set to values that can be put on a display page. They are not necessary for service operation.

When the service instance becomes the server and on the first evaluation of the service main module, the line:

If Watch(1, *RPCStatus);

evaluates to TRUE. This provides a point at which initialization can be performed when the instance that is server changes.

Finally, a timeout statement trips once per second on the server, to broadcast the counter contents to all connected clients and then increment the counter. The ServerEnable variable is simply there to prevent a race condition that would arise with two statements watching the same data value (*RPCStatus).

The RPC issued by the Send() call invokes module PeriodicRPC() on the server and all clients, carrying the count as the sole parameter to this RPC subroutine. When PeriodicRPC() is running in the server instance, it does not check the sequence number for errors.

Note that PeriodicRPC() performs its work in a CriticalSection, as RPC subroutines are run on the RPC Manager thread, whereas the remainder of the service code runs on the service thread.

This prevents erroneous results caused by one thread modifying a value shared by the service and the RPC subroutine. An alternative technique is to have the RPC subroutine launch a module that interacts with the service’s values. A module so launched, runs on the application thread. Selection of the most appropriate method is usually determined by the complexity of the operations to be performed in response to an RPC subroutine invocation.

Note also that the name for the service that is used for registration:

SvcName = "Sample" { Deliberately different from the module name

is different from the module name. The two names can be, and usually are, the same. However, they are two different entities, the service name being used to identify the service within the application and the module name used to identify a module within the scope of Code. The Send() call, in state Main, uses the module name to specify the context in which to find the RPC module, PeriodicRPC, but uses SvcName to identify the service within the application. The difference lies in the service name being used to determine which machines within the distributed system to send the RPC to, while the module name identifies the module within Code that contains the specified RPC module name.


Adding Server Only Synchronization

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Services > Programming Example Create a Simple Service > Adding Server Only Synchronization

Adding Server-Only Synchronization

The code in the preceding topic is sufficient to perform the work of the simple service, but requires the addition of a pair of modules to source and sink the synchronizable state when so requested by RPC Manager:

  {***** Required Synchronization modules, which RPC Manager will call *****}
  GetServerChanges  Module;
  SetHeartbeat      Module;

GetServerChanges() is launched by RPC Manager, on the server, when the service must provide its synchronizable state for a client. RPC Manager is careful to launch this module on the same execution thread as the service so that, while executing a script in GetServerChanges(), nothing else can execute on the service’s thread. This can greatly simplify the acquisition of the synchronizable state. It is still possible, however, to have a launched RPC or a module launched by an RPC subroutine run during execution of a script in GetServerChanges(), as launched modules typically do not perform all their work in one script. If any such modules can modify the synchronizable state of the service, it is essential to either place the acquisition of the synchronizable state by GetServerChanges() within a CriticalSection, or to wait in GetServerChanges() until all such modules have completed execution.

On entry to GetServerChanges(), all service RPCs for the service are suspended (RPCs for other services and directed RPCs are still processed), allowing GetServerChanges() to wait for any launched modules that can modify the synchronizable state to finish. It is good design to only have your synchronizable state modified by RPC subroutines or modules launched by RPC subroutines. In this way, as no more service RPCs will be started until GetServerChanges() indicates that they can, you can guarantee that the synchronizable state of your service will not change while GetServerChanges() samples it.

GetServerChanges passes the service’s synchronizable state to RPC Manager by returning a "packed stream" of RPC calls, which will be made on the client. This enables the re-construction of the synchronizable state to be achieved by making a sequence of RPC calls on the client, ensuring that the entire sequence of RPC calls is delivered to the client as one package, without scope for communication interruptions causing a partial update of the synchronizable state on the client. On the client, each component of the RPC package is executed in the strict sequence that they are packed into the stream on the server. No other RPC call can interpose in this sequence on the client.

The second of the two modules is SetHeartbeat(). This is simply a service-specified RPC subroutine that, in our simple service case, receives, as a parameter, the synchronizable state of the service and stores it on the client. This RPC subroutine is the only RPC in the call package delivered from the server.

Let’s look at the code for GetServerChanges():

<
{======================== GetServerChanges ===================================}
{ Called by RPC Manager during startup sync, on a server, to get the package  }
{ of RPCs which create a synchronizable state on the client which is in step  }
{ with the server.                                                          }
{=============================================================================}
GetServerChanges
(
  RevisionInfo                  { Revision info from GetClientRevision call
                                  made on synchronising client                };
  PackStreamRef                 { Pointer to var to receive changes           };
  ClientName                    { Name of client                              };
  Guid                          { GUID of the syncing application...        };
  SyncMonitorObj                { Object value of my RPCManager\ServerSync.
                                  Goes Invalid if sync aborts...VTS 10.0 on   };
)

[
  Stream                        { Stream of changes to go to client           };
]

Sample [
  {***** This delay is not necessary. It is only here to prove that our
         synchronizable state modification RPCs are suspended until we
         call SetDivert. *****}
  If Timeout(1, 5) Wait;
  [
    {***** Sample the synchronizable state and build an RPC package to send to
           the synchronizing client. *****}
    Stream = \RPCManager\PackRPC(Stream, "SetHeartbeat" { module },
                                 Invalid { scope },
                                 { Parameters: } Cast(LastHeartbeatCount, 4));
    {***** Start diverting all RPCs for this client from here onwards. RPC
           Manager will release the divert when synchronization done. This
           also enables the flow of service RPCs for this machine (the server).
           Expect a flood of 5 service modification RPCs to arrive! *****}
    \RPCManager\SetDivert(SvcName, ClientName);
  ]
  {***** If we lost the synchronizing session, abandon all hope! *****}
  If !Valid(SyncMonitorObj) Done;
]

Wait [
  {***** This delay is not necessary. It is only here to prove that the service
         RPCs can continue after the RPC package has been built and SetDivert
         called. At the end of this delay, this module will pass the sampled
         state to RPC Manager which, in turn, passes it to the client. If we
         lose the synchronizing session, abandon. ******}
  If Timeout(1, 10) || !Valid(SyncMonitorObj) Done;
]

Done [
  If 1;
  [
    *PackStreamRef = Stream;
    Slay(Self(), 0);
  ]
]

{ End of SampleService\GetServerChanges }
>

As stated above, RPC Manager launches this module when the server instance must provide the synchronized state of the service for a client. The parameters to GetServerChanges are:

RevisionInfo | See Client Revision Information.
PackStreamRef | A reference to a variable into which GetServerChanges() will store a packed stream of RPC calls that will be executed on the client.
ClientName | The workstation name of the client instance that is synchronizing with the server instance
Guid | The GUID of the synchronizing application. For cross-application RPC services, this will be different from the GUID of the application under which GetServerChanges runs.
SyncMonitorObj | The object value of the RPCManager object that is monitoring the synchronization sequence. If this goes Invalid, you should abort the current synchronization. Typically this will be because communications with the client have been lost. Only available on VTS 10.0 onwards.

The script in state Sample does the important work of this code. While this script is running, nothing else on the service’s execution thread can run. The first job is to pack together all the RPC calls that have to be made on the client to generate the same synchronizable state as is present on the server. In our simple case, this consists of a single call to SetHeartbeat with the current count as its only parameter:

    Stream = \RPCManager\PackRPC(Stream, "SetHeartbeat" { module },
                                 Invalid { scope },
                                 { Parameters: } Cast(LastHeartbeatCount, 4));

After the RPC package has been built into a temporary stream, the RPC Manager module SetDivert() is called:

    \RPCManager\SetDivert(SvcName, ClientName);

This causes two things to happen:

  • All RPCs for the service that are destined for the synchronizing client are held in a queue by RPC Manager until synchronization is complete. The effect of this is to allow the server instance to continue to perform its normal work, including updating other clients, without the risk of updates arriving at the synchronizing client instance before the synchronizable state has been stored there.
  • RPCs arriving for this service were held in abeyance when GetServerChanges() was launched. These RPCs are now permitted to flow.

The intent is that the synchronizable state of the service is now allowed to change. Changes to the state will be routed to in-sync clients and will be buffered for the synchronizing client until the client has processed the RPCs that bring it up to the same state as was sampled at the server.

Although the sample GetServerChanges shown is a launched module, (specifically to incorporate the code in state Wait to demonstrate the function of SetDivert), you can also write it as a subroutine module. In this case, it must return Invalid when it is finished its work. If you return a valid value, RPC Manager will hang. There is no particular advantage in choosing a subroutine over a launched module. You can simply choose the form that suits your needs best. The same is true of two other service synchronization modules, called by RPC Manager, named GetClientRevision and GetClientChanges. (Described later.)

The client stores the synchronizable state when RPC Manager unpacks the RPC package on the client. In this case, the only call in the package is to SetHeartBeat():

<
{=============================== SetHeartbeat ================================}
{ Called, on the client, by the RPC contained in the package generated by the }
{ server, during GetServerChanges.                                          }
{=============================================================================}
SetHeartbeat
(
  Sequence                      { Info regarding call                         };
)

SetHeartbeat [
  If 1;
  [
    HeartbeatCountIn = Sequence;
    \RPCManager\SetSyncComplete(SvcName, Invalid, 1);
    Return(Invalid);
  ]
]

{ End of SampleService\SetHeartbeat }
>

{ End of SampleService }

This simply stores the synchronizable state in HeartbeatCountIn and then informs RPC Manager that it is now synchronized. This is achieved by the call to SetSyncComplete(). It is vital that the client makes this call. Service synchronization will hang if this call is not made. Note that SetHeartbeat() does not have to make this call. It can be a separate call within the RPC package, but it must be made.

After SetSyncComplete() is called, RPC Manager releases the queue of service requests (on the server) for this client and all subsequent service RPCs start flowing normally to the newly synchronized client.


Configuring the Service

Now we will incorporate our service into a VTScada application and configure it. First, create a new, standard VTScada application. Do not enable remote configuration yet. Set the start page title to be "Test Service" and the start page file name to be "TestServ".

We want create a VTScada page that displays the innards of our service, just so we can see what is going on. Edit the "Pages\TestSrv.SRC" file to be like the following:

[
  Title = "Test Service";
]

Main [
  Return(Self);

    { RPC status }
  System.Edit(40, 110, 180, 70, "RPC Status:",
               \SampleService\ServiceMode, 0);

    { Server name }
  System.Edit(230, 110, 370, 70, "Server:",
               \SampleService\CurrentServer, 0);

    { Sequence Error Counts }
  System.Edit(40, 210, 180, 170, "Sequence Errors:",
               \SampleService\SequenceErrors, 0);

    { Sequence Numbers }
  System.Edit(40, 260, 180, 220, "Sequence Act:",
               \SampleService\LastHeartbeatCount, 0);
  System.Edit(230, 260, 370, 220, "Sequence Exp:",
               \SampleService\HeartbeatCount, 0);
]

A better way of doing this would be to interactively drop an instance of a widget that displays the required information, on a page. The creation of widgets is outside the scope of this document however, so the above will be sufficient for now.

Adding a module declaration to the VTScada application’s AppRoot.SRC file incorporates the service into the application. Suppose that the service code above is contained in file SAMPSERV.SRC. Then the AppRoot.SRC may appear as follows:

[
  Constant POINTS        = 0x0002     { Point template class                };
  Constant GROUPS        = 0xFF00     { Collections of point types          };
  Constant LIBRARIES     = 0xFF01     { Library class module                };
  Constant GRAPHICS      = 0xFF02     { Shared widgets for points   };
  Constant PAGES         = 0xFF03     { Graphic pages & dialogs             };
  Constant SERVICES      = 0xFF04     { Service class                       };
  Constant PLUGINS       = 0xFF05     { Plug-in class                       };
  Constant PRIORITYSTART = 0xFF06     { Items that are pre-started          };
  Constant TSERVICES     = 0xFF07     { Threaded service class              };

  [ (POINTS)        {========= Modules that are point templates ===========}
  ]

  [ (GROUPS)        {==== Modules that are collections of point types =====}
  ]

  [ (LIBRARIES)     {======== Modules that contain library objects ========}
  ]

  [ (GRAPHICS)      {= Modules that are shared widgets for points =}
  ]

  [ (PAGES)         {===== Modules that are graphic pages and dialogs =====}
    TestSrv Module "Pages\TestSrv.SRC";
  ]

  [ (SERVICES)      {===== Modules that are services that are started =====}
    SampleService Module  "SampServ.SRC";
  ]

  [ (PLUGINS)       {===== Modules added to other base system modules =====}
  ]

  [ (PRIORITYSTART) {===== Modules/variables that are to be prestarted ====}
  ]

  [ (TSERVICES)     {====== Modules that are threaded services to run =====}
  ]
]

Note that VTScada has already added a similar line for the initial page that we added.

Before we can use the service, it is necessary to inform VTScada which machine, or machines are potential servers for the service. This is normally done in the application’s Servers.XML file. A typical Servers.XML for our simple application might look like this:

<?xml version="1.0"?>
<RPC>
   <ServerLists>
      <Service Name="Default Server Lists">
         <Workstation Name="Default for Workstations">
            <Server>FREDSPC</Server>
         </Workstation>
      </Service>
   </ServerLists>
</RPC>

In our simple example, we have only one potential server, "FREDSPC", for all workstations and all services. All other machines that run this service will be clients to FREDSPC. You should use the workstation name of the machine that you wish to be the server, instead of FREDSPC. The application properties dialog provides the Edit Server Lists panel as a graphical interface for editing this XML file.

Now compile the application and run it. If all has gone well, you should see a display similar to the following: (navigation and title bar will vary by VTScada version)

Next we will enable remote configuration. That way, when you bring on one or more clients, the remote configuration service will ensure that subsequent code changes you make on the server will be correctly propagated. Start up the server instance again. On another machine, which will be a client, acquire and run the application. You should now have a server and a client that will maintain the simple numeric synchronizable state, no matter how you disrupt communication between them, or stop and start the application.

You can repeat the last step to add more and more clients, if you wish.


Adding More Servers

By simply changing the application configuration, you can add more potential servers to the list for our simple service. This enables you to experiment with "fail-over" from one server to another. Client machines will automatically re-synchronize to whichever machine is currently the highest available server.

For example:

<?xml version="1.0"?>
<RPC>
<ServerLists>
<Service Name="Default Server Lists">
<Workstation Name="Default for Workstations">
<Server>FREDSPC</Server>
</Workstation>
</Service>
<Service Name="Sample">
<Workstation Name="Default for Workstations">
<Server>FREDSPC</Server>
<Server>JOESPC</Server>
<Server>GONZOSPC</Server>
</Workstation>
</Service>
</ServerLists>
</RPC>

In this configuration, the Sample service has three potential servers, FREDSPC, JOESPC and GONZOSPC arranged in order of decreasing priority. You may have noticed that a different section was used for this (all other services are using the default list with just the single server, FREDSPC). This enables you to specify different server lists for different services.

The XML Service tag specifies potential server lists for the specific service identified by the Name property, with the "Default Server Lists" Name specifying the potential server list for all services that do not have their own potential server list section.

Now, the machine nearest the top of Sample’s server list, which has an available service instance, will be the current server for the service. If a higher-ranking machine becomes available, the higher-ranking machine will synchronize with the current server instance and then seize server status from the lower ranking, which will then switch into client mode and synchronize with the new server. All client machines will, likewise, synchronize to the new server.

By now you may have realized that this architecture is distinct from the traditional server/client architecture, where one or two machines were designated as server. Typically, one machine would be the "hot" standby for the other machine. The VTScada distributed architecture enables different services to have their server instances executing on different machines, each with different fail over strategies. The VTScada distributed architecture enables you to focus on writing solutions for your services, with minimal coding overhead to support such a versatile architecture.

The example is insufficient for some, more sophisticated needs. The following sections will examine the extensions to the above that are provided.


Server List Consistency

It is important to ensure that each machine that can be a server for a service has a consistent list of server machines. Failure to observe this will result in sporadic service synchronization failure. Note the wording of this statement. A machine that can never be a server, i.e. can only be a client can have a different server list from the server. This is the method used to implement clients-of-clients. However, a machine that can be a server must have a consistent list of servers specified for that service. Once again, note the careful wording. Consistent does not mean identical, but if a server has a different list of machines from another server, they are only allowed to be different by omitting some machines from the tail of the list.

For example, the server lists for the Sample service could be configured as follows:

<?xml version="1.0"?>
<RPC>
<ServerLists>
<Service Name="Default Server Lists">
<Workstation Name="Default for Workstations">
<Server>FREDSPC</Server>
</Workstation>
</Service>
<Service Name="Sample">
<Workstation Name="Default for Workstations">
<Server>FREDSPC</Server>
<Server>JOESPC</Server>
</Workstation>
<Workstation Name="GONZOSPC">
<Server>FREDSPC</Server>
<Server>JOESPC</Server>
<Server>GONZOSPC</Server>
</Workstation>
</Service>
</ServerLists>
</RPC>

You may wish to use such a configuration if machine GONZOSPC was in a remote location from FREDSPC and JOESPC. Then, if the communication medium between the two locations is broken, the area without GONZOSPC [the "Default for Workstations" list for the "Sample" service, used by FREDSPC and JOESPC] will use the higher available server of FREDSPC and JOESPC, whereas the area with GONZOSPC will lose communication with FREDSPC and JOESPC and so will fall back to GONZOSPC.

Of course, precisely the same effect would be obtained by having each machine use the first list, but this method reduces communication traffic between the two areas slightly, by not having to have FREDSPC and JOESPC examine the server status of GONZOSPC. It also prevents FREDSPC and JOESPC from every synchronizing to GONZOSPC. If GONZOSPC is isolated from the other two, higher servers, it will re-synchronize to the higher order servers when communication is restored, destroying the local state of the service on GONZOSPC.


Client Revision Information

Our simple service had very little data in its synchronizable state. A service will typically have a much richer set of data. While a set of packed RPCs, along with the ability to pass streams as RPC parameters, are a very flexible means to cope with diverse sets of data, some data sets may be so large that it is desirable to minimize the amount transferred.

Typical data sets that fall into this category include data that is acquired over a period of time, but has to be retained. The classic example of this is alarm history data. A user may wish to display such data on a client machine at any time. The programmer is left with an unenviable choice:

  1. Transfer all data during service synchronization. This lengthens synchronization times significantly and becomes impractical if many clients are attempting to synchronize concurrently. It has the advantage that, after synchronization, response times to user requests are short, as the data is local to the client.
  2. Leave all the infrequently accessed data on the server. This avoids the lengthy synchronization times, but gives a poorer response time to user requests to access such data.

RPC Manager provides support for a compromise between the two extremes, by transferring only that part of the data that the client doesn’t have. Initially, the client has to be passed the entire set of synchronizable data, but subsequent synchronizations are much briefer, as only the data that the client doesn’t have is transferred. Such an arrangement implies that the client can retain the bulk of the synchronizable state on non-volatile storage.

You may have noticed that the GetServerChanges() module that was developed in the Simple service example did not make any use of its first parameter, the RevisionInfo parameter. That parameter is a stream which RPC Manager obtains by calling GetClientRevision() on the synchronizing client.

GetClientRevision() is provided by the service code and RPC Manager passes in a reference to a variable which it expects to be set to the stream of client revision information. The contents of the stream is entirely service specific and contains whatever revision information is appropriate for the service to represent the latest data that the client instance has. RPC Manager places no interpretation on the contents of the stream. Typically, GetClientRevision() will populate the stream with one or more VTScada timestamps.

<
{======================== GetClientRevision ==================================}
{=============================================================================}
GetClientRevision
(
  RevisionRef                   { Reference to revision information           };
)

Only [
  If 1;
  [
    *RevisionRef = BuffStream("");
    {***** Populate the stream with a single timestamp *****}
    SWrite(*RevisionRef, "%5b", LastKnownTimeStamp);
    Return(Invalid);
  ]
]

{ End of GetClientRevision }
>

It then becomes the server instance’s responsibility to utilize the information within the RevisionInfo parameter to GetServerChanges() to generate the correct RPC package to bring the client up to date with the server.

GetClientRevision() is launched by RPC Manager on the service thread. Note that this module can be either a subroutine, returning Invalid, or a launched module that slays itself when complete. In the example above, we have chosen to make it a subroutine module.


Client Changes

There is one more method that a service can provide that RPC Manager uses during synchronization - GetClientChanges(). In the same way that the server instance builds an RPC package for execution on a client instance, the client instance can provide an RPC package for execution on the server. The RPC package from the client is executed after GetServerChanges() has been called. This ensures that any changes that result from the client instance’s RPC package being executed are not reflected in the RPC package generated by the server instance. Any changes in the synchronizable state of the service that result from executing the client instance-provided RPC package will cause normal service RPCs to be made to update all client instances.

It is uncommon for this facility to be required, however there are some circumstances in which it is necessary. The usual reason is where the client instance can operate independently from the server instance, if it loses the ability to communicate with the server instance.

It is essential for SetSyncComplete() to be called by the server instance, in the process of executing the RPC call stream that the client instance generated, just as it was essential for the client instance to call SetSyncComplete() during execution of the server generated RPC package. Once again, SetSyncComplete() can be called either by the last RPC subroutine in the package or the SetSyncComplete() can be embedded within the package.

The latter technique enables the RPC subroutines to be used other than for purely synchronization, by not embedding the SetSyncComplete() in an RPC subroutine. The following code demonstrates this:

<
{============================== GetClientChanges ===========================}
{ This module returns the changes seen on the client since the server was   }
{ last connected.                                                         }
{===========================================================================}
GetClientChanges
(
  PtrPackStream               { Pointer to var to receive changes           };
)

[
  Stream                      { Stream of changes to go to client           };
]

Only [
  If 1;
  [
    Stream = \RPCManager\PackRPC(Stream, "SomeRPC" { module },
                                 SvcName { scope  },
                                 { Parameters: } 69);
    Stream = \RPCManager\PackRPC(Stream, "SetSyncComplete" { module },
                                 "RPCManager" { scope  },
                                 { Parameters: } SvcName, Invalid, 1);
    *PtrPackStream = Stream;
    Slay(Self, 0);
  ]
]

{ End of GetClientChanges }
>

RPC subroutines that have a need to know whether they are being called via RPC or directly can determine this by comparing the current thread name against the name of the RPC Manager thread, as follows:

  IfThen (ThreadName(Self()) == "RPC",
    { Running on the RPC Manager thread }
  );

Related Functions:

GetServerChanges

SetSyncComplete

PackRPC


Read and Write Locks

The simple service that we have developed has the luxury of being able to acquire its synchronizable state within one script in the service instance. This guaranteed that the synchronizable state could not change while it was being acquired for transmission to the synchronizing client. After the SetDivert() call has been made, the service can modify the synchronizable state, safe in the knowledge that updates for the synchronizing client will be held in abeyance until the client has processed the RPC package.

However, if it is not possible to acquire the synchronizable state within a single script, some form of semaphore is going to be required, to hold the service off from modifying the synchronizable state until it has been sampled. Such a situation may arise if part of the synchronizable state was held on non-volatile storage, or if the VTScada statements needed to acquire the synchronizable state could not be used in a script.

RPC Manager provides such a semaphore and maintains one per service instance. The semaphore provides two types of "lock" which can be requested and acquired, a "Write" lock and a "Read" lock. These behave according to the following two rules:

  • Any number of Read locks may be granted simultaneously but they will not be granted if a Write lock exists.
  • Only one Write lock may be granted at a time and it will only be granted if there are no Read locks.

The idea is that a service module that wishes to examine the synchronizable state requests a Read lock, whereas a service module that wishes to modify the synchronizable state requests a Write lock. This enables many service modules to concurrently examine the service data without fear of it changing.

RPC Manager automatically acquires locks for a service during the synchronization process, as follows:

  • A Write lock is obtained on the client at the start of service synchronization. It is released when SetSyncComplete() is called on the client or when the synchronization process is aborted by RPC Manager, due to communication failure with the server instance.
  • A lock is obtained on the server immediately before GetServerChanges() is called. If the client instance provided an RPC package, a Write lock is obtained, otherwise a Read lock is obtained. The lock is released when the client has processed the RPC package from GetServerChanges() and the RPC package from the client instance (if any) has been processed, or when the synchronization process is aborted by RPC Manager, due to communication failure with the client instance.

Note that if you choose to use locks, you must be very careful to protect all methods which access the synchronizable state by the correct locking call:

    \RPCManager\ReadLock(&Ready, SvcName);
    \RPCManager\WriteLock(&Ready, SvcName);

Both lock calls require a reference to a variable as their first parameter. The variable value will be set to one when the lock has been obtained. The service name is passed as the second parameter. To release the lock, simply stop, or slay, the ReadLock() or WriteLock() instance that the above statements are running.


Synchronization Sequence

Putting together all the parts above, the full synchronization sequence is:

  1. RPC Manager obtains a Write lock on the client.
  2. When the Write lock has been obtained, RPC Manager launches GetClientRevision() on the client, into the service scope and on the service’s thread.
  3. RPC Manager launches GetClientChanges() on the client, into the service scope and on the service’s thread. This is done after 2, but RPC Manager does not wait for GetClientRevision to complete before launching GetClientChanges().
  4. RPC Manager then waits for both GetClientRevision() and GetClientChanges() to terminate, by slaying themselves or returning Invalid and then sends the client revision and changes streams to the server.
  5. RPC Manager, on the server, obtains either a Read or a Write lock, depending on whether there is a client changes stream.
  6. When the lock has been obtained, RPC Manager, on the server, atomically starts buffering service RPCs for the service and launches GetServerChanges().
  7. When GetServerChanges() calls SetDivert(), the buffered service RPCs are released for processing and service RPCs destined for the synchronising client start buffering.
  8. When GetServerChanges() terminates, by slaying itself or returning Invalid, RPC Manager queues the RPC package from GetServerChanges() for transmission to the client. If an RPC package was received from the client, RPC Manager, on the server, now processes that call package, calling the RPC subroutines within the package and then waits for SetSyncComplete() to be called on the server.
  9. RPC Manager, on the client, executes the RPC package from the server and waits for the client service instance to call SetSyncComplete(). When this is called, the client instance is marked as ready and the Write lock, obtained in 1, is released.
  10. When the server sees the client instance marked as ready (and 7, above, has completed), any buffered RPCs from the service for that client are queued for transmission to the client and synchronization terminates, clearing the Read or Write lock, obtained in 5, above.


Alternate Status

The prioritized list of servers that are specified in a configuration file contains sufficient information to determine what to do when communication between servers or between servers and clients fails. This could be due to failure of the communications medium or failure of the software on a machine (perish the thought) or failure of the computer hardware.

There may, however, be good reason to be able to inform RPC Manager of the health of a service. Typically, this will be where a service has to communicate to, or use, some third-party equipment. The service will need to indicate that it is, or is not, capable of performing the functions that it was designed for. A driver may typically use this facility to show its ability to communicate with a PLC.

This is achieved by setting or clearing the Alternate status of the service. RPC Manager monitors the Alternate setting to determine the most suitable service instance for the service. The rules by which server status is determined are described in the section on Server Evaluation Rules.

Related information:

Server Evaluation Rules


Sticky Status

A service can indicate to RPC Manager that server status is to "stick" with the machine that currently has server status for that service, rather than migrating server status to the highest ranking available server machine. This feature is of use where to change over to another machine carries an unacceptable penalty. For example, a service that communicates with some external equipment may have to drive signals or issue protocol to perform a physical changeover of communication routing equipment. The system designer may wish this to only happen infrequently.

A service is configured to be sticky by specifying a "Sticky" setting in the Servers.XML file, as in the following example, which specifies the Sample service as sticky:

<?xml version="1.0"?>
<RPC>
<ServiceSettings>
<Service Name="Sample">
<Setting Name="Sticky">1</Setting>
</Service>
</ServiceSettings>
<ServerLists>
<Service Name="Default Server Lists">
<Workstation Name="Default for Workstations">
<Server>FREDSPC</Server>
</Workstation>
</Service>
<Service Name="Sample">
<Workstation Name="Default for Workstations">
<Server>FREDSPC</Server>
<Server>JOESPC</Server>
<Server>GONZOSPC</Server>
</Workstation>
</Service>
</ServerLists>
</RPC>

If the Sticky setting is set to other than its default of zero, the service becomes a "sticky" service. If a sticky service instance that is the current server wishes to yield server status, it should set alternate status, see section Alternate Status. This will cause immediate migration of server status to the highest available server. The rules by which server status is determined are described in the section on Server Evaluation Rules.


Preventing Synchronization with Lower Order Servers

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Services > Synchronization Sequence > Preventing Synchronization with Lower Order Servers

Preventing Synchronization with Lower-Order Servers

There are some unusual circumstances where you may not wish a higher-order service instance to synchronize with a lower-order service instance that holds server status. Typically, one machine would be regarded as holding the master set of service data, regardless of whether a service instance was running on that machine or not. VTScada Security Manager is just one such service.

When initializing or on change of server, servers of a lower-order than the current server will synchronize with the current server. Servers of a higher-order than the current server will not synchronize with the current server.

To achieve this, the service must pass a valid non-zero value in the PrioritySync parameter to the \RPCManager\Register call, see section Service Control Methods.

This does not change the server evaluation rules or the synchronization sequence. It merely prevents synchronization to a lower-order server.


Server Evaluation Rules

The rules by which the server is determined encompass the prioritized list of servers specified in the application’s configuration, whether a service instance is synchronized, the Alternate status of a service instance and the Sticky status of a service instance.

Note that, in the rules that follow, the phrase "available service instance" means that a service instance has been registered and, if necessary, synchronized.

  1. When a service registers with RPC Manager, it defaults to having its Alternate status clear. The prioritized list of severs is read from the application’s configuration.
  2. If a service instance sets itself into Alternate status the next available service instance that is not Alternate, down the prioritized list, is selected as the server for that service.
  3. If all the service instances are in Alternate status, they are all forced out of Alternate status, except the service instance that was the most recent server, which remains in Alternate status. The highest priority available service instance is selected as the server.
  4. If a service instance clears its Alternate status (or has it forcibly cleared by 3) then it is selected as the server only if there are no higher priority service instances available.
  5. If there are no available service instances, the highest priority registered, but not synchronized, service instance is selected as the server.
  6. If the selected server is not the current server and the current server is not a "sticky" server, the current server is demoted from server status.
  7. The selected server is promoted to be the current server.
  8. If there is only one server on the prioritized list for the service, neither Alternate status nor Sticky has any effect.


RPC Call Backs

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Services > RPC Call Backs

RPC Call-Backs

Certain events that happen within the lifetime of a service instance may be of interest to the service instance or to the application as a whole. RPC Manager looks for the existence of a module called RPCServerNotice() in the service code and in Code for the application. If it finds such a module, it is called, as a subroutine when the following events occur and with the listed notification code, supplied as a parameter:

Notification Code | Reason
\RPCManager\#RPCCallbackRegistered | The local service instance has registered with RPC Manager.
\RPCManager\#RPCCallbackSessionClosed | A session with a remote service instance has been disconnected. The disconnection may or may not be the result of application shutdown..
\RPCManager\#RPCCallbackSessionOpen | A session with a remote service instance has been established.
\RPCManager\#RPCCallbackUnRegistered | The local service instance has unregistered with RPC Manager.
\RPCManager\#RPCCallbackSocketOK | A connection to a remote machine has been established (Code call-back only).
\RPCManager\#RPCCallbackSocketLost | A connection to a remote machine has been lost (Code call-back only).
\RPCManager\#RPCNewSessionData | A session table has been received from the remote system - this is synonymous with a socket connection being established. The RPC session tables will not yet be set up, so use of this call-back should be restricted to detecting a new connection.

RPCServerNotice() is called with the following parameters:

RPCServerNotice(NotifyCode, IP, Name, LocalIP, LocalName, WorkstationName, ShortName, SameAsLast);

Where:

NotifyCode | One of the codes listed above.
IP | The IP address of the remote machine. For codes #RPCCallbackRegistered and #RPCCallbackUnRegistered this value is undefined.
Name | The name of the remote machine. For codes #RPCCallbackRegistered and #RPCCallbackUnRegistered this value is undefined.
LocalIP | The IP of the local machine. On a multi-homed network this could be any of the legal IP addresses by which this machine is known.
LocalName | The name of the local machine.
WorkstationName | The name of the local machine, as determined by a WkStaInfo(0) statement. This is normally the same as the previous parameter.
ShortName | Valid for Code call-backs for service instance related events only. The name of the service to which the event relates.
SameAsLast | Valid for Code call-backs for service instance related events only. Non-zero if this notification is not the same as the previous notification for the same machine.


Connection Configuration and Management

This section describes how RPC Manager maintains the inter-machine connections in a distributed system. It is provided as an understanding of the sequence of operations in RPC Manager makes for easier configuration and diagnosis of problems.


Link Maintenance Cycle

A machine will not attempt to open a connection to another machine until it has a reason to do so:

  1. A service instance has registered and needs to communicate to a machine.
  2. A directed RPC is made to the remote machine.
  3. RPC Manager is explicitly requested to open a connection to a machine.
  4. The remote machine initiates communication, due to one of the above reasons.

When a connection is to be established for the first time, RPC Manager creates a MachineNode to oversee communication with the remote machine and one or more SocketNodes to maintain the raw socket stream connection between the machines.

The SocketNodes maintain the communication pathways between the MachineNode at either end of the link and report status changes to their owning MachineNode. The MachineNodes for the various interconnected machines report status changes that they cannot transparently manage to the Code level RPCServerNotice(), (see the section RPC Call-Backs), and to the TagNodes that are using them. TagNodes use these events in their driving of service instances.

SocketNode\SocketOpen will, initially, be Invalid. The SocketNode will aggressively try to establish a socket stream connection with a SocketNode on the remote machine up to the number of times specified in the RPCSktConnectAttemptMax system configuration setting, before deciding whether to mark the SocketNode open or not. If it fails to obtain a satisfactory connection within this number of attempts, SocketNode\SocketOpen is marked as closed (0) and MachineNode informed.

After a socket stream has been opened, SocketNode interrogates the stream to get detailed network information. It then marks the SocketNode open (SocketOpen>0) and informs MachineNode.

Session management information is now retrieved from MachineNode and transmitted to the remote MachineNode. When the MachineNodes first successfully exchange session management information, each of the two MachineNodes is marked as open (MachineNode\SocketOpen > 0). At this point, "pinging" is initiated down the socket stream. A "ping" is just a "keep-alive" transmission that elicits no response from the other end. Pings are very efficient and are only sent if there has been no other communication activity on the socket stream for the number of seconds defined in the RPCPingInterval system configuration setting.

If no activity is observed on a socket stream for the number of seconds defined in the RPCReconnectTime system configuration setting, the SocketNode terminates the socket stream and attempts to open another one. Once again, RPCSktConnectAttemptMax attempts are made at establishing a connection during the connection establishment process, as described above.

If, after RPCReconnectTime expired, no connection can be established within the number of seconds defined in the RPCSocketDeadTime system configuration setting, any sessions which the MachineNode has with applications running on the remote machine are terminated and their session IDs set to RPC_NO_SID. The session IDs will be set to new values when the session tables are re-built after a connection is re-established with the remote machine.

MachineNode will attempt to transmit RPCs to the remote machine while it is marked as open. Each RPC transmitted receives positive acknowledgment of its receipt. Failure to receive this acknowledgment within the number of seconds defined in the RPCResendDelay system configuration setting causes MachineNode to resend it. There will be a maximum of RPCSktResendAttempts to transmit the RPC successfully. If, after these retries, the RPC has still not been acknowledged, the socket stream is terminated and SocketNode goes through its link re-establishment cycle, as above.

All RPCs carry with them an identification that prevents a re-transmitted RPC from being executed if it was received and executed, but the acknowledgment was lost.


Link Tolerances

When two machines connect, the response time from one machine to another can be variable, partly due to CPU loading, but mostly due to link throughput limitations. To address this, a set of link "tolerances" can be specified in the SETUP.INI file. The tolerances are only applied to the RPCResendDelay, RPCReconnectTime and RPCPingInterval settings. The RPCPingInterval is only affected on the receiving machine when it is used to calculate the connection timeout.

A "tolerance factor" is specified as a percentage value, so a tolerance factor of 100 is unity, 300 is 3 times the value and 50 is half of the value.

This enables the specification of a base, system default, set of values and tolerances for each peer-to-peer connection that requires them.

It is desirable to be able to specify the settings for an entire system in one file [SETUP.INI], which can then be installed on all machines in the system.

Regardless of whether all machines have been given a copy of the same Setup.INI file, it is extremely important that all machines share the same set of link tolerance assignments.

This is achieved by having an INI file section heading which identifies a particular machine or IP interface in the system and having all the tolerance settings [for other machines with which that machine can communicate] specified as entries within the section. There are, however, a number of variations in how this is specified. On a system consisting entirely of single homed machines, "LinkTolerance-Name" [where name is a workstation name, as returned by WkStaInfo()] is sufficient to uniquely identify the network pathway from that machine to other machines. For multi-homed systems, it may be necessary to use "LinkTolerance-IP" [where IP is the IP of a network interface] to identify tolerances for different network pathways between two machines.

To resolve ambiguity and provide flexibility, each machine uses the following methods to extract the tolerance setting from this .INI file, when a connection is established. The rules are performed in the order listed:

  1. A search is made for a section [LinkTolerance-LocalIP], where LocalIP is the IP of the local machine. If found, that section is searched for the IP of the remote machine. If the IP of the remote machine is not found, the section is searched for the name of the remote machine.
  2. If 1 did not produce a tolerance, a search is made for a section [LinkTolerance-LocalName], where LocalName is the name of the local machine. If found, that section is searched for the IP of the remote machine. If the IP of the remote machine is not found, the section is searched for the name of the remote machine.
  3. If 2 did not produce a tolerance, a search is made for a section [LinkTolerance-RemoteIP], where RemoteIP is the IP of the remote machine. If found, that section is searched for the IP of the local machine. If the IP of the local machine is not found, the section is searched for the name of the local machine.
  4. If 3 did not produce a tolerance, a search is made for a section [LinkTolerance-RemoteName], where RemoteName is the name of the remote machine. If found, that section is searched for the IP of the local machine. If the IP of the local machine is not found, the section is searched for the name of the local machine.
  5. If 4 did not produce a tolerance, a search is made for a section [LinkTolerance-LocalIP], where LocalIP is the IP of the local machine. If found, that section is searched for an entry called "Default".
  6. If 5 did not produce a tolerance, a search is made for a section [LinkTolerance-LocalName], where LocalName is the name of the local machine. If found, that section is searched for an entry called "Default".
  7. If 6 did not produce a tolerance, a search is made for a section [LinkTolerance-RemoteIP], where RemoteIP is the IP of the remote machine. If found, that section is searched for an entry called "Default".
  8. If 7 did not produce a tolerance, a search is made for a section [LinkTolerance-RemoteName], where RemoteName is the name of the remote machine. If found, that section is searched for an entry called "Default".
  9. If 8 did not produce a tolerance, default to 100% of the tolerances.

Note that this procedure is only carried out the first time that a connection is established between two machines.

The "Default" setting within the sections allow you to specify a default tolerance for all connections from the machine or interface identified in the section header. This can significantly reduce the maintenance overhead of these tolerance sections.

For example:

[LinkTolerance-192.168.5.42]
Default = 200

[LinkToleance-GONZOSPC]
192.168.5.50 = 300
Default = 150
JOESPC = 100

This will cause machine 192.168.5.42 to have a 200% tolerance of all machines connected to it. GONZOSPC will have a 300% tolerance of machine 192.168.5.50, a 100% tolerance of JOESPC and a 150% tolerance of all other machines.

Note that these settings are specified in SETUP.INI and not in service configuration files.

You use workstation names other than IP addresses whenever possible, especially in networks where the workstations may be dual-homed, or where dynamic IPs are assigned. Because workstation names are unique, it is good practice to condition yourself to use workstation names, rather than IP addresses, even if your system configuration does not require the use of workstation names.


Multi homed Systems

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Connection Configuration and Management > Multi homed Systems

Multi-homed Systems

RPC Manager will take advantage of multiple network interfaces on a machine. Each network interface must have its own IP address.

There are two reasons why you might want to use a multi-homed system:

  1. To improve the tolerance of the distributed system to network failures.
  2. To separate the SCADA system network usage from a network used by business systems. The usage of a network by business systems can be quite unpredictable and dedicating a network to the SCADA and associated control systems may be prudent.

These two justifications have an area of overlap, in that the VTScada distributed system can see all networks connected to it, regardless of purpose.

Through configuration parameters, you can configure RPC Manager to use the available networks in two ways:

  1. Prioritized. The available networks are arranged in an order of priority. RPC Manager always uses the highest priority available network. This could be used for either of the above two scenarios.
  2. Round-Robin. All network interfaces are treated equal and RPC Manager traffic is sent using each interface in turn. This could only be used for scenario 1 and is the default behavior.

The two methods can be combined, where there are three or more networks, such that one of the networks could be prioritized and the other two left as round robin. RPC Manager traffic will always be sent over the prioritized network first, using the remaining two networks in round-robin mode if the prioritized network link to a machine fails.

For example:

[RPCManager-NetPriority]
IP = 192.168.1.0/24
IP = 192.168.2.0/24

Each line of the "RPCManager-NetPriority" section specifies an IP mask, of the form:

<IP address>/<number of bits>

such that the number of bits specified is applied to the IP address from the most significant end. A mask value of 24 specifies the first three numeric parts of the IP address (8-bits per number), a mask of 16 the first two numeric parts and so on.

The example above specifies that IPs on subnet 192.168.1 are to be given priority over IPs to the same machine on all other subnets. Likewise, IPs on subnet 192.168.2 are to be given priority over IPs to the same machine on all other subnets, except subnet 192.168.1. If an IP on subnet 192.168.1 becomes unusable, the corresponding one on subnet 192.168.2 will be used. If that also fails, any remaining IPs on other subnets will have RPCs transmitted to them in round-robin fashion.

Related information:

GetSubnetPriority

SetSubnetPriority

GetPreferredSubnet

GetLastUsedSubnet


Clients of Clients

It is common sense that a service instance should always see the same prioritized server list as all other service instances in the system, otherwise unexpected results may occur. However, it is deliberately possible to configure the distributed system in such a way that one (or more) machines can see different server lists. Such a situation may arise if a Remote Access Service (RAS) were to be configured so that the RAS client did not have free access to the LAN on which the distributed system is running. This may be desirable for security purposes, especially if the RAS connection is a dial-up.

In such a case, it is necessary to configure VTScada running on the RAS client as having the RAS server as its sole server instance. RPC Manager will synchronize the service instances running on the RAS client to those running on the RAS server. However, individual services may not provide full support by, for example, not broadcasting updates recursively to clients.

If the machine that is acting as both client and server is obliged to re-synchronize with its server, all its clients will be forced to re-synchronize with it, after it has synchronized with its server.

Related information:

See the Configuration section for details on how to configure this.


WANs

Wide area networks (WANs) are supported indirectly, by the operating system support provided at the network interface level. The primary considerations when having a distributed system operating in a wide area domain are:

  1. There will be reduced throughput and increased latency.
  2. Security measures, e.g. firewalls, are in common use. Network administrators must open up the port required by RPC Manager for this to function. The port required is set in RPC Manager configuration, (see Configuration)


Cross Application RPC

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Cross Application RPC

Configure Cross-Application RPC

This section discusses how cross-application RPC works and the modifications you will need to make to your application to achieve this.

Each application has it’s own Globally Unique Identifier (GUID), which is generated by VTScada when the application is created and is stored in the Settings.Startup file in the application directory.

In the scope of Code, the VTScada loader creates two variables for your application, LocalGUID and RemoteGUID, both of which are preset to the application GUID. As you will see from the Application Control of Servership

In normal operation, RPCManager controls which service instance is currently the server for a service. The system is simply configured to instruct RPCManager how its servership control algorithms should operate.

In rare cases, it may be necessary to control the servership of one or more services by the application itself. Consider, for example, a system where maintenance of the system is necessary while the application is running. For operational reasons, the system owners do not want a number of key services to have servership held by the machine undergoing maintenance, but do want the application to be running.

In such circumstances the application needs to either be able to disable a particular machine from owning servership of the key services or, more generally, be able to control which machine is the server for those services. More complex situations could arise where, for example, a specific machine does not want to be considered a candidate for servership.


Cross Application Services

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Cross Application RPC > Cross Application Services

Cross-Application Services

While cross-application RPC can be achieved between script applications it is in standard applications that it is most useful. In standard applications, RPCs are performed between services. In cross-application RPC in standard applications, services of the same name in different applications are maintained in synchronization.

One application houses the master service and the other applications house the slave services. The application housing the service with identical RemoteGUID and LocalGUID variables is the master. All other applications house slaves. There can be many different applications housing slaves, but only one application housing the master.

This terminology (master and slave) has been selected to try and avoid confusion between the terms server and client. In cross-application RPC, we define the term "server" consistently with non cross-application services, as being the only service instance that has servership of the service. By definition, this is the master service.

Therefore, exactly one instance of the master service can be a server. All other instances of the master service are clients. All instances of the slave services are clients to the current master service server. This is depicted in the following diagram, where each arrow points to the server instance.

Each application has a service named "Service 1" and a service named "Service 2". These two services are completely independent between the applications, i.e. Application A’s Service 1 has no relationship with Application B’s Service 1. Service Sample, however, is a cross-application service. Application A houses the master service. Application B houses a slave service. Application A on machine FRED is the current server instance of this service. If you were to stop Application A on machine FRED, servership of Application A would transfer to machine JOE (on the assumption that the server list for all Application A services is FRED, followed by JOE). Application B’s Sample service will follow the master service and both application B’s Sample service instances will become clients to Application A’s Sample service on machine JOE.

Note that Application B’s Sample service can not be a server instance, hence the term "slave".

Related information:

Cross-Application Service Variations - alternative arrangements.

CurSourceAppGUID - for the rare case where the master (or a slave) needs to know which application is making an RPC to it.


Cross Application Service Variations

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Cross Application RPC > Cross Application Service Variations

Cross-Application Service Variations

You can have many applications which house a slave service, for example, application A can house master service Sample. Applications B, C and D can all house slave services of Sample.

You can also have "slaves of slaves", in a similar manner to "clients of clients", the primary difference being that, because the slaves are in separate applications from the master, they can exist on the same machine (but don’t all have to).

To configure a "slave of a slave" configure an intermediate application service instance (the slave) to be the master for a second application. For example, if application A (GUID GA) houses the master service Sample, application B (GUID GB) houses a slave service Sample and application C (GUID GC) houses the slave of slave Sample, then create a RemoteGUID variable in service Sample of application B and set it to GUID GA and create a RemoteGUID variable in service Sample of application C and set it to GUID GB. Now, B’s Sample service will synchronize with and follow the server of application A’s Sample service and C’s Sample service will synchronize with B’s Sample service.

Beware that this can become complex. Consider the following example, in which three machines (FRED, JOE and BOB) each have an instance of applications A, B and C. Application A houses the master service, application B houses the slave service and application C houses the slave of slave service. Assume, also, that the server lists for the service have been configured FRED, then JOE for machines FRED and JOE, but only JOE for machine BOB (i.e. BOB is a client of a client):

Once again, the arrows point to the server instance of each service. Note that, because the slave services cannot be servers, they can only follow their master server location. For application B, the master is housed in application A and so, therefore, all application B slave services will have the current application A server as their current master. Because application B’s service instance can not be a server status (rather it is a master to application C’s slave service) all application C slaves regard the application B on the same machine as their master.

Be clear about this distinction between server and master: A server instance of a service has an RPCStatus (a pointer to which is returned from the register call) of server(2). A master instance of a service may have an RPCStatus of server(2) OR client(1), depending on whether it is server. A slave can not have an RPCStatus of server(2). Any instance can have an RPCStatus of unknown(0).


Revised Code Example

This section will show you how to create a simple cross-application service based on the Sample service created in an earlier section.

First, create a new standard application and copy the sample service code, developed earlier in this document into the new application. Compile this and make sure that it works.

You now have two identical applications, each of which has a different application GUID (look in the Settings.Startup file in each application directory to verify this). We will now change the second application so that the "Sample" service works cross application.

Add a RemoteGUID variable to the SampleService declarations.

{============================= SampleService ================================}
{ This service maintains a simple synchronizable state and properly supports  }
{ all entry points required by RPC Manager for correct operation.           }
{============================================================================}
[
  .
  .
  .
  RemoteGUID                    { GUID of the master application            };
  .
  .
  .
]

Set the RemoteGUID variable to the application GUID of the first application. Do this before calling \RPCManager\Register. Note that the binary form of the GUID is used. You can obtain the GUID from the first application’s Settings.Startup file.

Init [
  If 1 Main;
  [
    RemoteGUID = GetGUID(1{bin}, "e7a82aa4-21b2-4303-b7d7-1d66353dab35");
    {***** Register the sample service with RPC Manager. *****}
    RPCStatus    = \RPCManager\Register(SvcName, Invalid, Invalid,
                                        Invalid, \RPC_SYNC_MODE);
  ]
]

Use the fourth parameter to GetServerChanges. This is only required if you are doing x-app RPC. It is the GUID of the application that is synchronizing to the master service instance. This parameter must be called RemoteGUID (case insensitive), so that PackRPC and SetDivert will pick it up and work correctly.

<
{=================== GetServerChanges ==============================}
{ Called by RPC Manager during startup sync, on a server, to get the package of RPCs which create a synchronizable state on the client which is in step with the server. }
{===================================================================}
GetServerChanges
(
RevisionInfo { Revision info from GetClientRevision call
made on synchronizing client - unused here };
PackStreamRef { Pointer to var to receive changes };
ClientName { Name of client };
RemoteGUID { The GUID of the app synchronizing to me };
)

The Sample service in your second application is now a slave and will remain as a synchronized client to the master Sample service in your first application.

Related information:

Programming Example: Create a Simple Service


CurSourceAppGUID

The principle of having a service in a second application be a slave to the first application can be extended to as many applications as you wish, i.e. One master service can have slaves in many different applications. It is unusual for the master (or a slave) to need to know which application is making an RPC to it. However, for those occasions when this is needed, RPC Manager provides a variable called RPCManager\CurSourceAppGUID, which contains the binary GUID of the application that sourced the current RPC. Like all the other RPCManager\Cur*** variables, it is valid only for the duration of the RPC subroutine call.


Application Control of Servership

In normal operation, RPCManager controls which service instance is currently the server for a service. The system is simply configured to instruct RPCManager how its servership control algorithms should operate.

In rare cases, it may be necessary to control the servership of one or more services by the application itself. Consider, for example, a system where maintenance of the system is necessary while the application is running. For operational reasons, the system owners do not want a number of key services to have servership held by the machine undergoing maintenance, but do want the application to be running.

In such circumstances the application needs to either be able to disable a particular machine from owning servership of the key services or, more generally, be able to control which machine is the server for those services. More complex situations could arise where, for example, a specific machine does not want to be considered a candidate for servership.


RPCManager API

Rather than adding new algorithms to RPCManager to cope with individual situations, an RPCManager API exists that enables application provided code to control servership. The API consists of three methods:

  • ForceServers
  • GetInhibitedServiceList
  • GetInSyncServers

These API calls are described in the Service Control Methods section.

A higher-level interface still is provided by the VTScada layer. The service ServiceCtrl drives these RPCManager APIs and provides the ability for an OEM or application layer plug-in to be provided which simply determines who should be server.

Related information:

API Reference

Related Functions:

ForceServers

GetInhibitedServiceList

GetInSyncServers


VTScada Plug In API

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Application Control of Servership > VTScada Plug In API

VTScada Plug-In API

The plug-in must be named ServiceCtrlLogic and is automatically launched (on the application thread) and attached to the ServiceCtrl service when the VTScada application starts.

ServiceCtrl provides an interface that the ServiceCtrlLogic may use. The interface consists of a number of useful variable and constants defining a structure that holds the current server states:

  ServerStates                  { Structure holding server states             };
  Trigger = 0                   { Boolean - TRUE on ServerStates change       };
  RPCStatus                     { Current RPC status of ServiceCtrl           };
  ServiceName = "ServiceCtrl"   { Service name                                };
  RPCScopeName = "ServiceCtrl"  { RPC scope name (must match AppRoot decl)     };
  LogicObj                      { Instance of the ServiceCtrlLogic module     };

  {***** Indices into the ServiceState structure.
         The structure is held as an array, with row #SST_NAME being the
         service names and row #SST_STATES being arrays of a sub-structure.
         The sub-structure is an array with row #SST_SS_SERVER being the
         server name and row #SST_SS_STATE being the server state.     *****}
  Constant #SST_NAME = 0        { Service name                                };
  Constant #SST_STATES = 1      { Array of server/states                      };
  Constant #SST_NUMELEMENTS = 2 { Keep one bigger than the max above          };
  Constant #SST_SS_SERVER = 0   { Server names                                };
  Constant #SST_SS_STATE = 1    { Server states                               };
  Constant #SST_SS_NUMELEMENTS = 2 { Keep one bigger than the max above       };

Fundamental to the plug-in logic is an understanding of the ServerStates structure. Essentially, ServerStates is a 2D array with each element of row [#SST_NAME] holding the service names and each element of row [#SST_STATES] holding an array. ServerStates is initialized from the inhibited service list, from RPCManager. There is therefore one column for each service under application control.

Each element of row [#SST_STATES] is also a 2D array, with each element of row [#SST_SS_SERVER] holding the ordered list of servers, highest listed first. Each element of row [#SST_SS_STATE] is initially Invalid. It is the responsibility of the plug-in to maintain this row with the servership state of the service on the corresponding server.

A diagram may help here:

The plug-in must provide an InitializeState subroutine that gets called, in a CriticalSection, when the ServiceCtrl service instance becomes server. It must populate the ServerStates structure's #SST_SS_STATE elements to reflect the servership states for the service. Only one element for each service may be set to \#RPCServer. All others must be set to \#RPCClient. Failure to observe this precaution will result in unpredictable behavior in the services being controlled.

The plug-in is at liberty to change these element states at any time, but has to do so in a CriticalSection, to avoid race conditions with RPCManager. After setting them it must set ServiceCtrl’s Trigger variable to 1.

If the plug-in wishes to make an RPC call to other service instances of itself (inside the ServiceCtrl service), it can use the expression Concat(\RPCScopeName, "\LogicObj") as the RPC call scope and \ServiceName as the name of the service in which to make the call.


Service Synchronization

ServiceCtrl is an RPC service. It is therefore subject to normal RPCManager service synchronization rules. To this effect it provides a GetServerChanges method, to be called by RPCManager during service synchronization. This is extended into the ServiceCtrlLogic plug-in via two subroutine methods that the plug-in can provide:

  • StartGetServerChanges(). This is called in a CriticalSection at the start of GetServerChanges, allowing the plug-in to pack any RPCs is wishes to have executed during synchronization, before any RPCs that ServiceCtrl may generate as part of its synchronization package. StartGetServerChanges is expected to return a stream of packed RPCs, with the current stream pointer at the end of stream. If no RPCs are packed, StartGetServerChanges must return Invalid.
  • EndGetServerChanges(Stream). This is called in the same CriticalSection after ServiceCtrl has packed any RPCs it wishes into the supplied stream. The stream is positioned at end of stream. The plug-in can pack any RPCs it wishes into the stream and is expected to return the stream. If no RPCs are packed into the stream, EndGetServerChanges must return the stream unchanged.

ServiceCtrl will augment the stream with a SetSyncComplete call after EndGetServerChanges has returned.


System Level Services

A system level service is an RPC service whose execution scope lies within the system library (i.e. the root of VTS), rather than within an application. System level services are therefore started when VTScada starts, rather than when an application starts and remain running until VTScada is closed down.

System level services can be used to provide a service that is common to many applications or provide a service that does not rely on the presence of an application.

VTScada defines one such service - the VICManager service. Its function is to coordinate the management of VTScada Thin Clients across a number of computers running VTScada. It must be able to transfer and synchronize VIC server lists and application configurations regardless of whether any of those applications are running. In addition, it provides code that an application can call to obtain state information regarding VIC sessions across all configured computers and to control those VIC sessions.


Creating a System Level Service

A system level service operates identically to an application service, with the following exceptions and additions:

  • It cannot use an application GUID. Instead the system-level GUID must be used. This is an all-zero GUID and is pre-declared in RPCManager\SystemGUID.
  • The service must define local variables RemoteGUID and LocalGUID. These must be preset to RPCManager\SystemGUID.
  • The service must either provide its own configuration file or use a section in the system SETUP.INI file.
  • If the service requires RPC call-backs (see section RPC Call-Backs) it must insert into the array in \ServiceList the object value of the scope in which the call-back method (RPCServerNotice) can be found, for example:
    {***** Insert myself into the system-level service list *****}
    ServiceList = InsertArrayItem(ServiceList, Invalid, Self());

Other than the above list, write a system-level service just as you would an application level service.


Reference

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Reference

API Reference

This section contains a reference for each method that RPC Manager provides for external use.

Some methods can be called only as subroutines, whereas some methods can be called either from steady state or as subroutines. These are clearly indicated in each function description. Calling a method that is implemented only as a subroutine from steady state will have undesirable effects. Note that a steady-state call may return Invalid for a brief time before the return value of the method stabilizes.


API for the RPC Manager

BinIP2Text | (RPC Manager Library) Returns a text representation of a specified binary IP in a printable format.
ConnectToMachine | (RPC Manager Library) This subroutine increments the usage count on the specified workstation and forces RPC Manager to attempt to establish a connection with the specified workstation if it is not already connected. Subroutine call only.
DisconnectFromMachine | (RPC Manager Library) This subroutine disconnects from a workstation by decrementing the usage count on the specified workstation and forcing the RPC Manager to attempt to establish a connection with the specified workstation if it is not already connected. Subroutine call only.
ForceServers | (RPC Manager Library) Sets the servership of an application service to a specific state.
GetAllWorkstationNames | (RPC Manager Library) Launched module that creates an alphabetically sorted list of all known workstation names. The list is not service specific.
GetClientDiverts | (RPC Manager Library) Returns a one-dimensional array of flags, indicating the divert status of each client.
GetClientGUIDs | (RPC Manager Library) Returns a one-dimensional array of the application GUIDs of the clients of the specified RPC service instance.
GetClientIPs | (RPC Manager Library) Returns a one-dimensional array of the IPs of the clients of the specified service instance.
GetClientList | (RPC Manager Library) Returns a one-dimensional array of the names of the clients of the specified service instance. Steady state or subroutine call.
GetClientMode | (RPC Manager Library) Returns a one-dimensional array of the modes of the clients of the specified service instance.
GetClientNodes | (RPC Manager Library) Returns a one-dimensional array of the object values of the MachineNodes of the clients of the specified service instance. Steady state or subroutine call.
GetClientsListed | (Obsolete - RPC Manager Library) Returns a one-dimensional array of the names or IPs of the clients that have been derived from the "-Clients" section of the service configuration file.
GetInhibitedServiceList | (RPC Manager Library) Returns a one-dimensional array of the names of all services inhibited from RPCManager servership control.
GetInSyncServers | (RPC Manager Library) Returns a one-dimensional array of the names or IPs of the potential, synchronized servers for the given service.
GetIP | (RPC Manager Library) Returns an IP address for a workstation, given its name.
GetLastUsedSubnet | (RPC Manager Library) Returns the last subnet mask or remote IP used for communication with the specified machine.
GetLocalIP | (RPC Manager Library) Returns an IP address for the local workstation that is known to the specified remote workstation.
GetLocalNumber | (RPC Manager Library) Returns the index of the local workstation down the prioritized server list for the named service. Steady state or subroutine call.
GetMachineNode | (RPC Manager Library) Returns the object value of the MachineNode for the specified name or IP. Steady state or subroutine call.
GetMakeAltPtr | (RPC Manager Library) Returns a pointer to a variable containing the Alternate status for the local service instance in the calling application for the specified service. Steady state or subroutine call.
GetPreferredSubnet | (RPC Manager Library) Returns the highest priority subnet mask for the given machine name.
GetRemoteVersion | (RPC Manager Library) Returns the version number of VTScada running on a specified workstation. Steady state or subroutine call.
GetServer | (RPC Manager Library) Returns the name of the active server for a specified service.
GetServerChanges | (RPC Manager Library) Launched by RPC Manager on a service server to obtain the service's synchronization data (i.e. called by RPC Manager during startup synchronization on a server to get the package of RPCs that create a synchronizable state on the client which is in step with the server).
GetServerMode | (RPC Manager Library) Returns the mode in which the current server for a specified service is running.
GetServerNumber | (RPC Manager Library) Returns the index down the prioritized server list of the current server for the specified service. Steady state or subroutine call.
GetServerSIDPtr | (RPC Manager Library) Returns a pointer to a variable that holds the session ID for the current server for the specified service.
GetServersListed | (RPC Manager Library) This subroutine returns a one-dimensional array of the names or IPs of the servers that has been derived from the "-Servers" section of the service configuration file.
GetServiceScope | (RPC Manager Library) Returns the service instance for a service.
GetSessionID | (RPC Manager Library) Returns the current session ID for a specified application on a workstation.
GetSocketStatus | (RPC Manager Library) Returns the connection status of either: 1) The machine node if the subnet is not valid, or 2) The socket that is on the specified subnet.
GetStatus | (RPC Manager Library) Returns a variable that holds the current service instance status for the specified service.
GetSubnetPriority | (RPC Manager Library) This module returns a full set of network priority values configured.
IsClient | (RPC Manager Library) Is Client of a Service. This subroutine returns an indication of whether a particular workstation is a client connected to a service. Returns 1 for the specified service if the specified machine is a client to the machine on which the IsClient() call is made.
IsMatch | (RPC Manager Library) Determines whether two names or IPs indicate the same workstation. This subroutine returns a "1" if the two names or IPs (any combination) refer to the same workstation.
IsPotentialServer | (RPC Manager Library) Is Potential Server for a Service. This subroutine returns an indication of whether the local workstation is a potential server for a service. Returns "1" if the local workstation can be a server for the specified service. IsPotentialServer should not be called in steady state.
IsPrimaryServer | (RPC Manager Library) Returns 1 if the local machine is connected to the primary server for the specified service.
IsServiceReady | (RPC Manager Library) Is Primary Server Active for a Service. Only available in VTS 6. This module returns an indication of whether the specified server is in synchronization with the server instance. Returns "1" if the local instance is in synchronization with the server instance.
PackData | (OBSOLETE) (RPC Manager Library) This method packs an array or set of module instance parameters into a stream.
PackParms | (RPC Manager Library) This method packs supplied parameters into a stream. Subroutine call only.
PackRPC | (RPC Manager Library) Packs an RPC call and a set of parameters into a stream. Subroutine call only.
RecommendAlternate | (RPC Manager Library) Instructs RPC Manager that the local service instance does not consider itself a good server candidate.
RecommendPrimary | (RPC Manager Library) Instructs RPC Manager that the local service instance considers itself a good server candidate.
Register (RPC Manager) | Registers a service for RPC and returns a pointer to the variable containing the current RPC status of the service.
RunPack | (RPC Manager Library) Unpacks and executes a set of RPCs from a stream constructed with PackRPC.
Send | (RPC Manager Library) This subroutine sends a message by invoking a remote procedure call.
SetDivert | (RPC Manager Library) Informs RPC Manager that the synchronization state of a service has been sampled during synchronization, and service RPCs for the specified client should be buffered until synchronization completes. Subroutine call only.
SetRemoteValue | (RPC Manager Library) This subroutine sets the specified variable within an application instance on a workstation to the specified value. Subroutine call only.
SetSubnetPriority | (RPC Manager Library) This module enables setting the network priority configuration during runtime.
SetSyncComplete | (RPC Manager Library) Informs RPC Manager that service synchronization is complete as far as the local service instance is concerned. Subroutine call only.
TextIP2Bin | (RPC Manager Library) Returns the Binary representation of the specified IP.
UnpackData | (RPC Manager Library) This method unpacks a stream into an array or set of module instance parameters. Subroutine call only.
UnpackParms | (RPC Manager Library) This method unpacks a stream into the supplied parameters. Subroutine call only.
WriteLock | (RPC Manager Library) This subroutine attempts to require a Write lock for the specified service. Subroutine call only.


Deprecated RPC Methods

The methods in this section are deprecated and have been retained for use by existing, legacy applications. New applications should use \RPCManager\Send(), which subsumes all the functionality provided by these legacy methods.

RPC (function call)

SendAll

Broadcast

RPCExecute

RPCExecuteServer

RPCExecuteAll


Server List Source Callback Methods

An object that is passed into the ListSource parameter of \RPCManager\Register() should implement the following methods. Note that usually Invalid is passed into that parameter, in which case the list (if not explicitly provided in the ServerList parameter of the Register call) is retrieved from the application’s Servers.XML file. However, providing a ListSource object with the following interface is a way of specifying an alternate source of server lists for the service, should you desire a different way of dynamically updating server lists and settings.


ServerListSubscribe RPC Function

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Reference > Server List Source Callback Methods > ServerListSubscribe RPC Function

ServerListSubscribe

Description: | Called by RPCManager to subscribe to server list changes.
Returns: |
Usage: |
Function Groups: |
Format: | ServerListSubscribe(SubscriberObj, Callback)
Parameters: |
SubscriberObj
Object that is subscribing to server list changes
Callback
Text name of method in Subscriber to call (with no parameters) when the server list may have changed
Comments: If the server list cannot be changed dynamically, then this need not be implemented.


ServerListUnsubscribe RPC Function

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Reference > Server List Source Callback Methods > ServerListUnsubscribe RPC Function

ServerListUnsubscribe

Description: | Called by RPCManager to unsubscribe from server list changes.
Returns: |
Usage: |
Function Groups: |
Format: | ServerListUnsubscribe(SubscriberObj)
Parameters: |
SubscriberObj
Object that is unsubscribing from server list changes
Comments: If the server list cannot be changed dynamically, then this need not be implemented


GetServerList RPC Function

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Reference > Server List Source Callback Methods > GetServerList RPC Function

GetServerList

Description: | Called by RPCManager (on service registration, and after every subscription callback) to retrieve the server list given a specified server list name. It should return an array of server names/IPs.
Returns: |
Usage: |
Function Groups: |
Format: | GetServerList(ServerListName)
Parameters: |
ServerListName
Name of server list to retrieve
Comments:


GetRPCServiceSettings RPC Function

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Reference > Server List Source Callback Methods > GetRPCServiceSettings RPC Function

GetRPCServiceSettings

Description: |
Returns: |
Usage: |
Function Groups: |
Format: | GetRPCServiceSettings(ServerListName)
Parameters: |
ServerListName
Name of server list whose settings we are retrieving
Comments: It should return a dictionary of service settings, typically a dictionary with a single "Sticky" element, whose value is the sticky flag for the specified service.


Diagnostics

Earlier versions of the RPC Manager had an inbuilt diagnostic facility, which could be activated by setting the system variable \RPCManager\RPCDiagnostics to a non-zero value. Setting this back to zero will disable the diagnostics again.

This application has been superseded by the Trace Viewer application.

Related information:

Trace Viewer Application.


RPC Internal Routing

RPC Manager absolutely guarantees that a sequence of RPCs generated on one machine, will be routed to the next consumer of the request in the order that the RPCs were generated.

What this means to the programmer is that two consecutive RPCs that are generated on the same machine as each other and are to execute on the same target machine will always be executed in the order in which they were generated. This assumption promotes robust algorithms when programming for a distributed system. This assumption is necessary for the correct operation of services and other parts of the RPC subsystem.

In the interests of preventing one large RPC blocking others, the version 4 RPCManager only preserves this rule within a service or between directed RPCs. An RPC issued from service A is not guaranteed to execute before an RPC from service B, even if it was issued first. Two RPCs within service A are, however, guaranteed to execute in the order they were issued.

To achieve this, RPC Manager serializes all RPC requests through a single FIFO queue on the local machine. The serialization includes not only locally generated requests, but also requests that arrive from other machines.

RPC requests are then removed, one at a time, from the serialization FIFO and examined to determine:

  • If the request should be forwarded to other RPC manager instances in the distributed system. There the request will be processed in an identical fashion.
  • If the request should be executed on the local machine.

In versions of RPCManager prior to version 4, each MachineNode contains a transmission FIFO, ensuring that RPC requests are delivered to the remote machine in the strict order that they were generated on the local machine.

From version 4 onwards, each MachineNode contains one FIFO for directed RPCs and one FIFO for each service that is registered with RPCManager.

MachineNode selects the SocketNode to encode and transmit the request, according to the methods outlined in the section on Multi-homed Systems.

Each SocketNode\Receiver module accepts and decodes the incoming requests and places them on the local serialization FIFO for processing.

The flow of RPC requests through the RPC subsystem is depicted in the following diagram, where the parenthesized names are the RPC Manager module that performs the operation:

The settings that were provided by the original \RPCManager\Send() subroutine call provide the initial routing information. RPC Manager may modify this information before queuing the RPC request on a transmission FIFO, so that the receiving RPC Manager will make the correct decisions about any further routing. Further routing only occurs in the "client of a client" case (see the section Clients of Clients).

To achieve this, the RPC request carries a set of "routing flags" with it, which are transported across machines. These flags and the routing strategy are discussed in section RPC External Routing.

With the Diagnostics window’s "Detail Trace" button pressed, the routing of RPC requests between the serialization FIFO and the transmission FIFOs are revealed. A request received from a remote machine is diagnostically recorded when it is posted to the serialization FIFO, when it is removed from the serialization FIFO for processing and when it is queued on each transmission FIFO.

Without this button pressed, an RPC from a remote machine will be recorded only when it is removed from the serialization FIFO or when it is queued on each transmission FIFO.


RPC External Routing

All RPC requests carry a set of routing flags which determine how the RPC Manager which is processing the request, will route the message and whether it will execute the RPC locally.

The flags are bit-significant:

Flag Name | Bit
#FNR_EXECUTE | 20
#FNR_IFSERVER | 21
#FNR_TOCLIENTS | 22
#FNR_RECURSIVE | 23
#FNR_EXSERVERS | 24

The flags are initially generated when the \RPCManager\Send() call is made:

  1. If the RPC is a directed RPC, or the ExecLocally parameter is greater than zero, #FNR_EXECUTE is set.
  2. If the SendServer parameter is greater than zero, the #FNR_IFSERVER and #FNR_EXECUTE flags are set.
  3. If the SendAllClients parameter is greater then zero, the #FNR_TOCLIENTS flag is set.
  4. If the Recursive parameter is greater than zero, the #FNR_RECURSIVE flag is set.

When the RPC request is removed from the serialization queue and processed, the following rules are applied, in the order shown to implement the routing algorithm:

  1. If the RPC is a directed RPC:
    1. If the RPC is to be run on the local machine, execute it.
    2. Otherwise, place it on the transmission FIFO for the target machine.
  2. If the RPC is a service RPC:
    1. If the RPC has been received from a remote machine and has the #FNR_IFSERVER set, but the recursive flag is clear, the RPC request will be inhibited from propagating to a higher-order server. This is a somewhat special case, where an RPC request from a client-of-a-client is not to be continually propagated to subsequent servers. To achieve this, the #FNR_IFSERVER flag is forcibly cleared, so the following rules can continue to be applied.
    2. If the #FNR_IFSERVER flag is still set and the local machine is not the service server (from the point of view of the local machine) and the service filtering mode permits the request to be transmitted, it is queued on the transmission FIFO for the service server, with the same flag settings as the request.
    3. If the #FNR_IFSERVER flag is still set and the local machine is the service server and the #FNR_TOCLIENTS flag is set, the RPC is queued on the transmission FIFOs for each client of this server. If the #FNR_EXSERVERS flag is set, the RPC is only queued if the client is a potential server from the point of view of the local machine. If the #FNR_RECURSIVE flag is set, the request is queued with the #FNR_EXECUTE, #FNR_TOCLIENTS and #FNR_RECURSIVE flags set to cause it to be executed on the remote client and propagated to clients the client. If the #FNR_EXSERVERS flag is set, this is propagated to the potential servers as well. If the #FNR_RECURSIVE flag is clear, only #FNR_EXECUTE is set on the outgoing request.
    4. If the #FNR_IFSERVER is clear and the #FNR_TOCLIENTS flag is set, the RPC is queued on the transmission FIFOs for each client of this machine, for the service. The flag settings used in c, above, are used for propagation of requests to other machines. This rule implements the transmission to a client of a client.

The above information is of value when identifying why an RPC that you expected to go to a particular machine was not transmitted to it.


RPC Execution

An RPC request is executed on the local machine whenever:

  1. The RPC request is a directed RPC, aimed at this machine.
  2. The RPC is a service request and the #FNR_EXECUTE flag is set, unless the #FNR_IFSERVER flag is also set and this machine is not the service server (from the point of view of this machine).

The values of \RPCManager\CurSocketNode and \RPCManager\CurSessionID are set to reflect the machine that the RPC request was received from. If the RPC was sourced from the local machine, these will have valid values appropriate for the local machine.


RPC Security

VTScada security is application based. Usernames and passwords are held by an application and are used to authorize the actions that a user can perform. RPC security is system based and is concerned with ensuring that RPC communication between VTScada servers is secure.

Inter-server communication security can be sub-divided into two parts:

  • Security of data. This pertains to the protection against modification or discovery of system data.
  • Security of system. This pertains to the protection of the system against malicious network traffic and unauthorized hands-on modification of the system or the plant it controls.

Research shows the latter to be the area of almost all reported vulnerabilities of SCADA systems. The vulnerabilities cause loss of service, a crash or other catastrophic failure of the SCADA system. Discovery of these vulnerabilities is usually made in an environment other than a production environment (i.e. someone has a copy of the software and sets out to break it in a lab environment) and, therefore, physical access to the system is not implemented.


Security Measures

Best practices ensure best security and a multi-tiered approach is recommended:

  • Physical access to the servers comprising a SCADA system needs to be restricted to only those who need access.
  • Networks also require physical security. If it is not possible to connect a computer to the SCADA system servers, the attack surface is significantly reduced. This can be achieved either by preventing physical access to the networking infrastructure or by using a router to provide isolation of the network.
  • Network access to the servers. In addition to the protection afforded by limiting access to the network on which the servers are communicating, protocol security can be added to afford additional protection against compromise of the network. Server class Windows operating systems are quite capable of automatically securing communication to a specific machine using IPSec (and requiring that all other servers and workstations comply) by configuring IP Security Policies using the MMC IP Security Policy Management snap-in and either using Windows X.509 Certificate Management or purchasing third-party trusted certificates. This affords access restriction to nominated computers only (those with appropriate certificates installed) and prevents data snooping and tampering by using encryption and message digests. For a wide area network, secure tunnels must be used, e.g. an IPSec VPN connection between sites.


RPCManager AllowIP

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > RPC Security > RPCManager AllowIP

[RPCManager-AllowIP]

While preventing network access using IPSec is recommended, smaller systems running in trusted environments may wish to simply prevent inadvertent connection to a live VTScada system by, say, a development or test system.

The [RPCManager-AllowIP] section (in SETUP.INI) is used to achieve this. This can also be used to provide yet another tier in the security model.

This setting applies only to thick clients. Do not attempt to use it as a means of restricting thin client access.

This section is not present by default. Its inclusion causes RPCManager to refuse connections from all external computers and to refuse to establish socket connections to any external computer other than those listed in the section.

Modification of this section does not take effect until VTScada is restarted.

Each entry consists of a single line specifying the IP address of a peer, or subnet ranges with which connections are permitted. Names are not acceptable.

The IP addresses may be IPv4 or IPv6 addresses. Subnet ranges may be specified using IPv4 or IPv6 CIDR Closed Classless Inter-Domain Routing notation.

An example section might look like this:

[RPCManager-AllowIP]
  IP = 192.168.1.5
        ; Single IPv4 address
  IP = 62063:0bf4:32c4:43ad
        ; Single IPv6 address
  IP = 0.0/24
        ; IPv4 subnet range
  IP = 2046:470:1f2c:b56/32
        ; IPv6 subnet range

This will allow VTScada RPC connections from only the two listed IP addresses and from any computer on either of the two listed subnets. It is normal, especially with subnet specifications, to have the same content in the SETUP.INI file installed on each server.


Configuration

There are two types of initialization data used by RPC Manager:

  • Configuration used to control the behavior of the distributed system as a whole or a machine within the distributed system.
  • Configuration used to control a service.

Non-service configuration is held in the SETUP.INI file and has been designed to allow the specification of the non-service configuration for an entire distributed system identically on all machines within the distributed domain.

Service configuration, on the other hand, is specified in the application layer’s Servers.XML file, if the \RPCManager\Register() call’s ListSource parameter is Invalid. Otherwise, it depends on the ListSource’s API functions (see Server List Source Callback Methods section).

The server list from a layer’s Servers.XML that a service uses is based on the following order of precedence (given that the server list name is either the ListName parameter to the service’s Register call, or, if that isn’t provided, then the ServiceName in the Register call):

  1. A server list specific to the current workstation and server list name.
  2. A server list specific to the current server list name, but not workstation-specific.
  3. A server list specific to the current workstation, but not service-specific.
  4. The default server list.
  5. If none of these lists are present in Servers.XML, then this machine is treated like the solitary server.


SETUP INI System Values for RPC

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Configuration > SETUP INI System Values for RPC

SETUP.INI [System] Values for RPC

The following variables can be set in the [System] section of SETUP.INI, located in the VTScada installation directory.

Related information:

[RPCManager-ExcludeIP] Section - designation of excluded addresses. See also: RAS Clients

[RPCMANAGER-NETPRIORITY] Section - configuration of multi-homed systems. See also: Multi-homed Systems

[LINKTOLERANCE-…] Section- see also, the discussion: Link Tolerances


RPCBufferLength

This is the maximum TCP/IP buffer length to use for RX and TX buffers.

Prior to version 4, the default is 33,554,432 bytes if not defined. This has no bearing on the size of the RPC packets transmitted and should be left to default settings.

From version 4 onwards, the default is 262144. This defines the maximum amount of data from the socket connection that Windows will use. If VTScada does not drain the buffers, further transmissions from the remote end of the socket connection will cease until it is drained. This also defines the TCP "window size" that VTScada uses.

There is an important relationship between this value and RPCMaxPacketSize. RPCManager reads the packet header from the socket and then waits for sufficient data to become available before reading it. This is intentional and reduces the amount of buffer that VTScada must allocate and the amount of script code processing that needs to be done until the entire packet has been received. This effectively reduces the "attack surface" of RPCManager by limiting the amount of data that can be maliciously pushed into a socket connection.

Therefore, for version 4 onwards, the transmitting machine's RPCBufferLength MUST be greater than RPCMaxPacketSize by at least 10%. Otherwise, you will end up with a zero-length TCP window and lose your connection.

The default values will work for LANs and WANs.

Related information:

RPCMaxPacketSize


RPCConnectPort

The TCP/IP port that RPC Manager tries to connect to.

Defaults to the value of RPCServerPort.

Related information:

RPCServerPort


RPCConnectStrategy

The IP addresses that the RPC Manager can open to connect to remote machines , can be provided by two sources:

  • Name resolution.
  • A set of IP addresses, supplied by the other machine when the VTScada RPCManager connects to it.

The value of RPCConnectStrategy controls how these are used, as follows:

Value | Connect Strategy
Invalid | If a DNS server is being used for name resolution, opens each IP from the DNS query in the order supplied by DNS. If no DNS server, opens each IP supplied by the remote machine. This is the default setting for all VTScada versions after 10.2.06.
FALSE | Opens each IP supplied by name resolution, regardless of whether a DNS server is being used or not and ignores the IPs supplied by the remote machine.
TRUE | Initially opens only the first IP address supplied by name resolution and then opens each IP supplied by the remote machine.


RPCDiagnostics

Set to a non-zero value to display the RPC Diagnostics window on startup. This value may also be set at run time by scoping into the system and changing the value.


RPCMaxPacketSize

Specifies the maximum size of an encoded remote procedure call before the call will be fragmented over a number of transmissions.

From version 4 onwards, specifies the maximum size of an RPC packet. RPCs will be packed into a packet until there are no more to send, or RPCMaxPacketSize is reached. The default is 65536 bytes.

For version 4 onwards, the value of this configuration value must be less than RPCBufferLength by at least 10%. See the discussion of RPCBufferLength for more detail.


RPCMaxQLen

Specifies the maximum number of RPC messages destined for remote machines that will be queued before the queue is deemed to have "flooded" and the session closed with all messages lost. The local RPC queue is not subject to this limit. The larger this limit, the more tolerant the system will be to large bursts of RPC activity. However, the larger the queue, the more RAM will be required when the queues are large. This parameter cannot compensate for the condition where the average RPC traffic load exceeds the bandwidth of the network connection.

Default: RPCMaxQLen = 65536


RPCMaxStartDelay

Controls startup behavior if the workstation name is not valid. RPC Manager will wait for a maximum of the seconds specified in RPCMaxStartDelay before assuming there is no network available.

This is useful for auto starting a machine after a reboot, since it is possible for network services to not yet be started when VTScada is starting. RPC Manager will wait indefinitely for the network to start, if this value is set less than 0.

Default: RPCMaxStartDelay = 30


RPCMemBuffLimit

Specifies the number of bytes on a received RPC message that will be kept in RAM before the message is transferred to a temporary file to conserve memory. The larger this value, the faster larger messages will be processed, but correspondingly more RAM will be required.

Default: RPCMemBuffLimit = 2097152

(2Mb)


RPCMemSendLimit

Specifies the number of bytes on a transmitted RPC message that will be kept in RAM before the message is transferred to a temporary file to conserve memory. . The larger this value, the faster larger messages will be processed, but correspondingly more RAM will be required.

Default:RPCMemSendLimit = 1048576

(1Mb).


RPCPingInterval

Specifies the time that a socket can have no data transmitted before a "ping’ packet will be sent to all the receiving end to determine that the socket it still good. Will use no value less than 5. The RPCPingInterval is subject to the ToleranceFactor on the receiving machine. The receiver will wait 3 times this long or RPCReconnectTime, whichever is longer, to disconnect if no data is received.

Default: RPCPingInterval = 5

Related information:

[LINKTOLERANCE-…] Section


RPCReconnectTime

Specifies the seconds to wait for data on a socket before disconnecting the socket. The actual delay before disconnect is the greater of this time and three times the RPCPingInterval. RPCReconnectTime is NOT subject to the ToleranceFactor.

Default: RPCReconnectTime = 15

Related information:

[LINKTOLERANCE-…] Section


RPCResendDelay

Specifies the time to wait for an acknowledgment after sending a packet before resending the packet. RPCResendDelay is subject to the ToleranceFactor on the receiving machine.

Default (and minimum): RPCResendDelay = 3

Related information:

[LINKTOLERANCE-…] Section


RPCServerPort

The TCP/IP port that RPC Manager "listens" on.

Default: RPCServerPort = 5780

Related information:

RPCConnectPort


RPCSktConnectAttemptMax

Specifies the number of attempts to open a socket before it is declared to be closed. The time between starts at 5 seconds and grows by 10% after each attempt. If a socket is closed and there is no backup socket for the session, then the session is lost and service synchronization must occur when the socket is eventually opened and a new session established. The minimum value is 1.

Default: RPCSktConnectAttemptMax = 5


RPCSktResendAttempts

There will be a maximum of RPCSktResendAttempts to transmit the RPC successfully. If, after these retries, the RPC has still not been acknowledged, the socket stream is terminated and SocketNode goes through its link re-establishment cycle.

Default RPCSktResendAttempts = 5


RPCSocketDeadTime

Specifies the number of seconds that a session will remain alive with no socket connection. This time is AFTER the RPCSktConnectAttemptMax has expired.

Default (and minimum) RPCSocketDeadTime = 1


RPCSocketResendAttempts

Specifies the number of packet re-sends that will occur without acknowledgment, before the socket is closed.

Default (and minimum) RPCSocketResendAttempts = 5


RPCTrace

Set to a non-zero value to log all RPC activity to the disk file "RPCTRACE.TXT", in the VTScada installation directory. This variable only has effect while RPCDiagnostics is set non-zero.

Default: RPCTrace = 0


RPCUseBuffered

When non-zero this will cause RPC to read the TCP/IP IP and Name once only from the low-level socket stream and cache this information. This value should only be set to 0 if the TCP/IP IP or Name can change dynamically. This is not recommended.

Default: RPCUseBuffered = 1


Variables available in RPCManager

Viewing: Scripting > Services (Alarm, Historian, etc.) > RPC Manager Service > Configuration > Variables available in RPCManager

Variables available in \RPCManager

The following variables are available within RPCManager for public consumption, but are strictly read-only. Modifying any of these variables could lead to unexpected behavior.

Started

Initially zero, this gets set to a non-zero value after the RPC Manager has initialized. You should not attempt to register your service until RPC Manager has set this value.

WkStnIP

The IP address of the local workstation. Only valid after Started is set non-zero.

WkStnName

The name of the local workstation. Only valid after Started is set non-zero.

WkStnVersion

The VTScada version running on the local workstation. Only valid after Started is set non-zero.

WkStnIPList

Deprecated. Contains only IPv4 addresses. Do not use for IPv6 addresses.
An array, each element holding a textual representation of the set of IPs by which this workstation is known. This IP address list is not dynamic and will only populate for the local machine at VTScada startup.

Related information:

Application Settings for RPC


Name Resolution

RPC Manager uses name resolution to discover the IP for a particular machine name. The correct configuration of name resolution services is outside the scope of this document. Reference should be made to the operating system documentation.

Caution: A correctly configured name resolution system is essential for correct operation of the distributed system.

The default name resolution setup for Windows TCP/IP networks looks in the following places, in the following order, to derive an IP address:

  1. The operating system HOSTS file is searched.
  2. If not found, any configured domain name servers (DNS) are checked (including WINS servers).
  3. If still not found, NetBIOS broadcasting is used.

If you do not configure any name resolution system, the default behavior of Windows will cause NetBIOS broadcasts to be used. While this will work fine on most network configurations, it may not work properly on large, segmented networks.

The basic rule is that if you can reliable ping a machine by name and have the correct IP addressed by the ping packets, then VTScada will work correctly.

Most SCADA systems will function well with static IP to name mapping. This can be achieved through HOSTS files on individual machines, or by a centralized name resolution service, such as WINS.

VTScada will, however, also function correctly with dynamic IP address assignment, typically provided by DHCP. RAS clients also often use dynamic IP assignment when connected into a RAS server.

If NetBIOS broadcasting is insufficient to meet your name resolution needs, then you will need to consider one of the alternatives in the following topics:


HOSTS File

The simplest approach is to configure up a master HOSTS file and ensure that every machine in the distributed system has the same HOSTS file. For example:

127.0.0.1 localhost
192.168.3.21 Server1
192.168.3.22 Server2
192.168.3.23 Server3
192.168.3.30 OpRoom1
192.168.3.31 OpSuper
192.168.3.50 RemoteWorks
192.168.3.55 RemoteWorks1

The disadvantage of this method is that each machine in the distributed system must have a consistent set of information.


Centralized Name Resolution

In environments where new machines may be added on a regular basis, maintaining a consistent set of HOSTS files may be an unacceptable overhead. In such cases, a centralized name resolution system is preferable. This is normally provided by one or more designated systems, often domain controllers and is often termed DNS. The assignment of IPs to machine network interfaces can still be performed statically, or can be dynamically assigned.

Dynamic IP assignment refers to the ability of a designated system to dynamically assign an IP address from a pool of IP addresses, for a machine connected to it.

VTScada provides support for dynamic IP assignment.

For robustness, SCADA systems are generally configured with static IP address assignments, reserving dynamic IP assignment for multiple dial-in links.


RAS Clients

Remote Access Services have largely been replaced by Virtual Private Networks. Refer to: VTScada and VPNs

A Remote Access Service (RAS) server provides access to remote computers. Generally, the RAS server is configured to provide a separate IP address for itself and the remote client, when connected. Allocating each client a different IP address from a pool of addresses caters for multiple concurrent clients.

VTScada provides support for multiple remote clients.

When allowing a remote client to connect, due consideration should be given to deciding whether the remote client will require access to the LAN that the RAS server is connected to.

If access is required, then it is better to delegate the RAS server to be a machine other than one running VTScada. In this way:

  1. Routing between the RAS server and the SCADA system is handled by the network infrastructure.
  2. The RAS server can be shared between infrequent access to the SCADA system and other work, without compromising the SCADA system.
  3. "Hacking" attacks, e.g. denial-of-service (DoS), are less likely to disable your SCADA system, when the point of access is separated from the SCADA system.

If access is not required, or another system is not available to be a RAS server, then you can use a machine running VTScada as the RAS server.

Caution: If the RAS server is also running VTScada, prior to version 5.1502, then, for correct operation, it is essential that the RAS IP addresses appear on a different subnet to any Network Interface Cards (NIC). If this precaution is not observed, the attached RAS client will be able to access the NIC IP addresses on the same subnet. This will not compromise operation, but will severely impair RPC Manager’s performance.

From VTS version 5.1502 onwards, a machine running VTScada can accommodate RAS clients on any subnet, including one already used by a LAN connection. Instructing RPC Manager, via a SETUP.INI section, to not create a connection to specific IP addresses, achieves this. By specifying the IP that the RAS host presents as its own IP to the RAS client, the RAS client will not create a connection to the RAS host IP, but only connections to the other IPs that the host machine is known by.

For example, if a machine running VTScada had an IP of 192.168.0.40 and that machine was configured to support a RAS client, such that the RAS client would see the host machine as 192.168.0.150 and the RAS client be assigned an IP address from a pool of addresses from the range 192.168.0.151 to 192.168.0.155, then the following section should appear in the RAS client’s SETUP.INI file, so that the RAS client will only make a connection to 192.168.0.40 [which will be done over the RAS link] and not to 192.168.0.150:

[RPCManager-ExcludeIP]
IP = 192.168.0.150

Note that this is not necessary if the RAS IP address pool is on a different subnet from any other IP of the RAS host, so long as no routing exists between the two subnets.

From VTS version 5.18 onwards it is not necessary to exclude any IP addresses on the server, however, if the IP cannot be accessed by a connecting client VTScada system, it is advisable to exclude it from RPC Manager’s view by the above method.


Fully Qualified Domain Names

A fully qualified domain name [FQDN] takes the form <host>.<domain>, e.g. xx.xyz.com. When viewing the SocketNodes, displayed by RPC Diagnostics, you may notice that the MachineNode names are machine names, whereas the SocketNode names are FQDNs. This is because SocketNode names are obtained by reverse name lookup, converting the IP of the connected [remote] machine to a name. Name resolution, particularly via DNS, may yield such a name.

When specifying server lists, you must provide machine names [not FQDNs] in the configuration files and when acquiring an application from another machine.

Then configure name resolution to resolve names within the context of the appropriate domains by specifying domain suffixes during DNS configuration on the client machine [see diagram] and leave the mapping to DNS.

In the following diagram, a machine called XX will be searched for, firstly, within the trihedral.com domain and then in the xyz.com domain.

This means that machine names must be unique within the domains that RPC Manager can address, e.g. using the above configuration, RPC Manager will treat xx.trihedral.com and xx.xyz.com as the same machine [even if they are not].


Protocol

RPC Manager uses TCP/IP sockets to provide a transparent communication channel between RPC Manager instances. A proprietary protocol is transmitted between RPC Manager instances carrying both RPCs and control information.

This section describes the proprietary protocol used by RPC Manager. This information is not essential to use RPC Manager to its fullest capabilities.


Protocol Versions

There are two versions of the protocol, loosely named version 3 and version 4 (the version numbers actually refer to points of major change in RPCManager).

Version 3 protocol is used in all RPCManagers from VTS version 7.1.21 through version 9.

Version 4 protocol is used from version 10 onwards.

Version 4 has a different structure enabling RPCs from multiple source GUIDs and to multiple destination GUIDs to be transported in the same RPC packet, reducing the number of RPC packets needed (and hence the turnaround latency). Version 4 protocol supports packet compression and does so by default. Finally, VTScada TCP/IP engine changes permit version 4 to get increased throughput (particularly on WANs) by properly utilizing TCP window scaling and a larger default window size.

RPCManager versions using version 4 protocol also support version 3 protocol to enable support of mixed versions of VTScada in the same SCADA system.


General Structure

The RPC Manager protocol is a generic term that can be better defined as the cross-machine protocol used by two SocketNodes to provide the reliable RPC transport. By this definition, the protocol is private to SocketNode and is completely encapsulated within SocketNode.

TCP/IP provides for reliable delivery of packets of information, where, for the purposes of this document, a packet is defined as an atomically written block of bytes.

Each packet has the same format, information within the packet header being used to decode the message that it carries. Messages fall into two categories, control messages and RPC messages.


Version 3 Packet Format

A packet has the following format:

Sync | Dest GUID | Function Code | Message Length | Sequence Number | Source GUID | Message
4 bytes | 16 bytes | 1 byte | 2 bytes | 1 byte | 16 bytes | variable
Closed Sync

The Sync field is constant and is the character sequence #96#. As TCP guarantees reliable delivery, there is no CRC or checksum on a packet. This would be a duplication of the error checking abilities of TCP. The purpose of the Sync field is to provide defense against an internal RPC Manager fault, where a partial packet was transmitted. TCP guarantees reliable, atomic delivery of an atomically written sequence of bytes. The Sync field ensures that a non-atomic write (which should not happen) will not cause erroneous action at the receiving RPC Manager.

Closed Dest GUID

A running VTScada system contains one "root" system object and multiple application "root" objects. The Dest GUID field is used to discriminate between these root objects and allow RPC Manager to determine a starting scope in which to search for a target RPC subroutine.

The Dest GUID for an application root is the same GUID as used in the Settings.Startup file to uniquely identify an application’s code objects within the distributed domain. That Dest GUID is the same for all instances of the same application.

RPCs directed at the system root level carry an all-zero Dest GUID. An all-zero Dest GUID is also used on control messages.

Closed Function Code

The Function Code contains a unique value, defining the message type. This is combined with a set of modifier flags that provide for minor expansions to the "pure" set of commands.

The least significant 5 bits of the Function Code contains the command code. This gives a set of 32 possible commands. Command code 0 is, defensively, not used, giving a total of 31 commands, of which only five are defined:

Code Name | Value | Meaning
#FNF_PING | 1 | Ping packet. No message. The Binary GUID is all-zeros, the Message Length is zero and the Sequence Number is zero.
#FNF_ACK | 2 | acknowledgment of an #FNF_RPC. No message. The Binary GUID holds the same Binary GUID as the #FNF_RPC that is being acknowledged. The Message Length is zero. The Sequence Number contains the same Sequence Number as the #FNF_RPC that is being acknowledged.
#FNF_SESSION | 3 | Session management table in message.
#FNF_RPC | 4 | RPC in message.
#FNF_ RPCMULTI | 5 | Multiple RPCs in message.

The most significant 3 bits contain modifier flags. These flags are command specific and, presently, are only defined for #FNF_RPC:

Flag Name | Value | Meaning
# FNF_FLAG_DUALGUID | 32 | The Source GUID is present.
#FNF_FLAG_FIRST | 64 | First fragment of a fragmented RPC.
#FNF_FLAG_NEXT | 128 | Subsequent fragment of a fragmented RPC
Closed Message Length

The Message Length field contains the number of bytes that make up the Message Field.

Closed Sequence Number

This is a number, initialized to 1, which increments each time a transmitted #FNF_RPC has been acknowledged. When it reaches 255 and increments, it wraps around to 1. For all other Function Codes, the number is zero.

The receiving SocketNode acknowledges, but does not action, an RPC message that was a duplicate of the previous one.

This is designed to prevent SocketNode taking replicate action if the same RPC is re-transmitted, as part of a retry strategy. In the situation where the remote machine sees the RPC message transmission and acknowledges it, but the transmitting machine fails to receive the acknowledgment, a successful re-transmission of the same RPC message will be acknowledged, but a second invocation of the RPC subroutine will not occur. This could happen because SocketNode will tolerate a high degree of inter-machine communication link disturbance, before session termination occurs.

If the session is lost, the Sequence Number is reset to 1.

Closed Source GUID

The Source GUID is only present in cross-application RPC messages. It is the binary form of the GUID of the application that sourced the RPC.


Version 4 Packet Format

A packet has the following structure:

Function Code | Sequence # | Message Length | Uncompressed Length | Message
1 byte | 1 byte | 4 bytes | 4 bytes | variable
Closed Function Code

Version 3 protocol always started with a "Sync" marker of 4 bytes, the first byte of which was 0x23 (a # character). The version 4 function codes defines this function code value as a session table and interprets the remaining bytes of the transmission as an "old" format session table. When RPCManager opens a socket connection to a peer, this is the first message sent and enables the two RPCManagers to determine which protocol should be used. This avoids the need to have an old and new session table format.

The least significant 5 bits of the Function Code contains the command code. This gives a set of 32 possible commands. Command code 0 is, defensively, not used, giving a total of 31 commands, of which only five are defined:

Code Name | Value | Meaning
#FNF_PING | 1 | Ping packet (I have sent nothing for some time, but I’m still here). The entire transmission consists of only the function code.
#FNF_ACK | 2 | acknowledgment packet (acknowledging an RPC or RPCs received). The entire transmission consists of the function code and sequence number.
#FNF_SESSION | 3 | Unused. A version 4 format packet carrying this function code is treated as illegal and cause the session to reset.
#FNF_RPC | 4 | RPC in message. The entire transmission is of variable length and consists of the function code, sequence number, message length and variable length message field.
#FNF_ RPCMULTI | 5 | Unused. A version 4 format packet carrying this function code is treated as illegal and cause the session to reset.
#FNF_RPCCOMPRESS | 6 | Compressed RPC in message. The entire transmission is of variable length and consists of all the above fields.
#FNF_NEWSESSION | 35 | Session management table in message. Identical packet format to version 3.
Closed Sequence Number

This is a number, initialized to 1, which increments each time a transmitted #FNF_RPC or #FNF_RPCCOMPRESS has been acknowledged. When it reaches 255 and increments, it wraps around to 1.

The receiving SocketNode acknowledges, but does not action, an RPC message that was a duplicate of the previous one.

This is designed to prevent SocketNode taking replicate action if the same RPC is re-transmitted, as part of a retry strategy. In the situation where the remote machine sees the RPC message transmission and acknowledges it, but the transmitting machine fails to receive the acknowledgment, a successful re-transmission of the same RPC message will be acknowledged, but a second invocation of the RPC subroutine will not occur. This could happen because SocketNode will tolerate a high degree of inter-machine communication link disturbance, before session termination occurs.

If the session is lost, the Sequence Number is reset to 1.

Closed Message Length

This holds the number of bytes in the message field.

Closed Uncompressed Length

This field, only present with function code #FNF_RPCCOMPRESS, holds the number of bytes in the uncompressed length of the message field.

Closed Flags

The Flags byte contains routing flags that tell RPCManager how to process the message and flags that determine the format of the body:

Bit Number

Meaning

0 - 4

Routing Flags. Identical to those defined for previous versions of the RPC protocol, with the addition of the #FNR_EXSERVERS (24) flag for routing to potential server clients only.

5

Dual GUID. When set, a Source GUID field is present in the body. The Source GUID field is only present in cross-application RPCs.

6 - 7

Fragment Flags. This indicates:

Value | Meaning
0 | The body is a fragment of an RPC spanning multiple bodies.
1 | The body is the first fragment of an RPC spanning multiple bodies.
2 | The body is the final fragment of an RPC spanning multiple bodies.
3 | The body holds a complete RPC.


Session Table Message

A #FNF_SESSION packet is the first packet which is transmitted over a new socket stream connection. There is no acknowledgment that this packet has been received, however, there will be no transmission of any other packets until a #FNF_SESSION packet is received.

The message in a #FNF_SESSION packet contains the version number of the remote VTScada and a session management table:

Remote VTScada Version | Session Table Size | Session Table | Workstation Name | Flag Byte | Session Table Sequence # | VTScada Serial Number
8-byte IEEE floating point | 4 bytes | variable | Text, NUL terminated. | 1 byte | 4 bytes | 4 bytes

The Session Table Size is given in bytes and includes all bytes in the remaining fields.

The Session Table field holds the actual session table and is constructed from rows, each row forming the SID for a connection for an application:

Application GUID | Application Session ID | Connection Session ID
36 byte text GUID | 36 byte text GUID | 36 byte text GUID

This may appear to be a bandwidth-hungry message, but it is sent infrequently:

  • As the first packet down a new socket stream connection.
  • If an application terminates.
  • If an application starts.

An operational system will probably only have two rows in the session table, one with an Application GUID field of the all-zero Binary GUID and one for the end-user application. Sending a row for the VTScada system GUID permits the detection of VTScada being restarted during a network break.

The Workstation Name is the NetBIOS name of the workstation sending the session table.

The Flag Byte holds bits that describe the capabilities of the sending RPCManager and what additional fields are present:

Bit Number | Meaning
0 | The Session Table Sequence # field is present.
1 | The VTScada Serial Number is present (VTS 9.0.06 onwards).
2 | The sending RPCManager supports version 4 protocol.

The Session Table Sequence number is a 32-bit number, incremented each time a MachineNode sends a session table. This is used by the receiving RPCManager to detect session tables that arrive out-of-sequence on a multi-homed system. This prevents old session information from being interpreted as the current information where one route is slower than the other.

The VTScada Serial number is a 4-byte integer encoding of the VTScada serial number, exactly as obtained from a GetConfiguration(0) call.


Version 3 RPC Messages

#FNF_RPC

A #FNF_RPC message has the following, generic, format:

Mode Cut-Off | Routing Flags | Encoded RPC
1 byte | 1 byte | variable

The Mode Cut-Off field contains the mode cut-off value that was supplied to the original \RPCManager\Send() call. The Routing Flags field contains the RPC routing flags, see section RPC External Routing.

If the Encoded RPC is longer than the value defined in the configuration variable RPCMaxPacketSize, the RPC will be broken into fragments for transmission, each fragment being no longer than RPCMaxPacketSize.

A fragmented RPC utilizes the two Function Code flags #FNF_FLAG_FIRST (26) and #FNF_FLAG_NEXT (27). #FNF_FLAG_FIRST is set on the first fragment and #FNF_FLAG_NEXT on all subsequent fragments. The #FNF_RPC messages carry an additional 8 byte header:

Block Number | Total Blocks
4 bytes | 4 bytes

The Block Number field is set to zero and increments on each fragment, until Total Blocks minus 1 is reached. This denotes the last block in sequence. The header is followed by the generic #FNF_RPC message, so an RPC that was fragmented over 3 packets would appear:

Sync/GUID

Function Code (#FNF_RPC + #FNF_FLAG_FIRST)

Length

Sequence (n)

Block Number (0)

Total Blocks (3)

Mode Cut-Off

Routing Flags

Encoded RPC

Sync/GUID

Function Code (#FNF_RPC + #FNF_FLAG_NEXT)

Length

Sequence (n)

Block Number (1)

Total Blocks (3)

Encoded RPC

Sync/GUID

Function Code (#FNF_RPC + #FNF_FLAG_NEXT)

Length

Sequence (n)

Block Number (2)

Total Blocks (3)

Encoded RPC

#FNF_RPCMULTI

A #FNF_RPC message has the following, generic, format:

Length of this RPC | Mode Cut-Off | Routing Flags | Encoded RPC
4 bytes | 1 byte | 1 byte | variable

This message repeats throughout the length of the packet. Each message consists of an RPC for the same application GUID.

This function code was introduced in VTS version 5.18 as a means of more efficiently transporting updates for large numbers of drivers more efficiently. The encoding of the RPC is the same as #FNF_RPC.

RPC Encoding

The Encoded RPC field of the #FNF_RPC message has only one fixed length field, the RPC Code. All other fields are of variable length.

Target Type | Target | Module Name | Context | Packed Parameters
1 byte |  |  |  |

The purpose of the Target Type and Target fields are to differentiate between directed RPCs and service RPCs. The Target field’s type and content depends on the Target Type:

Target Type Field | Target Field | Description
Service RPC (0) | 2 off 1 byte numerics | The first byte contains an offset into the Context field where the service name can be found. The second byte contains the length of the service name.
Service RPC (1) | CR terminated string | The target field contains the service name, terminated with a carriage return.
Directed RPC (2) | CR terminated string | The target field contains the machine name or IP, terminated with a carriage return.

The Module Name and Context fields are also strings terminated with a carriage return.

The Packed Parameters field is described in the section "Packed Parameters" and is a common encoding with version 4 protocol.


Version 4 RPC Messages

#FNF_RPC

The message field consists of one or more "elements". An element contains either a complete RPC or a fragment of an RPC. The message may contain any combination of these. Elements are interpreted in the strict order that they appear in the message, from first received to last received.

The format of an element is

RPC Message Header | Packed parameters
variable | variable

The header description follows.

The Packed Parameters field is described in the section "Packed Parameters" and is a common encoding with version 3 protocol.

RPC Message Header

Flags | RPC Length | Mode Cut-off | Dest GUID | Source GUID | RPC Type | Service Name or IP/Machine | Module Name | Context | Fragment ID
1 byte | 4 bytes | 1 byte | 16 bytes | 16 bytes | 1 byte | CR terminated | CR terminated | CR terminated | 4 bytes

Flags

The Flags byte contains routing flags that tell RPCManager how to process the message and flags that determine the format of the body:

Bit Number | Meaning
0 - 4 | Routing Flags. Identical to those defined for previous versions of the RPC protocol, with the addition of the #FNR_EXSERVERS (24) flag for routing to potential server clients only.
5 | Dual GUID. When set, a Source GUID field is present in the body. The Source GUID field is only present in cross-application RPCs.
6 - 7 Fragment Flags. This indicates:
Value | Meaning
0 | The body is a fragment of an RPC spanning multiple bodies.
1 | The body is the first fragment of an RPC spanning multiple bodies.
2 | The body is the final fragment of an RPC spanning multiple bodies.
3 | The body holds a complete RPC.

Mode Cut-off

The Mode Cut-Off field contains the mode cut-off value that was supplied to the original \RPCManager\Send() call.

Dest GUID

This field is the same as the version 3 protocol header field of the same name and contains the application GUID that the RPC is intended for, with an all-zero GUID conventionally meaning the system root.

Source GUID

This field is optional and only present if the Dual-GUID flag is set in the Flags byte. If present it contains the application GUID that sourced the message. If absent, the sourcing application GUID is the same as the Dest GUID.

RPC Type

This field indicates if the RPC is a service (1) or a directed (2) type

Service Name or IP/Machine

This field contains the service name, if the RPC is a service RPC or the target machine name if the RPC is a directed RPC.

Module Name

This field contains the name of the module to be invoked as the target of the RPC.

Context

This field contains the scope in which to find the module to be invoked. This is specified as a scope string, with the starting point of the scope being determined by the Dest GUID and Service Name (if a service RPC).

Fragment ID

This field is optional and only present if the RPC is fragmented. If the RPC is fragmented the Flags byte will not have both the first and last fragment flags set. A complete RPC will have both flags set and will not have a Fragment ID field.

The fragments are concatenated together at the receiver and processed after the final fragment is received. The existing algorithm in the SocketNode receiver is used to maintain the stream of fragments in a temporary disk file stream, rather than a memory stream after the fragment concatenation becomes too large.


Packed Parameters

The parameters to the RPC subroutine are packed into the Packed Parameters field. The Packed Parameters field is simply the output of Pack. Running this field, in its entirety through UnPack() results in exactly the same data structure that was passed into Pack() when the RPC was encoded.

Type | Range | Encoded As
Invalid or any unsupported type |  | Single byte of value 255.
Numeric Integer | 0 to 0xDF | Single byte value.
Numeric Integer | 0xE0 to 0xFFF | A byte of 0xE0 or’ed with the top 4 bits of the numeric, followed by the least significant byte of the numeric.
Numeric Integer | 0x1000 to 0x7FFF | A byte of 0xF0, followed by the 2-byte numeric.
Numeric Integer | 0x8000 to 0xFFFF | A byte of 0xF1, followed by the 2-byte numeric.
Numeric Integer | 0x10000 to 0x7FFFFFFF | A byte of 0xF2, followed by the 4-byte numeric.
Numeric Floating Point | IEEE 4-byte floating point number | A byte of 0xF3, followed by the 4-byte IEEE floating point number.
Numeric Floating Point | IEEE 8-byte floating point number | A byte of 0xF4, followed by the 8-byte IEEE floating point number.
Text |  | A byte of 0xF5, followed by a 2-byte length of the text, followed by the text.
Stream |  | A byte of 0xF6, followed by a 4-byte length of the stream, followed by the stream.
Array |  | See following notes about Packed Arrays.

Packed Arrays

The first byte of an array encoding consists of a byte of 0xF7 or’ed with the number of array dimensions minus 1. There then follows a table, with one row per array dimension:

Start Index

Number of Elements

Each table row is packed in exactly the same manner as given for scalar values in the preceding section, minimizing the size of the table.

Each dimension of the array, in ascending order then has its elements packed, in ascending order, in the same manner as scalar values. This operates up to a maximum of three dimensions.

Related Functions:

Pack

Unpack


Security Manager

The Security Manager is a basic component of VTScada supplying all of the code necessary to provide varying levels of security in an application.

The Security Manager is available for use with both Script and Standard applications. It provides a set of API functions to create and modify user accounts, verify access credentials and query relevant permissions. It also provides a set of public variables that may be examined by application code.

The Security Manager is always active.


Accounts

There are two types of account: the user and the role. User accounts identify each person using the application, including their name, password, privilege set and other security-related information. A role is a named collection of security rules. One or more roles may be assigned to each user account, thereby simplifying the process of assigning privilege rules.

Both user accounts and role accounts are stored using the same data structure, within the Accounts.Dynamic file, which can be found in the application directory.

In most cases, accounts will be created by way of the user interface in the Accounts dialog. You may also add, modify and delete accounts through code, noting that there are security restraints in place on these functions to prevent unauthorized tampering.

While accounts are commonly referred to by name, each account is actually identified by an ID code. You may therefore change the name of an account if needed without losing any of its configuration.


Account Storage

The Security Manager database is held in a file within the application directory named Accounts.Dynamic. The information in this file cannot be read or successfully modified by any means other than the Security Manager user interface. Under no circumstance should any attempt be made to do so. Irreparable damage to your application is likely to result.

There are three sections in the Accounts.Dynamic file:

[SecMgr]

Has only one entry: the version number of the security manager database. This is "201" for the current version of VTScada.

[Accounts]

Stores the information for each user account, in the form used by VTS version 10 and earlier.

[Accounts-200]

Stores the information for each user account, in the form used by VTScada after version 10.0. For applications upgraded from version 10, VTScada will read the information in the [Accounts] section once, then create an [Accounts-200] section containing the same information stored in the new format. After the [Accounts-200] section has been created, VTScada will no longer read the [Accounts] section.

Each entry in the database takes the form, "AccountID = Encoded account definition". Restrictions are in place so that the Accounts.Dynamic file from one application cannot be used in another.


Alternate Identification

Alternate identification for an account may be assigned. The identification is typically a numeric code that operators may use when logging in to the Alarm Notification System.

No two users may have the same alternate ID - each must be unique. The minimum length of the ID is controlled by the Setup.INI property, MinAltIDLength, although a default minimum of four characters will be used if this property has not been set. MinAltIDLength must be added to the [SYSTEM] section.

Trihedral Engineering strongly discourages any reduction in the number of characters required for identification. Any reduction in the number of possible combinations makes it easier for an attacker to compromise your system.

Another possible alternate identification source is a card reader.

At the time of writing, only proximity cards from RF Ideas that support serial port emulation are supported by VTScada.
Readers that use only keyboard emulation are not supported.

Related information:

Configure Alternate Identification

Proximity Card Readers


Roles

A role is a type of account. The purpose of a role is to associate a set of security privileges or rules to a name that can then be associated with user accounts. Roles are meant to define job functions such as "Operator" and "Manager", with all of the security rules required for that job.

User accounts may be assigned multiple roles, gaining the combined privilege sets of all.

This association between a role and a user remains dynamic so that if changes are made to a role's privilege set, all users who have been assigned that role will immediately have their privileges changed.

While a Role is a type of account, roles differ from user accounts as follows:

  • Roles do not have passwords.
  • Roles do have descriptions.
  • It is not possible to sign in to an application using a role name.
  • Automatic time-out periods do not affect roles.
  • Roles do not have alternate ID values.
  • Roles are managed in an area of the Accounts dialog that is separate from the list of user accounts.

A user account can be used as the template for a new role, which will then have all the same privileges, but no continuing link. The reverse is also true.

The Logged Off Role

A role named "Logged Off" will be found in every installation as soon as security is activated. This role is in effect when no other user is signed in. You may use this role to permit a privilege for unrestricted access. For example, you might allow anyone to view the alarm page without first logging in. Take care not to open a security hole in your application by granting unnecessary privileges to this role.

You cannot delete the Logged Off role


Security Rules

Prior to VTS version 10.1, resources in an application were secured using privileges only. A privilege was created, then assigned to an output tag or page. The privilege could then be assigned to a user so that they would have permission to write data with the output tag or open the page. This led to a coarse-grained security model where the only way to increase the granularity of security was to assign new privileges.

VTS version 10.1 introduced the concept of a security rule. Rules are assigned to accounts or roles, not to resources. A rule is composed of three parts:

  • A mandatory privilege number (or a role name, thereby including a set of privilege numbers).
  • An optional scope.
  • An optional workstation name.

A scope is the name of a tag. A rule containing a scope applies to that named tag and all children of that tag. Therefore, scope restrictions should be used only with privileges that apply to tags. If a page is protected by privilege X and a rule is created stating that privilege X is valid only in the scope of tag Y, then no user will have access to the page since pages are not within the scope of tags.

When a check is made to determine if the current user has access to a resource, the privilege number assigned to the resource, the name of the tag associated with that resource and the workstation on which the request is being made are compared against the set of security rules assigned to the user. For a check to pass, all component parts of one of the user’s security rules must match.

Therefore, a rule that has only a privilege number is a "global" privilege - it will match any resource that requires the same privilege number.

A rule that has a privilege number and a scope will only match if the privilege numbers match and the name of the resource or any parent of that resource match the rule’s scope.

A rule that has a privilege number, a scope and a workstation name will only match if the privilege numbers match and the name of the resource or any parent of that resource match the rule’s scope and the request is being made on the same workstation as specified in the rule.

This permits the specification of finer-grained security without the need to expand the set of privileges significantly. The concept can be thought of as a privilege number defining a verb describing the operation (e.g. "control" or "view") and the scope defining a noun on which the verb operates (e.g. "TreatmentPlant"). The Workstation modifier adds a location clause, referring to the operator (e.g. "from OfficeComputer"). If the tag database is organized into a hierarchy, the noun can encompass a collection of tags related by the hierarchy.

Conversion of a 10.0 or earlier VTS security database results in an equivalent set of global rules being generated for each user account.

SecurityCheck determines the tag name of the resource being checked. It searches the caller and its parent scope(s) for the name of a tag by looking for a "Name" variable. When it finds one, it looks up the VTSDB to determine if the value of the found Name variable is indeed the name of a tag. If not, the search continues. If so, the discovered name is used to check the user’s security rules. This search can be bypassed by passing in a valid string to SecurityCheck’s TagName parameter.

If no name is supplied nor can be discovered, only global rules will be able to match the SecurityCheck request, as all parts of a rule must match for a check to be successful.

Widgets and any code called by them that calls SecurityCheck therefore must be careful to ensure that they either supply a TagName parameter to SecurityCheck or that they call SecurityCheck from a child scope of a tag. As most tag-centric widgets do run in tag scope, this is unlikely to be an issue in your code.

Combining Security Roles and Rules

A role is a security account whose purpose is to encompass a named set of security rules. The intent is to provide an easy way to represent a set of commonly assigned security rules. For example, a role named "operator" may have a set of security rules that are commonly assigned to any user that performs the tasks of a plant operator.

A security rule can reference a role instead of a privilege number, thereby allowing a role to be assigned to a user account. As a role is an account, a role can also contain a security rule that references another role, thereby allowing a role such as "engineer" to contain the "operator" role.

Because a security rule has an optional scope and workstation name, a security rule that contains a role can also qualify the role using a scope or workstation name. This enables you to define rules such as an operator for a particular plant area ("operator" - "TreatmentPlant") and even enables you to restrict the workstation at which that rule can be effective.

Where a security rule specifies a role and either or both the optional scope and workstation name, the scope is only applied to security rules within the role that do not explicitly define a scope and, likewise, the workstation name is only applied to security rules within the role that do not explicitly define a workstation name.

Where a role contains a security rule that references another role, scope and workstation name overrides are applied recursively, as described above.Combining Security Roles and Rules


Security Implementation

For every application, the security manager is activated when the application is activated. Applications are activated when an operator requests some action of them (for example, attempting to access the Application Configuration dialog) or, in the case of OEM layers, when a dependent application is activated.

The DisplayManager, the LayerModule and each VIC session all have the concept of a user security session. SecurityManager maintains state information for each user security session via the call tree of any code that makes an API call into SecurityManager.

Making a call from code within that call tree causes SecurityManager to use the security rules for the call tree’s user security session when evaluating permissions.

Making a call from outside such a call tree causes SecurityManager to use the Logged Off role security rules.

If the application is in a secured state, the Security Manager provides a number of variables controlling how security is managed and a set of functions for working with user accounts and checking access privileges.


System Privilege Reference for Programmers

The following is a list of general privileges for the current implementation.

Constants must be preceded by \SecurityManager\ unless you have imported the API as described in The SecurityManager API.

General privilege numbers are <= 0. Custom privilege numbers are >= 16.

The table is complete. Missing values are deprecated privileges.

Related information:

System Privilege Reference for Developers

System Privilege | Constant | Value | Description
Configure | PrivBitConfigure | 0 | Permits access to the Application and Configuration dialog, the Import File Changes button on the VAM and the right to delete applications.
Account View | PrivBitAccountView | -1 | Allows users to view (but not modify) their own privileges.
Account Modify | PrivBitAccountModify | -2 | Allows users to modify their own password, but does not allow them to modify their account privileges.
Accounts Manager | PrivBitManager | -3 | Permits manipulation of the Account List. Allows the user to add, copy, delete, and modify user accounts.
Security Administrator | PrivBitAdministrator | -4 | Permits access to the Administrative Settings dialog and modification of administrative functions. Also required to modify security roles.
Alarm Disable | PrivBitAlarmInhibit | -5 | Allows operators to disable alarms.
Manual Data | PrivBitManualData | -6 | Set or change the Manual Data value of a tag without having the Tag Modify privilege.
Questionable | PrivBitQuestionable | -7 | Change the Questionable flag of a tag without having the Tag Modify privilege.
Alarm Acknowledge | PrivBitAlarmAck | -8 | Allows operators to acknowledge alarms.
Application Stop | PrivBitAppClose | -9 | Allows users to stop the application
Tag Parameter View | PrivBitParamView | -11 | Allows users who do not have the Tag Modify privilege to view tag parameters.
Edit Files | PrivBitEditFiles | -14 | Allows users to change files through the Application Configuration dialog. Also required for the Compile button on the VAM. (Formerly called "Remove File")
Deploy Changes | PrivBitDeploy | -15 | Allows users to perform updates through the Application Configuration dialog.
Revert Changes | PrivBitRevert | -16 | Allows users to perform rollbacks through the Application Configuration dialog.
Page Add | PrivBitPageAdd | -17 | Allows users to add pages through the Idea Studio.
Page Modify | PrivBitPageModify | -18 | Allows users to modify page properties through the Idea Studio.
Page Delete | PrivBitPageDelete | -19 | Allows users to delete pages through the Idea Studio.
Tag Add/Copy | PrivBitTagAddCopy | -20 | Allows users to add or copy tags through the Tag Browser. Tag Modify also required.
Tag Modify | PrivBitTagModify | -21 | Allows users to modify tag properties through the Tag Browser.
Tag Delete | PrivBitTagDelete | -22 | Allows users to delete tags through the Tag Browser.
Thin Client Access | PrivBitInternetClient | -23 | Allows users to make connections to a Thin Client Server using a thin client.
Alarm Mute | PrivBitAlarmMute | -24 | Allows users to use the Mute button on the Alarm page to mute all current and future alarms.
Alarm Silence | PrivBitAlarmSilence | -25 | Allows users to use the Silence button on the Alarm page to silence the sounding alarm.
Group Modify | PrivBitHDVGroupModify | -26 | Allows the user to modify pen groups for the Historical Data Viewer page. If denied, then Group Delete and Group Save are also effectively denied.
Group Save | PrivBitHDVGroupSave | -27 | Allows the user to save pen groups for the Historical Data Viewer page.
Group Delete | PrivBitHDVGroupDelete | -28 | Allows the user to delete pen groups for the Historical Data Viewer page.
Pen Modify | PrivBitHDVPenModify | -29 | Allows the user to modify pen properties for the Historical Data Viewer page.
Note Add | PrivBitNoteAdd | -30 | Allows the user to add notes to a notebook tag using the Historical Data Viewer page.
Alarm Page Access | PrivBitAlarmPageAccess | -31 | Allows the user to access the Alarm page.
Reports Page Access | PrivBitReportsPageAccess | -32 | Allows the user to access the Reports page.
History Page Access | PrivBitHDVAccess | -33 | Allows the user to access the Historical Data Viewer page.
Thin Client Tools Access | PrivBitVICTools | -34 | Deprecated
Thin Client Monitor Access | PrivBitVICMonitorView | -35 | Allows a user at a thin client connection other than the MIC to view the Thin Client Monitor page.
Thin Client Monitor Admin | PrivBitVICMonitorAdmin | -36 | Allows a user at a thin client connection other than the MIC to operate the Thin Client Monitor page.
Page Note Edit | PrivBitPageNoteEdit | -37 | Allows a user to add, edit or delete page notes.
Page Note Hide | PrivBitPageNoteHide | -38 | Allows a user to make page notes hide without deleting them.
Advanced Version Control | PrivBitVersionControl | -39 | Allows a user to switch or revert versions in the Version Log.
Application Manager View | PrivBitVAMView | -40 | Allows users to view the VAM when the Setup.INI property, HideWAM, is set to TRUE.
Manage Tag Types | PrivBitManageTagTypes | -41 | Allows use of "Create new type" and "Redefine type" in the Tag Browser. Allows use of "Manage Types" in the Application Configuration dialog.
Alarm Shelve | PrivBitAlarmShelve | -42 | Enables operators to shelve alarms, leaving them enabled but deactivating all notifications.
Sites Page Access | PrivBitSitesPageAccess | -43 | Allows a user to open a Sites page.
Maps Page Access | PrivBitMapPageAccess | -44 | Allows a user to open a map
Operator Notes Page Access | PrivBitOpNotesPageAccess | -45 | Allows a user to open the Operator Notes page.
Edit Data | PrivBitEditData | -46 | Edit historical data by creating overrides.
Remote Data Access | PrivBitRemoteDataAccess | -47 | User may retrieve data via SOAP or REST
Control Outputs | PrivBitControlOutputs | -48 | Deny output operations for all I/O tags not otherwise protected by a custom privilege.
Global Tag & Area Filter | PrivButUserFilter | -49 | Filter tag and alarm lists by tag name and by area.
Recipe Edit | PrivBitRecipeEdit | -50 | Change recipes
Batch Run | PrivBitBatchRun | -51 | Start recipe batches
Recipe Page Access | PrivBitRecipePageAccess | -52 | Open the Recipe & Batch Management Page
Edit Roster Contacts | PrivBitEditRosterContacts | -53 | Edit contacts in Roster tags.
Remote Tag Value / History Retrieve | PrivBitRemoteTagHistRetrieve | -54 | Restricts access to the main History table when making remote queries. (Access to defined SQL Views can permitted on a tag-by-tag basis.)
Services Page Access | PrivBitServicesPageAccess | -55 | User may access the Services page
Server Change | PrivBitSwitchServers | -56 | User may force a service to change servers
Lock Add/Remove | PrivBitLockAddRemove | -57 | User can create Control Locks and can remove Control Locks over which the user has "ownership"
Lock Admin | PrivBitLockAdmin | -58 | User can remove any Control Lock
Token Request/Release | PrivBitTokenRequestRelease | -59 |
Token Admin | PrivBitTokenAdmin | -60 | Able to release a control token from any tag.

Three other constants are defined, which are duplicates of values in the above table. These exist for backward compatibility.

PrivBitRemoveFile == PrivBitEditFiles

PrivBitUpdate == PrivBitDeploy

PrivBitRollback == PrivBitRevert


Custom Privileges

Custom privileges are those that developers create for a given application. They are generally used to restrict access to custom pages and output tags. While general privileges control such actions as acknowledging alarms and adding pages, it is the job of Custom Privileges to restrict access to developer-created pages and writing to output tags.

Every custom privilege will have an index number, starting at 16. Also, every custom privilege is enumerated in the configuration file, Settings.Dynamic with values starting at zero. When writing expressions that check privileges, add 16 to the enumerated value in Settings.Dynamic.

The first variable in this section, PrivBitsTotal, is a count of the current number of custom privileges. For each privilege, the number following the name controls the order in which the privileges will be displayed in the user interface.

Separator lines for the user interface are stored using the format, "PrivSepDesc0 = -- Description, 1".

For example, the following set of privileges:

<SECURITYMANAGER-PRIVAPP>
  PrivBitsTotal                    = 2
  PrivDesc0                        = PageAccess, 0
  PrivDesc1                        = StationAccess, 1

Matches this set in the Privileges dialog.


The SecurityManager API

The SecurityManager API definitions can be imported into your application by calling:

System.ImportAPI(\SecurityManager);

The effectively includes the definitions in the calling module allowing you to omit the \SecurityManager prefix when accessing these variables. For example:

\SecurityManager\PrivBitManager

can be simply written:

\PrivBitManager

You should check the return value of ImportAPI. It returns the number of variable name clashes that occurred when the import was attempted. Zero is therefore a successful result.

Note that the following restrictions are in place:

  • The API calls will use the security context of the caller to verify that the user has Manager privilege. Any calls made from a user that is not so privileged will fail and a security event will be logged.
  • The API calls only operate on the security database associated with the security context of the caller, thereby preventing interference from another application or system level code.


AccountData Structure

Information about each account (both user accounts and roles) is stored in the following structure:

    AccountData Struct [
      AccountID               { Unique ID of this account                 };
      AccountName             { Unique name of this account               };
      Password                { Password - only used for user accounts    };
      AltID                   { Alternate ID - user accounts only         };
      AutoLogoff              { Automatic log-off timeout - user a/c only };
      PWDate                  { Password creation date - user a/c only    };
      Rules                   { Array of SecurityRule structures          };
      IsRole                  { TRUE if account is a role, else user      };
      Disable                 { TRUE to disable this account              };
      Description             { Textual description of this account       };
      CustomData              { Uncommitted field for application data    };
      PWCreationTS            { Timestamp of password creation            };
      Language                { User preferred language                   };
    ];

API module calls that require an AccountData structure for an existing account must provide a valid AccountID. An AccountID is a text value whose length is specified in the imported API constant AccountIDLength.

AccountName | Holds the unique name of the account, including any namespace (group) prefix, separated by your application’s configured NameSpaceDelimiter character. You may change an account name, which is why the API requires the immutable AccountID for all operations on an existing account.
Password

Accounts only, not roles. Any supplied passwords are given as plain text but must conform to the application-configured password strength requirements.

You are strongly advised to clear any variable holding a plain text password immediately after adding a new account.

The GetAccount function will never return a password as part of the AccountData structure.

AltID | User accounts only. This is the alternate account identification used by such subsystems as the Alarm Notification System.
AutoLogoff | User accounts only. It specifies the time, in minutes, after which a user session using this account will be signed out if there is no UI activity. This overrides the application configured global AutoLogoff value.
PWDate | User accounts only. This is the date on which the current password was created. It is used to enforce password change after a period of time. When creating an account, an Invalid value automatically sets the PWDate to today. If set to zero, it forces the user to change their password when they next sign in.
Rules | An array of SecurityRule structures, one per rule. If Invalid, the user or role has no privileges whatsoever.
Disable | A Boolean value, defaulting to FALSE. If set to TRUE, the account is disabled. If this is a user account, the user cannot sign in and, if already signed in, is immediately signed out. If this is a role, its security rules are disabled.
Description | Role accounts only. The purpose is to provide a meaningful description of the purpose of a role. Defaults to Invalid.
CustomData | Not used by SecurityManager. It is provided for application use to store any account-specific data it chooses. The data must either be text or numeric. If you need to store more complex data, serialize it into text before storing.


SecurityRule Structure

The SecurityRule definition is used by the API to represent the content of a security rule. The structure is part of the imported API. It has the following format:

    SecurityRule Struct [
      PrivRole                { Privilege number or role account ID       };
      TagName                 { Name of a point in the tag tree           };
      Workstation             { Name of a workstation for this rule       };
      Disable                 { TRUE to disable the rule                  };
    ];
PrivRole Must be valid and contain any of
  • A system-defined privilege number (examine the PrivBit… constants in the imported API).
  • An application defined privilege (defined in your Settings.Dynamic file at starting at a value of 16, for historical reasons)
  • The AccountID of a role or the name of a role. If a role name is specified, SecurityManager will convert this to an AccountID. Even if the role does not yet exist, it will convert this to an AccountID when the role becomes valid.
TagName | May be Invalid, in which case it does not play a part in the rule evaluation. Otherwise, this is the name of a tag, defining the scope in which the rule will permit access.
Workstation | May be Invalid, in which case it does not play a part in the rule evaluation. Otherwise, this is the name of a workstation that the account must be signed in at in order for the rule to permit access.
Disable | Defaults to FALSE. If set to TRUE, the rule is disabled. Any logged-on accounts using this rule will immediately have this rule disabled.


Security Manager Return Codes

The account manipulation methods all provide a return code that is one of the #SMAPIErr values defined in the imported API:

Constant #SMAPIErrSuccess     = 0 { Successful result                     };
Constant #SMAPIErrNoUser      = 1 { User doesn't exist                    };
Constant #SMAPIErrNeedManager = 2 { Caller did not have Manager privilege };
Constant #SMAPIErrUserExists  = 3 { User already exists - can't add again };
Constant #SMAPIErrBadParm     = 4 { Bad parameter                         };
Constant #SMAPIErrNotEditable = 5 { The application is not editable       };
Constant #SMAPIErrPwdTooWeak  = 6 { Password is too weak                  };

Note that GetAccountInfo (described in the Query Module Calls) is useful in obtaining account information in the same format as is required by ModifyAccount and DeleteAccount. The error code can be converted to text e.g. for error display purposes by calling UIErrorToText().


Security Manager Functions

Four modules make up the Security Manager API, each containing its own set of function calls. In all cases, the function call must start with \SecurityManager\

Account Manipulation Methods

AddAccount | Creates a new account.
ModifyAccount | Modifies an existing account.
DeleteAccount | Removes an account.

Query Module

SecurityCheck | Examines the rules that apply to the current user or the named user to determine if the specified privilege has been granted.
BuildFullName | If a namespace and namespace delimiter are being used, returns the full, namespace-qualified name of the specified account.
GetFullName | Returns the full, namespace-qualified name of the caller's account.
GetGroupName | Returns the namespace of the caller's account.
GetUserName | Returns the user name of the caller's account.
GetAccountID | Returns the account ID of the named account.
GetAccountInfo | Returns one or more AccountData structures.
IsLoggedOn | Returns TRUE if the calling user is signed in, else FALSE.
IsSecured | Returns TRUE if the application has any user accounts defined, else FALSE.
IsSuspended | Returns TRUE if the user's account is suspended, else FALSE.
UIErrorToText | Returns a text string corresponding to the error code provided.

VTScada Authentication Module

AlternateLogon | Either creates, or attempts to sign in using an alternate ID value. See comments.
AlternateLogoff | Synonym for LogOff().
Authenticate | Authenticates the Namespace, UserName and Password.
QuietLogon | Authenticates the authorization token (AuthToken) and, if successful logs the calling user session on as the user specified in the AuthToken.
LogOff | Logs the calling user session off.
UserCredChange | The return value will increment each time there is a change in the user session's logged-in user or their password.

Windows Authentication Module

UserLogonDialog | Returns the string value of the LDAP default naming context for the host machine domain.
WindowsLogon | Authentication request to Windows Authentication services.

User Interface Module

UserLogonDialog Launches the Sign in dialog.


Security Manager Public Variables

The following public, read-only variables are available for applications to examine:

InitComplete | Boolean. Set TRUE when you can call APIs that do not require accounts and settings to be loaded. Intended for system internal use only.
Ready | Boolean. Set TRUE when you can call APIs that do require accounts and settings to be loaded. Intended for general use.
Started | Same as Ready. For backwards compatibility.
SecMgrStatus | Artificial RPC status value for backwards compatibility. Always set to #RPCServer (2) when Ready is TRUE.


Security Plug-in Modules

Plug-in modules allow users to override default behaviors in VTScada applications. To override these modules, users can declare replacement modules in the PLUGINS section of the VTScada application's AppRoot.src source file.

The Security Manager recognizes two plug-in modules:

SecAlarm (SecAlarm.src)

The SecAlarm plug-in is responsible for alarm generation as prompted by security-related events.

SecDenied (SecDeny.src)

The SecDenied plug-in is responsible for displaying the feedback dialog that appears when a security check fails.


Security Event Logging

Information is logged on every security-related event witnessed by the Security Manager, including (but not limited to):

    Sign in/logoff events

    Account manipulation events

This information is used mainly as a form of feedback. You may view this logged information in the History list on the Alarm page.

Note that, in the case of Advanced, logging takes place only in the application that runs the security alarm module.


Security NameSpaces

You may subdivide security accounts into name spaces. This is required when using Realm Filtering. When namespaces are in use, the Sign in dialog will query users for their group name as well as their user name and password. Namespaces are therefore sometimes referred to as security groups.

A given namespace can be associated with one or more tag Area properties. The result is that the users belonging to that security group will only be able to access the tags belonging to the assigned areas. This functionality can be organized using security name spaces in combination with realm filtering (security name spaces on their own are not sufficient to segregate user data). For example, you may use security name spaces and realm filtering together in applications where you must restrict sets of users to specific sets of pages or subsets of data, and where managers or administrators must be able to oversee their own user base, but should be unaware of any other end-users.

Two variables in the Settings.Dynamic <SECURITYMANAGER-ADMIN> section are associated with security name spaces. These are:

<SECURITYMANAGER-ADMIN>
NameSpaceDelimiter =
GroupLogin =

Set GroupLogin to 1 to enable group logins, and NameSpaceDelimiter to one or two characters that will be used as the delimiter. A colon ":" is commonly used as the delimiter.

NameSpaceDelimiter

The NameSpaceDelimiter application property enables you to specify the character (or characters) you wish to be used by managers setting up security groups. The recommended characters for NameSpaceDelimiter are two colons, however, you may use any characters you deem appropriate. The assigned character (or characters) must then separate the name of the security group from the username of the user belonging to that group when a new security account is added to your application.

The following image displays the Add Account security dialog when a group is being specified for a new user. As you can see from this example, a colon has been assigned as the NameSpaceDelimiter.

GroupLogin

The GroupLogin application property enables you to add a third field to the Sign in dialog that opens when the Sign in button in the Display Manager's title bar is clicked. This third field is the Group field, which enables users to specify the group to which their user account belongs when they logon to an application. To include the Group field in the Sign in dialog, you must set GroupLogin to 1.

The following image on the left displays the Sign in dialog when GroupLogin has been set to 0 (its default value), while the following image on the right displays the Sign in dialog when GroupLogin has been set to 1.

When signing in, users must enter the name of the security group to which they have been assigned in the Group field.

A super user (one who has not been assigned to any group) may leave the Group field blank, and can logon as they normally would, by entering their username in the Username field, and their password in the Password field.

Super users cannot sign in via the VIC unless extra configuration is done as follows:

  • The RootNamespace Settings.Dynamic variable has to be set to a value for the super user realm, which is different from all other configured realms. The value of RootNamespace must not match any defined security realm.
  • That realm must be configured in the Internet settings dialog with the required application listed.

The URL used to sign in becomes "http[s]://servername/superrealm" where superrealm is the name assigned to RootNamespace and configured in Internet settings. A super user can then sign in using their (non-namespace) username and password

If security realms are enabled, managers who are members of a realm can see only those accounts and roles that are within the same realm.
If using security realms, it is important that you keep one manager account with no realm membership.


Socket Server Manager

This service is designed to manage inbound TCP/IP and UDP/IP sockets that are shared by multiple drivers. It was modeled after the Modem Manager and uses the same discriminator driver interfaces. Inbound socket streams are passed to this service so that the stream will be given to the appropriate driver instance.

There is one publicly accessible variable: SocketServerManager\Started will be true when the service has started.

Socket Server Manager - Error Logging

Errors are logged to a text file named "SocketServerEvents.log". Two application properties are available to control what is logged:

\SSMLogConnectFail When set to TRUE, the manager will log failed connection attempts.

\SSMLogConnectSuccess When set to TRUE, the manager will log successful connection attempts.

Both properties will default to FALSE.


SocketManagerServer ArrayToString

Viewing: Scripting > Services (Alarm, Historian, etc.) > Socket Server Manager > SocketManagerServer ArrayToString

SocketServerManager\ArrayToString

Description: | Utility function to pack an array of filtering addresses into a single string. The elements will be delimited using semicolons. Wrapper for JoinStrings.
Returns: | Text
Usage: | Script
Function Groups: | Stream and Socket
Format: | \SocketServerManager\ArrayToString(AddressArray)
Parameters: |
AddressArray
Required. An array of IP addresses, where each array element is a text value.
Comments: None.


SocketServerManager Register

Viewing: Scripting > Services (Alarm, Historian, etc.) > Socket Server Manager > SocketServerManager Register

SocketServerManager\Register

Description | Register a station with a group.
Returns | Invalid when complete
Usage | Script
Function Groups | Stream and Socket
Format | \SocketServerManager\Register(Context, StationKey, GroupName[, IPAllowString])
Parameters |
Context
Required. The context should be the root tag. This must include Discriminator() and Context() subroutines.
StationKey
Returned by Discriminator() in the root tag. A unique string that has meaning only VTScada, used to identify a particular station.
GroupName
The name of an IPListener tag (or group). This will be the source of the new data streams.
IPAllowString
An optional string. If valid, inbound connections will be restricted as specified. May be a partially specified address to allow a range of connection IP addresses. The string is one or more semicolon delimited IP addresses (or address ranges)
Comments Public subroutine used by modules that are to receive inbound connections. This is intended for, but not limited to, VTScada driver tags.

Users should wait until \SocketServerManager\Started is true before attempting to use the Register or Unregister functions.

GroupName defines a group containing driver tags and server socket tags. Typically the name of an IP Network Listener. Groups are for use by advanced VTScada programmers, allowing them to associate multiple IP Network Listeners.

Context provides the context for the discriminator calls. The StationKey must be unique within the StationList of a GroupNode\DiscrimNode.

The Station context must have Discriminator() and Connect() callbacks. The Discriminator module takes a sample of incoming data and returns a station key if it can understand the protocol. The Connect module will be called on the exact station context as indicated by the station key. Connect must return (a) the workstation name of the station server and (b) the object value of a context implementing an ExternalSocketConnect callback. This was intended for, but is not limited to, TCP/IP and UDP/IP port tags.

The service will not Connect() to a station unless the IP address of the remote stream passes an optional IPAllowString filter check. Utility functions ArrayToString() and StringToArray are provided in the SocketServerManager to ensure that the addresses are provided in the correct format, but in general, you can rely on the result returned from a pIPAddressList() widget, used in the tag configuration.

A station must be UnRegistered when about to change the StationKey or GroupName. The IPAllowString can be updated by calling register again.

Example:

[
  ActiveDevAddr  {PLC address to use in reads & writes                    };
  ListenerGroup  {SocketServerManager group to join                       };
  IPAddressAllow { Semicolon delimited string of IP addresses (or ranges
                        which can connect to this station                 };
]
Init [
  If Valid(Name) && \SocketServerManager\Started &&
     Watch(1, ActiveDevAddr, ListenerGroup, IPAddressAllow);
  [
    CriticalSection(
      IfThen(Valid(ActiveDevAddr) != Valid(RegDevAddr) ||
             ActiveDevAddr != RegDevAddr               ||
             Valid(ListenerGroup) != Valid(RegGroup)   ||
             ListenerGroup != RegGroup,
        \SocketServerManager\Unregister(Root, RegDevAddr, RegGroup);
      );
      RegDevAddr = ActiveDevAddr;
      RegGroup   = ListenerGroup;

       { Register with SocketServerManager }
      \SocketServerManager\Register(Root, RegDevAddr, RegGroup, IPAddressAllow);
    );
  ]
]


SocketManagerServer StringToArray

Viewing: Scripting > Services (Alarm, Historian, etc.) > Socket Server Manager > SocketManagerServer StringToArray

SocketServerManager\StringToArray

Description | Utility function to expand a semicolon-delimited string of IP addresses into an array of individual strings Wrapper for SplitString
Returns | Array of text
Usage | Script
Function Groups | Stream and Socket
Format | \SocketServerManager\StringToArray(AddressString)
Parameters |
AddressString
Required. A text string of IP addresses, where each address is delimited from the next by a semicolon.
Comments None.


SocketServerManager UnRegister

Viewing: Scripting > Services (Alarm, Historian, etc.) > Socket Server Manager > SocketServerManager UnRegister

SocketServerManager\UnRegister

Description: | Unregister a station from a group. The station must be unregistered whenever GroupName, or StationKey changes.
Returns: | Invalid when complete
Usage: | Script
Function Groups: | Stream and Socket
Format: | \SocketServerManager\UnRegister(Context, StationKey, GroupName)
Parameters: |
Context
Required. The context should be the root tag. This must have Discriminator() and Context() subroutines.
StationKey
Returned by Discriminator() in the root tag. An opaque string used to identify a particular station.
GroupName
The name of an IPListener tag (or group). This will be the source of the new data streams.
Comments: Users should wait until \SocketServerManager\Started is true before attempting to use the Register or Unregister functions.

Example:

ActiveDevAddr{PLC address to use in reads & writes                    };
ListenerGroup{SocketServerManager group to join                       };
IPAddressAllow{ Semicolon delimited string of IP addresses (or ranges
                        which can connect to this station};
  If Valid(Name) && \SocketServerManager\Started && Watch(1, ActiveDevAddr, ListenerGroup, IPAddressAllow);
  [
    CriticalSection(
      IfThen(Valid(ActiveDevAddr) != Valid(RegDevAddr) || ActiveDevAddr != RegDevAddr ||
             Valid(ListenerGroup) != Valid(RegGroup)   || ListenerGroup != RegGroup,
        \SocketServerManager\Unregister(Root, RegDevAddr, RegGroup);
      );
      RegDevAddr = ActiveDevAddr;
      RegGroup   = ListenerGroup;

       { Register with SocketServerManager }
      \SocketServerManager\Register(Root, RegDevAddr, RegGroup, IPAddressAllow);
    );
  ]


Time Synchronization Manager Service

The Time Synchronization Manager Service synchronizes client clocks with the configuration server’s clock.

Method

The Time Synchronization Manager Priority Service synchronizes time for a VTScada application as soon as the application is started. Clients then independently request time updates from the server both on startup and periodically (as defined by theTimeSyncUpdtItrvl application property). The server responds to these requests as they are received.

If synchronization with a centralized provider is required, configure the server to do so using the Windows® configuration tools.

The client transmits five update requests (in the form of GetTime calls) through RPC to the server. The server responds to each GetTime call with a SetTime RPC call that includes the server’s current time in UTC. The client calculates the round trip time for each request/response, and will select the most expedient (i.e. the shortest request/response time).

After the client chooses the shortest round trip response time, the client’s time delta from the server is calculated, taking the client’s timezone into consideration.

Delta Tolerance

The delta tolerance is equal to the round trip time, with 0.5 seconds as the minimum delta. The synchronization interval is 15 minutes (900 seconds), as defined by the TimeSyncUpdtItrvl application property.

If the time delta is 1 second, then the client’s clock is changed by 10 milliseconds every second. The client will then be in sync after 100 seconds, but any logs done on time won’t show any visible discontinuity. The client’s clock will immediately be adjusted if the delta exceeds 5 seconds.

Special Considerations for Time Adjustments

The following scenarios will cause the Time Synchronization Manager to abort a time adjustment to a client:

  • If adjusting the client’s clock would result in rolling the client’s data back to a previous day, the time adjustment will not occur, as doing so would have a detrimental effect on data logging, especially at the first day of a month, as the rollback would then be to the previous month.
  • The client’s clock will also not be adjusted if the delta from the server is less than a configurable tolerance (relative to the roundtrip time of the request). For example, if a roundtrip takes a whole second, the server’s timestamp will not be very precise, so the client’s clock will not be adjusted unless the delta is > 0.5 seconds.
  • The client’s clock will not be adjusted if the roundtrip time exceeds 10 minutes.
  • The client’s clock will not be adjusted if the server’s RPC queue (which takes priority) exceeds a user-defined value (as defined by the TimeSyncRPCQMax application property).
  • No time synchronization will take place if the TimeSyncEnable application property is set to 0 (disabled).


Cryptography in VTScada

This section provides architectural, programming, and other information on the implementation and use of cryptography in VTScada. It is aimed at both VTScada programmers and advanced engineers performing system configuration, and assumes knowledge of cryptography concepts.


Cryptography Terms and Abbreviations

BLOB | A generic sequence of bits that contain one or more fixed-length header structures plus context-specific data.
Ciphertext | A message that has been encrypted.
CryptoAPI | An application programming interface that provides services that enable application developers to add cryptography-based security to applications.
Cryptographic key | The session (symmetric) key used during the encryption and decryption processes, and the public and private keys used during the authentication process. Of these three keys, the session key and private key must always remain secret.
Cryptography | The art and science of information security. It includes information confidentiality, data integrity, entity authentication, and data origin authentication.
CSP Cryptographic Service Provider | An independent software module that actually performs cryptography algorithms for authentication, encoding, and encryption.
Decryption | The process in which ciphertext is converted to plaintext.
Encryption | The process in which data (plaintext) is translated into something that appears to be random and meaningless (ciphertext). Ciphertext is difficult to unscramble without a secret key.
Key BLOB | BLOB containing an encrypted private key. Key BLOBs provide a way to store keys outside the CSP.
Key container | A part of the key database that contains all the key pairs (exchange and signature key pairs) belonging to a specific user. Each container has a unique name that is used when calling GetCryptoProvider to get a handle to the container.
Plaintext | A message that is not encrypted. Plaintext messages are also referred to as cleartext messages.
Public/private key pair | A set of cryptographic keys used for public-key cryptography.
Public-key algorithm | An asymmetric cipher that uses two keys, one for encryption, the public key, and the other for decryption, the private key. As implied by the key names, the public key used to encode plaintext can be made available to anyone. However, the private key must remain secret. Only the private key can decrypt the ciphertext. The public-key algorithm used in this process is slow (on the order of 1, 000 times slower than symmetric algorithms), and is typically used to encrypt session keys or digitally sign a message.
Session key | A key used primarily for data encryption and decryption. Session keys are typically used with symmetric encryption algorithms where the same key is used for both encryption and decryption. For this reason, session and symmetric keys usually refer to the same type of key. A session key consists of a random number of approximately 40 to 2000 bits.
Symmetric encryption | Encryption that uses a single key for both encryption and decryption. Symmetric encryption is preferred when encrypting large amounts of data. Some of the more common symmetric encryption algorithms are RC2, RC4, and Data Encryption Standard (DES).
Symmetric key | A single key, typically a session key, used for both encryption and decryption.
Block cipher | A cipher algorithm that encrypts data in discrete units (called blocks), rather than as a continuous stream of bits. The most common block size is 64 bits. For example, DES is a block cipher. Block ciphers are considered more secure than stream ciphers, however, block ciphers tend to execute much slower.
Stream cipher | A cipher that serially encrypts data, one bit at a time.
Initialization vector (IV) | A sequence of random bytes appended to the front of the plaintext before encryption by a block cipher. Adding the initialization vector to the beginning of the plaintext avoids the chance of having the initial ciphertext block the same for any two messages. For example, if messages always start with a common header (a letterhead or "From" line) their initial ciphertext would always be the same, assuming that the same cryptographic algorithm and symmetric key was used. Adding a random initialization vector keeps this from happening.

Related information:

Cryptography Terms and Abbreviations

Cryptography Architecture

Cryptographic Service Providers

Cryptographic Keys

Data Encryption and Decryption

Cryptography Example

Related Functions:

Decrypt | DeriveKey | Encrypt
ExportKey | GetCryptoProvider | GenerateKey
GetKeyParam | ImportKey | SetKeyParam


Cryptography Architecture

VTScada supports cryptography by means of the Microsoft CryptoAPI (further details on the CryptoAPI may be found with MSDN).

At present VTScada only provides access to a limited portion of the CryptoAPI, but this is sufficient to generate keys to encrypt and decrypt data.

Application developers can use the VTScada cryptography functions without knowing details of the underlying implementation, in much the same way as they can use a graphics library without knowing anything about the particular graphics hardware configuration. The MS CryptoAPI works with a number of cryptographic service providers (CSP) that perform the actual cryptographic functions.

Data encryption transforms a message written in plain text (called "plaintext" in the cryptography community) so that it appears as random gibberish. A good data encryption system makes it difficult to transform encrypted data back to plaintext without a secret key. The data to be encrypted can be ASCII text, a database file, or any other data you want to store or transmit securely. In this documentation, the term "message" is used to refer to any piece of data, "plaintext" refers to data that has not been encrypted, and "ciphertext" refers to data that has been encrypted.

Encrypted data can be stored on non-secure media or transmitted over a non-secure network and still remain private. Later, the data can be decrypted into its original form.

Data encryption and decryption are simple processes. When data is encrypted, an encryption key is used. This key is comparable to a physical key that is used to lock a padlock. To decrypt the data, a decryption key is be used. The decryption key is comparable to using a key to unlock a padlock. Encryption and decryption are often done using the same key, but unlike working with physical keys, sometimes encryption and decryption can use different keys from a public/private key pair.

Encryption keys must be kept secret and safe, and must be transmitted securely to other users. This is discussed further in Data Encryption and Decryption. The main challenge is properly restricting access to the decryption key because anyone who possesses it will be able to decrypt all messages that were encrypted with its corresponding encryption key.


Cryptographic Service Providers

The first CryptoAPI function called by an application that uses any cryptographic APIs is the GetCryptoProvider function. This function returns a handle to a particular cryptographic service provider (CSP) that includes the specification of a particular key container within the CSP. This key container is either a specifically requested key container or it is the default key container for the logged-on user. GetCryptoProvider can also create a new key container.

A cryptographic service provider (CSP) has both a name and a type. For example, the name of one of the CSPs shipped with the operating system is Microsoft Base Cryptographic Provider. It is a PROV_RSA_FULL type provider. The name of each provider is unique, but the provider type is not.

When an application calls GetCryptoProvider to obtain a CSP handle, it specifies a provider type and, optionally, a provider name. If both a type and a name are specified, the function loads the CSP with the matching provider type and provider name. The function returns the CSP's handle that provides access to both the CSP and to a key container within the CSP.

When an application calls GetCryptoProvider and specifies a provider type but no provider name, the function looks for a named provider, first checking a list of default named providers associated with the logged-on user and, if that fails, from a list of default named providers associated with the computer. After the provider name has been determined, the GetCryptoProvider function searches for the CSP for that provider, loads it, and returns its handle.


Cryptographic Keys

Cryptographic keys are central to cryptographic operations. They must be kept secret because whoever possesses a given key has access to any data with which the key is associated. For example, if a key is used to encrypt a file, anyone with a copy of that key can decrypt the file.

There are two types of cryptographic keys: Session Keys and Public/Private Key Pairs.

Session Keys

Session keys, also called symmetric keys, are used with symmetric encryption algorithms. Symmetric algorithms are the most common type of encryption algorithm. They are called symmetric because they use the same key for both encryption and decryption. Session keys are often changed, usually using a different session key for each message encrypted.

Symmetric algorithms are faster than public-key algorithms. Thus, they are preferred when encrypting large amounts of data. Some of the more common symmetric algorithms are RC2, RC4, and the Data Encryption Standard (DES).

Session keys are created by applications using the GenerateKey function.

Because a good deal of the activity involving session keys relates to keeping them secret, it is important to keep the number of people who possess a particular session key as small as possible (one or two people is recommended.) These keys are kept internal to the CSP for safekeeping.

Unlike public/private key pairs, session keys are volatile. Applications can save these keys for later use or for transmission to other users by using the ExportKey function to export them from the CSP into application space in the form of an encrypted "key BLOB". The key BLOB may then be imported by another application using the ImportKey function.

Public/Private Key Pairs

Public/private key pairs are used for a more secure method of encryption called asymmetric encryption. Asymmetric encryption is used mainly to encrypt and decrypt session keys and digital signatures. Asymmetric encryption uses public-key encryption algorithms.

Public-key algorithms use two different keys: a public key and a private key. The private key member of the pair must be kept private and secure. The public key, however, can be distributed to anyone who requests it. When one key of a key pair is used to encrypt a message, the other key from that pair is required to decrypt the message. Thus if user A's public key is used to encrypt data, only user A (or someone who has access to user A's private key) can decrypt the data. If user A's private key is used to encrypt a piece of data, only user A's public key will decrypt the data, thus indicating that user A (or someone with access to user A's private key) did the encryption.

Unfortunately, public-key algorithms are very slow, — roughly 1, 000 times slower than symmetric algorithms. It is impractical to use them to encrypt large amounts of data. In practice, public-key algorithms are used to encrypt session keys. Symmetric algorithms are used for encryption/decryption of most data.

All keys in CryptoAPI are stored within CSPs. CSPs are also responsible for creating the keys, destroying them, and using them to perform a variety of cryptographic operations.

Storage and Exchange of Cryptographic Keys

There are situations where keys must be exported from the secure environment of the cryptographic service provider (CSP) into an application's data space. Keys that have been exported are stored in encrypted key BLOB structures.

There are two specific situations where it is necessary to export keys:

  • To save a session key for later use by an application, if, for example, an application has just encrypted a database file to be decrypted at a later time. The application is responsible for storing the encryption key. This is necessary because CSPs do not preserve symmetric keys from session to session.
  • To send a key to someone else. This would be easier if the respective CSPs could communicate directly, but they cannot. Because CSPs can't communicate, the key has to be exported from one CSP, transmitted to the destination application, and then imported into the destination CSP. This process can become more complicated if the communication path is not trusted.


Data Encryption and Decryption

Encryption is the process of translating plain text data (plaintext) into something that appears to be random and meaningless (ciphertext). Decryption is the process of converting ciphertext back to plaintext.

To encrypt more than a small amount of data, symmetric encryption is used. The symmetric key or session key is used during both the encryption and decryption processes. To decrypt a particular piece of ciphertext, the key that was used to encrypt the data must be used. Essentially, a session key consists of a random number, from 40 to 2,000 bits in length. The longer the key, the more difficult it is to decrypt a piece of ciphertext without possessing the key.

The goal of every encryption algorithm is to make it as difficult as possible to decrypt the generated ciphertext without using the key. If a really good encryption algorithm is used, there is no technique significantly better than methodically trying every possible key. Even a key size of just 40 bits works out to just over one trillion possible keys.

It is difficult to determine the quality of an encryption algorithm. Algorithms that look promising sometimes turn out to be very easy to break, given the proper attack. When selecting an encryption algorithm, it is often a good idea to choose one that has been around for a while, and has successfully resisted all attacks.

Data is encrypted using the Encrypt function and decrypted using the Decrypt function. If the data is too big to fit into memory it can be split into smaller chunks and can be processed using multiple calls to Encrypt and Decrypt.


Cryptography Example

Viewing: Scripting > Cryptography in VTScada > Cryptography Example

Concept Information

DeriveKey

Encrypt

ExportKey

GenerateHMAC

GenerateKey

GenerateSignature

GetCryptoProvider

GetKeyParam

ImportKey

SetKeyParam

Cryptography Example

A handle to a cryptographic service provider (CSP) is obtained using the GetCryptoProvider function. This returns a variable that contains a small wrapper for the CSP handle. The wrapper is necessary to ensure the CSP handle is correctly released when it is no longer referenced.

Calling the GenerateKey function creates a variable that contains a handle to a key. The variable may be copied which generates a duplicate of the key.

Properties of the key may be read and set using the GetKeyParam and SetKeyParam functions respectively.

To transfer secret session keys, the ExportKey and ImportKey functions are used.

Data is encrypted and decrypted using the Encrypt and Decrypt functions.

Example:

[
{ Variables and Constants for CSP }
   CSP;
   CSPFail;
   Constant CRYPT_EXPORTABLE = 0x00000001;
   Container = "VTS";
   Constant PROV_DSS_DH = 13;
   Constant CRYPT_NEWKEYSET = 8;
   Constant NTE_BAD_KEYSET = 0x80090016;
{ Items for key generation }
   Key1;
   Key2;
   Constant CALG_DH_EPHEM = 0xAA02;
   Constant KEY_SIZE = 512;
   Constant CRYPT_PREGEN = 0x00000040;
{ Items for key parameter set }
   Constant KP_PERMISSIONS = 6;
{ Items for key parameter get/set }
   KeyP;
   KeyG;
   Constant KP_P = 11 { DSS/Diffie-Hellman P value };
   Constant KP_G = 12 { DSS/Diffie-Hellman G value };
   Constant KP_Q = 13 { DSS Q value };
   Constant KP_X = 14 { Diffie-Hellman X value };
   Constant KP_Y = 15 { Y value };
{ Items for export/import }
   PubKey1;
   PubKey2;
   Constant PUBLICKEYBLOB = 0x6;
   Key3;
   Key4;
{ Algorithm conversion }
   Constant KP_ALGID = 7;
   Constant CALG_RC4 = 0x6801;
{ Variables for encryption / decryption }
   PlainText1 = "abcdefghijklmnopqrstuvwxyz0123456789";
   CipherText1;
   PlainText2;
]
Init [
   If 1 Main;
   [
      { Get the CSP }
      CSP = GetCryptoProvider(PROV_DSS_DH, Invalid, Container, Invalid, CSPFail);
      IfThen(CSPFail == NTE_BAD_KEYSET,
      { Not used this container before, make a new one }
         CSP = GetCryptoProvider(PROV_DSS_DH, Invalid, Container, CRYPT_NEWKEYSET, CSPFail);
      );

      { Make a key }
      Key1 = GenerateKey(CSP, CALG_DH_EPHEM,  KEY_SIZE << 16 || CRYPT_EXPORTABLE);

      { Get the key parameters }
      KeyG = GetKeyParam(Key1, KP_G);
      KeyP = GetKeyParam(Key1, KP_P);

      { Make another key using the parameters }
      Key2 = GenerateKey(CSP, CALG_DH_EPHEM, (KEY_SIZE << 16) || CRYPT_PREGEN);
      SetKeyParam(Key2, KP_G, KeyG);
      SetKeyParam(Key2, KP_P, KeyP);
      SetKeyParam(Key2, KP_X);

      { Export the public keys from both keys, and import to each other }
      PubKey1 = ExportKey(Key1, PUBLICKEYBLOB);
      PubKey2 = ExportKey(Key2, PUBLICKEYBLOB);
      Key3 = ImportKey(CSP, PUBLICKEYBLOB, PubKey1, Key2);
      Key4 = ImportKey(CSP, PUBLICKEYBLOB, PubKey2, Key1);

      { Now convert the shared secret key to the bulk encryption key }
      SetKeyParam(Key3, KP_ALGID, CALG_RC4);
      SetKeyParam(Key4, KP_ALGID, CALG_RC4);

      { Now use the keys to encrypt and decrypt some data }
      CipherText1 = Encrypt(Key3, PlainText1, 1, 0, 0);
      PlainText2 = Decrypt(Key4, CipherText1, 1, 0, 0);
   ]
]

The sample code demonstrates instantiating a CSP, generating two public / private key pairs, exporting the public parts of the keys, importing the public keys to create two new keys that have a shared secret, converting the resulting keys to a symmetric key and encrypting and decrypting data. For the sake of clarity, error handling is not shown.

Some points to note are:

  • Many parameters to the Cryptography functions and statements are constants that are defined in WinCrypt. The functions and statements do not interpret these values, but pass them directly to the CryptoAPI. This enables all the current and any new features of the CryptoAPI to be used without having to modify engine code if the parameters were directly interpreted.
  • The GetCryptoProvider function returns a value that represents a handle to the required CSP.
  • As the CSP isn't named, the actual CSP returned will depend on the OS and version of Internet Explorer. For this reason it's recommended that key sizes and other variable parameters are explicitly set.
  • GenerateKey is a function that returns a value holds the generated Key.
  • GetKeyParam and SetKeyParam are used to read and write to parameters of a Key.
  • The public part of Key1 is exported to a text variable that is returned by ExportKey, which is then imported into Key2 producing Key3 using ImportKey. A similar operation is performed to produce Key4. Key3 and Key4 now contain a shared secret.
  • The keys containing the shared secret are converted to a symmetric key using SetKeyParam.
  • Encrypt returns a text string that is the ciphertext of the plaintext string passed as a parameter. Decrypt returns a text string that is the plaintext of the ciphertext string passed as a parameter.
  • A variable containing a CSP handle has a type of 36 and if printed will display the textual name of the CSP.
  • A variable containing a Key handle has a type of 37 and if printed will display the hexadecimal value of the algorithm ID of the key.

Related Functions:

Decrypt | DeriveKey | Encrypt
ExportKey | GetCryptoProvider | GenerateKey
GetKeyParam | ImportKey | SetKeyParam


Custom Tag Types

The cornerstone of every VTScada application is a group of components called "tags" (sometimes referred to as "points"). These represent the various equipment processes that make up your system and enable you to create a chain of communications from VTScada to your physical equipment. A typical application based on the VTScada layer will include a set of tag types, with which you can create as many tag instances as your license allows.

You can extend VTScada's feature set by creating new kinds of tag. Some examples include:

  • A tag that collects data from several inputs, generating a combined value.
  • A driver tag for a new I/O device.
  • A controller that starts each motor in a group several seconds apart, thereby avoiding load spikes.

There are three ways to create new types of tag:

  • Create a Context type, adding properties and child tags that fully describe a machine, a site, an object or process.
  • Write a new type entirely from scratch using the information within this chapter.
  • Do a combination of the above, starting with a Context tag to define the fundamental structure, then extending its source code to add completely new features.

It is rare for anyone to write a new type entirely from scratch. If a Context-based structure does not fulfill the need, then it makes an excellent starting point for further development using custom code.

New types derived from Context tags do not count against your VTScada license limit until you add custom code to them, after which every instance of that type will be counted.

Every tag has three names: "ShortName" is the name of just that tag, alone. "Name" is the full name including all parents in the hierarchy. "UniqueID" is the guaranteed unique identifier, belonging to that one tag instance alone.
For any purpose that requires a lasting connection to a tag, such as alarm state & history, network values, communication with other machines, you should always use the unique ID rather than the name. TagObj.UniqueID (or just UniqueID from within a tag module) can be used to obtain the UniqueID for a tag.

Take care that you do not create a module within the tag having the same name as the tag. Or, matching any other existing module name.
Refer to examples within The Tag Variables Section


Terms for Tag Types

The following terms and abbreviations are used throughout this chapter.

Tag Template Module

A module that defines the structure of a tag. An example of a typical tag module is "AnalogInput". The tag module has formal parameters that correspond one-for-one with the fields in the tag properties database.

Tag

For the purposes of this section, a tag is defined as a named instance of a Tag Template Module. For example, an instance of the DigitalInput template is a digital input tag.
Another definition to describe a tag is, "A software component that can communicate with objects in the outside world. A tag can be used to accept input or generate output.

Database

The Database module is at the highest scope in a VTScada application, and is the location where all instances of the tags for the application are defined.

Library

The Library module is the location in a VTScada application where most of the modules and non-tag related variables are defined. The Library module is at the scope level just under the Database module. This module's instance goes by the name of "VTSDB" when referenced within a VTScada application.

Point

An older term for what is now called a "tag". Still in use at the code level.

Tag Properties Dialog

Also referred to as a "tag configuration folder", "config folder", or "config panel". A dialog-type window with a series of tabs, each of which contains a set of tag properties of a specific category and is appropriately labeled according to the property fields it contains (e.g. the ID tab contains properties that identify the tag.) The tag properties folder is a convenient tool that enables users to enter data into the Tag Properties Database.


Tag Template Modules

Tag template modules contain the code that defines each tag type available to your application. Tag template modules define not only what data types are available, but also how those data types can be displayed, their logic, their control actions, their alarm behavior, and all other characteristics native to tags of that type.

The modules for a tag template are typically stored in three separate files. This makes it easier to maintain and update the tag's code and makes it easier to find the various parts of the complete tag template. In the following example "Cnf" (appended to the tag name) indicates "Configuration modules" and "Cmn" indicates "Common modules"

You must declare all of the custom tags that you add to an application in the [POINTS] class of the application’s AppRoot.SRC file. VTScada will do this automatically when you run the Create New Type command on a Context tag.

You must also declare the configuration module and common module in the [PLUGINS ] class of AppRoot.SRC. You will then edit the source code for the tag itself so that it can find and use those submodules when needed.

Note that neither of these submodule are necessary for a context-derived type and VTScada will not create either of the submodules for you when creating a new type from a Context tag. If you choose to have a custom configuration panel and common module, you must write that code yourself. Examples are provided later in this chapter.

New types derived from Context tags do not count against your VTScada license limit until you add custom code to them, after which every instance of that type will be counted.


Example: CustomType.SRC

A tag is built using VTScada module Closed A collection of states, scripts, variables, parameters, comments and possibly other modules, all of which make up a VTScada program. Modules are separate tasks that run simultaneously in an application. Behind every page is a module and behind every tag on that page is an instance of another module (usually with submodules controlling separate tasks). and state Closed A collection of statements, grouped together within square brackets and given a name. A state is the part of the module that performs a task. Modules can have many states, but only one may be active at a time. code, just like any other piece of VTScada code. Like all modules, the tag template will include:

  • A parameter section
    All of the properties visible in any tag's properties dialog must be defined as parameters.
  • Declaration of variables and submodules used by the tag template module.
  • An initialization state, where start-up tasks are performed and the tag's Refresh module is launched.
  • The tag's main state.
  • A submodule named Refresh.
    This is responsible for updating parameter values, as well as other tasks.

Example:

A Context tag is created with name, CustomTag and type, CustomType. Two properties are added: Property1 and Property2.

ID tab of the Context tag, CustomTag

Settings tab of the ContextTag, CustomTag

The Context tag is saved as shown. Using the Tag Browser, the developer clicks Create New Type, thereby changing the Context tag into the new type, CustomType.

VTScada writes the template for the new type to the file, CustomType.SRC in the application folder and declares this module in AppRoot.SRC. The source code for the template follows:

{================================ TagType ==================================}
{ This tag type was generated programmatically. If you edit this SRC file,  }
{ you should remove the #CAN_EDIT_TYPE constant so that attempts to         }
{ update the type programmatically will not overwrite your SRC changes.     }
{===========================================================================}
(
  Name         <:TagField("SQL_VARCHAR(255)"):> { Name of the tag         };
  Area         <:TagField("SQL_VARCHAR(255)"):> { Area of the tag         };
  Description  <:TagField("SQL_VARCHAR(255)"):> { Description of the tag  };
  HelpKey      <:TagField("SQL_VARCHAR(255)"):> { HelpKey of the tag      };
  Property1 <:TagField("SQL_VARCHAR(255)"):>;
  Property2 <:TagField("SQL_VARCHAR(255)"):>;
)

[
  Constant DrawLabel;
  Constant NumTagFiles = 16;
  Constant #IS_CONTAINER  = True { Show these tags in tag browser tree     };
  Constant #CAN_EDIT_TYPE = True { Can be edited by tag type editing tools };

   { The next block of constants defines the offset into the parameter list,
     starting from 0, for each of the parameters }
  Constant #Name        = 0;
  Constant #Area        = 1;
  Constant #Description = 2;
  Constant #HelpKey     = 3;
  Constant #Property1   = 4;
  Constant #Property2   = 5;
  Constant #Property1_Comment = "";
  Constant #Property2_Comment = "";

  [ (GROUPS)
    Shared Container          { We are a container tag                      };
  ]

   { List of draw methods for this tag type }
  [ (GRAPHICS)
    Shared DrawAlarmList;
    Shared AlarmPriorityIndicatorBox;
    Shared AlarmPriorityIndicator;
    Shared DrawHDV;
    Shared AlarmList = "LSAlarmList";
    Shared SiteDetails = "LSSiteDetails";
    Shared GenericSiteDraw;
    Shared StationDraw = "LSStationDraw";
    Shared TagListDM;
  ]

  Root                        { This variable must be defined and must contain
                                the instance of this module as its value    };
  CustomMapIconName           { The name of the custom icon to use on a map };
  LatitudeValue               { Evaluated location of this site             };
  LongitudeValue              { Evaluated location of this site             };
  ConnectorColorValue         { Evaluated color of this connector          };

  Refresh Module              { Subroutine which will be called by the
                                tag parameter configuration tools to
                                notify this tag when on-line changes to the
                                parameters are made.                        };

  Value                       { Return value for the tag - Invalid          };
]

Init [
  If 1 TagMain;
  [
    CriticalSection(
       { Set up initial values }
      Root = Self();
      Refresh();
    );
  ]
]

TagMain [
   { Set the Latitude and Longitude }
  LatitudeValue       = (Valid(Scope(Root, "Latitude",       TRUE)) ?
                            \ExpressionManager : Invalid)\ToValue(Scope(Root, "Latitude",       TRUE));
  LongitudeValue      = (Valid(Scope(Root, "Longitude",      TRUE)) ?
                            \ExpressionManager : Invalid)\ToValue(Scope(Root, "Longitude",      TRUE));
  ConnectorColorValue = (Valid(Scope(Root, "ConnectorColor", TRUE)) ?
                             \ExpressionManager : Invalid)\ToValue(Scope(Root, "ConnectorColor", TRUE));
]

<
{================================ Refresh ==================================}
{ This subroutine will be called whenever the parameters for the module     }
{ are changed and allow the tag to perform any necessary actions to         }
{ undo any previous effects necessary such as changing drivers.  It is      }
{ passed an array of the previous parameter values.  The current parameter  }
{ values for the tag have already been changed by the time this is called.  }
{===========================================================================}
Refresh
(
  Parms                       { This is a pointer to an array which contains
                                the values of all of the parameters for the
                                tag prior to their change.                };
)

Refresh [
  If 1;
  [
    \ExpressionManager\SafeRefresh(&Scope(Root, "Latitude",       TRUE), Parms\Latitude);
    \ExpressionManager\SafeRefresh(&Scope(Root, "Longitude",      TRUE), Parms\Longitude);
    \ExpressionManager\SafeRefresh(&Scope(Root, "ConnectorColor", TRUE), Parms\ConnectorColor);

    \SetMapIcon(Root);

    Return(Invalid);
  ]
]

{ End of Refresh }
>


Tag Configuration Parameters

A tag template module must be configured with a set of formal parameters that correspond one-for-one to the fields of a table in the tag properties database. Each tag module begins by defining the tag's parameters within round parenthesis.

(
  Name        <:TagField("SQL_VARCHAR(255)", "Name",        0 ):> { Name of the tag   };
  Area        <:TagField("SQL_VARCHAR(255)", "Area",        1 ):> { Area of the tag   };
  Description <:TagField("SQL_PHRASEID",     "Description", 2 ):> { Description       };
  HelpKey     <:TagField("SQL_VARCHAR(255)", "Help Key",    3 ):> { HelpKey of the tag };
  Property1   <:TagField("SQL_VARCHAR(255)"):>;
  Property2   <:TagField("SQL_PHRASEID"):>;
)

It is instructive to compare this to any of the native VTScada types, which can be done by creating a new tag of any type using the Tag Browser, then examining its properties dialog. Or better, create the new type and then examine it using the Source Debugger.

You may add a new parameter to an existing tag by adding it to the end of the parameters section and assigning a matching parameter constant. Upon compiling the application and creating instances of the tag type, the new field will be added to the database.

For every parameter, a parameter constant definition must also be assigned. Note that the following code is taken from the declaration of variables, not the parameter list. These will be mentioned again in The Tag Variables Section.

   { The next block of constants defines the offset into the parameter list,
     starting from 0, for each of the parameters }
  Constant #Name        = 0;
  Constant #Area        = 1;
  Constant #Description = 2;
  Constant #HelpKey     = 3;
  Constant #Property1   = 4;
  Constant #Property2   = 5;

The first three parameters, Name, Area and Description are mandatory and must be exactly as shown in this example. "Name" must be the first parameter in the list. The others may be entered in either order, but you are advised to use the standard order of Name, Area, Description.

To define more parameters, use the example shown where each parameter is given a name, metadata defined as follows, an optional default value, and a comment describing the parameter's purpose.

Metadata examples from the Analog Status tag's parameter list:

UnscaledMax  <:TagField("SQL_DOUBLE",      "Unscaled Max", 7 ):> = 4095;
Units        <:TagField("SQL_PHRASEID",    "Units",        10):> = "PERCENTLABEL";

<: :> is the metadata operator. "TagField" is a structure with the following parts:

SQL data type, enclosed in quotation marks.

The data type should match a list of standard names (see list in the following topic). VTScada's Setup.INI file contains a block mapping those standard data type names to the actual data type names used by your ODBC compliant database program. This field is mandatory.

Note that the Name parameter must use the data type SQL_VARCHAR(255). Other text fields can use SQL_PHRASEID, SQL_VARCHAR(255) or SQL_LONGVARCHAR. While you might be tempted to use SQL_LONGVARCHAR for all, since all other fields can be expressions, it is helpful to type the parameter so that it gets cast appropriately, saving the need for casting in the Refresh module. For example, if the value is 0 and the type is SQL_INTEGER, then a 0 will be put into the tag parameter, whereas if the type is SQL_LONGVARCHAR, a "0" will be put into the parameter.

Values of any parameters of type SQL_BINARY will NOT be converted from the current Windows code page to UTF-8. These parameters are presumed to contain data where the bits are important rather than the characters, and any conversion would alter these.

The name of the field to be created in the database.

This is required only if the field name will differ from the parameter name. If not provided, then the field name in the database will be the same as the parameter definition. Note in the example from the Analog Status tag that the UnscaledMax parameter differs from the field name, "Unscaled Max". Field names may have spaces but parameter names cannot.

The column number of the field

Mentioned only for the sake of context when examining older examples. This parameter was required in versions of VTS prior to 8.0. Now, it defaults to the first unused index number, starting from 0. Note that the example from the Analog Status tag (which existed long before version 8.0) has this parameter, but the example created from a Context tag does not.

(Optional) Encryption flag

A Boolean that if TRUE, specifies that any value stored in this parameter should be encrypted.

(Optional) Avatar.

If the parameter resolves to an object, this names the variable where that object is stored. In practice, this is used only in I/O tags for the I/O device parameter, and then only if that type will be used to trigger alarms. For that specific case, the avatar should be set to "SitePoint".

(Optional) Moniker.

Label for the Avatar parameter, used for the graphical user interface. Typically, "IODeviceLabel" (referring to a Setup.INI label with that name), when the avatar is "SitePoint".

Default Value

You may assign a default value for any parameter by adding " = SomeValue" after the closing angle bracket. Repeating the example an Analog Status tag:

UnscaledMax <:TagField("SQL_DOUBLE",      "Unscaled Max", 7 ):> = 4095;
Units       <:TagField("SQL_PHRASEID",    "Units",        10):> = "PERCENTLABEL";

The default value may be a reference to a type of parent tag . For example, the DeviceTag parameter of an I/O tag will default to "*Driver". The Port parameter of a device driver will default to "*Port".

DeviceTag  <:TagField("SQL_VARCHAR(255)", "I/O Device Name", 3, FALSE, "SitePoint", "IODeviceLabel"):> = "*Driver";

Questionable

By default, new widgets that you create in the Idea Studio include a Tag Icon Marker. If your tag has a parameter named Questionable, and if the value of that parameter is set to TRUE, then operators will see a blinking question mark.

  Questionable <:TagField("SQL_DOUBLE", "Questionable Data"):> = 1
                      { Set to true when data is questionable          };


SQL Data Types for Tag Parameters

In practice, only a few SQL data types are used. In earlier versions of VTScada / VTS, these determined the type for the matching database column. In modern use, they are used as a hint for how VTScada should interpret the stored information. (For example, whether 0 should be read as an integer or text.)

The full list of available SQL data types follows. Notes are added where needed.

  • SQL_LONGUNICODE
  • SQL_NVARCHAR
  • SQL_BIT
  • SQL_TINYINT
  • SQL_BIGINT
  • SQL_LONGVARBINARY
    Values of any parameters of type SQL_LONGVARBINARY will NOT be converted from the current Windows code page to UTF-8. These parameters are presumed to contain data where the bits are important rather than the characters, and any conversion would alter these.
  • SQL_VARBINARY
    Values of any parameters of type SQL_VARBINARY will NOT be converted from the current Windows code page to UTF-8. These parameters are presumed to contain data where the bits are important rather than the characters, and any conversion would alter these.
  • SQL_BINARY
    Values of any parameters of type SQL_BINARY will NOT be converted from the current Windows code page to UTF-8. These parameters are presumed to contain data where the bits are important rather than the characters, and any conversion would alter these.
  • SQL_LONGVARCHAR
  • SQL_PHRASEID
    This marks a parameter as one that stores a PhraseID. This means that if the tag uses the default config folder, then a PPhraseEdit will be used to edit that parameter instead of a PEditField.
  • SQL_UNKNOWN_TYPE
  • SQL_CHAR
  • SQL_NUMERIC
  • SQL_DECIMAL
  • SQL_INTEGER
  • SQL_SMALLINT
  • SQL_FLOAT
  • SQL_REAL
  • SQL_DOUBLE
  • SQL_DATE
  • SQL_TIME
  • SQL_TIMESTAMP
  • SQL_VARCHAR


Encrypted Parameters

You may designate that the value of a parameter, as stored in the tag file, shall be encrypted. This does not encrypt the parameter in any VTScada user interface element. The purpose is to block unauthorized inquiries on the part of persons who do not have access to the application, but do have access to your server.

Encrypted parameters can only be defined for your custom tags. They are not used in any VTScada tag. Note that encryption is not applied retroactively if you modify your tag template file. Only tags created after the encryption flag has been set will have encrypted parameters.

In the parameter definition, the encryption flag is set as a Boolean in the TagField definition. In the following example, the parameter, "Password" is set to be encrypted:

(
   Name         <:TagField("SQL_VARCHAR(255)"):>;
   Area         <:TagField("SQL_LONGVARCHAR"):>;
   Description  <:TagField("SQL_LONGVARCHAR"):>;
   Password     <:TagField("SQL_LONGVARCHAR", "", Invalid, TRUE):>;
   HelpKey      <:TagField("SQL_LONGVARCHAR"):>;
)

Within VTScada, the value of "Password" will be visible unencrypted. (It is up to you to protect it in the user interface.) In the tag file, the value of Password will be stored encrypted.


The Tag Variables Section

The tag variables section follows the parameters and is enclosed in square brackets [ ].

This section declares (and in some cases, initializes) local variables, constants, and modules related to the tag. The following is a list of items commonly declared:

  • Required variables, such as Root and Value
  • Other local variables such as RawValue, RawTS, DisplayAddress, and SitePoint
  • Module declarations such as Refresh, NewData and Alarms
  • Plugins declarations such as the module for the configuration folder and the common (pop-up menu) module.
  • Graphics declarations for VTScada widgets that will be available to this tag.
  • Group membership declarations such as "Numeric" and "Loggers".
  • Constant declarations including parameter constant definitions, help ID values, and NumTagFiles.

The module, Configuration, is a legacy module. While never used in modern tags, it will still be recognized if present. If you name one of your modules "Configuration", VTScada will attempt to use it as a configuration panel and not as you intended.
Follow the instructions in Tag Configuration Folders and do not name any module within your tag "Configuration".

[
  Constant DrawLabel;
  Constant NumTagFiles = 16;
  Constant #IS_CONTAINER  = True { Show these tags in tag browser tree     };
  Constant #CAN_EDIT_TYPE = True { Can be edited by tag type editing tools };

   { The next block of constants defines the offset into the parameter list,
     starting from 0, for each of the parameters }
  Constant #Name        = 0;
  Constant #Area        = 1;
  Constant #Description = 2;
  Constant #HelpKey     = 3;
  Constant #Property1   = 4;
  Constant #Property2   = 5;
  Constant #Property1_Comment = "";
  Constant #Property2_Comment = "";

  [ (GROUPS)
    Shared Container          { We are a container tag                      };
  ]

   { List of draw methods for this tag type }
  [ (GRAPHICS)
    Shared DrawAlarmList;
    Shared AlarmPriorityIndicatorBox;
    Shared AlarmPriorityIndicator;
    Shared DrawHDV;
    Shared AlarmList = "LSAlarmList";
    Shared SiteDetails = "LSSiteDetails";
    Shared GenericSiteDraw;
    Shared StationDraw = "LSStationDraw";
    Shared TagListDM;
  ]

  Root                        { This variable must be defined and must contain
                                the instance of this module as its value    };
  CustomMapIconName           { The name of the custom icon to use on a map };
  LatitudeValue               { Evaluated location of this site             };
  LongitudeValue              { Evaluated location of this site             };
  ConnectorColorValue         { Evaluated color of this connector          };

  Refresh Module              { Subroutine which will be called by the
                                tag parameter configuration tools to
                                notify this tag when on-line changes to the
                                parameters are made.                        };

  Value                       { Return value for the tag - Invalid          };
]


Required Variables and Constants

The following variable, constant and submodule declarations must be part of every tag template:

    { Variables }
[
  Root                { Set to individual instance of this module };
  Value (5)           { Scaled value for this point.              };

   { The next block of constants defines the offset into the parameter list,
     starting from 0, for each of the parameters }
  Constant #Name        = 0;
  Constant #Area        = 1;
  Constant #Description = 2;
  Constant #HelpKey     = 3;
  Constant #Property1   = 4;
  Constant #Property2   = 5;
  { etc. for all parameters }

  Refresh Module      { Subroutine which will be called by the
                        tag parameter configuration tools to
                        notify this tag when on-line changes to the
                        parameters are made.                        }
  Constant NumTagFiles = 16;
]

Root

A variable named "Root" must be defined and must contain the instance of this module as its value. Root will be used to identify the individual instances of the module. This is required to allow the parameter editing tools to access the parameters of the tag.

Value

All type templates have a variable named Value, even if that type does not have a publicly accessible value. Value must be declared with a class type indicating the data type. (See: Variable Class Definitions.) The possible classes for Value are:

  • Class 0 - Disabled Declaring Value without a class type and leaving the stored value as Invalid will achieve the same result.
  • Class 1 - Bit
  • Class 2 - Unsigned byte
  • Class 3 - 16-bit integer
  • Class 4 - 32-bit integer
  • Class 5 - Double precision floating point
  • Class 6 - Text

The actual value to be stored within this variable must be set in a script, not in steady-state.

If the tag template provides the option of a manual value or an external value, then care must be taken to use that value whenever it is set. This is the role of The Refresh Module.

Parameter Constants

A numbered constant must be assigned for each of the declared parameters. These will be in the same order that the parameters were declared.

Refresh Submodule

Tags typically have several submodules, but only the Refresh submodule is mandatory. The Refresh subroutine will be launched by the tag's initialization state and will be called every time that the tag's data changes.

NumTagFiles

Recommended but not strictly mandatory as a default value of 64 will be assigned if this constant is missing. The value of NumTagFiles determines the number of tag files that are used to store all of the instances of this particular type. For example, the tag instances for the Analog Status tag type are randomly distributed between 256 files.

There is a trade-off between application start-up performance (faster with fewer tag files) and online tag editing performance (faster with fewer tags per file, hence faster with more tag files). In general, you will get good online-editing performance with up to 1000 tags/file. Therefore, since NumTagFiles in the Analog Status tag is set at 256 files, an application should have good online editing performance with up to 256,000 of these tags.

After the first instance of a tag has been created, any and all changes to NumTagFiles in the template will be ignored.


Optional Variables and Constants

ContextType:

Of particular note is the constant, ContextType. While not required, this is extremely useful when your tag definition is used as part of a parent-child tag structure. The context type declaration informs child tags of what type this is. For example, Alarm tags will automatically connect to the first *Numeric parent, Analog Input tags look for a parent of context type *Driver.

By specifying the context type of your tag, you make it possible to link your tag to the parent-child hierarchy, automatically. If your tag does not specify its ContextType explicitly, one will be created automatically, using the name of the tag.

Child tags are told what context type to use for a parameter by providing that value in the parameter definition. For example, in the Deadband tag's parameter list, you will find the following parameter declaration:

MonitoredValue <:TagField("SQL_LONGVARCHAR" ):> = "*Numeric";

In the list of constants for an Analog Status, Calculation, Digital Input, or other tag, you will find:

  Constant ContextType = "*Numeric";

(GROUPS) Declarations

Tag groups are collections of tag types that share some logical relationship. One example of a tag group is the Drivers group, which lists all of the I/O drivers in the system. Any tag can be a member of many groups. For example, the analog input tag type belongs both to the Analogs group (as it has an analog value), as well as to the Numeric group (as it has a numeric value).

Groups declaration of the Analog Input tag:

[ (GROUPS)
   Shared Numeric;
   Shared Analogs;
   Shared Trenders;
]

Groups declaration of the Context tag:

[ (GROUPS)
   Shared Container       { We are a container tag             };
]

One purpose of tag groups is to allow selection filtering, for example when using the Tag Browser or Historical Data Viewer. As another example, only members of the Containers group are shown in a Site List.

(GRAPHICS) Declarations

If your tag will be represented on screen by a widget, then you must specify which widgets can be used.

   { List of draw methods for this tag type }
  [ (GRAPHICS)
    Shared DrawAlarmList;
    Shared AlarmPriorityIndicatorBox;
    Shared AlarmPriorityIndicator;
  ]

#IS_CONTAINER

Declared as a constant and only for tags that are declared as part of the Container group, this property tells VTScada that these tags should always be shown in the Tag Browser tree.

Constant #IS_CONTAINER = True { Always show these tags in tag browser tree  };

PriorityLoad

Tags that contain this constant set to a value of 1, will be started before other tag types. Do not use without a clearly identified need.

PriorityReady

If a tag module has a PriorityLoad variable, it may optionally have a variable named PriorityReady as well. If PriorityReady is used, the tag loading code will wait until its value is set TRUE (non-zero) before starting any non-priority tag types.

Use PriorityReady with caution. Failure to ensure that its value is set TRUE will cause tag-loading to stop.

BuiltInAlarm:

Include and set true if the tag browser is to inform developers that this tag includes one or more built-in alarms.

Constant BuiltInAlarm = TRUE { Flag - TRUE if this tag has a built in alarm  };

DisplayAddress

Relevant only for I/O tags, if DisplayAddress is present, the Tag Browser is able to display the tag's configured I/O address. Because new types of tags have added to VTScada over many years, there is some variation in the name used for the I/O address field. By creating a variable with the name, DisplayAddress, and ensuring that it is always holds the current value of the I/O address, from whatever parameter stores that value for your tag, you can ensure that instances of your tag type display their I/O address in the Tag Browser.

IsOperable or IsOperable()

Either a Boolean or a module returning a Boolean. If using a module (common in the case that the variable isn't a flat FALSE), your module must check whether the instance of the tag is in fact able to operate when requested to do so from the Tag Browser. For example, with an I/O tag this would require a valid Write address. A Report tag would need a valid tag set, etc.

If the tag is Operable and if the currently signed-in user has whatever privileges are required, then the Tag Browser will contain an Operate option in the tag's right-click menu. Selecting that will trigger the DoOperate plugin for the tag.

SitePoint

The SitePoint variable is required only if an Avatar property was defined in the DeviceTag parameter. If so, then in the Main state of the tag, this property must be set to the object value of the device:

SitePoint = Scope(Root, DeviceTag);

Everything else

More variables will be required for local calculations, logging, built-in alarms, and other purposes. As an example, a partial list of variables from the Analog Status tag is provided:

{ Variables }
  RawValue       { Data value read from the IO                           };
  RawTS          { UTC Timestamp from NewData                            };
  SitePoint      { Object value of DeviceTag                             };
  OldSitePoint   { Previous value of SitePoint                           };
  Style          { Object value of the StyleSettings tag                 };
  Started = 0    { Let drawing methods know that Value has been restored.};
  DisplayAddress { Address for display in the Tag Browser                };
  QualityIssue   { TRUE if there is a data quality issue                 };


Latitude and Longitude

If users will place your container tag (site tag) on a map, it will need to store latitude and longitude coordinates and have a way to refresh those values. Both parameters and variables are required.

The parameter list must include Latitude and Longitude, to provide a means for users to locate the site on a map:

Latitude   <:TagField("SQL_LONGVARCHAR" ):> { The location of this site };
Longitude  <:TagField("SQL_LONGVARCHAR" ):> { The location of this site };

Matching constants must be created, as for all tag parameters.

In the tag's list of variables, you will create the following:

LatitudeValue  { Evaluated location of this site };
LongitudeValue { Evaluated location of this site };

The main state for the tag must provide a way to set those internal variables:

TagMain [
  { Set the Latitude and Longitude }
  LatitudeValue = (Valid(Scope(Root, "Latitude", TRUE)) ?
                   \ExpressionManager : Invalid)\ToValue(Scope(Root, "Latitude",  TRUE));
  LongitudeValue  = (Valid(Scope(Root, "Longitude", TRUE)) ?
                   \ExpressionManager : Invalid)\ToValue(Scope(Root, "Longitude", TRUE));
]

And finally, the Refresh module must provide a way to update the variables:

...
\ExpressionManager\SafeRefresh(&Latitude, Parms[#Latitude]);
\ExpressionManager\SafeRefresh(&Longitude, Parms[#Longitude]);
...


Tag States

As with all VTScada modules, the work is done with state code.

While it is common practice to name a module's initialization state, "Init" and the main state "Main", you should instead use distinctive names for these states in your tags. It will be easier to for you to debug your code if the state names reflect the tag modules they are a part of.

Initialization State

The first state in a module will always run automatically. In the case of a tag, this state has three mandatory tasks:

  1. Set the variable Root to "Self".
  2. Launch the Refresh module
  3. Transfer control to the main module.

Other initialization tasks may be required depending on the tag.

CustomTypeInit [
  If 1 CustomTypeMain;
  [
    CriticalSection(
       { Set up initial values }
      Root = Self();
      Refresh();
    );
  ]
]

Note that these mandatory tasks must be enclosed in a CriticalSection.

Main State

A tag's Main state may be complex, depending on the tag's function. Common tasks include updating the tag's value and other variables. The following partial example is taken from the Analog Status tag.

AnalogInMain [
  SitePoint = Scope(Root, DeviceTag);
  Style         = PickValid(Scope(Root, StyleTag), Variable(\#SYSTEM_STYLE));

  LowScaleValue  = PickValid(RangeMin, ScaledMin);
  HighScaleValue = PickValid(RangeMax, ScaledMax);
]

Other tasks include monitoring the tag's link to the I/O device driver, calculating scale, updating the value in an OPC server, etc. In later topics within this chapter, you will see code to develop this state further.


The Refresh Module

Your tag's Refresh module is called by VTScada when the tag starts and whenever any of the tag's parameters change. It is responsible for ensuring that new values are of the correct type for each parameter. Refresh must update every parameter of your tag other than the four commonly found in the ID tab.

The module will always have one parameter, "Parms", which is a pointer to an array of the tag's parameter values prior to being modified by the user. The tag's actual parameters will have already changed by the time "Refresh" is called. The "Parms" array can be used to watch for changes in the values, and take appropriate action based upon the changes

It is extremely important that the Refresh module contain a Return statement. The module will be called as a subroutine and must therefore have a return statement, even if it does not actually return any value.

In the case of tags that perform I/O, the Refresh module does not read from equipment, but does send an AddRead call to the driver. See Link to a Driver for more information on I/O.

In the following example, you will see instances of \ExpressionManager\SafeRefresh, which is common. This syntax is used for any parameter that can be configured using an expression, as is the case with Latitude and Longitude in a Context-derived tag where those parameters have been enabled.

The steps to add expression support for your parameters are covered in Expressions as Tag Parameters.

<
{================================ Refresh ==================================}
{ This subroutine will be called whenever the parameters for the module     }
{ are changed and allow the tag to perform any necessary actions to         }
{ undo any previous effects necessary such as changing drivers.  It is      }
{ passed an array of the previous parameter values.  The current parameter  }
{ values for the tag have already been changed by the time this is called.  }
{===========================================================================}
Refresh
(
  Parms                    { This is a pointer to an array which contains
                             the values of all of the parameters for the
                             tag prior to their change.                };
)

Refresh [
  If 1;
  [
    \ExpressionManager\SafeRefresh(&Scope(Root, "Latitude", TRUE), Parms\Latitude);
    \ExpressionManager\SafeRefresh(&Scope(Root, "Longitude", TRUE), Parms\Longitude);
    \ExpressionManager\SafeRefresh(&Scope(Root, "ConnectorColor", TRUE), Parms\ConnectorColor);

    \SetMapIcon(Root);

    Return(Invalid);
  ]
]

{ End of Refresh }
>

An example of the code used to update a tag parameter that does not have expression support follows. Here, the Analog Status tag's scan rate is being refreshed:

ScanRate = PickValid(Cast(ScanRate, 3), GetDefaultValue(&ScanRate));

A portion of the Analog Status tag's refresh module is shown here as an example. Note that the portion of a Refresh module that relates to writing data to, or reading data from a PLC is covered in the topic, Linking to a Driver.

<
{====================== AnalogStatus\Refresh ===========================}
{ This subroutine called at startup and whenever the point's parameters }
{   change                                                              }
{=======================================================================}
Refresh
(
  Parms                { Array for parameters prior to their change };
)

[
  NeedValueUpdate = FALSE;
]

Refresh [
  If 1;
  [
    ScanRate = PickValid(Cast(ScanRate, 3), GetDefaultValue(&ScanRate));

    {*****************************************************************}
    { Scaling                                                         }
    {*****************************************************************}
    UnscaledMin = PickValid(Cast(UnscaledMin, 3 { Float }),
                            GetDefaultValue(&UnscaledMin));
    UnscaledMax = PickValid(Cast(UnscaledMax, 3 { Float }),
                            GetDefaultValue(&UnscaledMax));
    ScaledMin   = PickValid(Cast(ScaledMin,   3 { Float }),
                            GetDefaultValue(&ScaledMin));
    ScaledMax   = PickValid(Cast(ScaledMax,   3 { Float }),
                            GetDefaultValue(&ScaledMax));

    IsText = UnscaledMin == UnscaledMax;

    {*****************************************************************}
    { Units                                                           }
    {*****************************************************************}
    { Provide default Units (%) for new points                        }
    Units = HookPointUnits = Cast(Units, 4 { Text });

    {*****************************************************************}
    { ManualValue                                                     }
    {*****************************************************************}
    ManualValue = Cast(ManualValue, 3 { Float });
    IfThen(ManualValue != Parm[#ManualValue] ||
           Valid(ManualValue) != Valid(Parm[#ManualValue]),
      NeedValueUpdate = TRUE;
    );
    {*****************************************************************}
    { Questionable                                                    }
    {*****************************************************************}
    Questionable = PickValid(Cast(Questionable, 0 { Boolean }),
                             GetDefaultValue(&Questionable));

    Return(0);
  ]
]
{ End of AnalogStatus\Refresh }
>

Refresh is called prior to the tag's data being written to the tag properties database and is passed an array of the previous parameter values for the tag. The current parameter values for the tag have already been changed by the time the Refresh module has been called. Refresh provides a way to reduce the memory requirements of the tag by reducing the number of active variable references and code required in the tag's main module, and thereby reduces the amount of memory required for each instance of the tag.


TagShutdown Module

If you need certain tasks to run whenever the tag stops, whatever the reason, then you may add the module, TagShutdown.

When any event causes a tag to stop, VTScada will look for a module named TagShutdown in that tag and execute the code found there. No parameters should be defined. This module must be used as a subroutine.

Example:

<
{============================ TagShutdown ==============================}
{ Called when the tag is slain - due to either tag stop or app shutdown.}
{ Makes note of the time when the shutdown occurred. This must be a     }
{ subroutine.                                                           }
{=======================================================================}
TagShutdown
Main [
  If 1;
  [  { Save the time of shutdown }
    SavedTime = CurrentTime();
    Return(Invalid);
  ]
]
{ End of TagShutdown }
>


Tag Configuration Folders

Every tag instance will require a user-configured name, area and description at a minimum. Typically, a range of other parameters will also exist.

In a Context-derived type, the configuration panel for these parameters is simply a list:

Default configuration panel for a Context-derived type

If there are more parameters than space in the default dialog, a scroll bar will be added. Every parameter is configured as a text field even if a set of radio buttons, a check box, a spin box or a color selector might be more appropriate.

You might prefer to give your developers a configuration panel that more closely resembles one from a native VTScada type:

Configuration panel for an Alarm Priority type.

VTScada provides the basic structure for the configuration panel and the necessary code behind it. You need only build upon that by creating a module that lays out the data input fields for each tab and ensure that those are linked to properties within your tag.

The code for the configuration panel is typically stored in file named for the tag and with the letters "Cnf" added to signify "configuration": CustomTypeCnf.SRC. There are two ways to declare that file, but note that in both cases, the assigned name must be "ConfigFolder".

1. For those who are modifying the source of a user-defined type, it is advisable to declare the configuration module within the user-defined type's variables section:

ConfigFolder Module "CustomTypeCnf.SRC";

2. For VTScada tags, the configuration file is typically declared in two places for purposes of flexibility: First, in your application by adding a line to the [PLUGINS] class of your AppRoot.SRC file where you will assign a variable name for the module. Second, within the tag's source code file, using that variable name instead of directly referencing the configuration file.

For example, in the AppRoot.src file of the application, add the following to the [PLUGINS] class:

[ (PLUGINS)Custom Filtering of the Sites List and Map
    CustomConfig       Module "CustomTypeCnf.SRC";
]

In the file CustomType.SRC, add the following to the Variables declaration section of the module.

[ (PLUGINS)
    Shared  ConfigFolder  =  "CustomConfig";

These two declarations provide VTScada with everything it needs to find your tag's configuration folder. In the next few topics, you will see the code for a sample configuration folder.


The Configuration Folder Module

The configuration folder module is responsible for drawing the contents of the tabbed dialog box used to edit a tag instance's properties. It must perform three tasks:

  • Define the tab labels
  • Respond to users requests to change from one tab to another
  • Display the correct fields in each tab

Each configuration module must contain the following states:

  • An initialization state.
    Used to initialize variables and pass control to the Switch state.
  • A Switch state.
    Used to switch from one tab's state to another, thereby allowing the user to switch tabs in the panel.
  • One state for each tab.
    These states contain the GUI functions to display the parameter fields.

The Parameters Section

Every configuration module will have exactly the same parameters section. To begin a new configuration module, copy the following:

(
  Parms                { Pointer to array of parameters                };
  Current              { Currently selected tab (starts at 0)          };
  PtrWaitClose         { Pointer to FLAG - TRUE when wait to close     };
  OKPressed            { OK Pressed from Properties Dialog             };
  CancelPressed        { Cancel Pressed from the properties Dialog     };
  ParmsData            { Parameter data                                };
  OldParms             { Old parameters                                };
  OldParmsData         { Old parameters                                };
  ParmsReady           { Pointer to the array of parameter ready flags };
)
  • The parameters array, Parms, is used by VTScada to link your tag parameters to this module.
  • VTScada sets the value of Current when a user clicks on a tab in the configuration panel. You will need to watch Current to know when to switch tabs.
  • PtrWaitClose is used by the VTScada code that handles the dialog box's Close button. It enables the code to finish all work before the dialog closes.
  • OKPressed is similar, but ensures that the values are written to the parameter array.
  • CancelPressed is set if the user cancels the configuration session. This allows you the chance to reset any values that may have been changed before cancel was pressed. Often useful, but not found in every configuration panel module.
  • ParmsData, OldParms and OldParmsData are arrays used by the tools that display values within the config folder. As a rule, you should include these even if you write no code for them.
  • ParmsReady is used in types derived from Context tags and tracks if each parameter is ready (TRUE) or in the process of being edited (FALSE).

The Variables Declaration Section

[
  Constant WIDTH = 500;
  Trigger                     { Edit field trigger                     };
  EditOK                      { OK to edit tag parameters              };
  [(1)
    IDTabLabel       = "ID";
    ConfigTabLabel   = "Settings";
  ]
]

The following are standard variables in a configuration folder.

  • Width - Normally declared as a constant, VTScada programmers set this value for their convenience when placing objects on the dialog. The height is set automatically by VTScada to accommodate all of the fields in the tallest tab of the dialog.
  • Trigger - Used by VTScada. Will be required in the code for each input field.
  • EditOK - Should be set according to whether the current user has tag modification privileges, then used in the FocusID field of every input control. (A value of 0 for FocusID disables a p-control.)
  • Tab label names - The text to display at the top of each tab.

The tab labels are declared in a Class 1 block. Each entry should be the phrase key for the label. The text you provide for each label name will be used as the default if not otherwise specified in the application's default language file. You are advised to create an entry for each label name using the Languages tab of the Application Properties dialog, then use the phrase key generated for that label.

The order in which the labels are provided will match the order of the tabs from left to right. For example, the following is copied from the Analog Status tag:

  [(1){ class declaration }
    IDTabLabel        = "ID";
    IOTabLabel        = "I/O";
    ScalingTabLabel   = "Scaling";
    AlarmTabLabel     = "Alarms";
    ExtAlmTabLabel    = "External Alarms";
    QualityTabLabel   = "Quality";
    OrderTabLabel     = "Order";
    HistorianTabLabel = "Historian";
  ]

For each tab, you must provide a state containing the graphics statements to be shown in that tab. See, Configuration Tab Contents.

The first tab in every dialog box must be the ID tab.

Initialization State

The initial state of the configuration module (commonly named, "Init") will set initial values for variables where required and pass control to the Switch state. If no initialization is required for your parameters, the state will always be written as follows:

Init [
  If 1 Switch;
  [
    {***** Initialize the wait close flag to not wait *****}
    *PtrWaitClose = 0;
  ]
]

Switch State

This is a crucial part of every configuration folder. The state for each of your tabs must monitor the parameter Current for change, which indicates that the user has chosen to view another tab. Control is passed to the Switch state, which checks the value of Current and activates the state matching the user's selection of tab. VTScada looks after updating the value of Current in response to the user's click on a tab. Tabs are numbered from left to right, staring at 0.

The content of this state is a set of IF statements, one for each tab in your config panel.

Switch [
  If Current == 0 ID;
  If Current == 1 Settings;
]

The ID State

Every tag must have a state named ID where the Name, Area, Description parameters are configured. VTScada tags include a HelpKey parameter, which is also configured in this tab, but this is optional for your custom tag.

Copy the following for your custom tag, optionally deleting the HelpKey entry if not in use. Note the first statement, watching the value of Current.

ID [
  If Current != 0 && ! *PtrWaitClose Switch;

   { Let the caller know when it's ok to close }
  *PtrWaitClose = PickValid(Trigger, 1) == 0;

    { Tag Name }
  GUITransform(30, 90, Width - 30, 45   { Boundaries of transform        },
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditName(Trigger));

    { Tag Area }
  GUITransform(30, 200, Width - 30, 100 { Boundaries of transform        },
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PAreaSelect(1 { can edit }, 2 { ID }, Parms[1] { Init },
                                          1 { Bevel }, 0 { VertAlign },
                                          1 { AlignTitle }, 1 { ParmNum },
                                          Trigger { Trigger }, OKPressed));

    { Tag Description }
  GUITransform(30, 200, Width - 30, 155 { Boundaries of transform        },
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
                \PPhraseEdit(\#Description, \GetPhrase("DescriptionLabel"),
                            1 { ID }, Trigger, 2, FALSE));

    { Help Key }
  GUITransform(30, 255, Width - 30, 210,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditField(\#HelpKey, \GetPhrase("HelpSearchKeyLabel"),
                                         \#VTypeText, 4 {FID}, Trigger, 2, FALSE));
]

P-Tools for Parameter Entry

The P-tools are a set of graphics statements designed expressly for parameter editing. Use these, and only these, in the tabs of your custom configuration panel. A full list is provided in the VTScada function reference. See: Graphics P-Tools.

The first parameter of each P-tool is a numeric value matching the defined constant of one of your tag parameters. (See: Parameter Constants.) This creates the link between each field in your configuration dialog and the parameters in your tag. For clarity, you are advised to use the name assigned to each constant rather than its numeric value.

The P-tools are not placed directly on a page, but are instead wrapped within a GUITransform statement that sets their location. The recommended size for each can be obtained from the example provided in the function reference for each.

It can be challenging to place the transforms evenly within a tab. The following guidelines may help, but expect to spend adjusting the layout. The coordinates of a GUITransform are defined in the order (left, bottom, right, top) and the 0, 0 coordinate of a VTScada window is at the upper left.

  • Define a width constant for the dialog and place transforms relative to that value.
  • Leave a border of 15 pixels to the left and to the right of the collection of transforms.
  • VTScada sets the height of the dialog automatically, allowing space for everything you place within it. Set the top of the first transform at 45 pixels to leave room for the title and a margin, then work down from there.
  • Leave at least 10 pixels between the bottom of one transform and the top of the next.
Settings [
  If Current != 1 && !*PtrWaitClose Switch;
  *PtrWaitClose = False(Trigger);

     { Parameter 1 as text }
  GUITransform(30, 90, ((Width - 60) / 2) - 5  , 45,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditField(\#Property1, \GetPhrase("Property1Label"),
                                         4 { text }, 1 { ID },
                                         Trigger { trigger }));

     { Parameter 2 as numeric selection }
  GUITransform(((Width - 60) / 2) + 5, 90, Width - 30, 55,
               1, 1, 1, 1, 1,
               0, 0, 1, 0,
               0, 0, 0,
               \DialogLibrary.PSpinbox(\#Property2, \GetPhrase("Property2Label"),
                                       1,
                                       0, 25 { Limits },
                                       3, 0, 1, 2,
                                       Invalid, Invalid, Trigger));

]


Expressions as Tag Parameters

The PTypeToggle widget (following image), provides the user with a choice between a tag, a constant value, or a block of steady state VTScada code (i.e. an expression).

If you intend to add support for expressions, you must ensure that the ExpressionManager is started in the tag's initialization state before any other actions take place. This is commonly done as follows (example taken from the Analog Status tag with relevant code in bold).

AnalogInit [

  If \AlarmManager\Started && \ExpressionManager\Started AnalogInMain;

  [

    CriticalSection(

      Root = Self;

       { Set up initial values }

      Refresh();

    );

  ]

]

In the Refresh() method of the module, use SafeRefresh() to update any parameters that may be assigned an expression. For example:

\ExpressionManager\SafeRefresh(&AlarmLo, Parm[#AlarmLo]);

In the tag's configuration folder, use a PTypeToggle for each variable that may be an expression. For example, here is the code that draws the user input for the low alarm setpoint of an Analog Status tag:

{***** Low Setpoint *****}
  GUITransform(30, 103, WIDTH/2 - 5, 45,
               1, 1, 1, 1, 1     { No scaling                     },
               0, 0, 1, 0        { No movement; visible; reserved },
               0, 0, 0           { Not selectable                 },
 \DialogLibrary.PTypeToggle(\#AlarmLo, "Numeric" { point type },
                            \GetPhrase("LowAlarmSetpointLabel"), 1 { to 3 - ID },
                            0 { top align }, 1 { align title },
                            Invalid, Invalid { limits },
                            Trigger, 1 { Allow Expression }));

Issues and Risks

Care must be taken when assigning to and from variables that may hold expression values. The implementation of expressions assumes that only one variable at a time holds a reference to a running expression.

A running expression must be slain before assigning to a variable that refers to it. Failing to do this will result in an orphaned expression, which is worse than creating a memory leak, because processor cycles are additionally wasted.

A reference to a running expression should not be copied. Instead of copying the reference, a new expression should be started with the same source. Failing to do this consistently will result in expressions dying unexpectedly.

The convenience methods \ExpressionManager\SafeAssign() and \ExpressionManager\SafeCopy() are provided to make this easier for developers.

Care must be taken not to rely on expressions running on different servers to return the same thing (example: Now(1))

It is possible, in theory, to create a situation where expressions are returning different values from each PC in a multi-server application. For example, suppose that a Logger is created that accepts input from a Calculation tag, which in turn uses an expression that relies on the local clock. If the local clock is slightly different on each PC, then this may result in odd log data when synchronizing between different PCs.


ExpressionManager Subroutines

The modules used by the ExpressionManager, are as follows:

\ExpressionManager\Start(Script, ExpressionParent, ExpressionCaller [, ReturnErrors, NewValue, IsScript] )

This method first attempts to cast Script to a number, then tries to scope it to a tag, then attempts to compile it into an expression module. If Script casts to a number or scopes to a tag, it is returned. If Script compiles successfully, it is returned. If Script compiles successfully, it is launched with ExpressionParent and ExpressionCaller as parent and caller respectively. If the cast, scope, and compile fail, it will return Invalid unless the optional parameter ReturnErrors is set to true, in which case a string describing the problem will be returned.

NewValue is an optional initial value for the expression

IsScript should be set to TRUE if the expression will be a script expression. Defaults to FALSE.

This interface is designed to behave in the same way as tag Refresh() methods do when interpreting strings that may be constants, tags, or expressions.

\ExpressionManager\IsExpression(ModuleRef)

This subroutine protects calling code from the design decision to mark ownership of expressions using a signature. It returns 1 if ModuleRef refers to a running module that the ExpressionManager launched, and 0 otherwise.

\ExpressionManager\ToString(Obj)

This subroutine will return a string representation of Obj. ToString() handles constants, tags, and expressions. \ExpressionManager\Start(ExpressionManager\ToString(Obj), … ) will return a new instance of a running expression, or a reference to the same tag, or the same constant.

\ExpressionManager\SafeAssign(PTarget, Source)

This convenience routine checks to see if PTarget is a pointer to a running expression. If it is, the expression is slain. Then *PTarget is set to Source (*PTarget is always set, regardless as to whether it points to an expression).

\ExpressionManager\SafeCopy(Obj, ExpressionParent, ExpressionCaller)

The same as \ExpressionManager\Start(\ExpressionManager\ToString(Obj), ExpressionParent, ExpressionCaller).

\ExpressionManager\SafeRefresh(PRefreshedVar, ParmVar[, NewValue])

  PRefreshedVar{ Variable that is being refreshed.     };
  ParmVar{ Previous value of variable being refreshed. };
  NewValue{ Optional initial value for expression      };

If a tag parameter holds a running expression rather than a variable, care must be taken in refreshing it. The SafeRefresh method provides a convenient way for developers to ensure that all parameters are correctly refreshed, and at the same time ensures that similar operations use the same code path.

Using the Function tag as an example, its refresh module starts as follows:

Refresh [
  If watch(1);
  [
    {***************************************************}
    { Parameters to the Function                        }
    {***************************************************}
   {***** Update variables *****}
    \ExpressionManager\SafeRefresh(&P1, Parm[#P1]);
    \ExpressionManager\SafeRefresh(&P2, Parm[#P2]);
    \ExpressionManager\SafeRefresh(&P3, Parm[#P3]);
    \ExpressionManager\SafeRefresh(&P4, Parm[#P4]);

Here, the variables P1 through P4 are all parameters to the tag. SafeRefresh will instantiate the expression if necessary and will set the parameter to that expression. If the parameter is a tag reference or a simple constant, those will be handled correctly as well.

\ExpressionManager\ToValue(Parm)

Takes the return value from SafeRefresh and returns the current value of the expression, tag or constant. \ExpressionManager\ToValue should always be called to safely use the value of a parameter in a module.

Example:

The Function tag uses the following to access the values of these four parameters:

  RawValue = PickValid(Cast(\ExpressionManager\ToValue(P1), 3),
           Valid(P1) ? Invalid : 0) +
             PickValid(Cast(\ExpressionManager\ToValue(P2), 3),
           Valid(P2) ? Invalid : 0) +
             PickValid(Cast(\ExpressionManager\ToValue(P3), 3),
           Valid(P3) ? Invalid : 0) +
             PickValid(Cast(\ExpressionManager\ToValue(P4), 3),
           Valid(P4) ? Invalid : 0);

If the parameter is a constant or expression, the scope resolution references to the tag-Name and tag-Value variables would be undefined. Any addition of variables, such as child tags starting or another application starting would cause the code to re-trigger. This behavior is intentional to catch the addition of child tags AFTER the instantiation of the references to them.


The ExpressionEdit Widget

The ExpressionEdit widget is used by the PTypeToggle to allow users to write expressions. It is unlikely that you will need to write code to open it, except in cases where screen area is too limited for a PTypeToggle and you need more control. It looks and acts similar to a SelectObject, except that instead of bringing up the Tag Browser when the user clicks the … button, an expression entry dialog is displayed. ExpressionEdit uses Start() to resolve what the user types in, so it can be used to select an expression, a tag, or a constant.

The format of the interface is as follows:

ExpressionEdit(Left, Bottom, Right, Top, ParmObjPtr, SetParm, ID, Root[, AllowRootSelection, ParmValueType, TargetSubType, FcnSelectionMode, Title])

Left | Left side of graphic
Bottom | Bottom edge of graphic
Right | Right side of graphic
Top | Top edge of graphic
ParmObjPtr | The parameter being set
SetParm | Set when the parameter has been set
ID | Focus ID
ExpressionParent | Scope into which to launch expressions.
HideValue | 1 (TRUE) to hide expression value (Default: 0 (FALSE))
BGColor | Optional background color of the edit box
FGColor | Optional foreground color of the edit box
Immutable | True if we want to force all tag references to generate immutable reference code. Defaults to FALSE
RootTag | Root tag, from which to execute scope operations
AllowRootSelection | TRUE to allow Root tag to be selected. Defaults to FALSE
ParmValueType

ValueType of the parameter

  • 0 = Status (boolean)
  • 1 = Short
  • 2 = Long
  • 3 = Double
  • 4 = Text
  • 5 = Octal
  • 6 = Hexadecimal
  • 7 = Color
  • 8 = Object
TargetSubType | The target's variable sub-type(s)
FcnSelectionMode

What kind of functions should be selectable:

  • 0 = Script
  • 1 = All Steady State (all) - Default
  • 2 = Steady State, no exclusive Steady States
Title | Optional text to use as the window title. Defaults to "Expression" in English.


Create or Assign Tag Widgets

VTScada provides an extensive selection of widgets that you may use with your tags. You can also write a custom widget for a tag if none of the built-in methods meet your needs. If creating a custom widget, start first with the Idea Studio. Write code only if absolutely necessary.

To use the tag widgets provided by VTScada, declare them in the [ (GRAPHICS)] class of your tag module. Note that you must use the declared name of the widget rather than the display name, which may vary. For example, the Pie Chart widget is declared as Meter20. A complete list of the available widgets can be found in Widgets List for Programmers.

The following example is a portion of the widgets declared in the Analog Status tag. Note that the first, Draw, is a submodule of the tag rather than a shared module.

  [ (GRAPHICS)
    Draw        Module     { Standard Draw Module for this point       };
    Shared TopBar;
    Shared RightBar;
    Shared LeftBar;
    Shared BottomBar;
    Shared Number;
    Shared DrawText;
    Shared Meter1;
    Shared Meter2;
    Shared Meter3;
    Shared Meter4;
    Shared Compass1;
    Shared AnimatedBitmap;
    Shared TwoColorBar;
    Shared ColorFill;
  ]

Note for Style-Tag Aware Widgets

The Status Color Indicator widgets and Indicator Light widgets are typically used to display a tag's value using the colors defined in the Digitals tab of the associated Style Settings tag. But, for tags in the ports group, drivers group, the Modem tag and the SMS Appliance tag, these widgets take the tag's value to represent an error state, and use the colors defined in the Errors tab of the style tag.

To inform the widget that your tag's value should be interpreted as an error indicator rather than a status value, you should add the following three parameters to the tag.

ValueIsErrorStatus

Boolean. Set TRUE to treat the tag's value as an error status condition and to use the No Error and Error colors of the Style Settings tag.

ValueIsErrorAbove

Numeric. This is the value above which the tag will be treated as being in error. Defaults to 0.

ValueIsErrorBelow

Numeric. This is the value below which the tag will be treated as being in error. Defaults to 0.

To add expression support to a widget:

Often a tag widget variable X that can be a tag or a constant will be set in steady-state with PickValid(). Graphic calls then use X directly as an input. This won't work if X is extended to allow expressions, as Start() is a subroutine. Instead, introduce a new variable (for example, Xdata) and base the graphics on that. Then add new code similar to the following:

If Watch( 1, X );
[
\ExpressionManager\SafeAssign( &Xdata, ValueType(X) == 7 { Object } ?
   X : ValueType(X) == 4 { Text } ? \ExpressionManager\Start(X, Self, Self) : X );
]

Finally, make sure that there is a PTypeToggle in the Panel module for X, and ensure that the PTypeToggle is called with the EnableExpressions argument set to 1.


Create a Custom Widget

If you decide that you need a widget with features that cannot be built in the Idea Studio, you can extend a widget that was started there or write a completely new one.

The module must be declared in the [(65282) group of the application's AppRoot.SRC file:

  [ (65282)
    QuickPump Module "Widgets\QuickPump.SRC";
    QuickValve Module "Widgets\QuickValve.SRC";
  ]

You have a choice when it comes to linking your custom widget to your custom tag. You can declare the widget in the [(Graphics) section of your custom tag.

[ (GRAPHICS)
    Shared QuickPump;

Or, you can work within the widget to declare the list of tags to which that widget can be linked. Note that this task is best done within the Idea Studio, using the Tag Types tool of the Widget Properties ribbon.

  Shared DrainValve (POINTS);
  Shared AnalogStatus(POINTS);

This option is the only one available for linking a custom widget to a VTScada tag. You cannot modify the source code for any of the built-in tags to add your custom widget to its list of graphics.

Each widget must have its own module, where there is one widget per module. This may be a submodule of your tag or more commonly, a separate file.

The following are common elements of a custom widget. Required elements are noted.

Optional: Module reference box coordinates.

All of the VTScada widget modules begin with reference box coordinates. While not mandatory, and not part of widgets created in the Idea Studio, you should consider adding these. See: Reference Boxes and Scaling.

(0, 160, 160, 0) { Meter 1 reference box }

Parameters for configuring the object.

At a minimum, these should include the Disable options for operator-interface controls. "Status" is a keyword, flagging these parameters as Boolean.

(
  DisableTrend      Status;
  DisableNavigation Status;
  DisableTooltip    Status;
)

Create a parameter for every aspect of the widget, over which developers will have control. For example, the CommLine widget has parameters for three colors and pen orientation

DrawLabel constant

The name of the module will be taken as the name of the widget unless you specify otherwise with a constant declaration named "DrawLabel". This should refer to a property that you add to your Settings.Dynamic file.

  Constant  DrawLabel = "MyWidgetLabel";

In an Idea Studio widget, the keyword Title will be used and will use whatever was assigned when the widget was created. If there is a chance that your widget will be used for alternate languages then you are urged to replace Title with DrawLabel as described here.

Other variables and constants as required

If you intend to provide a configuration panel where developers can set values for the widget's parameters, then it is common to create constants that determine the size of that panel. A widget's configuration panel is created in exactly the same way as a tag's configuration panel, therefore you must also create constants enumerating the parameters, just as is done for tag parameters.

Optional: Initialization state

If used, this will set default values if required (colors, fonts, sizes, etc.) and call's the module's main state.

Main state

The main state should include the steady state graphics command that define the drawing object.

The main state must also launch a call to the tag's Common module.

Optional: Panel submodule

A submodule named "Panel" should be included if the widget has parameters. If a Panel module is not supplied, VTScada will generate a basic configuration box for the parameters when the object is placed on the screen.

Panel must be declared with one parameter, Parms. This will be a pointer to an array that contains the initial values of the tag's parameters and that will be modified to contain the values entered by the user while editing.

You will need to create a Menu Item tag for your widget if you want to see it in any of the Idea Studio palettes. This is done automatically for widgets created in the Idea Studio.


Edit Mode versus Run Mode

When the application is in edit mode (Idea Studio), widgets should respond to user clicks differently than when the application is in run mode.

You can determine which mode the application is in by querying, ParentWindow()\Editing. VTScada will return a value of TRUE or FALSE depending on the mode. You can then code your widget to examine the \Editing value before responding to a user's action.

An example can be seen with Set Analog Value Hotboxes. When in Edit mode, these display as a yellow rectangle, but when in run mode, they are invisible until the user hovers the mouse pointer over them. You can emulate this behavior by adding a GUIRectangle to your widget and coding its Visibility parameter to examine the current value of ParentWindow()\Editing.

  {***** Display the hotbox when over top, or when editing *****}
  \HotBox(0, 0, 30, 100, 0, Invalid, Color);
  GUIRectangle(0, 30, 100, 0 { Also sets module ref box },
               1, 1, 1, 1, 1,
               0, 0, ParentWindow()\Editing ? 1 : 0, 0,
               0, 0, 0,
               -1, PickValid(Color, 14));


Example: Widget Parameters

As an example, the Analog Status tag has the following options in its Draw widget:

The matching parameters are declared as follows. (Parameters and variables for features that have not yet been covered in this chapter are excluded).

Note the presence of the word "Panel" in the menu. The contents of this display are controlled by a submodule of the widget named "Panel". You will need to create this module for your tag.

The four numeric values after the module name and before the parameter list are used to specify the size of the module reference box. When VTScada calls a module within a GUITransform, it scopes in and gets the bounds of largest of the GUI within that module. Setting the default graphic size avoids problems when there may be non-GUI graphics or you want the drawing area bigger to be than the GUI’s within it. See: Module Reference Boxes.

<
{=============================== Draw ==================================}
{ Graphic module to display Text Description and Value of the Input     }
{=======================================================================}
Draw
(0, 30, 200, 0)
(
  Digits                   { Digits after the decimal point            };
  ShowUnits                { TRUE if display the units                 };
  FontVal                  { Font to display text in                   };
  Border                   { Border options: 0 = no button, 1 = button };
  BgndColor                { Color for background inside the button    };
  DisableTrend             { Flag to disable trend windows             };
  DisableNavigation        { Flag to disable navigator menu            };
  DisableTooltip           { Flag to disable tool tips                 };
)

[
  Panel Module              { Parameter editing module                  };
  Offset                    { Offset for graphics, based on Width       };
  Color                     { Background color based on status of point };
  TextColor                 { Text color based on questionable data     };
  Buff                      { Text buffer holding string to display     };
  ChosenFont                { The font value chosen by the user         };
  DrawFontObj               { Object value of font to draw with         };
  Format                    { Format for the number                     };

  { Parameter definitions }
  Constant #Digits            = 0;
  Constant #ShowUnits         = 1;
  Constant #FontVal           = 2;
  Constant #Border            = 3;
  Constant #BgndColor         = 4;
  Constant #DisableTrend      = 5;
  Constant #DisableNavigation = 6;
  Constant #DisableTooltip    = 7;

   { Panel dimensions }
  Constant #PanelWd = 320;
  Constant #PanelHt = 6 * Space + TitleSpace + 3 * CheckHt + 242;
]


The Properties Panel

If the widget includes parameters, it is strongly recommended that you supply a Panel module. The purpose of this module is to control the layout of the parameter elements in the properties dialog when the widget is being edited.

The Panel module takes two parameters: Parms, which is a pointer to an array containing the widgets parameters and PtrWaitClose, which is used by VTScada when the properties dialog is being closed.

The Panel module will normally also have one internal variable, Trigger. This will be used by VTScada when each field in the panel is edited by the user.

Like the tag configuration dialog, the P* functions are commonly used for the data entry fields.

For example, the entirety of the Analog Status tag's Draw widget panel, as shown in the preceding topic, is as follows:

<
{=============================== Panel ===============================}
Panel
(0, #PanelHt, #PanelWd, 0)
(
  Parms;
  PtrWaitClose                { Pointer to Flag - TRUE to wait to close dlg   };
  ParmDefs                    { Array of page parameter definition structures };
  DialogRoot                  { The calling dialog window                     };
)
[
  Trigger                     { Edit fields trigger                           };
  SubWaitClose                { WaitClose flag for the datasource editor      };
  Height                      { Height of panel                               };
  PageInst                    { Page instance                                 };
  ContPageInfo                { Container page information                    };
  Modules                     { Array of modules to load in the ParameterEdit };
  Parameters                  { Array of parameters for ParameterEdit modules };
  ParmEditObj                 { Object value of the ParameterEdit control     };
  PEBottom                    { Bottom of the ParameterEdit                   };
  FontParm;  OldFontParm      { Used for ParameterEdit                        };
]
Init [
  If 1 PanelMain;
  [
    {***** Set defaults *****}
    Parms[#Digits]            = PickValid(Parms[#Digits],    1);
    Parms[#ShowUnits]         = PickValid(Parms[#ShowUnits], 1);
    Parms[#Border]            = PickValid(Parms[#Border],    0);
    Parms[#BgndColor]         = PickValid(Parms[#BgndColor], \DialogBGColor);
    Parms[#DisableTrend]      = PickValid(Parms[#DisableTrend],      0);
    Parms[#DisableNavigation] = PickValid(Parms[#DisableNavigation], 0);
    Parms[#DisableTooltip]    = PickValid(Parms[#DisableTooltip],    0);
    { Initialize the wait close flag to not wait }
    *PtrWaitClose = FALSE;
    { Get info about the parms of the container page }
    PageInst     = \GetUserSession()\GraphicEditor\GetSelectedTabItem();
    ContPageInfo = GetParamInfo(PageInst);
    { Set up variables for ParameterEdit }
    FontParm     =
      OldFontParm  = Parms[#FontParm];
    MetaData(FontParm, "Revision") = 0;
    { "Font" ParameterEdit }
    Modules     = New(3);
    Parameters  = New(3);
    { Tag option }
    Modules[0]       = "ParmEditTag";
    Parameters[0]    = New(1);
    Parameters[0][0] = "FontValue";
    { Parameter option }
    Modules[1]           = "ParmEditParmValue";
    Parameters[1]        = New(6);
    Parameters[1][0]     = ContPageInfo;
    Parameters[1][1]     = \#VTypeObject;
    Parameters[1][2]     = Invalid;
    Parameters[1][3]     = New(1);
    Parameters[1][3][0]  = "FontValue";
    Parameters[1][4]     = 0; { No Scaling }
    Parameters[1][5]     = Invalid; { No default value }
    { Expression option }
    Modules[2]       = "ParmEditExprNoNormalize";
    Parameters[2]    = New(2);
    Parameters[2][0] = 1;
    Parameters[2][1] = ContPageInfo;
  ]
]
PanelMain [
  {***** Let the caller know when its ok to close *****}
  *PtrWaitClose = PickValid(Trigger, 1) == 0 || PickValid(SubWaitClose, 0) == 1;
  Height = 10*Space + 2*TitleSpace + PEBottom + SpinHt + BtnHt + 3*CheckHt + 65;
  If Watch(0, Height);
  [
    SetPanelRefBox(Self, 0, Height, #PanelWd, 0);
  ]
  {***** Font *****}
  GUITransform(0, 1, 1, 0,
    1 - 0,
    2 * (EditHt + Space),
    #PanelWd,
    1 - 0,
    1, 0, 0, 1, 0, 0, 0, 0,
    ParmEditObj = \ParameterEdit(FontParm                            { Parameter Value             },
    ParmDefs[#FontParm]                 { Parameter Definition        },
    1                                   { Enable Flag                 },
    \GetPhrase("FontLabel")             { Title                       },
    Modules                             { Array of Parm Edit Modules  },
    Code                               { Contexts for Edit Modules   },
    Parameters                          { Parameters for Edit Modules },
    TextAttribs(\GetPhrase("FontLabel"), _DialogFont, 0) { Title Width             },
    Invalid                             { Index value                 },
    SubWaitClose                        { Wait to close               },
    DialogRoot                          { Calling dialog window       }));
    If FontParm != OldFontParm ||
      Valid(FontParm) != Valid(OldFontParm);
    [
      OldFontParm      =
        Parms[#FontParm] = RootValue(FontParm);
    ]
    PEBottom = PickValid(ParmEditObj\Height, 2 * (EditHt + Space));
    {***** Digits *****}
    GUITransform(0, 1, 1, 0,
      1 - 0,
      Space + PEBottom + SpinHt,
      170,
      1 - (Space + PEBottom),
      1, 0, 0, 1, 0, 0, 0, 0,
      \DialogLibrary.PSpinBox(#Digits, \GetPhrase("DigitsAfterDecLabel"), 1 { box on left },
      0, 9 { limits }, 3 { left, centered }, 0 { autosize },
      0 { no edit }, 3 { ID }, Invalid, Invalid, Trigger {Trigger}));
    {***** Show units *****}
    GUITransform(0, 1, 1, 0,
      1 - 180,
      Space + PEBottom + CheckHt + 4,
      #PanelWd,
      1 - (Space + PEBottom + 4),
      1, 0, 0, 1, 0, 0, 0, 0,
      \DialogLibrary.PCheckBox(#ShowUnits, \GetPhrase("ShowUnitsLabel"), 1 { box on left },
      3 { left, centered }, 4 { ID }));
      {***** Type of border *****}
    GUITransform(0, 1, 1, 0,
      1 - 0,
      2*Space + PEBottom + SpinHt + 65,
      #PanelWd,
      1 - (2*Space + PEBottom + SpinHt),
      1, 0, 0, 1, 0, 0, 0, 0,
      \DialogLibrary.PRadioButtons(#Border, 8 { to 10 - ID },
      1 { border }, \GetPhrase("TypeOfBorderLabel"), 1 { btns on left }, 1 { align title },
      \GetPhrase("NoButtonLabel"), \GetPhrase("ButtonLabel")));
    {***** Colors *****}
    System.Bevel(0,
      5*Space + TitleSpace + PEBottom + SpinHt + BtnHt + 65,
      #PanelWd,
      3*Space + PEBottom + SpinHt + 65,
      \GetPhrase("ColorsLabel"));
    {***** Background color *****}
    GUITransform(0, 1, 1, 0,
      1 - Space,
      4*Space + TitleSpace + PEBottom + SpinHt + BtnHt + 65,
      260,
      1 - (4*Space + TitleSpace + PEBottom + SpinHt + 65),
      1, 0, 0, 1, 0, 0, 0, 0,
      \DialogLibrary.PColorSelect(#BgndColor, \GetPhrase("BackgroundLabel"), 1 { btn on left },
      1 { standard size }, 1 { centered }, 12 { ID }));
    {***** Disable Options *****}
    System.Bevel(0,
      10*Space + 2*TitleSpace + PEBottom + SpinHt + BtnHt + 3*CheckHt + 65,
      #PanelWd,
      6*Space + TitleSpace + PEBottom + SpinHt + BtnHt + 65,
      \GetPhrase("DisableOptionsLabel"));
    {***** Disable Trends Check Box *****}
    GUITransform(0, 1, 1, 0,
      1 - Space,
      7*Space + 2*TitleSpace + PEBottom + SpinHt + BtnHt + CheckHt + 65,
      #PanelWd - Space,
      1 - (7*Space + 2*TitleSpace + PEBottom + SpinHt + BtnHt + 65),
      1, 0, 0, 1, 0, 0, 0, 0,
    \DialogLibrary.PCheckBox(#DisableTrend, \GetPhrase("DisableTrendLabel"),
      1  { box on left },
      3  { left, centered },
      13 { ID }));
    {***** Disable Navigation Check Box *****}
    GUITransform(0, 1, 1, 0,
      1 - Space,
      8*Space + 2*TitleSpace + PEBottom + SpinHt + BtnHt + 2*CheckHt + 65,
      #PanelWd - Space,
      1 - (8*Space + 2*TitleSpace + PEBottom + SpinHt + BtnHt + CheckHt + 65),
      1, 0, 0, 1, 0, 0, 0, 0,
      \DialogLibrary.PCheckBox(#DisableNavigation, \GetPhrase("DisableNavigationLabel"),
      1  { box on left },
      3  { left, centered },
      14 { ID }));
    {***** Disable Tooltip Check Box *****}
    GUITransform(0, 1, 1, 0,
      1 - Space,
      9*Space + 2*TitleSpace + PEBottom + SpinHt + BtnHt + 3*CheckHt + 65,
      #PanelWd - Space,
      1 - (9*Space + 2*TitleSpace + PEBottom + SpinHt + BtnHt + 2*CheckHt + 65),
      1, 0, 0, 1, 0, 0, 0, 0,
      \DialogLibrary.PCheckBox(#DisableTooltip, \GetPhrase("DisableTooltipLabel"),
      1  { box on left },
      3  { left, centered },
      15 { ID }));
]
{ End of Draw\Panel }


Widget States

Most widget modules will contain two states: one used to initialize the parameter values and one to display the tag's value and other graphics on a page.

The display functions must monitor properties of the tag. If the tag's units or scaling change, the widget will need to update its appearance to match the new format. It should also be able to display the Questionable or Manual Value markers if those exist and are set in the tag. (An example of the code to do this can be seen in Create a Custom Tag Widget.)

Finally, the tag's main state must launch a call to the tag's Common module if it is to support tool tips, trend windows or right-click navigation menus.

An abbreviated version of the states found in the Analog Status tag's Draw widget is presented here as an example. Features such as the alarm display have not yet been covered in this chapter and so are excluded from the example.

Init [
  If 1 Main;
  [
    {***** Set defaults for the parms *****}
    Digits            = PickValid(Digits,    0);
    ShowUnits         = PickValid(ShowUnits, 1);
    Border            = PickValid(Border,    1);
    BgndColor         = PickValid(BgndColor, \DialogBGColor);
    DisableTrend      = PickValid(DisableTrend,      0);
    DisableNavigation = PickValid(DisableNavigation, 0);
    DisableTooltip    = PickValid(DisableTooltip,    0);
  ]
]

Main [

  {***** Work format for display of value *****}
  Format = Concat(Valid(\Value) ? Concat("%0.", PickValid(Digits, 1), "f")
                                : Concat("*.", MakeBuff(PickValid(Digits,
                                               1), 0x2A { * character })),
                  " ",
                  PickValid(\Questionable, 0) ? "?" : "",
                  Valid(\ManualValue) ? "!" : "",
                  PickValid(\Questionable, 0) ||
                            Valid(\ManualValue) ? " " : "",
                  PickValid(ShowUnits, 0) ? "%s" : "",
                 );

  {***** Figure out what the text looks like *****}
  If Watch(1, Format, \ScaledMax, \Units);
  [
    {***** Get the full string - number, decimal, units and all *****}
    Buff       = BuffStream("");
    SWrite(Buff, Format,
           PickValid(PickValid(\ScaledMax, \Value), \Units), \Units);
  ]

  {***** Convert font point text name into an object and a font *****}
  If Watch(1, FontVal);
  [
    DrawFontObj = ValueType(FontVal) == 7 { Tag object } ?
                  FontVal : Scope(\Code, FontVal);
  ]
  ChosenFont = Font(DrawFontObj\FontName, DrawFontObj\CharacterSet,
                    DrawFontObj\Height,
                    DrawFontObj\Rotation, DrawFontObj\Weight,
                    DrawFontObj\Italic,   DrawFontObj\Fixed);

  QualityIssue   = PickValid(Scope(Root, Quality)\Value != 0, 0);

  TextColor = PickValid(Questionable, 0) ? \ButtonShadow :
                (Color == \ButtonTextColor ? 15 : \ButtonTextColor);

    { Background Button }
  GUIButton(0, 30, 200, 0,
            1, 1, 1, 1, 1,
            0, 0, Border, 0, 0, 0, 0,
            BgndColor, \ButtonHighlight , \ButtonShadow, -1,
            4, 0, "", "", 0, 0, 1, 2);
    { Description }
  GUIText(4, 30, 200, 0,
          1, 1, 1, 1, 1,
          0, 0, Border, 1,
          0, 0, 0,
          -1, \ButtonTextColor, PickValid(DrawFontObj\Value, \_DialogFont),
          2, 4,   { Alignment }
          \Description);
    { The indented box }
  GUIButton(130, 26, 196, 4,
            1, 1, 1, 1, 1,
            0, 0, Border, 0, 0, 0, 0,
            -1, \ButtonShadow, \ButtonHighlight, -1,
            4, 0, "", "", 0, 0, 1, 2);

    {***** Display the number *****}
  GUIText(0, 1, 1, 0,
          1 - (Border ? 131 : 0), Border ? 25 : 30,
          Border ? 195 : 200, 1 - (Border ? 5 : 0), 1,
          0, 0, 1, 1,
          0, 0, 0,
          Color, TextColor,
          PickValid(DrawFontObj\Value, \_DialogFont),
          4, 4, { Alignment }
          Format, PickValid(\Value, \Units), \Units);

  {***** Display common features *****}
  \Common(0, 30, 200, 0, DisableTrend, DisableNavigation, DisableTooltip);
]


Indicate Questionable and Manual Data

The unlinked widget, question mark and exclamation mark graphics, used to indicate any of these tag states in a widget, are created by the module TagIconMarker.

This module places a set of icons on the screen centered over a given rectangular region. The icon displayed is cycled with each passage of the period, measured in seconds. The images are provided by the module, but you are free to add your own symbols.

Centering the symbol within the user-defined drawing area requires some calculation. For more information about this function and an example taken from a VTScada tag widget, see IconMarker in the VTScada Function List.

The following example places a set of icons on the screen centered over a given rectangular region. The icon displayed is cycled with each passage of the period, measured in seconds.

  {***** Signify when data is questionable *****}
  GUITransform(0, 100, 100, 0,
               1, 1, 1, 1, 1 { Scaling },
               0, 0 { Movement },
               1, 0 { Visibility, Reserved },
               0, 0, 0 { Selectability },
               Variable("Code\Library")\TagIconMarker(\Root, FALSE));


Sample Widget

In general, custom widgets should be created in the Idea Studio. The parameters for GUITransform statements, while documented, are not meant to be coded by hand. After creating, you may then open the source code to make modifications as required.

The following example shows the code for the Meter19 widget (Antique Bolted). It has been modified slightly so that you can copy this example to your workstation as a .SRC file, then import it into the Idea Studio.

Notes:

  • \Root refers to the tag to which an instance of this widget is linked.
  • In the statement that draws the Radial Legend , Scope(VTSDB, "0h!22-c639", TRUE) refers to one of the VTScada Font tags.
{================================== Meter19 ==================================}
{ Draws a meter that mimics an antique gauge                                  }
{=============================================================================}
(0, 174, 174, 0) { bounding box }
(
  NumMajorDivisions Long      { Number of Major Divisions in the Scale      };
  NumMinorDivisions Long      { Number of Minor Divisions in the Scale      };
  UseTagScaling     Status    { Flag - True to use the Tag's Scaling Values };
  MinScaleValue     Double    { The Value at Minimum                        };
  MaxScaleValue     Double    { The Value at Maximum                        };
  ShowUnits         Status    { Flag - True to show the units on the meter  };
  NeedleColor       Text      { Color of the Needle                         };
  TextColor         Text      { Color of the text and scale                 };
  BackgroundColor   Text      { Color of the text and scale                 };
  DisableTrend      Status    { Flag to disable trend windows               };
  DisableNavigation Status    { Flag to disable navigator (context) menu    };
  DisableTooltip    Status    { Flag to disable tool tips                   };
)
[
  Constant DrawLabel = "Meter19Label";
    { Replace "Meter19Label" with an application property of your own creation }
  Constant #HelpID   = 21363  { HelpID 21363                                  };
    { Create a user-defined help entry and use that value }

  Panel Module;
  Constant PanelWd = 400      { Default panel width                           };
  Constant PanelHt = 500      { Default panel height                          };

  Constant #UseTagScaling     =  2;
  Constant #MinScaleValue     =  3;
  Constant #MaxScaleValue     =  4;
  Constant #DisableTrend      =  9;
  Constant #DisableNavigation = 10;
  Constant #DisableTooltip    = 11;

  { Initial set of tags, to which this meter can be linked }
  Shared AnalogInput (POINTS);
  Shared AnalogStatus (POINTS);
]

Main [
  If Watch(1);
  [
    DisableTrend      = PickValid(DisableTrend,       0);
    DisableNavigation = PickValid(DisableNavigation,  0);
    DisableTooltip    = PickValid(DisableTooltip,     0);
  ]
  \Common(GetModuleRefBox(Self, 0), GetModuleRefBox(Self, 1),
          GetModuleRefBox(Self, 2), GetModuleRefBox(Self, 3),
          DisableTrend, DisableNavigation, DisableTooltip);

  GUITransform(0, 174, 174, 0,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "Library", TRUE)\Bitmap(\ImageParmSet("Bitmaps\Meter Parts\Backgrounds\Case2_Background.png", BackgroundColor, 0, 1, 0, 1, 1, 1, 0, 1, 0, 0), -1, 0, 1, 1, 1, 1, 0, 0, 0, 0, 1, "<FFFFFFFF>", 0, 1));
  GUITransform(9, 181, 165, 25,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "MeterParts", TRUE)\RadialLegend(\Root, 300, 60, PickValid(NumMajorDivisions + 1, 0), Scope(VTSDB, "0h!22-c639", TRUE), TextColor, 0, 1, UseTagScaling, MinScaleValue, MaxScaleValue, 1));
  GUITransform(19, 168, 156, 38,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "MeterParts", TRUE)\SimpleRadialScale(NumMajorDivisions, NumMinorDivisions, 0.07, 0.03, PickValid(Abs(GetXFormRefBox(Self, 1) - GetXFormRefBox(Self, 3)) * 0.008, 0), PickValid(Abs(GetXFormRefBox(Self, 1) - GetXFormRefBox(Self, 3)) * 0.008, 0), 300, 60, 2, 8, TextColor, TextColor));
  GUIText(0, 83, 174, 63,
          1, 1, 1, 1, 1 { Scaling              },
          0, 0          { Movement             },
          PickValid(True(ShowUnits), 0), TRUE { Visibility, Font Scaling },
          0, 0, 0       { Selectability        },
          Brush("<00000000>", 0, 1), Pen(PickValid(TextColor, 0), 1, 1),
          Scope(\VTSDB, "LabelFont", TRUE)\Value,
          3, 4,
          "%s",
          \Root.Units);
  GUITransform(17, 169, 157, 37,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "MeterParts", TRUE)\RadialIndicator(\Root,
                                                                \ImageParmSet("Bitmaps\Meter Parts\Indicators\Radial\Needle13_White.png", NeedleColor, 0, 1, 0, 1, 1, 1, 0, 1, 0, 0),
                                                                -13, 0, 300, 60, 0, 1, 1, 1, 1, 0, 0, UseTagScaling, MinScaleValue, MaxScaleValue, 1, "<FFFFFFFF>"));
  GUITransform(0, 174, 174, 0,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               0.68, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(\Code, "Library", TRUE)\Bitmap(\ImageParmSet("Bitmaps\Meter Parts\Glass\Glass22.png", "<FFFFFFFF>", 0, 1, 0, 0.75, 1, 1, 0, 1, 0, 0), -1, 0, 1, 1, 1, 1, 0, 0, 0, 0, 1, "<FFFFFFFF>", 0, 1));
  GUITransform(0, 174, 174, 0,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Scope(Code, "Library", TRUE)\Bitmap(\ImageParmSet("Bitmaps\Meter Parts\Bezels\Case2.png", \ParameterSet(), \ParameterSet(), \ParameterSet(), \ParameterSet(), \ParameterSet(), \ParameterSet(), \ParameterSet(), \ParameterSet(), \ParameterSet(), \ParameterSet(), \ParameterSet())));
  GUITransform(72, 102, 102, 72,
               1, 1, 1, 1, 1 { Scaling              },
               0, 0          { Movement             },
               1, 0          { Visibility, Reserved },
               0, 0, 0       { Selectability        },
               Variable("\Code.Library")\TagIconMarker(\Root));
]

<
{=============================== Meter19\Panel ===============================}
{=============================================================================}
Panel
(0, PanelHt, PanelWd, 0)
(
  Parms                       { Array of Parameters                           };
  PtrWaitClose                { Pointer to Flag - True to wait to close dlg   };
  ParmDefs                    { Array of page parameter definition structs    };
  DialogRoot                  { The calling dialog window                     };
)
[
  PageInst                    { Page instance                                 };
  ContPageInfo                { Container page information                    };
  Height                      { Current height of the panel                   };
  PEObj                       { Array of ParameterEdit object values          };
  PEBot                       { Array of ParameterEdit Bottom coordinates     };
  SubWaitClose                { Wait-to-close variables for ParameterEdits    };
  TitleWd                     { Width of ParameterEdit titles                 };
  ColorModules                { Used for the "Color" ParameterEdits           };
  ColorParms                  { Used for the "Color" ParameterEdits           };
  ColorValue                  { Used to retain the Revision on the parameters };
  OldColorValue               { Used to retain the Revision on the parameters };
]

Init [
  If 1 Main;
  [
     { Get info about the parms of the container page }
    PageInst     = \GetUserSession()\GraphicEditor\GetSelectedTabItem();
    ContPageInfo = \GetParamInfo(PageInst);

    PEObj = New(7);
    PEBot = New(7);
    SubWaitClose = New(7);

    ColorModules = New(5);
    ColorParms   = New(5);

    ColorModules[0]  = "ParmEditColor";
    ColorParms[0]    = New(1);
    ColorParms[0][0] = TRUE;

    ColorModules[1]  = "ParmEditTagValue";
    ColorParms[1]    = New(2);
    ColorParms[1][0] = "Numeric";
    ColorParms[1][1] = 0; { No Scaling }

    ColorModules[2]  = "ParmEditParmValue";
    ColorParms[2]    = New(5);
    ColorParms[2][0] = ContPageInfo;
    ColorParms[2][1] = \#VTypeShort;
    ColorParms[2][2] = \#VTypeText;
    ColorParms[2][3] = Invalid;
    ColorParms[2][4] = 0;

    ColorModules[3]  = "ParmEditTagProperty";
    ColorParms[3]    = New(5);
    ColorParms[3][0] = ContPageInfo;
    ColorParms[3][1] = \#VTypeShort;
    ColorParms[3][2] = \#VTypeText;
    ColorParms[3][3] = Invalid;
    ColorParms[3][4] = 0;

    ColorModules[4]  = "ParmEditExprNoNormalize";
    ColorParms[4]    = New(2);
    ColorParms[4][0] = 1 + 2;
    ColorParms[4][1] = ContPageInfo;

    ColorValue    = New(3);
    OldColorValue = New(3);
    ColorValue[0] = OldColorValue[0] = Parms\NeedleColor;
    ColorValue[1] = OldColorValue[1] = Parms\TextColor;
    ColorValue[2] = OldColorValue[2] = Parms\BackgroundColor;
    MetaData(ColorValue[0], "Revision") = 0;
    MetaData(ColorValue[2], "Revision") = 0;
    MetaData(ColorValue[3], "Revision") = 0;
  ]
]

Main [
   { Let the caller know when its not ok to close.  Or is used so we can
      maintain the 2nd bit of the WaitClose flag that is set when an expression
      has some compiler errors in it.  It is used for an error dialog.  }
  *PtrWaitClose = Or(PickValid(SubWaitClose[0], 0), PickValid(SubWaitClose[1], 0),
                     PickValid(SubWaitClose[2], 0), PickValid(SubWaitClose[3], 0),
                     PickValid(SubWaitClose[4], 0), PickValid(SubWaitClose[5], 0),
                     PickValid(SubWaitClose[6], 0));

  Height = PEBot[6] + 5*\Space + \TitleSpace + 3*\CheckHt;
  If Watch(1, Height);
  [
    \SetPanelRefBox(Self, 0, Height, PanelWd, 0);
  ]
  TitleWd = Max(TextAttribs(GetPhrase("NumMajorDivisionsLabel"),  \_DialogFont, 0),
                TextAttribs(GetPhrase("NumMinorDivisionsLabel"),  \_DialogFont, 0),
                TextAttribs(GetPhrase("UseTagScalingLabel"),      \_DialogFont, 0),
                TextAttribs(GetPhrase("ShowUnitsLabel"),          \_DialogFont, 0),
                TextAttribs(GetPhrase("NeedleLabel"),             \_DialogFont, 0),
                TextAttribs(GetPhrase("TextLabel"),               \_DialogFont, 0),
                TextAttribs(GetPhrase("BackgroundLabel"),         \_DialogFont, 0),
                TextAttribs(GetPhrase("MinimumValueLabel"),       \_DialogFont, 0),
                TextAttribs(GetPhrase("MaximumValueLabel"),       \_DialogFont, 0));

  System.Bevel(0, PEBot[2] + \Space, PanelWd, 0, \GetPhrase("OptionsLabel)");

   { Number of Major divisions }
  PEObj[0] = \NumericParameterEdit(\Space,
                                   \Space + \TitleSpace + 2*\EditHt,
                                   PanelWd - \Space,
                                   \Space + \TitleSpace,
                                   Parms\NumMajorDivisions, ParmDefs\NumMajorDivisions,
                                   FALSE, \GetPhrase("NumMajorDivisionsLabel"), &(SubWaitClose[0]),
                                   DialogRoot, 1, 100, Invalid, TitleWd,
                                   TRUE, 1 {FID}, \#VTypeLong, TRUE);
  PEBot[0] = \Space + \TitleSpace + PickValid(PEObj[0]\Height, 2*\EditHt);

   { Number of Minor divisions }
  PEObj[1] = \NumericParameterEdit(\Space,
                                   PEBot[0] + \Space + 2*\EditHt,
                                   PanelWd - \Space,
                                   PEBot[0] + \Space,
                                   Parms\NumMinorDivisions, ParmDefs\NumMinorDivisions,
                                   FALSE, \\GetPhrase("NumMinorDivisionsLabel"), &(SubWaitClose[1]),
                                   DialogRoot, 1, 100, Invalid, TitleWd,
                                   TRUE, 2 {FID}, \#VTypeLong, TRUE);
  PEBot[1] = PEBot[0] + \Space + PickValid(PEObj[1]\Height, 2*\EditHt);

   { Show Units }
  PEObj[2] = \NumericParameterEdit(\Space,
                                   PEBot[1] + \Space + 2*\EditHt,
                                   PanelWd - \Space,
                                   PEBot[1] + \Space,
                                   Parms\ShowUnits, ParmDefs\ShowUnits,
                                   FALSE, \\GetPhrase("ShowUnitsLabel"), &(SubWaitClose[2]),
                                   DialogRoot, 0, 1, Invalid, TitleWd,
                                   TRUE, 3 {FID}, \#VTypeStatus);
  PEBot[2] = PEBot[1] + \Space + PickValid(PEObj[2]\Height, 2*\EditHt);

  System.Bevel(0, PEBot[5] + \Space, PanelWd, PEBot[2] + 2*\Space, \ColorizationLabel);

   { Needle color }
  GUITransform(0, 1, 1, 0,
               1 - \Space,
               PEBot[2] + 3*\Space + \TitleSpace + 2*\EditHt,
               PanelWd - \Space,
               1 - (PEBot[2] + 3*\Space + \TitleSpace), 1,
               0, 0, 1, 0,
               0, 0, 0,
               PEObj[3] = \ParameterEdit(ColorValue[0], ParmDefs\NeedleColor,
                                         TRUE, \GetPhrase("NeedleLabel"), ColorModules, Code, ColorParms,
                                         TitleWd, Invalid, &(SubWaitClose[3]), DialogRoot, 4 {FID}));
  If ColorValue[0] != OldColorValue[0] ||
     Valid(ColorValue[0]) != Valid(OldColorValue[0]);
  [
    OldColorValue[0] =
    Parms\NeedleColor = RootValue(ColorValue[0]);
  ]
  PEBot[3] = PEBot[2] + 3*\Space + \TitleSpace + PickValid(PEObj[3]\Height, 2*\EditHt);

   { Text Color }
  GUITransform(0, 1, 1, 0,
               1 - \Space,
               PEBot[3] + \Space + 2*\EditHt,
               PanelWd - \Space,
               1 - (PEBot[3] + \Space), 1,
               0, 0, 1, 0,
               0, 0, 0,
               PEObj[4] = \ParameterEdit(ColorValue[1], ParmDefs\TextColor,
                                         TRUE, \GetPhrase("TextLabel"), ColorModules, Code, ColorParms,
                                         TitleWd, Invalid, &(SubWaitClose[4]), DialogRoot, 5 {FID}));
  If ColorValue[1] != OldColorValue[1] ||
     Valid(ColorValue[1]) != Valid(OldColorValue[1]);
  [
    OldColorValue[1] =
    Parms\TextColor  = RootValue(ColorValue[1]);
  ]
  PEBot[4] = PEBot[3] + \Space + PickValid(PEObj[4]\Height, 2*\EditHt);

   { Background color }
  GUITransform(0, 1, 1, 0,
               1 - \Space,
               PEBot[4] + \Space + 2*\EditHt,
               PanelWd - \Space,
               1 - (PEBot[4] + \Space), 1,
               0, 0, 1, 0,
               0, 0, 0,
               PEObj[5] = \ParameterEdit(ColorValue[2], ParmDefs\BackgroundColor,
                                         TRUE, \GetPhrase("BackgroundLabel"), ColorModules, Code, ColorParms,
                                         TitleWd, Invalid, &(SubWaitClose[5]), DialogRoot, 6 {FID}));
  If ColorValue[2] != OldColorValue[2] ||
     Valid(ColorValue[2]) != Valid(OldColorValue[2]);
  [
    OldColorValue[2]      =
    Parms\BackgroundColor = RootValue(ColorValue[2]);
  ]
  PEBot[5] = PEBot[4] + \Space + PickValid(PEObj[5]\Height, 2*\EditHt);

   { Scaling limits }
  GUITransform(0, 1, 1, 0,
               1 - 0,
               PEBot[5] + 2*\Space + \TScalingFldsHt,
               PanelWd,
               1 - (PEBot[5] + 2*\Space),
               1                        { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               PEObj[6] = \TagScalingFields(Parms, #UseTagScaling, #MinScaleValue, #MaxScaleValue,
                                            \Root, &(SubWaitClose[6]), 7 { ID + 2 end }, ParmDefs, DialogRoot, TitleWd));
  PEBot[6] = PEBot[5] + 2*\Space + PickValid(PEObj[6]\Height, 2*\EditHt);

   { Disable Options }
  System.Bevel(0,
                PEBot[6] + 5*\Space + \TitleSpace + 3*\CheckHt,
                PanelWd,
                PEBot[6] + \Space,
                \GetPhrase("DisableOptionsLabel"));

   { Disable Trends Check Box }
  GUITransform(0, 1, 1, 0,
               1 - (\Space + \BvlWd),
               PEBot[6] + 2*\Space + \TitleSpace + \CheckHt,
               PanelWd,
               1 - (PEBot[6] + 2*\Space + \TitleSpace), 1,
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PCheckBox(#DisableTrend, \GetPhrase("DisableTrendLabel"),
                                        1  { box on left },
                                        3  { left, centered },
                                        11 { ID }));

   { Disable Navigation Check Box }
  GUITransform(0, 1, 1, 0,
               1 - (\Space + \BvlWd),
               PEBot[6] + 3*\Space + \TitleSpace + 2*\CheckHt,
               PanelWd,
               1 - (PEBot[6] + 3*\Space + \TitleSpace + \CheckHt), 1,
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PCheckBox(#DisableNavigation, \GetPhrase("DisableNavigationLabel"),
                                        1  { box on left },
                                        3  { left, centered },
                                        12 { ID }));

   { Disable Tooltip Check Box }
  GUITransform(0, 1, 1, 0,
               1 - (\Space + \BvlWd),
               PEBot[6] + 4*\Space + \TitleSpace + 3*\CheckHt,
               PanelWd,
               1 - (PEBot[6] + 4*\Space + \TitleSpace + 2*\CheckHt), 1,
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PCheckBox(#DisableTooltip, \GetPhrase("DisableTooltipLabel"),
                                        1  { box on left },
                                        3  { left, centered },
                                        13 { ID }));
]
{ End of Meter19\Panel }
>
{ End of Meter19 }


Widgets List for Programmers

General purpose widgets

Declared name | Widget
ActiveInd | Active Indicator
NotesAddButton | Add Note Button
NotesAddField | Add Note Field
AlarmPriorityIndicator | Alarm Priority Indicator
AlarmPriorityIndicatorBox | Alarm Priority Indicator Box
HPAnalogBarIndicator | Analog Bar & Indicator
HPAnalogBar | Analog Bar
HPAnalogIndicator | Analog Indicator
AnimatedBitmap | Animated Bitmap
Meter14 | Antique
Meter19 | Antique Bolted
Meter8 | Aqua
Meter21 | Arc
Meter9 | Army
Meter25 | Audio
Meter10 | Backlit
BottomBar | Bottom Bar
CampbellPointers | Campbell Pointers
SelectorSwitchDrawCheckbox | Check box
Meter5 | Classic
Meter7 | Cockpit
ColorBlink | Color Blink (four state)
TwoStateColorBlink | Color Blink (two state)
ColorBox | Color Box (four state)
TwoStateColorBox | Color Box (two state)
ColorFill | Color Fill
ColorLine | Color Line
CommLine | Comm Line
CommandButton | Command Button
CommMessages | Communication Messages
CommIndicator | Communication Status Indicator
CommStatistics | Communications Statistics
Compass1 | Compass 1
Compass2 | Compass 2
PortImageChange | Connection Status (port)
CurrentHistIndex | Current History Index
Data_Age | Data Age
DotMatrixNumeric | Dot Matrix Numeric
DrawAlarmList | Draw Alarm List
DrawElapsedTime | Draw Elapsed Time
DrawHDV | Draw HDV
DrawLastLoggedValue | Draw Last Logged Value
DrawText | Draw Text
StringDropList | Drop List
EnablePollingCB | Enable Polling Check box
 | Equipment - see Status Color
Fast_Scan | Fast Scan
GenericSiteDraw | Generic Site Draw
Meter26 | Glance
Meter4 | Glass
GradColorChange | Gradient Color Change
SelectorSwitchDrawHButtons | Horizontal Buttons
HoursEntry | Hours Entry
IlluminatedToggleSwitch | Illuminated Toggle Switch
ImageChange | Image Change (four state)
TwoStateImageChange | Image Change (two state)
IndicatorLight | Indicator Light
IOMultiText | IO Multi Text
Meter16 | LCD Arc
LCDBar | LCD Bar
Meter17 | LCD Meter
Meter15 | LCD Ring
LEDNumeric | LED Numeric
LeftBar | Left Bar
Meter13 | Linear
MapDraw | Map Draw
Meter24 | Metal
Meter1 | Meter 1
Meter2 | Meter 2
Meter3 | Meter 3
ModemStatus | Modem Status
ModemIndicator | Modem Status Indicator
MomentaryPushButton | Momentary Push Button
MultiColor | MultiColor
MultiText | MultiText
MultiWriteBtn | MultiWrite Button
MultiWriteBox | MultiWrite Hotbox
Meter11 | Nautical
NetworkStatusDraw | Network Link
Number | Numeric Value
NumericDataEntry | Numeruc Entry
PakBusDriverInfo | PakBus Driver Info
Meter20 | Pie Chart
PlotData | Plot Data
PolledStation | Polled Station
Meter22 | Power
Meter18 | Pressure
PushButton | Push Button
Meter12 | Quarter Arc
ResetButton | Reset Button
ResetHistoryPoll | Reset History Poll
ResetTarget | Reset Target
Meter6 | Retro
ReWriteOutputsBtn | ReWrite Outputs Button
RightBar | Right Bar
ROCDriverHistInfo | ROC Driver History Info
ROCDriverHistReset | ROC Driver History Reset
RotaryControl | Rotary Control
SelectorSwitchDraw | Selector Switch
SetAOValue | Set Analog Value Hotbox
CommandTarget | Legacy Set Value Hotbox
ActiveInd | Site Active Indicator
SiteDraw | Site Draw
Slider | Slider
Sparklines | Sparklines
SpiderGraph | Spider Graph
SMSIndicator | SMS Appliance Status Indicator
StatusIndicator | Status Color (Equipment)
StringDroplist | Droplist
StringEntry | String Entry
TagListDM | Tag List
TextChange | Text Change (four state)
TwoStateTextChange | Text Change (two state)
Meter23 | Thermometer
TogglePollingBtn | Toggle Polling button
SelectorSwitchDrawToggle | Toggle Switch
TopBar | Top Bar
Totalizer | Totalizer
TwoColorBar | Two Color Bar
SelectorSwitchDrawVButtons | Vertical Buttons

Alarm panel library

Declared name | Widget
AlarmPanelAckAllBtn | Acknowledge All Button
AlarmPanelAckSelected | Acknowledge Selected Button
AlarmPanelAckShown | Acknowledge Shown Button
AlarmPanelSelectDateButton | Alarm Date Selector
AlarmPanelGoToTodayButton | Alarm GoTo Today
AlarmPanelDrawBanner | Draw Banner
AlarmPanelDrawList | Draw List
AlarmPanelFilterDialog | Filter Dialog
AlarmPanelFilterField | Filter Field
AlarmPanelListButton | List Button
AlarmPanelMuteButton | Mute Button
AlarmPanelSilenceButton | Silence Button
AlarmPanelNumericBinSort | Sort Button

Report library

Declared name | Widget
ReportButton | Report Button
ReportOutputType | Report Destination
ReportOptionList | Report Options List
ReportTagList | Report Tag List
ReportTypeList | Report Type
ReportTimeList | Reporting Period
ReportTagTimeList | Reporting Period Enhanced

Notebook library

Declared name | Widget
NotesAddButton | Add Note Button
NotesAddField | Add Note Field Button
NotesDisplay | Note List

Site graphics (aka LiftStation graphics)

Declared name | Widget
LSAlarmList | Alarm List
LSAnalogControl | Analog Control
LSAnalogControlList | Analog Control List
LSAnalogDisplay | Analog Display
LSAnalogInputList | Analog Input List
LSDigitalButton | Digital Button
LSDigitalInputList | Digital Input List
LSDigitalOutputList | Digital Output List
LSDigitalIndicator | DigitalIndicator
MPEPumpControl | MPE Pump Control
MPEStationStats | MPE Station Stat
LSNumericEntry | Numeric Entry
LSPumpControl | Pump Control
LSPumpList | Pump List
LSSelectorSwitch | Selector Switch
LSSiteDetails | Site Details
LSStationAllInputs | Station All Inputs
LSStationAllOutputs | Station All Outputs
LSStationComms | Station Comms
LSStationDetails | Station Details
LSStationDraw | Station Draw
LSStationFaults | Station Faults
LSStationIcon | Station Icon
LSStatusDisplay | Status Display
LSTitleHeader | Title Header
LSWellDetails | Well Details
LSWellFlow | Well Flow
LSWellPlot | Well Plot
LSWellSetpoint | Well Setpoint
LSWellSetpointSlider | Well Setpoint Slider
LSWellSetpoints | Well Setpoint


The Tag Widget Reference Folder

When you click the Draw command for a tag in the Tag Browser, VTScada will check the list of Tag Widget Reference Folders for an entry matching the type of tag you are about to draw. If found, you will be given the matching list of widgets to choose from. If there is no matching reference folder, then VTScada will make a longer search for widgets that can be used with a type, and present a list of folders containing those widgets.

When there is a small set of widgets that match a type then it is more efficient for those to be grouped together in a reference folder.

For example, there is a reference folder for the Roster type, containing the widgets most commonly used when drawing that type. When drawing a Roster, you will see only those widgets.

By contrast, the Analog Status tag can be represented by many types of widgets, found in many folder groups. It is also common for developers to create their own widgets that can be linked to the Analog Status. In this case, it is better to let VTScada search out all matching widgets and present those, still grouped by folder.

If you were to create a new widget for Roster types, then you might add a Menu Item for it to the folder referenced by the Rosters entry in this list: [Widgets\Tag Type Widgets\Communications\Alarm Dialer\Roster Widgets]. Note however, that there is no requirement that you do anything at all with these reference folders.

If you have a custom tag type and have created several widgets that may be linked to that type, you can achieve the effect of having a Tag Widget Reference Folder by placing those widgets into a folder that is named after your custom type. This folder may be placed anywhere in the Widgets hierarchy.


Common Module

Various user-interface features are common to the VTScada tag widgets. The widgets will issue calls to the Common module of the associated tag to provide the contents and functionality of the interface feature. These may include a call to the Navigator module (context menu), the ToolTip module, and the PkTrend module. Any external graphic modules must make a call to the Common module within the tag. The Common module takes four parameters that define the area of the screen occupied by the drawing object and three that allow an instance of a tag to disable the user interface elements. The seven parameters of the Common module are:

  • Left - Any numeric expression for the object's left side coordinate.
  • Bottom - Any numeric expression for the object's bottom coordinate.
  • Right - Any numeric expression for the object's right side coordinate.
  • Top - Any numeric expression for the object's top coordinate.
  • DisableTrend - Any Boolean expression for disabling the trend window
  • DisableNavigation - Any Boolean for disabling the right-click menu
  • DisableTooltip - Any Boolean expression to disable the tooltip display

For example, most widgets will display a pop-up menu in response to a right-click.

The menu that appears is under your control via the Navigator module. It is up to you to decide what to include in this module for your custom tags and what each entry should do.

Related information:

Navigator Calls (Shortcut Menu)

ToolTip Contents

Open an HDV (trend) Window

Common Module Example


Navigator Calls (Shortcut Menu)

Calls to the Navigator result in a context menu being associated with a tag type. When the user right clicks on the graphic object representing the value of a tag, the context menu opens and enables the user to configure the tag's properties. Tag properties modified using the context menu are automatically written to the tag properties database, following a call to the "Refresh" module.

Access to the context menu is controlled by the Security Manager, which has a specific system bit set aside for this purpose (\SecurityManager\PrivBitConfigure). The Security Manager handles the privileges granted to the signed in user, and disables any context menu options or tag properties for which the signed in user is not authorized. See: Security for Output Tags

Navigator Module Parameters

The activation of the Navigator should not occur when a tag's widget is in preview mode or when the Navigator module is called from a container's drawing module.

The first parameter for the Navigator module (Enable), detects if the system is in preview mode, or if the Navigator module is being called by a container module.)

Parameters of the Navigator module:

  • Enable - The Enable parameter is set to 1 (true) when the shortcut menu may appear. The shortcut menu is disabled during the preview and placement process.
  • Left - The left coordinate of the object to click upon to open the shortcut menu.
  • Bottom - The bottom coordinate of the object to click upon to open the shortcut menu.
  • Right - The right coordinate of the object to click upon to open the shortcut menu.
  • Top - The top coordinate of the object to click upon to open the shortcut menu.

The Navigator takes groups of four additional significant parameters that describe the menu items and their actions. These parameters are appended to the end of the parameter list in groups of four. Each group of four defines one line in the shortcut menu.

Navigator supports NavData structures for passing parameters to launched modules. Prior to the release of VTScada 12.1.29, modules could be launched from a Navigator call by setting the property NavTabNums to the module name that should be launched, however no parameters could be passed in to that module.

Instead, you can provide a NavData struct, which will contain the module name and up to 16 parameters to be passed to that module. The Navigator works as before with strings, but when a NavData struct is encountered the module will be launched and the parameters in the struct will be passed to it.

NavContents

The shortcut menu option's name. If the name is set equal to "--", a beveled ruling line is placed in the menu, rather than a selectable text option.

NavToggles

A pointer to a value that is a toggle option (i.e. each time this shortcut menu option is selected in the shortcut menu, it is toggled on or off (i.e. is logically inverted)). When the value of the variable pointed to is true, the shortcut menu option is toggled on, and a check mark appears to its left. When the value of the variable pointed to is false, the shortcut menu option is toggled off, and no check mark appears to its left. Any element may be invalid if not used. If the NavTabNums element is used to open the tag's properties folder, this value must be invalid. If the variable pointed to by this parameter is in a module other than the one pointed to by the "Root" parameter (please see previous section), the NavTabNums parameter contains the object value of that other tag.

The NavToggles parameter can also serve a very different purpose if it contains an object value, in which case it will be the tag instance to use to launch the TabNums parameter actions within. This can be used to allow direct access to sub-tag parameter configuration folders, or to launch modules within other contexts. This cannot be used in combination with the TabNums parameter value being invalid, since the TabLabels will not correspond to the correct tag properties folder.

NavDisabled

May have three meanings as follows:

  • Negative number: Treated as a privilege number. A security check will be made to ensure that the currently signed in account has the right to view this menu.
  • 0 (FALSE): Enabled
  • 1(TRUE): Disabled

NavTabNums

An index that indicates the tab number (of the tag properties folder) to display if the shortcut menu option is selected (tag properties folder tabs are labeled starting at 0). If this value is invalid, the entire tag properties dialog is opened (i.e. rather than a single tab displayed as a window, the tag properties dialog will open to the ID tab, and will additionally reveal its other tabs).

If this value is a text string, a module by that name is launched within the scope of the calling tag. If the corresponding NavToggles entry has an object value, the module is launched within the scope of that object value.

If NavTabNums is an instance of NavData(ModuleName, Parm0, Parm1...) the module ModuleName will be launched in the tag scope and passed the parameters supplied. Up to 16 parameters can be supplied in this way

If the variable pointed to by the NavToggles parameter is in a module other than the one pointed to by the "Root" parameter, the NavTabNums parameter contains the object value of that other tag.

If the NavToggles parameter is a pointer to a parameter of a tag that is not in that current tag, this value must be the object value of the tag where that toggled parameter exists.

To summarize, there are the following modes for these parameters:

Action | NavToggles | NavTabNums
Full tag properties folder | Invalid | Invalid
Single tab tag properties folder | Invalid | Tab number
Toggle parm in this tag | Pointer to the parm | Invalid
Toggle parm in another tag | Pointer to the parm | Object value of other tag
Launch module in tag scope | Invalid | Module name (text)
Launch module in tag scope | Invalid | NavData(ModuleName (text), parameters)
Launch module in other scope | Scope in which to run | Module name (text)


ToolTip Contents

When the user holds the mouse pointer over a widget, the normal VTScada behavior is to display the associated tag's name and description. You can control what text will be displayed for your tag by including a call to WinToolTipCtrl in your tag's Common module.

If your Common module does not include a call to WinTooltipCtrl, then there won't be a tool-tip.

The target for the tool-tip should be the same as the area parameters passed to the Common module. If this point is contained within another object and the container calls this widget's module, then you do not want this tool tip note to display. This is typically indicated by the calling container's widget module adding one additional parameter to the list. By detecting that the number of parameters that the widget is called with is not the same as the number of formal parameters, you can prevent the tool tip note from appearing. This will also prevent the note from appearing during preview and placement which is also desirable.

For example:

  WinTooltipCtrl(Left, Bottom, Right, Top,
                 WTTS_FLAG_TRACKINACTIVE + (PickValid(\NoBalloonTips, 0) ? 0 : WTTS_FLAG_BALLOON),
                 \GetPhrase(\Description), \Name, Invalid,
                 \ShowTip && ! *pNavActive && PickValid(! DisableTooltip, 1),
                 \TipFont\Value);


Open an HDV (trend) Window

If your tag contains a value that can be trended, then you may include a call to PKTrend in the Common module. This will watch for a left-click within the area of the widget and open a Historical Data Viewer window in response.

This code is generally incompatible with the control dialog code, which uses the same mouse button. The first four parameters should match the area as indicated by Left, Bottom, Right & Top because they specify the target area for the mouse. The last parameter is the object value of this point instance.

This function will automatically be disabled when the page is in editing mode.

For example:

((DisableTools || True(TrendPopupDisable)) ? Invalid : Self)\PkTrend(Left, Bottom, Right, Top, \Root, TRUE);


Common Module Example

The code to enable this menu for the Analog Status tag is as follows:

{=========================== AnalogStatus\Common ===========================}
{ This module handles the common actions associated with all drawing        }
{ modules for this point.  It will be called by all external drawing        }
{ modules.                                                                  }
{===========================================================================}
(
  Left                        { Area occupied by the drawing object         };
  Bottom;
  Right;
  Top;
  DisableTrend                { Flag to disable trend windows               };
  DisableNavigation           { Flag to disable navigator menu              };
  DisableTooltip              { Flag to disable tool tips                   };
)

[
  PROTECTED TrendPopupDisable { Trend popup Disabled flag                   };
  PROTECTED pNavActive        { Pointer to user session nav active flag     };
  PROTECTED DisableTools      { Flag, TRUE if tools are to be disabled      };
]

Init [
   { Run functions here to reduce Common state module load }
  If Watch(1) Common;
  [
    pNavActive = &\GetUserSession().NavActive;
  ]
]

Common [
   { Disable some tools if we're in an editing window or a preview }
  DisableTools = TRUE(ParentWindow().Editing);

  {*************************************************************************}
  { "Post-it" note section                                                  }
  {*************************************************************************}

  WinTooltipCtrl(Left, Bottom, Right, Top,
                 WTTS_FLAG_TRACKINACTIVE + (PickValid(\NoBalloonTips, 0) ? 0 : WTTS_FLAG_BALLOON),
                 GetPhrase(\Description),
                 \System.ShrinkTagName(\Name, #TOOLTIP_MAX_TITLE_LENGTH, Invalid, Invalid, TRUE),
                 Invalid,
                 \ShowTip && ! *pNavActive && PickValid(! DisableTooltip, 1),
                 \TipFont\Value);

  {*************************************************************************}
  { Navigator menu section                                                  }
  { Only run the SecurityCheck if trends haven't been disabled by other     }
  { parameters.                                                             }
  {*************************************************************************}

  TrendPopupDisable = ! PickValid(((True(DisableTrend) || False(\AITrendEnable))
                                  ? Invalid
                                  : \SecurityManager).SecurityCheck(\SecurityManager.PrivBitHDVAccess, 1), 0)
                                    || True(DisableTrend) || False(\AITrendEnable);

  ((DisableTools || True(DisableNavigation)) ? Invalid : Self)\Navigator(
   TRUE { Disabling is done in the call, not parameters },
   Left, Bottom, Right, Top         { Target area for opening - same as
                                      the GUI statement area.          },
   { Menu line 1 } "HelpLabel", Invalid, 0, "HelpLaunch",
   { Menu line 2 } "--", Invalid, 0, Invalid,
   { Menu line 3 } True(\AlarmStatusLo.IsShelved)
                     ? "UnShelveLowAlarmLabel"
                     : "ShelveLowAlarmLabel", Invalid, !Valid(\AlarmStatusLo)
                                                        ? TRUE
                                                        : \SecurityManager.PrivBitAlarmShelve,
                                                          \LowAlarmNavData,
   { Menu line 4 } True(\AlarmStatusHi.IsShelved)
                     ? "UnShelveHighAlarmLabel"
                     : "ShelveHighAlarmLabel", Invalid, !Valid(\AlarmStatusHi)
                                                         ? TRUE
                                                         : \SecurityManager.PrivBitAlarmShelve,
                                                           \HighAlarmNavData,
   { Menu line 5 } "InhibitLowAlarmLabel", &(\InhibitLo), !Valid(\PriorityLo)
                                                           ? TRUE
                                                           : \SecurityManager.PrivBitAlarmInhibit, Invalid,
   { Menu line 6 } "InhibitHighAlarmLabel", &(\InhibitHi), !Valid(\PriorityHi)
                                                            ? TRUE
                                                            : \SecurityManager.PrivBitAlarmInhibit, Invalid,
   { Menu line 7 } "AlarmSettingsLabel",   Invalid,  \SecurityManager.PrivBitAlarmInhibit,  3,
   { Menu line 8 } "ViewAlarmsLabel",      Invalid,  \SecurityManager.PrivBitAlarmPageAccess, "TagAlarmList",
   { Menu line 9 } "--",                   Invalid,  0,                                    Invalid,
   { Menu line 10} "ManualDataLabel",      Invalid,  \SecurityManager.PrivBitManualData,   5 { Quality tab   },
   { Menu line 11} "LoggingDeadbandLabel"  Invalid,  \SecurityManager.PrivBitManualData,   7 { Historian tab },
   { Menu line 12} "QuestionableLabel",    &(\Questionable),  \SecurityManager.PrivBitQuestionable,  Invalid,
   { Menu line 13} "PlotDataLabel",        Invalid,  TrendPopupDisable,                   "TrendPicked",
   { Menu line 14} "--",                   Invalid,  0,                                   Invalid,
   { Menu line 15} "PropertiesLabel",      Invalid,  0,                                   Invalid);

  {*************************************************************************}
  { Trend window pop-up section                                             }
  {*************************************************************************}

  ((DisableTools || True(TrendPopupDisable)) ? Invalid : Self)\PkTrend(Left, Bottom, Right, Top, \Root, TRUE);
]

{ End of AnalogStatus\Common }


Link to a Driver

If the purpose for your custom tag is to connect to hardware to read or write values then you must link it to a driver. A parameter must be added to create this link:

DeviceTag  <:TagField("SQL_VARCHAR(255)"):> = "*Driver"
             { Driver tag to communicate through                 };

When a user configures an instance of this tag, the name of the associated I/O device driver will be stored in this parameter.

Rather than using this parameter directly within the tag code, it is common to use the tag's Variables section to specify a location where the object value of the I/O device will be stored. Also, the raw value from the I/O tag will not be used directly as the tag's value - rather, it will be stored in a local variable. When the raw I/O value changes, scaling or other operations can be applied to find the tag's new value.

Updating the example code, the Variables section will now look like the following, where the last line refers to the driver:

    { Variables }
  Value (5)          { Scaled value for this point.                 };
  RawValue           { Data value read from the IO                  };
  Root               { Set to individual instance of this module    };
  SitePoint          { Object value of DeviceTag parameter          };

The Main state will be responsible for linking the variable to the object value of the I/O device tag:

CustomTagMain [
   SitePoint = Scope(Root, DeviceTag);
]

The code examples just shown will suffice to link your tag to a I/O device driver. It will be the job of your tag's Refresh module to add or remove reads for the addresses in the device driver in response to any change in parameters. Other modules will take care of handling data sent from the driver.

PAddressEntry

You must provide a way for the developer to specify the address to use on the I/O device driver. The PAddressEntry function serves this purpose. This will display a standard edit field, or if the driver includes an AddressAssist module, will display the user-interface elements coded there. (see: Provide an AddressAssist Module in the Communication Drivers chapter.)

ScanInterval

A ScanInterval parameter should be provided to allow control over frequency of driver reads.


Trigger a Data Read

Having established a link between your tag and a driver tag (previous topic), your Refresh module must issue an AddRead request to the driver to start receiving data. If any of the connection parameters change, this request should be cleared and a fresh AddRead issued.

After the AddRead has been issued to the driver instance, it is then up to the driver code to poll the PLC at the ScanInterval rate and send new values back to the specified destination. Note: The Refresh module is not used to handle new values from the driver. For that, you will need a NewData module, as covered in the following topic.

The following example (taken from the Analog Input tag's Refresh module) shows how the AddRead function should be called. The tag's RawValue parameter is used as the destination for the value read from the driver. You may then write code that scales this before using the result as the tag's value or, if the manual data flag is set, ignores the raw data value in favor of the manual data value. Note that this example is for analog data - digital values are read using the same technique, but would not be scaled.

Refresh [
  If 1;
  [

    {***** Scan Interval *****}
    ScanInterval = PickValid(Cast(ScanInterval, 3),
                             GetDefaultValue(&ScanInterval));

    {***** The connection parameters were set or changed *****}
    IfThen (PickValid(Parm[#IODevice]      != DeviceTag,    1) ||
            PickValid(Parm[#ScanInterval]  != ScanInterval, 1) ||
            PickValid(Parm[#Address], "")  != PickValid(Address, ""),

      {***** Remove the previous read request (this will do nothing
             if the parameters are invalid) *****}
      Scope(Root, Parm[#IODevice])\Driver\DelRead(Parm[#Address],
                                       &RawValue, Parm[#ScanInterval]);

      RawValue = Invalid { old value no longer valid };

      {***** Add a new read request *****}
      Scope(Root, DeviceTag)\Driver\AddRead(Address
                        { Address in the PLC for the data },
                                              1
                        { Number of data elements to get         },
                                              &RawValue
                        { Destination pointer for data read      },
                                              ScanInterval
                        { Scan Interval                          });
    );
    {******************************************************************}
    { ManualValue                                                      }
    {******************************************************************}
    ManualValue = Cast(ManualValue, 3 { Float });
    IfElse (Valid(ManualValue),
      Value = ManualValue;
    { Else } IfThen (!ExternalValue,
      Value = IsText ? RawValue : Scale(RawValue, UnscaledMin,
                                        UnscaledMax, ScaledMin, ScaledMax);
    ));


The NewData Module

While it is true that there is more than one method for reading values from an I/O driver, use of the NewData module is recommended for all new tags.

If your tag includes a module named NewData, with the structure similar to that shown in the following example, the I/O driver will use it to send values from the device to the tag.

NewData should have the following five parameters where the last two, Quality and ServiceSync, are optional.

NewData
(
  Addr              { Address we asked for                        };
  TimeStamps        { Single value or 1D array of UTC timestamps  };
  Data              { Single value or 1D array of unscaled data
                      values                                      };
  Quality           { Single value or 1D array of Quality data    };
  ServiceSync       { used to denote that the NewData call was made
                      as a result of a server synchronization (the
                      server has just started up and this
                      data has been taken from a running server) };
)

For purposes of comparison, the body of the NewData modules from both the Analog Status tag and the Digital Status tag are reprinted here.

Items to note are:

  • The RawValue is found in the first item of the Data array.
  • The NeedValueUpdate variable scopes to the parent tag module. This is used to alert the tag to the fact that a new value has been received and that the tag's value should be updated.
  • The largest portion of the module provides support for drivers that send history values. These are scaled and logged as required.

NewData() example for reading analog values:

<
{========================== NewData ===============================}
{ Subroutine that receives and processes incoming data from driver }
{ RefreshData in VTSDriver guarantees that TimeStamps is a valid   }
{ time stamp or an array of valid time stamps regardless of the    }
{ validity of Data                                                 }
{==================================================================}
NewData
 (
  Addr               { Address we asked for                        };
  TimeStamps         { Single value or 1D array of UTC timestamps  };
  Data               { Single value or 1D array of unscaled data
                       values                                      };
)
 [
  I                  { General counting variable                   };
  HistSizeRet        { Size of history list returned               };
  MaxHistTS          { Highest TS in history list                  };
  LastHistPos        { Index of newest data in history list        };
  HistoryValues      { Scaled history array to pass to data logger };
  HistImgTimeStamps  { For history use, 1D array, image of
                       TimeStamps                                  };
  HistImgData        { For history use, 1D array, image of
                      Data                                        };
  NeedValueUpdate = FALSE   { TRUE if the tag needs to recalculate
                              Value                               };
]

Main [
  If 1;
  [
    IfElse (PickValid(Addr == CurrValAddr, 0), Execute(
       { Current value data }
      RawValue = Data[0];
      RawTS    = PickValid(TimeStamps[0], CurrentTime(1));
      NeedValueUpdate = TRUE;
    );
    { Else } IfThen (PickValid(Addr == HistoryAddr, 0),
   { History data might have been Recv'd as single value or as an array }
   { Size of history array }
      IfElse(Valid(HistSizeRet = ArraySize(Data, 0)), Execute(
         { Data is an array }
        HistImgTimeStamps = TimeStamps;
        HistImgData       = Data;
      );
      { Else } Execute(
         { Data is a single value so copy to a single-value array }
        HistSizeRet          = 1;
        HistImgTimeStamps    = New(HistSizeRet);
        HistImgData          = New(HistSizeRet);
        HistImgTimeStamps[0] = TimeStamps;
        HistImgData[0]       = Data;
      ));

       { If the current tag value comes from history }
      IfThen (ValueFromHist,
         { Extract RawValue & RawTS from history list if no
           Current Value address defined }
         { Find the newest history TS }
        MaxHistTS = AMax(HistImgTimeStamps[0], HistSizeRet);
         { Only use it if greater than current value TS }
        IfThen (MaxHistTS > PickValid(TimeStamp, 0),
           { Where is this in the array ? }
          LastHistPos = Lookup(HistImgTimeStamps[0],
                               HistSizeRet, MaxHistTS);
           { Set our values to the newest history value }
          RawValue = HistImgData[LastHistPos];
           { Set the time as well }
          RawTS = HistImgTimeStamps[LastHistPos];
          NeedValueUpdate = TRUE;
        );
      );

       { Scale the data & log it }
      HistoryValues = New(HistSizeRet);
      I = 0;
      WhileLoop(I < HistSizeRet,
        HistoryValues[I] = Scale(HistImgData[I], UnscaledMin,
                                 UnscaledMax, ScaledMin, ScaledMax);
        I++;
      );

       { Log history values }
      \HistorianManager\WriteHistory(Root, HistImgTimeStamps,
                                     HistoryValues);
    ));

    IfThen(NeedValueUpdate && !Valid(ManualValue),
      UpdateValue(ValueFromHist);
{ The parameter tells UpdateValue to not log Value if it came
           from a history value; this has been logged already }
    );

    Return(0);
  ]
]

{ End of AnalogStatus\NewData }
>

NewData() example for reading digital values:

<
{========================= NewData ==================================}
{ Subroutine that receives and processes incoming channel data from  }
{ driver RefreshData in VTSDriver guarantees that TimeStamps is a    }
{ valid time stamp or an array of valid time stamps regardless of    }
{ the validity of Data                                               }
{====================================================================}
NewData
(
  Addr                 { Address we asked for (not used)             };
  TimeStamps           { Single value or 1D array of timestamps      };
  Data                 { Single value or 1D array of unscaled data
                         values                                      };
  Quality              { Single value or 1D array of Quality data    };
)

[
  HistSizeRet          { Size of history list returned               };
  MaxHistTS            { Highest TS in history list                  };
  LastHistPos          { Index of newest data in history list        };
  HistoryValues        { Scaled history array to pass to data logger };
  HistImgTimeStamps    { For history use, 1D array, image of
                         TimeStamps                                  };
  HistImgData          { For history use, 1D array, image of
                         Data                                        };
]

Main [

  If 1;
  [
    IfElse (PickValid(Addr == Bit0Address, 0), Execute(
       { If b0 address }
      RawValue0 = Data[0];
      RawTS     = PickValid(TimeStamps[0] - TimeZone(0), CurrentTime());
    );
    { Else - b1 address } IfElse(PickValid(Addr == b1ValAddr, 0), Execute(
      RawValue1 = Data[0];
      RawTS     = PickValid(TimeStamps[0] - TimeZone(0), CurrentTime());
    );
    { Else } IfThen (PickValid(Addr == HistoryAddr, 0), { History Address }
     { History data might have been Recvd as single value or as an array }
     { Size of history array }
      IfElse(Valid(HistSizeRet = ArraySize(Data, 0)), Execute(
         { Data is an array }
        HistImgTimeStamps = TimeStamps;
        HistImgData       = Data;
      );
      { Else } Execute(
         { Data is a single value so copy to a single-value array }
        HistSizeRet          = 1;
        HistImgTimeStamps    = New(HistSizeRet);
        HistImgData          = New(HistSizeRet);
        HistImgTimeStamps[0] = TimeStamps;
        HistImgData[0]       = Data;
      ));

       { If the current tag value comes from history }
      IfThen (ValueFromHist,
         { Extract RawValue & RawTS from history list if required }
         { Find the highest history TS }
        MaxHistTS = AMax(HistImgTimeStamps[0], HistSizeRet);
         { Only use it if greater than current value TS }
        IfThen (MaxHistTS - TimeZone(0) > PickValid(TimeStamp, 0),
           { Where is this in the array ? }
          LastHistPos = Lookup(HistImgTimeStamps[0], HistSizeRet,
                               MaxHistTS);
           { Set our value to the newest history value }
          RawValue0 = HistImgData[LastHistPos];
          RawTS     = HistImgTimeStamps[LastHistPos] - TimeZone(0);
        );
      );

       { Invert the data & log it  }
      HistoryValues = New(HistSizeRet);
       { Make a copy of the data array. }
      ArrayOp2(HistoryValues[0], HistImgData[0], HistSizeRet, 0);

       { Some data massage required... }
       { Force all data to 0/1 values.
          This first step actually returns the inverted data. }
      ArrayOp1(HistoryValues[0], HistSizeRet, 0, 12 {==});
      IfThen (!InvertInput,
         { Invert the data back to normal if not inverted }
        ArrayOp1(HistoryValues[0], HistSizeRet, 0, 12 {==});
      );

       { Log history values }
      \HistorianManager\WriteHistory(Root, HistImgTimeStamps,
                                     HistoryValues);
    )));

    Return(0);
  ]
]
{ End of NewData }
>


Write Data: The Set Module

Tags that write data to a driver tag must have a subroutine module named "Set". This module will perform 3 actions:

  • Check that the value to be written is valid. Do not write an invalid value.
  • Scale or invert the value for the PLC according to the tag's scaling parameters.
  • Ensure that the value is sent to all workstations in the network with a call to the RPCManager's Send function.

The return value from the Write() function will be the object value of the write module launched. When this value becomes invalid, the caller can assume that the write is complete. Note that, for a client machine on a network, this value will always be invalid.

The following example is taken from the Analog Control tag:

<
{======================== AnalogOutput\Set ==========================}
{ This subroutine writes a value to SitePoint. The parameter is the  }
{ value to write, which may be inverted before writing.              }
{                                                                    }
{====================================================================}
Set
(
  NewValue              { Value to write to the SitePoint            };
)

[
  WriteObj              { Object value of launched write             };
  WriteValue            { Actual value written                       };
]

Set [
  If 1;
  [
    NewValue = PickValid(Limit(NewValue, ScaledMin, ScaledMax), NewValue);
    SaveValue = Value = NewValue;

    {**** Don't bother to write to the PLC if the value is invalid *****}
    IfThen (Valid(Value),
      WriteValue = PickValid(Scale(NewValue, ScaledMin, ScaledMax,
                                   UnscaledMin, UnscaledMax), NewValue);
      WriteObj   = SitePoint\Driver\Write(Address, 1, &WriteValue);
    );

    {***** Send the value to everybody *****}
    \RPCManager\Send(SitePoint\Driver\RPCService { service },
                    \LocalGUID { GUID },\RPC_ACCEPT_FILTER {mode cut-off },
                    1 { server }, Invalid { machine }, 1 { clients },
                    0 { locally }, 1 { recursive }, "SetValue" { module },
                    "RPCManager" { scope  }, Root { queue data },
                    Invalid { InputSessionID },
                    { Parameters: } \LocalGUID, Concat("VTSDB\", Name),
                    "Value", Value);

    Return(WriteObj);
  ]
]
{ End of AnalogOutput\Set }
>


Log Tag Data

Tag data can be logged either by attaching a Logger tag, or by including code in the tag to write history. In both cases the tag must define a HistorianSchemaString, identifying the data to be logged.

Custom Logging for Tags

One reason to add logging code to your tag modules is to free the user from doing any configuration work to enable data logging. It also provides you with control over what is logged and when.

Three things are required in order for your tag to do its own logging:

HistorianName

HistorianName will hold the name of the Historian tag and must be declared as a parameter or variable in your tag. In general, it is better to use a parameter than a variable for HistorianName. This will provide greater flexibility in configuration. For example, in the parameters declaration of the Analog Status tag, HistorianName is declared as follows. Note that the System Historian is provided as the default value.

  HistorianName  <:TagField("SQL_VARCHAR(255)" ):> = #SYSTEM_HISTORIAN
                                     { Historian Tag name               };

HistorianSchemaString

This variable within your tag defines what information to write for each entry in the log and how to format that information. In most cases there should be four fields, as described in the following notes. Each field within the schema is separated from the next by a pipe character (vertical bar: |).

The first two fields must always specify the primary time stamp and the generation timestamp. Timestamp is usually provided by the PLC or data source and GenTimeStamp is automatically generated by the Historian. Timestamp should be stored as type TSTAMP (data and time timestamp). GenTimeStamp should be stored as UI4, a four-byte integer suitable for UTC values.

The third field is the tag data to be logged. "Value" is recommended in nearly all cases. The number (as in UI4 or R8) is the data type and the number of bytes required to store the data.

The fourth field, Value!, is used to log tag attribute data. Refer to Table Structure and Notes

While this may take any of the forms described in the following table, only three forms are used for most VTScada tags:

Analog values:

   { Historian schema }
  Constant HistorianSchemaString = "Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-R8|Value!-UI4";

Digital values:

   { Historian schema }
  Constant HistorianSchemaString = "Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-UI1|Value!-UI4";

String values:

   { Historian schema }
  Constant HistorianSchemaString = "Timestamp-TSTAMP-T|GenTimestamp-UI4-A|Value-STR|Value!-UI4";

The type is defined by a short text string:

TSTAMP
I | Signed integer.
UI Unsigned integer.
UI4 is typically used for UTC timestamps.
R | Real number
STR | String of bytes
BYTES | Synonym for STR
BOOL | Boolean value

Any field that you wish to hide from the HDV must be marked with an exclamation mark, such as Value!. Although any field marked with a ! will be hidden from the HDV, the HDV treats the Value! field specifically as a value attributes field. Other fields with ! will be hidden entirely.

WriteHistory

You must call \HistorianManager\WriteHistory(Root) each time you want to write log data. (WriteHistory)

\HistorianManager\WriteHistory(Root, TimeStamp, Value);

The Value parameter must be an array of values (one for Value and one for Value!) rather than a single value.

The call to write to the historian should be placed such that it is called whenever the value changes sufficiently to merit a new record (a deadband parameter is commonly used to avoid logging of very small changes). The call may also be placed in the tag's Refresh module (or a submodule called from Refresh) for the case where the HistorianName parameter may change, to log invalid to the old Historian and the current value to the new one.

If your tag supports the retrieval and logging of historical data that has been stored on the PLC, you will need a control structure to loop through the arrays. Typically, this is handled in a separate state.

You may choose to record any calculated values you like, and may impose conditions on whether the write occurs with each refresh. For example, the Analog Status tag will not perform a write until the tag's value has changed from the previously written value by at least a threshold amount (controlled by the parameter, Deadband, if set).

  IfThen(PickValid(Abs(Value - LastLoggedValue) >= Threshold, 1),
      \HistorianManager\WriteHistory(Root, TimeStamp, Value);
      LastLoggedValue = Value;
  );

Note that any tag with an HistorianName parameter or variable will be added to both the "Loggers" and the "Trenders" tag groups, automatically.

Attach a Logger to a custom tag

In order to be used as the data source for a Logger tag, a tag must be a member of the Trenders group and must expose one or more variables by defining an HistorianSchemaString.

The HistorianSchemaString is similar to that just described for built-in logging except that the name of the loggable fields must match the name of the loggable variables. In addition, your tag needs to add a Value! variable programmatically, using the function AddVariable(). It must also set Value! using Variable() in the same block of script code that sets Value.

It is also common practice to include a Logger tab in a tag's configuration dialog.

To do this, include the variable "LogContributors" as a plugin in your tag definition module.

[ (PLUGINS)
    LogContributors       { This is the "handle" used by the VTS code
                             to maintain a list of the logger contributors};

And, add the following to your tag's configuration panel code:

Variable declarations:

  LogContribs             { List of log contributors                };
  NumLogs                 { Number of log contributors              };

Logger panel:

Logger [
  If Current != x Switch;

  {***** Logger contributor list *****}
  GUITransform(80, 203, 420, 96,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PContributor("LogContributors" { holder },
               \Root,
               Parms[\#ContributionType] { contrib type },
               "LogPoint" { point type },
               \GetPhrase("LoggerContribLabel"), 1 { & 2 - ID },
               NumLogs ? 1 : 0 { no add if already 1 }));

  {***** Keep track of the number of log contributors *****}
  LogContribs = Scope(\Root, "LogContributors");
  NumLogs     = PickValid(ArraySize(*LogContribs, 1), 0);
]

Prior to the release of VTS 10, logging was done using the LogManager module. This is now obsolete, having been replaced by the HistorianManager. Any references to LogManager or Logger in tags from legacy applications must be updated to use the HistorianManager API instead.


Add Alarms to Custom Tags

The VTScada Alarm tag can monitor the value of any other tag that is a member of the group Numerics and that has a Value variable. Provided that your custom tag has these two features, it can be used to trigger an alarm.

You must ensure that when the application starts, your tag waits for the VTScada AlarmManager to start. This is commonly done in the tag's initialization state, along with ensuring that the expression manager has started: (Relevant code in bold.)

CustomTypeInit [
  If \AlarmManager\Started && \ExpressionManager\Started CustomTypeMain;
  [
    CriticalSection(
      Root = Self
      Refresh();
    );
  ]
]

No additional code is necessary, however you may choose to add two more features:

  • You may choose to make your custom tag aware of the Alarm tags that use it as a trigger. See: Alarm Containers.
  • You may choose to provide built-in alarm configuration for your tag. See:Build Alarms Into a Tag.

Reasons for doing so include:

  • Custom widgets for your tag may need to display the current alarm state.
  • Your tag may be a contributor to another tag and should therefore pass its alarm state to that owner.
  • You may choose to display a list of attached alarm tags in your custom tag's configuration panel.


Alarm Containers

In order for attached Alarm tags to contribute their values and alarm states to your custom tag, you must provide the variables to which they can connect.

ContributorAdded and ContributorDeleted

Declare "ContributorAdded" and "ContributorDeleted" as plugins:

  [ (PLUGINS);
    Shared ContributorAdded   = "ContributorAdded";
    Shared ContributorDeleted = "ContributorDeleted";
  ...

Required Variables

Declare all of the following variables:

  { List of variables handling points contributing to this one }
AlarmActive       { This is an array of alarm priorities for all
                    active alarm contributors.  Any alarm
                    contributors which are not active will set
                    their element to invalid. };
AlarmUnacked      { This is an array of alarm priorities for all
                    unacknowledged alarm contributors.  Any
                    acknowledged alarm will set its element to
                    invalid.  This array is a 1 to 1
                    correspondence to the AlarmActive array. };
AlarmContributors  { This is the "handle" used by the VTScada code
                    to maintain a list of the alarm contributors };
AlmSetpointPtrs   { This is an array of Pointers to the setpoints
                    of each of the alarm contributors };
AlmPriorityPtrs   { This is an array of Pointers to the
                    Priorities of each of the alarm contributors };

Configuration Panel, Alarm Tab

No additional variables are needed in the configuration module. The state where alarm contributors are shown and added will look like the following:

Alarm [
  If Current != X Switch;

  {***** Alarm contributor list *****}
  GUITransform(80, 250, 420, 50,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PContributor("AlarmContributors" { holder },
                 \Root,
                 Parms[\#ContributionType] { contrib type },
                "AlarmPoint" { point type },
                 \GetPhrase("AlarmContribLabel"), 1 { & 2 - ID }));
]


Build Alarms Into a Tag

To add one or more built-in alarms to a custom tag, you will need the following parts:

  • Configuration parameters for storing alarm properties. Your tag's configuration panel should include a tab for the alarm properties.
  • Local variables and constants for handling your alarms.
  • A set of statements in the tag's Refresh module to commission the alarm, setting or updating parameters as needed.
    In the event that the tag is being deleted, decommission should be called.
  • A call to \AlarmManager\EvaluateAlarm() to reevaluate the alarm's state with the tag's current value each time that value changes.

Prior to VTScada version 11.2, there was a requirement that separate submodules be created for each alarm if the tag included more than one. This is no longer the case. The GetAlarmObjVal module is now obsolete, but may be maintained for backward-compatibility.

Configuration Parameters and Variables

Alarm records have the configuration fields shown in the following table. Not all need to be set, so select those that are relevant to your tag and application. For example, trips should not be used with an analog tag. Deadbands are not used with digital tags.

At a minimum for a properly functioning alarm, you will need Name, Priority, Function, and Setpoint.
FriendlyName, Area, Description and Disable may not be required, but are highly recommended, and are usually set using properties of the tag.

ConfigurationStruct { All Boolean flags default to FALSE }
Name

Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).

FriendlyName | Display name of the alarm's source. This is only needed for alarms that are not associated with a tag, such as service alarms. Tag alarms will always show the tag's Name as the display name.
Area | Area
Description | Description. See also: NoLegacyAlarmDesc
Priority | Priority. Must be valid to be commissioned. Must be an integer corresponding to the Alarm Priority tag values. A priority of 0 will be treated as an event and will not go on either the Active or Current lists.
Reserved
Disable | TRUE to disable the alarm.
DisableParmName | Name of the tag's disable parameter. Allows you to get the operator name who made the configuration change.
OnDelay | Seconds to delay before activating.
OffDelay | Seconds to delay before clearing.
RearmDelay | Seconds to delay before rearming after acknowledgment.
Setpoint | Setpoint of alarm evaluation. The value is compared against the setpoint.
ValueLabels | Array of labels to display instead of Value or Setpoint. Rarely used by tags other than digitals.
Units | Phrase Key of the setpoint units.
Function | Enumerated function for alarm evaluation. See: Alarm Manager Function Constants
AlarmType | String identifying the type of alarm. Used for display purposes only, in accordance with the ISA18.2 standard. Examples include "Low", "High", "Test".
Trip | TRUE if alarm only becomes unacked not active.
NormalTrip | TRUE if alarm becomes unacked when it clears.
OffNormal | TRUE if alarm only becomes active not unacked.
Deadband | Setpoint deadband.
PopupEnable | TRUE to enable popup display of active alarm.
SoundFile | Filename relative to app path of custom sound.
Custom | Number/String/Array/Dictionary/Structure containing custom data. This information is not shown anywhere on the AlarmPage by default, but could be displayed using a custom column.
AdHoc | TRUE if alarm is ad hoc.
ReactivateOnValueChange | If TRUE, the alarm will reactivate whenever the reported value changes.
DescPhraseID | PhraseID or a ParmPhrase structure to translate the description to current language.
NormalAck | TRUE to auto-ack the alarm when it clears.
Hook

The name of a module you supply, which will be called whenever any alarm event occurs for the given alarm, including events such as active / normal / acknowledge / shelve / disable / commission / etc.

VTScada will look for the callback module starting in the AlarmObject that is provided in the call to Commission(), and will search upwards until it reaches Code level. This gives you flexibility to specify your callback module in your custom alarm tag, or in a custom ancestor tag, or in the application (AppRoot).

The callback module must take a TransactionInfo structure as its only parameter. It is expected to return TRUE or Invalid to allow the transaction to be logged, or FALSE to prevent it.

An example, showing how to configure these as tag properties:

Setpoint  <:TagField("SQL_DOUBLE", "Set Point"):> = 0
         { State or setpoint that triggers the alarm };
Function  <:TagField("SQL_VARCHAR(255)", "Function Code"):>
         { Text string defines the  comparison between value and setpoint };
Priority  <:TagField("SQL_DOUBLE", "Priority")   :>
         { Numeric Priority of this alarm };
Disable   <:TagField("SQL_LONGVARCHAR", "Disable"):> = FALSE
         { TRUE to Disable the alarm };

If your alarm is to be used only for low levels or high levels, you can set the Function field as a constant, otherwise, you will need to create a configuration parameter for it and provide a selection in the user interface. See: Alarm Manager Function Constants.

If creating more than one alarm, create a set of properties for each. For example, SetpointLo and SetpointHi.

As with other tag parameters, a constant should be defined for each alarm parameter. For example, if the parameter constant before Setpoint was 7, then:

Constant #Setpoint = 8;
Constant #Function = 9;

... and so on.

An alarm configuration structure will be required to commission your alarm(s). Declare each as a protected variable:

PROTECTED AlarmCfg     { Structure of alarm configuration parameters };

Your tag may also need variables to hold any alarm status information that you care to examine during the normal running of the tag and any configuration fields that are to be set but are not being exposed as user-configurable tag properties. The AlarmStatus structure (any name may be used) is typically set immediately after the alarm is commissioned. An example is provided later in this topic.

{ Alarm variables }
PROTECTED AlarmStatus  { Structure of alarm status information. };
{ ... other variables as required ... }

If the tag has a built-in alarm, that fact should be reflected as an icon in the Tag Browser.

To achieve this, all that is required is to add the following constant declaration. The Tag Browser will take care of the rest.

Constant BuiltInAlarm = TRUE { Flag - TRUE if this tag has a built in alarm  };

Tag Initialization

Your module should ensure that the Alarm Manager has started before attempting to commission itself. Because it is also typical for a tag to ensure that the Expression Manager has started, that is also shown in the following example.

MyTagInit [
  If \AlarmManager\Started && \ExpressionManager\Started MyTagMain;
  [
    CriticalSection(
      Root = Self();
      Refresh();
    );
  ]
]

Main State - Handle changes to the Disable parameter

Under the ISA18.2 standard, it is recommended that you provide a way for the tag to be disabled and re-enabled dynamically. This can be done with the tag's Common module (right-click menu), and by allowing the Disable parameter to be configured via a constant, expression or tag (i.e. via a PTypeToggle in the configuration panel).

Changes to this parameter outside the properties dialog are handled in your tag's main state. The configuration object must be updated and the Alarm Manager's Commission function called.

AlarmDisable = PickValid(Cast(ValueType(Disable) == \#VTypeObject
                              ? Disable\Value
                              : (Valid(Scope(Root, Disable)\Name)
                                 ? Scope(Root, Disable)\Value
                                 : Disable),
                              \#VTypeStatus),
                         AlarmDisable,
                         FALSE);
{ Enable/Disable }
If Watch(1, AlarmDisable);
[
  AlarmCfg = \AlarmManager\GetAlarmConfiguration(Root\UniqueID);
  AlarmCfg\Disable = AlarmDisable;
  \AlarmManager\Commission(Root, AlarmCfg, Value);
]

Note: You might prefer to set the 5th parameter of Commission to TRUE for these types of modification to the alarm so that the change is not added to the history list.

Refresh Submodule: Configure, Commission and Update

Alarm parameters are handled much like others in the refresh module. (Note: you are advised to use a PTypeToggle in your tag's configuration panel for the disable parameter so that it can be tied to a tag or expression. Other parameters may be configured as you see fit. The following example reflects this detail.)

\ExpressionManager\SafeRefresh(&Disable,   Parms[#Disable]);
AlarmRearmEnable = PickValid(Cast(AlarmRearmEnable, \#VTypeStatus), GetDefaultValue(&AlarmRearmEnable));

The Refresh module must call the Commission function of the Alarm Manager, handing it all of the properties you are configuring in your alarm.

If the tag contains only one alarm, then the name will be the same as the tag's unique ID value. If there are multiple alarms within the tag, then each will be the UniqueID concatenated with the alarm separator string (defaulting to :#:) followed by a digit starting with 0. Thus, when assigning the alarm name for a single alarm, the code will be:

AlarmCfg\Name            = Root\UniqueID;

When assigning the alarm name for the first of several alarms within a tag, the code will become:

AlarmLoCfg\Name = Concat(Root\UniqueID,
                         PickValid(\AlarmSeparatorString, ":#:"), "0");

Noting that the digit must be incremented for each subsequent alarm.

The name will be used several times, therefore it makes sense to store it in a variable such as "AlarmName" or "AlarmLoName".

The following example shows slightly more than a minimal configuration. Your code will likely set additional properties in the configuration structure.

IfElse(Valid(Name), Execute(
  AlarmName               = Root\UniqueID;
  AlarmCfg                 = \AlarmManager\GetAlarmConfiguration(AlarmName);
  AlarmCfg.Name            = AlarmName;
  AlarmCfg.FriendlyName    = Name      { The tag's short name };
  AlarmCfg.Area            = Area      { The tag's area };
  AlarmCfg.DescPhraseID    = DescPhrase { Variable containing a phase key for the description};
  AlarmCfg.Priority        = Priority;
  AlarmCfg.Function        = \AlarmManager\ALM_FUNC_LESS_THAN; { a low alarm, no user-selection }
  AlarmCfg.Setpoint        = PickValid(Cast(Setpoint, \#VTypeDouble), AlarmCfg\Setpoint);
  \AlarmManager.Commission(Root, AlarmCfg, Value);
  { ... repeat for more alarms ... }
);
{ Else, the tag is being deleted... }
  IfThen(Valid(Parms[#Name]),
    \AlarmManager.Decommission(AlarmName);
  );
);

If your tag needs to know its current alarm state, you should follow this by obtaining a reference to your alarm's entry in the master database. Typically, this is required only for widgets that can indicate that state. The reference to the database entry will allow quick access the alarm's current state without having to make function calls.

AlarmStatus = \AlarmManager\GetAlarmStatus(Root\UniqueID);

Evaluate the Alarm

The preceding should result in a commissioned alarm record when you compile your tag and generate an instance of it in your running application, setting priority to an integer. But, that is not enough to trip or activate an alarm event. You must also call the Alarm Manager's EvaluateAlarm function whenever the value of your tag changes so that the new value can be compared to the setpoint using the assigned comparison function.

If your tag links to a driver and has a NewData submodule, then place the following code there. Otherwise, it might go into the main state, if that is where new values are being calculated. Note that EvaluateAlarm cannot be called in Steady State.

If Watch(1, Value);
[
  \AlarmManager\EvaluateAlarm(Root\UniqueID, Value);

If the time is being collected from remote equipment with the value, then you should include that in the call as a UTC timestamp:

\AlarmManager\EvaluateAlarm(Root\UniqueID, Value, TimeOfValue);


Alarm Tab Notes

If you intend to allow developers to set the comparison function used when triggering the alarm (>, =, <=, etc) then you should create a dictionary of the function codes. Declare it as a shared variable in the tag module:

SHARED FunctionCodes        { Function code strings                    };

Then populate the dictionary in the Init state, again in the tag module:

MyTagInit [

  If \AlarmManager\Started && \ExpressionManager\Started MyTagMain;
  [
    { If (and only if ! ) you are allowing the developer to choose
      the comparison function, create list of function codes }
    IfThen(!Valid(FunctionCodes),
      FunctionCodes = Dictionary();
      FunctionCodes["<"]    = \AlarmManager\ALM_FUNC_LESS_THAN;
      FunctionCodes["<="]   = \AlarmManager\ALM_FUNC_LESS_EQUAL;
      FunctionCodes[">="]   = \AlarmManager\ALM_FUNC_GREATER_EQUAL;
      FunctionCodes[">"]    = \AlarmManager\ALM_FUNC_GREATER_THAN;
      FunctionCodes["="]    = \AlarmManager\ALM_FUNC_EQUAL;
      FunctionCodes["=="]   = \AlarmManager\ALM_FUNC_EQUAL;
      FunctionCodes["!="]   = \AlarmManager\ALM_FUNC_NOT_EQUAL;
      FunctionCodes["<>"]   = \AlarmManager\ALM_FUNC_NOT_EQUAL;
      FunctionCodes["&"]    = \AlarmManager\ALM_FUNC_AND_WITH;
      FunctionCodes["&&"]   = \AlarmManager\ALM_FUNC_AND_WITH;
      FunctionCodes["|"]    = \AlarmManager\ALM_FUNC_OR_WITH;
      FunctionCodes["||"]   = \AlarmManager\ALM_FUNC_OR_WITH;
      FunctionCodes["^"]    = \AlarmManager\ALM_FUNC_XOR_WITH;
      FunctionCodes["NAND"] = \AlarmManager\ALM_FUNC_NOT_AND_WITH;
      FunctionCodes["NOR"]  = \AlarmManager\ALM_FUNC_NOT_OR_WITH;
    );

    CriticalSection(
      Root = Self();
      Refresh();
    );
    Started = 1;
  ]
]

In the module for the configuration panel, create the following variables:

FindFunction   Module "FindFunc.WEB"  { Finds function in FuncList        };
FuncList                    { List of valid functions                     };
FuncIndex                   { Index into the FuncList array               };
FuncValues                  { Values of the function descriptions         };
FuncType                    { The long text string version of Function    };

Then in the panel's Init state, initialize the arrays:

Init [
  If 1 Switch;
  [
  {***** Set up the function list *****}
    FuncList     = New(12);
    FuncList[0]  = \NoFunctionLabel;
    FuncList[1]  = Concat(\GetPhrase("LessThanLabel"),         " <");
    FuncList[2]  = Concat(\GetPhrase("LessThanEqualLabel"),    " <=");
    FuncList[3]  = Concat(\GetPhrase("GreaterThanLabel"),      " >");
    FuncList[4]  = Concat(\GetPhrase("GreaterThanEqualLabel"), " >=");
    FuncList[5]  = Concat(\GetPhrase("EqualToLabel"), " = ",  \GetPhrase("OrLabel"), " ==");
    FuncList[6]  = Concat(\GetPhrase("NotEqualToLabel"), " != ", \GetPhrase("OrLabel"), " <>");
    FuncList[7]  = Concat(\GetPhrase("ANDedWithLabel"),  " & ",  \GetPhrase("OrLabel"), " &&");
    FuncList[8]  = Concat(\GetPhrase("ORedWithLabel"),   " | ",  \GetPhrase("OrLabel"), " ||");
    FuncList[9]  = Concat(\GetPhrase("XORedWithLabel"),        " ^");
    FuncList[10] = Concat(\GetPhrase("NotANDedWithLabel"),     " ! ( && )");
    FuncList[11] = Concat(\GetPhrase("NotORedWithLabel"),      " ! ( || )");
    FuncValues      = New(12);
    FuncValues[0]   = "";
    FuncValues[1]   = "<";
    FuncValues[2]   = "<=";
    FuncValues[3]   = ">";
    FuncValues[4]   = ">=";
    FuncValues[5]   = "=";
    FuncValues[6]   = "!=";
    FuncValues[7]   = "&";
    FuncValues[8]   = "|";
    FuncValues[9]   = "^";
    FuncValues[10]  = "NAnd";
    FuncValues[11]  = "NOr";
    {***** Find the current function type *****}
    FuncType = FindFunction(Parms[\#Function]);
    FuncIndex = LookUp(FuncList[0], 12, FuncType);
    { ... }

Finally, in the state for the tab where the alarm function is to be selected, display the list:

{***** Function *****}
GUITransform(30, 155, 470, 110,
             1, 1, 1, 1, 1,
             0, 0, 1, 0,
             0, 0, 0,
             \DialogLibrary.PDropList(\#Function, \FunctionLabel,
                                      FuncList, 0, FuncIndex
                                   { Labels, CanEdit, Index              },
                                      HasPriv ? 11 : 0, 0
                                   { FocusID, No Trigger                 },
                                      FuncIndex, 1, 0, 1
                                   { Init, DrawBevel, VertAlign, AlignTitle  },
                                      FuncValues
                                   { Return Values    }));

Related information:

Add Alarms to Custom Tags

Alarm Manager Function Constants


Security for Output Tags

All tags that allow operators to write to a device must provide the option of being secured by a custom privilege.

This can be implemented as follows:

Create a parameter named SecurityBit:

SecurityBit    <:TagField("SQL_VARCHAR(255)", "Security Bit",   10):>

In the refresh module, ensure that this contains the correct data type:

SecurityBit = Cast(SecurityBit, 1 { Short });

And in the configuration panel, use the PSecBit function to allow the user to select from the existing custom privileges.

{***** Security bit *****}
GUITransform(30, 180 { btm at 125 }, 470, 80,
      1, 1, 1, 1, 1            { No scaling                     },
      0, 0, 1, 0               { No movement; visible; reserved },
      0, 0, 0                  { Not selectable                 },
      \DialogLibrary.PSecBit(\#SecurityBit, \GetPhrase("SecurityBitLabel"), 1 { ID }));

Each output widget will test the SecurityBit of the attached tag against the logged-in operator's privileges before performing a write.

If you have created your own output widgets for your custom tags, you must include code to check the security privilege. For example:

   IfThen ( !Editing && \OkToWrite(\SecurityBit, 1),

The value of \SecurityBit comes from the tag instance attached to the widget. The call to \OkToWrite() compares the signed in user's assigned security privileges with the SecurityBit and returns TRUE or FALSE. It is then the job of the code within your widget to allow the write to proceed or not.


Containers, Contributors and Site Tags

A "container" is a tag that holds a collection of other tags known as "contributors". A tag may be a container for multiple contributor types, and a tag may also contribute to several different containers.

Site tags are a type of container. (Not all containers are site tags, but all site tags are containers.) A site tag is one that can be included in the Sites List page, such as Context tags, Polling drivers and Station tags. In order to classify a container tag as a site, the groups declaration must have at least the following line.

[ (GROUPS)
Shared Container { We are a container tag };

A tag that is a container may also be a contributor at the same time (a container tag may accept values from its contributors, while in turn contributing its value to another container).

For example, each station in a given area might contribute its value to a container that calculates the value for that area, and each area container might contribute its value to a container that calculates the value for the province or region. These regional containers can also contribute their values to a container that calculates a national value.

The container uses a handle variable that lists the contributors for a given tag. There may be several handle variables defined, one for each kind of contributor possible. There is no naming restriction on handle variables, but both the contributor and container modules must know the name. A handle variable is used by three VTScada functions:

  • AddContributor
  • DeleteContributor
  • GetContributors

The following descriptions for container and contributor configuration show the minimum steps required to establish the relationship between the tags.

Container Configuration

For a container tag to know that it has contributors, it must declare the following modules in its PLUGINS group:

  [ (PLUGINS)
    Shared ContributorAdded   = "ContributorAdded";
    Shared ContributorDeleted = "ContributorDeleted";

The statement, Shared Container; is optional.

The container must also declare a variable that will hold all instances of each type of contributor tag. For example, an Analog Input may have the following contributors: a Logger tag, Script tags, and Alarm tags. These are declared as follows:

  AlarmContributors      { This is the "handle" used by the VTS code
                           to maintain a list of the alarm contributors};
  ScriptContributors     { This is the "handle" used by the VTS code
                           to maintain a list of the script contributors};
  LogContributors        { This is the "handle" used by the VTS code
                           to maintain a list of the logger contributors};

Contributor Configuration

Most code to configure a container-contributor relation between tags is located in the contributor. This is where the functions noted earlier will be used.

First, the contributor must include a parameter that is used to identify the tag to which it contributes. Using code from the VTScada Script tag as an example, this declaration will look like the following:

HookTag  <:TagField("SQL_VARCHAR(255)","Point to Attach", 3 ):> = "*Numeric"
          { Name of the point whose scope we will launch the script within.};

All tag parameters require an enumerating constant:

  Constant #Hooktag    = 3;

You must also declare two variables; one to hold the current value of the parameter and one to hold the previous value. This allows you to write code to take any necessary steps when the user changes the selected hook tag.

  Hook                   { Instance of HookTag                    };
  OldHook                { Previous value of Hook                 };

In the Main state, you must watch for changes to the hook tag:

CustomTagMain [
   { Hook can change after Refresh has been called }
  If Valid(Hook = Scope(Root, HookTag)) != Valid(OldHook) || Hook != OldHook;
  [
    CriticalSection(
      \DeleteContributor("ScriptContributors", Invalid, Invalid, OldHook,
                          Root, Invalid);
      \AddContributor("ScriptContributors", Invalid, Invalid, Hook,
                       Root, Invalid, Invalid, Invalid);
      OldHook = Hook;
    );
  ]

As noted in the previous code, it is the Refresh state that watches for changes to the hook tag:

Refresh [
  If 1;
  [
    IfThen (PickValid(Scope(Root, HookTag) != OldHook, TRUE),
      \DeleteContributor("ScriptContributors", Invalid, Invalid,
                          OldHook, Root, Invalid);
      \AddContributor("ScriptContributors", Invalid, Invalid,
                       Scope(Root, HookTag), Root, Invalid, Invalid, Invalid);
      OldHook = Scope(Root, HookTag);
    );
    Return(0);
  ]


Custom Filtering of the Sites List and Map

The Sites page shows a list of all configured site pages in your application. For each of these, sub-sites and I/O are also listed. If you have a mixture of sub-site types and want to control which ones are displayed, or if you want to exclude the I/O, there are some ways in which you can filter the contents of the list.

The list is built automatically. Developers can filter this list for their Context-tag based sites by editing the code for that tag type to add the parameter, CustomSiteListFilterType and set its value to the name of the type or type-group that they want to filter for.

New types derived from Context tags do not count against your VTScada license limit until you add custom code to them, after which every instance of that type will be counted.

If you are writing a site tag from scratch, you can build-in filters for the sites list and for the maps by adding subroutine modules to be used as call-backs.

CustomSiteListGetSubTags

This must return an array of tag names. If this module exists in your custom tag, then GetSessionContainerTags will call it instead of GetTagList. An example of such a module is provided:

<
{================== CustomSiteListGetSubTags =================}
{=============================================================}
CustomSiteListGetSubTags
[
  Tags;
]
CustomSiteListGetSubTags [
  If 1;
  [
    Tags = \GetTagList(Root\Name, Invalid, Invalid, Invalid, "MultiSmart");
    Return(Tags);
  ]
]
>

After adding this code, you may want to consider setting your tag's SiteListDisplay parameter. If your subroutine returns a list of I/O, you may want to set the SiteListDisplay to 1 to treat it as a site. if it returns a list of sub-sites or a mixture of sub-sites and I/O, you may want to set SiteListDisplay to 2 to treat it as a folder. If the SiteListDisplay value is not set explicitly, the default behavior may be other than what you prefer.

CustomSiteMapGetSubTags

This module will be similar in structure to CustomSiteListGetSubTags. Two parameters can be provided:

ShowAll is an optional Boolean.

NavigationPath is an optional array of the tag names that were followed (clicked upon by the operator) to arrive at the list being viewed. This parameter can be used if you want to change the filter based on the path taken through the site structure.

<
{================== CustomSiteMapGetSubTags ==================}
{=============================================================}
CustomSiteMapGetSubTags
(
  ShowAll;
  NavigationPath;
)
Main[
  { Your filtering code, returning an array of tag names. }
]
>


Make a Custom Tag Visible to OPC Clients

When running VTScada as an OPC server, the values of standard tags are available to clients. This will not be true of your custom tags unless you add modules that specify what will be made available.

The following modules may be added. Examples of these follow.

OPCGetTagAttributes | This tells the VTScada OPC server whether this tag can be read from or written to, as well as the data type it is to return. Required for the tag to be visible to an OPC client.
OPCGetTagProperties | Optional. Returns a dictionary of all the items that will be available from the tag.
OPCReadTagValue | Must be included if the tag is to be readable.
OPCWriteTagValue | Only required if the tag is writeable.

For any OPC constants that are not defined locally, you should be able to add a backslash to obtain it from VTScada.

OPCServerEnabled

This is a public variable that will be set to TRUE when there are OPC Servers to which a tag should be publishing. It will be either Invalid or FALSE if no server is present.

UpdateOPCData

UpdateOPCData() is a VTScada module. As with the constants, if it is not in the immediate scope, you can add the backslash operator.

Example:

    IfThen(Valid(\OPCServerHandle),
           \UpdateOPCData(Self(), \OPC_PROP_RAW_VALUE, RawValue);
    );
    IfThen(True(\Code.OPCServerEnabled),
           \UpdateOPCData(Self(), \OPC_PROP_RAW_VALUE, RawValue);
    );

This will tell the server code to update the RawValue attribute, since it has changed. OPCServerEnabled is set higher up the scope tree when the OPC server is enabled - this prevents that code from being called if it is not present.

Make the tag's value available to OPC clients. If included, your tag's main state should call \UpdateOPCData(Self()); whenever the value changes.

<
{======================== OPCReadTagValue =============================}
{ Subroutine that returns the current value, quality, and timestamp of }
{ this tag for OPC purposes.                                           }
{======================================================================}
OPCReadTagValue
(
  pValue          { (Output) The value of the tag, must be a Valid value };
  pQuality        { (Output) The quality of the value                    };
  pTimestamp      { (Output) The timestamp of the value                  };
  pTimestampIsUTC { (Output) Indicates whether the timestamp is in UTC   };
)

Main [
  If 1;
  [
    *pValue     = PickValid(Value, Valid(Cast(Value, \#VTypeText)) ? "" : 0);
    *pTimestamp = Timestamp - TimeZone(0);
    *pQuality = Operational
                ? (Operable && Valid(ManValue))
                  ? \OPC_QUALITY_GOOD_LOCAL_OVERRIDE
                  : Valid(Value)
                    ? \OPC_QUALITY_GOOD
                    : \OPC_QUALITY_BAD
                : \OPC_QUALITY_UNCERTAIN;
    Return(Invalid);
  ]
]

{ End of OPCReadTagValue }
>

This will be called when an OPC client is requesting the values. The parameter, pValue, is what you want it to show, normally gained from Value

The following module example creates a dictionary of properties that will be available to OPC clients. Remove any properties that you do not intent to make available. For example, if you don’t need OPC_PROP_DESCRIPTION declared then remove the line within this module. A complete list of OPC values can be found in Properties of OPC Classic Item Tags.

<
{======================== OPCGetTagProperties ========================}
{ Subroutine that returns a dictionary of OPC properties and values   }
{ supported by this tag. The dictionary is keyed by property ID.      }
{=====================================================================}
OPCGetTagProperties
 [
  PropDict;
]
Main [
  If 1;
  [
    PropDict = Dictionary();
    PropDict[OPC_PROP_EU_UNITS]                = Units;
    PropDict[OPC_PROP_DESCRIPTION]             = Description;
    PropDict[OPC_PROP_HIGH_EU]                 = ScaledMax;
    PropDict[OPC_PROP_LOW_EU]                  = ScaledMin;
    PropDict[OPC_PROP_HIGH_INSTRUMENT]         = UnscaledMax;
    PropDict[OPC_PROP_LOW_INSTRUMENT]          = UnscaledMin;
    PropDict[OPC_PROP_TIMEZONE_MINUTE_OFFSET]  = TimeZone(0)/60;
    PropDict[OPC_PROP_AREA]                    = Area;
    PropDict[OPC_PROP_DEVICE_TAG]              = DeviceTag;
    PropDict[OPC_PROP_ADDRESS]                 = Address;
    PropDict[OPC_PROP_RAW_VALUE]               = RawValue;
    PropDict[OPC_PROP_LOW_ALARM]               = Cast(AlarmLo,3);
         { In case AlarmLo is a tag or expression }
    PropDict[OPC_PROP_HIGH_ALARM]              = Cast(AlarmHi,3);
         { In case AlarmHi is a tag or expression }
    Return(PropDict);
  ]
]

{ End of OPCGetTagProperties }
>

Example to define whether the tag can be read from or written to by the OPC client:

<
{======================= OPCGetTagAttributes ==========================}
{ Subroutine that returns the OPC attributes of this tag.              }
{======================================================================}
OPCGetTagAttributes
 (
  pAccessRights  { (Output) The read/writeability of the tag           };
  pDataType      { (Output) The COM datatype of the value of the tag   };
)

Main [
  If 1;
  [
    *pAccessRights = Output ? \OPC_ACCESS_READWRITEABLE : \OPC_ACCESS_READABLE;
    *pDataType = Valid(Value)
                 ? Valid(Cast(Value, \#VTypeText))
                   ? \VT_BSTR
                   : \VT_R8
                 : \VT_EMPTY;
    Return(Invalid);
  ]
]

{ End of OPCGetTagAttributes }
>

pAccessRights defines whether the tag's value can be read or written to according to the assignment of one of the following constants:

  CONSTANT OPC_ACCESS_READABLE               = 1;
CONSTANT OPC_ACCESS_WRITEABLE              = 2;
CONSTANT OPC_ACCESS_READWRITEABLE   = 3;

pDataType sets the data type of the tag to one of the following for compatibility with component object model standards:

 CONSTANT VT_EMPTY= 0;
 CONSTANT VT_NULL= 1;
 CONSTANT VT_I2= 2;
 CONSTANT VT_I4= 3;
 CONSTANT VT_R4= 4;
 CONSTANT VT_R8= 5;
 CONSTANT VT_CY= 6;
 CONSTANT VT_DATE= 7;
 CONSTANT VT_BSTR= 8;
 CONSTANT VT_BOOL= 11;
 CONSTANT VT_VARIANT= 12

If your tag will allow OPC Write access, you will need a module similar to the following example. Note that this example does not provide for any checking of the request - something may wish to add.

<
{=========================== OPCWriteTagValue =============================}
{ Subroutine called when an OPC client wants to write a value to this tag. }
{==========================================================================}
OPCWriteTagValue
 (
  NewValue      { (Input) The value to be written, must be a Valid value };
)

Main [
  If 1;
  [
    Set(NewValue);
    Return(0);
  ]
]

{ End of AnalogOutput\OPCWriteTagValue }
>

For a description of the Set() module, see: Write Data: The Set Module.


ValueSyncService

Use ValueSyncService sparingly, and only for rapidly changing values.

The role of the value synchronization service (i.e. ValueSyncService ) is to allow a tag to register a list of named variables to be kept in synch. The following VTScada tags use this service:

  • Totalizer
  • Counter
  • Selector Switch
  • Historian
  • History Statistics
  • Rate of Change

This service is meaningful only for tags. The service provided startup synchronization of all registered variables. It also provided synchronization on new tag creation while the application is running (online tag creation). In the case of online tags, the values are always synchronized with the primary server for the service. The service supports clients of clients.

Note the following tasks:

  • You must explicitly RPC (Remote Procedure Call) the value, unlike NetworkValues.
  • You must explicitly persist the value, again unlike NetworkValues.

There are two synchronization situations:

1) Start-up Synchronization:

When a Client comes online or re-syncs with a Server, it will get the Primary server’s version of the variables.

2) Online Tag Synchronization:

A new tag is created on a machine, and an EditLockoutManager update is performed. The convention for this is that all machines will sync from the primary server's values, regardless of who actually created the tag first. Thus, whatever happens to be the value of the variable when the tag comes alive on the primary server; that is what is synchronized.

API

\ValueSyncService\Register

Description: | Called by a tag to create a list of variables which are to be kept in sync.
Returns: | Nothing (sets PtrRegisterDone when complete)
Usage: | Script Only.
Format: | \ValueSyncService\Register(TagObj, PtrRegisterDone, TagVars)
Parameters: |
TagObj
Required. The object value of the tag.
PtrRegisterDone
Required. A pointer to a variable. Used to return the result of the operation. The value will be set to 1 to indicate that the variables have been synchronized.
TagVars
Required. An array of the variable names to be synchronized.

Example:

As used in the initialization state of the Selector Switch:

  If \ValueSyncService\Started WaitRegister;
  [
    Root = Self;
    { Register with the ValueSyncService - save processing by registering for the first instance only }
    IfThen(!Valid(SyncedVars),
      { SyncedVars is a SHARED array, we must be the first instance }
      SyncedVars    = New(2);
      SyncedVars[0] = "SaveValue";
      SyncedVars[1] = "RequestedValue";
    );
    \ValueSyncService\Register(Root, &RegisterDone, SyncedVars);

    { Set up initial values }
    Refresh();
    {… }
  ]

WaitRegister [
  If RegisterDone Main;
]


Programming Parent Tags

The following information describes an older technology. With rare exceptions, Parent-Child tag structures created using the Tag Browser should be used instead of programmed parent tags.

Parent tags are a user-created tag type that will generate a set of related tags (child tags) with each new instance. They are typically used in applications that have a series of devices such as generators or lift stations where each instance will use a similar port, driver, I/O tag set, etc.

The tag that represents the generator or lift station as a whole is referred to as the "parent tag", while the various dynamically-generated tags are referred to as the "child tags". The child tags are created by way of calls to the StartTag function. Their parameters do not exist within the tag properties database, except in the case where the developer subsequently overrides those properties.

Because the child tags are created automatically by each parent, it becomes a simple task for developers to add new lift stations or other objects to the application.

Parameterized pages can be created that accept an instance of a parent tag as the parameter, then automatically link all of the monitoring and control features within the page to the child tags. Parent tag structures are most useful when there is a clear pattern to the child tag parameters from one instance to the next. It should be possible to calculate or copy each child tag's parameters from its parent's configuration.

Child tags and their properties are not stored in the tag properties database. The exception to this rule is that overrides to properties are stored in the tag properties database. Parent tags and all of the child tags will be listed in the Tag Browser and their properties may be edited there.

Although child tags do not store their parameters in the tag properties database, they do count towards the tag limit as set by your VTScada license.

Overrides to child tag values will remain in effect and be distributed to all stations running the application. Overridden fields in the configuration panel will turn orange instead of green (subject to the application property, ParmOverrideColor). You can also right-click on a child tag's configuration panel field and select "Add Override" from the pop-up menu.

Right-clicking and selecting "Remove Override" is the only way to return to the property value defined in code - simply deleting the value will set it to an override value of Invalid, rather than removing the override.


Building Parent Tags

The structure of a parent tag is the same as any other custom tag (see Creating Custom Tag Types) with one exception: The parent tag contains a number of calls to StartTag, thereby creating child tags automatically with each new instance.

The parent tag's parameters should include all of the information that will be required by the various child tags. There must be some pattern to the child tag parameters from instance to the next for these structures to be useful. For example, if all of the child tags that perform I/O functions use addresses that can be calculated from a station number or a base address value, then the parent tag will require very little configuration. If each parameter of each child tag in each instance of the parent must be provided individually, then few benefits remain.

For parent tags with very complex configurations, you should consider creating a configuration wizard to help operators create each new instance. See The VTScada Wizard Engine. If the configuration is not overly complex, then a standard set of configuration panels should suffice.

The concepts of parent tag structure are illustrated in the following example. This shows the source code for a simple lift station with a port, a Modbus Compatible Device , a polling driver. I/O addressing in this example takes advantage of the Modbus virtual I/O feature.

{====================== Parent Tag Example =================}
{ An sample Parent tag that creates several child tags.     }
{===========================================================}
{ The parameters section of the module contains all of this }
{   tag's configuration parameters                          }
(
  Name         <:TagField("SQL_VARCHAR(64)",  "Name"     ):>
    { Name of this tag                              };
  Area         <:TagField("SQL_VARCHAR(255)", "Area"     ):>
    { Group which this device belongs to            };
  Description  <:TagField("SQL_VARCHAR(255)", "Description" ):>
    { Description of device                         };
  Station   <:TagField("SQL_VARCHAR(255)", "Station"   ):> = 1
    { Modbus address of the PLC                     };
  IOBaseAddr   <:TagField("SQL_VARCHAR(255)", "IOBaseAddr"  ):>
    { I/O addressing offset for this instance       };
  Port         <:TagField("SQL_VARCHAR(255)", "Port"        ):>
    { Port tag used to communicate with the device  };
  ScanInterval <:TagField("SQL_VARCHAR(255)", "ScanInterval" ):>
    { Polling interval                              };
)
{ The variables section of the module contains the standard  }
{   variables, constants and module declarations for a tag   }
[
  Root                  { Instance of this module            };
  Value(5)              { Value of this tag                  };
  Refresh      Module   { Standard module in all tags        };
  ConfigFolder Module   { Configuration folder               };
  Common       Module   { right-click menu and tool tip      };

  [(GRAPHICS)
    Shared Number;  { the only widget that will be available }
  ]
     { Parameter Constants }
  CONSTANT #Name          = 0;
  CONSTANT #Area          = 1;
  CONSTANT #Description   = 2;
  CONSTANT #Station       = 3;
  CONSTANT #IOBaseAddr    = 4;
  CONSTANT #Port          = 5;
  CONSTANT #ScanInterval  = 6;

]

{ The initialization state of all tags will set Root to self  }
{   and call the Refresh module                               }

Init [
  If 1 Main;
  [
    Root = Self;
    Refresh();
  ]
]

Main [
{ The value of the parent tag will be taken from the value   }
{  of the Polling Driver child-tag                           }
  Value = Variable("PollDriver\Value");
]

<
{========================== Refresh ========================}
{ This subroutine is called on startup and whenever the     }
{ tag's parameters change                                   }
{===========================================================}
Refresh
(
  Parm         { Array for parameters prior to their change };
)

Refresh [
  If 1;
  [
    { This section creates the instances of the child tags. Some      }
    { parameter values come directly from the parent (Area), some are }
    { set in code and some are built here, based on information from  }
    { the parent's parameters.                                    }
    { Since child tags are always named  ParentName\ChildName, there  }
    { is no need here to create a unique name here for each child     }
    { instance. The drivers, for example, will be Instance1\SiteDriver, }
    { Instance2\SiteDriver, etc.                                  }

    { Create Driver tag }
    \StartTag(Root,
              Valid(Root\Name)     { Conditional launch expression },
              "ModiconDriver"      { Tag type },
                { Name and value pairs }
              "Name",              "SiteDriver" ,
              "Area",              Area,  { The child takes its area from the parent }
              "Description",       Concat(\GetPhrase(Description), " ", \GetPhrase("DriverLabel")),
              "Station",           Station, { from the parent configuration }
              "Channel",           0,
              "PortTag",           Port,    { from the parent }
              "TimeLimit",         1,
              "Retries",           3,
              "Hold",              0,
              "KeyOffDelay",       0,
              "Options",           0,
              "TimeSquelch",       0.2,
              "RetryTime",         1,
              "Adapter",           -1,
              "TimeInc",           2,
              "MBPRetries",        2,
              "MBPDMPathCount",    8,
              "MBPPollRate",       0.025,
              "VPLCHoldingCoils",  9999,  { Virtual I/O is used for this example }
              "VPLCInputCoils",    9999,
              "VPLCInputRegs",     9999,
              "VPLCHoldingRegs",   9999,
              "HelpKey",           Invalid);
    { Create Polling Driver tag }
    \StartTag(Root,
              Valid(Root\Name) { Conditional launch expression },
              "PollDriver"     { Tag type              },
              "Name",          "SitePoller" { Parameter name & value pairs },
              "Area",          Area,
              "Description",   Concat(\GetPhrase(Description), " Poll Driver"),
              "DeviceTag",     Concat(Name",\SiteDriver"),
              "PollGroup",     "DEFAULT",
              "Sequence",      0,
              "Interval",      ScanInterval,
              "Offset",        0,
              "PollDisabled",  0,
              "HelpKey",       Invalid);
    { Create an Analog Status tag }
    \StartTag(Root,
              Valid(Root\Name)    { Conditional Launch expression },
              "AnalogStatus"      { Name of tag type },
              "Name",     "AS1",
              "Area",     Area,
              "Description",    "Analog Status child 1",
              "DeviceTag",    Concat(Name",\SitePoller"),
              "Address",    Cast(40000 + Cast(IOBaseAddr, 2), 4),
              "ScanRate",    1,
              "UnscaledMin",    0,
              "UnscaledMax",    4095,
              "ScaledMin",    0,
              "ScaledMax",    100,
              "Units",     "%",
              "AlarmLo",    Invalid,
              "AlarmHi",    Invalid,
              "PriorityLo",    Invalid,
              "PriorityHi",      Invalid,
              "InhibitLo",    Invalid,
              "InhibitHi",    Invalid,
              "AlarmSound",    Invalid,
              "ManualValue",    Invalid,
              "Threshold",    Invalid,
              "Questionable",    0,
              "Quality",    Invalid,
              "DisplayOrder",    Invalid,
              "HelpKey",    Invalid,
              "PopupLo",    Invalid,
              "PopupHi",    Invalid,
              "AlarmLoDeadband",  Invalid,
              "AlarmHiDeadband",  Invalid,
              "AlarmLoDelay",    Invalid,
              "AlarmHiDelay",    Invalid);
    { Create an Analog Control tag }
    \StartTag(Root,
              Valid(Root\Name) { Conditional Launch expression },
              "AnalogControl"  { Name of tag type },
              "Name",   "AC1",
              "Area",   Area,
              "Description",  "Analog Control child 1",
              "DeviceTag",  Concat(Name",\SitePoller"),
              "Address",  Cast(40000 + Cast(IOBaseAddr, 2), 4),
              "UnscaledMin",  0,
              "UnscaledMax",  4095,
              "ScaledMin",  0,
              "ScaledMax",  100,
              "Units",   "%",
              "SecurityBit",   Invalid,
              "DataSource",   Invalid,
              "Questionable",  0,
              "DisplayOrder",  Invalid,
              "HelpKey",  Invalid);
    { Create a Digital Status tag }
    \StartTag(Root,
              Valid(Root\Name) { Conditional Launch expression },
              "DigitalStatus"  { Name of tag type },
              "Name",        "DS1" { Name and value pairs },
              "Area",         Area,
              "Description",  "Digital Status child 1",
              "DeviceTag",    Concat(Name",\SitePoller"),
              "Bit0Address",  Concat(Cast(40100 + Cast(IOBaseAddr, 2), 4), "/0"),
              "Bit1Address",  Invalid,
              "ScanRate",     Invalid,
              "InvertInput",  0,
              "OffText",      "Off",
              "OnText",       "On",
              "AlarmState",   Invalid,
              "AlarmDelay",   Invalid,
              "TripOptions",  0,
              "Priority",     0,
              "Inhibit",      1,
              "AlarmSound",   Invalid,
              "ManualValue",  Invalid,
              "Questionable", 0,
              "Quality",      Invalid,
              "DisplayOrder", 1,
              "HelpKey",      Invalid,
              "PopUp",       0);
    { Create a Digital Control tag }
    \StartTag(Root,
              Valid(Root\Name)    { Conditional Launch expression },
              "DigitalControl"    { Name of tag type },
              "Name",             "DC1" { Name and value pairs },
              "Area",             Area,
              "Description",      "Digital Control child 1",
              "DeviceTag",        Concat(Name",\SitePoller"),
              "Address",          Concat(Cast(40100 + Cast(IOBaseAddr, 2), 4), "/0"),
              "InvertOutput",     0,
              "PulseDuration",    0,
              "FeedBackTag",      Invalid,
              "FeedBack1",        Invalid,
              "FeedBack0",        Invalid,
              "SecurityBit",      Invalid,
              "DataSourceTag",    Invalid,
              "InvertDataSource", 0,
              "Questionable",     0,
              "DisplayOrder",     Invalid,
              "HelpKey",          Invalid);
    Return(0);
  ]
]
{ End of Refresh }
>
 { As with all tags, the ConfigFolder module is called when the }
 { tag's  properties are displayed.                        }

<
{==================== ConfigFolder ===========================}
{ This is the shell of an editable ConfigFolder for a tag     }
{ where the ConfigFolder is created and maintained by the     }
{ ConfigFolder Wizard.                                   }
{ Manual editing of the code is allowed as long as the state  }
{ structure is maintained.                               }
{=============================================================}
ConfigFolder
(
  Parms              { Pointer to array of parameters              };
  Current            { Currently selected tab (starts at 0)        };
  PtrWaitClose       { Pointer to FLAG - TRUE when wait to close.
                         Caller must default to 0.            };
  OKPressed          { OKPressed from PropertiesDialog             };
)
[
  Constant #WIDTH = 500;
  [(1)
    IDTabLabel      = "ID";
    ConfigTabLabel  = "Config";
  ]
]
Switch [
  If Current == 0 ID;
  If Current == 1 Config;
]
ID [
  {**** If page changes, change states *****}|
  If Current != 0 Switch;
  {***** Name of the point *****}
  GUITransform(30, 90, 470, 45,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
              \DialogLibrary.PEditName());

  {***** Group (area) that the point belongs to *****}
  GUITransform(30, 200 { btm at 145 }, 470, 100,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PAreaSelect(1 {can edit}, 2 {ID}));
  {***** Description of the point *****}
  GUITransform(30, 200, 470, 155,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditField(2, \DescriptionLabel, 4 {text},
                                         3 {ID}));
]

Config [
    {**** If page changes, change states *****}
  If Current != 1 Switch;
    {***** Communications Port *****}
  GUITransform(30, 90, #Width - 30, 45,
               1, 1, 1, 1, 1,
               0, 0, 1, 0,
               0, 0, 0,
               \DialogLibrary.PSelectObject(#Port    { Parm          },
                                            "Ports"  { Point type    },
                                            "Communications Port" { Title },
                                            1        { Focus ID      },
                                            0        { List at top   },
                                            0        { Align top of bevel )));
    {***** Station Address *****}
  GUITransform(30, 145, #Width / 2 - 10, 100,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditField(#Station  { Parm Num            },
                                         "Station Address" { Title       },
                                         1              { Short          },
                                         2              { Focus ID       }));
    {***** I/O Base Address *****}
  GUITransform(30, 200, #Width / 2 - 10, 155,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditField(#IOBaseAddr  { Parm Num         },
                                         "I/O Base Address" { Title      },
                                         1              { Short          },
                                         2              { Focus ID       }));
    {***** Scan Interval *****}
  GUITransform(#Width / 2 + 10, 145, #Width - 30, 100,
               1, 1, 1, 1, 1            { No scaling                     },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditField(#ScanInterval { Parm Num        },
                                         "Scan Interval" { Title         },
                                         3              { Float          },
                                         3              { Focus ID       }));
]
{ End of ConfigFolder }
>

<
{========================= Common ==============================}
{ This module handles the common actions associated with all    }
{ drawing modules for this point. It will be called by all     }
{ external drawing modules.                                }
{===============================================================}
Common
(
  Left          { Area occupied by the drawing object         };
  Bottom;
  Right;
  Top;
)

Common [
  \PostIt(Left, Bottom, Right, Top, \Name, \Description,
          ! \GetUserSession()\NavActive);
  \Navigator(1 { Opening condition for the folder },
             Left, Bottom, Right, Top    { Target area for opening -
                                          same as the GUI statement
                                          area.     },
             { Menu line 1 } \PropertiesLabel, Invalid, 0, Invalid);
]
{ End of Common }
>


Widgets for Parent Tags

You can create a tag widget or a parameterized page for a parent tag in the same way that you would for any other tag.

Parameterized pages and user-created tag widgets are particularly well suited for drawing your stations and are an efficient alternative to writing graphics code in the template.

The process for adapting a parameterized page or widget to display all the child tags for a parent tag instance is as follows:

Given a parent tag that has been added to an application and where at least one instance of the tag has been created.

  1. Create either a new parameterized page or a user widget.
  2. Add a parameter to the parameterized page or widget. This will be a tag type where the selected type is the parent tag structure.

  3. Open the page for editing.
  4. Select an instance of the parent tag for the parameter.
  5. Draw the station using the child tags.

  6. For each widget that makes up the station, change its source from tag to parameter.

  7. Select the parameter, then the child tag or grand-child tag from the parent tag.

  8. Save your work.


Rules for Child Tags

The following optimizations and considerations should be heeded when you are using parent and child tags in your application:

  • When structuring a parent and child tags, it is good practice to configure the parent with only those parameters that are necessary to define what is unique for the station (i.e. the parent should have enough parameters to cover variants in the children). The child tags will then have the common parameters defined.
  • Don't launch tags that you do not need. If stations don't use all, launch only the ones required. For example, some stations may have 3 pumps, but others only 2.
  • Child tags that are I/O tags do count towards the tag limit as defined by your VTScada license.


Simplified VTScada Communications Architecture

VTScada is made up of many independent modules that run locally, but benefit from a well-tested Remote Procedure Call (RPC) service. One feature this provides is to manage inter-server communications (from one VTScada server to another) and guarantee that only a single machine becomes the server for a given process.

The RPC service also looks after synchronization between servers. As an example, consider modules that run as tags. The RPC service guarantees that their stored parameters are synchronized between servers. Variables that are not defined as parameters are synchronized only if the module they are within either registers its own RPC service or uses the service provided by another module, such as a driver.

In a typical data acquisition and presentation scenario, an I/O tag will ask a driver to provide the value associated to its address. The driver will request that value through its own method, which is usually a protocol exchange with an external device, such as a PLC. The request operation takes place only in the server currently assigned to the driver’s RPC service. When finished, the driver calls the standard VTSDriver service, which updates the local tag through direct assignment and sends an RPC update message to the same instance of the service on all other connected servers. Those update their local versions of the requesting tag modules, thus assuring that the same tag reports the same value on all servers.

If the I/O tag is configured to enable logging to an attached Historian tag, then that I/O will ask the Historian to log its value. Because all instances of the tag, running on different servers, receive the same data, and have no knowledge of the source of such data (direct communication or RPC broadcast), all will request the Historian to store the value and timestamp. But, because the Historian has an RPC service of its own, it will only perform “data authoring” (attaching the proper timestamp) if it is running on the current Historian server. In that case, it will write the data to the assigned database engine (either the internal file DB or an external ODBC-connected server). Afterward, it will send an RPC broadcast message to all other Historian servers, which will store a copy of that data, rather than the version sent by the local I/O tag. This guarantees that it will be assigned the same timestamp on all servers, thus avoiding duplicate records.

A parallel task, either run inside the I/O tag or through a connected alarm tag, will evaluate the value locally on all machines, through a call to the Alarm Manager, which also runs an RPC service. The alarm status returned by the tag itself will be defined locally, while the alarm event will be raised by the Alarm Manager, but only if running on the current alarm server. Like the Historian (which uses the same engine), it will record an alarm event to the database and broadcast it to all other servers. The main difference is that Alarm Historian tags are usually configured to enable Client Storage. It means that all clients are going to act like passive servers, regardless of whether they are included in the server list. In other words, they will always receive new alarm records from the server, and will try to log those events themselves if unable to communicate with the server. The alarm notification system is based on the alarm records, which will synchronize their notification behavior based on the status currently defined on the database and therefore synchronized across the network.

A simplified diagram of the process follows. This assumes a simple server list with the same machine holding the server role for all communications, historian and alarms. A dashed arrow means that the request will be usually ignored, while dash-dot means it will be ignored on pure clients:


Communication Drivers

Writing a VTScada communication driver involves developing all components that are essential to the software including common driver widgets, error checking, and collection of statistics.

Because VTScada communication drivers are tags, their code must meet all of VTScada's requirements for a tag, as well as the requirements for a driver. The rules for all custom tag types are included elsewhere in the Programmer’s Guide. See: Custom Tag Types.

Older drivers often used two module files: one for the high level tasks that interfaced between the I/O tag and the VTSDriver module and one for the lower level tasks that were specific to the driver protocol. This model is obsolete. It is recommended that communication drivers be created within a single file.

Communication drivers tend to require large amounts of code. This is due to the complexity of the protocols developed for many hardware devices. The VTScada side of the equation is usually quite straight-forward, but it often happens that a large number of subroutines will be needed to handle all the details of a driver’s protocol.

This chapter describes the software design process as it applies to the creation of communication drivers in VTScada. It is organized as follows:

  • The fundamental concepts of how VTScada implements a communication driver are covered in the first few topics. If you have not written a driver before, start with Communication Driver Fundamentals.
  • The information you should gather before beginning to write code is listed in the topic, Communication Driver Design.
  • A step-by-step description of how to create a communication driver is provided, followed by detailed information on the mandatory and optional components of a driver. See: Writing a Communication Driver.
  • A template for a simple driver is presented as an example. All hardware-specific code has been removed from this example, leaving only the VTScada components. See: Communication Driver Template.
  • Information about tools for driver diagnostics and statistics gathering. See: Driver Diagnostic Tools.
  • A reference section is provided, starting at The VTSDriver API, and including:
    • The API of the built-in module, VTSDriver.
    • Details on how driver information is distributed through a networked application.
    • Rules for writing a driver.
  • Instructions for installing and using a driver are given at the end of this chapter. If you have been given the code for a new driver, and are simply looking for the steps to add it to your application, you can skip ahead to the section: Install a New Driver (Example: GE 9030 SNP Driver).

Experienced developers might (very rarely) create their own AddRead or DelRead modules as part of the driver. This might be done if certain address sets or blocks require handling other than the default. If the custom AddRead or DelRead modules return a 0 (or Invalid) then the custom driver's read queues and processing will be used. If the driver does not have a custom AddRead or DelRead, or if the custom modules return a 1, then the default handling will be used.

It is extremely rare for a driver to need a custom AddRead or DelRead.


Communication Driver Fundamentals

Summary:

  • Communication drivers are tags. All the rules of tag structure must be followed when creating a driver.
  • VTScada includes a standardized driver module, VTSDriver that provides a consistent interface to all I/O tags.
  • VTSDriver relies on the communication driver tag to handle read/write requests according to the hardware’s protocol.

VTScada collects information from industrial equipment through hardware input devices, displays the information graphically on a computer, and sends control signals back to hardware output devices to control the operation of the equipment. Computers and hardware input/output devices do not use the same protocol to communicate, therefore a data translator is required to provide communication between the devices. This is the role of a communication driver.

In VTScada, communication drivers are in the form of a specialized tag type. Because each type, make, and model of I/O device uses a different communication protocol, many different communication driver tag types are required to provide the interface from these different I/O devices to the VTScada software.

VTScada ships with communication drivers for the following I/O devices:

Allen-Bradley, CalAmp, CIP, Data Flow RTUs

DNP3, MDS Diagnostic, Modicon, Omron Host Link

OPC Classic Client and Server, Siemens S7, SNMP

… and more.

Tag types can have unlimited instances, therefore many copies of the same or different drivers may run at the same time, providing communication between your PC and multiple I/O device drivers.


Data Exchange between VTScada and a Driver

VTScada uses I/O tags that are assigned to read from or write to specific address in the PLC or RTU. These include analog input and output tags, digital input and output tags, status tags, control tags, etc.

All I/O tags have the following two properties in common:

  • I/O Device: The "I/O Device" property tells the tag which driver tag it should use to communicate with the correct PLC or RTU.
  • Address: The "Address" property tells the tag which memory location at the PLC or RTU to read from or write to.

All communication drivers have a common property:

  • Port: The "Port" property indicates to the device driver tag the correct serial port or TCP/IP socket that it should use to transmit and receive data from the PLC or RTU.

In summary, port tags provide communication over a physical connection between remote equipment and the PC. Communication drivers read and write data over that connection using the protocol required by the remote device. I/O tags within VTScada read data from or send data to the communication drivers to complete the link between the specific addresses in the remote equipment and the widgets on the screen of a VTScada application.


Communication Process

The VTScada software module, "VTSDriver" (the source code for which is stored in a file named, "VTSDrvr.web"), provides the link between the communication driver and the VTScada application. A unique instance of VTSDriver is automatically created for every instance of every driver within an application.

Briefly, the role of VTSDriver is to:

  • Distribute data to I/O tags
  • Trigger polling
  • Distribute data to client workstations via RPC.
  • Synchronize data on startup.

Reading Data

VTSDriver contains a module called, "AddRead" that is called by an input tag to create a request to read a specific range of memory. AddRead expects the following parameters:

  • The address from the input tag.
  • The number of elements (size of the block) to read.
  • A pointer to a place to put the retrieved values.
  • The rate at which to perform the read.

AddRead calls VTSGetAddr and VTSMaxBlock in the communication driver to get the information it needs to coalesce the addresses into appropriate blocks. A ReadBlock module is then launched, which determines the best organization of blocks and launches a separate VTSRead module for each actual block of data to be read.

VTSRead, VTSGetAddr and VTSMaxBlock all reside in the communication driver, not in the VTSDriver module. This is an important detail to note if you are planning to write your own communication driver.

Writing Data

Whenever a value is changed in an output tag, a Write module in VTSDrvr.web is called. This module expects the following parameters:

  • The address from the I/O tag.
  • The number of elements to write.
  • A pointer to the source of the written data.
  • The data type.
  • The name of the I/O tag that called this module to request a write.

The Write module launches WriteData, which in turn calls VTSGetAddr to obtain the information it needs to call VTSWrite. VTSWrite, a module in the communication driver, is then launched.

To emphasize, note that VTSWrite is a module that you create in the communication driver, not in VTSDrvr.web.

Rewriting Data

VTSDriver provides the ability to store and rewrite the last set of output values if requested or required. This feature is controlled by the following code that you may add to your custom driver:

Data Storage

Your custom driver must contain a variable named, StoreOutputs. When set to TRUE (1), VTSDrvr stores the last output value sent to each address. If later changed to FALSE (0), the stored values are erased so that they cannot be written accidentally.

Each VTScada Driver instance stores its own information on what value was written to what address in a retained dictionary. The dictionary is keyed on address and stores both the value and the tag name.

The information is populated only after a successful write has been carried out. It is stored via the module RememberOutputs().

Data Rewrite

A rewrite may be triggered either automatically, or manually.

A module in VTSDrvr named ForceRewrites carries out the rewrite. This module is launched by MonitorRewrites, which determines when the rewrite should execute.

ForceRewrites may be triggered by a user pressing the widget button, Rewrite Outputs. It may also be triggered automatically as follows:

Your custom driver must contain a module named CheckCommLossErr(). An example is provided later in this chapter. This module is called whenever SaveCommStats in VTSDrvr detects an error. CheckCommLossErr() returns a true or false to indicate whether that error qualifies as a loss of communications.

Your custom driver must also contain a Boolean variable named AutoRewrite. If set to TRUE, and if CheckCommLossErr() returns a TRUE value, the trigger is armed.

Upon restoration of communications, as indicated by CheckCommLossErr() returning a FALSE, MonitorRewrites will then execute as follows:

MonitorRewrites monitors the state of the trigger variable, verifies that the server machine's IO instance is in a position to do the writes and verifies that it is the server. Because of the server clause, there will only ever be one instance of this MonitorRewrites through all machines.

The trigger will not be disarmed until ForceRewrite has completed at least one good write.

Read Block Value Coalescing

VTScada combines individual PLC/RTU addresses into a single group or block that is intended to be executed as a single communication message. This is known as "coalescing" and is an attempt to increase throughput by allowing the reading and writing of large blocks of data, where possible.

There are a number of VTScada modules and variables that control how coalescing will be performed:

  • VTSGetAddr: Gets the addresses for the blocks of data and parses them. The Info1, Info2, and Info3 parameters provided to this module must be either invalid or the same type in order for coalescing to occur.
  • VTSMaxBlock: The value of the VTSMaxBlock variable sets the maximum number of values that can be coalesced into a single read. As an alternative, there may be a VTSMaxBlock subroutine defined, which returns the size of the maximum block for a given address.

The result of coalescing depends on the data type of the MemAddr parameter in VTSGetAddr:

  • If MemAddr is numeric, VTScada will coalesce the message blocks into a continuous address range, even if that range includes addresses that are not identified or needed. For example, if the system is configured to read addresses 15 and 50, and the VTSMaxBlock variable is set to 100, then VTSRead is called such that addresses 15 to 50 will be read as a single read message, even though address 16 to 49 inclusive are not needed.
  • If the data type of MemAddr is a string, then the result of the coalescing algorithm includes the configured addresses. Using the same example as above, VTSRead is passed an array of strings (in the MemAddr parameter) with two elements 15 and 50.


Communication Driver Design

VTScada was created using an object-oriented, layered approach to software design, and it is highly recommended that VTScada communication drivers follow suit. One advantage to this approach is modularity, because components may be added or removed without affecting critical components. Layers are designed to build on the functions and services of the lower layers. The communication driver software should be self-contained, and have only a few well-defined entry points. This makes it less reliant on other code so that changes to one part will have a limited effect on other parts of VTScada.

The error state of Communication drivers can be represented on a page by a Status Color Indicator Widget. For the widget to use the error colors defined in an associated Style Settings tag, the driver must contain a flag named ValueIsErrorStatus, set to TRUE. If this flag does not exist, or is not set TRUE, then the widget will use the colors defined for state 0 and state 1 in the Style Settings tag.

By default, zero is defined as "no error" and all other values as "error". You can expand the range of "no error" values by using the following two parameters:

ValueIsErrorAbove as a numeric. This is the value above which the tag will be treated as being in error. Defaults to 0.

ValueIsErrorBelow as a numeric. This is the value below which the tag will be treated as being in error. Defaults to 0.

Error Messages

If you are writing a driver that will become part of VTScada you will need to supply a list of known error codes and matching messages. When adding those to the language file, en.csv, they must all follow a common naming format, as follows. The number may be decimal or hexadecimal as used by the driver. Do not include the words "driver" or "label".

NameErrMsgNum

Examples from en.csv:

ABErrMsg0x200,Communication Failure - Retry Limit Exceeded,6
CIPENIPErrMsg0x0001,Connection failure,6
GE90SerialErrMsg01,Privilege Level Insufficient,6


Steps to Write a Communication Driver

  1. Gather the details of the hardware protocol.
  2. Create a new source file using a text editor (such as UltraEdit). Ensure that this source file is named logically, and is given the extension ".SRC" (e.g. "MyDriver.SRC"). Save this source file within your application's folder.
  3. Structure your source file according to the rules for a tag template.
  4. Referring to the topic, Mandatory Communication Driver Components, add the modules and variables required for a driver. The code you write in the mandatory modules will depend on the driver protocol.
  5. According to the details of the driver protocol and your interest in logging statistics, add Optional Communication Driver Components.


Researching a Communication Driver Protocol

A communication driver cannot be written without a full understanding of the protocol that the I/O device uses to communicate. A document that completely describes the protocol must be located, or the device must be reverse-engineered by monitoring communications and experimenting with the inputs and outputs. At a minimum, you will need to know:

  • The structure of the messages the I/O device sends and receives.
  • The valid values for each component of the message.
  • The format that the device expects the data to be in.
  • Error detection and correction procedures, if used.
  • If a checksum or cyclic redundancy check (CRC) is included in the message, the algorithm that is used to calculate it must be known.

Also, some protocols will define an "end of message" character to indicate the end of the packet. In other protocols, the messages are fixed length, and the length of the packet is either a constant or is indicated as part of the header. You cannot proceed without knowing this structure.


Design an Addressing Scheme

An addressing scheme is a logical means of organization whereby memory locations in the I/O device are labeled (often, according to the data type stored) for access by external devices. Some protocols specify an addressing structure, and it usually makes sense to use this addressing scheme instead of redesigning it.

Whatever addressing scheme is used, it must be broken down into information that is stored in a series of 3 parameters (Info1, Info2, and Info3) by a module in the communication driver named, "VTSGetAddr". This information may be the type of data, byte number, record or file number, or something else that is protocol specific. These parameters should contain whatever information is necessary to build and decode the packet that is sent to and received from the correct location in the I/O device.

This information is also used to coalesce the addresses into blocks so that a single communication message can send or receive a large amount of data. Although single address reads and writes are permitted, block reads and writes increase the throughput and overall performance of the software. Addresses are combined into blocks that are as efficient as possible. For example, if the file number is one of the info parameters, the VTSDriver module waits for a series of read or write requests, looks at the file numbers for each request, and then attempts to combine as many sequential file numbers as possible into a single block.

It may be that an address structure is not defined in the device protocol. In such cases, one will have to be designed. An addressing scheme may divide common addresses into groups, but each address must be unique.


Provide an AddressAssist Module

A driver may provide a custom AddressAssist module to assist the user in building addresses when configuring I/O tags. An example may be seen in any I/O tag that is using an SNMP or OPC Classic Client driver.

The module is commonly stored in its own file, with a unique name matching the driver it is meant for, but within the driver itself it must be declared using the name "AddressAssist". The PAddressEntry function (used in the I/O tag's configuration) will check for the existence of an AddressAssist module and (if found) display your code instead of the usual edit field.

The AddressAssist must provide the code for the user interface elements that will be displayed in the I/O tag's configuration panel as well as whatever user-interface tools will be provided to help the developer to select the address. For the configuration panel element, you may:

  • draw an edit field with a browse button (as shown in the preceding example),
  • create a drop-list or drop-tree with possible addresses,
  • create any other address selector that fits within the space of the usual edit-field for address entry.

A simplified example of an AddressAssist module follows.

{======================= AddressAssist ===================================}
{ A custom address selection module for a driver. It consists of          }
{ the usual edit field, along with a button that launches an              }
{ address browser.                                                      }
{=========================================================================}
(
  Left                     { The left coordinate of the address assist    };
  Bottom                   { The bottom coordinate of the address assist  };
  Right                    { The right coordinate of the address assist   };
  Top                      { The top coordinate of the address assist     };
  Var                      { The variable that we're going to set          };
  SupportedData            { Digital, Analog, or Text                     };
  FunctionType             { Read/Write                                   };
  ID                       { Focus ID of the editfield                    };
  Trigger                  { Set when var changed                         };
  BGColor                  { Background color to use in the edit field    };
  FGColor                  { Foreground color to use in the edit field    };
)

Main [
  { Display the edit field with a Browse button }
  System.Edit(Left, Top, Right - SmlBtnWd - Space,
               Bottom + EditHt { Coordinates },
               Invalid, Var, ID, Trigger, Invalid, 4 {Text},
               0 { no bevel }, Invalid, Invalid, Invalid, Invalid,
               Invalid, Invalid, Invalid, BGColor, FGColor);
  If GUIButton(0, 1, 1, 0              { Unit box             },
               1 - (Right - SmlBtnWd)  { 1 - Left             },
               Top + BtnHt             { Bottom               },
               Right                   { Right                },
               1 - (Top)               { 1 - Top              },
               1                       { Scaling              },
               0, 0                    { Movement             },
               1, 0                    { Visibility, Reserved },
               PickValid(ID, 1) != 0 ? 68 : 0, PickValid(ID, 1),
               0  { Selectability },
               ButtonFace,
               ButtonShadow,
               ButtonHighlight,
               ButtonTextColor  { Colors           },
               0, 0             { Sides, Reserved      },
               "...", "..."     { UpLabel, DownLabel   },
               _DialogFont, 0, 1, 2 { Font, DownValue, UpValue, Variable},
               SmallButtonImgs);
  [
    { Implement custom code here to display your address browser }
  ]

  Return(TRUE);
]


Control Access to Shared Resources

In many cases, an application must communicate with multiple pieces of equipment over a common medium, such as a serial port. In order to prevent multiple driver tags from accessing the same communications medium simultaneously, semaphores (Queued Modules) are used. The driver tag is responsible for calling the \PortManager.PortConnectSem module. This module will return true indicating the port is ready to be accessed. It is recommended that driver tags be created with separate read and write semaphore modules. This ensures that queued write requests (such as emergency shut-down instructions) will be processed in a timely fashion by alternating between read and write requests.


Modem Support

Communication drivers are responsible for triggering outgoing modem connections if required. Regardless of whether the driver will be connecting to the device using a modem or not, this mechanism should be implemented as it is required to support TCP/IP connections.

Also, regardless of whether the hardware supports a TCP connection or not, TCP support should be implemented so that devices such as Lantronix, which provide TCP/IP to serial conversion, can be used.

In order to connect to hardware using a modem, the driver must call the port tag’s Port\Connect() module. Before calling the connect module, the driver should check the Port\Modem variable to make sure a connection must be established before communications can begin. The variable Port\IsConnected() can be checked to determine if the connection has been made.

In order for the driver to accept an incoming modem connection ("hardware dialed in"), a discriminator must be written. This module will inform the modem manager which calls should be handed to the driver. This is required since many different units and types of hardware may be dialing in. Details on creating discriminators and registering them with the modem manager are covered in the Modem Manager Service document.


Mandatory Driver Components

Within your driver source file, you will need to create the following modules. These modules are well-defined entry points that are called by VTSDriver in VTSDrvr.web.

  • VTSRead - reads VTScada variables from an input device.
  • VTSWrite - writes VTScada variables to an output device.
  • VTSGetAddr - gets the VTScada addresses and parses them.
  • VTSMaxBlock - defines the maximum size for block reads and writes

Of particular note in this list is VTSMaxBlock. Your configuration may still work initially, but without a set maximum size for block reads and writes, it is inevitable that you would eventually break packet size limits.

You must also define the following variables:

  • Driver - This is used internally by the VTScada engine and should not be set by the driver tag code being created. It will automatically be linked to the instance of VTSDriver that will be created for this driver instance.
  • Ready - This variable should be set to 1 by the driver tag code when it is safe to start reading or writing I/O.
  • Value - Will be set to the local Error value of VTSRead \ VTSWrite whenever they increment their Counts or ErrorCounts variable.
  • Root - Set to some object value, usually Self().

Do not name any variable in your driver AddRead or DelRead.


Optional Driver Components

The following variables and modules, while often found in communication drivers, are defined as optional.

  • Hold - Set to 1 to hold data on error. Otherwise, all data is invalidated when an error occurs. Normally defined as a parameter.
  • ByteOrder - reverse byte order if data is not being provided in the Intel, little-endian format. By default, VTScada assumes that the 1st byte is the low-order byte.
  • RPCService - necessary for networked applications. Set to a string that is the name of the RPC service that will handle the driver. Usually, the service name will be the same as the tag name. There is also a configuration setting for this value.
  • GetClientRevision - RPC service
  • GetClientChanges - RPC service
  • CommStatsUpdateRate - For this and the next two items, see: Driver Diagnostic Tools.
  • CommStatsQualityFactor - see: Driver Diagnostic Tools.
  • DisableCommStats - see: Driver Diagnostic Tools.
  • ErrMessage. Optional but strongly recommended. This should be defined as a public module that will return text matching a given error code number. Messages may be hard-coded in the driver or extracted from the device as appropriate. They are normally stored in an array, indexed by the error code value.
  • StoreOutputs - A variable used to indicate that the driver should store the last set of values written to each output address.
  • AutoRewrite - A variable used to indicate that this driver should automatically rewrite stored values upon recovery from a communications error.
  • CheckCommsLossErr - A module that determines if the current ErrorVal value indicates a loss of communications. Used if providing AutoRewrite capabilities.


Data Propagation

The VTSRead that you create as a subroutine of your driver is responsible for delivering the data that it read from the I/O device. This is best done by using the RefreshData module within the scope of the CallBackObj parameter of the VTSRead module. If your driver needs to invalidate all data due to a communication failure, use the NoData module within the scope of the CallBackObj parameter of the VTSRead module.

RefreshData is provided for you as part of the VTSDriver module.


Port Manager

The VTScada Port Manager service provides a simplified means for drivers to access and share Serial, TCP/IP, and UDP/IP ports. The service allows for a driver to make a single call before accessing a port for read and write operations. This call can provide all of the following:

  • Queued semaphore access to the port
  • Open the port connection to the remote device
  • Provide indication of success when ready to use
  • Provide indication of failure if the connection was not made
  • Provide an indication of failure if the port was disconnected during use

The port manager will return one of several error codes when a fault is detected, starting at a value of 1. A successful connection is indicated by a value of 0. While waiting for the connection attempt, the function will return nothing.

Error codes

Drivers making use of the PortManager should allocate a space of 50 errors to allow for the full range that can be provided by the service. Currently defined error codes are:

#PMNoError = 0

#PMPortNotDefined = 1

#PMPortFailToConnect = 2

#PMPortLostConnection = 3

#PMPortOutofRange = 4

#PMPortInUse_NotAvail = 5

#PMPortAccessDenied = 6

#PMPortGeneralFailure = 7

#PMPortParameterBad = 8

#PMPortNotConnected = 9

#PMUnknownError = 10

#PMMaxErrorCodes = 50

The Port Manager API

Two public functions are provided by the port manager:

\PortManager.PortConnectSem

Description | A generic port connection / semaphore for use within drivers that returns the stream for the caller to use.
Returns | TRUE when the port semaphore has been granted A numeric error code if that semaphore will not be granted Nothing (Invalid) if waiting for the port semaphore
Usage | Script Only.
Format | \PortManager.PortConnectSem(PortObj [, RetError, pStream, ReadOrWrite, AllowMultipleConnections]);
Parameters |
PortObj
Required. The object of the port tag from which we require a connection and semaphore.
RetError
Optional. A pointer to a value that will contain one of the defined error codes at the conclusion of the operation.
pStream
Optional. (But recommended.) Used to allow PortConnectSem to return the Stream on which data should be transferred back to the driver.
ReadOrWrite
Optional. (But recommended.) Used to set the semaphore type for the request and should be set to the constants #ReadSem or #WriteSem.
AllowMultipleConnections
Optional. (But recommended.) Used to tell PortConnectSem() whether the driver supports multiple connections

\PortManager.GetErrorMessage

Description | Returns a text error message for a given error code.
Returns | Text
Usage | Script Only.
Format | \PortManager.GetErrorMessage(RetError);
Parameters |
RetError
Required. The error code returned in the RetError parameter of a call to PortConnectSem

Example:

The following code sends text “Hello Detroit!!!” out through port tag defined by parameter “PortTag”
every 1 second after the port has opened and has the semaphore.  If an error is encountered, the module
returns the text value of the error to the calling module.

Connect_And_Send [
   { Get the object value of the port defined in driver tag parameter PortTag }
  PortObj = Scope(Root, PortTag);

   { Attempt connection and get the semaphore }
  OkToSend = \PortManager.PortConnectSem(PortObj, RetError, &Stream, #WriteSem, FALSE)

   { When connected & we have the semaphore, OK to send every 1 second }
  If TimeOut(OKToSend, 1);
  [
    SWrite(Stream, “Hello %s!!!\r\n”, PickValid(\GreatRockTown, “Detroit”));
  ]

   { Error was detected on port, all done with it }
  If RetError AllDone;
  [
    Return(\PortManager.GetErrorMessage(RetError));
  ]
]

AllDone [
  { Nothing to see here, keep moving along }
]


Communication Driver Template

A sample communication driver is displayed in part here. Code that is useful only for the particular hardware this driver was designed to communicate with is not included. This driver was designed to be read-only. It does not contain a VTSWrite module. The tag’s configuration and common modules are not shown here.

The driver starts with standard tag definitions:

{===============================================================}
(
  Name              <:TagField("SQL_VARCHAR(64)",  "Name" ):>;
  Area              <:TagField("SQL_VARCHAR(255)", "Area" ):>;
  Description       <:TagField("SQL_VARCHAR(255)", "Description" ):>;
  HelpKey           <:TagField("SQL_VARCHAR(255)", "HelpKey" ):>;
{
 Other parameters will vary by driver but often include the following
}
  RespTimeOut       <:TagField("SQL_VARCHAR(255)", "RespTimeout" ):>;
  SiteID            <:TagField("SQL_VARCHAR(255)", "SiteID" ):>;
  UTCOffset         <:TagField("SQL_VARCHAR(255)", "UTCOffset" ):>;
  StoreOutputs      <:TagField("SQL_VARCHAR(255)" ):>
          { When TRUE permits storing of output values     };
  Hold              <:TagField("SQL_INTEGER", "Hold" ):> = 0
          { 1=hold last value 0=invalidate on error };
  AutoRewrite       <:TagField("SQL_VARCHAR(255)" ):>
          { When TRUE permits the automatic Rewriting of Outputs };
)

[ {Variables}
  {==================Version Control Information =================}
  { V 0.0.01 - Original issue - 9 December, 2008                 }
  {===============================================================}
  Constant DriverVersion                  = "0.10.0 6 January, 2009";
  Constant DrawLabel                      = "USGSDriver";
  Constant #Name                          = 0;
  Constant #Area                          = 1;
  Constant #Description                   = 2;
  Constant #ResponseTimeOut               = 3;
…

In the variable declaration modules and error constants are also defined:

  { Module Numbers }
  Constant #VTSGetAddr                    = 0;
  Constant #VTSRead                       = 1;

  { Error Constants }
  Constant #NoError                       = 0;
  Constant #ConnectionError               = 1;
…

As well as the required modules and variables (plus a few extra shown here):

  {***** Required for all VTScada drivers *****}
  DriverNameLabel     = "DemoDriver";
  Driver                { The generic driver module instance   };
  Ready                 { Indicates to VTScada driver the module is ready };
  RPCService            { Name of the RPC service for this tag };
  Value                 { Driver status                        };

{ Modules }
  ShowComm      Module  "DemoShowComm.SRC"  { Show communication };
  ShowStats     Module  "DemoShowStats.SRC" { Show comm statistics };
  VTSMaxBlock   Module  { Returns Maximum record size          };
  VTSRead       Module  { The Read module                      };
  VTSGetAddr    Module  { Subroutine to parse address          };
  Refresh       Module  { Refresh module                       };
  ErrMessage    Module  { Converts error codes to text strings };
  ReportTraffic  Module { Translator for the traffic monitor   };
  SetStats      Module  { Updates driver statistics            };
  TransmitReceiveData Module { Transmit/Receive Module         };
  ProcessReturnedData Module { Processes ret data into arrays  };
  SiteTime_2_UTCTS    Module { Converts Site time to VTScada time  };
  HistPoll     Module    { Sets the history poll values        };
  ReadLineStatus  Module  { Reads a line and returns status    };
  CheckCommsLossErr Module { Checks the comms fail errors      };

   { Variables }
  Root              { Root object value                    };
  DriverObj         { Object value of driver               };
  CommPortObj       { Communication port tag object        };
  ErrorMessages     { Array of Error Messages              };
  Counts       = 0  { # of successful transactions         };
  TimeStamp         { Time of last successful transaction  };
  Error          = 0 { Global Error code                    };
  ErrorCounts    = 0 { # of errors since starting           };
  ConsecErrCount = 0 { Consecutive time out error counts    };
  ErrorMemAddr       { Memory address of last error         };
  ErrorTime          { Time of last error                   };
  LastError          { Error code for last error            };
  Shared Message[100]  { List of error messages             };
  CommDisplay        { Object communications display module };
  ErrorModule        { Module number generating error       };
  ErrorDate          { Date of last unsuccessful com attempt};
  ErrorOwner         { Object value of module last error    };
  dt                 { Time since last transaction          };
  DateStamp          { Date of last successful comm.      };
  LastURL            { Last URL generated                   };
  ResponseTO         { Response Time Out variable           };
  DataFilePath       { Path for data file to write/read     };
  Status             { Status of file directory creation    };

Finally, the standard groups memberships are defined:

  { Parameter Constants }
  [ (GROUPS)
   Shared Numeric;
   Shared Drivers            { This is a driver point };
  ]

  [ (GRAPHICS)
   Shared CommIndicator;
   Shared CommStatistics;
   Shared CommMessages;
   Shared ReWriteOutputsBtn; { Used if implementing Rewrite Outputs }
  ]

  [ (PLUGINS)
    Shared ConfigFolder = "DemoDriverConfig";
    Shared Common       = "DemoDriverCommon";
  ]

The module opens with an initialization state:

DemoDriverInit [

  If \NetworkValues\Started WaitServer;
  [
     { Set the RPC service for this instance depending on the }
     { Configuration parameter }
    RPCService = PickValid(\USGSSharedRPC, 0) ? "USGSDriver" : Name;
     { Return object value }
    Root = Self();
    DriverObj = Root;
    Refresh();

    IfThen(!Valid(Message[#NoError]);
       { Set up of driver statistics display labels }
      CountsLabel           = PickValid(\CountsLabel, "Counts");
       { … etc … }

       { Driver internal errors }
      Message[#NoError                ]  = "No Error";
       { … etc … }

    ) { IfThen };

     { Register with the network values service }
    \NetworkValues\Register(Self(), Name);

  ]
]

Rather than one main state, the driver has three: Wait, Client and Server. Most of the time it will be in the Wait state, waiting to send or receive data.

Wait [
    { If this PC is a data server for this PLC, }
    { go to the Server state }
  If PickValid(Driver\Started, 1) &&
     PickValid(*(Driver\RPCStatus), \#RPCServer { Server }) == \#RPCServer Server;
    { If this PC is a client for this PLC, go to the Client state }
  If PickValid(Driver\Started, 1) &&
             *(Driver\RPCStatus) == \#RPCClient Client;
]

Server [
    { If no longer server go to wait state }
  If *(Driver\RPCStatus) != \#RPCServer Wait;
    { Get object values in steady state }
  CommPortObj = USGSTCPIPPort;
  Ready = 1;
    { Reset if there is a switch from a server to a client }
  If *(Driver\RPCStatus) != \#RPCServer Wait;
]

Client [
    { Get object values in steady state }
  Ready = 1;

  If PickValid(*(Driver\RPCStatus),\#RPCServer) != \#RPCClient Wait;
]

The last tag-specific part of the driver is the Refresh module. If implementing Auto-Rewrites, include code to ensure that the StoreOutputs value is always true if AutoRewrite is true.

<
{=========================== Refresh =============================}
{ Refresh subroutine.                                          }
{=================================================================}
Refresh
(
  Parm { Array parameters prior to their change }
)

Refresh [
  If Watch(1);
  [
    RPCService = Name       { Set RPCService                  };
    UTCOffset  = PickValid(Cast(UTCOffset, 2) , TimeZone(0));
    ResponseTO = PickValid(ResponseTimeOut, 10);

   StoreOutputs = PickValid(Cast(StoreOutputs, \#VTypeShort), 0);
   AutoRewrite  = PickValid(Cast(AutoRewrite,  \#VTypeShort), 0);
{ Sort the parms, when AutoRewrite is true, StoreOutputs must be true }
   IfThen(AutoRewrite && !StoreOutputs,
     StoreOutputs = 1;
   );

   IfThen(!StoreOutputs &&
           PickValid(*(Driver\RPCStatus) == \#RPCServer, 0),
      Driver\ResetOutputDict();
   );

    Return(0);
  ]
]
{ Refresh }
>

Refresh is followed by the standard modules of a communication driver: VTSGetAddr, VTSMaxBlock, VTSRead and VTSWrite. In the following examples, any code that is not general in purpose has been removed.

<
{================ USGSDriver\VTSGetAddr ========================}
{                                                              }
{===============================================================}
VTSGetAddr
(
  Address        { Raw address specified by point parameters};
  RetAddress     { Returned address                          };
  BitNum         { Pointer to bit number variable to set     };
  TableName      { Table name                                };
  Info2          {                                           };
  Info3          {                                           };
  DType          { Pointer to data type to return            };
  Read           { TRUE if a READ address, otherwise write   };
  Rate           { Rate for read coalescing                  };
)
[
  NRead          { Number of Values not read                 };
  SiteNumber     { Station Number Field                      };
  ParameterField { Parameter Field                           };
  AddressError   { Set on error                              };
]

Main [

  If Watch(1);
  [
    AddressError = 0;
     { Need an valid non-null value address }
    IfElse(Valid(Address) && StrLen(Address) > 0;
       { Set to incoming address -           }
       { sends array of addresses to VTSRead }
      *RetAddress   = Address;
      *AddressError = 1;
    ); { IfElse }
     { Return error }
    Return(AddressError);
  ]
]
{ End of VTSGetAddr }
>

<
{======================= VTSMaxBlock =========================}
{ Returns the Maximum size for block reads and writes. In    }
{  example, VTSMaxBlock will simply return a constant.     }
{=============================================================}
VTSMaxBlock
(
  Info1              { Not used                  };
  Info2              { Not used                  };
  Info3              { Not used                  };
  DType              { Pointer to data type      };
)
[
 Constant #VTSMaxBlock = 100;
]

VTSMaxBlock [
  Return(#VTSMaxBlock);
]
{ VTSMaxBlock }
>

Here comes the VTSRead module. Again - only the most general purpose of statements have been included.

<
{================= USGSDriver\VTSRead =======================}
{ This module performs the I/O reads.                     }
{============================================================}
VTSRead
(
  Trigger       { Will do read on positive edge             };
  Array         { Array to put the result into              };
  N             { The number of values to read              };
  MemAddr       { Field Name Parameter                      };
  BitNum        { Pointer to bit number variable  (not used)};
  Info1         { Site Number to read                       };
  Info2         {                                           };
  Info3         {                                           };
  DType          { Data type                                 };
  RefreshContext { Where to call the RefreshData() module    };
)

[
  Name   = "VTSRead"  { Module name for stats                };
  LocErr              { Local Error                          };
  Counts       = 0    { # of successful transactions         };
  TimeStamp           { Time of last successful transaction  };
  Error        = 0    { Global Error code                    };
  ErrorCounts  = 0    { # of errors since starting           };
  ErrorMemAddr        { Memory address of last error         };
  ErrorTime           { Time of last error                   };
  LastError           { Error code for last error            };
  ModNumber           { Module number for VTScada read           };
  SiteData            { Data array to pass to refresh context};
  SiteTimeStamp       { Timestamp array to pass to refresh context};
…
]

Init [
  If 1 VTSWaitTrigger;
  [
    Return(Self);
  ]
]

VTSWaitTrigger [

  If Trigger GetSiteData;
  [
    ResetParm(Self(), 1)      { Reset the trigger              };
    LocErr         = Invalid();
    SiteData       = New(N);
    SiteTimeStamp  = New(N);

     { Type of poll  - default to data since last poll }
    PollType       = PickValid(HistPollType, #HistPollSinceLast);
  ]
]

GetSiteData [
  LocErr = TransmitReceiveData(SiteID, MemAddr, StartDateTS,
                               EndDateTS);
  If !LocErr ProcessData;
  [
    LocErr = Invalid();
  ]
  If LocErr SetStats;
]

ProcessData [
  LocErr = ProcessReturnedData(&SiteData, &SiteTimeStamp,
                                LastTSRead);
  If !LocErr SetStats;
  [
     { Send the new data and timestamps }
    RefreshContext\RefreshData(SiteTimeStamp, SiteData);
     { Update the network variable }
    LastReadingTS = Max(PickValid(LastReadingTS, 0), LastTSRead);
  ]
  If LocErr SetStats;
]

SetStats [
  If 1 VTSWaitTrigger;
  [
    SetStats(Error = LocErr, Self(), ModNumber, 0, 0)
                    { Set driver stats };
    IfElse(LocErr;
      ++ErrorCounts;
       { Else no error }
      ++Counts { Increment counts };
    ) { IfElse };
  ]
]
{ USGSDriver\VTSRead }
>

If implementing automatic rewrites of saved data, you must have CheckCommsLossErr() module similar to the following. The specific error codes will depend on your driver - those used in the example are for the Allen Bradley driver only.

<
{================== ABDriver\CheckCommsLossErr ====================}
{==================================================================}
CheckCommsLossErr
 (
  ErrorVal;
)
Main [
  If 1;
  [
    {***** Comms Loss errors noted for the AB driver *****}
    IfThen(ErrorVal == 4       ||
           ErrorVal == 32      || ErrorVal == 48    ||
           ErrorVal == 64      || ErrorVal == 0x200 ||
           ErrorVal == 0x202   || ErrorVal == 0x213 ||
           (ErrorVal >= 0x300  && ErrorVal <= 0x309),
      Return(1);
    );
    Return(0);
  ]
]
{ End of ABDriver\CheckCommsLossErr }
>

In the code for your driver's configuration panel, if you are implementing output rewrites, you must also provide a check box for AutoRewrite and StoreOutputs. Include the following code to ensure that if AutoRewrite is true, StoreOutputs can't be false:

  If Watch(0, Parms[\#StoreOutputs]);
  [
    IfThen(!Parms[\#StoreOutputs],
  { Ensures if StoreOutputs is false then AutoRewrite can't be true }
      Parms[\#AutoRewrite] = 0;
    );
  ]

  If Watch(0, Parms[\#AutoRewrite]);
  [
    IfThen(Parms[\#AutoRewrite],
  { Ensures if AutoRewrite is true then StoreOutputs can't be false }
      Parms[\#StoreOutputs] = 1;
    );
 ]


ShowStats Submodule

Required to draw a Show Stats widget for your driver.

The following template provides a generic dialog. Yours may differ.

<
{================================= ShowStats ===============================}
{ This module displays a window showing current driver statistics for the   }
{ main driver.                                                              }
{===========================================================================}
ShowStats
(
  Enable                      { Set true to display window                  };
)
[
  PROTECTED Info              { Driver info                                 };
  PROTECTED Stats             { Driver stats                                };
]

Init [
  If 1 Show;
  [
    Info  = Dictionary();
    Stats = Dictionary();
     { Declare the labels in the order we want them displayed }
    Info["DriverNameLabel"]     = Name;
    Info["DriverTypeLabel"]     = Invalid;
    Info["VersionLabel"]        = DriverVersion;
    Stats["CountsLabel"]        =
    Stats["TimeStampLabel"]     =
    Stats["DateStampLabel"]     =
    Stats["DtLabel"]            =
    Stats["MaxDtLabel"]         =
    Stats["MinDtLabel"]         =
    Stats["ErrorLabel"]         =
    Stats["ErrorMessLabel"]     =
    Stats["LastErrorLabel"]     =
    Stats["LastErrMessLabel"]   =
    Stats["ErrorCountLabel"]    =
    Stats["ErrorTimeLabel"]     =
    Stats["ErrorDateLabel"]     =
    Stats["ErrorMemAddrLabel"]  = Invalid;
  ]
]

Show [
  \ShowStatsDialog(Enable, Info, Stats, HelpID {If F1 help is available});
  Info["DriverTypeLabel"]    = \GetPhrase(\GetDrawLabel(Root));
  Stats["CountsLabel"]        = Counts;
  Stats["TimeStampLabel"]     = GetTimePhrase(\CommStatsTimeStamp, "TimeFmtHMS24Hour");
  Stats["DateStampLabel"]     = GetDatePhrase(\CommStatsTimeStamp / 86400, "DateFmtFullWritten");
  Stats["DtLabel"]            = Format(0, 3, dt);
  Stats["MaxDtLabel"]         = Format(0, 3, Maxdt);
  Stats["MinDtLabel"]         = Format(0, 3, Mindt);
  Stats["ErrorLabel"]         = Error;
  Stats["ErrorMessLabel"]     = ErrMessage(Error);
  Stats["LastErrorLabel"]     = LastError;
  Stats["LastErrMessLabel"]   = ErrMessage(LastError);
  Stats["ErrorCountLabel"]    = ErrorCounts;
  Stats["ErrorTimeLabel"]     = GetTimePhrase(ErrorTime, "TimeFmtHMS24Hour");;
  Stats["ErrorDateLabel"]     = GetDatePhrase(ErrorDate, "DateFmtFullWritten");
  Stats["ErrorMemAddrLabel"]  = ErrorMemAddr;
]
{ ShowStats }
>

Any values you want can be put in the Stats dictionary. The values need to be set somewhere, which is usually done in a post-read data-processing submodule or in a subroutine as follows.

<
{=================================== SetStats ================================}
{ This subroutine sets the driver stats                                       }
{=============================================================================}
SetStats
(
  Err;
  ErrAddress;
)

Stats[
  If Watch(1);
  [
    IfElse(!Err,
      Execute(
        { Good Message }
        Error = Err;
        ++Counts;
        dt = Seconds() - TimeStamp;
          { Check for negative dt }
        IfThen(dt <= 0,
          dt = Invalid;
       ); { End IfThen }

        Mindt = PickValid(Min(Mindt, dt), Mindt, dt);
        Maxdt = PickValid(Max(Maxdt, dt), Maxdt, dt);
        TimeStamp = Seconds();
        DateStamp = Today();
      ) { Execute };
    {ELSE}
      Execute(
        { Bad Message }
        LastError = Error;
        Error = Err;
        ++ErrorCounts;
        ErrorTime = Seconds();
        ErrorDate = Today();
        ErrorMemAddr = ErrAddress;
      ) { Execute };
    ) { IfElse };
    Return();
  ]
]

{ SetStats }
>


ShowComm Submodule

Required to draw a Show Comm widget for your driver.

{ShowComm and CommDisplay are declared in the driver's
  variables list: }

<
{================================== ShowComm ============================}
{ This module displays a window showing current driver communication for }
{ the main driver.                                                       }
{========================================================================}
ShowComm
(
  Enable                      { Set true to display window               };
)
[
  PROTECTED Info              { Driver info                              };
  CONSTANT  HelpID = 00000    { Set to the assigned F1 help ID           };
]

Init [
  If 1 Show;
  [
     { Declare the labels in the order we want them displayed }
    Info = Dictionary();
    Info["DriverNameLabel"] = Name;
    Info["DriverTypeLabel"] = \GetDrawLabel(Root);
    Info["VersionLabel"]   = Version;
  ]
]

Show [
  Info["DriverTypeLabel"] = \GetPhrase(\GetDrawLabel(Root));
  CommDisplay = \ShowCommDialog(Enable, Info, 3 { ASCII }, HelpID);
]
{ ShowComm }
>

ShowCommDialog is a VTScada module taking up to 5 parameters:

  • Boolean. Set true to open the dialog.
  • Info. A dictionary of information to show in the top section (see code sample).
  • DataType. Optional numeric. May be any of 0=Dec, 1=Octal, 2=Hex, 3=ASCII, for initial selection for data display. Defaults to 0.
  • HelpID of dialog.
  • NRows. Optional numeric. Number of rows in the dialog's gridlist.

ShowCommDialog exposes four public variables. The caller may scope into the module to set the transmit and receive buffers through the following four public variables:

{ PUBLIC }
XmitBuff        { Transmit buffer to display                    };
RcvBuff         { Receive buffer to display                     };
RebuildXmit     { Set true to rebuild transmit buffer           };
RebuildRcv      { Set true to rebuild receive buffer            };


Error Messages

Drivers typically have a submodule named ErrMessage, which returns a text message for a given numeric error code. May be called as a subroutine or in steady-state.

In the driver module, error labels are built using dictionaries. In earlier versions of VTScada, these were stored in Settings.Dynamic using the format:

ABErrMsg0x3FD                    = Time limit on RSLinx response

or

SiemensS7ErrMsg133               = PG/OP Response Exceeds Maximum Length

where the number following "ErrMsg" is the decimal or hex value of the error code matching the label.

Error messages are now stored in the language files (en.CSV, etc.) with a key identical to the old property name.

The driver must transfer these values into a dictionary:

ErrMess[10] = \DriverNameErrMsg10;

<
{============================== ErrMessage =================================}
{ This module returns a text message for an error code handed to it as a    }
{ parameter.  It can be called as a subroutine or in steady state.          }
{ It accesses the error text from the Mess array allowing clients to also   }
{ get the error message.                                                    }
{===========================================================================}
ErrMessage
(
  ErrCode                       { Code to return message for                };
)

Main [
  If Watch(1, ErrCode);
  [    Return(Valid(Code)
            ? \GetPhrase(PickValid(Mess[Code], "UnknownErrorCodeLabel"))
            : \GetPhrase("InvalidErrorCodeLabel"));
  ]
]
{ ErrMessage }
>


DriverMUX support

The driver multiplexer requires a call to RecommendAlternate.

\RPCManager\RecommendAlternate(RPCService)

The MUX driver intercepts the RPC call and fails over the driver. This is usually written in the Server state of the driver.

PROTECTED PLCConnectErrors = 0 { Total PLCConnMon connect attempts       };
{ If the consecutive connection attempts exceeds limit recommend alternate }
If PLCConnectErrors > PickValid(\VRDPLCConnAttLimit, 5);
[
  IfThen(!PickValid(\NoSoftDriverFailure, 0),
         { Surrender being the server if we cannot connect }
         \RPCManager\RecommendAlternate(RPCService);
        );
  { Reset the connection attempts }
  PLCConnectErrors = 0;
]

Increment PLCConnectErrors where error processing occurs and set to 0 when a successful connection is made. Example:

{ If there was an error, increment counter for MUX driver fail over }
IfElse(Err,
  PLCConnectErrors++;
  {ELSE}
  PLCConnectErrors = 0;
) { IfElse };


The VTSDriver API

The VTSDriver module is supplied with VTScada. It includes the generic driver interface for VTScada and is used in combination with each device-specific communication driver.

Several of the functions in VTSDriver are called directly from I/O tags. For example, AddRead is called by an input or status tag to request that data be sent from the driver. AddRead will call VTSRead in the device-specific communication driver to do the actual work according to the particular device’s requirements.

Note that you cannot call VTSDriver\PollAll() directly after calling AddRead(). AddRead takes a non-zero time to start, but PollAll synchronously triggers all current reads. The solution is to wait for VTSDriver\RefreshReady to become TRUE after calling AddRead. VTSDriver\RefreshReady is FALSE when read modules are being changed (in flux), and TRUE after they have stabilized on their new state. AddRead and DelRead set it FALSE, and it is then set TRUE again after the Read modules are up and running.

For a driver that saves its values on a comm failure, VTSDriver relies on that driver having a local variable or parameter named "Hold", set to TRUE if driver is holding its values.

VTSDriver and multi-server applications

If you are running a multi-server application, note the following details:

  • The subroutines VTSRead and Write will not run on client workstations.
  • I/O addresses that are configured only on a client workstation will not be read. They must be committed to the server before they will be used.
  • Data blocks are synchronized on startup.
  • Switching can occur on RecommendAlternate to provide for soft fail-overs.
  • Drivers sharing the same serial port must be in the same RPC service. The RPCService variable sets the service name for a driver instance.

Started

A flag to let you know that RPC is ready.

RPCStatus

Provides the client/server state.

AddRead

A subroutine called by I/O tags to request a read from the communication driver. Does not force a read to occur immediately.

Parameters:

Address
The address from which to get the data.
N
The number of elements to get
Value
Either a pointer to the destination for the data or an object value if VTSDriver will call Value\NewData when data changes.
Rate
The data update period, measured in seconds.

NewData

Typically called from within an I/O tag when RefreshData is called and before the data is returned. NewData will only be called when there is new data available - including invalids.

Parameters:

Address
From the original AddRead
Time
StampIn seconds, UTC
Data
The new data - either a single value or an array of values.
Attribute
Data attributes. Single value or array, matching Data.

DelRead

A module that must be called when the address changes.

Read

A module that performs a one-shot read, the data from which will be sent only to the calling server.

Write

The main subroutine used to request a write to the communication driver.

AddWrite

Obsolete. Was used to request a write to the communication driver.

PollAll

Forces all pending reads to occur immediately. This subroutine, which includes feedback, is especially useful with radio links where reads must occur when the link is established.

CoalesceRPC

Obsolete. Do not use in new code. Remove from code being upgraded to the current version of VTScada.


VTSDriver and multi-server applications

If you are running a multi-server application, you should be aware of the following details:

  • The subroutines VTSRead and Write will not run on client workstations.
  • I/O addresses that are configured only on a client workstation will not be read. They must be committed to the server before they will be used.
  • Data blocks are synchronized on startup.
  • Switching can occur on RecommendAlternate to provide for soft fail-overs.
  • Drivers sharing the same serial port must be in the same RPC service. The RPCService variable sets the service name for a driver instance.


CheckAddresses

This subroutine is not a part of the VTScada API. You must write it as part of your communications driver.

Description:

A subroutine called by a driver to check whether any of its reads need to moved, added or deleted in the existing ReadBlocks for that drive.

If so, it will rebuild reads without restarting the application or disabling and then enabling the driver tag

Returns: Nothing
Usage: Script Only.
Function Groups:
Related to:
Format: CheckAddresses(AddOnError)
Parameters:
AddOnError
Required Boolean. TRUE to force a new AddRead even if VTSGetAddr returns an error when rebuilding reads

Comments

If a driver detects a PLC configuration change or other event(*) that could change the result of a VTSGetAddr check, the driver should call CheckAddresses so that all addresses of tags using that driver are re-checked.

(*) As an example, an address that previously failed a VTSGetAddr check might now pass.

Example:

Code for this module will be specific for each driver. The following is an example only of how it might be called.

If Ready && PLCModeChanged;
[
  Driver.CheckAddresses(TRUE);
  PLCModeChanged = FALSE;
]

Where, Ready is a Boolean flag in the driver indicating that the driver has started. PLCModeChanged is a Boolean flag set in the driver's Refresh module when driver's parameter, PLCMode, changes.


Driver Diagnostic tools

The VTScada driver contains two subroutines that you should use for diagnostics, ReportTraffic and SaveCommStats.

ReportTraffic

ReportTraffic allows the driver communications stream to be viewed or logged by viewer applications. The interface is accessed through the TMObj variable within the scope of the "Driver" object value. Traffic must be manually reported by the driver tag using this subroutine.

Usage:

Script Only.

Format:

Driver\TMObj\ReportTraffic(PortName, Direction, TrafficData);

Parameters:

PortName
This should be set to a text string identifying the port tag used by the driver.
Direction
Specifies the direction of the traffic (0 = Receive, 1 = Transmit).
Traffic
Data Text string used to display the actual contents of the communications data. This string will be displayed as is and should be formatted into a legible string before being passed to the ReportTraffic Module.

The "Active" flag located within the scope of TMObj indicates whether any listener applications are monitoring the driver. ReportTraffic should only be executed if the "Active" flag is set.

IfThen(Driver\TMObj\Active,
  Driver\TMObj\ReportTraffic(ExternalPort\Name, Direction, Data);
);

SaveCommStats

Use to log statistics about the status of the communications driver. The communications driver is responsible for calling this subroutine whenever a successful or a failed communications attempt has been detected. In other words, anytime the error value of the driver is set.

Usage:

Script Only.

Format:

Driver\SaveCommStats(ErrorValue[, ErrorAddress, ErrorAfterRetry, ResponseTime, CommStatsCallerInfo]);

Parameters:

ErrorValue
Required numeric. Set to the current numerical error value of the communications driver. A value of 0 indicates success.
ErrorAddress
Optional text. The memory address that caused the error to occur.
ErrorAfterRetry
Optional Boolean. A flag indicating whether the error, or the success, occurred on a retry. A value of 1 indicates this was a retry attempt, a value of 0 indicates this was the initial attempt. Defaults to 0.
ResponseTime
Optional numeric. Expressed in seconds, this parameter specifies the time it took the I/O device to receive a command, process it, and send a response. This should only be valid if the ErrorValueParm is 0, meaning a successful communication.
CommStatsCallerInfo
Optional text. Allows the I/O driver to pass a string that can be displayed in a real time Statistics viewer. This value is not logged, and will default to the module name of the SaveCommStats caller.

The ResponseTime is defined as the time it took the I/O device to receiver a command, process it, and return a response. The I/O driver is responsible for calculating the response time. It should be calculated using the following formula:

ResponseTime = EndTime - StartTime - XmitTime - RcvTime

Where XmitTime is the time it took to transmit any data and RcvTime is the time it took to receive the data based on the number of bytes sent, the baud rate, parity, stop bits, whether there is an echo expected and whether RTS key delays are used. It is the responsibility of the communications driver to calculate the ResponseTime.

Communications driver (driver tag) statistics variables are automatically synchronized between clients and servers of the I/O Driver service by the VTScada driver module. The communications driver is not responsible for this task.


NoData

This subroutine is not a part of the VTScada API. You must write it as part of your communications driver.

Description: | Used in combination with a VTSRead module to invalidate data due to errors such as a comm failure
Returns: | Nothing
Usage: | Script Only.
Function Groups: |
Related to: | RefreshData
Format: | CallBackObj\NoData(Hold, Attribute)
Parameters: |
Hold

This should be set to the driver's Hold parameter.

If FALSE (default), the values of the input tags will be invalidated.

If TRUE, the values of the input tags will be left as is but will be marked with a stale attribute.

Attribute

A value that indicates why the data is being invalidated.

Defaults to the communication failure attribute as SetBit(0, \#DATA_ATTR_COMMFAIL, TRUE).

Comments:

This function should be called whenever there is a reason to invalidate the input values. The most common reason for this is when a communicate failure occurs.

{ Bit numbers for logging data attributes }

#NUM_DATA_ATTR_BITS = 12

The number of bits in data attributes

#DATA_ATTR_MANUAL_DATA = 00

The value was from the tag's ManualData parm

#DATA_ATTR_MANUAL_ENTRY = 01

The value was manually entered

#DATA_ATTR_EDITED_DATA = 02

The historical value was manually edited

#DATA_ATTR_QUESTIONABLE = 03

The tag was marked as questionable

#DATA_ATTR_STALE_DATA = 04

The value was reported as stale by VTSDriver

#DATA_ATTR_IMPORTED = 05

The value was imported from a CSV file

#DATA_ATTR_COMMFAIL = 06

The driver experienced a comm failure

#DATA_ATTR_QUALITY = 07

The tag has marked the value as unreliable

#DATA_ATTR_DRIVER_COMMFAIL = 08

The PLC reported a downstream comm failure

#DATA_ATTR_DRIVER_QUALITY = 09

The PLC reported the value may be unreliable

#DATA_ATTR_DRIVER_OVERRIDDEN = 10

The PLC reported the value was overridden

#DATA_ATTR_DRIVER_NODATA = 11

The PLC reported there is no data available

Example:

  If CommFail Next;
  [
   { Clear the data if we experience a communication failure }
    CallbackObj.NoData(Hold, SetBit(0, \#DATA_ATTR_COMMFAIL, TRUE));
  ]


RefreshData

Description: | Used in combination with a VTSRead module to delivering data read from the I/O device
Returns: | Nothing
Usage: | Script Only.
Function Groups: |
Related to: | NoData | AddRead | DelRead
Format: | CallBackObj\RefreshData(TimeStamp, NewData, Attribute, QueueObj, PropagateOnlyOnDataChange)
Parameters: |
TimeStamp

Optional. If invalid, the system uses current time in UTC to timestamp the data. Otherwise, may be either of the following:

  • A single timestamp value, expressed in number of seconds since January 1st 1970 UTC. This value will be applied to each element of NewDta.
  • An array, having the same structure as NewData. Each data point will be assigned its corresponding timestamp from the timestamp array.

For event driven reads, you may wish to process only the data from a single address, rather than from a full read block. You can achieve this by setting all the TimeStamp array elements to invalid except for the one matching the element of NewData which you want to process.

Note that invalid timestamps in a timestamp array have special meaning. An invalid timestamp element indicates that the corresponding data has not changed. This enables drivers to pass back partial updates. This feature is independent of the PropagateOnlyOnDataChange option.

NewData

This is the value read from the I/O device. It may be either a simple array, or an array of arrays having the same size as the MemAddress array used in the VTSRead function.

If a simple array, there will be one element for each address. The array of arrays option is generally used for returning historical data for a given address.

Calling Refresh data with the NewData parameter specified as an array of arrays will work only with Analog Status, Digital Status and Pump Status. It will not work with Analog Input, Digital Input, and any tag not specifically coded to handle an array of results being passed into newData().

Attribute

Optional. No default. May be a single value, which will be applied to all elements of NewData if that is an array, or may be an array of attributes that gets assigned to the corresponding array of data.

If an array, the size and arrangement of the array must be the same as NewData.

QueueObj

Obsolete. Should be set to Invalid.

PropagateOnlyOnDataChange

Flag that when set true, will prevent data from being propagated through RPC or to tag\NewData() unless the value of NewData or Attributes has changed since the last time RefreshData was called. Defaults to TRUE.

Historical reads, whether by array or array-of-array, are expected to set PropagateOnlyOnDataChange to FALSE to disable the automatic filtering. One can interpret this option as 'automatically detect and ignore data which has not changed'.

Comments

The data type and structure can vary for the three parameters, NewData, TimeStamp and Attribute. If the driver will read blocks of history data, you will need to take additional steps.

Invalid data is accompanied by a valid timestamp:

TimeStamp[i] = Some Valid Time;
Data[i]             = Invalid;

Missing Data is indicated by an invalid timestamp:

TimeStamp[i]  =  Invalid;

Currently, for the entire array of data to be written to the Historian the History address must be used in the I/O tag.

Block history

When reading historical data, an array of arrays may optionally be used, where each element of the NewData array will contain another array which must be sized for the number of data points that are being returned for the matching MemAddress. This holds true even if there is only one value to return for each I/O address.

Note: the IO tag supports accepting arrays.

This a special mode used only for input tags that can support the different read result. These are, the I/O, AnalogStatus, DigitalStatus and the PumpStatus, all of which have a 'History Address' parameter. The reading of block history has little to do with VTSDriver itself since VTSDriver simply passes through whatever the driver provides. The contract that standard status tags expect is that a block of history will be passed to NewData() as an array, and that the Timestamp parameter will be a matching array with corresponding timestamps. If Attributes are present, then attributes for block history should be in an array corresponding to the Data/Timestamp arrays. It is important that drivers pass block history data in the form that VTScada status tags support.

If the block of history records is being passed in an array, then the oldest timestamp must be at index 0. The restriction that the block history be in a certain order is due to the Historian, which logs exactly what it is given without modification (by design). Having timestamps reversed means that out-of-order history is written, which will slow performance. If the driver’s protocol requires block history with the newest item first, then that driver should swap the order before passing it along.

Example 1:

Given MemAddress with two addresses, "Addr1" and "Addr2" and data for Addr1 = 1.23 and data for Addr2 = 2.34, you might do something like:

 { Make a data array }
Data = New(2);
 { Add first element }
Data[0] = New(1);
Data[0][0] = 1.23;
 { Add second element }
Data[1] = New(1);
Data[1][0] = 2.234;

{ Make it So }
CallBackObj\RefreshData( Invalid, Data, Invalid );

Example 2:

Multiple Data/Timestamp Value Pairs for each item in MemAddress, no Attributes

Given MemAddress with two addresses, "Addr1" and "Addr2" and data/timestamps for
Addr1 = 1.23/2009-08-01 11:23, 1.24/2009-08-01 11:24 and data for Addr2 = 2.34/2009-08-01 11:21, 2.35/2009-08-01 11:22
you might do something like:

{ Make a data array }
Data      = New(2);
TimeStamp = New(2);

{ Add first element}
TimeStamp[0]    = New(2);
Data[0]         = New(2);
Data[0][0]      = 1.23;
TimeStamp[0][0] = ConvertTimestamp(
                    \ODBCManager\ConvertToVTSTimeStamp(
                       "2009-08-01 11:23"),
                       "US Eastern Standard Time", 0,
                       "GMT Standard Time" );
Data[0][1]      = 1.24;
TimeStamp[0][1] = ConvertTimestamp(
                    \ODBCManager\ConvertToVTSTimeStamp(
                       "2009-08-01 11:24"),
                       "US Eastern Standard Time", 0,
                       "GMT Standard Time" );

{ Add second element}
Data[1]      = New(2);
TimeStamp[1] = New(2);

Data[1][0]      = 2.34;
TimeStamp[1][0] = ConvertTimestamp(
                    \ODBCManager\ConvertToVTSTimeStamp(
                       "2009-08-01 11:21"),
                       "US Eastern Standard Time", 0,
                       "GMT Standard Time" );
Data[1][1]      = 2.35;
TimeStamp[1][1] = ConvertTimestamp(
                    \ODBCManager\ConvertToVTSTimeStamp(
                       "2009-08-01 11:22"),
                       "US Eastern Standard Time", 0,
                       "GMT Standard Time" );

{ Make it So }
CallBackObj\RefreshData( TimeStamp, Data, Invalid );


VTSGetAddr

This subroutine is not a part of the VTScada API. You must write it as part of your communications driver.

Description: | Convert the Address parameter (specified in the "Address" field for tags such as analog and digital inputs and outputs) to a value that uniquely classifies the address into a block that can be coalesced by VTScada.
Returns: | Numeric
Usage: | Script Only.
Function Groups: |
Related to: |
Format: | VTSGetAddr(Address, MemAddr, BitNum, Info1, Info2, Info3, DataType, Read, Rate);
Parameters: |
Address
The raw address from the I/O tag's Address field. This is often a text string, but may be a numeric value. The contents of this parameter are driver-specific. It is the job of this module to interpret the address.
The data type to read from or write to is usually implied by the address. If it is not, the strings shown in the following table may be appended to the address (without spaces) to force the data to be interpreted as a specific type (e.g. "40001/UDWord").
If you intend the address to be numeric, you should ensure this by casting it to a numeric value.
Suffix | Meaning
/ABFloat | Allen-Bradley PLC/3 Floating Point (4 bytes) (Used for Allen-Bradley exclusively)
/AB5Float | Allen-Bradley PLC/5 Floating Point (4 bytes) (Used for Allen-Bradley exclusively)
/BCD2 | 2-digit (1 byte) Binary Coded Decimal
/BCD3 | 3-digit (2 bytes - lowest 12 bits) Binary Coded Decimal
/BCD4 | 4-digit (2 bytes) Binary Coded Decimal
/Bit | A bit number
/Double | IEEE Double Precision Floating Point (8 bytes)
/Float | IEEE Single Precision Floating Point (4 bytes)
/SByte | Signed Byte
/SDWord | Signed 32-bit Integer
/Sword | Signed 16-bit Integer
/UByte | Unsigned Byte
/UDWord | Unsigned 32-bit Integer
/UWord | Unsigned 16-bit Integer
MemAddr

Assists the VTScada code in creating efficient driver read and write calls. PLC I/O locations with different MemAddr values and the same values for the Info1, Info2, and Info3 parameters are coalesced into the same read block, provided they are within VTSMaxBlock, or the return of VTSMaxBlock(Info1, Info2, Info3, DataType) values of each other.
It is the responsibility of the VTSGetAddr module to set this variable to the correct data type and value.

The MemAddr variable should be one of two data types:

  • A pointer to an integer value. If so, it must be set by dereferencing (using a * before the variable name) before being assigned a value.
  • A pointer to a string. Cast MemAddr to text if the driver does not use integers for a address or if you need to parse the address as text.

VTScada driver code behaves differently, depending on the data type of the variable's contents. This variable is usually a pointer to an integer. If the value is to be a number, make sure a text string is not returned if the value was extracted from the Address string.

If a driver does not use integers to denote an address, return the text string in the MemAddr parameter. The VTSRead module and the VTSWrite module are passed an array of strings rather than a memory starting address. This means, if you set MemAddr to a text value, such as "100" the VTScada code interprets this as a text address rather than a numeric one. This means that the coalescing will not pay any heed to the actual value of the address, but will simply pass an array of text strings to the VTSRead or VTSWrite in the MemAddr parameter.

BitNumber
A pointer to the integer bit number within the memory address specified by MemAddr. This value may be set to invalid if there is no bit value.
Info1, Info2, Info3
Pointers to values that are used by the VTScada code to determine which addresses can be coalesced into a larger read block. These parameters are also passed to the VTSRead and VTSWrite subroutines. Any values that are not required should be set to "0" (i.e. they must be a valid value). These values are typically set to such things as file type or data area. Any differences between the values of the three Info parameters and those of another Address will prevent those addresses from being coalesced (i.e. grouped into the same read request).

Info1 must be a number. A string value will not work. If your code sets Info1 to a string value, the SetData module in VTSDrvr.web will not work correctly, and client computers will not display the results of the driver server computer's read commands. For example, an analog input that is drawn on the screen will always have invalid contents if the Info parameters are set to strings (such as "abc"), rather than a number.

DataType
A pointer to a value that holds the data type preferred for the specified address. If left invalid the default data type will be 2 (16-bit unsigned integer). This value will be overridden by the explicit data type specified as an appended string to the address.

The MemAddr, BitNum, Info1, Info2, Info3, and DataType parameters are pointer values, and must be set by dereferencing them before assigning the values (i.e. using an asterisk "*" before the variable name (please refer to "Pointers" for further details on pointers and dereferencing).

Read
Specifies whether the address will be used for a Read or a Write command. If true, the address is used for reading data, otherwise it is used for writing data. Most drivers ignore this parameter since there is usually no difference in the returned values for reads and writes.
Rate
A pointer to the scan rate of the I/O device. This may be an Invalid pointer.

Comments:

The VTSGetAddr subroutine must return an error code. If the return value is not 0, the VTScada code assumes that there is an error in the address and it will not include that tag when coalescing the block.

You are advised to use unsigned data over signed data for the default data type as it is much easier to work with via ArrayToBuff and BuffToArray


VTSMaxBlock

This subroutine is not a part of the VTScada API. You must write it as part of your communications driver.

  • If the maximum block size is a constant, regardless of the data type or address, then VTSMaxBlock can be declared as a variable and set to a numeric value.
  • If supplied as a subroutine then, based on the address and data type information, this module should return the maximum amount of data that can be handled in a single read or write. It is your job to write this subroutine as part of your driver, using the following format:

Format:

Description: | VTSMaxBlock determines the maximum block size that is coalesced into a VTScada read or write. This can be either a subroutine or a variable.
Returns: | Nothing
Usage: | Script Only.
Function Groups: |
Related to: | DelRead
Format: | VTSMaxBlock(Info1, Info2, Info3, DataType);
Parameters: |
Info1, Info2, Info3

These are pointers to values that are used by the VTScada code to determine which addresses can be coalesced into a larger read block. These parameters are also passed to the VTSRead and VTSWrite subroutines. Valid values must be supplied for all three, therefore any values that are not required should be set to "0".
These values are typically set to such things as file type or data area. Any differences between the values of the three Info parameters and those of another Address will prevent those addresses from being coalesced into the same read request.

The value of Info1 must be numeric. If your code sets Info1 to a string value, the SetData module in VTSDrvr.WEB will not work correctly and client computers will not display the results of the read commands.

DataType
A pointer to a value that holds the data type preferred for the specified address. This data type may be left invalid if the VTSRead and VTSWrite subroutines ignore it. If left invalid the default data type will be 2 (16-bit unsigned integer). This value will be overridden by the explicit data type specified as an appended string to the address. The DataType is what is passed to the VTSRead and VTSWrite subroutines from VTSGetAddr. The appended data type (refer to the table in the Address parameter section above) specifies how the data is to be interpreted after it is read from the I/O device if this is to be different from the DataType returned by VTSGetAddr. The VTSRead and VTSWrite modules do not see the value of the appended data type string.

Comments

This subroutine is used by nearly every communication driver and is required. Without specify limits, your configuration may work initially but will eventually break packet size limits.


VTSRead

This subroutine is not a part of the VTScada API. You must write it as part of your communications driver.

Description: | The VTSRead module is run continuously to read data from the I/O device. It is called from the VTSDriver code.
Returns: | Nothing (Data returned via parameters)
Usage: | Script Only.
Function Groups: |
Related to: | DelRead
Format: | VTSRead(Trigger, Data, N, MemAddr, BitNumber, Info1, Info2, Info3, DataType[, CallBackObj]);
Parameters: |
Trigger
A logical value that, when true, requests that the VTSRead module scan the I/O device for data.
Data

Do not use in new code. Instead, use \CallBackObj\RefreshData()

In legacy applications, this was an array into which the read data is to be placed.

N
The number of values to read from the I/O device. If MemAddr is an array of strings, then N is set to the size of the array.
MemAddr
Assists VTScada in creating more efficient driver read and write calls. PLC I/O locations with different MemAddr values and the same values for the Info1, Info2, and Info3 parameters are coalesced into the same read block, provided they are within VTSMaxBlock, or the return of VTSMaxBlock(Info1, Info2, Info3, DataType) values of each other.
It is the responsibility of the VTSGetAddr module to set this variable to the correct data type and value. Note that the data type of the MemAddr parameter in VTSGetAddr affects the data type of this parameter. If the data type is a string in VTSGetAddr, then this parameter will be an array of strings.
BitNumber
A pointer to the integer bit number within the memory address specified by MemAddr. This value may be set to invalid if there is no bit value.
Info1, Info2, Info3
Are variables (not pointers), that are used by the VTScada code to determine which addresses can be coalesced into a larger read block. These parameters are also passed to the VTSGetAddr and VTSWrite subroutines. Any values that are not required should be set to "0" (i.e. they must be a valid value). These values are typically set to such things as file type or data area. Any differences between the values of the three Info parameters and those of another Address will prevent those addresses from being coalesced (i.e. grouped into the same read request).

Note that Info1 must be a number: a string value will not work. If your code sets Info1 to a string value then the SetData module in VTSDrvr.WEB will not work correctly and client computers will not display the results of the driver server computer's read commands. For example, an analog input that is drawn on the screen will always have invalid contents if the Info parameters are set to strings rather than a number.
DataType
A pointer to a value that holds the data type preferred for the specified address. This data type may be left invalid if the VTSRead and VTSWrite subroutines ignore it. If left invalid the default data type will be 2 (16-bit unsigned integer).
This value will be overridden by the explicit data type specified as an appended string to the address. The DataType is what is passed to the VTSRead and VTSWrite subroutines from VTSGetAddr. The appended data type (refer to the table in the "Address" parameter section above) specifies how the data is to be interpreted after it is read from the I/O device if this is to be different from the DataType returned by VTSGetAddr. The VTSRead and VTSWrite modules do not see the value of the appended data type string.
CallBackObj
Optional, but recommended. An object value whose scope is used to call RefreshData. (see: Data Propagation) RefreshData is the recommended method for propagating data.
If using RefreshData to propagate data, then VTSRead should not also update the Data Array parameter on its own.
VTSRead must return an object (usually Self()) that includes the three mandatory variables: Counts, ErrorCounts and Error.

Comments:

A VTSRead should return data for one or more addresses as contained in the array parameter, MemAddress. Data is returned by calling CallBackObj\RefreshData as described in the topic, Data Propagation. An example is provided at the end of the parameter description.

VTSRead must increment either Counts or Error Counts before processing new data.

Example:

<
VTSRead
(
  Trigger{ Will do read on positive edge           };
  Data{ Array to put the result into               };
  N{ The number of values to read                  };
  MemAddress{ Address to read                      };
  BitNum{ Bit to read / not used here              };
  Info1{ Info1                                     };
  Info2{ Info2                                     };
  Info3{ Info3                                     };
  DType{ Data type used for read                   };
  CallBackObj{ Object value where RefreshData is located };
)
[
  Error        = 0;
  Counts       = 0;
  ErrorCounts  = 0;
  StartTime            { Request start time              };
  ElapsedTime          { Request elapsed time            };
  Tries        = 0     { Number of attempts on modem     };
]
Main [

  If Trigger;
  [
    ResetParm(Self(), 1) { Reset the trigger since does not feed back
                           from the driver };

      { Process data according to the protocol }
    . . .

      { error in data, increment ErrorCounts },
    IfElse((AValid(TimeArray[0], ArraySize(TimeArray, 0) !=  ArraySize(TimeArray, 0)) ||
           (AValid(DataArray[0], ArraySize(ValueArray, 0) !=  ArraySize(ValueArray, 0)),
      ++ErrorCounts,
    {Else - no errors in data, increment Counts and send data}
      Execute(
        ++Counts,
          { Send data and timestamps }
        CallBackObj\RefreshData(TimeArray,ValueArray,Invalid,Invalid)
      ) {End Execute},
    ) {End IfElse};

    Return(Self);
  ]
]
>


VTSWrite

This subroutine is not a part of the VTScada API. You must write it as part of your communications driver.

The VTSWrite module is launched by the VTSDriver code to write a block of values to the I/O device. Its code is very similar to that of the VTSRead module with the same number of parameters.

Format:

Description: | The VTSWrite module is launched by the VTSDriver code to write a block of values to the I/O device.
Returns: | Nothing
Usage: | Script Only.
Function Groups: |
Related to: |
Format: | VTSWrite(Trigger, Data, N, MemAddr, BitNumber, Info1, Info2, Info3, DataType);
Parameters: |
Trigger
A logical value that, when true, will request that the VTSWrite module send the data to the I/O device.
Data
An array where the written data will be read.
N
The number of values to write to the I/O device. If MemAddr is an array of strings, then N indicates the size of the array.
MemAddr
Assists VTScada in creating more efficient driver read and write calls. PLC I/O locations with different MemAddr values and the same values for the Info1, Info2, and Info3 parameters are coalesced into the same write block, provided that they are within VTSMaxBlock, or the return of VTSMaxBlock(Info1, Info2, Info3, DataType) values of each other.
It is the responsibility of the VTSGetAddr module to set this variable to the correct data type and value. The data type of the MemAddr parameter in VTSGetAddr affects the data type of this MemAddr parameter. If the DataType is a string in VTSGetAddr, then this parameter will be an array of strings.
BitNumber
A pointer to the integer bit number within the memory address specified by MemAddr. This value may be set to invalid if there is no bit value.
Info1, Info2, Info3
Are variables (not pointers) that are used by the VTScada code to determine which addresses can be coalesced into a larger read block. These parameters are also passed to the VTSRead and VTSWrite subroutines. Any values that are not required should be set to "0" (i.e. they must be a valid value). These values are typically set to such things as file type or data area. Any differences between the values of the three Info parameters and those of another Address will prevent those addresses from being coalesced (i.e. grouped into the same read request).

Note that Info1 must be a number: a string value will not work. If your code sets Info1 to a string value, the SetData module in VTSDrvr.WEB will not work correctly, and client computers will not display the results of the driver server computer's read commands. For example, an analog input that is drawn on the screen will always have invalid contents if the Info parameters are set to strings rather than a number.
DataType
A pointer to a value that holds the data type preferred for the specified address. This data type may be left invalid if the VTSRead and VTSWrite subroutines ignore it. If left invalid the default data type will be 2 (16-bit unsigned integer). This value will be overridden by the explicit data type specified as an appended string to the address. The DataType is what is passed to the VTSRead and VTSWrite subroutines from VTSGetAddr. The appended data type (refer to the table in the Address parameter section above) specifies how the data is to be interpreted after it is read from the I/O device if this is to be different from the DataType returned by VTSGetAddr. The VTSRead and VTSWrite modules do not see the value of the appended data type string.

Comments

The VTSWrite module will usually be slain immediately after the write is completed.

VTSWrite must increment one of two mandatory internal variables each time it is called. Either "Counts" if the write was successful or "ErrorCounts" otherwise.

Example

The code for VTSWrite might look like:

<
VTSWrite
(
  TriggerParm{ Will do read on positive edge           };
  Array{ Array to put the result into                  };
  N{ The number of values to read                      };
  MemAddress{ Address to read                          };
  BitNum{ Bit to read                                  };
  Info1{ Info1 - not used                              };
  Info2{ Info2 - not used                              };
  Info3{ Info3 - not used                              };
  DataType{ Data type used for read - uses standard types };
)
[
    { Trigger is PUBLIC and is referenced by VTSDriver }
      Trigger= 1{ TRUE when initial trigger set        };
  Error        = 0;
  Counts       = 0;
  ErrorCounts  = 0;
  StartTime         { Request start time                     };
  ElapsedTime       { Request elapsed time                   };
  Tries        = 0  { Number of attempts on modem            };
  WriteActive  = 0  { TRUE when the write has been triggered };
]

Main [

  If Trigger || TriggerParm;
  [
      { Process the data according to the protocol }
   . . .

{ Reset the triggers }
    ResetParm(Self(), 1);
    Trigger = 0;
  ]
]
>


Rules for Writing a Communications Driver

  • Communication drivers are tags and must be built as such.
  • The module must contain a variable named "Driver".
    This variable must not have a value set in the module. The VTScada loader sets it before the module starts.
  • The module must include a variable named "Ready".
    The driver tag code must set this to true when the driver tag is ready to be used.
  • Ready must not be set to true before:
    • The variable Root is set to some object value (usually Self() )
    • The variable RPCService is set.
    • Before Driver\Started becomes true.
    • Before Driver\RPCStatus is 2 (server) or 1 (client)
Ready = Valid(Root) && Valid(RPCService) && Driver\Started &&
        (Driver\RPCStatus == 2 || Driver\RPCStatus == 1);
  • If the driver tag being developed has other constraints they must also be added.
  • For tags that do I/O using a communication driver, the driver tag passed in as a parameter must first be converted to an object value. This object value must be used to launch a copy of any read requests required. This is done with the script code like:
If Watch(1, IODevice, Address, ScanRate) &&
           (ValueType(IODevice) == 4 { Text } ||
            Valid(IODevice\Driver) { Driver has started });
[
  IfThen (ValueType(IODevice) == 4 { Text string },
     { Convert text driver name to the object value of }
     { that driver                                  }
    IODevice = Scope(\Code, IODevice)
  );
    { Save a copy of the driver instance for next change }
  Driver = IODevice\Driver;
    { Delete any previous read requests }
  Driver\DelRead(&RawValue);
    { Start new request for the data }
  Driver\AddRead(Address,
                 1 { # of Elements/Bytes },
                 &RawValue,
                 ScanRate);
]

The Address and ScanRate are typically parameters to the tag template module. The Driver variable must be defined in the module.

  • Writes to the I/O Device are done by executing a call to the Write module in the driver within a script. The code might look like:
 Driver\Write(Address, Length { # of elements/bytes }, Data);
  • A Value variable is common for most tags. For drivers, this value is an error code where 0 indicates no error. Value should be set to the Error from VTSRead/VTSWrite, and must be set on the current primary I/O server.
  • All drivers must have a variable called Drivers with a class of GROUPS. (not to be confused with "Driver" in point 1). This should also be a shared variable to conserve RAM. This makes the tag a part of the Drivers group and is necessary to permit the tag to show up in driver tag selection lists and to allow it to set its "Driver" variable before the tags use it.
  • Any driver tag that should share the same RPC service for all instances, should define a constant named "RPCService" with the default value being the name of the service. This name should typically be the name of the driver tag. This will force all instances of the driver tag to share the same server. It will dramatically improve the startup performance of systems that have a large number of instances of the same driver tag type, such as SCADA systems with a large number of RTU’s. An alternative option is possible if the RPCService variable does not have a default value. The driver tag may elect to set this variable based upon some run-time condition (such as a configuration file setting). If the variable exists, it must be set prior to the Driver\Started variable being set in the VTSDriver code.
  • If the driver tag uses a serial port, it is a good idea to flush the input buffer before any data is sent. The mechanism that VTScada uses to add and delete read/write commands is such that a read or write that is in progress could be removed from the "queue" in the middle of processing. This means that it is possible that a read or write command could send its data but then be removed from the communications loop before the response comes back. The next read or write command would then collect the data, if the serial buffer was not emptied. (Refer to the function, SerRcv, for one mechanism to empty the input buffer).
  • Do not create a separate module to serve as a low level driver
  • Do not declare the variables that are added by diagnostics.
  • Add the driver tag to the groups: Trenders, Loggers and Numeric, Drivers.


Driver Module Instance Object Value

The object value of a driver module instance can be used to provide information about how that particular driver is running. This is done by accessing the public variables described in the following table.

Counts | The number of successful communications since starting. Counts is a Long variable.
ErrorCounts | The number of errors encountered since starting. ErrorCounts is a Long variable.
SilentErrorCounts | Used only on reads and only by drivers that can have managed sessions or poll for exception, unsolicited data, etc. Indicates that the read could not happen, but this is not necessarily an error. Used to suppress VTSDriver from changing the driver's Value parameter.
Error

The error code number of the current communication attempt. Error is reset to "0" when the error clears. Error codes follow:

Error Description

0

No error

1

Not executable in RUN mode

2

Not executable in MONITOR mode

3

Not executable with PROM mounted

4

Address over (data overflow)

B

Not executable in PROGRAM mode

C

Not executable with PROM mounted

D

Not executable in LOCAL mode

10

Parity error

11

Framing error

12

Overrun

13

FCS error (checksum)

14

Format error (parameter length error)

15

Entry number data error (parameter error, data code error, data length error)

16

Instruction not found

18

Frame length error

19

Not executable (due to unexecutable error clear, non-registration of I/O table, etc.)

20

I/O table generation impossible (unrecognized Remote I/O unit, word over, duplication of Optical Transmitting I/O unit)

80

Incomplete response to WRITE

81

Bad serial port parameters

82

Serial port already used

83

FCS error (checksum)

84

No response from PLC (timed-out)

85

Wrong PLC station address responded

86

TYPE parameter out-of-range

87

Garbled/incomplete message

A0

Aborted due to parity error in transmit data

A1

Aborted due to framing error in transmit data

A2

Aborted due to overrun in transmit data

A4

Aborted due to format error in transmit data

A5

Aborted due to entry number data error in transmit data

A8

Aborted due to frame length error in transmit data

B0

Not executable because the program area is not 16K
LastError | The error code number of the last error encountered by any communications attempt. LastError is not reset to zero when the error clears.
TimeStamp | The time (in seconds) of the last successful communication since midnight. TimeStamp is a floating-point variable.
DateStamp | The date of the last successful communication since January 1, 1970. DateStamp is a long variable.
ErrorTime | The time of the last error encountered in any communication attempt in seconds since midnight. ErrorTime is a floating-point variable.
ErrorDate | The date of the last error encountered in any communication attempt in days since January 1, 1970. ErrorDate is a Long variable.
ErrorOwner | An object variable that holds the object value of the read or write statement that encountered the most recent error.
SCounts[255] | An array of Counts values, one for each Omron PLC.
SDateStamp[255] | An array of DateStamp values, one for each Omron PLC.
SError[255] | An array of Error values, one for each Omron PLC.
SErrorCount[255] | An array of ErrorCounts values, one for each Omron PLC.
SErrorDate[255] | An array of ErrorDate values, one for each Omron PLC.
SErrorTime[255] | An array of ErrorTime values, one for each Omron PLC.
STimeStamp[255] | An array of TimeStamp values, one for each Omron PLC.
Version | A text variable that is set to the version number of the driver when the driver is started.

For example, if the object value of the driver module was assigned to an object variable called, "Driver" then to display any errors generated by any reads or writes using this driver, use an expression similar to the following example:

Output(0, 0, 1, 0, 0, Driver\Error, 15, 0, 0, 0, 0) { Show the current error code }


Error Checking

Error statistics should be examined, and errors recovered from, if possible.

Communication failures may occur as a result of human error (such as an unplugged cable) or hardware error (such as a power failure or noise in the communication channel). A communication link may not occur on the first attempt, but may after repeated attempts. If it does not, the error should be reported so that the operator can fix it.

When reliable communications are being used, it will be necessary to wait for some type of acknowledgment from the receiver to ensure the message sent was received. In RS-232 serial communications, an echo of data that was received may be sent back. In Ethernet communications, an acknowledgment (ACK) or a negative acknowledgment (NACK) packet may be sent to indicate whether the packet was received. Similarly, when receiving a packet, it may be necessary to let the transmitter know a message has been received.

The protocol for the packet may use built-in error checking, such as a checksum. If this is the case, the validity of the message can be verified upon receipt, and the message discarded if an error occurred on the communication channel distorting the data.

Another potential issue exists if the driver uses a serial port. The mechanism that VTScada uses to add and delete read/write commands is such that a read or write that is in progress could be removed from the queue in the middle of processing. This means that it is possible that a read or write command could send its data, but then be removed from the communications loop before the response is received. The next read or write command would then collect the data if the serial buffer was not emptied. Therefore, it is a good idea to flush the input buffer before any data is sent.


Maintaining Statistics

VTScada communication drivers keep at least the following statistics:

LastError | The error code number of the last error encountered by a communications attempt. Unlike the Value variable, LastError is not reset to zero when the error clears.
TimeStamp | The time of the last successful communication, measured in the number of seconds since midnight.
DateStamp | The date of the last successful communication measured in days since January 1, 1970.
ErrorTime | The time the last error occurred, measured in seconds since midnight.
ErrorDate | The date of the last error, measured in days since January 1, 1970.
ErrorOwner | An object variable that holds the object value of the read or write statement that encountered the most recent error.
SCounts, SDateStamp, SError, SErrorCounts, SErrorDate, SErrorTime, STimeStamp | These are arrays of 255 elements, with one element for each possible driver instance. The elements contained in the array correspond to the name of the array.
Version | A text variable that is set to the version number of the driver when the driver is started.

In addition to the statistics that the driver maintains, the VTSRead module maintains statistics for each read attempt that is returned to the VTSDriver module (in VTSDrvr.web). The three statistics that must be returned when VTSRead is finished are:

  • Counts: The number of successful communications since the driver started.
  • ErrorCounts: The number of errors since the driver started.
  • Error: The error code number of the current communication attempt. Error is set to zero when the error clears.


Common Driver Widgets

In order for operators with little or no programming knowledge to see if problems may be occurring with a driver, and acquire some insight into what the problems are, graphics are required for VTScada communication drivers. These graphics can be drawn anywhere on the pages of the VTScada application.

The ShowStats, ShowComm, CommIndicator, SetStats, and ErrorMsg widgets are used for graphical display. ShowStats, ShowComm, and CommIndicator are graphics modules, while SetStats and ErrorMsg are support modules that provide the statistics and error messages that are displayed. All of these modules can be customized to suit each individual type of I/O device. For example, additional statistics and information can be included in the ShowStats and ShowComm windows, however, the standard displays are generally sufficient.


Debugging and Testing Communications Drivers

There are several tools that may be used for debugging and testing a communication driver, including monitoring software such as WireShark®, the VTScada Source Debugger, and simulators. These tools are described briefly here.

Monitoring Software

This software allows you to view all traffic across the computer's serial or TCP/IP port. You may then verify if the information being sent and received meets expectations.

VTScada Source Debugger

Use this tool to watch variables for value changes, insert breakpoints, and view module content and code.

I/O Device Simulators

Actual I/O device hardware may not be available to test with the communication software. On such occasions, it is helpful to write or obtain a simulator to emulate the I/O device with which communication is desired. A script application written to use the I/O device's protocol and imitate the I/O device's actions can be run in VTScada at the same time as the driver tag. This enables testing of the communication driver without having the I/O device prior to installation on site.


Windows, Pages, and Graphics

Coordinates for graphics are always given in the form (Left, Bottom, Right, Top), where numbers are relative to the top left of the container holding the graphic. For example, a box with coordinates (0, 10, 10, 0) has one corner at the upper left of the containing window (0, 0) and the other corner ten pixels down and ten pixels to the right (10,10). While it is standard practice to specify a Right value that is greater than the Left, and a Bottom value that is greater than the Top (coordinates increase down from the top left), VTScada will not mirror the object if you swap the numbers. This is not to say that the order doesn't matter. Stay with the convention of (Left, Bottom, Right, Top) and you will reduce confusion.

The following tools are available to hold your user-interface elements.

Page

The standard container for user-interface elements in a VTScada application. Although created using the Idea Studio, you can exercise extensive control over the appearance and behavior of pages through code.

Widget

Also created using the Idea Studio using exactly the same tools as those used for a page. A widget is very similar to a page except that menu links can be created only to pages, not to widgets. Widgets are meant to be displayed within pages. Additionally, widgets can be linked to tags but pages cannot. Both widgets and pages may have parameters.

Window

A container for graphics. For example, pages are displayed within a window that is launched and maintained by the VTScada display manager. You can create your own windows, over which you exercise complete control. See: Window

4BtnDialog

A graphics statement that opens a window containing an OK/Cancel type of dialog. Use this rather than a page or window if your goal is to prompt the operator or request confirmation. See: 4BtnDialog

An example of a call to the window function can be found in the AppRoot.src file of every new script application.

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);
]

The Window() function specifies the size, location, and attributes of the window when it is created. The seventh parameter (Graphics() in this example) is a call to start another module. Any graphic statements that appear in the called module or in any of its child modules are drawn on the screen created by the Window function.

Icons

If the close icon is enabled on the window (via the Style parameter, 8th bit), care must be taken to ensure that when the user selects it, the action you desire occurs, as by default, clicking the close button stops your application; you may prefer to close the window but keep the application running. To help you specify the action you wish to occur when the close button is clicked, the WindowClose() function is provided.

For example, you may wish to define a "Cancel" button that will close the window, as well as having the close button enabled:

If ZButton(10, 220, 110, 200, "Cancel", 2) || WindowClose(Self()) Done;
[
  ...
  winOpen = 0 { Assuming winOpen was used as the 11th parameter of Window function };
]

When either this cancel button or the close button is selected, the script above will execute, causing the variable that is in the Window function's Enable parameter to become "0", thereby closing the window. Notice that the WindowClose function (as used above), does not actually close the window; rather it checks to see if the user is trying to close the window with the window close button. It returns a true value when this is the case, and the resulting execution of the script closes the window. This example therefore, does not conflict with the caution in the following topic about overloading a PageClose button.

Note that having a WindowClose(Self) call is not always enough. The Window call should always set bit 19. Otherwise, if the user hits the X before the WindowClose has had a chance to run (for example, if the object running in the window has an Init state that is taking time to collect some data), then the window will close as if no WindowClose statement is running. This may cause other problems.


Working with Pages

Related Functions:

Window

Graphics

Display Manager Properties

You can change the appearance and behavior of the pages in your application. There are two levels of access to the characteristics of pages: at the developer's level, page characteristics are set using the Idea Studio and its associated tools. At the programmer's level, page characteristics can be set within a page's source file. Developer tools are described elsewhere in this guide. (Display Building (Idea Studio))

The code for user-created widgets is very similar to that of page modules, and therefore much the following information also applies to them.

Where to find the code for your pages:

For each page, there is a resource file stored within your application in a folder named, "Pages". These are user-editable copies but note that any change must be imported into the application by an authorized user before it will become part of the running application. The file is named after the initial title of the page and have the extension ".SRC". Changes to the page title do not affect the name of the file.

The code of a page is a standard VTScada module Closed A collection of states, scripts, variables, parameters, comments and possibly other modules, all of which make up a VTScada program. Modules are separate tasks that run simultaneously in an application. Behind every page is a module and behind every tag on that page is an instance of another module (usually with submodules controlling separate tasks)., following all the rules of the VTScada language. It may begin with an optional set of parameters.

(
   parmName <:"description text":> data_type;
)

Following the parameters (if any) will be the variable declarations.

[
   Title = "Overview";
   Color = 89;
   ...
]

Most pages will have one state, named "Main" by default when the page is created within the VTScada development tools. Typically, this is the only state in a page.
Pages are called modules that return their object value. Therefore all states within the page that display the user interface must include a Return(Self); statement.

All graphic entities added to a page within the Idea Studio will use the GUI- functions (GUIPipe, GUITransform, etc.), but you are free to use Z- functions if you are adding objects using code.

The order of the graphical statements within the page's state determines their display order (later statements have a higher z-order than earlier statements) and also the tab-order for user-input elements.

Tags are drawn using widget code, placed within GUITransforms. The widget code controls the appearance (meter, topbar, slider, etc.). The GUITransform controls the scaling and location.

As with all graphics, pages have a reference box, defined either explicitly or implicitly. Unless otherwise specified, the reference box of a page matches the area of all objects drawn on that page using GUI-statements. Z-graphic objects don't count and will only be displayed inside the reference area. (The Z-graphic objects are an older technology that should rarely, if ever, be used in a modern application.)

Within the page code, each tag is referred to by its unique ID. This enables developers to rename tags at will without losing the associated graphic. If you copy the graphic, then paste it into an editor, VTScada will automatically look up the current name of the tag, and use that instead. (The absolute name will be used rather than the relative name, as indicated by the angle brackets.) Note that the result cannot be used in another page's source code; for that, copy from one .SRC file to another.

Copy & paste page code

On Working With Page Code:

Do not edit a page's source code while simultaneously editing the page using the Idea Studio. Attempting to do so is likely to cause a conflict in the version control system.

To reduce the likelihood of a conflict, and to protect your source code, you can hide the page from the Idea Studio. Do so by adding the following line to the variable declaration section of your page:

CONSTANT HiddenPage = HPF_NOTINLISTS;

With this addition, your page can only be edited in code.

Standard Variables within a Page’s Source File

All of the page elements that are accessible from the page editing dialogs are stored in the page's source code file and can be modified there. Variables will not be present if not set. (Defaults are not stored in the source code file.)

Title

The display title for the page. In a multilingual application, the value will be a phrase identifier key.

May also be set as an expression within the body of the page's main state.

PageToolTipLabel

Text to display as a tool-tip when the page has been added to the navigation bar.

Color

Alpha-RGB string setting the background color of the page.

Bitmap

Name of the image to use for the page background.

NoStretch

The NoStretch variable is associated with the ScaleDisplayContent configuration variable, both of which enable you to control scaling for the pages comprising your application. When set to a non-zero value, ScaleDisplayContent causes the graphics on all pages to scale to fit the dimensions of the window. ScaleDisplayContent affects all pages in an application, however, there may be selected pages to which you do not wish the scaling to apply. The NoStretch variable enables you to inhibit scaling for such pages. If NoStretch has a non-zero value, then the page will not be scaled regardless of the setting of the ScaleDisplayContent configuration variable.

Automated display scaling works reasonably well when enlarging the page. It cannot do as good a job when shrinking a display for a smaller screen. In particular, labels embedded within buttons or widgets are more likely to be truncated than scaled down.
Always design for the smallest screen that the application will be displayed upon. Further information is provided in Size Pages for Differing Screens

PageWinOpt

The PageWinOpt variable overrides the Style parameter options used for windowed pages. (Refer to the Window function for a description of the style parameter options.) Note that bits are counted from right to left and that examples you may see in pages often exclude the unset bits to the left of the highest numbered bit being set.

Refer also to Bitwise Parameters & Operations.

PageX

The PageX variable enables you to set the X coordinate for the top left corner of a windowed page. If PageX is not set for a windowed page, a default value is used.

PageY

The PageY variable enables you to set the Y coordinate for the top left corner of a windowed page. If PageY is not set for a windowed page, a default value is used.

PageHeight

The PageHeight variable overrides the normal PageHeight calculation for a windowed page (see the Window function for details). If not specified, the height is calculated from the page components.

PageWidth

As above, but for width.

PageMinHeight

Minimum number of pixels to use for the height when the page is displayed in its own window.

PageMinWidth

Minimum number of pixels to use for the width when the page is displayed in its own window.

PageVWidth

Maximum width, in pixels, of a windowed page.

PageVHeight

Maximum height, in pixels, of a windowed page.

PageBMPMarginsWin

A Boolean value (1 or 0) controlling whether a margin should be used when a windowed page displays an image.

PageBMPMarginLeft

Left margin to use when PageBMPMarginsWin is enabled.

PageBMPMarginBottom

Bottom margin to use when PageBMPMarginsWin is enabled.

PageBMPMarginRight

Right margin to use when PageBMPMarginsWin is enabled.

PageBMPMarginTop

Top margin to use when PageBMPMarginsWin is enabled.

ExcludeFromTagSearch

If present and set to 1 (TRUE) the page will be ignored by any task that seeks to open a page where a tag has been drawn.

Note that the opposite may be true, where a developer wishes to add pages that might not normally be searched, to the cache of those that are. For this case, it is possible to create a hook to let an application provide a set of pages + parameters to be checked whenever a "Go To Page" operation (for a tag) is performed. This is useful for custom-coded applications that access pages through a means other than the page menu and page change widgets.

The callback module must be named "GetPagesForTagsHook" and must return an array of structures, each with three fields: Name, Parms, and Label. The array is limited to 10,000 entries.

The following structure may also be used:

\PageTagRefMgr.GetPagesForTagsHookPageInfo(--Name of the custom page--,
                            --array of parameters needed by the page--,
                                                    --the page label--);

Display Manager Bit Flags for Page Display

In addition to the modifiable variables within a page’s source file, the Display Manager defines and uses a set of bit flags that determine how a VTScada page is displayed.

Constant PSTTB = 0x0001 { Page Style - Show Title Bar };
Constant PSBMP = 0x0002 { Page Style - Show Title Bar Bitmap };
Constant PSLGN = 0x0004 { Page Style - Show Title Bar Logon Button };
Constant PSCFG = 0x0008 { Page Style - Show Title Bar Configure Button };
Constant PSDTE = 0x0010 { Page Style - Show Title Bar Date & Time };
Constant PSIND = 0x0020 { Page Style - Show Title Bar Alarm indicators };
Constant PSTTT = 0x00FF { Page Style - Show all Title Bar decorations };
Constant PSMBR = 0x0100 { Page Style - Show Task Bar };
Constant PSMNU = 0x0200 { Page Style - Show Menu Button and Menu };
Constant PSMPB = 0x0400 { Page Style - Show Task bar Page buttons };
Constant PSMFB = 0x0800 { Page Style - Show Task bar "<" and ">" buttons};
Constant PSMPM = 0x1000 { Page Style - Show Task bar "+" and "-" buttons};
Constant PSMHD = 0x2000 { Page Style - Hold page btn changes target };
Constant PSMMM = 0xFF00 { Page Style - Show all Menu Bar decorations };

There is a public variable, PageStyle, defined in the Graphics module in each session, which is an OR of the style bits that apply to a page. The initial setting is PSMMM + PSTTT, which is all decorations.

The address of the PageStyle variable is passed as a parameter to the MenuBar and TitleBar plug-ins.

Although PageStyle is public (because the MenuBar and TitleBar plug-ins need to see it) setting its value directly is ineffective because it is reset with each page change.

Whenever a new page is displayed, PageStyle is set as follows (in priority order)…

Normal page:

  1. Default value of a PageStyle variable in the page.
  2. The value of DefaultPageStyle.

Windowed page:

  1. Default value of a PageWStyle variable in the page.
  2. The values supplied in parameter 4 of the Display Manager method, ShowStyledPage.
  3. The value of DefaultPageStyle.

DefaultPageStyle defaults to the value that shows all decorations. This can be overridden by the configuration settings \DispMgrWPageStyle and \DispMgrPageStyle, or by parameter three of the DisplayManager method ShowStyledPage.

For example, to disable in all pages, the feature whereby a navigation bar button changes if you hold it down for more than 1.5 seconds, you have to set the configuration variable \DispMgrPageStyle to the value 0xFDFF (you cannot use the constant values defined in DisplayManager).

Application properties for pages

  • DispMgrPageStyle - For all normal pages
  • DispMgrWPageStyle - For windowed pages

(Please refer to Application Properties for the Display Manager for further information on these and other modifiable variables.)

For Custom pages you can use code similar to the following example to offset the top and bottom of the page in the Display Manager:

TopOffset = PickValid(And(Caller(Self())\PageStyle, \DisplayManager\PSTTB), 0) ?
            \DisplayManager\Task_Height : 0;
BottomOffset = PickValid(And(Caller(Self())\PageStyle, \DisplayManager\PSMBR), 0) ?
               \DisplayManager\Menu_Height : 0;


Owned Windows versus Child Windows

A child window is embedded in a parent window and cannot leave that display area. It is automatically moved when the parent is moved. The child window's X,Y position is relative to the parent's, rather than to the screen. Typically a child window has no frame or title, although you can configure them.

This is not true for owned windows (those with bit 15 set in their Window call).

An owned window is always layered in front of its owning window. Owned windows have no icon on the MS Taskbar. An example of an owned window is the Add Application Wizard.

Owned, caption-less windows are a common way to create pop-up (right-click) menus.


The Focus ID

Every function for drawing graphics includes a FocusID parameter. VTScada does not force you to set a unique value for each ID since there are situations where it is desirable to use one value for several objects. (For example, disabling several AddressEntry fields by setting their FocusID values to 0.)

A graphic only needs a unique focus ID value if you intend to use the NextFocusID function to give it the focus, or the FocusID() function to see if it has the focus. Otherwise, best practice is to give every active control the focus ID of 1.

Tab order between user input controls follows their z-order (that is, the order of the statements within the state), rather than their Focus ID value.

The function, NextFocusIDcan be used to set the focus to the next item with a certain focus ID number. FocusIDreturns the focus ID number of the item that has focus.

Note that the above refers to keyboard focus. If several overlapping objects can react to a mouse-click then that click will be used by all the overlapping objects. It does not matter that only one has focus.

Placing Focus on an Object vs. Selecting an Object

There is a difference between an object being selected, and an object that has the focus on a page. It is very important to note that an object that has the focus is not necessarily selected. In a sense, focus can be thought of as a property while selection is a command.

For example, it is possible to force the input focus to a certain graphic object by means of a NextFocusID statement. When dealing with statements that combine an If function and a GUIButton function, it is important to keep in mind that you may focus the button, but the script paired with the If function will not be executed until the button is actually pressed (either by the keyboard or the mouse).

An object that has the focus is ready for input from the user. If the object is an edit field for example, the cursor will blink within the field, indicating that it is ready for input. If the object with the focus is a button, it is highlighted when selected. In order for an object that has the focus to be selected, it must be clicked by the mouse, or the <TAB> key, or the <RETURN> or <ENTER> key must be pressed.

Focus movement (on a tab key) or reverse tab (i.e. Shift + Tab keys)) is based on the order that statements appear in the source code. This applies recursively to calling sequences in steady state. For example:

ZButton(...1...);
ChildMod();
ZButton(...2...);

In this example, ZButton(...1...) would be first in the focus order, followed by any focusable statements in ChildMod, followed by ZButton(...2...).

Launched modules will appear in the focus order after steady state focusable statements and steady-state calling sequences.

For example:

If Watch(1);
[
  LaunchedMod();
]
ZButton(...1...);
ChildMod();
ZButton(...2...);

In the above sequence, the focus order will be the same as that of the previous example above, with the addition of any focusable statements in LaunchedMod, after ZButton(...2...).


Native Windows Tooltip Support

The statement, WinTooltipCtrl, supports Windows tooltips.

A Windows tooltip is a pop-up text window that provides an operational hint to a user based on the object on which the mouse pointer is focused. As a VTScada developer, you may choose to present the text box-style tooltips to users, or use the balloon-style tooltips (default).

The default behavior is to display balloon-style tooltips for "drawn" objects (for example, an analog input represented as a number on a page), and to display rectangular tooltips for other objects, such as buttons in a tool bar (rectangular tooltips appear for each of the buttons in the tool bar on the Historical Data Viewer page). This behavior can be changed to always display rectangular tooltips by setting the application property "NoBalloonTips" to a non-zero value.

The names of the related application properties start with "Tip" (e.g. TipOn & TipFont). The default (Invalid) for all of these settings results in the default operating system settings being used. Please refer to "Application Properties for Tooltips".

The WindowOptionsstatement allows for setting the text color, background color, and timings associated with all tooltips for a given window. These settings are inheritable, so that Windows that are children of a window that already has these settings modified uses the parent window's settings, unless explicitly overridden by subsequent WindowOptions statements.


Reference Boxes and Scaling

If a particular module is to be used to draw graphics, and this module will be used inside of a transform at any point, it may be helpful to fix the module's reference box size. In doing so, all scaling done by the transform will be predictable. This can be done by following the module's name with a group of constants that define the reference box for the module.

The constants define the left, bottom, right, and top coordinates of the module's reference box respectively. One-unit values are commonly used when the intention is to allow the transform code to control the final size. By using unit values, you greatly simplify calculations of scale.

The same technique is also used by all of the GUI... functions.

Note that these values must be constants. The use of variables for the four values is not allowed by the compiler.

If the purpose of a module is to display a graphic object, it is useful to define a reference box. This defines the rectangle to be occupied by all graphics drawn by the module. Reasons to do so include the option of including a margin around those objects, or if some of your graphics are transformed so that not all graphics would be drawn within the module's default reference box.

If a reference box is not defined, then VTScada will automatically calculate one based on the graphics being displayed.

Commonly, graphic objects are displayed using a GUITransform that sets the size, location, and other attributes. The module's reference box will be mapped to the bounding box defined and transformed by the GUITransform. So for example, if you had a module named PumpSymbol, you might display it as follows:

GUITransform(0, 150, 100, 50 { Bounding box of object },
             1, 1, 1, 1, 1 { No scaling },
             0, 0 { No trajectory or rotation },
             1, 0 { Object is visible; reserved },
             0, 0, 0 { Graphic cannot be focused },Time Formatting Codes
             flow = PumpSymbol(1, amps) { A sample module call });

When a GUITransform is applied, the module will be scaled such that its reference box will exactly fill the reference box of the transform, and that will be acted upon by the other transform parameters.

The reference box is defined using constants (numbers or defined constants) that are enclosed in parentheses and placed immediately after the module's name in its definition. The x and y coordinates of the reference box corners are defined in the order LeftReference, BottomReference, RightReference, TopReference. Variables and expressions may not be used.

For example:

PumpSymbol
(0, 100, 100, 0) { reference box }
( { parameters }
  State { current pump state  },
  Amps  { Amperage to display }
)
[ ...

Widgets created within the Idea Studio do not define their reference box with constants at the beginning of the module. Rather, their reference box is based on the collection of objects they contain and can be obtained dynamically (if ever needed) using the function GetModuleRefBox(\Self, SideIndex) to determine each of the four sides.

Use Scaling to Position Graphic Objects

It is sometimes desirable to position an object, such as a GUIButton, based on the value of some variable or parameter.

Because the first four parameters of all GUI functions must be constants, the scaling parameters must be used to dynamically change the position and size. This is easier to achieve if the first four parameters are used to define a unit box, and the side-scaling parameters (five through eight) are used to position and size the object being drawn. Because the scaling parameters do not have to be constants, variables may be used to set the object's position.

The first four parameters are always in the order Left, Bottom, Right, Top. The unit bounding box must be defined as 0, 1, 1, 0. Do not change the order. If you use this in a module that will be modified by GUITransform, (e.g. a widget), you will probably need to give the widget a fixed reference box that contains the area where the graphics will be drawn.

The scaling parameters are also in the order of Left, Bottom, Right and Top. The scale values to apply will always use the formula, (1 - Left), Bottom, Right, (1 - Top).

For example, to position a GUIRectangle using the side scaling parameters:

left = 10;
bottom = 80;
right = 100;
top = 10;
...
GUIRectangle(0, 1, 1, 0 { Unit bounding box },
             1 - (left) { Left scaling },
             bottom     { Bottom },
             right      { Right scaling },
             1 - (top)  { Top scaling },
             1          { No scaling as a whole },
             0, 0       { No movement },
             1, 0, 0, 0, 0 { Visible, not selectable },
             14, 12     { Yellow interior, red outline });

This rectangle will be identical to one drawn using the following constants for the initial bounding box.

GUIRectangle(10, 80, 100, 10 { Unit bounding box },
             1, 1, 1, 1, 1   { No scaling },
             0, 0            { No movement },
             1, 0, 0, 0, 0   { Visible, not selectable },
             14, 12          { Yellow interior, red outline });

As a second example, suppose that you have created the rectangle depicted in the first case above, and that you now want to draw another rectangle, smaller by 3 pixels in all directions, and perfectly centered within the first rectangle

GUIRectangle(0, 1, 1, 0     { Unit bounding box },
             1 - (left + 3) { Left scaling },
             bottom - 3     { Bottom },
             right - 3      { Right scaling },
             1 - (top + 3)  { Top scaling },
             1              { No scaling as a whole },
             0, 0           { No movement },
             1, 0, 0, 0, 0  { Visible, not selectable },
             10, 0          { Green interior, black outline });

Again, substitute the appropriate scaling coordinates into the formula in the positions held by left, bottom, right and top.


Transparent and Alpha-blended Windows

VTScada supports transparent windows and alpha-blended (also referred to as translucent) windows.

Transparent Windows

A transparent window is one that has a transparent or invisible frame and background. The intended use for this feature is to allow the display of non-rectangular windows by rendering the background as transparent, while allowing mouse messages, such as movement and clicks, to "drill-through" the transparent area to the window below. Objects (such as graphics) placed on the transparent window remain opaque and mouse messages do not drill-through these opaque objects.

The simplest way to create a transparent window is to specify a background color less than zero (e.g. -1). The underlying implementation, however, requires that a specific color be used as the "key" color. All pixels of that color in the otherwise rectangular screen area that the window occupies are rendered as transparent. Using a background color of <0 results in the key color being black (i.e. RGB(0, 0, 0)), and the window background being set to that color. It may well be that you wish to have black as a color in your window, however. Therefore, setting bit 18 in the Window statement also announces that this window is to be rendered as transparent, with whatever color is specified as the background color being the transparent color.

Alpha-blended or Translucent Windows

An alpha-blended or translucent window is one that has an alpha channel set up in the final renderer, resulting in a translucent effect to the window (i.e. it behaves like a normal window, except that you can see through the window to some degree). The degree of translucency ranges from 0 (invisible) to 255 (completely opaque, like a normal window). Setting bit 17 on your Window statement invokes "automatic" alpha blending, where the window is set to be 50% translucent when inactive, and opaque when active. This is useful for dialogs that are non-modal Closed A modal dialog is always displayed on top of the calling window and prevents further interaction with that window. and always on-top, so that when another window is active, you can see through the underlying windows. If you need a finer degree of control, do not set bit 17, but rather use a new value for the Option parameter of WindowOptions (9) and set the WindowOptions "OptValue" parameter to the degree of alpha-blending that you wish (0 to 255).

Neither the transparent nor the alpha-blended/translucent effects work with child windows. These effects are not designed for animation purposes, and are not sufficiently efficient for this purpose. The amount of processing power required to redraw one of these windows depends on the rating of the graphics card in your machine - the newer and faster the better.


Drag & Drop to a Window

Any window can be used as a drag and drop target. An example can be seen in the Idea Studio, where you can drag an image from any Windows folder directly to your editing canvas to both import the image and draw it on the canvas.

Not all object types can be imported.

To add this functionality, you must include two call-back modules in the module that controls the window. These are OLEDrag and OLEDrop. OLEDrag is not strictly necessary, but without it users will have no visual reference that a drag and drop operation is under way.

In the following example, the parameters shown are required to make the call-backs work. The content of the modules is entirely up to you.

It is a requirement that these modules operate as subroutines.

Example:

{=========================== System =================================}
{====================================================================}
( System               { Provides access to system library functions };
  Layer                { Provides access to the application layer    };
)
[
  Graphics      Module { Contains user graphics                      };
  WinTitle = "IDropTarget Test" { Window title                       };
  RunningOnVIC            { TRUE if this is a VIC session            };
]

Init [
  If 1 Main;
  [
    RunningOnVIC = IsVICSession();
  ]
]

Main [
  Window(  0,   0           { Upper left corner   },
         800, 600           { View area           },
         800, 600           { Virtual area        },
         Graphics()         { Start user graphics },
          {65432109876543210}
         0b00010000000110011,
         Concat(WinTitle, RunningOnVIC ? " - %S" : ""),
         0, 1);
]

<
{======================== System\Graphics =============================}
{ This module handles all of the graphics for the application          }
{======================================================================}
Graphics
[
  OLEDrag        MODULE { Called when a droppable object passes over    };
  OLEDrop        MODULE { Called when a droppable object is dropped here};
  PlaceImage     MODULE { Draws an image in the position it was dropped };
  PROTECTED PlacedImages { Dictionary of dropped image objects          };
  PROTECTED CurrentDragItem  { Storage for current droppable obj if any };
  PROTECTED CurrentDragImage { Image being dragged if applicable        };
  PROTECTED DragX             { Current drag X position                 };
  PROTECTED DragY             { Current drag Y position                 };
  PROTECTED ImgSzX            { Current image width                     };
  PROTECTED ImgSzY            { Current image height                    };
  PROTECTED Base              { This object                             };
  CONSTANT  #CF_TEXT     = 1  { Text clipboard format                   };
  CONSTANT  #CF_HDROP    = 15 { File drop clipboard format              };
]

Init [
  If 1 Main;
  [
    PlacedImages = Dictionary();
    Base         = Self();
  ]
]

Main [
  ZText(10, 30,
        "Click and drag MSDN_Butterfly.jpg from the app folder", 0, 0);
  ZText(10, 45,
        "onto this window.", 0, 0);
  ZText(10, 60,
        "Does the image appear and track to the cursor (roughly)", 0, 0);
  ZText(10, 75,
        "when the mouse is over this window?", 0, 0);
  ZText(10, 90,
        "Release the mouse button, dropping the image.", 0, 0);
  ZText(10, 105,
        "Does a copy of the image appear in the dropped position?", 0, 0);
  ZText(10, 120,
        "If the answer to both questions above is yes then this", 0, 0);
  ZText(10, 135,
        "test is a success, otherwise it fails. Feel free to try", 0, 0);
  ZText(10, 150,
        "other files. Only images should be processed by this test.", 0, 0);
  { The following code draws a copy of the image on the page positioned
    to match the last reported drag position. The image is drawn extending
    up and left from the position.                                         }
  ImgSzX = BitmapInfo(CurrentDragImage, 0);
  ImgSzY = BitmapInfo(CurrentDragImage, 1);
  GUIBitmap(0, 1, 1, 0,
            1 - (DragX - ImgSzX),
            DragY,
            DragX,
            1 - (DragY - ImgSzY),
            1, 0, 0 { No overall scaling, trajectory, or rotation },
            1, 0    { visibility, reserved },
            0, 0, 0 { No activation or focus },
            CurrentDragImage);
]

<
{============================== OLEDrag ==============================}
{ Called in response to an IDropTarget drag notification.             }
{=====================================================================}
OLEDrag
(
  Type                { The clipboard format of the data parameter   };
  Data                { The data passed, data type varies (see above) };
  KeyState            { Keyboard key press enumeration                };
  X                   { X-coordinate of the cursor                    };
  Y                   { Y-coordinate of the cursor                    };
  Mode                { Op code: 0=drop, 1=enter, 2=over, 3=exit      };
)

Main [
  If 1;
  [
  { When a drag enters a window it reports the data, but does not during drag over or exit operations. Grab a copy of the image during the enter and
    remove it upon exit.                                                      }
  IfElse(Mode == 1 && Type == #CF_HDROP, Execute( { Only try to make a bitmap if given a file name }
    CurrentDragItem = Data;
    CurrentDragImage = MakeBitmap(CurrentDragItem);
  );
  { Else } IfThen(Mode == 3,
    CurrentDragItem = CurrentDragImage = Invalid;
  ));
{ Update the drag position, technically this is only necessary because
  XLoc etc. don't report mouse position during a drag.                 }
  DragX = X;
  DragY = Y;
  Return(Invalid);
]
]
{ End of System\Graphics\OLEDrag }
>

<
{============================== OLEDrop ===============================}
{ Called in response to an IDropTarget drop notification.              }
{======================================================================}
OLEDrop
(
  Type                 { The clipboard format of the data parameter   };
  Data                 { The data passed, data type varies (see above) };
  KeyState             { Keyboard key press enumeration                };
  X                    { X-coordinate of the cursor                    };
  Y                    { Y-coordinate of the cursor                    };
  Mode                 { Op code: 0=drop, 1=enter, 2=over, 3=exit      };
)
[
  PROTECTED Image      { Image loaded from the file                    };
]

Main [
  If 1;
  [  { The imae is being dropped, cease to draw the drag-tracking image }
    CurrentDragItem = CurrentDragImage = Invalid;
    { Add a copy of the image to the window at the current coordinates. }
    IfThen(Type == #CF_HDROP { Only do this if we were passed a file name },
      Image = MakeBitmap(Data);
    IfThen(Valid(Image),
      PlacedImages[GetGUID(1)] = Launch(\PlaceImage, Base, Base, Image, X, Y);
    );
    );
    Return(Invalid;);
  ]
]
{ End of System\Graphics\OLEDrop }
>

<
{=========================== PlaceImage ===============================}
{ Draws an image on the window at with a lower right corner at the given pos. }
{======================================================================}
PlaceImage
(
  Image                { Image to be placed                            };
  X                    { Right side of the placement                   };
  Y                    { Left side of the placement                    };
)
[
  PROTECTED ImgSzX     { Current image width                           };
  PROTECTED ImgSzY     { Current image height                          };
]

Main [
{ Draw an image extending up and left from the given position. This just
  makes things easy given the way that the image is being traced during the
  drag.                                                                     }
  ImgSzX = BitmapInfo(Image, 0);
  ImgSzY = BitmapInfo(Image, 1);
  GUIBitmap(0, 1, 1, 0,
            1 - (X - ImgSzX),
            Y,
            X,
            1 - (Y - ImgSzY),
            1, 0, 0 { No overall scaling, trajectory, or rotation },
            1, 0    { visibility, reserved },
            0, 0, 0 { No activation or focus },
            Image);
]
{ End of System\Graphics\PlaceImage }
>
{ End of System\Graphics }
>


Web Services and XML

The ODBC driver now shipping with VTScada provides a REST interface, and does not implement SOAP. Customers who have existing SOAP applications can continue to use those. The new driver, supporting REST, is installed as the "VTScada ODBC driver" The older driver, supporting SOAP, was installed as "VTS ODBC Driver". Both may be installed on the same server.

The Web Services Module provides a means for VTScada to receive Simple Object Access Protocol (SOAP) requests over a network and translate those requests into VTScada procedural requests. The results of these requests can be compiled back into the SOAP message format and sent back to the remote computer.

The ability to provide Web Services is a separate licensing option of VTScada. If you did not purchase a license for Remote Data Access, it will not be available on your system.

This technology enables multi-server applications to make use of selected VTScada services that you choose to provide from your application. Possible applications range from remote reporting to complex delivery scheduling systems, relying on calculations done in VTScada to predict when material deliveries will be required.

The WebService module links together a WSDL document, a VTScada Realm, and a set of project-defined VTScada modules. This linkage enables VTScada to accept SOAP messages directed at specific VTScada Realms via the network and translate those messages into procedural requests for VTScada applications. The results of these requests can then be compiled back into SOAP message format and returned to the network entities that made the requests.

Realms can be accessed only by authorized users. Security must be enabled and there must be at least one account with the Thin Client Access privilege.

The WSDL document

A generic WSDL file is included with VTScada, C:\VTScada\VTS\VTSSOAPServices.wsdl. Before creating your own WSDL file, examine this one to determine whether it can be modified to meet your needs.

The WSDL file describes the structure of the web service. At a minimum the WSDL file will define, in XML format:

  • The operations that are available.
  • The data types of variables passed and returned.
  • The location of the Realm to which the application is linked.

The WSDL file must also include the name of the module to be called. Incoming SOAP messages will use this same name to indicate the module to call. Outgoing messages will use the name of the module with the string "Response" appended, thereby indicating their source.

The Realm

Each VTScada Realm can expose a single WSDL and connect it to a specific module within a single application. All VTScada modules to be called via that Realm must be direct submodules of the connected module, so that the WebService functions can locate them.

Subsequent WSDL attachments to the same Realm will supersede existing attachments, not aggregate with them.

After a Realm is attached to a WSDL it can start accepting SOAP messages immediately and will continue to accept them until the attachment is removed. The individual calls can accept up to 30 parameters each.

The parameters must be provided as defined by the WSDL and passed via the SOAP message. In the case that a complex type is sent as a parameter in the message, that parameter will be passed to the module as a XMLNode Tree.

The module

The project-defined VTScada module commonly takes the form of a .SRC file in the application's main directory. It is reserved by the system as the root of the web service. Submodules of this root are used to expose parameters and VTScada operations to the WebService.

Only one module can be associated with a realm, but since this module may contain submodules that are available to the web service, an effectively unlimited number of SOAP calls can be handled via the single root module

Do not confuse the module with the application pages. None, any or all tags from any or all application pages may be exposed to the web service through the module system.

A key feature of the module will be a call to the WebService function, SetWSDL. This function connects a Realm to the application to provide the web service interface. An example of a call to this function can be found in the Web Services Example: Creating the VTScada Module.

VTScada is compliant with SOAP 1.1 not with SOAP 1.2. Messages must be encoded for SOAP 1.1.


Web Services Terms

DOM

Document Object Model. A W3C standard that defines a programmatic interface to a parsed XML document. The DOM presents an easily processed, standardized interpretation of an XML document.

DTD

Data Type Definition. A declaration and optional syntactic rules that an XML document must adhere to. DTDs are still legal, but have largely been superseded by XML schema.

RPC

Remote Procedure Call.

SOAP

SOAP (originally Simple Object Access Protocol) is a protocol for exchanging XML-based messages over computer networks, normally using HTTP.

SOM

Schema Object Model. A Microsoft implemented API that provides a procedural API to schema cached in their XML engine.

W3C

World-Wide Web Consortium. An organization that maintains the standards used on the Internet, including the specifications that relate to XML and XML schema.

Web Service

The W3C defines a Web service as a software system designed to support inter-operable Machine to Machine interaction over a network. Web services are often just Web APIs that can be accessed over a network, such as the Internet, and executed on a remote system hosting the requested services.

WSDL

Web Services Description Language is an XML-based language that provides a model for describing Web services. The World Wide Web Consortium provides a description of WSDL and a set of examples for using it at http//www.w3.org/TR/wsdl

XML

eXtensible Markup Language. A W3C standard for the representation of arbitrary data and associated properties using a markup language.

XML Document

An XML stream that is complete, having a valid XML declaration and a complete set of balanced tags.

XML Processor

A VTScada engine internal entity that exposes a script code interface to allow an XML document to be represented in a manner easy for script to access and manipulate. The XML processor is capable of parsing and writing XML documents.

XML Schema

An XML document that specifies additional syntactic rules that an XML document that "conforms" to the schema must adhere to.

XSLT

XML Style Sheet Transformation. An XML document that contains a set of transforming instructions. Such a transform can be used by an XML processor to generate a new W3C standards-compliant output document from an XML document, e.g. (X)HTML output.


Module and Parameter Naming

The WebService functions use name matching on the WSDL Closed Web Services Description Language. An XML-based language that provides a model for describing Web services <operation> tags to discover SOAP Closed SOAP (originally Simple Object Access Protocol) is a protocol for exchanging XML-based messages over computer networks modules. Modules to be called must therefore be named such that they match the names of the <operation ...> tags described in the WSDL document. Incoming SOAP messages will use this same name to indicate the module to call, while outgoing messages will use the name of the module with the string "Response" appended to indicate their source.

Example:

    <wsdl:message name="GetTagValueInput">
        <wsdl:part name="request" type="tns:GetTagValueIn" />
    </wsdl:message>

    <wsdl:message name="GetTagValueOutput">
        <wsdl:part name="response" type="tns:GetTagValueOut" />
    </wsdl:message>
    <wsdl:portType name="TagQueryServicesPort">
        <wsdl:operation name="GetTagValue"
                        parameterOrder="request response">
           <wsdl:input message="tns:GetTagValueInput"/>
           <wsdl:output message="tns:GetTagValueOutput"/>
        </wsdl:operation>
    </wsdl:portType>

The VTScada module referenced here, GetTagValue, must be created and given parameters as follows:

<
GetTagValue
(
  request;
  response;
)
...
>

Parameters exposed by the called modules must cover both input from the incoming SOAP message and output to the outgoing SOAP response. The names of these parameters must match the <part> tag names associated with both the <input> tags and <output> tags as defined in the <operation> section of the WSDL for the called module.

This system enables parameters to be properly integrated into messages. Each output parameter will be given a pointer to a blank instance of the type required by the method. The method should fill out these structures, extending array portions as necessary. Similarly, each input parameter will be passed a pointer to the incoming data type that the parameter represents. The pointers themselves must not be changed as this would break the linkage to the WebService system calling the module and prevent proper passage of output data.

The return value of a called module must not be of type OBJECT and should be INVALID. Steady-state called modules must not contain a return statement at all, as this will cause VTScada to attempt to execute them as subroutines (i.e. procedurally). Any values that are returned will be discarded by the system.

After a web service is set up, a variable called "WSDrvr" will be added to the connected module

Developers should not include a variable with the name "WSDrvr" themselves. The WebService initialization function will reject any modules containing such a variable.

This variable records several pieces of context data relevant to the new web service as well as a group of support functions for common web service processing tasks.


VTScada Web Service Commands

The WebService module exposes two methods for use during web service deployment, SetWSDL and RemWSDL. The first performs the attachment of a WSDL to a Realm and the second disconnects such an attachment if it exists.

SetWSDL connects a Realm with a WSDL file and a set of VTScada modules to enable a web service interface. Linkage is first applied between the WSDL file and the VTScada modules by generating an XML schema using the WSDL and the parameters provided to this function. The Realm’s address is then registered with the VTScada HTTP server to connect the whole thing to the network.

A prototype for a call to the SetWSDL function follows. It will return 0 for success and 1 for failure. If an error occurs, a message will be returned via the pointer, pResponse.

System.WebService\SetWSDL(<WSDL File Path>,
                           <Realm>,
                           <Call Scope>,
                           <Service>,
                           <pResponse>);

RemWSDL disconnects a Realm from a WSDL file and the associated set of VTScada modules. It then proceeds to clean up any resources consumed by the web service that this association represented. After RemWSDL is called, the associated web service will immediately stop processing messages. Note, however, that any operations set in motion by that service will run to completion. This function is called implicitly if the connected module is destroyed.

A prototype for a call to the RemWSDL function:

System.WebService\RemWSDL(<Realm>);
RemWSDL must be called in a script.


WSDrvr Services

After a web service is successfully registered via SetWSDL, a variable named "WSDrvr" is added to the connected module. This variable exposes a set of data points for use by the web service and the WebService functions, as well as a small group of helper functions. The data points are presented to the web service on a READ ONLY basis - developers should not attempt to modify these values as it will adversely affect their web service.

The Web Service Helper Functions are described following the data points:

Web Service Data Points

\WSDrvr\Realm | This is a copy of the realm name to which the web service is attached.
\WSDrvr\Rscope | This is an object reference to the connected module.
\WSDrvr\WSDL | A copy of the WSDL in use. This has not been converted into VTScada format; it is a raw text dump.
\WSDrvr\XMLHandle | The XML processor used for this web service, it contains the basic schemas for SOAP processing as well as a schema-converted version of the WSDL.
\WSDrvr\MsgNamespace | The target namespace of the WSDL, used by all messages and operations.
\WSDrvr\XMLns | A list of "xmlns" declarations delineating all of the namespaces used in the WSDL and basic SOAP schemas (and therefore all namespaces usable by this web service). Any messages generated by this service must have at least a subset of these declarations attached.
\WSDrvr\NSminus | Due to a rule of SOAP 1.1, the tags in a response message to a SOAP request should not (and in most cases must not) have namespace prefixes if they are declared in the "MsgNamespace". This is a list of all other namespace / prefix pairs declared for the service and is used to generate output messages.
\WSDrvr\Nsp | This object enables rapid conversion of namespaces to prefixes. It consists of a group of variables with names matching the namespaces declared for this web service (note that these contain "illegal" variable name characters, and can only be referenced via the Scope keyword), the value of each being a string containing the prefix associated with that namespace.
\WSDrvr\Pfx | This object enables rapid conversion of prefixes to namespaces. It consists of a group of variables with names matching the namespace prefixes declared for this web service, the value of each being a string containing the namespace name itself.
\WSDrvr\CallIdx | An object containing linkage data between messages and modules. This is of use only to the WebService functions.
\WSDrvr\ClassFactory | The XML Schema Cache Dictionary object used by the Web Service connected to the given module, it can be used to instantiate any of the types in any of the schemas registered by this service. The user of this service is free to add additional schemas to the Schema Cache Dictionary object as desired. Each Web Service has its own ClassFactory object to prevent a single damaged service from affecting others.

Web Service Helper Functions

\WSDrvr\MakeTypeArray

Description: | The MakeTypeArray function creates a SOAP 1.1 compliant array within the parent XMLNode provided and of the size specified.
Returns: | Invalid.
Usage: | Script
Format: | \WSDrvr\MakeTypeArray(pParent, Namespace, Name, Size, MemberNamespace, MemberName);
Parameters: |
pParent
A pointer to the XMLNode where the array will be added.
Namespace
The namespace of the array type.
Name
The name of the array.
Size
The size of the array.
MemberNamespace
The namespace of the member type.
MemberName
The name of the member type
Comments: The function creates an array of the specified size under a member called Name in the parent XMLNode. If the MemberName can be found in the schema cache under the MemberNamespace, then each element of the array will be of the specified type. Otherwise, it will be a plain XMLNode.

\WSDrvr\MakeTypeInstance

Description: | The MakeTypeInstance function creates a copy of an XMLNode representing an XMLType.
Return Value: | The XMLNode representing the type or invalid if the type cannot be found.
Usage: | Script
Format: | \WSDrvr\MakeTypeInstance(Namespace, Name)
Parameters: |
Namespace
The namespace of the type
Name
The name of the type
Comments: This function creates a clone of the XMLType specified by Name in the Namespace. If the type doesn't exist in the Namespace or the Namespace doesn't exist in the Schema Namespace Cache (ClassFactory) then invalid is returned.

\WSDrvr\ReportFault

Description: | Used to raise an engine level SOAP fault from within the service, causing the next processing phase to abort and a SOAP fault packet to be returned to the client.
Return Value: | Invalid
Usage: | Script
Format: | \WSDrvr\ReportFault(Description, Detail, ProcessFault);
Parameters: |
Description
A string describing the fault.
Detail
A string providing extra detail information.
ProcessFault
0 indicates an input problem, 1 indicates a processing problem.
Comments: The SOAP fault can be attributed to either local web service processing or poor input data from the client. Detailed fault information must be added to the message.

\WSDrvr\GetAttValue

Description: | GetAttValue returns the value of the specified XML attribute (stored as value metadata) within a particular tag representation.
Usage: | Script
Return Value: | The value of the attribute if found, otherwise Invalid
Format: | \WSDrvr\GetAttValue(pTag, Name, NameSpace);
Parameters: |
pTag
A pointer to the variable to be inspected.
Name
The name of the attribute to be retrieved.
NameSpace
The namespace of the member type.
Comments: The tag representation may functionally be any variable. The name of the attribute to retrieve is first attempted to be resolved as a full QName, and if no match is found then just the name of the attribute is resolved. QName construction is first attempted by using the NameSpace parameter, and then by getting the namespace of the tag.
A QName is a qualified name. For example, <tns:myElement tns:myAttrib="abc">. In this case "tns:myAttrib" is the QName. Thus, if a Namespace is provided, then the prefix for that namespace is looked up and preprended to the name and then tried first when searching for an attribute. If not found, then the plain Name is used.


Retrieve Tag Values Using SOAP

The ODBC driver now shipping with VTScada provides a REST interface, and does not implement SOAP. Customers who have existing SOAP applications can continue to use those. The new driver, supporting REST, is installed as the "VTScada ODBC driver" The older driver, supporting SOAP, was installed as "VTS ODBC Driver". Both may be installed on the same server.

VTScada exposes an SQL interface that allows retrieval of current tag values, historical tag values, alarm history, and alarm configuration and status. This interface is available both locally (on the same machine)and remotely (on a different machine as long as it has HTTP access to the machine running the VTScada application).

There are two main ways for a third-party application to send a SQL Query to a VTScada application:

  • ODBC – a standard protocol for database connectivity
  • SOAP – a standard Internet protocol for data requests and response

In order to use either of these methods the VTScada application will need configuration to expose the SQL interface. These steps are provided in the Developer's Guide topic, Configure an ODBC Server.

After configuration has been completed and tested, you can (for example) retrieve the current value of a tag named AnalogStatus1 using the SQL query:

SELECT Value FROM 'AnalogStatus1:Current'

Here, "AnalogStatus1:Current" is the name of a simulated database table that simply contains the current value of AnalogStatus1.

Do not create code that will send many queries every second, where "many" is defined as several hundred. Doing so may easily overload the CPU, network bandwidth, or both of the VTScada server. In general, it is better to query logged history rather than current values. Sample queries can be found in the Developer's Guide topic SQL: Reference and Examples.

Using SOAP to Retrieve Current Tag Values

After your VTScada application is configured to expose the SQL interface, you can test your ability to connect to that interface by using any web browser to go to the following URL:

http://hostname/YourApp’sRealmName/WSDL

You should receive the WSDL document shown following. This document describes the SOAP interface and is what you will likely use to create your SOAP client software.

It is beyond the scope of this document to describe in detail how to write SOAP client software, but you will generally need to write software that sends the following SOAP request over HTTP:

SQLQueryRequest("SELECT Value FROM AnalogStatus1:Current")

This will look like the following HTTP request. Note the Authorization HTTP header that is required to access a secured VTScada application.

Soap Request:

POST /SQLServicesRealm/SOAP/ HTTP/1.1
Host: www.trihedral.com
Content-Type: text/xml; charset="utf-8"
Content-Length: 430
SOAPAction: "http://trihedral.com/SQLQueryRequest"
Authorization: Basic d2lsbDoxMjM=

<?xml version="1.0" encoding="utf-8"?>
<SOAP:Envelope
  xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP:Body SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
       <m:SQLQueryRequest xmlns:m="http://trihedral.com/">
         <request>
            <Query>SELECT Value from AnalogStatus1:Current</Query>
         </request>
       </m:SQLQueryRequest>
    </SOAP:Body>
</SOAP:Envelope>

Response:

HTTP/1.1 200 OK
Date: Mon, 12 Jan 2009 14:45:03 GMT
Server: VTS 8.2.00.01
Content-Type: text/xml; charset="utf-8"
Content-Length: 1000
Cache-Control: no-cache
Connection: Close
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soapenv:Envelope xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
  xmlns:s="http://www.w3.org/2001/XMLSchema"
  xmlns:sii="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:soapp="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:tnss="http://trihedral.com/VTSSoapServicesAPI/2007"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <soapenv:Body>
    <SQLQueryRequestResponse>
      <response>
        <ResultArray soapenc:arrayType="s:string[1]">
          <string>70</string>
        </ResultArray>
        <NumFields>1</NumFields>
        <FieldNames soapenc:arrayType="s:string[1]">
          <string>Value</string>
        </FieldNames>
        <FieldTypes soapenc:arrayType="s:int[1]">
          <int>8</int>
        </FieldTypes>
        <ReturnCode>0</ReturnCode>
        <ErrorMessage/>
      </response>
    </SQLQueryRequestResponse>
  </soapenv:Body>
</soapenv:Envelope>


Web Services Example

A relatively straight-forward example of a web service is to use a CGI application running on a remote website to read tag values from a VTScada application.

The following are minimum requirements:

  • A network connection.
  • A running application that includes one or more tags with values to be read.
  • Security is enabled and at least one account possesses the Thin Client Access Privilege.
  • A named realm that makes the application available.
  • A WSDL file in the application directory that describes the service.
  • A module in the application that provides the web service
  • (Optional, but useful to ensure that the service is instantiated at startup:) A line in the application's AppRoot.src module to name the service module above.
  • A program running remotely to call and use the web service.

Assuming the first two items, the network connection and a working application are in place, the following steps will describe the process of setting up a web service to read values from the application from a PHP-enabled web page.

This example uses a fictional application named Station Example which is located in the directory C:\VTScada\StationExample. It contains a single analog input named AI20_1.

It is assumed that you already know how to Configure a VTScada Thin Client Server. For the sake of the example, it is also assumed that you have also completed the steps in Configure a Realm, and have created one named QueryServicesRealm, holding the application Station Example.

Next Steps:

Creating a WSDL File


Creating a WSDL File

The Web Services Description Language file provides the model for describing the web service.

The file commonly starts with a header which includes links to the XML schema. To adapt the following header to your own system, replace every entry that reads "localhost" with the fully qualified domain name of your own server. ('localhost' will probably work on your system for testing purposes)

XML requires that the target Namespace be a globally unique identifier. Common practice would be to use a fully qualified domain name here. "localhost" only works for our example because the application is running on the same computer as the "remote" CGI script.

<?xml version="1.0"?>
<wsdl:definitions name="TagQueryServices"
targetNamespace="http://localhost/"
xmlns:tns="http://localhost/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:s="http://www.w3.org/2001/XMLSchema">

After the header comes a section describing the WSDL types. This describes the target namespace (again, localhost is used here - substitute your own domain), and the expected input and output variables. In this case, when a request is made for 'TagName' a response will be generated that includes 'TagValue' and a 'ReturnCode'. The TagName is expected to be of type String. The TagValue will be of type Float and the ReturnCode will be an integer.

<wsdl:types>
<s:schema
targetNamespace="http://localhost/">
<s:import
namespace="http://schemas.xmlsoap.org/soap/encoding/" />
<s:import
namespace="http://schemas.xmlsoap.org/wsdl/" />
<s:complexType name="GetTagValueIn">
<s:sequence>
<s:element
minOccurs="1"
maxOccurs="1"
name="TagName"
type="s:string" />
</s:sequence>
</s:complexType>
<s:complexType name="GetTagValueOut">
<s:sequence>
<s:element
minOccurs="1"
maxOccurs="1"
name="TagValue"
type="s:float" />
<s:element
minOccurs="1"
maxOccurs="1"
name="ReturnCode"
type="s:int" />
</s:sequence>
</s:complexType>
</s:schema>
</wsdl:types>

The expected SOAP messages are defined next: In this case there are only two: GetTagValueInput (the request) and GetTagValueOutput (the response).

<wsdl:message name="GetTagValueInput">
<wsdl:part name="request" type="tns:GetTagValueIn" />
</wsdl:message>
<wsdl:message name="GetTagValueOutput">
<wsdl:part name="response" type="tns:GetTagValueOut" />
</wsdl:message>

The PortType section includes a supported set of operations, in this case "GetTagValue".

Each operation lists the input and the output messages of the operation.

<wsdl:portType name="QueryServicesPort">
<wsdl:operation
name="GetTagValue"
parameterOrder="request response">
<wsdl:input message="tns:GetTagValueInput"/>
<wsdl:output message="tns:GetTagValueOutput"/>
</wsdl:operation>
</wsdl:portType>

The Binding section ties the SOAP calls to the supported operations. Note the use of the 'localhost' address in this section. Again, you will need to change this to the domain of your own server. Also to be noted is the reference to the port defined above.

<wsdl:binding
name="QueryServicesSoapBinding"
type="tns:QueryServicesPort">
<soap:binding
style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="GetTagValue">
<soap:operation soapAction="http://localhost/GetTagValue" style="rpc"/>
<wsdl:input>
<soap:body
use="encoded"
namespace="http://localhost/"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</wsdl:input>
<wsdl:output>
<soap:body
use="encoded"
namespace="http://localhost/"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</wsdl:output>
</wsdl:operation>
</wsdl:binding>

At the end of the WSDL file is the most interesting part. This small block of code ties the operations defined above to the actual realm that will be called from our external program. Note the name - this will appear again in the next step which creates the VTScada module to handle the requests. Also note the appearance of the realm name after the domain when defining the address for the SOAP requests.

<wsdl:service name="TagQueryServices">
<wsdl:port
name="QueryServicesPort"
binding="tns:QueryServicesSoapBinding">
<soap:address
location="http://localhost/QueryServicesRealm/"/>
</wsdl:port>
</wsdl:service>

To finish the file, close the tag that opened it all:

</wsdl:definitions>

Next Steps:

Create the VTScada Module


Create the VTScada Module

To fully understand the following block of code requires some knowledge of VTScada's programming language. However, the important points are easily described:

GetTagValue is the name of the subroutine which will do exactly that function: get the requested tag's value.

The ServiceActive line includes a call to the function SetWSDL. This function requires four parameters:

  • The location of the WSDL file,
  • The name of the realm,
  • The scope of the call (in this case, 'self' - the current module),
  • The name of the service - which was pointed out in the preceding section on the WSDL file

The 5th parameter is ErrMsg: a pointer to an error message to return should SetWSDL fail. While optional, this parameter is strongly recommended as it can be invaluable when debugging.

The MAIN section of the code is somewhat cryptic, but what it does is rather simple: It takes any given tag name and attempts to find the current value associated with that tag. If found, the value will be returned along with a "0" to indicate success. Otherwise, a value of "-1" is returned to indicate failure.

Text lines between braces {...} are comments.

{=========================== TagQueryServices =========================}
{ This module contains the code that implements the services provided.       }
{======================================================================}
[
  ServiceActive               { Return value from SetWSDL                    };
  GetTagValue    Module;
  ErrMsg;       { Error message from SetWSDL. Invalid if none. }
]
Init [
  If Watch(1);
  [
    ServiceActive = System.WebService\SetWSDL(
                     "file://C:/vts/Station1/TagQueryServices.wsdl",
                     "QueryServicesRealm",
                     Self,"TagQueryServices",
                     &ErrMsg);
  ]
]
<
{============================= GetTagValue ==========================}
{ Subroutine called through SOAP to request the value of a tag.              }
{====================================================================}
GetTagValue
(
  request;
  response;
)
[
  TagName;
  TagObj;
]
Main [
  If 1;
  [
    TagName = (*request)\TagName;
    TagObj = Scope(\Code, TagName);
    IfElse(Valid(TagObj), Execute(
      (*response)\TagValue = TagObj\Value; { get the tag's value }
      (*response)\ReturnCode = 0;     { success }
    );
    {Else}
      (*response)\ReturnCode = -1;    { error - tag doesn't exist }
    );
    Return (0);
  ]
]
>

Next Steps:

Modifying AppRoot.SRC


Modifying AppRoot.SRC

The final step on the VTScada side of supplying web services is to add a line to the Services section of the application's AppRoot.SRC file to tell it where to find the module created in the last step. This step is required only if you want the web service to be instantiated at start up.

For this example, it will be declared as:

[ (SERVICES) {=== Modules that are services that are started ===}
  TagQueryServices Module "TagQueryServices.SRC";
]

Again, note the name "TagQueryServices" that was defined in the WSDL file and then used again within the module TagQueryServices.SRC.

After adding this line, the application will need to be re-compiled. Stop it if it is running and run the Compile command from the VAM. You will be prompted to import the new files:

When the application starts again it will be providing a web service of returning requested tag values from our application.

Next Steps:

Requesting Values via the Web Service


Requesting Values via the Web Service

This example uses a PHP web page to interact with the VTScada web service.

The point of this example is to show that any program that can access web services can now interact with VTScada. You could call the web service from another VTScada application, from a CGI script in a web page as shown here, or from your own web-enabled application.

While the following code does work, it should not be taken as representing a fully developed application. PHP was selected for this example as it is freely available and relatively easy to use, but problems that can be traced to the PHP configuration have been reported.

Success when using web services will require that you understand the SOAP protocol support in your chosen client.

** Trihedral Engineering provides no support for programs other than VTScada. **

The process of making the call to VTScada's web services is to send a SOAP-encoded message, calling the operations that were exposed with the WSDL file. Depending on your application, you may or may not need to include a header with the SOAP-encoded message. If so, the header would look something like this:

POST /TagQueryServicesRealm/SOAP/ HTTP/1.1
Host: localhost
Content-Type: text/xml; charset="utf-8"
Content-Length: 343
SOAPAction: "http://localhost/GetTagValue"

In the case of this PHP example(*), this header is not required as the PHP SOAP client object takes care of it automatically.

<html><head><title>VTScada Web Services Tester</title></head>
<body bgcolor="#ffffff">
<?php
  echo "<h2>VTScada Web Services Tester</h2>";
  // create an instance of PHP's SOAP client object
  // the client should not need a local copy of the .WSDL. It can pull it from the server
  $client = @new SoapClient("http://localhost/QueryServicesRealm/WSDL");
  $params = array('TagName'=>'AI20_1');

  try {
    $result = $client->GetTagValue($params);
    $tagvalue = $result->TagValue;
    echo "The value of AI20_1 is ".$tagvalue;
  } catch (SoapFault $exception) {
    echo $exception;
  }
?>
</body>
</html>

Full tag names are supported. For example, to access a tag from the Completed Tutorial Example, use:

$params = array('TagName'=>'Local TCP Port\PLCSim\Pump 1\Motor Speed');

If you are attempting to follow this example and errors are returned, you are advised to do a web search using the text of those error messages. A scan of online forums related to making SOAP calls from PHP will reveal a number of common problems and solutions. Messages in your PHP error log file may also be useful for this search. In particular, be careful to configure VTScada and Apache with differing port numbers, and if VTScada is using a number other than 80, adjust the addressing in the client to match.

If security is enabled in your VTScada application, then ensure that your account has the Thin Client Access privilege and modify the SoapClient call as follows:

  $client = @new SoapClient("http://localhost/QueryServicesRealm/WSDL",
            array('login' => "Your User Name", 'password' => "Your Password"));

For the sake of simplicity in the example, no effort is made to protect the user name and password. Keep security in mind as you develop your own client application.


VTScada Engine XML API

Applications created prior to VTS 10 that used XML must be re-coded to be compatible with changes made to the API in that release.

If your goal is only to read data from an external XML source, use the JSON driver tag rather than writing code.

The XML API is used to create an XML Processor, which is a script code interface to allow an XML document to be represented in a manner that is easy for a script to access and manipulate. An XML Processor serves as a conduit between an XML document and an application that will do something with the content found in that document.

How to Access an Array Within an XML Node:

The XML code always tries to drill down into the #content member when scoping, so that retrieving the actual content of a node is a simple scope operation.

When there are multiple XML nodes with the same name, they are held as an array and can be accessed via the subscript operator []. The result will be the #content member of the XMLNode you have subscripted. To get a specific node use XMLGetNode(Node[x]) to "defeat" the automatic scoping into the #content member.

To determine if an item is an XMLNode or an array of nodes use ValueType(*XMLNode). For example, ValueType(*SomeArrayNode) returns #VTypeXMLNode (51) as it is an XMLNode, but ValueType(*NonArrayNode) does not. Note that you must use the "*" dereference operator to dereference the pointer that holds the array or XMLNode. Check only for #VTypeXMLNode because, if it is not an XMLNode, then the type could vary.

To determine how many nodes are in the array use ArraySize() on the result of an XMLGetNode call that does not include a subscript operator: ArraySize(XMLGetNode(XMLNode));


Validating versus non-Validating XML Processors

The XML Processor can be either validating or non-validating, depending on whether it has an optional schema cache as specified in a module designated as a Schema Cache Dictionary. If it is created to have a schema cache, it is a validating processor.

A non-validating XML Processor checks the XML supplied to it for being "well-formed", meaning that the XML is syntactically correct.

A validating XML Processor goes further by checking that the structure of the supplied XML conforms to the structuring rules specified by the schemas. To do this, the XML Processor’s schema cache must be given all the schemas referenced by the XML, and all the schemas referenced by the added schemas. (Note: the root XML schemas are excepted since these are already built-in to the XML Processor)

A validating XML Processor also creates type definitions for all structures described by the schemas. These type definitions are added to the Namespace Schema Cache.

When a non-validating XML Processor successfully parses the XML supplied, it generates an XMLNode Tree.

When a validating XML Processor successfully parses the XML supplied, it generates an XMLNode tree. Any type definitions encountered will be added to the Namespace Schema Cache.

For further information on XML Schemas, refer to the following two resources:

http://www.w3.org/2001/XMLSchema

http://www.w3.org/2001/XMLSchema-instance


The Schema Cache Dictionary

This is a dictionary of namespaces, keyed by XML namespace. As "SchemaCacheDictionary" it is required by the XMLProcessor function, which creates an XML handle. The contents of a schema cache dictionary are XMLNode representations of the XML types.

The schema cache dictionary replaces the ClassFactory, which was used in versions of VTS prior to 10.0


XMLNodes

An XMLNode has 6 members known respectively as: #content, #attribs, #namespace, #control, #cdata and #comment. If an XML tag has child tags, then they are represented as additional members of the structure.

For example, given the following XML code:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Simple XML to do a test for well-formedness -->
<catalog>
  <book id="book42">
    <author>Pomeroy, Steve</author>
    <title>RPC Manual</title>
    <genre>SCADA Software</genre>
  </book>
</catalog>

This would be represented in VTScada by the following XMLNode structure:

The fact that the #content member is at subscript [0] enables script code to take advantage of automatic subscription into arrays, to refer to the #content member of any node just by specifying the node. For example, to access the book title, assuming the XMLNode tree is held in variable "XMLNodes", use the following code:

XMLNode\catalog\book\title

All other members can be accessed via Scope():

Scope(XMLNode\catalog\book, "#attribs")

Both these constructs can be used on either side of an assignment.

The purpose of the 6 standard members of the structure are as follows:

Member Name | Purpose
#content | The textual content of the tag.
#attribs | A dictionary containing the attributes of the tag.
#namespace | A string representing the namespace the tag belongs to.
#control | An internal use field. Used by XMLWrite to spot loops.
#cdata | A string representing any CDATA associated with the tag.
#comment | A string representing a comment associated with the tag.

All members can be both read from and written to, but note that the #control member will be altered by XMLWrite() when processing the XMLNode tree. As each node is visited, the #control member is set to a unique value for that call to XMLWrite(). If a node already has the unique value when visited then a loop has been found and writing terminates at that point. An error is returned.

Accessing a portion of an XMLNode tree.

Take care when writing code to access a portion of an XMLNode tree. You should use either the address-of operator (&) to pass a pointer, or use XMLGetNode() to extract the node of interest:

MySub(&(XMLNode\catalog\book));

or

MySub(XMLGetNode(XMLNode\catalog\book);

Note that the first version will require the use of the dereference (*) operator on every access.


Obtain a list of child tags

When code requires a list of all the child tags in a tag use the ListKeys() function. This will also return the ‘fixed’ members of the structure. Child members can be found starting at subscript [6] if the keys are returned in creation order by setting the Order parameter of ListKeys() to ‘TRUE’.

Example:

Members = ListKeys(XMLNode\catalog\book, 1);


Determine if a member is an XMLNode or an array of nodes

When an XMLNode contains multiple instances of tags with the same name, then these are represented in the XMLNode tree by the member containing an array of XMLNodes. For example, given the following XML and its XMLNode representation of the price tag:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Simple XML to do a test for well-formedness -->
<catalog>
  <book id="book69">
    <author>Pomeroy, Steve</author>
    <title>RPC Manual</title>
    <price currency="GBP">44.95</price>
    <price currency="CAD">89.95</price>
  </book>
</catalog>

To determine if a member is an XMLNode use XMLGetNode():

Var1 = Valid(XMLGetNode(XMLNode\catalog\book));
Var2 = Valid(XMLGetNode(XMLNode\catalog\book\price));

Var1 will be set to ‘TRUE’, Var2 will be set to ‘FALSE’.


Assign values to an array of XMLNodes

When assigning values to an array of XMLNodes, such as the price array in the previous topic, neither ArrayOp1() or ArrayOp2() can be used. Instead, a While or Do loop must be used.


Add or delete child tags

Members are added using XMLCloneNode() and removed with XMLDeleteMember(). XMLCloneNode() takes a dictionary of new members and their values and adds them to a copy of the specified node which is then returned as a result of the call. This enables addition of multiple members at the same time:

MembersDict = Dictionary(0);
MembersDict["ISBN"] = XMLCreateNode("01234567890");
MembersDict["SubTitle"] = XMLCreateNode("All the RPC you’ll ever need!");
XMLNode\catalog\book = XMLCloneNode(XML\catalog\book, MembersDict);

Results in the following XMLNode tree (building on the book example shown in earlier topics).

Deleting a member requires the use of XMLDeleteMember() specifying the XMLNode and the member, as shown:

XMLDeleteMember(XMLNode\catalog\book, "ISBN");

Note that the deletion is done ‘in-place’.


XML Namespaces

Namespaces are used to avoid ambiguity between XML elements of the same name. An XML Namespace is often specified as URI Closed Uniform Resource Identifier. URIs Identify, whereas URLs Locate. In many cases, a URI looks a lot like a URL.. Such a URI might typically look like:

http://schemas.xmlsoap.org/wsdl/http/

Namespaces are declared with an associated prefix that is then applied to a tag. When the XMLNode representation is constructed, the prefix is removed and the namespace corresponding to the prefix is set in the #namespace member of the node. When writing out an XMLNode tree, a namespace dictionary is supplied, often the same one produced when parsing the incoming XML that indicates the prefixes to be used for each namespace.

Although multiple prefixes could be used for a single namespace, on writing out the XMLNode tree only the first prefix added to a namespace dictionary is used. The following XML uses namespaces and the subsequent images show the XMLNode representation and the namespace dictionary.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Simple XML to do a test for well-formedness - should work -->
<ans:catalog xmlns:ans="http://trihedral.com/enginetests/XML">
  <ans:book id="book69">
    <ans:author>Pomeroy, Steve</ans:author>
    <ans:title>RPC Manual</ans:title>
    <ans:genre>SCADA Software</ans:genre>
    <ans:price>44.95</ans:price>
    <ans:publish_date>2006-01-19</ans:publish_date>
    <ans:description>A guide to VTScada RPC.</ans:description>
  </ans:book>
</ans:catalog>


The VTScada Wizard Engine

A Wizard wraps up a configuration task into a series of steps where input validation can be made at each stage and the user is free to go back and alter previously entered information until the Wizard is finalized. A simple, uncluttered user-interface makes the Wizard particularly suitable for guiding inexperienced users through complex procedures.

VTScada provides a Wizard Engine that manages the task of steering your module through its various states. The Wizard Engine also provides several useful support functions.

VTScada includes a wizard template that has been provided to assist programmers in creating their own wizards. This template is installed with the VTScada software, and can be found in the Example folder within the VTScada installation directory: C:\VTScada\Examples\Wizard.SRC.
You can import this module as a page in the Idea Studio (File menu >> Import). Make sure that you add the page to the menu, then close the Idea Studio and open the wizard page. The sample wizard will open in a pop-up, demonstrating several features that you can use in your own wizards. (Wizard pages are generally not added to the menu, but rather are opened explicitly, when required.)
To see the example code in action, you should comment out the two parameters and in the CreateAndSaveTag state, change the tag type from the mythical "SampleTag" to "ContextType".

The WizardEngine includes a public constant named "Version", so that scripts can handle future changes to the WizardEngine functionality. This property was introduced at version 2. The absence of this property indicates version 1.


Getting Started

A Wizard is a module that runs in its own window. The recommended way of structuring the Wizard module is to have an outer module with two states, with all the necessary initialization done on the transition between these, and a child module containing the Wizard code, which is launched as the final step. For these notes, the use of this model is assumed. The term "Parent" refers to the outer module, and "Wizard" refers to the Wizard code module.

Parent Module, parameters and variables:

If you intend to pass parameters to the Wizard, do so as you would for any module:

{  Receive any required parameters from the calling environment ...  }
(
  Param1;
  Param2;  { etc as required. }
)
  Constant LHS     = 8    { LHS of the message panel                       };
  Constant TOP     = 60   { Top of the message panel                       };
  Protected BOT           { Y coord of horiz line above buttons            };
  Protected RHS           { RHS of the drawing panel                       };
  Protected MID           { Centre of drawing panel                        };
  Protected Split         { Horizontal division of drawing panel           };
  Root                    { Object value of Wizard - useful for tag config  };

Window Parameters

If running the Wizard in its own window, the recommended window parameters are:

  Width  = 520;
  Height = 360;
  Style  = 0b1010010100000111;

Note that the height of the top and bottom bars of the window are fixed at 30 and 40 pixels respectively.

Alternatively, you can run a Wizard within a Display Manager page. To do this, the following attributes should be defined in the page's source file:

Constant PageWidth  = 520;
Constant PageHeight = 360;
Constant WinFlag    = 1;
Constant PageStyle  = 0;
Constant PagWinOpt  = 0b1010010100000111;
Constant NoStretch  = 1;
Constant Bitmap;
Constant Color      = -17 { Background color for page - #SYSCOLOR_BUTTONFACE };
SecBit                    { Set page security as required                    };
WindowCloseFlag     = 1   { Flag tells DispMgr not to close our window       };

Tag Configuration

In general, if the Wizard is being used to perform Tag configuration then the simplest way to do this is to start the Wizard with a Parms array parameter of the correct size for the Tag type and to fill in the Parms array as you proceed. It is usually possible to call a Tag's ConfigFolder since (with Root pointing to Self and the Parms array provided) the calling environment is correct. If it is required to configure multiple Tags, then create multiple parameter arrays and swap them in and out of "Parms" as needed.

{== Sample variables for tag configuration ===============================}
{ Parameter indices - these are standard, add others as required          }
  Constant #Name        = 0;
  Constant #Area        = 1;
  Constant #Description = 2;
  #IODevice;
  Protected TmpCfg;
  Parms;
{============== End parent module variable declarations ==================}
]

Parent Module Initialization

The Parent performs the initialization of resources required by the Wizard. It is also likely that in its main state, it has to monitor a Cancel flag and to tear down the structure if the flag is set.

If running as a Display Manager page, the Init state should launch the Wizard child module before running the main state, which will watch for a Cancel from the user. If running as a Window, the main state should call the Window function, passing the Wizard child module as a parameter.

The example wizard (C:\VTScada\Examples\Wizard.SRC) shows how to write code that can be used either way. The following assumes the Wizard will run in a Display Manager page.

WizardInit [
  If 1 WizardMain;
  [
    { Setup instance }
    SetInstanceName(Self, \SecurityManager\GetAccountID());
    { Setup some basic metrics }
    RHS = PageWidth - 8;
    BOT = PageHeight - 40;
    MID = Int(PageWidth / 2);
    Split = MID + 40;

If you are going to be configuring Tags, then you will likely need a parms array and various offsets into that array. You can establish these dynamically as follows...

    { Get a module/object handle to the required tag type, where "SampleTag"
      is to be replaced by the module name of the type you require.         }
    TmpCfg    = Scope(\Code, "SampleTag");

    { Get its parameter indices }
    #IODevice = GetDefaultValue(FindVariable("#IODevice", TmpCfg, 0, 0));
    { ... etc. }
    Parms     = New(FormalParms(TmpCFG));

Or, alternatively:

    #IODevice = GetDefaultValue(FindVariable("#IODevice", Variable("SampleTag"), 0, 0));
    { ... etc. }
    Parms     = New(FormalParms(Variable("SampleTag")));

Finally, launch the wizard:

    { Running as a DisplayManager page - launch a Wizard }
    Wizard(Parms);
  ]
]    {===== End WizardInit ======}

Parent Module Main State

WizardMain [
  { Running as a DisplayManager page }
  If Cancel;
  [
    \DisplayManager.StopPage(Self);
  ]
]

VTScada includes a wizard template that has been provided to assist programmers in creating their own wizards. This template is installed with the VTScada software, and can be found in the Example folder within the VTScada installation directory: C:\VTScada\Examples\Wizard.SRC.
You can import this module as a page in the Idea Studio (File menu >> Import). Make sure that you add the page to the menu, then close the Idea Studio and open the wizard page. The sample wizard will open in a pop-up, demonstrating several features that you can use in your own wizards. (Wizard pages are generally not added to the menu, but rather are opened explicitly, when required.)
To see the example code in action, you should comment out the two parameters and in the CreateAndSaveTag state, change the tag type from the mythical "SampleTag" to "ContextType".


Basic Wizard Engine Module

Use only the Wizard Engine methods. Do NOT add your own state transition logic for the states controlled by the Wizard Engine.

The Wizard has a few special requirements:

  • The first step of the Wizard user interface must correspond to the first state in the module.
  • The Wizard must launch a copy of \WizardEngine into its own scope. It will need to retain the Object value to access the helper modules.
  • Several variables will be required to be passed to the instance of \WizardEngine for control of the actions of the Wizard.
  • The Wizard must have a state named, "Finish". This is not necessarily the final state in the Wizard, but is the final step of the user interface. As many additional states as are required to perform the Wizard's completion tasks may come after the "Finish" state.
  • If the Wizard is to perform Tag configuration, it may be useful for the Wizard to be instantiated with a suitable Parms array and a Root variable so that it can impersonate a tag instance.

In practice, the Wizard module starts at its first state and is then navigated between its various states by the controlling WizardEngine, which responds to the user's use of the "Next" and "Back" buttons, as well as providing the programmatic flow control. After the Wizard reaches its "Finish" state, and the user presses the "Finish" button, the Wizard then does whatever is required to perform its required operations. There is no going back from this point. The Wizard must complete its task. All necessary validation must be performed prior to the Wizard reaching the Finish state.

The Wizard has to launch a copy of the WizardEngine on entry to its first state, typically:

<
{========================= Wizard ===========================}
{ The Wizard serialization module.                          }
Wizard
(
  Parms;
)
[
  Protected Engine    { Instance of the WizardEngine        };
  Protected Trig      { Trigger for input field completion  };
  Protected Msg       { Current message to display          };
  {                                  }
  {  Other variables as required... }
  {                                 }
]

The Wizard Engine has the following parameters:

  • WizardName: A text value setting the name for this particular Wizard.
  • WizBmp: An image value of a graphic that will be displayed at the first and last steps of the Wizard (see the notes later in this topic for sizing information).
  • pState: A pointer to a variable that is set by the WizardEngine to the name of the next state that the Wizard should execute.
  • pMove: A pointer to a variable set by the WizardEngine as a trigger when the Wizard is required to change states. The actual value of the trigger provides further information, if required, about the direction of movement, and so forth.
  • pClose: A pointer to caller's close flag - set by engine.
  • pTitle: A pointer to the caller's current title string. This will be displayed in the header.
  • LogoBmp: An image value of a graphic that will be displayed at the RHS of the header bar. If Invalid, the VTScada logo will be shown.
  • AppName: A text value that will be displayed as the initial title and at the bottom left of other screens. Defaults to the current application name if invalid.
Init [
  If !Valid(Engine);
  [
    Root = Self();
    Engine = Launch(Scope(\Code, "WizardEngine"), Self, Self,
                GetDefaultValue(FindVariable("Title", Self, 0, 1)),
                MakeBitmap(FileFind("C:\VTScada\Resources\WizVTS.jpg", 0)),
                &nextState,
                &Move,
                &Close,
                &WTitle);
  ]
  WTitle = ConCat("This wizard is a template for a new Wizard.",
                  CRLF, CRLF, CRLF, CRLF,
                  "Press NEXT to continue");
  If Move;
  [
    Move = 0;
    ForceState(NextState);
  ]
]

The sample code above, running in a page titled "Wizard Template" in an application named "Bedford" produces the following result.

The example above is only a portion of a wizard module.
VTScada includes a wizard template that has been provided to assist programmers in creating their own wizards. This template is installed with the VTScada software, and can be found in the Template directory within the VTScada installation directory: C:\VTScada\Example\Wizard.src.

With regards to the image above:

  • The image is scaled so that its height fits the vertical space between the title bar and the bottom bar. The aspect ratio then determines the positioning of the RH panel. To avoid distortion, it is best to size the image exactly. The bottom bar is 40 pixels high.
  • The large title "Bedford" comes from the "AppName" parameter.
  • In this instance, the "WizardName" parameter is "Wizard Template" (obtained from the DisplayManager page name), and this string is used in the window caption and the "Welcome to…" message.
  • The remainder of the text comes from the variable addressed by the pTitle parameter. Note the use of CRLF (defined as:
Constant CRLF = Concat(MakeBuff(1, 13), MakeBuff(1, 10));

to achieve vertical spacing).

Let's review the state code:

If Move;
[
   Move = 0;
   ForceState(NextState);
]

This is the basic Wizard control. When the Next button is clicked, the variable "Move" (the "pMove" parameter to the WizardEngine) will be set to non-zero, and the variable "NextState" (the "pState" parameter to the WizardEngine) will be set to the name of the next state to be used. So, the remaining code for a simple Wizard could be:

StateTwo [
   WTitle = "We are at the second step.";
   If Move;
   [
      Move = 0;
      ForceState(NextState);
   ]
]
ThirdStep [
   WTitle = "We are now at the third step.";
   If Move;
   [
      Move = 0;
      ForceState(NextState);
   ]
]
Finish [
   If Move;
   [
      Move = 0;
      ForceState(NextState);
   ]
]
DoLotsOfWork [
  If 1 MoreWork;
  [
.. .. .. .. ..

Note that a title is not required for the "Finish" step, as the WizardEngine generates standard text.

Related Functions:

Error Messages [Error] | Dead Ends [NoNext]
Skipping [SkipIf] | Dead Ends [NoBack]
Branching [Switch] | Initial Action [InitCheckBox]
Triggered Branch [ForceMove] | Final Action [FinalCheckBox]
Unconditional Branch [NextIs] | Final Processing Stage [EndControl]


Wizard API

The following methods are supported by the Wizard Engine. An example of each is provided in following topics.

Given a Wizard object, creating with a statement similar to the following:

    Engine = Launch(Scope(\Code, "WizardEngine"), Self, Self,
                GetDefaultValue(FindVariable("Title", Self, 0, 1)),
                MakeBitmap(FileFind("C:\VTScada\Resources\WizVTS.jpg", 0)),
                &nextState,
                &Move,
                &Close,
                &WTitle);

Then, each of these methods would be invoked as follows:

Engine\Method(Parameters);

Error dialog

Error(
       Msg1 { First line of error message},
       Msg2{ Second line of error message},
       Msg3{ Third line of error message}
      );

Usage: Script

Causes an error message dialog to display and cancels the current state change. Up to three lines of error message are displayed depending on the number of parameters. This is a subroutine message, pausing execution until the error message is acknowledged.

Final Check Box

FinalCheckBox(
               Value  { Initial, and returned, value for check box  },
               Msg    { Text message for check box                 },
               Enable { TRUE to enable the display of the check box }
             );

Usage: Steady State

Enables caller to define a check box for the final wizard screen, stating, "Do this when the wizard finishes".

May be used only in the at the end of the wizard process.

Force Move

ForceMove(
           MoveNow  { If valid TRUE, then trigger the state change now },
           NewState { New target state name }
          );

Initial Check Box

InitCheckBox(
              Value  { Initial, and returned, value for check box  },
              Msg    { Text message for check box                  },
              Enable { TRUE to enable the display of the check box }
            );

Usage: Steady State

Enables the caller to define a check box for the first wizard screen, saying: "Do this when the wizard starts" ...

Valid only when used at the start of the wizard.

Next Is

NextIs(
        NewState { New target state name }
       );

Usage: Steady State

Specify (change) the next state in the wizard flow. (The default is the next state in the source code file.)

No Back

NoBack(
       Inhibit { While valid & TRUE, the "Previous" button is disabled. }      );

Usage: Steady State

May be used to prevent a return to the previous state.

No Next

NoNext(
        Inhibit { While valid & TRUE, the "Next" button is disabled. }
     );

Usage: Steady State

May be used to prevent forward progress until the operator provides information in the current state.

Skip If

SkipIf(
        Condition { If TRUE, then switch to NewTarget state },
        NewTarget { Optional target for the switch.
                    Defaults to the next state. }
      );

Usage: Steady State

Evaluates its first parameter and, if true, causes an immediate state change to the second parameter (or the next state). Note that the current state is not added to the history (does not become the previous state).

Switch

Switch(
        Labels       { Array of short label for radio buttons   },
        Bmps         { Array of bitmap values for icons (32*32) },
        Descriptions { Array of descriptive texts
                      (max is 4 lines each)                     },
        Destinations { Array of target state names              },
        DefaultVal   { Optional, default initial choice         },
        BottomMargin { Optional, padding to add to bottom       }
       );

Usage: Steady State

Displays a set of radio buttons and sets the next state change according to the chosen option. Explanatory text and an optional icon are displayed for each button.

Trim

Trim(
      TextString
    );

Usage: Script

A subroutine that removes leading & trailing whitespace from string, returning the result.

End Control

EndControl(
            HideOverlay { Boolean. Set TRUE to hide the overlay
                          window while processing is underway (and
                          display a progress bar or other indicator)
                          Set FALSE when done to restore the
                          overlay window. },
            FinalTitle { The final title },
            FinalText  { Text to display at finish }
          );


Flow Direction

The script code in the state changes is where any work resulting from a particular state needs to be done, including validation of any entered values. Additionally, when you consider Wizard actions, it becomes clear that you need to consider the direction of flow. For example, if you move forward to a particular step, and then move back to the previous step without entering anything, you do not want the Wizard to complain, whereas you do want it to complain if you try to move forward without entering anything. Therefore, the value of Move indicates the direction of travel. Forward = 1, Backward = -1, and you can write:

If Move;
[
   IfThen(Move == Forward,
{ Perform Validation }


Text Input and Output

The WizardEngine utilizes the System.TextBox method, with which you can output multi-line text for instructions.

To collect information from the operator, you can use any of the standard input widgets, particularly members of the PTools library. With suitable code, you can also display a tab from a tag's ConfigFolder. Remember to use and check the input trigger for any fields before changing states. Because the trigger values for the standard input widgets are all set in script, you only need one trigger variable, and you can test it for simply being valid.

A good guideline to follow for laying out Wizards is to set the input controls extending 40 pixels to the right of the mid-point, and placing helper text in a TextBox that starts 48 pixels to the right of the mid-point.

The code for this example follows the image. This state also illustrates input validation, where the user must provide an answer for the field, Your Name before they may press Next.

The code for this state follows:

AskDetails [
  WTitle = "Enter your details.";
  Msg = "Please enter your name and, optionally, a few words about yourself.";
  System.TextBox(Split + 8, BOT - 10, RHS, TOP + 17, Msg, \_DialogFont, 5);
  GUITransform(0, 1, 1, 0,
               1 - LHS, TOP + 55,
               Split, 1 - (TOP + 10),
               1                        { Scale whole                    },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditField(#Area, "Your Name", 4 { Text },
                                         1 { ID }, Trig { trigger },
                                         1 { view }, 1 { Bevel }, 0 { VAlign },
                                         1 { AlignTitle }, Invalid {Min},
                                         Invalid {Max}, 1 {PrivNotReqd}));
  GUITransform(0, 1, 1, 0,
               1 - LHS, TOP + 110,
               Split, 1 - (TOP + 65),
               1                        { Scale whole                    },
               0, 0, 1, 0               { No movement; visible; reserved },
               0, 0, 0                  { Not selectable                 },
               \DialogLibrary.PEditField(#Description, "Describe yourself",
                                         4 { Text }, 2 { ID }, Trig { trigger },
                                         1 { view }, 1 { Bevel }, 0 { VAlign },
                                         1 { AlignTitle }, Invalid {Min},
                                         Invalid {Max}, 1 {PrivNotReqd}));

  If Move && PickValid(Trig != 0, 1);
  [
    IfThen(Move == Forward,
      Engine\Trim(&Parms[#Area]);
      Emsg = Invalid;
      IfThen(PickValid(Parms[#Area] == "", 1),
        Emsg = "I do need to know your name.";
      );
      Engine\Error(Emsg);
    );
    Move = 0;
    ForceState(NextState);
  ]
]


Cleaning Up Input [Trim]

The Wizard Engine provides a subroutine method, "Trim", which will remove leading and trailing spaces from a string. Trim takes a single parameter, a pointer to a string, which is updated in place by the Trim method.

  If Move;
  [
    IfThen(Move == Forward && PickValid(Trig != 0, 1),
      Engine\Trim(&Username); {trim leading & trailing whitespace}
      IfElse(PickValid(Username, "") == "",
        Engine\Error("A username is required");
        … … …


Error Messages [Error]

If validation is performed when leaving a state, then there is a need to be able to issue an error message to the user and cancel the move to the next state. This function is provided by the WizardEngine's "Error" method.

The "Error" method takes one, two, or three parameters, being the first, second, and third lines of a 4BtnDialog. Calling "Error" will cause the dialog to display and the state move canceled.

You must call "Error" before you call "ForceState".

Example:

If Move;
[
IfThen(Move == Forward && PickValid(Trig != 0, 1),
  IfElse(PickValid(Username, "") == "",
    Engine\Error("A username is required.");
   { Else }
    IfElse(PickValid(Password, "") == "",
      Engine\Error("A password is required.");
    { Else }
      IfThen(!Valid(PasswordConfirm) || (Password != PasswordConfirm),
        Engine\Error("Passwords do not match.");
      );
  ));
);
Move = 0;
ForceState(NextState);
]


Skipping [SkipIf]

Sometimes it is necessary to skip a particular step, if some condition is true. The WizardEngine method "SkipIf" performs this function. If its first parameter evaluates to true, then "Move" and "NextState" are immediately set to cause transition to the next state in the current direction of travel. Because it may also be necessary to skip validation rules, the "Move" variable is assigned a value to indicate that skipping is taking place. Move will be set to 2 if skipping forward and -2 if skipping backward.

The second (optional) parameter enables the destination state to be specified. This method is either a subroutine or a steady-state call.

GetTagName [
   Engine\SkipIf(Valid(TagName), "GotTagName");
   GUITransform(0, 1, 1, 0,
… … …


Branching [Switch]

More useful than simple skipping is to present the user with a set of choices, and to branch the flow as requested. The WizardEngine provides a method named, "Switch" for this purpose. The parameters to "Switch" are:

  • Labels: An array of labels for the radio buttons.
  • Bmps: An array of image values for the icons (32*32 images).
  • Descriptions: An array of descriptions (up to four lines of text can be accommodated).
  • Destinations: An array of state names.
  • DefaultVal: An optional parameter that is the value (0..2) of the initial selection.
  • BottomMargin: An optional parameter specifying the padding at the bottom of the wizard.
  • EnableFlags: Arrays of TRUE/FALSE flags to determine which radio buttons are enabled/disabled.
  • ToolTips: Phrase labels to display in the tooltips for the individual radio buttons

A maximum of five choices can be accommodated. Assuming that suitable variables were declared and initialized:

Tasks         = New(3);
TaskDescs     = New(3);
TaskBmps      = New(3);
TaskSwitch    = New(3);
Tasks[0]      = "Choice 1";
Tasks[1]      = "Choice 2";
Tasks[2]      = "Choice 3";
TaskBmps[0]   = MakeBitmap(FileFind("C:\VTScada\Resources\Copy.png", 0))
TaskBmps[1]   = MakeBitmap(FileFind("C:\VTScada\Resources\Cut.png", 0))
TaskBmps[2]   = MakeBitmap(FileFind("C:\VTScada\Resources\Paste.png", 0))
TaskDescs[0]  = "Selecting this will take you down path number one.";
TaskDescs[1]  = "Selecting this will take you down path number two.";
TaskDescs[2]  = "Selecting this will take you down path number three.";
TaskSwitch[0] = "Switch1";
TaskSwitch[1] = "Switch2";
TaskSwitch[2] = "Switch3";

Then the state for the branch might appear as follows:

SelectTask [
  WTitle = "Select Required Task";
  Task = Engine\Switch(Tasks, TaskBmps, TaskDescs, TaskSwitch, SvTask);
  If Move;
  [
    SvTask = PickValid(Task, 0);
    Move = 0;
    ForceState(NextState);
  ]
]

Example:

"Switch" returns the value (0..2) selected.


Triggered Branch [ForceMove]

Sometimes it may be necessary to force a change of Wizard state without waiting for the user to click the "Next" button (for example, the user may double-click some item in a list box and expect some response). The method "ForceMove", which takes two parameters, performs this task. The second parameter enables the destination state to be specified. The first parameter triggers the state switch. The method is a steady-state call and only works in a forwards direction.

PersonDetails [
   Engine\ForceMove(DClick, "EditPerson");
   If Move;
… … …


Unconditional Branch [NextIs]

When flow has been branched using the "Switch" method, it is likely that there will be a need to use an unconditional branch to re-merge the flow. The WizardEngine provides a method named, "NextIs", which changes the destination state for the step from the default (next state), to the state whose name is provided as the first parameter of the "NextIs" method. The method is a steady-state call.

Example:

Engine\NextIs("StateName");


Dead Ends [NoNext]

There are situations when validation determines that the user can go no further down his chosen path until he goes back and changes something. The WizardEngine provides a method named, "NoNext", which causes the "Next" button to be disabled. This method takes a single parameter which should be set to TRUE to disable the "Next" button. The method is a steady-state call.


Dead Ends [NoBack]

If used, the method NoBack will inhibit the Back button until the next (forward) state change. Generally, this is not a desirable action in a wizard. Before using this feature, please consider the options provided by the EndControl method first.


Initial Action [InitCheckBox]

There is sometimes a need to give the user some option about some action when the Wizard starts. The WizardEngine provides a method InitCheckBox for this purpose. It takes three parameters:

  • Value: The initial value for the check box, and the returned value.
  • Message: The message/label attached to the check box.
  • Enable: If true, then the check box is displayed.

This method should only be called from the initial state (it will be disabled otherwise).

Init [
  { Initial step }
  Engine\Initcheck box(tellme, "Tell me about alternatives to this Wizard", Valid(tellme));
  If Move;
  [
    ForceState(NextState);
    IfThen(Move == Forward,
.. .. ..


Final Action [FinalCheckBox]

There is sometimes a need to give the user options for actions to perform when the Wizard completes. The WizardEngine provides a method named, "FinalCheckBox" for this purpose. It takes the following three parameters:

  • Value: The initial value for the check box, and the returned value.
  • Message: The message/label attached to the check box.
  • Enable: If true, then the check box is displayed.

This method should only be called from the "Finish" state. It will otherwise be disabled.

Finish [
{ Final Step }
   Engine\Finalcheck box(RunNow, "Run the report when the wizard finishes", Valid(RunNow));
   If Move;
   [
      ForceState(NextState);
      IfThen(Move == Forward,


Final Processing Stage [EndControl]

The default flow of the wizard is that the user can move freely back and forth between the Init state and the Finish state. When the user clicks the Finish button, there is no more interaction with the user and the wizard window closes after any residual processing is complete.

If the final processing is likely to take some time, it is good user interface design to present a progress indication while processing completes, and then have a final landing point when everything is finished.

The method EndControl will alter this final stage. It takes three parameters:

  • HideOverlay valid and non-zero to hide the final window overlay
  • FinalTitle a text string to override the default title on the final screen
  • FinalText a text string to override the default text on the final screen

Notes:

  • If any of these parameters is invalid, that parameter is ignored
  • The two character sequence "^W" in the FinalTitle will be replaced by the Wizard’s name

This method is as follows:

When moving forward from the Finish state (i.e. the Finish button has been clicked) call EndControl(1) to hide the overlay window. This will return the wizard display to be that which normally shows between the start and finish states. Your wizard code can now draw text, progress bars etc to keep the user informed.

You can change states (using the ForceState method to do this) and this window will remain on display.

When all processing is complete, change to a final state and call EndControl(0, "Title", "Message"). The window will change to the usual final screen, except that you can (optionally) replace the title and message text. The only button that is enabled is the Finish button and when this is clicked, you should terminate the wizard.

The following code sample is an example of using these features. In this example, the normal finish screen shows the Finalcheck box. If it is checked, then the wizard enters the two stage finish.

Finish [
  Msg = "This is the final state in the Wizard." + CRLF + CRLF +
        "However, if you wish to test the extended finish " +
        "features, then tick the check box.";
  Engine\EndControl(Invalid, Invalid, Msg);
  Engine\FinalCheckBox(ExtendedFinish, "Use extended finish", 1);
  Engine\NextIs(ExtendedFinish ? "LongFinish" : "AllDone");
  If Move;
  [
    Move = 0;
    ForceState(NextState);
  ]
]

LongFinish [
  WTitle = "Extended Finish";
  Msg = "We are waiting here for 10 seconds to simulate ongoing background tasks." + CRLF + CRLF +
        "At the end of that time we will automatically advance to the end of the Wizard.";
  System.TextBox(LHS, TOP + 65, RHS, TOP + 17, Msg, \_DialogFont, 5);
  Engine\EndControl(1 {Hide Overlay});
  Engine\ForceMove(TimeOut(1, 10), "DoneDone");
  If Move;
  [
    Move = 0;
    ForceState(NextState);
  ]
]

DoneDone [
  Engine\EndControl(0 {Unhide overlay}, "The ^W is totally finished!", "We really are all done now." + CRLF + "Thank you for your patience.");
  If Move;
  [
    Move = 0;
    ForceState(NextState);
  ]
]

AllDone [
  If !Cancel;
  [
    { All done now, let’s get out of here }
    Cancel = 1;
  ]
]


Wizard Configuration Settings

There are 5 text labels used by the Wizard Engine. These can be added to your application's Settings.Startup file.

  • WizardWelcomeTitle = Welcome to the ^W.
  • WizardFinishText1 = The Wizard has acquired all necessary information.
  • WizardFinishText2 = Press FINISH to complete the operation, BACK to change parameters or
  • WizardFinishText3 = CANCEL to abort the operation without making any changes.
  • WizardFinishTitle = The ^W is ready.

Note that the sequence "^W" in WizardWelcomeTitle and WizardFinishTitle will be replaced by the name of the Wizard.


Cautionary Notes for Wizards

There are several dangers that you should keep in mind when creating a Wizard.

Loops

It is possible to use the "Switch", "ForceMove", and "SkipIf" methods to create a Wizard structure where the user can go round a loop several times. The WizardEngine attempts to recognize when a sequence of steps is being repeated, and to delete the duplicates from the history, so that when you use the "Back" button, you just go round the loop once.

State Changes

Do not be tempted to set your own state changes in your Wizard code. The WizardEngine methods must be called for all state changes while the "Next" and "Back" buttons are active. However, after you have moved to the state after your "Finish" state, then you are in control, and not only must you control all state changes, but you must also arrange termination after you are done (i.e. set the "Cancel" flag). Note that if you use the EndControl method to allow progress to display after the finish state, then you must continue to use Wizard logic to change states until you call EndControl(0).

Validation

You must fully validate all user input before reaching the "Finish" state. when you reach this state and the user clicks "Finish", you must complete the programmed task. There is no going back, and no opportunity for error exits.

Remember to use the Trim method before testing for null input .


Index

*

*-REALMFILTER [*-REALMFILTER] Section

.

.Dynamic Configuration File Structure
.Startup Configuration File Structure

[

[HTTP-Unauthenticated] [HTTP-Unauthenticated] Section
[ReferenceTypeDefaults] Section Names

\

\LocalGUID GetGUID

#

4BtnDialog 4BtnDialog
65282 Class Declarations for Modules in AppRoot

A

a unit conversion Calculations & Operations Columns
ABB Totalflow Driver ABB Totalflow Driver
ABDF1IgnoreAckNak ABDF1IgnoreAckNak
ABDF1SerialMessages ABDF1SerialMessages
ABFailoverCount ABFailoverCount
Abs Abs
ABSharedRPC ABSharedRPC
AbsTime AbsTime
AcceptSecurityContext AcceptSecurityContext
Account Modify Privilege System Privilege Reference for Developers
Account View Privilege System Privilege Reference for Developers
AccountLockoutTime AccountLockoutTime
AccountRateWindow AccountRateWindow
Accounts Accounts and Roles
accounts Create Accounts and Roles
Accounts.Dynamic - defined Application Files and Folders
accounts.dynamic - definition Account Storage
AccountsChangeDlgWait AccountsChangeDlgWait
Accumulate Accumulate
ACE Motorola IP Gateway Tags
Ack The Alarm Page , Ack
ack all button Ack All Button
ack selected button Ack Selected Button
ack shown button Ack Shown Button
AckAllAcksOnlyVisible AckAllAcksOnlyVisible
AckAllAlarms AckAllAlarms
AckAllAlarmsPlusDlg AckAllAlarmsPlusDlg
AckAllRequiresConfirmation AckAllRequiresConfirmation
Acknowledge Acknowledge
ACos ACos
AcquireLock AcquireLock
ActivateProgressDelay ActivateProgressDelay
Active Active
active alarm list List Options for Alarms
active indicator widget Active Indicator Widget
ActiveAlarmFlash ActiveFlashRate
ActiveCode ActiveCode
ActiveCommColor ActiveCommColor
ActiveFlashRate ActiveFlashRate
ActiveLanguage ActiveLanguage
ActiveMonitor Obsolete Functions
ActiveState ActiveState
ActiveWindow ActiveWindow
ActiveX ActiveX
Add Equals Operators
Add Lock Button Add Lock Button Widget
add new application Add New Applications
Add Note Field Add Note Field Widget
add note widget Add Note Button
Add Parameter Expression Automated Tag Configuration
add parameter expresson Automated Tag Configuration
add server Error Dialogs (Add Server / Add Connection Address)
add start condition Automated Tag Configuration
AddAccount AddAccount
AddCertificate AddCertificate
AddConnection AddConnection
AddContributor AddContributor
AddEditorText AddEditorText
AddEvent AddEvent
addin Excel Add-in for Data Retrieval
add-in Excel Add-in for Data Retrieval
Addition Operators
AddLock AddLock
AddModule AddModule
AddOptional AddOptional
AddPageToApp Obsolete Functions
AddParameter AddParameter
AddRead AddRead
addread example Trigger a Data Read
Address Operators
Address Assist Communication Driver Tags
address suffixes Data Suffixes for Tag I/O Addressing
AddressAssist Provide an AddressAssist Module
AddressEntry AddressEntry
addressing - Allen-Bradley Allen-Bradley Driver I/O Addressing
addressing - CalAmp CalAmp Driver I/O Addressing
addressing - CIP Rockwell Driver I/O Addressing
addressing - DNP3 DNP3 I/O Addressing
addressing - MDS Diagnostic driver MDS Diagnostic Driver I/O Addressing
addressing - Modbus Plus Modbus Plus PLC Addressing
addressing - Modicon Modbus Compatible Device I/O Addressing
addressing - Siemens S7 Siemens S7 Driver I/O Addressing
addressing - workstation status Workstation Status Driver I/O Addressing
addressing scheme Design an Addressing Scheme
AddressParseErrorTimeout AddressParseErrorTimeout
AddSection SectionControl
AddState AddState
AddStatement AddStatement
AddToList AddToList
AddVariable AddVariable
ADGroupPrefix ADGroupPrefix
ADGroupSearchBase ADGroupSearchBase
AdHocAlarm AdHocAlarm
Adjust Image Adjust Image Dialog
AdjustArray AdjustArray
AdjustCode AdjustCode
administrator options Administrative Settings
Administrator Privilege System Privilege Reference for Developers
ADRefreshPeriod ADRefreshPeriod
ADUserSearchBase ADUserSearchBase
Advanced Version Control Privilege System Privilege Reference for Developers
AITrendEnable AITrendEnable
Alarm (obsolete function) Obsolete Functions
Alarm Acknowledge Privilege System Privilege Reference for Developers
alarm acknowledgement by email Allow Acknowledgment by Email or SMS Text
alarm alerts
alarm page Alarm Display & Tasks
alarm sounds Alarm Display & Tasks
spoken Alarm Display & Tasks
station page Alarm Display & Tasks
stn. symbol Alarm Display & Tasks
title bar Alarm Display & Tasks
alarm area filtering Alarm Area Filtering
alarm banner Legacy Alarm Banner
alarm database type Alarm Database Tags
Alarm Databases Alarm System Configuration
Alarm Date Selector (Legacy) Alarm Date Selector
alarm definition The Alarm Page
Alarm Disable Privilege System Privilege Reference for Developers
alarm filtering dialog (Legacy) Filter Dialog Button
alarm history list List Options for Alarms
Alarm List Alarm List
alarm list button Alarm List Button
alarm logging Alarm Data Logging
alarm notification system events Alarm Data Logging
operator control Alarm Data Logging
security events Alarm Data Logging
alarm manager Alarm Manager Service
Alarm Mute Privilege System Privilege Reference for Developers
alarm notification menu Dialing-in. The Alarm Notification System Menu
alarm notification properties Alarm Notification System Properties
alarm notification system Alarm Notification System - Alerts by Phone, Email or Text
alarm notification system tags Alarm Notification System Tags
alarm page - description The Alarm Page
Alarm Page Access Privilege System Privilege Reference for Developers
Alarm Priority Box Alarm Priority Box
Alarm Priority Icon Alarm Priority Icon , Alarm Priority Icon
alarm priority tag type Alarm Priority Tags
alarm properties Alarm Properties
Alarm Record Alarm API Structure Definitions
Alarm Reports The Alarm Page
alarm roster hierarchy rules Roster Selection Hierarchy
Alarm Shelve Privilege System Privilege Reference for Developers
Alarm Silence Privilege System Privilege Reference for Developers
alarm sounds Alarm Display & Tasks
alarm status tags Alarm Status Tags
alarm system Alarms
alarm tag widgets Alarm Tags
alarm tags Alarm Tags
alarm template hook Alarm Notification Template Hooks
alarm tools library Alarm Lists and Related Tools
ALARM_MANAGER Section Names
AlarmAckCodeAgeLimit AlarmAckCodeAgeLimit
AlarmAckCodeDigits AlarmAckCodeDigits
AlarmAckCodeTemplate AlarmAckCodeTemplate
AlarmActive I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
AlarmAutoNavEnable AlarmAutoNavEnable
AlarmAutoNavHold AlarmAutoNavHold
AlarmAutoNavTimeout AlarmAutoNavTimeout
AlarmAutoNavWindowed AlarmAutoNavWindowed
AlarmCat Obsolete Functions
AlarmCheckMail AlarmCheckMail
AlarmCheckMailFastPoll AlarmCheckMailFastPoll
AlarmColor AlarmColor
AlarmCondition AlarmCondition
AlarmDatabaseGroups Alarm Database Groups
AlarmDatabasePurgeDelay AlarmDatabasePurgeDelay
AlarmDatabasePurgeEnable AlarmDatabasePurgeEnable
AlarmDatabasePurgeRate AlarmDatabasePurgeRate
AlarmDialerStatusTemplate AlarmDialerStatusTemplate
AlarmDialerTemplate AlarmDialerTemplate
AlarmDisplayDateFormat AlarmDisplayDateFormat
AlarmDisplayTimeFormat AlarmDisplayTimeFormat
AlarmEditEmailAck AlarmEditEmailAck
AlarmEmailAckSubjectTemplate AlarmEmailAckSubjectTemplate
AlarmEmailAckTemplate AlarmEmailAckTemplate
AlarmEmailStatusTemplate AlarmEmailStatusTemplate
AlarmEmailSubjectTemplate AlarmEmailSubjectTemplate
AlarmEmailTemplate AlarmEmailTemplate
AlarmEventDesc0 AlarmEventDescX
AlarmEventDesc1 AlarmEventDescX
AlarmEventDesc2 AlarmEventDescX
AlarmEventDesc3 AlarmEventDescX
AlarmEventDesc4 AlarmEventDescX
AlarmEventDesc5 AlarmEventDescX
AlarmEventDesc6 AlarmEventDescX
AlarmEventDesc7 AlarmEventDescX
AlarmEventDesc8 AlarmEventDescX
AlarmEventDesc9 AlarmEventDescX
AlarmEventDesc10 AlarmEventDescX
AlarmEventDesc11 AlarmEventDescX
AlarmEventDesc12 AlarmEventDescX
AlarmEventDesc13 AlarmEventDescX
AlarmEventDesc14 AlarmEventDescX
AlarmEventDesc15 AlarmEventDescX
AlarmEventDesc16 AlarmEventDescX
AlarmEventDesc17 AlarmEventDescX
AlarmEventDesc18 AlarmEventDescX
AlarmEventDesc19 AlarmEventDescX
AlarmEventDesc20 AlarmEventDescX
AlarmEventDesc21 AlarmEventDescX
AlarmEventDescX AlarmEventDescX
AlarmFlashTaskBar AlarmFlashTaskBar
AlarmFlashTaskBarOnVIC AlarmFlashTaskBarOnVIC
AlarmFlashTime AlarmFlashTime
AlarmFlashTitleBar AlarmFlashTitleBar
AlarmFlashTitleBarOnVIC AlarmFlashTitleBarOnVIC
AlarmIndDisable AlarmIndDisable
AlarmIndDisableOnVIC AlarmIndDisableOnVIC
AlarmInst Obsolete Functions
AlarmListBGColor AlarmListBGColor
AlarmListDefaultColumnFormat AlarmListDefaultColumnFormat
AlarmListDefaultSortDir AlarmListDefaultSortDir
AlarmListDefaultSortKey AlarmListDefaultSortKey
AlarmListFormats.XML. Customize Columns in Alarm Displays
AlarmManager.INI Moving to the Current Version
AlarmManager\AddEvent AddEvent
alarm-notification events Alarm Data Logging
AlarmNotifyEmailAcknowledge AlarmNotifyEmailAcknowledge
AlarmNotifySMSAcknowledge AlarmNotifySMSAcknowledge
AlarmPageBackgroundColor AlarmPageBackgroundColor
AlarmPageHistoryRecordHardLimit AlarmPageHistoryRecordHardLimit
AlarmPageHistoryRecordLimit AlarmPageHistoryRecordLimit
AlarmPagerStatusTemplate AlarmPagerStatusTemplate
AlarmPagerTemplate AlarmPagerTemplate
AlarmPageTextColor AlarmPageTextColor
AlarmPopupsEnable AlarmPopupsEnable
AlarmPrintPort AlarmPrintPort
AlarmPriorityDescWidth AlarmPriorityDescWidth
AlarmPriorityIndicatorColor AlarmPriorityIndicatorColor
AlarmPriorityIndicatorShowNormalUnacked AlarmPriorityIndicatorShowNormalUnacked
AlarmRPCEnable AlarmRPCEnable
alarms
spoken Configuring Spoken Alarms
AlarmSeparatorString AlarmSeparatorString
AlarmSMSAckTemplate AlarmSMSAckTemplate
AlarmSMSStatusTemplate AlarmSMSStatusTemplate
AlarmSMSTemplate AlarmSMSTemplate
AlarmSnapshotCount AlarmSnapshotCount
AlarmSnapshotInterval AlarmSnapshotInterval
AlarmSnapshotMinInterval AlarmSnapshotMinInterval
AlarmSoundCheck Obsolete Functions
AlarmSoundDisable AlarmSoundDisable
AlarmSpeechEnable AlarmSpeechEnable
AlarmSpeechInit AlarmSpeechInit
AlarmSpeechQuality AlarmSpeechQuality
AlarmSpeechTemplate AlarmSpeechTemplate
AlarmSpeechVoice AlarmSpeechVoice
AlarmStatRange0 AlarmStatRange0 - AlarmStatRange3
AlarmStatRange1 AlarmStatRange0 - AlarmStatRange3
AlarmSTatRange2 AlarmStatRange0 - AlarmStatRange3
AlarmStatRange3 AlarmStatRange0 - AlarmStatRange3
AlarmStatusDesc0 AlarmStatusDesc0 , AlarmStatusDesc0
AlarmStatusDesc1 AlarmStatusDesc0
AlarmStatusDesc2 AlarmStatusDesc0
AlarmStatusDesc3 AlarmStatusDesc0
AlarmStatusDesc4 AlarmStatusDesc0
AlarmStatusDesc5 AlarmStatusDesc0
AlarmStatusDescWidth AlarmStatusDescWidth
AlarmTemplateDateFmt AlarmTemplateDateFmt
AlarmTemplateTimeFmt AlarmTemplateTimeFmt
AlarmUnAckCondition AlarmUnAckCondition
AlarmUnacked I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
AlarmWidgetsShowUnackedNormalAlarm AlarmWidgetsShowUnackedNormalAlarm
align Align
alignment snap Align
AlignmentParameterEdit AlignmentParameterEdit
AlignSelected AlignSelected
Allen-Bradley addressing Allen-Bradley Driver I/O Addressing
Allen-Bradley comm. messages dialog Allen-Bradley Communication Messages Dialog
Allen-Bradley comm. statistics dialog Allen-Bradley Statistics Dialog
Allen-Bradley driver tag Allen-Bradley Driver
AllowedLanguages AllowedLanguages
AllowIP [RPCManager-AllowIP] Section
AllowRemoteTest AllowRemoteTest
AlmAck Obsolete Functions
AlmAckID Obsolete Functions
AlmArray Obsolete Functions
AlmCatName Obsolete Functions
AlmColor Obsolete Functions
AlmEnable Obsolete Functions
AlmList Obsolete Functions
AlmListTextColor AlmListTextColor
AlmPgStartList AlmPgStartList
AlmTone Obsolete Functions
alpha-blended window Transparent and Alpha-blended Windows
AlphaNumericXFormScheme AlphaNumericXFormScheme
Alternate Operator's Guide to Security
Alternate identification Configure Alternate Identification
AlternateLogoff AlternateLogoff
AlternateLogon AlternateLogon
alwaysShowShelved Customize Columns in Alarm Displays
AMax AMax
AMin AMin
Analog Bar & Indicator Analog Bar & Indicator Widget
analog clock widget Analog Clock
analog control tags Analog Control Tags
analog input tag Analog Input Tags
analog output tags Analog Output Tags
analog statistics tags Analog Statistics Tags
analog status tag Analog Status Tags
Analog Summary Report Report Types Described
AnalogControlName AnalogControlName
AnalogInputWidth AnalogInputWidth
AnalogScaledMaxDefault AnalogScaledMaxDefault
AnalogScaledMinDefault AnalogScaledMinDefault
AnalogStatusName AnalogStatusName
AnalogSummaryReportTimeUnits AnalogSummaryReportTimeUnits
AnalogUnscaledMaxDefault AnalogUnscaledMaxDefault
AnalogUnscaledMinDefault AnalogUnscaledMinDefault
ancestor Module Scope
And And
animated bitmap widget Animated Image Widget
AnimateState Obsolete Functions
animations - generate custom Adding Custom Animations
AnswerCalls AnswerCalls
Antique Bolted Widget Antique Bolted Gauge Widget
Antique Gauge widget Antique Gauge Widget
Anywhere Client Connect Using the Anywhere Client
App Password Google & Microsoft vs Basic Authentication
AppIsRunning AppIsRunning
AppIsStarted AppIsStarted
AppIsStarting AppIsStarting
AppKeywords AppKeywords
AppLayer Use Application Properties
Application Section Names
application manager VTScada Application Manager (VAM)
Application Manager View System Privilege Reference for Developers
application privileges Protect Pages and Output Tags
Application Stop Privilege System Privilege Reference for Developers
Application.version - defined Application Files and Folders
ApplyChangeSetFile ApplyChangeSetFile
ApplyMuteSilencePerComputer ApplyMuteSilencePerComputer
ApplyMuteSilencePerUser ApplyMuteSilencePerUser
AppRoot.src - defined Application Files and Folders
AppTheme AppTheme
Aqua Gauge widget Aqua Gauge Widget
Arc Arc
Arc widget Arc Meter Widget
are you sure - confirmation prompts Confirmation Prompts for Output Tags
AreaExclude AreaExclude
AreaFilter AreaFilter
Area-REALMAREAS [RealmName-REALMFILTER] Section
Areas Section Names
Army Gauge widget Army Gauge Widget
array Arrays
ArrayDimensions ArrayDimensions
ArrayOp1 ArrayOp1
ArrayOp2 ArrayOp2
ArraySize ArraySize
ArrayStart ArrayStart
ArrayToBuff ArrayToBuff
ArrayToDictionary ArrayToDictionary
ASDU IEC 60870-5-104 Addressing
ASin ASin
aspect ratio contraint (realm display setup) Realm Display Setup Tags
asterisk Tag Icon Marker
ATA Using VoIP for Alarm Notification
ATan ATan
attempts (login) MaxFailedLoginAttempts
Audio Call Sequence of Events for Outgoing Calls
audio discriminator Sequence of Events for Incoming Calls
audio mode, modem manager Sequence of Events for Incoming Calls
Audio Widget Audio Meter Widget
AudioFileLength AudioFileLength
Authenticate Authenticate
authentication errors Setting Up a Specific VoIP Connection
auto start [APPS] Section Variables
AutoAckClearedAlarms AutoAckClearedAlarms
AutoActivate AutoActivate
AutoAddADUsers AutoAddADUsers
AutoCommitInterval AutoCommitInterval
AutoExportToUCDelay AutoExportToUCDelay
AutoExportToUserCopy AutoExportToUserCopy
AutoLogOff AutoLogOff
AutoLogOffMax AutoLogOffMax
AutoLogOffMin AutoLogOffMin
automatic log-off Automatic Sign Out Time Period
automatically start Automatic Start
AutomaticDeploy AutomaticDeploy
Automation Interfaces Introduction to COM
AutoOpenIdeaStudio AutoOpenIdeaStudio
AutoOverrideOEMPages AutoOverrideOEMPages
AutoRecover AutoRecover
AutoStart AutoStart
AutoStartDlgTimeout AutoStartDlgTimeout
AValid AValid
AverageCPU Workstation Status Driver I/O Addressing

B

B Functions B Functions
Backlit Gauge widget Backlit Gauge Widget
BackupAlarmPriority BackupAlarmPriority
Backups Backups
BackupSwitchCount BackupSwitchCount
BACnet BACnet Driver
BACnet. statistics dialog BACnet Driver Statistics Dialog
BadQualityColor BadQualityColor
Ball Ball
Bar Bar
Bar Graph Bar Graph Widget
Base64Decode Base64Decode
Base64Decoder Base64Decoder
Base64Encode Base64Encode , Base64Encoder
Batch & Recipe Management Page The Batch & Recipe Management Page
Batch Details Page The Batch Details Page
Batch Details Widget Batch Details Widget
Batch History The Batch History Page
Batch History List Widget Batch History List Widget
Batch Setpoints Widget Batch Setpoints Widget
Batch Status Widget Recipe Batch Status Widget
BatteryLevel Workstation Status Driver I/O Addressing
BatteryLifetime Workstation Status Driver I/O Addressing
BatteryState Workstation Status Driver I/O Addressing , Workstation Status Driver I/O Addressing , Workstation Status Driver I/O Addressing , Workstation Status Driver I/O Addressing , Workstation Status Driver I/O Addressing
baud rate Serial Port Tags
Baud Rate TAPI and UniModem Considerations
Beep Beep
Bevel Bevel
binary notation Value Types
BinaryToIP BinaryToIP
binding Module Scope
BinIP2Text BinIP2Text
Bit Bit
BitmapDirExt BitmapDirExt
BitmapInfo BitmapInfo
bitmaps folder Application Files and Folders
Blend Blend
BLOB Cryptography Terms and Abbreviations
block cipher Cryptography Terms and Abbreviations
BlockDecrypt BlockDecrypt
BlockEncrypt BlockEncrypt
BlockWrite BlockWrite
blue tag fields Configuration Field Colors
Bluetooth SMS Appliance Tags
Blumenthal SNMPv3AgentWritePrivProtocol , SNMPv3AgentReadPrivProtocol , SNMPv3AgentTrapPrivProtocol
BMPath BMPath
Boolean Boolean
border (shape) Border
bottom bar widget Bottom Bar Widget
Box Box
Brain Boards Opto 22 Mux Driver
breaker Illuminated Toggle Switch Widget
breakpoint Working with Breakpoints and Data Breakpoints
bring forward Display Order
Bristol History Info Widget Bristol History Info Widget
Bristol Network Tag Bristol Network Tag
BristolFailoverCount BristolFailoverCount
Broadcast Deprecated RPC Methods
BrowserHeight BrowserHeight
BrowserWidth BrowserWidth
BrowserX BrowserX
BrowserY BrowserY
Brush Brush
Bubble Bubble
BubbleList BubbleList
BubbleQueueLength BubbleQueueLength
BubbleReceive BubbleReceive
BubbleSend BubbleSend
BuffOrder BuffOrder
BuffRead BuffRead
BuffStream BuffStream
BuffToArray BuffToArray
BuffToHex BuffToHex
BuffToParm BuffToParm
BuffToPointer BuffToPointer
BuffWrite BuffWrite
BuildDelete BuildDelete
BuildFullName BuildFullName
BuildInsert BuildInsert
BuildSelect BuildSelect
BuildUpdate BuildUpdate
bulk download Bulk Downloads of Map Tiles
ButtonFace ButtonFace
ButtonHighlight ButtonHighlight
ButtonShadow ButtonShadow
ButtonTextColor ButtonTextColor

C

C Functions C Functions
CalAmp comm. messages dialog CalAmp Diagnostic Driver Communication Messages Dialog
CalAmp diagnostic driver CalAmp Diagnostic Driver
CalAmp diagnostic driver comm. statistics CalAmp Diagnostic Driver Statistics Dialog
CalAmp driver addressing CalAmp Driver I/O Addressing
calculation tags Calculation Tags
calendar (Legacy) Alarm Date Selector
Call Call
Call Manager Status Widget Call Manager Status Widget
call progress codes Call Progress and Error Codes
Callable Subroutines Launched Versus Called Modules
CallBackScope Callbacks and Subscriptions
Called Launched Versus Called Modules
CalledInstances CalledInstances
Caller Caller
CallInterval1 CallInterval1
CallInterval2 CallInterval1
CallInterval3 CallInterval1
CallInterval4 CallInterval1
CallInterval5 CallInterval1
CallInterval6 CallInterval1
CallInterval7 CallInterval1
CallInterval8 CallInterval1
CallInterval9 CallInterval1
CallInterval10 CallInterval1
CallManagerAlarmPriority CallManagerAlarmPriority
CallManagerBadCallLimit CallManagerBadCallLimit
CallManagerShowCredentials CallManagerShowCredentials
CallMgrMaxLogAge CallMgrMaxLogAge
CallMgrTraceInterval CallMgrTraceInterval
CallMgrTraceMax CallMgrTraceMax
CallOutDelay1 CallOutDelay1
CallOutPriority CallOutPriority
Camera Tag API Camera Tag
CameraTagConnectionLimit CameraTagConnectionLimit
CampbellCheckSig CampbellCheckSig , Campbell Scientific Array Driver
CampbellCRLFWaitTime CampbellCRLFWaitTime , Campbell Scientific Array Driver
CampbellCRSendCount CampbellCRSendCount , Campbell Scientific Array Driver
CampbellCRSendWaitTime Campbell Scientific Array Driver , CampbellCRSendWaitTime
CampbellFailoverCount CampbellFailoverCount
CampbellNoLastMatchRequired CampbellNoLastMatchRequired.htm , Campbell Scientific Array Driver
CampbellProgressWindow CampbellProgressWindow , Campbell Scientific Array Driver
CampbellReadAllFirstTime CampbellReadAllFirstTime , Campbell Scientific Array Driver
CampbellReadOnStart CampbellReadOnStart , Campbell Scientific Array Driver
CampbellRTULabel CampbellRTULabel
CampbellSearchWindowSize Campbell Scientific Array Driver , CampbellSearchWindowSize
CampbellSharedRPC Campbell Scientific Array Driver , CampbellSharedRPC
CampbellTestMode CampbellTestMode , Campbell Scientific Array Driver
CanAddLock CanAddLock
Cancel Button Execute / Cancel Button Widget
CancelCall CancelCall
CanControl CanControl (Control Token Manager) , CanControl (Control Lock Manager)
CanDenyTokenRequest CanDenyTokenRequest
CanEditDoc CanEditDoc
CanGrantTokenRequest CanGrantTokenRequest
canonical address format Canonical Address Format
CanRedefineOEMType CanRedefineOEMType
CanReleaseToken CanReleaseToken
CanRemoveLock CanRemoveLock
CanRequestToken CanRequestToken
CaptureImage CaptureImage
CaptureSettings CaptureSettings
Case Case
Cast Cast
CAT CAT M5X Driver , CAT M5X CCM Manager
CAT Electronic Engine Controllers CAT M5X Driver , CAT M5X CCM Manager
CCM CAT M5X Driver , CAT M5X CCM Manager
Ceil Ceil
Certificate Certificate Management
Change Change
ChangePersistentSize Obsolete Functions
ChangeSet ChangeSets for Distribution
CharCount CharCount
Charging Workstation Status Driver I/O Addressing
CheckAddresses CheckAddresses
Checkbox Checkbox
checkbox switch widget Checkbox Switch Widget
CheckCertificateChain CheckCertificateChain
CheckFileExist CheckFileExist
CheckIPMask CheckIPMask
CheckPathExist CheckPathExist
CheckSignature CheckSignature
CheckTagGroup CheckTagGroup
child module Module Scope
child tags Programming Parent Tags
child tags, considerations Rules for Child Tags
child tags, drawing Widgets for Parent Tags
child windows Owned Windows versus Child Windows
ChildDocs ChildDocs
ChildInstances ChildInstances
CHM Resources, Terms, Definitions
CHM file Custom Help Files
Choose Log and Report
choose server Add New Applications
CIP addressing Rockwell Driver I/O Addressing
CIP driver statistics CIP Driver Statistics Dialog , Rockwell Driver Statistics Dialog
CIP driver tag Rockwell Driver Tag , Rockwell Driver Tag
CIPENIPSharedRPC CIPENIPSharedRPC
CIPForwardCloseAdvance CIPForwardCloseAdvance
ciphertext Cryptography Terms and Abbreviations
CIPMaxNumberofSessions CIPMaxNumberofSessions
CIPPLCConnAttLimit CIPPLCConnAttLimit
CIPTransTimeOutCount CIPTransTimeOutCount
Circle Circle
ClassFactory The Schema Cache Dictionary
Classic Gauge widget Classic Gauge Widget
CleanModule CleanModule
Clear Button Widget Clear Button Widget
ClearModule ClearModule
ClearState ClearState
ClearVarMetaData ClearVarMetaData
Click Click
ClientCabPath ClientCabPath
ClientSocket ClientSocket
ClipboardGet ClipboardGet
ClipboardPut ClipboardPut
clone (ChangeSet) Add New Applications
clone (page or widget) Pages
Cloned Modems TAPI and UniModem Considerations
cloning Backups
ClosePopUp ClosePopUp
CloseStream CloseStream
Cls Cls
CLSID Accessing COM Objects
cluster Server Requirements and Licensing
CMEP CSV Data Driver
coalescing Communication Process
Cockpit Gauge widget Cockpit Gauge Widget
code coverage Code Coverage
CodeText CodeText
CollapseTree Obsolete Functions
color blink widget Color Blink Widget
color box widget Color Box Widget
color fill widget Color Fill Widget
color line widget Color Line Widget
color palette VTScada Color Palette
color properties Color Properties
ColorParameterEdit ColorParameterEdit
ColorSelect ColorSelect
ColumnFormats Customize Columns in Alarm Displays
COM Using COM in VTS
COM objects, accessing Accessing COM Objects
Combine Combine
COMClient COMClient
COMEvent COMEvent
comm indicator widget Comm Indicator Widget
comm line widget Comm Line Widget
Comm Link Sequencer Comm Link Sequencer Tags
comm messages button widget Comm Messages Button Widget
CommaFormat CommaFormat
command line options - service Service Command Line Reference
Command Parameters of Internet Client Requests Command Parameters of Internet Client Requests
CommandLine CommandLine
CommDisplay ShowComm Submodule
comment Version Control
CommFailColor CommFailColor
CommIndicator, module Common Driver Widgets
Commission Commission
CommitEditedFiles CommitEditedFiles
CommitFocused CommitFocused
common module Common Module
CommStatsQualityFactor CommStatsQualityFactor
CommStatsUpdateRate CommStatsUpdateRate
communication driver design Communication Driver Design
communication driver properties Communication Driver Properties
Communication Driver Templates Rules for Writing a Communications Driver
communication drivers Communication Drivers
communication drivers, debugging Debugging and Testing Communications Drivers
communication drivers, drawing Common Driver Widgets
communication drivers, essential components Communication Drivers
communications chain Tag Reference
Communications Data page Communications Data Page
CompactLogix Rockwell Driver Tag
compass 1 drawing method Compass 1 Widget
compass 2 drawing method Compass 2 Widget
compass indicator widget Compass Indicator
Compile Import File Changes Tool , Compile
CompileProgressDelay CompileProgressDelay
component object model Using COM in VTS
COMPort COMPort
Compress Compress
COMStatus COMStatus
Concat Concat
Cond Cond
Config.DB Moving to the Current Version
Config.INI Moving to the Current Version
ConfigListBroadcastWait ConfigListBroadcastWait
Configuration Configuration File Structure
configuration folders Tag Configuration Folders
configuration parameters Tag Configuration Parameters
Configure Configure
configured alarm list List Options for Alarms
Configurer Built-In Roles
confirmation Confirmation Prompts for Output Tags
Connect multiple instances of JSON/XML drivers to the same domain Connect JSON/XML Drivers in Parallel
ConnectInitString Modem Manager Functions
connection status indicator drawing method Connection Status Indicator Widget
Connector Properties Add Properties to Context Tags
ConnectToMachine ConnectToMachine
constant Value Types
constant / expression / tag Constant, Expression or Tag
ConstCount ConstCount
Constructor Constructors and Destructors
containers Containers, Contributors and Site Tags
Containers Report Visual Design
ContainerTerm ContainerTerm
context menu, disable Choices for Operator Interaction
context tags Context Tags
ContextType Optional Variables and Constants
contributors Containers, Contributors and Site Tags
control Widgets for Operation
Control Locks Control Locks
Control Outputs System Privilege Reference for Developers
Control Token Box Control Token Box
ControlLockAutoUnlockUponLogout ControlLockAutoUnlockUponLogout
ControlLockCanOnlyRemoveOwnLock ControlLockCanOnlyRemoveOwnLock
ControlLockIsOwnerHook Control Lock Security , ControlLockOwnerMode
ControlLockLevel1Color ControlLockLevelXColor
ControlLockLevel1Label ControlLockLevelXLabel
ControlLockLevel1PreventControl ControlLockLevelXPreventControl
ControlLockLevel2Color ControlLockLevelXColor
ControlLockLevel2Label ControlLockLevelXLabel
ControlLockLevel2PreventControl ControlLockLevelXPreventControl
ControlLockLevel3Color ControlLockLevelXColor
ControlLockLevel3Label ControlLockLevelXLabel
ControlLockLevel3PreventControl ControlLockLevelXPreventControl
ControlLockLevelIconXOffset ControlLockLevelIconXOffset
ControlLockLevelIconYOffset ControlLockLevelIconYOffset
ControlLockLevelXColor ControlLockLevelXColor
ControlLockLevelXLabel ControlLockLevelXLabel
ControlLockLevelXPreventControl ControlLockLevelXPreventControl
ControlLockNoteMinLength ControlLockNoteMinLength
ControlLockNoteRequiredForAdd ControlLockNoteRequiredForAdd
ControlLockNoteRequiredForRemove ControlLockNoteRequiredForRemove
ControlLockOwnerMode ControlLockOwnerMode
ControlLocksEnabled ControlLocksEnabled
ControlLogix Rockwell Driver Tag
ControlNet Rockwell Driver Tag
ControlTokenAutoRequestOption ControlTokenAutoRequestOption
ControlTokenAutoStealOption ControlTokenAutoStealOption
ControlTokenCanOnlyRemoveOwnToken ControlTokenCanOnlyRemoveOwnToken
ControlTokenCustomFieldHook Custom Ownership Mode for Control Tokens
ControlTokenEnableOwnerMonitor ControlTokenEnableOwnerMonitor
ControlTokenEnablePopupRequests ControlTokenEnablePopupRequests
ControlTokenLevelXColor ControlTokenLevelXColor
ControlTokenLevelXLabel ControlTokenLevelXLabel
ControlTokenManualRequestOption ControlTokenManualRequestOption
ControlTokenManualStealOption ControlTokenManualStealOption
ControlTokenMaxAge ControlTokenMaxAge
ControlTokenMonitorTime ControlTokenMonitorTime
ControlTokenOwnerHeartbeat ControlTokenOwnerHeartbeat
ControlTokenOwnerMode ControlTokenOwnerMode
ControlTokenPendingRequestStaleTime ControlTokenPendingRequestStaleTime
ControlTokenRequestMaxAge ControlTokenRequestMaxAge
ControlTokenRootTagArea RequestToken
ControlTokenRootTagName RequestToken
ControlTokensEnabled ControlTokensEnabled
ControlTokenStaleTokenTime ControlTokenStaleTokenTime
Contructor Constructors and Destructors
conversions Value and Type Conversions
convert value types Value Types
ConvertProgressDelay ConvertProgressDelay
ConvertTimeStamp ConvertTimeStamp
ConvertToDbDate ConvertToDbDate
ConvertToDbTime ConvertToDbTime
ConvertToDbTimeStamp ConvertToDbTimeStamp
ConvertToVTSDate ConvertToVTSDate
ConvertToVTSTime ConvertToVTSTime
ConvertToVTSTimeStamp ConvertToVTSTimeStamp
Coordinates Coordinates
coordinates - widget property Coordinates
coordinates application Coordinates Application
CoordToPixel CoordToPixel
CopyDir CopyDir
CopyIn CopyIn
CopyObjects Obsolete Functions
CopyOut CopyOut
CopyRecords CopyRecords
Cos Cos
counter tags Counter Tags
CoverageSnapshot CoverageSnapshot
CRC CRC
CRCTable CRCTable
Create New Type From Context to Type
create new type Design Your Own Tags
CreateModule CreateModule
Critical Workstation Status Driver I/O Addressing
CriticalSection CriticalSection
Crop Crop
CrossReference CrossReference
CryptoAPI Cryptography Terms and Abbreviations
cryptographic key Cryptography Terms and Abbreviations
cryptography Cryptography in VTScada
cryptography, architecture Cryptography Architecture
CryptRandom CryptRandom
CSP Cryptography Terms and Abbreviations
current alarm list List Options for Alarms
CurrentLine CurrentLine
CurrentTime CurrentTime
CurrentWindow CurrentWindow
custom map icons Custom Map Icons
custom privilege Restrict Access to Output Tags
custom privileges Protect Pages and Output Tags
custom reports Script Custom Reports
custom tags Custom Tag Types
custom widgets Create a Custom Widget
customization
auto-start VTS Automatic Start
CustomSiteListGetSubTags Custom Filtering of the Sites List and Map
CustomSiteMapGetSubTags Custom Filtering of the Sites List and Map
Cut Obsolete Functions
CycleDelay CycleDelay
CycleLength CycleLength

D

D Functions D Functions
Daily Snapshot Report Report Types Described
Daily Total Report Report Types Described
dashboards Sample Pages
data age widget Data Age Widget
data bits Serial Port Tags
Data Call Sequence of Events for Outgoing Calls
Data Diode Data Diode Support
Data Diode Properties Data Diode Properties
Data Diode Publisher Data Diode Publisher Tag
Data Flow comm. messages dialog Data Flow Communication Messages Dialog
Data Flow communication statistics Data Flow Statistics Dialog
Data Flow RTU drivers Data Flow RTU Driver
data folder Application Files and Folders , Application Files and Folders
data labels (HDV) Add Value Labels to the Graph
data logging Log and Report
data mode, modem manager Sequence of Events for Incoming Calls
data types for tag parameters SQL Data Types for Tag Parameters
database SQL Logger Group Tags
database - historian options Historian Data Storage
DataDiodeClientDisconnectTimeout DataDiodeClientDisconnectTimeout
DataDiodeClientMaxLogAge DataDiodeClientMaxLogAge
DataDiodeClientMaxLogFiles DataDiodeClientMaxLogFiles
DataDiodeClientMaxPacketNum DataDiodeClientMaxPacketNum
DataDiodeClientTraceInterval DataDiodeClientTraceInterval
DataDiodeClientTraceMax DataDiodeClientTraceMax
DataDiodePublisherFailoverCount DataDiodePublisherFailoverCount
DataDiodePublisherMaxLogAge DataDiodePublisherMaxLogAge
DataDiodePublisherMaxLogFiles DataDiodePublisherMaxLogFiles
DataDiodePublisherMaxQSize DataDiodePublisherMaxQSize
DataDiodePublisherPingInterval DataDiodePublisherPingInterval
DataDiodePublisherPortConnErrorDelay DataDiodePublisherPortConnErrorDelay
DataDiodePublisherSendInterval DataDiodePublisherSendInterval
DataDiodePublisherTraceInterval DataDiodePublisherTraceInterval
DataDiodePublisherTraceMax DataDiodePublisherTraceMax
DataFlowStationName DataFlowStationName
DataIdleTime DataIdleTime , Sequence of Events for Incoming Calls
DataLines #DataLines
DataPort Sequence of Events for Incoming Calls
Dataradio Diagnostic driver CalAmp Diagnostic Driver
DataradioSharedRPC DataradioSharedRPC
Date Date
date format codes Date Formatting Codes
Date Time Selector Date Time Selector
date, concepts Time and Date
DateNum DateNum
DateSelector DateSelector
Day Day
daytime List Options for Alarms
db store rate - historian status Historian Status
DBAdd DBAdd
DBDropList DBDropList
DBGetStream DBGetStream
DBGridList DBGridList
DBInsert DBInsert
DBListGet DBListGet
DBListSize DBListSize
DBRemove DBRemove
DBSystem DBSystem
DbTraceDaysToPreserve DbTraceDaysToPreserve
DbTraceFileSize DbTraceFileSize
DBTransaction DBTransaction
DBUpdate DBUpdate
DBValue DBValue
DCOM OPC Classic Configuration
DDE DDE Client , Using DDE
function DDE
DDE Client VTScada as a Local DDE Client
DDE driver tags DDE Client
DDE server Use VTScada as DDE Server
DDEPoke DDEPoke
DDEShareAdd DDEShareAdd
DDEShareDel DDEShareDel
DDESharedRPC DDESharedRPC
deactivate security Activate Security
DeadBand DeadBand
deadband control tag widgets Deadband Control Tags
deadband control tags Deadband Control Tags
Debugger Debugger
debugger utility Debugger Utility
debugging Troubleshoot
debugging properties Editing and Debugging Properties
Decode Decode
DecodeParms DecodeParms
Decommission Decommission
decorations Decorations
Decrypt Decrypt
decryption Cryptography Terms and Abbreviations
Default Memory Value I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag , Memory Tags
DefaultAnalogDeadbandFractionOfFullScale DefaultAnalogDeadbandFractionOfFullScale
DefaultBGColor DefaultBGColor
DefaultCalculationDeadbandFractionOfFullScale DefaultCalculationDeadbandFractionOfFullScale
DefaultContainerDetailsPage DefaultContainerDetailsPage
DefaultDriverDeadbandFractionOfFullScale DefaultDriverDeadbandFractionOfFullScale
DefaultEmailSubject DefaultEmailSubject
DefaultEquipmentTypes Section Names
DefaultExcelType DefaultExcelType
DefaultLanguage DefaultLanguage
DefaultMaxEmailSize DefaultMaxEmailSize
DefaultNamingContext DefaultNamingContext
DefaultPage DefaultPage
DefaultPrinter DefaultPrinter
DefGraphicBColor DefaultPageColor
DefGraphicPColor DefGraphicPColor
Deflate Deflate
delete page Delete a Page , Display Building (Idea Studio)
delete widget Display Building (Idea Studio)
DeleteAccount DeleteAccount
DeleteArrayItem DeleteArrayItem
DeleteContributor DeleteContributor
DeleteListItem Obsolete Functions
DeleteModule DeleteModule
DeleteOptional DeleteOptional
DeletePrivFromUser DeletePrivFromUser
DeleteSection SectionControl
DeleteState DeleteState
DeleteStatement DeleteStatement
DeleteUser DeleteUser
DeleteVariable DeleteVariable
DelPageFromApp DelPageFromApp
DelRead DelRead
delta tolerance Time Synchronization Manager Service
DeltaDigitalMaxBlockSize DeltaDigitalMaxBlockSize.htm
DeltaVTSMaxBlock DeltaVTSMaxBlock
DemoMode DemoMode
DenyTokenRequest DenyTokenRequest
Deploy Version Control , Local versus Deployed Changes
Deploy Changes Privilege System Privilege Reference for Developers
Deriv Deriv
Derived Flow Report Report Types Described
DeriveKey DeriveKey
descendant Module Scope
Destructor Constructors and Destructors
Detail Report Report Types Described
DetectFlatline DetectFlatline
DF1 networks Rockwell Driver Tag
DFS Stn Widget DFS Station Draw
DFSDriverAlarmArea DFSDriverAlarmArea
DFSDriverAlarmDescription DFSDriverAlarmDescription
DFSDriverAlarmDisable DFSDriverAlarmDisable
DFSDriverAlarmName DFSDriverAlarmName
DFSDriverAlarmOnDelay DFSDriverAlarmOnDelay
DFSDriverAlarmPriority DFSDriverAlarmPriority
DFSimulateOn DFSimulateOn
DHRIO Rockwell Driver Tag
diagnostic files Custom Diagnostic Files
diagnostics Troubleshoot
DialCancelOnAck DialCancelOnAck
DialCancelOnNormal DialCancelOnNormal
DialDTMFFeedback DialDTMFFeedback
DialerAckIndividualAlarms DialerAckIndividualAlarms
DialerConnectDelay DialerConnectDelay
DialerLocation DialerLocation
DialerSpeechInit Sequence of Events for Outgoing Calls , DialerSpeechInit
DialerVoice DialerVoice
DialInControl DialInControl
DialogBGColor DialogBGColor
DialogInitPos DialogInitPos
DialogMoveTime DialogMoveTime
DialogServiceFailoutTime DialogServiceFailoutTime
DialOnActive DialOnActive
DialOnClear DialOnClear
DialResetTime DialResetTime
DialWaitTime DialWaitTime
dictionaries - definition Dictionaries
Dictionary Dictionary
dictionary operations Dictionary Operations
DictionaryCopy DictionaryCopy
DictionaryRemove DictionaryRemove
Diff Diff
Digipeat Data Flow RTU Driver
digital control tag widgets Digital Control Tags
digital control tags Digital Control Tags
digital input tag Digital Input Tags
digital output tag widgets Digital Output Tags
digital output tags Digital Output Tags
digital statistics tags Digital Statistics Tags
digital status tag Digital Status Tags
DigitalControlName DigitalControlName
DigitalIndicator0Color DigitalIndicator0Color
DigitalIndicatorInvalidColor DigitalIndicatorInvalidColor
DigitalInputWidth DigitalInputWidth
DigitalStatusName DigitalStatusName
Dir Dir
DirectApply DirectApply
Disable Disable
disable min/max (realm display setup) Realm Display Setup Tags
disable options Choices for Operator Interaction
DisableCommStats DisableCommStats
DisableControlWidgetIfMismatched DisableControlWidgetIfMismatched
DisableControlWidgetIfOtherMismatched DisableControlWidgetIfOtherMismatched
DisableControlWidgetIfOtherSelected DisableControlWidgetIfOtherSelected
DisableControlWidgetIfSelected DisableControlWidgetIfSelected
disabled alarm list List Options for Alarms
DisabledControlWidgetOpacity DisabledControlWidgetOpacity
DisableGoToPage DisableGoToPage
DisableGoToPageAsPopup DisableGoToPageAsPopup
DisableOutGoingCalls DisableOutGoingCalls
DisablePageNotes DisablePageNotes
DisablePageSnapShotting DisablePageSnapShotting
disables pop-ups DisableGoToPageAsPopup
DisableUSDialog DisableUSDialog
DisableVAMPerAppColoring DisableVAMPerAppColoring
DisconnectFromMachine DisconnectFromMachine
DiscretesWithoutEquipmentTypeUseDigitalLabels DiscretesWithoutEquipmentTypeUseDigitalLabels
discriminator Modem Manager API
display manager properties Display Manager Properties
DisplayAddress Optional Variables and Constants
DisplayManagerTitle DisplayManagerTitle
DisplaySection SectionControl
DispMgrAspectRatio DispMgrAspectRatio
DispMgrBMPMarginBottom DispMgrBMPMarginBottom
DispMgrBMPMarginLeft DispMgrBMPMarginLeft
DispMgrBMPMarginRight DispMgrBMPMarginRight
DispMgrBMPMarginsWin DispMgrBMPMarginsWin
DispMgrBMPMarginTop DispMgrBMPMarginTop
DispMgrDateFormat DispMgrDateFormat
DispMgrFullScreen DispMgrFullScreen
DispMgrHeight DispMgrHeight
DispMgrHidden DispMgrHidden
DispMgrHoriz DispMgrHoriz
DispMgrMinHeight DispMgrMinHeight
DispMgrMinMaxDisabled DispMgrMinMaxDisabled
DispMgrMinWidth DispMgrMinWidth
DispMgrPageStyle DispMgrPageStyle
DispMgrResizable DispMgrResizable
DispMgrStartupPageX DispMgrStartupPageX
DispMgrTimeFormat DispMgrTimeFormat
DispMgrTitleBorder DispMgrTitleBorder
DispMgrVert DispMgrVert
DispMgrWidth DispMgrWidth
DispMgrWPageStyle DispMgrWPageStyle
DispMgrX DispMgrX
DispMgrY DispMgrY
DisSPatch MultiSpeak API , MultiSpeak Support
distributed version control Version Control
DITrendEnable DITrendEnable
DLL DLL
DLLs Using DLLs
DNP3 addressing DNP3 I/O Addressing
DNP3 comm. messages dialog DNP3 Driver Communication Messages Dialog
DNP3 driver comm. statistics DNP3 Driver Statistics Dialog
DNP3DataInvalidOnFail DNP3DataInvalidOnFail
DNP3DefaultNoScan DNP3DefaultNoScan
DNP3DelayedResponseTimeout DNP3DelayedResponseTimeout
DNP3FailoverCount DNP3FailoverCount
DNP3MaxFileSize DNP3MaxFileSize
DNP3SharedRPC DNP3SharedRPC
DoAcknowledge Obsolete Functions
DoLoop DoLoop
DOM Web Services Terms
DoNotStart DoNotStart
DoNotSyncLayer DoNotSyncLayer
DontLogTrendPens DontLogTrendPens
DoOperate DoOperate
dot matrix numeric widget LCD Bar Widget
DragHandle DragHandle
DragState Obsolete Functions
draw command Widgets for Tags
draw scale Draw Scale
draw tag widget Draw Widget
draw text widget Numeric Value Widget , Draw Text Widget
DrawArcPath DrawArcPath
DrawChordPath DrawChordPath
DrawEllipticalPath DrawEllipticalPath
DrawLabel Create a Custom Widget
drawn tag property Select a Data Source
DrawPath DrawPath
DrawPiePath DrawPiePath
DrawQRCode DrawQRCode
DrawScale DrawScale
DrawServiceListEnableSwitchingAll DrawServiceListEnableSwitchingAll
DrawServiceListEnableSwitchingSelected DrawServiceListEnableSwitchingSelected
DrawServiceListServerSwitchAllRequiresConfirmation DrawServiceListServerSwitchAllRequiresConfirmation
DrawServiceListServerSwitchRequiresConfirmation DrawServiceListServerSwitchRequiresConfirmation
DrawServiceListUpdateRate DrawServiceListUpdateRate
DreamReport Log and Report
DriveInfo DriveInfo
Driver Communication Error Detail Report Report Types Described
Driver Communication Summary Report Report Types Described
driver failover NoSoftDriverFailure
driver module instances Driver Module Instance Object Value
driver multiplexer tags Driver Multiplexer
driver tags Communication Driver Tags
DriverMUX Driver Multiplexer
DriverRPCOptimization DriverRPCOptimization
drivers - DDE DDE Client
driverselect widget DriverSelect Widget
DriverSetupDelay DriverSetupDelay
Droplist Droplist
droplist control widget Droplist Control Widget (Legacy version)
DropTree DropTree
DTD Web Services Terms
dump file Dump Files
duplexes widget Duplexes Widget
Duration Selector Duration Selector
DurationParameterEdit DurationParameterEdit
DV8 POC-DV8 Tag
DV8 Overview POC-DV8 Overview
Dynacard Dynacard Upload Driver Tag
Dynacard Structure Sequencing Reads in a Pump-Off Controller
dynamic array Comparison of Static and Dynamic Arrays
dynamic data exchange DDE Client
Dynamic Data Exchange Using DDE
dynamic link libraries Using DLLs

E

E Functions E Functions
EC350 Honeywell Mercury Driver
ECAT Honeywell Mercury Driver
ECC CAT M5X Driver , CAT M5X CCM Manager
EchoPhoneThroughSpeaker EchoPhoneThroughSpeaker
Edge Edge
Edit Edit
Edit Data Privilege System Privilege Reference for Developers
Edit Files Privilege System Privilege Reference for Developers
edit property check box Edit Property Checkbox
edit property field widget Edit Property Field
Edit Roster Contacts System Privilege Reference for Developers
editable Manage Types Outside VTScada
EditFile EditFile
EditINI EditINI
EditINICheckbox EditINICheckbox
Editor Editor
EFM The Oil & Gas Solutions Layer
elapsed time widget Elapsed Time Widget
Electronic Flow Monitoring The Oil & Gas Solutions Layer
Ellipse Ellipse
email alarm acknowledgement Allow Acknowledgment by Email or SMS Text
EmailServer EmailServer
EmailSubject EmailSubject
EmailUserName EmailUserName
Enable Enable
enable MultiSpeak MultiSpeakServiceEnable
EnableHelp EnableHelp
EnableIOSyncOfRequestedValue EnableIOSyncOfRequestedValue
EnableLexiconDialog EnableLexiconDialog
EnableMobileMaps EnableMobileMaps
EnableRosterListRepeat EnableRosterListRepeat
EnableShowHide EnableShowHide
EnableSiblingTagAutoLinking EnableSiblingTagAutoLinking
EnableTwilio EnableTwilio
EnableTwilioVoiceRecognition EnableTwilioVoiceRecognition
EnableVOIP EnableVOIP
Encode Encode
EncodeURIComponent EncodeURIComponent
Encrypt Encrypt
encryption Data Encryption and Decryption
Enron comm. statistics dialog Enron Modbus Device Statistics Dialog , TeleBUS Statistics Dialog
EnronBoolMaxBlockSize EnronBoolMaxBlockSize
EnronContinuousHistoryRead EnronContinuousHistoryRead
EnronHistoryReadStartUpDelay EnronHistoryReadStartUpDelay
EnronLongMaxBlockSize EnronLongMaxBlockSize
EnronMaxHistoryBlockSize EnronMaxHistoryBlockSize
EnronPropagateOnlyOnDataChange EnronPropagateOnlyOnDataChange
EnronShortMaxBlockSize EnronShortMaxBlockSize
equipment widgets Equipment / Status Color Indicator
ErrMessage ErrMessage
error checking, communication drivers Error Checking
error codes, TAPI Call Progress and Error Codes
error messages (wizard engine) Error Messages [Error]
ErrorLogFileName ErrorLogFileName
ErrorMsg, module Common Driver Widgets
ERX Honeywell Mercury Driver
ERX350 Honeywell Mercury Driver
Escape Escape
EvaluateAlarm EvaluateAlarm
Event Event
event definition The Alarm Page
event log button Event Log List
Event Log Messages Event Log Messages - Event ID 1001
excel add-in Excel Add-in for Data Retrieval
Excel template Use an Excel Macro Template
ExcludeFromTagSearch Working with Pages
ExcludeIP [RPCManager-ExcludeIP] Section
Execute Execute
Execute Button Execute / Cancel Button Widget
ExecuteQuery ExecuteQuery
ExecuteQueryCached ExecuteQueryCached
Exp Exp
Export Languages
Export Comm Log Export Comm Log Widget
export tags Edit Tags Outside of VTScada
Export/Sync Tags Edit Tags Outside of VTScada
ExportKey ExportKey
Expression Workstation Status Driver I/O Addressing
ExpressionEdit The ExpressionEdit Widget
expressions, as tag parameters Expressions as Tag Parameters
extending structures Structures
Externally Triggered Recipe Batches Externally Triggered Recipe Batches
extra Customize Columns in Alarm Displays

F

F Functions F Functions
Fail Fail
failover NoSoftDriverFailure
False FALSE
fast scan widget Fast Scan Widget
FastPollCommColor FastPollCommColor
FastPollDuration FastPollDuration
FastPollRate FastPollRate
FFT FFT
FieldHighlight FieldHighlight
FieldShadow FieldShadow
FIFO RPC Manager Service
File Manifest Maintain the File Manifest
File Menu Display Building (Idea Studio)
FileChooser FileChooser
FileDialogBox FileDialogBox
FileFind FileFind
FileRootModule FileRootModule
FileSize FileSize
FileStream FileStream
fill patterns Fill Patterns
Filter Filter
filter field button (Legacy) Filter Field Button
filter HDV Filter the Selection
filtering, alarm area Alarm Area Filtering
filtering, concepts Filtering Tags, Alarms and Realms
filtering, tag area Tag Area Filtering
FiltHigh FiltHigh
FiltLow FiltLow
Find Create Queries
find servers Add New Applications
FindAction FindAction
FindCertificate FindCertificate
FindFile FindFile
FindModem FindModem
FindVariable FindVariable
FirstState FirstState
FitOffset FitOffset
FitR2 FitR2
FitSlope FitSlope
FlashUnackedAlarmsOnServer FlashUnackedAlarmsOnServer
FlashUnackedAlarmsOnVIC FlashUnackedAlarmsOnVIC
FloBoss DNP3 FBx Series DNP3 Driver Stats Dialog
FloBoss DNP3 driver FBx Series DNP3 Driver Tag
Flush Flush
FlushCache FlushCache
FocusID FocusID
Folder Folder
folders widget Folders
Font Font
font character sets Font Character Sets
font tags Font Tags
FontDialog FontDialog
ForceEvent ForceEvent
ForceMove Triggered Branch [ForceMove]
ForcePasswordAltIdSync ForcePasswordAltIdSync
ForceServers ForceServers
ForceState ForceState
Form Reset Button Widget Form Reset Button Widget
FormalParms FormalParms
Format Format
format ribbon Formatting Tools
FormatBatchQuery FormatBatchQuery
FormatInteger FormatInteger
FormatNumber FormatNumber
frame Frame
FRead FRead
FreeDiskSpace Workstation Status Driver I/O Addressing
Freeze Obsolete Functions
FriendlyTagServiceNames FriendlyTagServiceNames
function tags Function Tags
FWrite FWrite
FXO Using VoIP for Alarm Notification

G

G Functions G Functions
GDI.WIF Moving to the Current Version
GDIObjects Workstation Status Driver I/O Addressing
GE series 90 GE Series 90 Driver
GeneralAlarm Roster Selection Hierarchy
GenerateHMAC GenerateHMAC
GenerateKey GenerateKey
GenerateQRCode GenerateQRCode
GenerateSignature GenerateSignature
Generation Modes Report Tags
GESeries90FailoverCount GESeries90FailoverCount
Get Get
GET COLUMNS SQL: Reference and Examples
get from server Add New Applications
GET PRIMARY_KEYS SQL: Reference and Examples
GET TABLES SQL: Reference and Examples
GetAccountID GetAccountID
GetAccountInfo GetAccountInfo
GetAdaptersInfo GetAdaptersInfo
GetAlarmActionLabel GetAlarmActionLabel
GetAlarmConfiguration GetAlarmConfiguration
GetAlarmList GetAlarmList
GetAlarmName GetAlarmName
GetAlarmObject GetAlarmObject
GetAlarmStat GetAlarmStat
GetAlarmStateStats GetAlarmStateStats
GetAlarmStatus GetAlarmStatus
GetAllScadaPoints GetAllSCADAPoints
GetAllTagTypesInGroup GetAllTagTypesInGroup
GetAllWorkstationNames GetAllWorkstationNames
GetAppInstance GetAppInstance
GetAttValue WSDrvr Services
GetByte GetByte
GetCertificateInfo GetCertificateInfo
GetClientDiverts GetClientDiverts
GetClientGUIDs GetClientGUIDs
GetClientIPs GetClientIPs
GetClientList GetClientList
GetClientMode GetClientMode
GetClientNodes GetClientNodes
GetClientsListed Obsolete Functions
GetCodeObj GetCodeObj
GetColorInfo GetColorInfo
GetConfiguration GetConfiguration
GetConnList GetConnList
GetContainerNumActive GetContainerNumActive
GetContainerNumUnacked GetContainerNumUnacked
GetContributors GetContributors
GetCryptoProvider GetCryptoProvider
GetCurrentRecipe GetCurrentRecipe
GetCurrentSubordinate GetCurrentSubordinate
GetCurrentVersion GetCurrentVersion
GetDatePhrase GetDatePhrase
GetDefaultValue GetDefaultValue
GetDevices GetDevices
GetDisplayIndex GetDisplayIndex
GetDisplayRoot GetDisplayRoot
GetDisplayValue GetDisplayValue
GetEquipmentColor GetEquipmentColor
GetEquipmentLabel GetEquipmentLabel
GetFileAttribs GetFileAttribs
GetFullName GetFullName
GetGroupName GetGroupName
GetGUID GetGUID
GetHistory GetHistory
GetHostByName GetHostByName
GetID GetID
GetInhibitedServiceList GetInhibitedServiceList
GetINIProperty GetINIProperty
GetInstance GetInstance
GetInSyncServers GetInSyncServers
GetIP GetIP
GetISOTSfromTS GetISOTSfromTS
GetKeyCount GetKeyCount
GetKeyParam GetKeyParam
GetLastUsedSubnet GetLastUsedSubnet
GetLiveMJPEG GetLiveMJPEG
GetLoadedAppInstance GetLoadedAppInstance
GetLocalIP GetLocalIP
GetLocalNumber GetLocalNumber
GetLockLevel GetLockLevel
GetLog GetLog
GetLogHeader Obsolete Functions
GetLogInfo GetLogInfo
GetLogonCredentialsFromSmartcard GetLogonCredentialsFromSmartcard
GetMachineNode GetMachineNode
GetMakeAltPtr GetMakeAltPtr
GetMethods GetMethods
GetMethodsResponse GetMethods
GetMethodsResult GetMethods
GetModuleContext GetModuleContext
GetModuleRefBox GetModuleRefBox
GetModuleText GetModuleText
GetModuleTimeStamp GetModuleTimeStamp
GetNameOfRecord GetNameOfRecord
GetNextKey GetNextKey
GetNumUnacked GetNumUnacked
GetOEMLayer GetOEMLayer
GetOneParmText GetOneParmText
GetOPCServerRequestRate GetOPCServerRequestRate
GetOutputTypes GetOutputTypes
GetOverrides GetOverrides
GetParameter GetParameter
GetParmPhrase GetParmPhrase
GetParmPhraseForLang GetParmPhraseForLang
GetParmText GetParmText
GetParserOffset GetParserOffset
GetPathBound GetPathBound
GetPhrase GetPhrase
GetPhraseForLang GetPhraseForLang
GetPhraseID GetPhraseID
GetPlatformInfo GetPlatformInfo
GetPowerState GetPowerState
GetPreferredSubnet GetPreferredSubnet
GetRawPhrase GetRawPhrase
GetRecipes GetRecipes
GetReferencedValues GetReferencedValues
GetRemoteVersion GetRemoteVersion
GetReportTypes GetReportTypes
GetRetainedValue GetRetainedValue
GetReturnValue GetReturnValue
GetScadaAnalogByScadaPointID GetSCADAAnalogByScadaPointID
GetScadaStatsuByScadaPointID GetSCADAStatusByScadaPointID
GetSelected GetSelected
GetSelectedInfo GetSelectedInfo
GetServer GetServer
GetServerChanges GetServerChanges
GetServerMode GetServerMode
GetServerNumber GetServerNumber
GetServerSIDPtr GetServerSIDPtr
GetServersListed GetServersListed
GetServiceScope GetServiceScope
GetSessionContainers GetSessionContainers
GetSessionContainerTags GetSessionContainerTags
GetSessionID GetSessionID
GetShapePath GetShapePath
GetSocketStatus GetSocketStatus
GetState GetState
GetStatement GetStatement
GetStatementNum GetStatementNum
GetStateText GetStateText
GetStatus GetStatus
GetStreamLength GetStreamLength
GetStreamType GetStreamType
GetStructInfo GetStructInfo
GetSubGraphic Obsolete Functions
GetSubnetPriority GetSubnetPriority
GetSubordinateDriver GetSubordinateDriver
GetSystemColor GetSystemColor
GetTagConfiguredParameters GetTagConfiguredParameters
GetTagHistory GetTagHistory
GetTagList GetTagList
GetTagMode GetTagMode
GetTagTypes GetTagTypes
GetTimePhrase GetTimePhrase
GetToken GetToken
GetTokenLevel GetTokenLevel
GetTrajectoryPath GetTrajectoryPath
GetTransform GetTransform
GetTransitText GetTransitText
GetTSfromISOTS GetTSfromISOTS
GetUserName GetUserName
GetUserNameOfRecord GetUserNameOfRecord
GetUserSession GetUserSession
GetValue GetValue
GetValue_Numeric Sequencing Reads in a Pump-Off Controller
GetValueAttribute GetValueAttribute
GetVariableText GetVariableText
GetVariableType GetVariableType
GetVarMetadata GetVarMetadata
GetVersions GetVersions
GetVoices GetVoices
GetWCPath GetWCPath
GetWCRevision GetWCRevision
GetXformRefBox GetXformRefBox
GetXMLNodeArray GetXMLNodeArray
GI Poll GI Poll Button
GiveUpCallTimeout GiveUpCallTimeout
Glance Widget Glance Meter Widget
Glass Gauge Glass Gauge Widget
Global Tag & Area Filter System Privilege Reference for Developers
go to most recent (button) (Legacy) Alarm Go To Most Recent Button
GoToOffset GoToOffset
GoToPageHook Hook for "Go To Page" calls
gradient color change widget Gradient Color Change Widget
Grandstream Tips for Configuring a Grandstream VoIP ATA
grant privileges Assign Privileges
Granting Consent OAuth 2.0 Authorization Code flow
GrantTokenRequest GrantTokenRequest
graphic editor panel The Properties Panel
GRAPHICS Class Declarations for Modules in AppRoot
GrayedText GrayedText
green tag fields Configuration Field Colors
Grid Grid
grid (shape) Grid
grid view HDV Grid as a Reporting Tool
GridList GridList
group Select and Arrange , Select and Arrange
Group Create Widgets
Group Delete Privilege System Privilege Reference for Developers
Group Modify Privilege System Privilege Reference for Developers
group name Security Realms
Group Save Privilege System Privilege Reference for Developers
GroupLogin Security NameSpaces , GroupLogin
GroupName.src - defined Application Files and Folders
GROUPS Class Declarations for Modules in AppRoot
GSC CAT M5X Driver , CAT M5X CCM Manager
GuardTone GuardTone
GUIArc GUIArc
GUIBitmap GUIBitmap
GUIButton GUIButton
GUIChord GUIChord
GUIEllipse GUIEllipse
GUIPie GUIPie
GUIPipe GUIPipe
GUIPolygon GUIPolygon
GUIRectangle GUIRectangle
GUIStretch GUITransform
GUIText GUIText
GUITransform GUITransform

H

H Functions H Functions
Handles Workstation Status Driver I/O Addressing
HangUpDelay HangUpDelay
HasCompilationErrors HasCompilationErrors
Hash Hash
hash table TableInterpolation
hashing algorithm Storage of Security Data and Configuration
HasMetaData HasMetaData
HasReturnStatement HasReturnStatement
HasUndeployedChanges HasUndeployedChanges
hatch patterns Fill Patterns
HDV Historical Data Viewer (HDV)
HDV filters Filter the Selection
HDV properties Trending (HDV) Properties
HDVAnalogAlarmsVisibility HDVAnalogAlarmsVisibility
HDVAnalogPenAutoScaling HDVAnalogPenAutoScaling
HDVAnalogPenAverageVisibility HDVAnalogPenAverageVisibility
HDVAnalogPenMinMaxVisibility HDVAnalogPenMinMaxVisibility
HDVAnalogPenScale HDVAnalogPenScale
HDVAnalogPenStyle HDVAnalogPenStyle
HDVAnalogPenVisibility HDVAnalogPenVisibility
HDVAnalogPenWidth HDVAnalogPenWidth
HDVAnalogScalesVisibility HDVAnalogScalesVisibility
HDVDataRetrievalWaitTime HDVDataRetrievalWaitTime
HDVDateFormat1 HDVDateFormat1
HDVDateFormat2 HDVDateFormat2
HDVDigitalGridColor HDVDigitalGridColor
HDVDigitalPenVisibility HDVDigitalPenVisibility
HDVDigitalScalesVisibility HDVDigitalScalesVisibility
HDVDisplayTimeSelectionScrollBar HDVDisplayTimeSelectionScrollBar
HDVDisplayToolbar HDVDisplayToolbar
HDVGridCellColor HDVGridCellColor
HDVGridViewColor HDVGridViewColor
HDVGridViewSortOrder HDVGridViewSortOrder
HDVHorizontalGridColor HDVHorizontalGridColor
HDVLayoutBGColor HDVLayoutBGColor
HDVLegendVisible HDVLegendVisible
HDVMaxDataSources HDVMaxDataSources
HDVNotesLineVisibility HDVNotesLineVisibility
HDVNotesPenVisibility HDVNotesPenVisibility
HDVPlotBGColor HDVPlotBGColor
HDVPlotViewColor HDVPlotViewColor
HDVShowAllScales HDVShowAllScales
HDVShowTimeScales HDVShowTimeScales
HDVSimpleLegend HDVSimpleLegend
HDVTimeCursorColor HDVTimeCursorColor
HDVTimeFormat1 HDVTimeFormat1
HDVTimeFormat2 HDVTimeFormat2
HDVVerticalGridColor HDVVerticalGridColor
HelloPacketLength HelloPacketLength , Sequence of Events for Incoming Calls
Help Help
help - where to look Find Help
help files - adding custom help Custom Help Files
help key references Custom Help Files
HelpFile HelpFile
HelpServerPath HelpServerPath
hexadecimal format Value Types
HexToBuff HexToBuff
Hidden property sections Configuration File Structure
HiddenPage Working with Pages
hide data value (HDV) Add Value Labels to the Graph
hide page notes Page Notes , Hide a Page Note
hide VAM Hide the VAM
HideFromVAM HideFromVAM
HideInaccessiblePages HideInaccessiblePages
HideMenuOnOutgoing HideMenuOnOutgoing
HideVAM HideVAM
HideWam HideWAM
High Workstation Status Driver I/O Addressing
HighAlarmActive I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
HighAlarmUnacked I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
HighHighAlarmActive I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
HighHighAlarmUnacked I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
HighlightState Obsolete Functions
HighlightTree Obsolete Functions
HighlightUnackedAlarms HighlightUnackedAlarms
historian API Historian Manager API
historian manager Historian - API and Queries
historian monitoring expression Monitor the Historian's Connection
historian status tool Historian Status
Historian Tag Historian Tag
HistorianBroadcastMaxSize HistorianBroadcastMaxSize
HistorianBroadcastMinInterval HistorianBroadcastMinInterval
HistorianConnect HistorianConnect
HistorianConnectionRetryDelay HistorianConnectionRetryDelay
HistorianDataAgeSweepIntervalDivisor HistorianDataAgeSweepIntervalDivisor
HistorianDefaultArchiveInterval HistorianDefaultArchiveInterval
HistorianDeleteRecords HistorianDeleteRecords
HistorianFailoverInterval HistorianFailoverInterval
HistorianGetData HistorianGetData
HistorianGetInfo HistorianGetInfo
HistorianODBCTableNames HistorianODBCTableNames
HistorianPublisherManagerMaxLogAge HistorianPublisherManagerMaxLogAge
HistorianPublisherManagerMaxLogFiles HistorianPublisherManagerMaxLogFiles
HistorianPublisherManagerTraceInterval HistorianPublisherManagerTraceInterval
HistorianPublisherManagerTraceMax HistorianPublisherManagerTraceMax
HistorianPublishManagerCriticalDiskSpace HistorianPublishManagerCriticalDiskSpace
HistorianPublishManagerFlushInterval HistorianPublishManagerFlushInterval
HistorianPublishManagerMaxPendingRecords HistorianPublishManagerMaxPendingRecords
HistorianPublishManagerMaxStateNum HistorianPublishManagerMaxStateNum
HistorianPublishManagerSyncInterval HistorianPublishManagerSyncInterval
HistorianReadRecords HistorianReadRecords
HistorianWriteBufferMaxLength HistorianWriteBufferMaxLength
HistorianWriteBufferMaxTimeDiff HistorianWriteBufferMaxTimeDiff
HistorianWriteRecords HistorianWriteRecords
Historical Data Viewer Historical Data Viewer (HDV)
History Page Access Privilege System Privilege Reference for Developers
History Statistics Tag History Statistics Tag
History Statistics Widget History Stats Value Widget
HLookup TableInterpolation
Home Ribbon Ribbons
Honeywell Honeywell Mercury Driver
Honeywell Mercury Driver Honeywell Mercury Driver
horizontal button widget Horizontal Button Widget
HOSTS Configure a VTScada Thin Client Server
hotbox Find and Open Pages Within an Application
hotbox (HDV) Open HDV Hotbox
HotBoxImage HotBoxImage
HotBoxTransparency HotBoxTransparency
Hourly Snapshot Report Report Types Described
Hourly Total Report Report Types Described
HoursEntry HoursEntry
HP Radial Gauge HP Radial Gauge
HRESULT Introduction to COM
HScrollbar HScrollbar
HSTS HTTP Strict Transport Security (HSTS)
HT813 Tips for Configuring a Grandstream VoIP ATA
HTTP Strict Transport Security HTTP Strict Transport Security (HSTS)
HTTPAllow HTTPAllow
HTTPDeny HTTPDeny
HTTPMaxEntityLength HTTPMaxEntityLength
HTTPRequestMaxSize HTTPRequestMaxSize
HTTPSend HTTPSend
HTTPServerMaxHeaderLength HTTPServerMaxHeaderLength
HTTPServerMaxHeaders HTTPServerMaxHeaders
HTTPServerThreads HTTPServerThreads

I

I Functions I Functions
IconMarker IconMarker , Indicate Questionable and Manual Data
IdleWebSessionTimeout IdleWebSessionTimeout
IECFailoverCount IECFailoverCount , IEC 60870-5-104 Driver
IECPropagateOnlyOnDataChange IEC 60870-5-104 Driver , IECPropagateOnlyOnDataChange
If If
IfElse IfElse
IfOne IfOne
IfThen IfThen
illuminated toggle switch Illuminated Toggle Switch Widget
image - add or draw Images
image change widget Image Change Widget
Image Format Ribbon Ribbons
ImageArray ImageArray
ImageParmSet ImageParmSet
ImageSetStruct GUIButton
ImageSweep ImageSweep
Import File Changes Configuration File Structure , Import File Changes Tool
import images Import Images
Import New Files Import File Changes Tool
import tags Edit Tags Outside of VTScada
Import/Export Files Import File Changes Page
Important Alarms
ImportAPI ImportAPI
imported images Import Images
ImportKey ImportKey
In In
InactiveCommColor InactiveCommColor
inbound email Email Setup for Alarms and Reports
IncludeAreaNotesWithTrendedTags IncludeAreaNotesWithTrendedTags
IncludeGroupNotesWithTrendedTags IncludeGroupNotesWithTrendedTags
incoming calls Modem Manager Operation
IncomingCallSection IncomingCallSection
index padding Comparison of Static and Dynamic Arrays
inheritance Inheritance Across Layers
INIFiles SetINIProperty
INIProperty SetINIProperty
InitCheckBox Initial Action [InitCheckBox]
InitialDataDelay InitialDataDelay , Sequence of Events for Incoming Calls
InitModemsDisabled InitModemsDisabled
input, keyboard Obtaining User Input
input, mouse Obtaining User Input
InsertArrayItem InsertArrayItem
InsertListItem Obsolete Functions
installation Requirements and Installation
Instance Instance
instance count utility Instance Count Application
Int Int
Integra-H CalAmp Diagnostic Driver
Integra-TR CalAmp Diagnostic Driver
Internet Client Access Privilege System Privilege Reference for Developers
Internet Client Monitor Monitor Internet Connections
Internet Client Monitor Access Privilege System Privilege Reference for Developers
Internet Client Monitor Admin Privilege System Privilege Reference for Developers
Internet logging Monitor Internet Connections
internet privileges Securing a VTScada Thin Client Server
internet server setup Define the Server Setup
Internet status dialog The VIC Status Dialog
InterpolateAnalogPlots InterpolateAnalogPlots
Intgr Intgr
Invalid Invalid
invalid characters Naming Rules
invalid data Special Symbols for Tags
InvalidColor InvalidColor
InvalidText InvalidText
InWord InWord
IOBPS Workstation Status Driver I/O Addressing
IP Network Listener tag IP Network Listener Tags
IPAddressList IPAddressList
IPMaskToText IPMaskToText
iQR Mitsubishi Driver
IsActive, alarm function IsActive
IsAppEditable IsAppEditable
IsChild IsChild
IsClient IsClient
IsDictionary IsDictionary
IsDisabled, alarm function IsDisabled
IsEqual IsEqual
IsExpression, expression manager module ExpressionManager Subroutines
IsLoggedOn IsLoggedOn
IsMatch IsMatch
IsOnLocalBranch IsOnLocalBranch
IsOperable Optional Variables and Constants
IsPotentialServer IsPotentialServer
IsPrimaryServer IsPrimaryServer
IsRunning IsRunning
IsRunOnly IsRunOnly
IsSecured IsSecured
IsServiceReady IsServiceReady
IsShelved IsShelved
IsSuspended IsSuspended
IsTagOperable IsTagOperable
IsUnacked IsUnacked
IsVICSession IsVICSession

J

J Functions J Functions
Java ODBC Java to ODBC Connection
JavaScript MIME Types Supported
JDBC Java to ODBC Connection
JoinStrings JoinStrings
JSON JSON/XML Driver
JSON/XML drivers connect sequentially Connect JSON/XML Drivers in Parallel
JSON_Encode JSON_Encode
JSONEncode JSONEncode
JSONParse JSONParse

K

K Functions K Functions
key Cryptography Terms and Abbreviations
key up delay Serial Port Tags
keyboard input Obtaining User Input
Keyboard Shortcuts Keyboard Shortcuts
KeyCount KeyCount
KeyFake KeyFake
Keys Keys
Keywords Keywords
knob widget Rotary Control Widget (Knob)
Koyo address format Koyo Address Translation
Koyo Click Koyo Address Translation
Koyo device statistics dialog Koyo Device Statistics Dialog
Koyo Driver Koyo DirectNET Driver
KoyoFailoverCount KoyoFailoverCount , Koyo DirectNET Driver
KoyoSharedRPC KoyoSharedRPC , Koyo DirectNET Driver

L

L Functions L Functions
LABELS Section Names
Language Language
LargeSocketWrite LargeSocketWrite
last logged value widget Last Logged Value Widget
LastSelected LastSelected
LastSelectedModule Obsolete Functions
LastSelectedState Obsolete Functions
Latch Latch
late binding Module Scope
LatitudeValue Latitude and Longitude
Launch Launch
Launched Launched Versus Called Modules
layer Reusable Application Layers
LayerInUse LayerInUse
LayerRoot\Stop LayerRoot\Stop
Layers Panel Layers Panel
LCD 5x7 matrix widget LCD 5x7 Matrix Widget
LCD Arc widget LCD Arc Widget
LCD Meter widget LCD Meter Widget
LCD Ring widget LCD Ring Widget
LDAP Windows Authentication Notes
LED 7 Segment Widget LCD 7 Segment Widget
left bar widget Left Bar Widget
legacy applications Moving to the Current Version
legacy data settings View Legacy Data
LegacyHistoryPath LegacyHistoryPath
Legend Site Legend
lexicon Configure Speech Lexicon
Lexicon.vlx - defined Application Files and Folders
LIBRARIES Class Declarations for Modules in AppRoot
library widget Plain Widgets
library, defined Terms for Tag Types
license Licensing
license - tags Tag Licensing
LiftstationDrivers Table of Type Characteristics
Limit Limit
LimitRosterToParentDB LimitRosterToParentDB
Line Line
line types Line Types
Linear Gauge widget Linear Gauge Widget
linear indicator widget Linear Indicator
Linear Scale Linear Scale Widget
LinearIndicator LinearIndicator
LinearIndicatorOverage LinearIndicatorOverage
LinearLegend LinearLegend
Lines Lines
link Widgets for Tags
Linked Tag Properties Linked Tag Properties
ListAdd ListAdd
Listbox Listbox
ListCertificates ListCertificates
ListInstances ListInstances
ListKeys ListKeys
ListRemove ListRemove
lists (Application Manager) Lists in the Application Manager
ListVars ListVars
Ln Ln
Load Obsolete Functions
Load Balancing Define the Connection Addresses
load distribution Servers for Specific Services
LoadDLL LoadDLL
LoadMIB LoadMIB
LoadModule LoadModule
local Structure and Rules
local modems Local Modems
LocalGroup LocalGroup
LocalScope LocalScope
LocalScopeSyntax LocalScopeSyntax
LocalVariable Variable
Locate Locate
LocCapture LocCapture
Lock Add / Remove System Privilege Reference for Developers
Lock Admin System Privilege Reference for Developers
Lock Level Control Locks
Lock Level Box Lock Level Box Widget
Lock Level Icon Lock Level Icon Widget
locked tag Control Locks
lockout time AccountLockoutTime
Locks List Widget Locks List Widget
LocSwitch LocSwitch
Log Log
log and historian properties Logging & Reporting Properties
log off Sign Out From Your Application
LogContributors Log Tag Data
Logged Off Accounts and Roles
Logged Off VIC Sessions Administrative Settings
Logged-Off Role Built-In Roles
Logger tags Collecting Data
logging, operator actions VTScada Event Logging
logging, overview Log and Report
logging, security Security Event Logging
logging, security events VTScada Event Logging
LogNTEvent LogNTEvent
LogOff LogOff
LogOffUponHide LogOffUponHide
logon Operator's Guide to Security
LogPath LogPath
LongitudeValue Latitude and Longitude
LookUp LookUp
Lookup table TableInterpolation
Low Workstation Status Driver I/O Addressing
low power shutdown Shutdown on Low Power
LowAlarmActive I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
LowAlarmUnacked I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
LowBatteryPercent LowBatteryPercent
LowBatteryTime LowBatteryTime
LowLowAlarmActive I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
LowLowAlarmUnacked I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
LSAlarmColor LSAlarmColor
LSDefaultTheme LSDefaultTheme
Lufkin POC-Lufkin SAM Well Manager
LUT TableInterpolation
LValue LValue

M

M Functions M Functions
M5X CAT M5X Driver , CAT M5X CCM Manager
MACID MACID
MaintainAspectRatio MaintainAspectRatio
make active widget Make Active Widget
MakeActiveAlarmUnackedWhenUnshelved MakeActiveAlarmUnackedWhenUnshelved
MakeActiveAlarmUnackedWhenUnsuppressed MakeActiveAlarmUnackedWhenUnsuppressed
MakeAlarmRecordSpeechFile MakeAlarmRecordSpeechFile
MakeArray MakeArray
MakeBitmap MakeBitmap
MakeBuff MakeBuff
MakeCall MakeCall
MakeDAG MakeDAG
MakeDictionary MakeDictionary
MakeEditor MakeEditor
MakeFixedBuff Obsolete Functions
MakeIPMask MakeIPMask
MakeNonPersistent MakeNonPersistent
MakeNonShared MakeNonShared
MakeParmPhrase MakeParmPhrase
MakePersistent MakePersistent
MakeSelfSignedCertificate MakeSelfSignedCertificate
MakeShared MakeShared
MakeTypeArray WSDrvr Services
MakeTypeInstance WSDrvr Services , Obsolete Functions
MakeValidFName MakeValidFName
Manage Tag Types System Privilege Reference for Developers
manage types Manage Types Outside VTScada
Manager Privilege System Privilege Reference for Developers
Manhattan Vertex
manual data Indicate Questionable and Manual Data , Special Symbols for Tags
Manual Data Privilege System Privilege Reference for Developers
ManualUnshelveDoesNotAckActiveAlarm ManualUnshelveDoesNotAckNormalAlarm
ManualUnshelveDoesNotAckNormalAlarm ManualUnshelveDoesNotAckNormalAlarm
ManualVICServerLists ManualVICServerLists
Map Page Access Privilege System Privilege Reference for Developers
map tile source Change the Map Source
MapAreaLimiting MapAreaLimiting
MapDraw MapDraw
MapTiler MapTiler as a Map Source
MapZoomTransitionThreshold MapZoomTransitionThreshold
marquee properties Object Selection Marquee Properties
MarqueeDashColor MarqueeDashColor
MarqueeSolidColor MarqueeSolidColor
MarqueeSpeed MarqueeSpeed
masked data entry String Entry Widget , Numeric Entry Widget
master Master & Subordinate Applications
match Match Properties
MatchKeys MatchKeys
Max Max
MaxCallAlarmPriorityReported MaxCallAlarmPriorityReported
MaxFailedLoginAttempts MaxFailedLoginAttempts
MaxHandOffCount MaxHandOffCount
MaxMuteDuration MaxMuteDuration
MaxNestedExpressionDepth MaxNestedExpressionDepth
MaxNoteCacheCount MaxNoteCacheCount
MaxNoteCacheDuration MaxNoteCacheDuration
MaxPagerBaudRate MaxPagerBaudRate
MaxPagerMessage MaxPagerMessage
MaxRateFailedLoginAttempts MaxRateFailedLoginAttempts
MaxRecipeBooksInBatchHistoryList MaxRecipeBooksInBatchHistoryList
MaxShelveDuration MaxShelveDuration
MaxSnapshotsPerMobileUser MaxSnapshotsPerMobileUser
MaxSpeakToFileLength MaxSpeakToFileLength
MaxWinPage MaxWinPage
MCSInstance MCSInstance
MCSMod MCSMod
MDLC Motorola IP Gateway Tags
MDS comm. messages dialog MDS Diagnostic Driver Communication Messages Dialog
MDS Diagnostic driver addressing MDS Diagnostic Driver I/O Addressing
MDS diagnostic driver comm. statistics MDS Diagnostic Driver Statistics Dialog
MDS diagnostic driver tag MDS Diagnostic Driver
MDSSharedRPC MDSSharedRPC
Mean Mean
Melsec Mitsubishi Driver
MemIn MemIn
Memory Memory
Memory Tags I/O and Calculation Tags , I/O and Calculation Tags , I/O and Calculations Tag
memory tracer utility Memory Tracer Application
Memory() Workstation Status Driver I/O Addressing
MemOut MemOut
MemTrace MemTrace
menu - alarm notification Dialing-in. The Alarm Notification System Menu
menu configuration Add New Menu Items
menu item tags Menu Item Tags
menu tasks Add Navigation
Menu.TXT Moving to the Current Version
MenuBgnd MenuBgnd
menuitem Menu Item Tags
MenuRepeatMax MenuRepeatMax
MenuTextColor MenuTextColor
MEPMD01 CSV Data Driver
Mercury Honeywell Mercury Driver
MercuryDriverAlarmXXXPriority MercuryDriverAlarmXXXPriority
MercuryDriverEventXPriority MercuryDriverEventXPriority
MercuryDriverTAPriority MercuryDriverTAPriority_XXXX
Merge Merge
Merge2 Merge2
MetaData, function MetaData
Metal Widget Metal-Themed Meter Widget
meter 1 widget Meter 1 Widget
meter 2 widget Meter 2 Widget
meter 3 widget Meter 3 Widget
meter 13 widget Linear Gauge Widget
MFA Secure Your Application
MIC URL Configure a Realm
Micro 800 Rockwell Driver Tag
Milsoft MultiSpeak Support
MIME type MIME Types Supported
Min Min
MinAltIDLength MinAltIDLength , Alternate Identification
Mini-AT Honeywell Mercury Driver
Mini-Max Honeywell Mercury Driver
minimum window height (realm display setup) Realm Display Setup Tags
minimum window width (realm display setup) Realm Display Setup Tags
MinModemsFree MinModemsFree
MinMuteDuration MinMuteDuration
MinShelveDuration MinShelveDuration
Mitsubishi Mitsubishi Driver
MitsubishiFailoverCount MitsubishiFailoverCount
MitsubishiPortSharedRPC MitsubishiPortSharedRPC
MitsubishiSharedRPC MitsubishiSharedRPC
MkDir MkDir
MMCycleTime MMCycleTime
MMDropOrphanCallTimeout MMDropOrphanCallTimeout
MMLogDateFormat MMLogDateFormat
MMLogLevel MMLogLevel
MMLogTimeFormat MMLogTimeFormat
MMRPCTimeout MMRPCTimeout
MMUnAvailRetry MMUnAvailRetry
mobile browser properties Mobile Browser Properties
MobileBrowserAlarmHistoryMaxRecords MobileBrowserAlarmHistoryMaxRecords
MobileBrowserAlarmHistoryTimeRange MobileBrowserAlarmHistoryTimeRange
MobileBrowserAutoRefreshPeriod MobileBrowserAutoRefreshPeriod
MobileBrowserDisablePageGraphics MobileBrowserDisablePageGraphics
MobileBrowserSnapshotRefreshPeriod MobileBrowserSnapshotRefreshPeriod
MobilePageMaxRenderTime MobilePageMaxRenderTime
MobileSlippyMapTilesSource1 MobileSlippyMapTilesSource1
modal Transparent and Alpha-blended Windows
Modbus Compatible Device Modbus Compatible Device Driver
ModBus driver tags Modbus Compatible Device Driver
Modbus Plus addressing Modbus Plus PLC Addressing
mode of operation (VTS/IS option) Define the Connection Addresses
modem address format Canonical Address Format
modem configuration
CallInterval1 Modem Manager Operation
CallLength Modem Manager Operation
CycleDelay Modem Manager Operation
managed pools Modem Manager Operation
server designation Designate Modem Manager Server(s)
modem event Event Log List
modem indicator widget Modem Indicator Widget
Modem Initialization Strings TAPI and UniModem Considerations
modem installation Install a Voice Modem
modem logging Configure Modem Logging
modem manager Modem Configuration and Use , Designate Modem Manager Server(s)
modem manager error codes Call Progress and Error Codes
modem manager, API Modem Manager API
modem manager, constants Modem Manager Constants
modem manager, event recording Modem Manager Alarm and Event Reporting
modem manager, operation Modem Manager Concepts
modem manager, overview Modem Manager Service
modem manager, properties Modem Manager Properties
modem properties Modem Manager Properties
modem removal Removing a Modem
modem return values Modem Tag Return Values
modem selection Modem Manager Operation
modem statistics Modem Statistics
modem status tool Modem Status
modem tags Modem Tags
modem tools library Modem Tools Library
modem verification Modem Configuration and Use
ModemAlarm ModemAlarm
ModemAutoReset ModemAutoReset
ModemCallPrefix ModemCallPrefix
ModemControl ModemControl Plug-in
ModemCount ModemCount
ModemDev ModemDev
ModemDial ModemDial
ModemDigits ModemDigits
ModemList ModemList
ModemManagerLogSize ModemManagerLogSize
ModemMedia ModemMedia
ModemName
Device ModemName Device
Disabled ModemName Disabled
ModemRetries ModemRetries
modems
driver installation Installing the Trihedral TSP and Modem Audio Driver
modems, local Local Modems
ModemSpeechTO ModemSpeechTO
ModemStream ModemStream
ModemTCPIPPort ModemTCPIPPort
ModemTransfer ModemTransfer
Modes GetTagHistory
Modicon comm. messages dialog Opto 22 Communication Messages Dialog , Modbus Compatible Communication Messages Dialog
Modicon comm. statistics dialog Motorola ACE Statistics Dialog , Modbus Compatible Device Statistics Dialog
Modicon driver addressing Modbus Compatible Device I/O Addressing
Modicon driver tags Modbus Compatible Device Driver
ModiconDigitalMaxBlockSize ModiconDigitalMaxBlockSize
ModiconFailoverCount ModiconFailoverCount
ModiconPortSharedRPC ModiconPortSharedRPC
ModiconPropagateOnlyOnDataChange ModiconPropagateOnlyOnDataChange
ModiconSharedRPC ModiconSharedRPC
ModiconTypedAddr1Offset ModiconTypedAddr1Offset
ModiconVTSMaxBlocka ModiconVTSMaxBlock
ModifyAccount ModifyAccount
ModifyBitmap ModifyBitmap
ModifyConfiguration ModifyConfiguration
ModifyTags ModifyTags
ModifyUserPrivilege ModifyUserPrivilege
module Module Structure
ModuleCollapsed Obsolete Functions
ModuleFileName ModuleFileName
ModuleHighlighted ModuleHighlighted
ModuleSnapshot ModuleSnapshot
ModuleTree Obsolete Functions
ModuleTreeSize Obsolete Functions
momentary button widget Momentary Button Widget
Month Month
Motor Protection Equipment controllers MPE SC Series Station Tags
Motorola Motorola IP Gateway Tags
Motorola ACE Motorola IP Gateway Tags
Motorola ACE driver tags Motorola ACE Driver
Motorola IP Gateway tags Motorola IP Gateway Tags
mouse input Obtaining User Input
MoveEditor MoveEditor
movement Movement
MoveSelState Obsolete Functions
MoveSibling MoveSibling
MoveState Obsolete Functions
MoveWindow MoveWindow
MPE Duplexer Child Tags MPE Duplexer Child Tags
MPE Duplexer Station Tags MPE Duplexer Station Tags
MPE SC Child Tags MPE SC Child Tags
MPE SC Series tags MPE SC Series Station Tags
MQTT MQTT Client Driver
MultiCheckboxParameterEdit MultiCheckboxParameterEdit
multi-color widget Multi-Color Widget
multidimensional arrays Arrays
Multifactor Authentication Secure Your Application
Multi-Line Widget Multi-Line Text Widget
Multilingual Expressions Multilingual Expressions
multi-page display Configure for Multiple Monitors
multiple historians Historians and Multiple Servers
multiple JSON/XML drivers Connect JSON/XML Drivers in Parallel
multiple monitor display Configure for Multiple Monitors
MultiSmart Child Tags MultiSmart Station Child Tags
MultiSmart Station Tags MultiSmart Station Tags
Multispeak MultiSpeak Support
MultiSpeak MultiSpeak Support
MultiSpeak configuration MultiSpeak Support
MultiSpeakLegacyIOPublish MultiSpeakLegacyIOPublish
MultiSpeakMaxMessagePoints MultiSpeakMaxMessagePoints
MultiSpeakMaxPointIDLength MultiSpeakMaxPointIDLength
MultiSpeakMessageRetries MultiSpeakMessageRetries
MultiSpeakMessageTimeout MultiSpeakMessageTimeout
MultiSpeakMHCompanyAttribute MultiSpeakMHCompanyAttribute
MultiSpeakNotificationDelay MultiSpeakNotificationDelay
MultiSpeakPingURLProbingPeriod MultiSpeakPingURLProbingPeriod
MultiSpeakRealmNames MultiSpeakRealmNames
MultiSpeakServiceEnable MultiSpeakServiceEnable
MultiSpeakSubscriptionMethods MultiSpeakSubscriptionMethods
MultiSpeakSubscriptionPassword MultiSpeakSubscriptionPassword
MultiSpeakSubscriptionURL MultiSpeakSubscriptionURL
MultiSpeakSubscriptionUsername MultiSpeakSubscriptionUsername
MultiSpeakTraceFileSize MultiSpeakTraceFileSize
MultiSpeakTraceLevel MultiSpeakTraceLevel
MultiSpeakTraceMemorySize MultiSpeakTraceMemorySize
multi-text widget Multi-Text Widget
Multitrode MultiSmart Station Tags
Multi-Write Button Multi-Write Button Widget
Multi-Write Hotbox Multi-Write Hotbox Widget
multiwrite tag Multi-Write Tags
multiwrite tag widget Multi-Write Tags
mute alarm sounds Silence or Mute Alarms
mute button Mute Button
MuteAlarms MuteAlarms
MuteSound, alarm function MuteSound
MySQL Historian Data Storage

N

N Functions N Functions
Name Name
NameSpaceDelimiter Security NameSpaces , NameSpaceDelimiter
Namespaces XML Namespaces
namespaces Security NameSpaces
naming rules Naming Rules
Nautical Gauge widget Nautical Gauge Widget
navigation Add Navigation
Navigator Navigator Calls (Shortcut Menu)
navigator menu, disable Choices for Operator Interaction
NETPRIORITY [RPCMANAGER-NETPRIORITY] Section
network link widget Network Link Widget
network status tag Network Status Tags
network values Network Values
NetworkValuesDetailTracing NetworkValuesDetailTracing
New New
new features What's New...
new page Pages
newdata module The NewData Module
NewDataGroup Sequencing Reads in a Pump-Off Controller
NewPage Obsolete Functions
NewTagPublishParmValue NewTagPublishParmValue
NewTagsFullyStarted NewTagsFullyStarted
Next Poll Index Next Poll Index Widget
NextFocusID NextFocusID
NextIs Unconditional Branch [NextIs]
nighttime List Options for Alarms
NMEA 0183 Driver NMEA 0183 Driver
NMEA. statistics dialog NMEA 0183 Driver Statistics Dialog
NMEADriverSharedRPC NMEADriverSharedRPC
NMEAFailoverCount NMEAFailoverCount
NoBack (wizard engine) Dead Ends [NoBack]
NoBalloonTips NoBalloonTips
NoBattery Workstation Status Driver I/O Addressing
NoData NoData
NoIconFile NoIconFile
NoInitialDriverDial NoInitialDriverDial
NoLegacyAlarmDesc NoLegacyAlarmDesc
NoModal NoModal
NoNext Dead Ends [NoNext]
NoOpChangeDialog NoOpChangeDialog
Normal Normal
NormalColor NormalColor
Normalize Normalize
NormalTrip, alarm function NormalTrip
NormalUnackedAlarmColor NormalUnackedAlarmColor
NoSoftDriverFailure NoSoftDriverFailure
NoSplash NoSplash
NoStretch Working with Pages
Not Not
Note Add Privilege System Privilege Reference for Developers
NoteAddRequiresAuthentication NoteAddRequiresAuthentication
notebook tags Notebook Tags
NoteMinLengthForAck NoteMinLengthForAck
NoteMinLengthForShelve NoteMinLengthForShelve
NoteMinLengthForUnshelve NoteMinLengthForUnshelve
NoteRequiredForAck NoteRequiredForAck
NoteRequiredForShelve NoteRequiredForShelve
NoteRequiredForUnshelve NoteRequiredForUnshelve
notes - adding Add Operator Notes
NotesTimestampFormat NotesTimestampFormat
NotesTimestampSort NotesTimestampSort
notification Alarm Notification System - Alerts by Phone, Email or Text
NotificationErrorDelay NotificationErrorDelay
NotifyVIC NotifyVIC
Now Now
NParm NParm
nudge Nudge to Move and Re-Size
NumAlarm Obsolete Functions
numbers Value Types
numeric entry widget Numeric Entry Widget
NumericParameterEdit NumericParameterEdit
NumHistoryItems NumHistoryItems
NumInstances NumInstances
NumParms NumParms
NumSelected NumSelected
NumSets NumSets
NumTagFiles Required Variables and Constants
NumVariables NumVariables
NVShowCheckFilesDlgCount NVShowCheckFilesDlgCount
NVShowDialogs NVShowDialogs

O

O Functions O Functions
Obsolete Functions Obsolete Functions
Ocean Data Systems Log and Report
OCPP Driver OCPP Driver
octal notation Value Types
ODBC Using ODBC , ODBC
ODBC connection Configure an ODBC Server
ODBC interface
data available Table Structure and Notes
ODBC server SQL Queries
ODBC server configuration Configure an ODBC Server
ODBC Show Stats widget ODBC Statistics
ODBCBeginTrans ODBCBeginTrans
ODBCColumns ODBCColumns
ODBCCommit ODBCCommit
ODBCConfigureData ODBCConfigureData
ODBCConnect ODBCConnect
ODBCDisconnect ODBCDisconnect
ODBCManagerAllowDeleteAll ODBCManagerAllowDeleteAll
ODBCManagerCheckBackupLog ODBCManagerCheckBackupLog
ODBCManagerConnectDelay ODBCManagerConnectDelay
ODBCManagerDateFormat ODBCManagerDateFormat
ODBCManagerDisconnectOnError ODBCManagerDisconnectOnError
ODBCManagerExecuteDelay ODBCManagerExecuteDelay
ODBCManagerFormatNumeric ODBCManagerFormatNumeric
ODBCManagerLogViewer ODBCManagerLogViewer
ODBCManagerMaxConnectTime ODBCManagerMaxConnectTime
ODBCManagerMirrorToDisk ODBCManagerMirrorToDisk
ODBCManagerPaceRecovery ODBCManagerPaceRecovery
ODBCManagerRollbackOnConnect ODBCManagerRollbackOnConnect
ODBCManagerThreaded ODBCManagerThreaded
ODBCManagerTimeFormat ODBCManagerTimeFormat
ODBCManagerTraceOn ODBCManagerTraceOn
ODBCManagerUseDriverTimeout ODBCManagerUseDriverTimeout
ODBCRollback ODBCRollback
ODBCSingleTable Historian Data Storage
ODBCSources ODBCSources
ODBCStatus ODBCStatus
ODBCTables ODBCTables
OEM layer Reusable Application Layers
OEMHelp OEMHelp
OffColor OffColor
OffNormal OffNormal
Oil & Gas Solutions The Oil & Gas Solutions Layer
OilVolumeCorrectionFactor OilVolumeCorrectionFactor
OilVolumeCorrectionToBase OilVolumeCorrectionToBase
OKStopPtr Interrupt the Shutdown Process
OkToWrite OkToWrite
OLEDrag Drag & Drop to a Window
OLEDrop Drag & Drop to a Window
Omron comm statistics dialog OCPP Driver Show Stats , Omron Statistics Dialog
Omron comm. messages dialog Omron Communication Messages Dialog
Omron Host Link driver Omron Host Link Driver
OmronFailoverCount OmronFailoverCount
OmronFINSDriverSemTimeOut OmronFINSDriverSemTimeOut
OmronFINSFailoverCount OmronFINSFailoverCount
OmronFINSServerFailTimeOut OmronFINSServerFailTimeOut
OmronFINSSharedRPC OmronFINSSharedRPC
OmronSharedRPC OmronSharedRPC
OnColor OnColor
Ones Ones
OnScreenKeypadNighttimeMode OnScreenKeypadNighttimeMode
OnScreenKeypadSize OnScreenKeypadSize
OnTop OnTop
opacity Opacity , Color Selector
opaque Opacity
OpaqueBackground OpaqueBackground
OPC addressing OPC Classic Addressing for VTScada
opc client Configure VTScada as an OPC Classic Client
OPC client driver comm. statistics dialog OPC Classic Client Driver Statistics Dialog , OPC UA Client Driver Statistics Dialog
OPC Client Driver tags OPC Classic Client Driver
OPC configuration OPC Classic Configuration
OPC properties Properties of OPC Classic Item Tags
OPC security Securing an OPC Classic Server
OPC server OPC Classic Configuration
OPC server tag OPC Classic Server Setup
opc tunneller Compatibility with OPC Tunneller Software
OPCClientSharedRPC OPCClientSharedRPC
OpChange OpChange
OPCServer OPCServer
OPCServerEnabled Make a Custom Tag Visible to OPC Clients
OPCServerRequestRateThreshold OPCServerRequestRateThreshold
OPCServerRequestRefreshPeriod OPCServerRequestRefreshPeriod
OPCUA Certificate Management , OPC UA Client Driver
OPCUAClientBlockSize OPCUAClientBlockSize
OPCUAClientDriverFailoverCount OPCUAClientDriverFailoverCount
OPCUAClientSharedRPC OPCUAClientSharedRPC
Open Data Base Connectivity Using ODBC
open HDV button HDV Button Widget , Open HDV Button
open HDV hotbox HDV Hotbox Widget , Open HDV Hotbox
OpenSitesAsPopup OpenSitesAsPopup
Operate Operate from the Tag Browser
OperationalChange Obsolete Functions
Operator Built-In Roles
% active Historical Data Viewer (HDV)
operator change Use Application Properties
operator logging properties Operator Logging Properties
operator notes - printing Export & Print Operator Notes
operator notes page Operator Notes Page
Operator Notes Page Access Privilege System Privilege Reference for Developers
operator precedence Operators
operator priority Operators
OperatorLog\AddEvent AddEvent
OperatorLogArea OperatorLogArea
OperatorLogging OperatorLogging
OperatorLogName OperatorLogName
OperatorLogTemplate OperatorLogTemplate
operators defined Operators
optimized expression Automated Tag Configuration
Optimized Expressions Automated Tag Configuration
options (security dialog) Activate Security
Opto 22 Mux Opto 22 Mux Driver
Or Or
Oracle Historian Data Storage
orange tag fields Configuration Field Colors
OrderlyShutdown OrderlyShutdown
Orphaned Alarms Orphaned Alarms
Out Out
outbound email Email Setup for Alarms and Reports
outline Outline Properties
Output Output
output tags Output Tags
OutWord OutWord
Overall Total Report Report Types Described
Override Automated Tag Configuration
owned windows Owned Windows versus Child Windows
OwningModule OwningModule

P

P Functions P Functions
P Tools Function Reference
Pack Pack
PackData Obsolete Functions
PackParms PackParms
PackRPC PackRPC
PAddressEntry PAddressEntry
Page Page
Page Add Privilege System Privilege Reference for Developers
page background image Page Property Reference
page close widget Page Close Button Widget
page color Page Property Reference
Page Delete Privilege System Privilege Reference for Developers
page hotbox widget Legacy Page Hotbox Widget , Legacy Page Button Widget , Page Hotbox Widget , Page Button Widget
page menu Find and Open Pages Within an Application
Page Modify Privilege System Privilege Reference for Developers
Page Note Edit Privilege System Privilege Reference for Developers
Page Note Hide Privilege System Privilege Reference for Developers
page note properties Page Note Scope and Appearance
page notes Page Notes
page order Pages
page properties Page Properties
Page Properties Ribbon Ribbons
page security Page Property Reference
page shuffle Page Shuffling
page size Page Property Reference
page title Page Property Reference
PageBMPMarginBottom Working with Pages
PageBMPMarginLeft Working with Pages
PageBMPMarginRight Working with Pages
PageBMPMarginsWin Working with Pages
PageBMPMarginTop Working with Pages
PageButtonToolTipBalloonStyle PageButtonToolTipBalloonStyle
PageButtonToolTipDelay PageButtonToolTipDelay
PageButtonToolTipEnable PageButtonToolTipEnable
PageButtonToolTipFont PageButtonToolTipFont
PageChangeUpdateSamePopup PageChangeUpdateSamePopup
PageFileBytes Workstation Status Driver I/O Addressing
PageHeight Working with Pages
PageListForGoToPageHook Hook for a List of Pages
PageMinHeight Working with Pages
PageMinWidth Working with Pages
PageNoteDateFormat PageNoteDateFormat
PageNoteTimeFormat PageNoteTimeFormat
PAGES Class Declarations for Modules in AppRoot
pages - navigation Find and Open Pages Within an Application
pages folder Application Files and Folders
PageShuffleDelay PageShuffleDelay
PageShuffleEnable PageShuffleEnable
PageShuffleList PageShuffleList
PageShufflePauseDuration PageShufflePauseDuration
PageShuffleRealms PageShuffleRealms
PageSnapshotCacheThresholdCount PageSnapshotCacheThresholdCount
PageSnapshotCacheThresholdPct PageSnapshotCacheThresholdPct
PageSnapshotsMaxInMemory PageSnapshotsMaxInMemory
PageToolTipLabel PageToolTipLabel , Working with Pages
PageVHeight Working with Pages
PageVWidth Working with Pages
PageWidth Working with Pages
PageWinOpt PageWinOpt , Working with Pages
PageX Working with Pages
PageY Working with Pages
PakBusClockAdjustDiff Campbell Scientific PakBus Driver , PakBusClockAdjustDiff
PakbusFailoverCount PakbusFailoverCount
PakBusInvalidDataPortTimeOut PakBusInvalidDataPortTimeOut , Campbell Scientific PakBus Driver
PakBusInvTableDefRetries PakBusInvTableDefRetries , Campbell Scientific PakBus Driver
PakBusMoreRecsExistCheck Campbell Scientific PakBus Driver , PakBusMoreRecsExistCheck
PakBusSharedRPC PakBusSharedRPC , Campbell Scientific PakBus Driver
Palette Obsolete Functions
Palettes Display Building (Idea Studio)
PAlmPriority PAlmPriority
PalStatus PalStatus
parallel connections Connect JSON/XML Drivers in Parallel
Parameter Parameter
parameter metadata Parameter Metadata
Parameter View Privilege System Privilege Reference for Developers
ParameterEdit ParameterEdit
parameterized page Parameterized Pages
ParameterPanel ParameterEdit Snap ins
ParameterSet ParameterSet
PAreaSelect PAreaSelect
parent module Module Scope
parent tags Programming Parent Tags
ParentModule ParentModule
ParentObject ParentObject
ParentWindow ParentWindow
parity Serial Port Tags
ParmChangedColor ParmChangedColor
ParmEditColor ParameterEdit Snap ins
ParmEditColorNone ParameterEdit Snap ins , ParameterEdit Snap ins , ParameterEdit Snap ins
ParmEditDateTime ParameterEdit Snap ins
ParmEditDuration ParameterEdit Snap ins
ParmEditExprMovement ParameterEdit Snap ins
ParmEditExprNoNormalize ParameterEdit Snap ins
ParmEditExprNormalize ParameterEdit Snap ins
ParmEditFont ParameterEdit Snap ins
ParmEditHorizAlign ParameterEdit Snap ins , ParameterEdit Snap ins
ParmEditLineStyle ParameterEdit Snap ins
ParmEditLineWidth ParameterEdit Snap ins
ParmEditNum ParameterEdit Snap ins
ParmEditNumSlider ParameterEdit Snap ins
ParmEditPageVariable ParameterEdit Snap ins
ParmEditParmMovement ParameterEdit Snap ins
ParmEditParmValue ParameterEdit Snap ins
ParmEditPattern ParameterEdit Snap ins
ParmEditPipeColor ParameterEdit Snap ins
ParmEditPipeWidth ParameterEdit Snap ins
ParmEditTag ParameterEdit Snap ins
ParmEditTagMovement ParameterEdit Snap ins
ParmEditTagProperty ParameterEdit Snap ins
ParmEditTagValue ParameterEdit Snap ins
ParmEditText ParameterEdit Snap ins
ParmEditTextExpression ParameterEdit Snap ins
ParmEditTPMovement ParameterEdit Snap ins
ParmInfoCreatedByLabel ParmInfoCreatedByLabel
ParmInfoCreatedOnLabel ParmInfoCreatedOnLabel
ParmInfoHistoryEnabled ParmInfoHistoryEnabled
ParmInfoLastModByLabel ParmInfoLastModByLabel
ParmInfoLastModOnLabel ParmInfoLastModOnLabel
ParmInfoTimeFormat ParmInfoTimeFormat
ParmOverrideColor ParmOverrideColor
ParmPhrase ParmPhrase
Parms The Properties Panel
ParmToBuff ParmToBuff
ParserSRO ParserSRO
password - changing Change Your Password
password options Password Options
PasswordDisplay PasswordDisplay
PasswordMinLen PasswordMinLen
PasswordTimeLimit PasswordTimeLimit
PasswordWarningTime PasswordWarningTime
PasteObjects PasteObjects
Path Path
PathDraw PathDraw
PatternMatch PatternMatch
PBX Using VoIP for Alarm Notification
PCheckbox PCheckbox
PColorEdit PColorEdit
PColorSelect PColorSelect
PContributor PContributor
pcProxBaudRate pcProxBaudRate
pcProxConnectCheckTO pcProxConnectCheckTO
pcProxDataBits pcProxDataBits
pcProxEnable pcProxEnable
pcProxExcludePortx pcProxExcludePortx
pcProxParity pcProxParity
pcProxPortNum pcProxPortNum
PcProxPortScanHigh PcProxPortScanHigh
pcProxPortScanLow pcProxPortScanLow
pcProxStopBits pcProxStopBits
PDroplist PDroplist
PEditfield PEditfield
PEditName PEditName
PeekStream PeekStream
Pen Pen
pen groups
deleting Pen Groups - Save Tag Selections
modifying Pen Groups - Save Tag Selections
saving Pen Groups - Save Tag Selections
Pen Modify Privilege System Privilege Reference for Developers
Pending Pending
percent active Historical Data Viewer (HDV)
PercentDifference PercentDifference
persisted Persistent Variables
persistent Persistent Variables
PersistentSize PersistentSize
PFileChooser PFileChooser
Phantom II CalAmp Diagnostic Driver
phone id Configure Alternate Identification
phonemes Phonetic Spelling Reference
Phonetic Phonetic Spelling Reference
PhraseDroplist PhraseDroplist
PhraseEdit PhraseEdit
PHSliderBar PHSliderBar
PHueSelect PHueSelect
Pick Pick
PickBMP PickBMP
PickModule Obsolete Functions
PickState Obsolete Functions
PickValid PickValid
PID PID
Pie Pie
Pie Chart Pie Chart Widget
Pie Chart Widget Pie Widget
PImageSelect PImageSelect
pin Configure Alternate Identification
PingURL PingURL
PINRetries PINRetries
PINTimeOut PINTimeOut
PIPAddressList PIPAddressList
Pipe Pipe
Pipes Pipes
PipeStream PipeStream
PixelColor PixelColor
pktrend example Open an HDV (trend) Window
plaintext Cryptography Terms and Abbreviations
Platform Platform
PlatformInfo folder Application Files and Folders
Play Play
PLC Alarm PLC Alarm Tag
PLCAlarm Deprecated PLC Alarm (OGS)
PLCAlarmCfgDeadbandDigits PLCAlarmCfgDeadbandDigits
PLCAlarmCfgDelayDigits PLCAlarmCfgDelayDigits
PLCAlarmCfgSetPointDigits PLCAlarmCfgSetpointDigits
PLCAlarmCommon Deprecated PLC Alarm (OGS)
PLCAlarmConfig Deprecated PLC Alarm (OGS)
Plot Plot
plot data widget Plot Data Widget
plot view HDV Grid as a Reporting Tool
PlotBuff PlotBuff
PlotXY PlotXY
PLUGINS Class Declarations for Modules in AppRoot
PMultiCheckBox PMultiCheckBox
POC POC-DV8 Tag , POC-Unico Tags , Weatherford Tag , POC-Lufkin SAM Well Manager
Point Point
pointer Using Pointers
pointer dereferencing Comparison of Static and Dynamic Arrays
PointerToBuff PointerToBuff
PointID MultiSpeak Data Structures
PointList PointList
points Tag Reference
POINTS Class Declarations for Modules in AppRoot
points, defined Custom Tag Types
Points.MDB Moving to the Current Version
Poll Status Widget Poll Status Widget (Bristol driver)
PollDisabledColor PollDisabledColor
PollDriverAlarmDisable PollDriverAlarmDisable
PollDriverAlarmOnDelay PollDriverAlarmOnDelay
PollDriverAlarmPriority PollDriverAlarmPriority
polled station widget Polled Station Widget
polling driver tags Polling Driver Tags
pool - modems Modem Manager Operation
popup Page Property Reference
popup menu, disable Choices for Operator Interaction
pop-up page control Limit Pop-up Pages
pop-up windows DisableGoToPageAsPopup
PopupCloseOnPageClose Limit Pop-up Pages , PopupCloseOnPageClose
PopupLimitAction PopupLimitAction
PopupStandard Customize Columns in Alarm Displays
port properties Port Properties
port tags Port Tags
POverride POverride
Pow Pow
Power Gauge Widget Power Widget
PowerStatus Workstation Status Driver I/O Addressing
PPageSelect PPageSelect
PPhraseDroplist PPhraseDroplist
PPhraseEdit PPhraseEdit
PPPDial PPPDial
PPPHandles PPPHandles
PPPStatus PPPStatus
PRadioButtons PRadioButtons
precedence - rules of Operators
PrepStringForTemplate PrepStringForTemplate
Pressure Gauge Pressure Gauge Widget
prevent pop-up windows from opening DisableGoToPageAsPopup
Print Print
print operator notes Export & Print Operator Notes
PrintDialogBox PrintDialogBox
printing Print...
PrintLine PrintLine
PrintWidth PrintWidth
Prioritized [RPCMANAGER-NETPRIORITY] Section
Priority Obsolete Functions
priority mode Define the Connection Addresses
PriorityLoad Optional Variables and Constants
PriorityReady Optional Variables and Constants
PRIORITYSTART Class Declarations for Modules in AppRoot
PriorityWeight Obsolete Functions
PrivateBytes Workstation Status Driver I/O Addressing
PrivBitsTotal PrivBitsTotal
PrivDescX PrivDescX
privilege reference System Privilege Reference for Developers
ProcessingLoad Workstation Status Driver I/O Addressing , ProcessingLoad
ProcInfo ProcInfo
profiler Profiler
ProgID Accessing COM Objects
program spawn widget Program Spawn Widget
ProgressBar ProgressBar
ProgSpawnTitle ProgSpawnTitle
Prompt Numeric Entry Widget
PromptForBadAltID PromptForBadAltID
pronunciation Configure Speech Lexicon
Properties Dialog Helper Functions Function Reference
properties folder Tag Configuration Folders
Protected Protected Variables
proto2 Protobuf Support
Protobuf Protobuf Support
ProtobufDecode ProtobufDecode
ProtobufEncode ProtobufEncode
ProtobufInstantiate ProtobufInstantiate
ProtobufParse ProtobufParse
Proximity card readers Proximity Card Readers
PrtScrn PrtScrn
PSecBit PSecBit
PSelectCertificate PSelectCertificate
PSelectObject PSelectObject
PServerListName PServerListName
PSpinbox PSpinbox
PTimeZone PTimeZone
PTools Function Reference
PtrWaitClose The Properties Panel
PType PType
PTypeToggle PTypeToggle
public/private key pair Cryptography Terms and Abbreviations
PublisherListTag PublisherListTag
pulse input tags Pulse Input Tags
PulseInName PulseInName
Pump Activity Report Report Types Described
Pump Discrepancy Report Report Types Described
pump status tags Pump Status Tags
Pump-Off Controller POC-DV8 Tag , POC-Unico Tags , Weatherford Tag , POC-Lufkin SAM Well Manager
PumpReportSortPumps PumpReportSortPumps
Purge Alarms Purge Alarms Widget (Bristol driver)
push button widget Push Button Widget
PVR Meter Run Tags
PWidgetSelect PWidgetSelect

Q

Q Functions Q Functions
QCPU Mitsubishi Driver
Quarter Arc Gauge widget Quarter Arc Gauge Widget
query for plotting Using a Query to Select Tags
questionable data Indicate Questionable and Manual Data , Special Symbols for Tags
Questionable Privilege System Privilege Reference for Developers
queue - modem Modem Manager Operation
queue length - historian status Historian Status
Queued Launched Versus Called Modules
Quick Access Toolbar Display Building (Idea Studio)
Quick Add Add New Applications
QuickAddTypeGUID QuickAddTypeGUID
QuietLogon QuietLogon

R

R Functions R Functions
radial indicator widget Radial Indicator
radial legend widget Radial Legend Widget
Radial Scale Radial Scale Widget
RadialIndicator RadialIndicator
RadialIndicatorOverage RadialIndicatorOverage
RadialLegend RadialLegend
RadioButtons RadioButtons
Rainfall Report Report Types Described
Rand Rand
Range Limits List Options for Alarms
rate of change tags Rate of Change Tags
RateOfChangeRPCThreshold RateOfChangeTagRPCThreshold
RateOfChangeTagRPCInterval RateOfChangeTagRPCInterval
RcvBuff ShowComm Submodule
Read Read
read timeout Define the Connection Addresses
ReadBlock ReadBlock
Readblocks Rockwell Driver Tag
ReadConfiguration ReadConfiguration
ReadINI ReadINI
ReadINIProperties ReadINIProperties
ReadLock ReadLock
ReadNum Obsolete Functions
read-only workstation Read-Only Workstation
ReadOnlyStation ReadOnlyStation
ReadPropertiesFile ReadPropertiesFile
ReadSectINI ReadSectINI
ReadText Obsolete Functions
ReadValues Sequencing Reads in a Pump-Off Controller
ReadX ReadX
ReadXY ReadXY
realm Internet Realms
Realm Area Filtering Realm Filtering
realm area filtering Realm Filtering
realm display setup tags Realm Display Setup Tags
Realm Filtering Realm Filtering
realm filtering Realm Filtering
realm tag filtering Realm Filtering
RealmAreas - application properties [*-REALMFILTER] Section , [REALMFILTER] Section
REALMAREAS, config.ini section Realm Filtering
RealmAreasExcludeInvalid RealmAreasExcludeInvalid
REALMFILTER [REALMFILTER] Section
RealmName-REALMFILTER [RealmName-REALMFILTER] Section
rearm Create Alarms
RebuildRcv ShowComm Submodule
RebuildXmit ShowComm Submodule
ReceiveColor ReceiveColor
Recipe Recipe Book Tag
Recipe Book Tag Recipe Book Tag
Recipe Delete Widget Recipe Delete Widget
Recipe Edit System Privilege Reference for Developers
Recipe Export Widget Recipe Export Widget
Recipe Import Recipe Import Widget
Recipe Ingredient Tag Recipe Parameter Tag
Recipe List Recipe List Widget
Recipe Note Widget Recipe Note Widget
Recipe Page Access System Privilege Reference for Developers
Recipe Retrieve Widget Recipe Retrieve Widget
Recipe Revert Widget Recipe Revert Widget
Recipe Save As Widget Recipe Save As Widget
Recipe Selector Widget Recipe Selector Widget
Recipe Start Widget Recipe Start Widget
Recipe Trigger Tag Recipe Trigger Tag
Recipe Update Widget Recipe Update Widget
RecommendAlternate RecommendAlternate
RecommendPrimary RecommendPrimary
Record Operator-Entered Values Output Tags
RecordAlarmStatusWhileDisabled RecordAlarmStatusWhileDisabled
RecordAlarmStatusWhileSuppressed RecordAlarmStatusWhileSuppressed
RecordManualDataInEventLog RecordManualDataInEventLog
RecordProperty RecordProperty
RecordSuppressionStatus RecordSuppressionStatus
red arrows Align
red tag fields Configuration Field Colors
redefine type Modify a Custom Type
Redirect Redirect
Reeder SNMPv3AgentWritePrivProtocol , SNMPv3AgentReadPrivProtocol , SNMPv3AgentTrapPrivProtocol
Reference Folders The Tag Widget Reference Folder
refresh Create Queries , The Refresh Module
refresh, tag module The Refresh Module
RefreshData Data Propagation , RefreshData
RefreshRate RefreshRate
Register Register
Register - SocketServerManager SocketServerManager Register
Register, alarm function Register Alarm Manager
Register, modem function Register (Modem Manager)
RegisterCustomTable RegisterCustomTable
Release Token Button Release Token Button
ReleaseLock ReleaseLock
ReleaseToken ReleaseToken
ReloadWCProgressDelay ReloadWCProgressDelay
RemCfgTransLog RemCfgTransLog
RememberLoginDuration RememberLoginDuration
RememberNewTagParameters RememberNewTagParameters
remote Structure and Rules
Remote Data Access Privilege System Privilege Reference for Developers
remote desktop and HDV colors HDV Problems in Remote Desktop Sessions
Remote History Table Access System Privilege Reference for Developers
RemoteAuthMethodsDisallowed RemoteAuthMethodsDisallowed
removable Manage Types Outside VTScada
remove application Remove an Application
remove start condition Automated Tag Configuration
RemoveCertificate RemoveCertificate
RemoveFromList RemoveFromList
RemoveLock RemoveLock
RemoveParameter RemoveParameter
RemWSDL RemWSDL
Rename Rename
rename privileges Protect Pages and Output Tags
RenamedVariables Deprecated PLC Alarm (OGS)
RepeatMenuTime RepeatMenuTime
Replace Replace
ReplaceStatement ReplaceStatement
RepoClashWait RepoClashWait
report button widget Report Button Widget
report iterations Report Iterations Widget
report option list widget Report Options Widget
report output type widget Report Destination Widget
report properties Report Generation Properties
Report tag Report Tags
report tag list widget Report Tag List Widget
report templates Use an Excel Macro Template
report tools library Run-Time Configuration of Report Tags
report type list widget Report Type Widget
ReportBrowseDir ReportBrowseDir
ReportDateFormat ReportDateFormat
ReportError ReportError
ReportErrorSilenceAll ReportErrorSilenceAll
ReportFault WSDrvr Services
reporting period (enhanced) widget Reporting Period (Enhanced) Widget
ReportMaxDataSets ReportMaxDataSets
ReportOutputDir ReportOutputDir
reports - create using code Script Custom Reports
Reports Page Access Privilege System Privilege Reference for Developers
ReportTempDir ReportTempDir
ReportTemplateDir ReportTemplateDir
ReportTimeZoneAware ReportTimeZoneAware
ReportTraffic Driver Diagnostic tools
repository clash ChangeSets for Distribution
RepositoryCommentDisable RepositoryCommentDisable
RepositoryCommentMinLen RepositoryCommentMinLen
RepositoryShowCloneHistory ChangeSets for Distribution , RepositoryShowCloneHistory
RepoSubscribe RepoSubscribe
Request Token Button Request Token Button Widget
RequestToken RequestToken
Reset Reset
reset button widget Reset Button Widget
Reset Polling History Widget Reset Polling History Widget
Reset Sequence FBx Series DNP3 Driver Tag
reset target widget Reset Target Widget
Reset to Default Relative Paths - Tag Relationships
ResetParm ResetParm
resources folder Application Files and Folders
Restart Required Restart Required
restrict access Restrict Access to Output Tags
ResultFormat ResultFormat
ResyncDoc ResyncDoc
Retained Retained Variables
Retro Gauge widget Retro Gauge Widget
Return Return
Reverse Reverse
reverse - version change Reverse Version Changes
Revert Version Control , Local versus Deployed Changes
Revert Changes Privilege System Privilege Reference for Developers
revision file Create a ChangeSet File
revision files ChangeSets for Distribution
rewrite outputs widget Rewrite Outputs Widget
RibbonCmd RibbonCmd
RibbonContextUI RibbonContextUI
RibbonGalleryItems RibbonGalleryItems
Ribbons Ribbons
RibbonSetProperty RibbonSetProperty
right bar widget Right Bar Widget
RmDir RmDir
Rockwell Rockwell Driver Tag
Rockwell Control Widget Rockwell Control Widget
Rockwell Information Widget Rockwell Information Widget
Rockwell Statistics Widget Rockwell Statistics Widget
RockwellDriverDHRIOChannels RockwellDriverDHRIOChannels
RockwellDriverMaxCPInstance RockwellDriverMaxCPInstance
RockwellDriverMaxInboundPacketSize RockwellDriverMaxInboundPacketSize
RockwellDriverMaxOutboundPacketSize RockwellDriverMaxOutboundPacketSize
RockwellDriverMaxStringLength RockwellDriverMaxStringLength
RockwellMaxUploadIdle RockwellMaxUploadIdle
RockwellPollB4BuildComplete RockwellPollB4BuildComplete
RockwellReadsBeforeAddressError RockwellReadsBeforeAddressError
RockwellWriteMode RockwellWriteMode
ROCPropagateOnlyOnDataChange ROCPropagateOnlyOnDataChange
role privileges Built-In Roles
Roles Accounts and Roles
RootNamespace RootNamespace
RootTransform RootTransform
RootValue RootValue
RootWindow RootWindow
roster activation - automatic Activate a Roster
roster alarm test Roster Alarm Test Widget
Roster Control Status Widget Roster Control Status Widget
roster selection Roster Selection Hierarchy
roster tags Roster Tags
RosterDelay RosterDelay
RosterFailureBackoffRate RosterFailureBackoffRate
RosterFailureMaxDelay RosterFailureMaxDelay
RosterFailureMinDelay RosterFailureMinDelay
RosterListDelay RosterListDelay
rotary control widget Rotary Control Widget (Knob)
Rotate Rotate
rotate graphics Rotation
round Int
rounding Int
Round-robin [RPCMANAGER-NETPRIORITY] Section
row height List Options for Alarms
RPC manager service RPC Manager Service
RPC properties Application Settings for RPC
RPC, definition RPC Manager Service
RPCBufferLength RPCBufferLength
RPCCompress RPCCompress
RPCConnectPort RPCConnectPort
RPCConnectStrategy RPCConnectStrategy
RPCDiagnostics RPCDiagnostics
RPCExecute Deprecated RPC Methods
RPCExecuteAll Deprecated RPC Methods
RPCExecuteServer Deprecated RPC Methods
RPCLocalQLength Workstation Status Driver I/O Addressing
RPCLocalQTime Workstation Status Driver I/O Addressing
RPCManager–AllowIP [RPCManager-AllowIP] Section
RPCManager–ExcludeIP [RPCManager-ExcludeIP] Section
RPCMaxPacketSize RPCMaxPacketSize
RPCMaxQLen RPCMaxQLen
RPCMaxStartDelay RPCMaxStartDelay
RPCMemBuffLimit RPCMemBuffLimit
RPCMemSendLimit RPCMemSendLimit
RPCReconnectTime RPCReconnectTime
RPCRemoteQDelay Workstation Status Driver I/O Addressing
RPCResendDelay RPCResendDelay
RPCs Remote Procedure Calls RPCs
RPCServerPort RPCServerPort
RPCSktConnectAttemptMax RPCSktConnectAttemptMax
RPCSktResendAttempts RPCSktResendAttempts
RPCSocketDeadTime RPCSocketDeadTime
RPCSocketResendAttempts RPCSocketResendAttempts
RPCTrace RPCTrace
RPCUseBuffered RPCUseBuffered
RTimeOut RTimeOut
RTS/CTS Serial Port Tags
rule scope Rules for Privilege Scope
Run Batch System Privilege Reference for Developers
RUNFileName RUNFileName
RUNFileVersion RUNFileVersion
RunInBubble RunInBubble
RunPack RunPack

S

S Functions S Functions
S7 memory addresses Siemens S7 Driver I/O Addressing
SafeAssign, expression manager module ExpressionManager Subroutines
SafeCopy, expression manager module ExpressionManager Subroutines
SafeRefresh, expression manager module ExpressionManager Subroutines
sample pages Sample Pages
Sample Table Read Status History Data for a TBox RTU
satellite maps Change the Map Source
Save Save
save log button Save Log Button
SaveCommStats Driver Diagnostic tools
SaveHistory SaveHistory
SaveImage SaveImage
SaveModule SaveModule
SBO DNP3 I/O Addressing
SC1000 controller MPE SC Series Station Tags
scadaAnalog MultiSpeak Data Structures
SCADAAnalogChangedNotification SCADAAnalogChangedNotification
SCADAPack SCADAPack History Read
scadaPoint MultiSpeak Data Structures
scadaStatus MultiSpeak Data Structures
SCADAStatusChangedNotification SCADAStatusChangedNotification
Scale Scale
scale display content Page Property Reference
scale graphics Scale
ScaleDisplayContent ScaleDisplayContent
scaling Scale
ScanCom ScanCom Driver Tag
SChannel Internet Security (TLS, X.509, SSL)
schema cache Validating versus non-Validating XML Processors
Scientific notation Value Types
Scope Scope
ScopeLocal ScopeLocal
ScreenReportsInExcel ScreenReportsInExcel
script applications Structure and Rules
script tag widget Script Tags
script tags Script Tags , Configuring a Script Tag
ScriptIconFile ScriptIconFile
scroll bars - adding Add Scroll Bars to a Page
SCT.MDB Moving to the Current Version
SDev SDev
SDS Driver SDS Driver Tag
search and replace Tag Links Panel
search notes Search for Notes
Searching Searching for Widgets
SecAlarm Security Plug-in Modules
SecDenied Security Plug-in Modules
Seconds Seconds
Section names Configuration File Structure
SectionControl SectionControl
Security Secure Your Application
security events Alarm Data Logging
security manager Security Manager
security manager plug-ins Security Plug-in Modules
Security Menu Secure Your Application
security privileges System Privilege Reference for Developers
security properties Security Properties
security realms Security Realms
security rules Rules for Privilege Scope
Security, Best Practices Best Practices for Security
SecurityAlarmArea SecurityAlarmArea
SecurityAlarmPriority SecurityAlarmPriority
SecurityCheck SecurityCheck
security-group Security Realms
SecurityManager.INI Moving to the Current Version
SecurityManager-Admin Configuration File Structure , Section Names
SecurityManager-PrivSys Section Names
Seek Seek
SelColor SelColor
Select Before Operate DNP3 I/O Addressing
select color Color Selector
SelectArea SelectArea
SelectCodePointer SelectCodePointer
SelectDAG SelectDAG
SelectedBGnd SelectedBGnd
SelectedText SelectedText
SelectGraphic SelectGraphic
SelectHandle SelectHandle
SelectHandleNum SelectHandleNum
Selection Input Obtaining User Input
selector switch tag widgets Selector Switch Tags
selector switch tags Selector Switch Tags
selector switch widget Selector Switch Widget
SelectPath SelectPath
SelectStates Obsolete Functions
Self Self
Send Send
send back Display Order
Send NRT and Time Widget Send NRT and Time Widget (Bristol)
SendAll Deprecated RPC Methods
SendMail SendMail
SerBreak SerBreak
SerCheck SerCheck
serial port tag Serial Port Tags
SerialNum SerialNum
SerialShareSemaphore SerialShareSemaphore
SerialStream SerialStream
SerIn SerIn
SerLen SerLen
SerOut SerOut
SerPortDisconnectDelay SerPortDisconnectDelay
SerRcv SerRcv
SerRTS SerRTS
SerSend SerSend
SerStrEsc SerStrEsc
SerString SerString
ServerList ServerList
servers.rpc - definition Application Files and Folders
ServerSocket ServerSocket
service errors Service Error Dialogs
service installation Service Installation
service status Historian Status
Service Status Widget Service Status Widget
Service Synchronization, definition RPC Manager Service
service, running VTScada VTScada as a Windows® Service
SERVICES Class Declarations for Modules in AppRoot
Services Page Services Page
Services Page Access System Privilege Reference for Developers
Service-Specific Lists VTScada Services Reference
SerWait SerWait
Session ID Session IDs
session timeout Define the Connection Addresses
SESSIONSTART Class Declarations for Modules in AppRoot
Set Write Data: The Set Module , Set
set analog value widget Set Analog Value Widget
Set Value Button Set Value Button Widget
set value button widget Legacy Set Value Button Widget
set value hotbox widget Widget Reference , Legacy Set Value Hotbox Widget
SetAllBlocks SetAllBlocks
SetBit SetBit
SetByte SetByte
SetCertificateProperty SetCertificateProperty
SetClock SetClock
SetCodeText SetCodeText
SetCurrentFilter SetCurrentFilter
SetCurrentRecipe SetCurrentRecipe
SetCurrentVersion SetCurrentVersion
SetCursor SetCursor
SetDDEServer SetDDEServer
SetDefault SetDefault
SetDivert SetDivert
SetEditMode SetEditMode
SetEnable SetEnable
SetFileAttribs SetFileAttribs
SetHandle SetHandle
SetHelp SetHelp
SetINIProperty SetINIProperty
SetInstanceName SetInstanceName
SetInstanceRefBox SetInstanceRefBox
SetKeyParam SetKeyParam
SetLibrary SetLibrary
SetLogHeader Obsolete Functions
SetModuleRefBox SetModuleRefBox
SetModuleText SetModuleText
SetOneParmText SetOneParmText
SetOPCData SetOPCData
SetOverride SetOverride
SetParameter SetParameter
SetParmText SetParmText
SetParserParm SetParserParm
SetRefRect SetRefRect
SetRemoteValue SetRemoteValue
SetReturnValue SetReturnValue
SetShelved SetShelved
SetStateColor Obsolete Functions
SetStateText SetStateText
SetStats, module Common Driver Widgets
SetSubnetPriority SetSubnetPriority
SetSuppressed SetSuppressed
SetSyncComplete SetSyncComplete
Settings.Dynamic Configuration File Structure
Settings.Startup Configuration File Structure
SetTransfer SetTransfer
SetTransitText SetTransitText
Setup Recommendations Dialog Setup Recommendations Dialog
Setup.INI Configuration File Structure , System Properties - Setup.ini
SetUserLanguage SetUserLanguage
SetVariableClass SetVariableClass
SetVariableText SetVariableText
SetVariableType SetVariableType
SetVarMetadata SetVarMetadata
SetVicParms SetVicParms
SetWSDL SetWSDL
SetXLoc SetXLoc
SetYLoc SetYLoc
SGBD tag SNMPGetBulkDistributor Tag
ShadowTree Obsolete Functions
Shape Format Ribbon Ribbons
shapes Shapes, Pipes, Lines
Shared Security Advanced
shared variables Shared Variables
SharedContexts SharedContexts
SharedSecurity SharedSecurity
ShellTemperatureCorrection ShellTemperatureCorrection
shelve an alarm Shelve Alarms
shelved alarm list List Options for Alarms
ShelvedEvent Obsolete Functions
ShiftStream ShiftStream
shortcut menu Navigator Calls (Shortcut Menu)
show a percentage Calculations & Operations Columns
Show Elapsed Time Draw HDV Widget
show shelved alarms Shelve Alarms
show stats button widget Show Statistics Button Widget
show stats widget Show Stats Widget (ODBC)
ShowComm ShowComm Submodule
ShowComm, module Common Driver Widgets
ShowCommDialog ShowComm Submodule
ShowDefaultOnFailedLookup ShowDefaultOnFailedLookup
ShowDisplayAnywhere ShowDisplayAnywhere
ShowDisplayMobile ShowDisplayMobile
ShowDisplayVIC ShowDisplayVIC
ShowDownloadStandalone ShowDownloadStandalone
ShowLexicon ShowLexicon
ShowPage ShowPage
ShowPage2 ShowPage2
ShowStats ShowStats Submodule
ShowStats, module Common Driver Widgets
ShowTip ShowTip
ShowUnlinkedIndicators ShowUnlinkedIndicators
ShowUserRealm ShowUserRealm
shuffle Page Shuffling
shutdown process Interrupt the Shutdown Process
SHUTDOWN_HOOK Interrupt the Shutdown Process , Class Declarations for Modules in AppRoot
ShutdownOnLowBattery ShutdownOnLowBattery
Siemens driver addressing Siemens S7 Driver I/O Addressing
Siemens S7 comm. messages dialog Siemens S7 Communication Messages Dialog
Siemens S7 driver comm. statistics dialog Siemens S7 Driver Statistics Dialog
Siemens S7 tags Siemens S7 Driver
SiemensS7FailoverCount SiemensS7FailoverCount
SiemensS7PortSharedRPC SiemensS7PortSharedRPC
SiemensS7PropagateOnlyOnDataChange SiemensS7PropagateOnlyOnDataChange
SiemensS7SharedRPC SiemensS7SharedRPC
sign out Sign Out From Your Application
silence alarm sounds Silence or Mute Alarms
silence button Silence Button
SilenceSound SilenceSound
SilentErrorCounts Driver Module Instance Object Value
SimpleOpChange SimpleOpChange
SimulateIO SimulateIO
SimulateMouse SimulateMouse
Sin Sin
SIP Using VoIP for Alarm Notification
Site Alarm List Widget Site Alarm List
Site Details page Site Details Page
site details widget Site Details Widget
site draw widget Site Draw Widget
site icon widget Pulse Beacon Widget
site legend widget Site Legend
Site List page Sites List Display Options
Site Map Site Map
Site Properties Add Properties to Context Tags
SiteDetailsWindowed SiteDetailsWindowed
SiteDispParms SiteDispParms
SiteRetries SiteRetries
Sites Sites List Display Options
Sites Page Access Privilege System Privilege Reference for Developers
Sites Widget Sites Widget
SitesPageIconLoadTime SitesPageIconLoadTime
SiteToolsQueryChange SiteToolsConfirmOutput
SizeWindow SizeWindow
SkipIf Skipping [SkipIf]
SkipLogonDialout SkipLogonDialout
Slay Slay
slide show Page Shuffling
slider widget Slider Widget
slippy map Site Map
SlippyMapBulkDownloadMaxZoomDiff SlippyMapBulkDownloadMaxZoomDiff
SlippyMapCriticalDiskSpace SlippyMapCriticalDiskSpace
SlippyMapDownloadFailoutTime SlippyMapDownloadFailoutTime
SlippyMapDownloadTimeLimit SlippyMapDownloadTimeLimit
SlippyMapMaxConcurrentDownloads SlippyMapMaxConcurrentDownloads
SlippyMapMaxRetryDelay SlippyMapMaxRetryDelay
SlippyMapMaxTileSize SlippyMapMaxTileSize
SlippyMapMaxZoomLevel SlippyMapMaxZoomLevel
SlippyMapMinZoomLevel SlippyMapMinZoomLevel
SlippyMapOSMDisable SlippyMapOSMDisable
SlippyMapRemoteTileSource1 [SlippyMapRemoteTileSourceN] Section
SlippyMapTiles Change the Map Source
smartcards Smart Card Support
SmartcardUPNMatch SmartcardUPNMatch
SMS appliance tags SMS Appliance Tags
SMS modem indicator widget SMS Indicator Widget
SMSTextSubstitution SMSTextSubstitution
SMTPPort SMTPPort
snap lines Snap Lines
Snapshot ChangeSet ChangeSets for Distribution
SNMP addressing SNMP I/O Addressing
SNMP agent SNMP Agent Configuration
SNMP comm. messages dialog SNMP Communication Messages Dialog
SNMP Driver SNMP Driver
SNMP driver comm. statistics dialog SNMP Driver Statistics Dialog
SNMP driver tags SNMP Driver
SNMPAgentEnable SNMPAgentEnable
SNMPAgentInformRetryInterval SNMPAgentInformRetryInterval
SNMPAgentInformRetryLimit SNMPAgentInformRetryLimit
SNMPAgentIPListener SNMPAgentIPListener
SNMPAgentMaxRepetitionsCap SNMPAgentMaxRepetitionsCap
SNMPAgentMaxTCPSize SNMPAgentMaxTCPSize
SNMPAgentMaxUDPSize SNMPAgentMaxUDPSize
SNMPAgentReadCommunity SNMPAgentReadCommunity
SNMPAgentSessionTimeout SNMPAgentSessionTimeout
SNMPAgentSNMPVersion SNMPAgentSNMPVersion
SNMPAgentTagExposedProperties SNMPAgentTagExposedProperties
SNMPAgentTagNotifyMode SNMPAgentTagNotifyMode
SNMPAgentTrapCommunity SNMPAgentTrapCommunity
SNMPAgentTrapHost SNMPAgentTrapHost
SNMPAgentTrapPort SNMPAgentTrapPort
SNMPAgentWriteCommunity SNMPAgentWriteCommunity
SNMPAgentWriteEnable SNMPAgentWriteEnable
SNMPDriverLegacyV3Notifications SNMPDriverLegacyV3Notifications
SNMPDriverOctetStringMaxSize SNMPDriverOctetStringMaxSize
SNMPFailoverCount SNMPFailoverCount
SNMPGetBulkDistributor SNMPGetBulkDistributor Tag
SNMPv3AgentMinSecurityLevel SNMPv3AgentMinSecurityLevel
SNMPv3AgentReadAuthPassword SNMPv3AgentReadAuthPassword
SNMPv3AgentReadAuthProtocol SNMPv3AgentReadAuthProtocol
SNMPv3AgentReadPrivPassword SNMPv3AgentReadPrivPassword
SNMPv3AgentReadPrivProtocol SNMPv3AgentReadPrivProtocol
SNMPv3AgentReadUser SNMPv3AgentReadUser
SNMPv3AgentTrapAuthPassword SNMPv3AgentTrapAuthPassword
SNMPv3AgentTrapAuthProtocol SNMPv3AgentTrapAuthProtocol
SNMPv3AgentTrapPrivPassword SNMPv3AgentTrapPrivPassword
SNMPv3AgentTrapPrivProtocol SNMPv3AgentTrapPrivProtocol
SNMPv3AgentTrapUser SNMPv3AgentTrapUser
SNMPv3AgentWriteAuthPassword SNMPv3AgentWriteAuthPassword
SNMPv3AgentWriteAuthProtocol SNMPv3AgentWriteAuthProtocol
SNMPv3AgentWritePrivPassword SNMPv3AgentWritePrivPassword
SNMPv3AgentWritePrivProtocol SNMPv3AgentWritePrivProtocol
SNMPv3AgentWriteUser SNMPv3AgentWriteUser
SOAP Web Services Terms , Web Services and XML
SoapServicesRealmName SoapServicesRealmName
SocketAttribs SocketAttribs
SocketPingSetup SocketPingSetup
SocketServerEnd SocketServerEnd
SocketServerManager\ArrayToString SocketManagerServer ArrayToString
SocketServerManager\Register SocketServerManager Register
SocketServerManager\StringToArray SocketManagerServer StringToArray
SocketServerManager\UnRegister SocketServerManager UnRegister
SocketServerStart SocketServerStart
SocketWait SocketWait
Soft Phone Using VoIP for Alarm Notification
softphone Setting Up a Specific VoIP Connection
SOM Web Services Terms
Sort Sort
sort button (Legacy) Sort Button
SortArray SortArray
Sound Sound
source debugger utility Source Debugger
Sparklines Sparklines Widget
Sparkplug Edge Device Sparkplug Edge Device
Sparkplug Edge Node Sparkplug Edge Node
SparkplugBEngUnitsProperty SparkplugBEngUnitsProperty
SparkplugBRangeMaxProperty SparkplugBRangeMaxProperty
SparkplugBRangeMinProperty SparkplugBRangeMinProperty
SparkplugLegacySTATE SparkplugLegacySTATE
Spawn Spawn
Speak Speak
SpeakToFile SpeakToFile
specify the startup page for a subordinate Master & Subordinate Applications
speech Working with Speech
speech lexicon Configure Speech Lexicon
SpeechEnum Obsolete Functions
SpeechLexiconDlg Obsolete Functions
SpeechReset Obsolete Functions
SpeechSelect Obsolete Functions
SpeechSpeak Obsolete Functions
SpeechStream Obsolete Functions
Spinbox Spinbox
splash screen NoSplash
SplitList SplitList
SplitListSelector SplitListSelector
SplitPath SplitPath
SplitString SplitString
SplitTagSelector SplitTagSelector
spoken alarms Configuring Spoken Alarms , Alarm Display & Tasks
AlarmSpeechEnable Configuring Spoken Alarms
AlarmSpeechInit Configuring Spoken Alarms
AlarmSpeechQuality Configuring Spoken Alarms
AlarmSpeechTemplate Configuring Spoken Alarms
AlarmSpeechVoice Configuring Spoken Alarms
message templates Alarm Message Templates
SpeechEngine Configuring Spoken Alarms
UseOldSpeechEngine Configuring Spoken Alarms
SQL Data Query Tag SQL Data Query Driver
SQL data types SQL Data Types
SQL Driver. statistics dialog SQL Data Driver Statistics Dialog
SQL logger group tags SQL Logger Group Tags
SQL logger tags SQL Logger Tags
SQLDataQueryDriverDefaultDBType SQLDataQueryDriverDefaultDBType
SQLDataQueryDriverDefaultTableName SQLDataQueryDriverDefaultTableName
SQLDataQueryDriverFailoverCount SQLDataQueryDriverFailoverCount
SQLite Historian Data Storage
SQLLoggerDefaultLogInterval SQLLoggerDefaultLogInterval
SQLLoggerDefaultMaxDataAge SQLLoggerDefaultMaxDataAge
SQLLoggerDefaultTagDataTableName SQLLoggerDefaultTagDataTableName
SQLLoggerDefaultTagIdTableName SQLLoggerDefaultTagIdTableName
SQLLoggerDeleteInterval SQLLoggerDeleteInterval
SQLLoggerDeleteOffset SQLLoggerDeleteOffset
SQLLoggerGroupSharedRPC SQLLoggerGroupSharedRPC
SQLLoggerLogInvalids SQLLoggerLogInvalids
SQLPaginationEnabled SQLPaginationEnabled
SQLQuery Querying the Alarm History , SQLQuery
SQLQueryDriverMaxTagsPerQuery SQLDataQueryDriverMaxTagsPerQuery
SQLQueryHideLegacyTables SQLQueryHideLegacyTables
SQLQueryHistoryNoOverridesTableName SQLQueryHistoryNoOverridesTableName
SQLQueryMaxRequestLength SQLQueryMaxRequestLength
SQLQueryMaxResultCells SQLQueryMaxResultCells
SQLQueryMaxResultRows SQLQueryMaxResultRows
SQLQueryParserDepthLimit SQLQueryParserDepthLimit
SQLQueryRetrieveData RegisterCustomTable
SQLQueryTableTPPs SQLQueryTableTPPs
SQLServer Historian Data Storage
SQLTagParmExtraColumns SQLTagParmExtraColumns
Sqrt Sqrt
SquelchDetectDelay SquelchDetectDelay , Sequence of Events for Incoming Calls
SquelchIdleTime SquelchIdleTime , Sequence of Events for Incoming Calls
SquelchPacketLength Sequence of Events for Incoming Calls , SquelchPacketLength
SRead SRead
SSL certificate Thin Clients: Mobile and Internet , Internet Security (TLS, X.509, SSL)
standard applications Structure and Rules
Standard Report Report Types Described
StandardServerLists Section Names
star Tag Icon Marker
Start Start
start an application Start and Stop
Start Tag Expressions Automated Tag Configuration
start VTScada Start and Stop
Start, expression manager module ExpressionManager Subroutines
start, splash animation NoSplash
Started Variables available in RPCManager
StartOfWeek StartOfWeek
StartSound Obsolete Functions
StartTag StartTag
startup animation NoSplash
State0DefColor State0DefColor
State1DefColor State1DefColor
State2DefColor State2DefColor
State3DefColor State3DefColor
StateDiagram Obsolete Functions
StateHighlighted Obsolete Functions
StateList StateList
StatementInstance StatementInstance
StateName StateName
static array Comparison of Static and Dynamic Arrays
StaticSize StaticSize
station icon widget Site Icon Widget
station mask Read-Only Workstation
station summary widget Site Summary Widget
station tags Station Tags , Recipe and Batch Processing Tags
StationMaskApp StationMaskApp
StationMaskSys StationMaskSys
statistics History Statistics Tag
statistics button Modem Statistics
statistics, communication drivers Maintaining Statistics
StatsWin StatsWin
status color indicators Equipment / Status Color Indicator
Step Step
Step Buttons Step Buttons
sticky mode Define the Connection Addresses
Stop Stop
stop an application Start and Stop
stop bit Serial Port Tags
StopPage StopPage
stopped sending notifications Google & Microsoft vs Basic Authentication
StorageLocation StorageLocation
StorageType StorageType
StrCmp StrCmp
stream cipher Cryptography Terms and Abbreviations
StreamEnd StreamEnd
StretchBackground StretchBackground
StrICmp StrICmp
StrictlyEqual StrictlyEqual
StrictlyNotEqual StrictlyNotEqual
String Droplist Widget Droplist Widget
String Entry Widget String Entry Widget
strings Value Types
StrJustify StrJustify
StrLen StrLen
Struct Struct
structures
overview Structures
style settings tag Style Settings Tags
Submit Button Widget Submit Button Widget
subordinate Master & Subordinate Applications
Subroutine Launched Versus Called Modules
SubStatementIndex SubStatementIndex
SubStr SubStr
Sum Sum
SumBuff SumBuff
SuperUser Built-In Roles
Suppress Alarms Suppress Alarms
suppress privileges Suppress or Reveal Privileges
sweep select Select and Arrange
Switch The Configuration Folder Module
Switch Servers System Privilege Reference for Developers
SWrite SWrite
symmetric encryption Cryptography Terms and Abbreviations
Sync Status Indicator Sync Status Indicator Widget
Sync.WIF Moving to the Current Version
Synchronizable State, definition RPC Manager Service
SyncOEMLayers SyncOEMLayers
SyncServAuditDeferTime SyncServAuditDeferTime
SyncServConnectTimeout SyncServConnectTimeout
SyncServSyncTimeout SyncServSyncTimeout
Syntax Syntax Rules for Expressions
SysPrivDefault SysPrivDefault
SysPrivSuppress SysPrivSuppress
SYSTEM Section Names
system status tools Historian Status
SystemAlarmAreas Section Names
SystemAvailableMemoryBytes Workstation Status Driver I/O Addressing
SystemAvailablePhysicalMemoryBytes Workstation Status Driver I/O Addressing
SystemCPU Workstation Status Driver I/O Addressing
SystemSelf SystemSelf
SystemTotalMemoryBytes Workstation Status Driver I/O Addressing
SystemUsedMemoryBytes Workstation Status Driver I/O Addressing
SystemUsedMemoryPercentage Workstation Status Driver I/O Addressing
SyTech Incporporated Log and Report

T

T Functions T Functions
Table Obsolete Functions
TableInterpolation TableInterpolation
TableSynch TableSynch
Tag Tag
Tag Add/Copy Privilege System Privilege Reference for Developers
Tag Area Filtering Tag Area Filtering
tag browser The Tag Browser
Tag Delete Privilege System Privilege Reference for Developers
tag I/O Link to a Driver
tag icon marker Tag Icon Marker
tag import/export Edit Tags Outside of VTScada
tag links Tag Links Panel , Tag Links Panel
Tag Links Panel Tag Links Panel
Tag List Drawing Method Tag List Widget
Tag Modify Privilege System Privilege Reference for Developers
tag parameter expression Automated Tag Configuration
Tag Parameter View System Privilege Reference for Developers
tag parameters Tag Configuration Parameters
tag properties Tag Properties
tag selector (HDV) Select Pens (Tags) to Plot
tag states Tag States
tag template modules Tag Template Modules
tag tooltips ToolTip Contents
Tag Widget Create Widgets
tag widgets Create or Assign Tag Widgets
TagField1Name TagField1Name
TagField2Name TagField2Name
TagField3Name TagField3Name
TagIconMarker TagIconMarker
TagNameDelimiter TagNameDelimiter
TagParameterEdit TagParameterEdit
tags Tag Reference
adding Add a New Tag
copying Copy an Existing Tag
deleting Delete a Tag
tags - custom Custom Tag Types
tags - naming Best Practices for Tags
tags folder Application Files and Folders
TagShutdown TagShutdown Module
Tan Tan
TAPI Modem Manager Service , Modem Configuration and Use
TAPI errors Call Progress and Error Codes
Target Target
task bar style (realm display setup) Realm Display Setup Tags
TBox RTU History Data for a TBox RTU
TCP/IP TCP/IP Port Tags
TCP/IP Networking TCP/IP Networking
TCP/IP port tag TCP/IP Port Tags
TCPIPPortMaxRcvLen TCPIPPortMaxRcvLen
TCPIPPortMaxXmtLen TCPIPPortMaxXmtLen
TCPIPReset Obsolete Functions
TeleBUS driver tag TeleBUS Statistics Dialog
telephony application programming interface Modem Manager Service
TempFileStream TempFileStream
template Alarm Message Templates
Template ChangeSet ChangeSets for Distribution
Template ChangeSets ChangeSets for Distribution
templates, alarm messages Alarm Notification Templates
TempLoggerEnable TempLoggerEnable
TempLoggerExpiryPeriod TempLoggerExpiryPeriod
temporary variables Temporary Variables
Ternary Operators
TescoDriverDiagnosticLogAge TescoDriverDiagnosticLogAge
TescoDriverDiagnosticLogDuration TescoDriverDiagnosticLogDuration
TescoDriverDiagnosticLogEnable TescoDriverDiagnosticLogEnable
TescoDriverDiagnosticLogRecentSize TescoDriverDiagnosticLogRecentSize
TescoDriverDisableCommStats TescoDriverDisableCommStats
TescoFailoverCount TescoFailoverCount
TescoPortErrorDelay TescoPortErrorDelay
TescoSharedRPC TescoSharedRPC
test framework Test Framework Application
Text Text
text - adding Text
text - data type Value Types
text change widget Text Change Widget
Text Format Ribbon Ribbons
TextAttribs TextAttribs
TextBox TextBox
TextEncode TextEncode
TextIP2Bin TextIP2Bin
TextOffset TextOffset
TextParameterEdit TextParameterEdit
TextSearch TextSearch
TextSize TextSize
TGet TGet
ThemedPageBGColor ThemedPageBGColor
Themes System Properties - Setup.ini
Thermometer Widget Thermometer Widget
thin client Thin Clients: Mobile and Internet
Thin client connections Thin Clients: Mobile and Internet
ThinClientDisclaimer ThinClientDisclaimer
ThinClientFraming ThinClientFraming
Thread Thread
thread list utility Thread List Application
thread snapshot Thread List Application
Threaded Launched Versus Called Modules
ThreadHistory ThreadHistory
ThreadIdle ThreadIdle
threading Threading
ThreadList ThreadList
ThreadName ThreadName
ThreadPriority ThreadPriority
thumbnail Page Property Reference
TI505FailoverCount TI505FailoverCount
TI505PropagateOnlyOnDataChange TI505PropagateOnlyOnDataChange
TI505SharedRPC TI505SharedRPC
tiled image Images
tiles Site Map
Time Time
time adjustments Time Synchronization Manager Service
time formats Time Formatting Codes
Time Range Mode Draw HDV Widget
time synchronization DNP3 Driver
time synchronization manager Time Synchronization Manager Service
time zone functions VTScada and Time Zones
time, concepts Time and Date
TimeArrived TimeArrived
TimeOut TimeOut
timers Timers and Timing
TimestampParameterEdit TimestampParameterEdit
timesync properties Time Synchronization Manager Properties
TimeSyncEnable TimeSyncEnable
TimeSyncMicroAdjust TimeSyncMicroAdjust
TimeSyncRPCQMax TimeSyncRPCQMax
TimeSyncUpdtItrvl TimeSyncUpdtItrvl
TimeUtils\GetPeriods TimeUtils
TimeUtils\Periods TimeUtils
TimeZone TimeZone
TimeZoneList TimeZoneList
TipBack TipBack
TipFore TipFore
TipOff TipOff
TipOn TipOn
Title Working with Pages
title bar decorations Page Property Reference
title bar style (realm display setup) Realm Display Setup Tags
TitleLogoTarget TitleLogoTarget
Today Today
TODBC TODBC
TODBCBeginTrans TODBCBeginTrans
TODBCCommit TODBCCommit
TODBCConnect TODBCConnect
TODBCDisconnect TODBCDisconnect
TODBCRollback TODBCRollback
Toggle Toggle
Toggle Button Toggle Button Widget
toggle switch widget Toggle Switch Widget
ToggleVal ToggleVal
Token Administrator System Privilege Reference for Developers
Token Level Box Token Level Box
Token Level Icon Token Level Icon
Token Request System Privilege Reference for Developers
Token Requests List Token Requests List
Tokens List Tokens List
ToLower ToLower
tool tip widget Tool Tip Widget , Tool Tip Widget
tool tip, disable Choices for Operator Interaction
ToolBar ToolBar
tooltip Operational Controls
tooltip properties Tooltip Properties
tooltip visibility Tooltips Do Not Appear
tooltips Native Windows Tooltip Support
top bar widget Top Bar Widget
totalizer tags Totalizer Tags
totalizer widget Totalizer Widget
TOTP Two Factor Authentication with TOTP
ToUpper ToUpper
ToValue, expression manager module ExpressionManager Subroutines
Toyopuc Toyopuc Driver
ToyopucDriverVTSMaxBlock ToyopucDriverVTSMaxBlock
TPPath TPPath
trace viewer utility Trace Viewer Application
trace VTS actions Trace VTScada Actions Application
TraceBrowser TraceBrowser
TraceCM TraceCM
TraceDispMgr TraceDispMgr
TraceDlg TraceDlg
TraceMenuEd TraceMenuEd
TraceModem TraceModem
TraceNav TraceNav
TracePageMgr TracePageMgr
TracePLimit TracePLimit
TraceRamRecs TraceRamRecs
TraceRPC TraceRPC
TraceSQL TraceSQL
TraceTagCfg TraceTagCfg
TraceToFile TraceToFile
TraceTool TraceTool
TraceUserConfigActions TraceUserConfigActions
TraceVAM TraceVAM
Trajectory Trajectory
Transaction Transaction
transaction definition The Alarm Page
Transaction Logger tags Transaction Logger Tags
TransactionCached TransactionCached
TransferFields, alarm function TransferFields
translucent window Transparent and Alpha-blended Windows
TransmitColor TransmitColor
transparent Opacity , Color Selector
transparent window Transparent and Alpha-blended Windows
TreeControl, system module TreeControl
trend window, disable Choices for Operator Interaction
trending Trending and Plotting Functions and Statements
trending properties Trending (HDV) Properties
TrendOnTop TrendOnTop
TrendTimeFormat TrendTimeFormat
trigger Create Alarms
trigger (report tags) Report Tags
trigger tags Trigger Tags
TriggerCounter TriggerCounter
Trihedral voice modem service Modem Manager Service
Trim (wizard engine) Cleaning Up Input [Trim]
TrimSpaces TrimSpaces
Trip Alarm Create Alarms
Trip, alarm function Trip
Troubleshoot Troubleshoot
troubleshooting Troubleshoot
Troubleshooting Operator's Guide to Security
True TRUE
TServerList TServerList
TSERVICES Class Declarations for Modules in AppRoot
TSP Modem Configuration and Use
Twilio Using Twilio for Alarm Notifications
TwilioMaxLogAge TwilioMaxLogAge
TwilioPickupDelay TwilioPickupDelay
TwilioShowCredentials TwilioShowCredentials
TwilioTraceInterval TwilioTraceInterval
TwilioTraceMax TwilioTraceMax
two color bar widget Two Color Bar Widget
two-factor authentication OpenID Connect Authentication
Two-factor authentication Secure Your Application
Type - definition Design Your Own Tags
type - new application Reusable Application Layers
TypeFilter Type Filters

U

U Functions U Functions
UDP/IP port tag UDP/IP Port Tags
UIErrorToText UIErrorToText
UnackAlarmFlash UnackAlarmFlash
UnackFlashRate UnackFlashRate
UnEscape UnEscape
ungroup Create Widgets
Unico POC-Unico Tags
UniModem TAPI and UniModem Considerations
Unimodem V Modem Manager Service , Modem Configuration and Use
uninstalling Uninstall VTS
UniqueID Custom Tag Types
unlinked widgets Special Symbols for Tags
Unpack Unpack
UnpackData UnpackData
UnpackParms UnpackParms
Unregister Unregister
UnRegister - SocketServerManager SocketServerManager UnRegister
UnselectedBgnd UnselectedBgnd
UnselectedText UnselectedText
UnselectGraphics UnselectGraphics
UnselectObject UnselectObject
UnTransform UnTransform
UnTypedParameterEdit UntypedParameterEdit
Update Location Site Map
Update Site Location Site Map
update type Modify a Custom Type
UpdateCoordinates UpdateCoordinates
UpdateOPCData Make a Custom Tag Visible to OPC Clients
updating applications Moving to the Current Version
upgrade notes Moving to the Current Version
UPN Smart Card Support
UPS System Properties - Setup.ini
UPS Configuration OrderlyShutdown
use VoIP for alarm notifications Setting Up a Specific VoIP Connection
UseLegacyEventPriorityAlarmBehavior UseLegacyEventPriorityAlarmBehavior
UseLegacyHistoryPriorTo UseLegacyHistoryPriorTo
UseOldSiteDialog UseOldSiteDialog
UseOnScreenKeypad UseOnScreenKeypad
user files Application Files and Folders
user groups Security Realms
user input Obtaining User Input
UserCredChange UserCredChange
UserFilterIconColorize UserFilterIconColorize
UserFilterIconFlash UserFilterIconFlash
UserFilterMode UserFilterMode
UserLogonDialog UserLogonDialog
UserName UserName
UseSerialAreaInModemCall UseSerialAreaInModemCall
UseSMTPOverTLS UseSMTPOverTLS
UseUnimodem UseUnimodem
UWI POC-DV8 Tag , Flow Computer Tags , POC-Unico Tags , Weatherford Tag , POC-Lufkin SAM Well Manager

V

V Functions V Functions
Valid Valid
valid characters Naming Rules
ValidateEmailAddrs ValidateEmailAddrs
ValidateHistory Obsolete Functions
value Required Variables and Constants
ValueIsErrorAbove Create or Assign Tag Widgets
ValueIsErrorBelow Create or Assign Tag Widgets
ValueIsErrorStatus Create or Assign Tag Widgets
ValueSyncService ValueSyncService
ValueType ValueType
VAMIcon VAMIcon
VAMStopAppCheck Interrupt the Shutdown Process
VarAttributes Obsolete Functions , VarAttributes
Variable Variable
VariableClass VariableClass
variables Value Types
Variance Variance
VDRSharedRPC VDRSharedRPC
Version Version
version property (wizard engine) The VTScada Wizard Engine
Version Selector (Recipes) Recipe Version Selector
VersionRequired VersionRequired
Vertex Vertex
vertical button widget Vertical Buttons Widget
VIC properties Thin Client Server and Client Properties
VIC URL Configure a Realm
VICAutoAddDebugTools VICAutoAddDebugTools
VICDistributionPath VICDistributionPath
VICInfo VICInfo
VICMessage VICMessage
VICMonitorLogFileName VICMonitorLogFileName
VICMonitorPageInfo Monitor Internet Connections
VICSmartcardMonitor VICSmartcardMonitor
VICSmartcardResponse VICSmartcardResponse
VICSmartcardsEnable VICSmartcardsEnable
Viper SC CalAmp Diagnostic Driver
virtual server Virtual Servers
VirtualMemory Workstation Status Driver I/O Addressing
VLookup TableInterpolation
Voice Call Redundancy Voice Call Redundancy
VoiceTalk VoiceTalk
VoIP Using VoIP for Alarm Notification
VoIP Application Configuration Setting Up a Specific VoIP Connection
VOIPCertName VOIPCertName
VOIPEnableTLS VOIPEnableTLS
VOIPMediaPort VOIPMediaPort
VOIPMediaPortRange VOIPMediaPortRange
VOIPPickUpDelay VOIPPickUpDelay
VOIPPublicAddress VOIPPublicAddress
VOIPRegisterTimeout VOIPRegisterTimeout
VOIPTLSPort VOIPTLSPort
VRDPLCConnAttLimit VRDPLCConnAttLimit
VScrollbar VScrollbar
VStatus VStatus
VTable Interfaces Introduction to COM
VTS/IS Configure a VTScada Thin Client Server
VTScada Alarm Dialer Alarm Notification System - Alerts by Phone, Email or Text
VTScada Historian Historian Tag
VTScada Internet Server Configure a VTScada Thin Client Server
VTScada ODBC Driver SQL Queries
VTScada OPC Driver OPC Classic Configuration
VTScadaLIGHT Welcome , Licensing
VTSCPU Workstation Status Driver I/O Addressing
VTSDriver module Communication Process
VTSDriverClearDataOnServerLossDelay VTSDriverClearDataOnServerLossDelay
VTSDrvr.web Communication Process
VTSExit Interrupt the Shutdown Process
VTSGetAddr VTSGetAddr
VTSMaxBlock, driver module VTSMaxBlock
VTSRead, driver module VTSRead
VTSSQLInterface Querying the Alarm History
VTSWrite, driver module VTSWrite
VTSX Connect Using the VTSX Program

W

W Functions W Functions
W3C Web Services Terms
Watch Watch
Watch Window Watch Window
WatchArray WatchArray
WatchForTagChanges WatchForTagChanges
WatchTags WatchTags
WavAmplitude WavAmplitude
WAVType WAVType
WCSubscribe WCSubscribe
Weatherford Weatherford Tag
Weatherford Overview Weatherford Overview
Web Browser Widget Web Browser Widget
Web Service Web Services Terms
web services Web Services and XML
WebBrowser WebBrowser
WebBrowserNavigate WebBrowserNavigate
WebSktSubscribe WebSktSubscribe
WebSocket WebSktSubscribe , WebSocket Support
WelcomeToTheLabel WizardWelcomeLabel
WhileLoop WhileLoop
Widget Format Ribbon Ribbons
Widget Properties Ribbon Ribbons
Widgets Operational Controls , Searching for Widgets
WinButton WinButton
WinComboCtrl WinComboCtrl
Window Window
window height (realm display setup) Realm Display Setup Tags
window width (realm display setup) Realm Display Setup Tags
WindowBgnd WindowBgnd
WindowClose WindowClose
WindowFrame WindowFrame
WindowOptions WindowOptions
WindowsLogon WindowsLogon
WindowSnapshot WindowSnapshot
WinEditCtrl WinEditCtrl
WinLocSwitch WinLocSwitch
WinMatchKeys WinMatchKeys
WinShiftKeys WinShiftKeys
WinTooltipCtrl WinTooltipCtrl
WinXLoc WinXLoc
WinYLoc WinYLoc
wizard engine The VTScada Wizard Engine
wizard engine, interface Basic Wizard Engine Module
Wizard properties Wizard Engine Properties
WizardFinishText1 WizardFinishText1 , Wizard Configuration Settings
WizardFinishText2 Wizard Configuration Settings
WizardFinishText3 Wizard Configuration Settings
WizardFinishTitle WizardFinishTitle , Wizard Configuration Settings
WizardWelcomeTitle Wizard Configuration Settings
WKSList WKSList
WKSPath WKSPath
WKSStatus WKSStatus
WKStaInfo WKStaInfo
WkStnIP Variables available in RPCManager
WkStnIPList Variables available in RPCManager
WkStnName Variables available in RPCManager
WkStnVersion Variables available in RPCManager
working files Application Files and Folders
workspace - source debugger General Tab
workstation status tag addressing Workstation Status Driver I/O Addressing
workstation status tags Workstation Status Tag
Workstation.Dynamic Configuration File Structure
workstation.dynamic Workstation-Specific Properties
Workstation.INI Moving to the Current Version
Workstation.Startup Configuration File Structure
workstation.startup Workstation-Specific Properties
WrapText WrapText
Write Write
write rate - historian status Historian Status
WriteHistory WriteHistory
WriteINI WriteINI
WriteINIProperties WriteINIProperties
WriteLock WriteLock
WritePropertiesFile WritePropertiesFile
WriteSectINI WriteSectINI
WSDL Web Services Terms
WSDL document Web Services and XML
WSDrvr, web services variable WSDrvr Services
WSI Windows Authentication Notes

X

X Functions X Functions
XLoc XLoc
XLookup TableInterpolation
XLReporter Log and Report
XmitBuff ShowComm Submodule
XML Web Services Terms , Web Services and XML
XML API VTScada Engine XML API
XML Document Web Services Terms
XML file (MultiSmart) MultiSmart Station Tags
xml mime type MIME Types Supported
XML Processor Validating versus non-Validating XML Processors , Web Services Terms
XML Schema Web Services Terms
XMLAddSchema XMLAddSchema
XMLCloneNode XMLCloneNode
XMLCreateNode XMLCreateNode
XMLDeleteMember XMLDeleteMember
XMLGetNode XMLGetNode
XMLParse XMLParse
XMLProcessor XMLProcessor
XMLWrite XMLWrite
XOr XOr
XSLT Web Services Terms

Y

Y Functions Y Functions
Year Year
yellow blob Tag Icon Marker
yellow tag fields Configuration Field Colors
YLoc YLoc

Z

Z Functions Z Functions
ZBar ZBar
ZBox ZBox
ZButton ZButton
ZColorChange ZColorChange
ZEditField ZEditField
ZGrid ZGrid
Zip Zip
ZLine ZLine
zoom - HDV Adjust the Plot
Zoom Controls Display Building (Idea Studio)
ZPipe ZPipe
ZText ZText


Use VTScada as DDE Server

Use VTScada as a DDE Server

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. The below directions are required to run it.

VTScada can be used as a DDE server. This functionality is turned off by default. To activate, you must start VTScada with the command line switch, ' /d'.

For example:

c:\Program Files\Trihedral\VTScada\VTScada_YourVersionNumber\vts.exe /d

The /d flag must be run directly on the VTScada executable each time, it will not retain the DDE mode on subsequent runs without it. Windows desktop shortcuts can be configured to supply flags such as this one to VTScada each time, see "Configure VTScada DDE Shortcut" below.

Excel Configuration

Review Security settings for Dynamic Data Exchange to learn about enabling security features Server Lookup and Server Launch in the Microsoft 365 Excel Trust Center.

DDE functionality is commonly configured to rely on Excel spreadsheets to store and organize data. Windows may require settings specific to the version of Windows VTScada is being run on.

Windows Office 2000: This pop up will appear on start up. Select 'Yes'.

Windows Office 2003: This pop up will appear on start up. Select 'Update'.

Windows Office 2007: Select 'Options' > enable 'Enable this content' and then 'OK' to close.

VTScada Data Display in Excel

In your client program, you must provide address information for the VTScada program, the name of the running application, the names of the tags you wish to query, and the name of the property you want to obtain from each tag (usually '\value').

The most common use-case is to configure Microsoft Excel to display VTScada tag values in the cells of a spreadsheet. This can be done using a formula for each cell, as follows.

The formula has four parts: the name of the program (VTS), the name of the application, the name of the tag, and the property of the tag to obtain.

As entered in an Excel spreadsheet cell, the formula would have this form:

=VTS|'AppName'!'TagName\Value'

This formula is not literal. The various components are described in the following table.

If there are multiple display manager windows, the reference must be to a specific display manager session. The format changes to =VTS|'AppName 1' !'TagName\Value' (or 2, etc). Without this change, you will get an error message that Excel cannot start VTS.

If the tag name you've specified has spaces, back-slashes, or other characters that Excel might interpret as anything other than the name, then you must surround the 'Tag Name\Property' portion of the function with single quotes as shown. It is advisable to do this for every instance, whether required or not.

Syntax | Description
= | The equals sign (=) indicates to Excel that this is a formula.
VTS | VTS is literal, specifying the name of the program to access. If VTScada is not running when the spreadsheet opens, it will be started automatically.
| | The pipe character separates the program name from the document or topic name. (In the case of VTScada, this is the application name.)
AppName | Following the pipe character is the application name. Note: If the application name includes spaces, you must use single quotes to surround the name.
! | The exclamation point character is the topic item delimiter, separating the application name from the tag to which you are referring.
TagName | Following the exclamation point character should be the name of the tag whose data you want to report in the spreadsheet cell. The tag name should appear exactly as it is displayed in the name property of the tag properties folder.
\ | The back slash character (\) is the scope operator, separating the tag name from the property or data to which you are referring.
Value | The name of one of the tag's properties, whose value you want to report in the cell. In most cases, this will be Value, but it could also be, Name, Area, Description, etc.

Formula Examples

The following formula examples have been provided to assist you in setting up Excel spreadsheet cells to read values from VTScada tags.

Given an application named, "DDE Test" and containing a tag named "AnalogInputTag"...

To display the tag's value in a spreadsheet cell:

=VTS|'DDE Test'!'AnalogInputTag\Value'

To display the name of the same tag's associated I/O device:

=VTS|'DDE Test'!'AnalogInputTag\IODevice'

To display the description of the same tag:

=VTS|'DDE Test'!'AnalogInputTag\Description'

The name of the tag configuration variable you are requesting must be written exactly as it occurs in the tag's code. If you are unsure, use the Source Debugger to examine an instance of the tag type.

Configure VTScada DDE Shortcut

Following these directions, you can create a new desktop shortcut to run VTScada with DDE functionality.

  1. You will need the file path of your VTSLauncher.exe. If you already have a VTScada shortcut you can find it by right-clicking on the VTScada Desktop Shortcut and selecting 'Show more options' > 'Properties'. Copy the address from the 'Target' field under the 'Shortcut' tab.

  2. Right-click on your desktop background and select 'New' > 'Shortcut' in the context menu. Paste the location of your VTSLauncher in the search bar.

  3. Select 'Next', enter a name for your new shortcut (i.e. "VTS DDE Mode") when prompted and select 'Finish'.

  4. Right-click on your new desktop icon and select 'Show more options' > 'Properties'.

  5. Under the shortcut tab, within the Target field, go to the end of the address and type a space and '/d' after the last quotation mark.

  6. Select 'Apply' and 'OK' to save. Now the DDE flag will be supplied every time you launch VTScada with this desktop shortcut.

Related information:

VTScada as a Local DDE Client - How VTScada can read from (and write to) a DDE server program.


VTScada as a Local DDE Client

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.

When VTScada is a local DDE Closed Dynamic Data Exchange client, data from items within a DDE server will be reported as the value of a tag in VTScada. For example, you might want a tag to mirror the value of a cell in an Excel workbook.

You can write as well as read. In the example that follows, substitute an Analog Output or Analog Control for the input tag and you will send values out, rather than read them in.
There must be one tag for each item read from (or written to).

There are three tasks to complete for VTScada to read values from a DDE server:

  1. Create a DDE data source.

For example, a Microsoft Excel™ spreadsheet.

  2. Configure a new DDE Client tag within your VTScada application to communicate between VTScada and the DDE server.
  3. Configure a new input tag within your VTScada application to read a value from the data source.

Continuing the example, the value might be read from a cell in the spreadsheet.

Example: Configuring VTScada to read values from Excel spreadsheet cells:

Part 1: Excel

  1. Create or select a Microsoft Excel spreadsheet, containing values that you wish to read.
  2. Within Excel's options dialogs, the R1C1 reference option must be selected.
  3. Save the file to your VTScada application's folder. Example: "MySpreadsheet.xlsx"

Part 2: VTScada DDE Client tag

  1. Open the VTScada application that is to read values from Excel.
  2. Create a new DDE Client tag, providing a name.
  3. Open the Local DDE tab of the driver tag.
  4. Set the name of the DDE application to "Excel".
  5. Set the name of the DDE topic to the name of the spread sheet file, "MySpreadsheet.xlsx".
  6. The Network DDE tab is not required for a local spreadsheet.
  7. Click OK to save the new tag.

You may with to draw the tag to ensure that there is a connection. A Comm Indicator box is suggested.

Part 3: VTScada Input tag

  1. Create a new Analog Input or Analog Status tag.
  2. Ensure that its I/O device is the DDE Client you created in Part 2.
  3. Set the address to row and column of the cell you wish to read from using the format "RnCn".

For example, R1C3 will read from row 1 (A) and column 3.

  4. Open the Scaling tab of the analog tag.
  5. Set both the Unscaled and the Scaled values to range from 0 to 1.

This results in the analog tag reporting whatever value is in the spreadsheet cell. If your purposes require scaling, adjust the values as needed.

  6. Draw the tag as you wish.

Related information:

Use VTScada as a DDE Server - How to access VTScada data from a DDE client program.

DDE Client - Required to allow VTScada to read from a DDE server program.


VTScada as a Network DDE Client

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.

When VTScada is a network DDE client, data can be entered in the cell of an Excel spreadsheet, and the value will be reported as the value of a tag in VTScada.

Five tasks must be completed to configuring VTScada as a network DDE client.

  1. Configure a new DDE share object using the DDEShare utility.
  2. Configure a new DDE Client tag within your VTScada application to communicate between VTScada and the external application with which you wish to share data.
  3. Select or create an output tag within your VTScada application to write data to the external application.
  4. Select or create an input tag within your VTScada application to read the data that you are writing to the external application to ensure that communications are occurring as they should.
  5. Configure an Excel spreadsheet of the same name specified in your DDE share object, and ensure that the path to the file is correctly configured within Excel for VTScada to locate it.

The steps for each task follow. DDE Share screen-shots were created using Windows XP, the last version of Windows that included native support for this technology. Your screens may differ.

Part 1: Configure a New DDE Share Object Using DDEShare

To designate VTScada as a DDE client, you must first configure the network DDE on the server PC using the DDEShare utility. The following instructions will guide you through the correct process of configuring DDEShare.

  1. Obtain and install a copy of NetDDE.
  2. Open the Windows Start menu.
  3. Enter "DDEShare" in the Search for Programs and Files field.
  4. Click OK. The DDE Share dialog opens.

  5. Double-click the icon that does not display a check mark. The DDE Shares dialog opens similar to the following:

  6. Click the Add a Share button. The DDE Share Properties dialog opens as shown.

  7. Enter a unique name for the share item in the Share Name field followed by the dollar sign character ($) (e.g. "DDEShare$"). (The Share Name will not accept duplicates any of the names of existing shares in the DDE Shares dialog.)
  8. Enter the application name and topic name in the Old Style and New Style fields as shown in the next image.
  9. Select the Allow start application check box. The DDE Share Properties should appear similar to the following:

Observe the example settings shown in the DDE Share Properties dialog above: "book1.xls" identifies the name of the Excel workbook into which the data will be placed. This can be substituted for any Excel workbook name you choose. "Sheet1" is the name of the Excel sheet that the DDE Share is going to access within the selected Excel workbook. You may enter any sheet name you choose, as long as the sheet exists within the specified Excel workbook. Finally, select the "Allow start application" check box to enable VTScada to start Excel and open to the correct sheet in the specified workbook.

  10. Click the Permissions button. The DDE Share Name Permissions dialog opens as shown, and displays the names of the current users and groups.

  11. Select any local or domain users that you to grant access to the new share, and select an appropriate option from the Type of Access drop-down list. If security is not an issue, you may wish to select "Everyone" and set the Type of Access to "Full Control". This will ensure trouble-free connectivity (as far as new users on the network are concerned). A second option might be to create a new group and grant the group permission to access the new share. You can later enable new users to access the share simply by adding them to the group.

  12. Click OK. You are returned to the DDE Share Properties dialog.

  13. Click OK. You are returned to the DDE Shares dialog where the name of the new share is added to the list.

  14. Select the new share in the DDE Shares list. The new share is highlighted.
  15. Click the Trust Share button. The Trusted Share Properties dialog opens as shown.

  16. Select the Start Application Enable check box.
  17. Select the Initiate to Application Enable check box. The Trusted Share Properties dialog should appear as shown:

  18. Click Set to set the properties for the new share.
  19. Click OK. You are returned to the DDE Shares dialog.

  20. Click OK. You are returned to the DDE Share on WorkstationName dialog.

  21. Close the DDE Share on WorkstationName dialog using the Windows close button. You can now begin to configure the DDE Client tag and input/output tags within the VTScada application on the client PC.

Part 2: Configure a New DDE Tag to Communicate between VTScada and an External Application

The next step in communicating between VTScada (the client) and an external application (such as Microsoft Excel), is to create a new DDE tag.

  1. Run VTScada. The VAM opens.
  2. Select the VTScada application from which you wish to output data to the external application.
  3. Click the Run button. The application runs.
  4. Sign in to the application (if necessary) using your username and password.
  5. Navigate to the page upon which you wish to place your DDE-related tag widgets.
  6. Open the Tag Browser.
  7. Select DDE Client from the Types drop-down list.
  8. Click New. The New DDE Client Properties folder opens.
  9. Enter a name for the new DDE Client tag in the Name field.
  10. Enter an area for the new DDE Client tag in the Area field.
  11. Enter a description for the new DDE Client tag in the Description field. An example follows:

  12. Click the Network DDE tab.
  13. Enter the name of the server on which the DDE share created in Part 1 was created in the DDE Computer Name field.
  14. Enter the name of the new DDE share created in Part 1 (in this example, "DDEShare$"), followed by the extension .OLE.

  15. Click OK. The DDE Client tag properties folder closes and the information is saved in the tag properties database. You are returned to the Tag Browser where the name of the new DDE tag is displayed and selected.
  16. Click the Draw button and select the Comm Indicator widget. The Comm Indicator square is attached to the mouse pointer.
  17. Click to drop the Comm Indicator object on the page. The Comm Indicator dialog opens as shown.

  18. Click OK.

The Comm Indicator object shows the status of communications between the DDE Client and the external application, by way of a changing color square. By default, green indicates communications are occurring, red indicates that communications have failed, and gray indicates that the tag is reading invalid (as it should be).

Part 3: Configure a New Input Tag to Read Data from the External Application

The next step in setting up VTScada as a DDE client is to configure a new input tag (either analog or digital) to read data from the external application on the remote PC via the DDE tag created in Part 2. This tag will help you to confirm that the data you will be outputting (via the output tag created in Part 4) is being transmitted.

  1. Open the Tag Browser.
  2. Click New and set the type to Analog Input.
  3. Enter a name for the new Analog Input tag in the Name field.
  4. Enter an area for the Analog Input tag in the Area field.
  5. Enter a description for the Analog Input tag in the Description field. The completed properties for the ID tab of the Analog Input tag properties folder should appear similar to the example shown:

  6. Click the I/O tab.
  7. Select the name of the DDE Client tag from the I/O device drop-down list.
  8. Enter the address of the location from which you wish to read data in the Address field. (In this example, the goal is to read data from row 1 cell 1 of the Excel spreadsheet, therefore enter "r1c1" in the Address field. The completed I/O tab should appear similar to the following image.

  9. Click OK. You are returned to the Tag Browser where the new Analog Input tag is displayed and selected.
  10. Close the Tag Browser.
  11. Open the Idea Studio and select the Widgets palette.
  12. Select one of the widgets that display the numeric value of the tag (i.e. Numeric Value or Meter1, Meter2, or Meter3), and drag it onto the page.
  13. Link the widget to your Analog Input tag.
  14. Configure the widget's display properties as you require.

Part 4: Configure a New Output Tag to Write Data to the External Application

The next step in setting up VTScada as a DDE client is to configure a new output tag (either analog or digital) to write data to the external application on the remote PC via the DDE tag created in Part 2.

  1. Open the Tag Browser.
  2. Click New and set the type to Analog Output.
  3. Enter a name for the new analog output tag in the Name field.
  4. Enter an area for the new analog output tag in the Area field.
  5. Enter a description for the new analog output tag in the Description field.
  6. Click the I/O tab. The properties of the I/O tab are displayed.
  7. Select the name of the DDE Client tag created in Part 2.
  8. Enter the address of the location to which you wish to write data in the Address field. (In this example, the goal is to write data to row 1 cell 1 of the Excel spreadsheet, therefore enter "r1c1" in the Address field.
  9. Click OK.
  10. Close the Tag Browser.
  11. Open the Idea Studio and select the Widgets palette.
  12. Expand the Analog Outputs group.
  13. Select the Numeric Entry widget and drag it onto the page.
  14. Link the widget to the tag you created.
  15. Configure the display properties as desired.

Part 5: Configure an Excel Spreadsheet with the Name as Specified for Your DDE Share Object, and Ensure the Path is Correctly Configured Within Excel

The configuration of VTScada as a DDE client is now almost complete. The only tasks remaining are to create a spreadsheet with the same name as was specified for your DDE share object, and ensure that the path is properly configured within Excel so that VTScada can locate it.

  1. Run Microsoft Excel.
  2. Create a new spreadsheet. Name this spreadsheet with the exact same name as you configured within your DDE share. For example, consider the DDE Share Properties dialog, shown in the following image. In the example DDE share object, the name of the Excel spreadsheet is given as "book1.xls", therefore, the spreadsheet must be named to match.
  3. Save the new spreadsheet in your application directory.

  4. Select Tools|Options in Excel's menu. The Options dialog opens.
  5. Click the General tab.
  6. Enter the path to your application directory in the Default File Location field.
  7. Click OK.

The configuration of VTScada as a DDE client is now complete. To output data values to Excel, simply enter a value in the Numeric Entry field (i.e. the widget you used for your output tag). When you press the Enter key, the value you entered in the Numeric Entry field for the analog output tag is transmitted to the Excel spreadsheet. If you look in the Excel spreadsheet, the cell you specified to write the data to should display the output number. The widget you used for the Analog Input tag should also display the number you entered, as it reads it back from the spreadsheet.

If the value you enter in the Excel spreadsheet is not registering, try stopping both Excel and your VTScada application, compile your VTScada application, then restart it and reenter the value you wish to output.


Create Alarm & Event Queries

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

If your query involves more than one tag or more than one calculation, additional columns will be created as required when the report runs, to a limit of 30 columns. You do not need to create a separate column for every tag and every calculation.

To report on alarms and events, start by clicking in the header row of column A as shown in the following image to open the Data Cell Properties panel. (Timestamps are available within the alarm and event query, and need not be specified in a separate column.)

Selecting the column header in order to access properties

Select column A to define an Alarm and Event query Data Set

With the Data Cell Properties panel, you can do the following for Alarm and Event Data Sets:

Delete the column

Click the trash can icon in the header of the Data Cell Properties panel. Note that deleting the column removes it from the table but does not remove the Data Set definition. (You can delete a Data Set from the Data Set Manager on the bottom-left.)

Create a Data Set

For every column you want to add to your report, you'll be making a Data Set. Data Sets may not always appear in reports. You can maintain a collection to easily swap values in and out of reports or reference Data Sets using other Data Sets.

You're likely to accumulate a lot of them, so it is a best practice to give them a descriptive name.

No predefined Data Sets exist for alarm and event queries. You must create your own.

To create an Alarm & Events Data Set you have two options:

  1. Add a column to the table component. Click the [+] that appears in the new Data Cell Properties pane.

  2. Click the [+] on the bottom-left below the Data Set Manager.

Either of these options will present you with a New Data Set dialog. Choose a name and select "Alarms & Events" as the type.

Set the Type to Alarm and Event

Must be set to "Alarm and Event" for this column to include information from any of the alarm and event databases.

Select a Database

By default, all alarm and event databases will be queried. Select one or more to restrict the query. For example, you should choose the System Event DB if you want a report that shows only operator actions.

Add Data Columns

Data columns are the alarm and event properties that will be included in the report. Add as many data columns as needed by clicking the <<Click to Add>> tool at the bottom of the list. There must always be at least one data column for every Data Set. Columns can include any of alarm event information and alarm configuration information but note that columns that are useful for events might not be useful for alarms and vice versa.

  • Batch Number - The user provided batch number.
  • Batch Start Time- The recorded start time of the batch.
  • Batch End Time- The recorded end time of the batch.
  • Parameters (All)- If Parameters (All) is selected, a column will appear in the final report for every Recipe Parameter tag.
  • Recipe Name- The name of the recipe associated with each batch.
  • Recipe Version- The recipe version number associated with each batch.
  • Step- Multi-step batches will be broken out into multiple lines. Step denotes to which step each line refers.
  • Note- User-provided notes associated with each batch.
  • Batch Duration- The period of time the batch took, the time units can be specified.
  • Step Start Time- The recorded start time of the step
  • Step End Time- The recorded end time of the step
  • Step Duration- The period of time a step took, the time units can be specified.
  • User- The user account that was logged in when the report ran.
  • Parameter (Custom)- Split one recipe parameter out from "Parameters (All)" (that becomes "Parameters (Remaining)") Parameter (Custom) will display the selected parameter in the column name. Add multiple instances to split out multiple parameters.

Define Filters

Use filters to define the alarm or event report that you want to generate. For example, to create a report of all alarm acknowledgments you should ensure that the System Alarm DB (or your own alarm database) is selected and add an Event filter of "Ack". Columns might include Timestamp, Action, User, Description.

Filters match those available within the Alarm Page except that here you can add multiple criteria to each category to be ORed together. e.g. User of "a" or user of "b". Different categories are ANDed together. (See: Sort and Filter the Alarm List).

Description

Filter using the text of the alarm's description field. For the description field only, the filter will include all alarms that include the text you provide, not just those that match the text exactly.

This filter can be made case sensitive.

Name

Filter using the name (or unique id) of the alarm tag. This will find only tags with an exact match for the name. Use leading or trailing wildcards to expand the filter to names that include the provided text.

Select the option, Include children, to filter for a parent tag name and populate the list with all alarms in all child tags of that parent.

Area

Use the drop-down list to select one area property for the field. You may type an area value if you would like to expand the filter using wildcards. For example: Zone* will filter for alarms in Zone 1, Zone 2 and Zone 3.

Priority

The priority option creates a filter matching alarm priority values. Use this to filter the list to show only Critical or High alarms. By selecting the "Or higher priority" option, you can filter for High and also include Critical alarms in the list.

User

Enter the account name of an operator to filter for alarms and events attributed to that operator. It is not possible to filter for more than one operator at a time.

All operator actions including setting output values and shelving alarms, are attributed to the operator signed in at the workstation where the action occurred. Each alarm is attributed to the operator who acknowledges it. Unacknowledged alarms will not be included in this filter.

Event

Select one of the predefined event types from the list to filter for all alarms or events matching that type. Event types are described in Alarm Event Reference

Workstation

Enter the name of a workstation to restrict the report to the events associated with that computer. It is not possible to filter for more than one workstation at a time. (WorkstationA OR WorkstationB is not an option.) No event is associated with multiple workstations (WorkstationA AND WorkstationB would always return an empty report.)

Maximum Records

Optionally, set a maximum record limit for notes that appear within a report.

Notes

Summary information is typically suppressed for alarm and event Data Sets.


Create Tag Queries

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

All tables start with a single column. Click the [+] bar to the right to add more.
Note that a tag query that includes multiple tags or calculations will generate as many columns as needed to display the result of the query.

Tag queries are typically placed in column B of a table. Recommended practice is place a Time-type Data Set in Column A because summary titles (if summary lines are configured) are always placed in the first column, therefore any data that you intend to summarize should be placed in other columns. (Timestamps are not summarized.)

If your query involves more than one tag or more than one calculation, additional columns will be created as required when the report runs, to a limit of 30 columns. You do not need to create a separate column for every tag and every calculation.

Whether configuring a Time column or a query, start by clicking in the title row as shown to open the Data Cell Properties panel.

Select column B to define a tag query Data Set

To Create or Edit a Tag Query

To create a Tag Query Data Set you have two options:

  1. Add a column to the table component. Click the [+] that appears in the new Data Cell Properties pane.
  2. Click the [+] on the bottom-left below the Data Set Manager.

Either of these options will present you with a New Data Set dialog. Choose a name and select "Tag Query" as the type.

Configuration options for a Tag Query data cell.

A new Tag Query being created.

With the Data Cell Properties panel, you can do the following for Tag Query Data Sets:

Delete the column

Click the trash can icon in the header of the Data Cell Properties panel. Note that deleting the column removes it from the table but does not remove the Data Set definition. (You can delete a Data Set from the Data Set Manager).

Create a Data Set

For every column you want to add to your report, you'll be making a Data Set. Data Sets may not always appear in reports. You can maintain a collection to easily swap values in and out of reports or reference Data Sets using other Data Sets.

You're likely to accumulate a lot of them, so it is a best practice to give them a descriptive name.

No predefined Data Sets exist for tag queries. You must create one using the tags in your application.

  • Click the plus button [+] to create a new Tag Query Data Set or use the droplist to select an existing Tag Query Data Set.
  • To Rename, Copy or Delete a Data Set, access it's properties via the Data Set Manager.

Set a Tag Hierarchy Context [Optional]

Context can be used in two ways:

  • As a filter, limiting tag selection to those below a parent tag such as a station.
  • As a parameter, allowing the same report to be run for multiple contexts or stations.

Setting a context for a tag query column.

To use Context as a filter, select a parent tag. The Tag Selector will show only child tags of that parent.

To use Context as a parameter, you must first create a parameter. Refer to Define Parameterized Reports. Note that a value must be assigned to the parameter for use in the Report Studio before you can continue with further steps. Proceed to tag selection as usual. When operators run the report, they will be prompted to select a station or other parent tag to use for that instance of the report. Use Report Tags to predefine a choice for the parameter.

Open the Tag Selector

Click on the Tag Selector button to open the Tag Selector Dialog, where you can choose the tags to include in the report. If a Context was set, only child tags of that parent will be shown. The order of the tags in the Tag Selector dialog will affect the order of the columns in the report.

Note that it is often helpful to define a query rather than select specific tags.

Add Data Columns

Data columns are the calculations applied to tag values. Examples include Average, Minimum, Run Time and also "Raw Value".

Add as many data columns as needed for each tag in the Data Set by clicking the <<Click to Add>> tool at the bottom of the list. There must always be at least one data column for every Data Set. Values in a report can be averages, snapshots, minimums, etc. A list is provided within this topic.

Data column properties

Select each column to adjust header and precision.

If the data column displays a numeric value (e.g. Average, Minimum, ...) you can specify the header text for the column and the precision with which the value is displayed. The default is to use the precision specified with the tag's display configuration. Otherwise, you may specify a precision between 0 and 9.

If the data column displays a time value (e.g. Time of Minimum, Raw Timestamp, ...) you can open the Parameterized Phrases dialog to display time and date in the format of your choice. This is usually required for Raw Timestamps, which are measured to the millisecond.

If reporting on Raw Timestamp and Raw Data values for more than one tag, note that the column for each tag is generated independently. Timestamps are unlikely to match across any row.

To remove the default function, add a second data column using the function you want, then delete the first. Arrows to the side of the Data Columns list allow you to change the order of the functions.

Group Data Columns By Tag

Given a Data Set with multiple tags and multiple data columns, the default is to group the output by tag. You could choose instead to group by the data column function. For example, a set of columns showing all of the averages, then a set of columns showing all of the minimums, etc.

For complex groupings, you might use multiple tag-query columns. ( C, D, etc...)

Define Header Text

Sets the title for each column. Because columns are generated automatically according to your tag query, it is typical to use parameters to define titles dynamically.

Select from the drop-down list of predefined titles or click the provided button [image] to open the Make Parameterized Phrase dialog. Refer to Parameterized Phrases for examples.

Summary Suppression

Typically used when both of the following conditions are true:

  • You have created one or more summary rows
  • Your report includes two or more Data Sets.

If either of those conditions is not true, there is no need to suppress summary information.

An example of where you might use this is a pump report that includes a data column for flow characteristics, and a column for pump run time. The first Data Set might be summarized with a Range. The second might be summarized with a total. For each column you would suppress all summaries that do not apply.

Data Column Reference for Tag Queries

Except for the raw timestamp and raw data options, all calculations are performed for time span defined by the table's time per record value. Refer to Set the Time per Record.

  • Average - Average of all values within the set time per record (time span).
  • Minimum - Smallest of all values within the set time per record.
  • Maximum - Largest of all values within the set time per record.
  • Delta - Difference between the largest and smallest of all values within the set time per record.
  • Value at Start - Use for "snapshot" reports. The value at the beginning of each time per record interval.
  • Minimum Time - Time within the span when the smallest value was recorded.
  • Maximum Time - Time within the span when the largest value was recorded.
  • Starts - Number of zero to non-zero transitions.
  • Running Time - Length of time when the value was non-zero.
  • Totalize - Adds all the recorded values within each time per record.
  • Start and End Difference - The difference between the last value recorded and the first value recorded for a time per record.*
  • Bitwise AND - Should be used only with digital tags (those having a value of 1 or 0) Compares the current row to the previous and returns 1 if both are 1.
  • Bitwise OR - Should be used only with digital tags (those having a value of 1 or 0) Compares the current row to the previous and returns 1 if either are 1.
  • Raw Timestamp - Use with Raw Data. The time when the value was recorded. A display format that includes milliseconds is recommended.
  • Raw Data - Returns all values stored rather than a calculation over the time per record interval. Should not be used in combination with other calculations.
  • Runtime Data - A constant value, calculated at runtime. Use this to display any of the following from a selected tag: ShortName, Relative name, Description, Area, Units. The value will be shown in every row.

Accounting for Rollovers with Start and End Difference data

If Start And End Difference is selected, a Rollover setting appears. You can use this option to account for rollovers when calculating the start and end difference.

This is for hardware that can count to a limited number, then rolls over to start a fresh count. For example, a tag that counts equipment starts, but which can only count from 0 to 15 before wrapping around to start again. This gives a value of sixteen per roll-over since there must be one more start after fifteen to have the roll-over occur. A graph of a very simple case where there is a start every second would look like the following:

(Each rollover must be followed by a fresh start, not a gradually declining value. If there are a series of declining values then, because each is less than the previous, each counts as another rollover.)

The formula used is (RolloverCount * RolloverValue) + (LastValidValue - FirstValidValue).

Where, for any given time interval:

  • Rollovers are counted when a new value is smaller than the last valid value.
  • The RolloverValue is passed to the function in the parameter StaleTime.
  • LastValidValue starts with the last valid value in the previous time interval (if any), and is updated with each new valid value within the time interval.
  • FirstValidValue starts with the last valid value in the previous time interval (if any), and is updated with only the first valid value found in the current time span.

Given this example, suppose that you want a count of starts in each thirty-second interval. In the first interval there is no previous valid value, one wrap-around and a last valid value of 12. (1*16) + (12 - 0) = 28.

This is an idealized case. Consider a more realistic case where not all values are logged. (This may be due to factors such as polling intervals, deadbands, hardware, etc.) The following graph shows the same data where the orange dots represent values obtained and logged and the gray line represents what really happened:

In the first 30 seconds there is one roll-over when the value drops from 13 to 2. The first value is 0 and the last is 11. The Historian will return 27: (1*16) + (11-0) = 27.

The Historian will return 30 for the period from 30 to 60. The first valid value (carried from the previous period) is 11. The last valid value is 9 and there are two roll-overs. (2*16) + (9-11) = 30.

Select Start And End Difference to see the Rollover setting:

The rollover setting is disabled by default. When enabled but left blank, the field reads "Default's to Tag's Max Value" and it will automatically use the max scaling value configured in the property settings of the tag. Otherwise, you can set a specific value.


Data Sets

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Data Sets define the content of the tables and charts in your reports. You can save a Data Set in a report for quick recall without having to reconfigure. The default maximum number of Data Sets that can be saved to a report is 30. Create new Data Sets as you configure components or use the Data Set Manager to add new, rename, copy or delete Data Sets.

Data Set Types

Time - Configure Time ColumnsSee Also

Data Sets of type, "Time", can be chosen within the data cell properties for a column. When a table component is added, the default column is a "Timestamp" column by default. You might create additional Time Data Sets if you need to display time or data information in varying formats for different reports. Otherwise, you might simply adjust the Timestamps Data Set to suit and use it for all your reports.

Tag Query - Create Tag Queries

Data sets of type "Tag Query" define both the tags to include in a table or line chart and also which data columns to include such as maximum, minimum, or average. Data is always retrieved for time intervals defined by the overall table or line chart unless you select the option, "raw data values".

Recipe Batches - Create Reports for Recipe & Batch Management

Use this type of report to create your own version of a Recipe Batch Report

Alarm and Events - Create Alarm & Event Queries

Any alarm or event property can be shown in a report. Filters that you assign to the Data Set will define which alarms or events are included.

Row Labels - Pivot Tables

When Pivot Tables are used, the Timestamp column becomes a column of row labels, identifying the parent tag of multiple child tag columns.

Transaction - Create Transaction Logger Reports

Link this Data Set to a Transaction Logger tag to retrieve values from Transaction Logger tags and their child tags.

Notes - Adding Notes to Reports

Include notes from selected Notebook tags. Include parent notes only or whole thread. Filter by contents and operator by text or parameter. Limit the number of notes and choose whether or not to include comments with your filter settings.

Related information:

ReportMaxDataSets


Add Additional Columns [Optional]

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

If your query involves more than one tag or more than one calculation, additional columns will be created as required when the report runs, to a limit of 30 columns. You do not need to create a separate column for every tag and every calculation.

One example of why you might want a column C is if you are creating a report of flow rates and also need to track the matching pump run times. In column B you would create a tag query that includes the tag measuring the flow rate. In column C you would create a tag query that includes the matching pump status tag.

Another reason to create an additional column is that your data might require different summary operations. Perhaps one column should be summed and the next should be averaged. By creating separate tag queries in separate columns you can suppress summary operations for each to show only those that are appropriate.

Add Additional Columns

Begin by clicking the [+] box to the right of column B to create column C.

Adding a new report column

Adding a new Data Set column.

You will now have a new column, in which you can select or create another new Data Set. Proceed as described in Create Tag Queries.


Define Parameterized Reports

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Parameters are used to select which tags to use for your custom report each time you run it. For example, if your application has several stations and you would like to produce the same report individually for each station, then you can use a parameter.

When running a parameterized report from the Reports Page, you will be prompted for the necessary values when the report runs. If running the report with a Report Tag, you can preset the parameter values as part of the Report Tag's configuration.

There are three main tasks:

  1. Create one or more parameters.
  2. Use those parameters as part of your tag query.
    (Optionally, you can also use those parameters as part of any text that you choose to add to the report.)
  3. Provide values to the parameters, either when running the report or configured within a Report Tag.

Manage Parameters and Parameter Values

Use the tools in the Report Studio ribbon to add and modify parameters or assign values in a report:

Add and manage parameters in the same ribbon where reports are saved, deployed, deleted, and previewed.

The Manage Parameters button opens a dialog where you can create new parameters and modify existing ones.

The buttons along the bottom of this manager allow you to add, edit, rearrange and delete parameters.

Adding a parameter opens a New Parameter dialog:

New Parameter dialog

Adding a tag parameter.
The type is a user-defined tag in this example

The example shows a new parameter being configured. Recommended practice is to ensure that the parameter name is unique, avoiding any conflict with tags or other named objects. The description field should guide developers or operators when selecting the tag or value for the parameter. If the parameter is of type tag, then you should guide the user by selecting which types can be used. You may use the Ctrl key to select several types.

The same dialog is used when editing existing parameters.

Parameterized pages, plain widgets, and the Report Studio use parameters in the same way and share configuration dialogs.

(For pages and widgets only.) Text parameters can be marked as non-translatable. Select this for text that should never be translated, such as I/O addresses.

Values for Parameters

Use the Values tool in the Report Studio to set display values for use while building the report. This allows you to preview the effect of a parameter while continuing development work.

These values are saved as part of the report definition and will be used as defaults if other values are not provided when running the report.

Use Parameters in Tag Queries

After creating a parameter, you can use it in your tag queries and parameterized text. Tag queries assume that the parameter will contain a parent tag and do not work otherwise.

The following is easier to do if you use the Values tool to select a tag whose child tags should be displayed while you continue configuration.

Working in a Tag Query, set the Context to a parameter that contains a tag as shown in the following example:

Data cell properties allow you to name and define a set of data points to chart.

A Data Set with a context used as a parameter

Open the Tag Selector. The available tags are limited to child tags of the one associated with your parameter.

Select the tags for your report or create a query as shown in the preceding example.
(|*running | * | * | * |, which is any tag whose name ends with "running".) In a query, "Field" will be "value" for every tag except certain custom-code tags and communication drivers (see Communication Driver Log-Enabled Variables)

Use Your Parameters in Report Text

After adding text to your report, look in the Text Properties panel to find and click the button to open the Parameterized Phrases dialog.

Your parameter will be available for inclusion in the phrase. For tag parameters, Name, ShortName, Description and Value will be included. Using the tag value will display the value of the selected tag at the time the report is generated. This parameter type is "Auto" because the value may be a string or a number.

Example of making a parameterized phrase

Tag properties have been added to this Parameterized Phrase selector.

Supply Parameter Values when Running the Report

When running your parameterized report from the Reports Page, users will be prompted to provide values for the parameters.

Use the tag selector to assign a tag to the parameter

Sample prompt for a parameter when running the report

If configuring a Report Tag to run your report, you can set values for your parameters in the tag as shown in the following image. To run the report for multiple stations, create multiple Report tags.

Use the tag selector to assign a tag to a parameter in reports generated with the report tag.

Setting a parameter value in a Report tag


Parameterized Phrases

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Parameterized phrases are used for any customizable wording within a report, including:

  • The title of the report.
  • The header text of any column.
  • The display of time and date information.
  • Any text that you add to the body of the report.

Parameter keywords begin with a % and are enclosed in square brackets as shown in the following example. All other text is passed through, exactly as written. You need not include any parameters when adding titles, headers, or other text to your reports.

Make Parameterized Phrase dialog

Standard parameters available to tag query parameterized phrases

When building a parameterized phrase, leave a space between each element unless you want words to run together. If building your own time format, it is up to you to include colons between hours, minutes, and seconds.

Tag Query Parameter Variables

ShortName - The name of a tag, excluding all parents.

DataColumn - The function applied to the column.

Field - For any I/O tag (including legacy input / output tags) this is simply "Value".
Field is most useful when displaying driver statistics or values from custom tags that store data other than value.

Units - Engineering units configured for the tag displayed in any column.

RelativeName - The name of a tag including parents to the selected Context or the top of the tag tree.

Description - The configured description of each tag.

AncestorShortName - The shortname of an ancestor tag at a specified level (default: 1).

AncestorRelativeName - The name of an ancestor tag at a specified level (default: 1) including parents to the selected Context or the top of the tag tree.

AncestorDescription - The configured description of an ancestor tag specified by level (default: 1).

Time Parameter Variables

Time - Displayed as hh:mm tt, where tt represents AM/PM.

Date - Displayed as yyyy-MM-dd.

Hours12 - The current hour using a 12-hour clock.

Hours24 - The current hours using a 24-hour clock.

Minutes - Minutes within an hour.

Seconds - Seconds within a minute.

SubSeconds - Three decimal points of accuracy.

AMPM - AM or PM.

DayNum - The numeric day within a month.

MonthNum - The numeric month within a year.

Year - The four-digit representation of the year.

DayString - The name of the day of the week.

MonthString - The name of the month of the year.

Label & Report Title Variables

StartDate - Beginning date of the time span formatted as yyyy-MM-dd

StartTime - Beginning time of the time span formatted as hh:mm tt

EndDate - Date ending the included time span.

EndTime - Time ending the included time span.

RunDate - Date when the report was generated.

RunTime - Time when the report was generated.

WorkstationName - The identity of the workstation where the report was generated.

Time Duration Variables

Time Duration variables are relative to:

  • Report Tag Query dataset --> Running Time data column
  • Report Recipe Batches dataset --> Batch Duration and Step Duration data columns

(For the examples included with each variable, assume the total run time is 326589.1234 seconds)

TotalSecondsFullPercision - Total running time, in seconds, to 4 decimal points.

Milliseconds -The number of milliseconds in the run time value. (ex. 123)

TotalMilliseconds - Total running time in whole milliseconds. (ex. 326589123)

Seconds - The number of seconds in the run time value. (ex. 9)

TotalSeconds - Total running time in whole seconds. (ex. 326589)

Minutes - The number of minutes in the run time value (ex. 43)

TotalMinutes - Total running time converted to whole minutes. (ex. 5443)

Hours - The number of hours in the run time value. (ex. 18)

TotalHours - Total running time converted to whole hours. (ex. 90)

TotalDays - Total running time converted to whole days. (ex. 3)

TimeZone - The time zone of the workstation. Appears after the WorkstationName.

Custom Parameters

As described in Define Parameterized Reports, parameters that you create for your report can also be used in your parameterized phrases. This is useful for report titles, column headers and text components. Custom tag type parameters can be defined to display tag information in text components.


Create Reports for Recipes

Create Reports for Recipe & Batch Management

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

If your query involves more than one tag or more than one calculation, additional columns will be created as required when the report runs, to a limit of 30 columns. You do not need to create a separate column for every tag and every calculation.

Retrieve information from Recipe Book Tags and their child tags. To generate a report using the recipe batches Data Set, you will convert the default timestamp column. It is more practical to use the Batch Start Time data column to replace Timestamps. Click on the cells of Column A to highlight it. In the properties panel to the right, find the Data Set droplist and click the [+] to add a new Data Set. A dialog will appear asking you to choose a Name and Type. Choose a name and select Recipe Batches from the Type droplist. The properties panel will change to reflect the new Data Set configuration:

Data Cell Properties Panel - Recipe and Batch Data Set

In the Data Cell Properties panel for Recipe Batches data set, you can find the following options:

Delete the column

The trash can icon in the header of the Data Cell Properties panel deletes the column. Note that deleting the column removes it from the table but does not remove the Data Set definition. (You can delete Data Sets from the Data Set Manager).

Data Set

For every column you want to add to your report, you'll be making a Data Set. Data Sets may not always appear in reports. You can maintain a collection to easily swap values in and out of reports or reference Data Sets using other Data Sets.

You're likely to accumulate a lot of them, so it is a best practice to give them a descriptive name.

This field gives you the option to perform the following actions:

  • Select an existing Data Set, perhaps one that you have created previously.
  • Click the plus button [+] to create a new Data Set with a name of your choosing.

Select a Recipe Book tag

You have the option of selecting a tag from the tag browser or selecting a report parameter. Try clicking the tag selector on the right-hand side and selecting a recipe book tag from the tag browser.

Data Columns

Data columns are the recipe batch properties that will be included in the report. There are a few listed by default, you can add as many data columns as needed by clicking the <<Click to Add>> tool at the bottom of the list. There must always be at least one data column for every Data Set.

  • Batch Number - The user provided batch number.
  • Batch Start Time- The recorded start time of the batch.
  • Batch End Time- The recorded end time of the batch.
  • Parameters (All)- If Parameters (All) is selected, a column will appear in the final report for every Recipe Parameter tag.
  • Recipe Name- The name of the recipe associated with each batch.
  • Recipe Version- The recipe version number associated with each batch.
  • Step- Multi-step batches will be broken out into multiple lines. Step denotes to which step each line refers.
  • Note- User-provided notes associated with each batch.
  • Batch Duration- The period of time the batch took, the time units can be specified.
  • Step Start Time- The recorded start time of the step
  • Step End Time- The recorded end time of the step
  • Step Duration- The period of time a step took, the time units can be specified.
  • User- The user account that was logged in when the report ran.
  • Parameter (Custom)- Split one recipe parameter out from "Parameters (All)" (that becomes "Parameters (Remaining)") Parameter (Custom) will display the selected parameter in the column name. Add multiple instances to split out multiple parameters.

Data columns can be reordered by clicking the arrows under the Data Columns box. They can be removed by clicking on the one you want to remove and then clicking the [x] under the box.

To include step-related information in the report, include at least one of the following: Step, Step End Time, Step Start Time, Step Duration, Parameters (All/Remaining), Parameter (Custom).

Maximum Records

Optionally, set a maximum record limit for notes that appear within a report. If you reach the maximum number of rows mid-recipe, it will just cut off. Include the Batch End Time data column to denote that a batch has completed as a quick and easy indicator that the whole recipe event was captured.

Generating your Report

  1. Name your Data Set.
  2. Select the Recipe Batches type.
  3. Select a Recipe Book tag.
  4. Select your data columns and change formatting as desired.
  5. Re-order your columns as it suits you (Try moving start and end times to the top of your list)
  6. Don't forget to save your changes.
  7. Preview your report to see if you need to make adjustments.


Add Summary Rows

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Use summary rows to display totals, averages, and other statistics for the values in each column other than the first, which will contain the label for each summary.

Create a Summary Row

Click in the [+] bar below the main part of the table. You can add as many summary rows as needed, up to the number of possible operations.

Adding a summary row by clicking the plus bar

Adding a summary row

The row is added and can be configured using the Operation selector and Title, shown in the right-hand panel.

Example of a summary row operation being added

Selecting the operation for a summary row

By default, labels match operations but you are free to replace these with any phrase you prefer. The label will always be displayed in the first column.

When the report runs, the selected operation will be applied using all the values in the column above it.

The operation will apply to all columns for all tag queries. If your table includes multiple Data Sets it is likely that operations may be relevant to some columns but not others. In this case, update each column's configuration to suppress summary operations that are not useful to the query. Refer to notes for Data Cell Properties -> Summary Suppression in Create Tag Queries.

Available Summary Operations

Multiple operations can be selected. Each will be shown on its own row below the table of reported values.

  • Total
  • Average
  • Minimum
  • Maximum
  • Standard Deviation
  • Median
  • Range
  • Count

Most operations should be clear based on the name but note that "Count" will return the total number of valid entries in a column, not the total number of non-zero entries. To create a count of non-zero or other specific entries, copy the report output to Excel, where you can do operations such as COUNTIF. Within a VTScada report, Count is most useful for data that has not been aggregated. For example you might create a count of alarm event messages over a given time period.


Tables: Appearance and Data Aggregation

Tables: Appearance and Data Aggregation Concept Link Icon See Also

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Tables hold the information that you want to include in your report. The columns in those tables are populated by queries that you create. You can adjust table properties to control how the result is presented.

Add tables to your report by dragging them from the palette in the Report Studio. The Table Properties panel will open whenever the table as a whole is selected, usually by clicking in the upper left corner of a table as shown:

Selecting the upper corner of a table to access table properties.

With the Table Properties panel, you can do the following:

Delete the table

Click the trash can icon in the header of the Table Properties panel:

Selecting the upper corner of a table to access table properties.

Set the Time per Record.

Measured in seconds, this is used for consistent data aggregation from row to row for all queries in the table. Neither 0, nor "Raw data" are an option here. If raw data is needed, select that option when defining your tag queries.

The following table of typical values may be helpful:

Time per Record (sec) | Equals
900 | 15 minutes
3600 | 1 hour
86400 | 1 day
604800 | 1 week

Configure a Pivot Table or Transpose Table

Pivot Tables - Displays parent names as row labels and child tag names as column labels.

Transpose Tables - Swaps the rows and columns

Set the format of header, body, and summary cells.

Each part of the table can be configured independently. The following image shows the formatting options for the body cells. The header and the summary portions of the table look similar, except that the header is always a single row.

Format options for table cells.

Let's look at the options for the Body Cells:

  • In the grid box, click on a line to add or remove the equivalent lines from display in the table. Lines are single-width and black.
  • The three justification buttons will justify the contents of the cells to the left, center or right of the cell.
  • With the tag selector, change the font with a Font Style tag.
  • There are two color selectors to choose the color of the font and the color of the cell (background).

Click the [+] to add zebra striping to your table. Font tag selection, and color selector buttons for font and fill will appear for each stripe added. A set of arrows and an x button will appear on the right to rearrange stripe order or remove striping.

Stripes will be applied to columns if the table is transposed.


Configure Time Columns

Configure Time Columns Concept Link Icon See Also

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

All tables start with a single column. Click the [+] bar to the right to add more.
Note that a tag query that includes multiple tags or calculations will generate as many columns as needed to display the result of the query.

Time values (where the Data Set type is "Time") are typically displayed in column A of a table. This recommended because summary labels (if summaries are used) are always placed in the first column and therefore work best below time values, which are never summarized. You are free to choose any column for time and might choose to have several time columns if the format differs or if you want to repeat the timestamp in a report with many columns.

The Time data cell type is recommended for reports with aggregated data. A separate Time column may not be needed if creating an Alarm & Events report.

Whether configuring time or a query, start by clicking in the title row as shown following to open the Data Cell Properties panel.

Shown here is a Table component with a Time column A and a Tag Query type column B

Select column A to define a time-based Data Set

To create a Time Data Set you have two options:

  1. With the correct column highlighted, click the [+] that appears in the new Data Cell Properties pane.
  2. Click the [+] on the bottom-left below the Data Set Manager.

Either of these options will present you with a New Data Set dialog. Choose a name and select "Time" as the type.

Actions for a Time Data Set type:

Delete the column

Click the trash can icon in the header of the Data Cell Properties panel. This deletes the column from the table but does not delete the Data Set definition. (You can delete the Data Set from the Data Set Manager).

A "timestamps" dataset for a report column.

Select or create a Data Set

For every column you want to add to your report, you'll be making a Data Set. Data Sets may not always appear in reports. You can maintain a collection to easily swap values in and out of reports or reference Data Sets using other Data Sets.

You're likely to accumulate a lot of them, so it is a best practice to give them a descriptive name.

Click the [+] to create a new Data Set or use the droplist to change the Data Set associated with whichever column you've selected.

Define a Header

Text displayed at the top of the column. Defaults to "Date". Replace with any other wording that is appropriate.

Select a Date Format and Time Format

The format for time and date can be edited by making a parameterized phrase.

Click on button to the right of the field to open the Parameterized Phrases dialog. Multiple formats are available for selection, or you can enter a format of your own using the available Date Formatting Strings and Time Formatting Strings.


Report Studio Tools

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Tools in the report studio are listed here. Descriptions and instructions can be found in the following topics.

The report studio before configuration.

Sample Report Studio (Click to expand)

Tools

Undo / Redo

The result of a Report Studio editing session is stored in the VTScada Version Control system. Steps within an editing session are not. Use these buttons to back up while editing a report.

Clipboard - Copy / Paste

Reuse elements within a report. Pasted copies are always added to the end of the report and can be moved as required from there.

Save / Clone

As labeled.

Parameters - Manage / Values

Use "Manage" to create and edit parameters that allow you to (for example) use the same report for any selected station. Use "Values" to select (again, for example) the station to use while building and previewing the report.

Preview

Run a sample report to check your work so far.

Settings - Title / Settings

Use the Title button to change the title of the report or click the Settings button to open a settings dialog.

Adjust Time Per Record for Daylight Savings Time Changes

Adjust Time Per Record for Daylight Saving Time Changes - Enabled by default. Any records occurring during Daylight Savings Time are adjusted to compensate for the lost or added hour.

Should you disable this setting?
Enabled: timestamps are adjusted. Consistent timestamps are more important than the duration of each record.
Disabled: Timestamps are not adjusted. Consistent duration for each record is more important.
For example, Batch Process applications may wish to disable this setting if duration is more important than timestamp.

Delete

Remove the report.

Components Palette

Drag components from the palette to the canvas. When a component is selected in the canvas area it's properties are available for editing in the right-most panel. Tables are always centered within the report body. Decorative components can be left-, right-, or center-justified relative to tables.

Image

Add a logo or other image to your report. See: Report Visual Design

Line Chart

Add a line chart to your report, showing all the pens in a tag query.

Spacer

No space is left between report elements other than what you define using spacers. See: Report Visual Design

Table

Tables define the body of most reports. See: Tables: Appearance and Data AggregationSee Also

Text

Add a title, explanation, or other notes to the report. See: Report Visual Design

Add tag values (at the time the report is generated) to a text component. See: Use Your Parameters in Report Text

Data Set Manager

See and manage Data Sets that have been created in a report. If you drag a Table component onto the canvas, two Data Sets are generated and will appear in the manager. (Row Labels and Timestamps). Any Data Set you add through the properties panels of other components will all appear in the Data Set Manager.

Select a Data Set from the Data Set manager to see Data Set properties. From the Data Set Properties panel, you can rename a Data Set.

Add a new Data Set

Add a new Data Set from the Data Set Manager by clicking the [+] in the bottom-left corner. A pop-up dialog will appear asking for a Name and a Type from a droplist of options.

The name cannot be left blank. You cannot have duplicates-- you may not use the same name as another Data Set in the same report.

Copy

Copy an existing Data Set with a new name. This tool is handy for quickly generating Data Sets with slight modifications. A dialog will appear so you can modify the name of the Data Set. The Type droplist will be disabled.

Delete

Click on a Data Set in the Data Set Manager and then click the nearby trash can. A dialog will pop up with a warning, "This Data Set may be in use by components or other Data Sets. Are you sure you want to delete the selected Data Set?" Select Delete to remove the Data Set from the report, or cancel to close the dialog without changes to the report.


Report Visual Design

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Determine the layout and cosmetics of your report with spacers, images, text and containers.

Add Spacers

Represented in the Report Studio as a bar with a vertical arrow, these are replaced by empty space of the specified height in pixels when the report runs. The space in the generated report will match what you see on the screen. (Some variation is possible depending on whether the selected destination is HTML, PDF, or other.) Note that adjacent elements will touch if you do not place a spacer between them.

Example of a report spacer

A spacer between text and a table

Add Images

The VTScada logo is provided as a sample image. Drag it to the report, then use the Image Properties panel to select and adjust any image you prefer. Click the [...] button to the right of the image name to open the Select Image dialog.

Images must be part of your application before they can be included in the report. To import a new image into your application, click the + button at the bottom left of the Select Image dialog. The process is the much the same as for adding images in the Idea Studio except that images cannot be dragged from the Windows File Explorer to the Report Studio. Refer to Import Images.

Image properties panel for a report

The Report Studio Image Properties panel

Add Text

Use text to give your report a title or to add relevant notes between other elements.

Drag the Sample Text to your report and edit to suit using the Text Properties panel. You cannot include line breaks in your text, but long text will flow over multiple lines as required when the report is built for PDF or HTML.

Text properties for a report

The Report Studio Text Properties panel

Note the tool for creating a parameterized phrase (circled in the preceding image). Instructions for this tool are provided in Parameterized Phrases.

When building a parameterized phrase, you can include any text in addition to selected parameter variables. Be sure to leave spaces to ensure that words do not run together unless that is your intent. For example:

Sample Report Generated on %[RunDate] at %[RunTime]

Containers

Organize the layout of report pages in The Report Studio with resizable containers that order their contents vertically or horizontally. These are components that can contain all other components, including other containers, making them a versatile tool in optimizing use of space.

Imagines, line charts and spacers are pictured inside two vertical containers that are both places inside one horizontal container.

Report components organized by two vertical containers (yellow) inside one horizontal container (blue).

Using Containers

Containers are accessible within the "Components" sidebar of Report Studio, denoted as "Container (V)" for a vertical-ordering container and "Container H" for horizontal. Drag and drop either onto the canvas to get started.

Component icons representing vertical and horizontal containers are pictured in the Components panel.

You may notice that a container first appears on the canvas as a tiny box. Note its blue color when you first drop it and its white color when you click outside of it. This visual aid indicates where the focus is. Be mindful of which container is in focus when deleting components. Deleting a container will also delete all components it holds.

When clicking and dragging any component in or around a container, blue ribbons will appear around it or any pre-existing components to indicate where the new one will be accepted.

You may drag and drop other components into a container and it will automatically resize to fit them. Containers can hold as many components as you would like but will only order them vertically or horizontally (Think of them as mini canvases).

Spacers work with Containers. They can be placed between these components to customize buffer space. The Spacer symbol will reorient itself once it is in place, although their icon may not change as you drag and drop them.

Components can be removed from containers and placed elsewhere on the canvas, containers moved this way can do so without compromising the integrity of their contents.

Container Properties

The horizontal container showcased above displays properties like this.

When a container is in focus, a corresponding properties menu will appear in the upper-right sidebar menu of Report Studio. Container properties may possess the following controls for placement of each component within the container's context:

Float Component Upwards

Float Middle

Float Component towards the Middle

Float Bottom

Float Component towards the Bottom

Fill Space

Fill Space Vertically, allowing the component to reach its maximum height (applies to Vertical Container Only).

Stretch to Fit

Stretch to Fit. Without exceeding the maximum height or width of the component, this will center it within the available space of a container along its primary axis. Multiple 'Stretch to Fit' components in the same container will share the space evenly, even across different screen sizes.

Clicking a component's name in the container properties window will focus on the component instead and open up the component's properties. For more information on controls, see Report Studio Tools.

These properties will default to 'Float Upwards' for the component if it is moved elsewhere within the canvas.

Alignment within the context of containers is only available along the vertical axis. To change horizontal alignment, view the individual component properties.

Rendering Containers in Different Formats

Container lines are not visible in the rendered report from Report Studio (see Printing Reports for more information). Container use is translated in various ways across the available file types, as follows:

HTML

Container-organized layouts translate readily into HTML through the use of formatted <div> tags.

CSV

As a minimalist file type, CSV formatting will ignore line charts and complex images. It will translate container layouts into one vertical layout ordered left-to-right and by component depth within the containers (see tables numbered in orange below).

The table order in the report above translates to a vertical layout below in CSV formatting

Container tables CSV translation example

Excel (.xlsx)

Container-organized layouts can be replicated consistently in Excel, with some tables undergoing resizing to accommodate all text sizes. Table cells are all translated into a uniform size, as determined by the largest text a cell is required to fit, so text in a smaller font may appear to be given more space than necessary.

Line chart data is accessible as a table on a separate sheet within the Excel file.


The Report Studio

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Topics in this chapter:

Report Studio Tools

Parameterized Phrases

Data Sets

...Configure Time ColumnsSee Also

...Create Tag Queries

...Create Reports for Recipe & Batch Management

...Create Alarm & Event Queries

Create Transaction Logger Reports

Calculations & Operations Columns

Adding Notes to Reports

Tables: Appearance and Data AggregationSee Also

...Add Additional Columns [Optional]

...Add Summary Rows

Pivot Tables

Transpose Tables

Add a Line Chart to Reports

Report Visual Design

Define Parameterized Reports

Report Studio Outputs and Formats

Use the VTScada Report Studio to create your customized reports. Open this tool from the Reports Page, which is typically part of the Alarms, Reports & Diagnostics folder.

Opening the Report Studio to create a new report.

Creating a new report from within the Reports page.

Reports are tables of information where you select which tags to include, what calculations to perform, and what summary information to calculate. Any report can contain multiple tables, allowing you to create comprehensive overviews of your system.

In addition to the tables, you can add images, line charts, spacers, and text to provide clarity and context.

A configured report in the Report Studio.

Report elements in the studio

The resulting report.

The resulting report

Preview

A preview button in the Report Studio gives you a way to check your work. After you click Preview, a pop-up prompt will ask you for a time span. Note that what matters is the time and date shown rather than the current preset, the list of which serve only to give you a quick way to set time and date.

The destination for a preview is always the screen.

Tips:

Column A is typically used for Time but can be used for data retrieval. If you add a summary row to your report, column A must display a Time column so that room is left for the summary labels.

Column B will expand into as many columns as needed to show the results of your query.

Column C, etc., can be used to add additional tag queries to a table. It does not display summary data for a row.

All data columns other than Raw Timestamp and Raw Data are retrieved with a common time interval per row (Time per Record), which is set for the table or line chart as a whole. Click in the upper right corner of a table or a line chart to set this value. You can set the time per record as large or small as needed, but cannot set it to 0 (zero).

If creating a table with Raw Timestamp and Raw Data values for more than one tag, note that the column for each tag is generated independently. Timestamps are unlikely to match across any row.

If the available list of data columns does not include the calculation you're looking for, recall that you can create tags from the Analytics group including I/O and Calculation tags to generate additional statistics. (Referring here to the selection of tags for a query, not the summary information compiled at the bottom of a column.)

Add rows showing summary statistics by clicking the plus at the bottom of the table and then configuring the summary row. You can have multiple summary rows as needed, up to the number of possible summary actions.

If your table has multiple tag query columns, not all summary statistics will apply to all queries. Suppress statistics that do not apply on a column-by-column basis (referring to configuration columns B, C, etc., not output columns).

Under the current configuration, there is a limit of 30 columns and 10,000 rows per table.

All elements in a report can be duplicated by doing a copy and paste (Ctrl-C / Ctrl-V). Copied elements are always added to the bottom of the report.

For both tables and line charts, the components are configured by clicking on a region and then using the panel on the right edge of the Report Studio to customize the selected region. Note the blue highlight, indicating which aspect of the table or line chart you have selected to customize.

The definition of each report that you create is stored as a JSON file in the folder named "ReportDefinitions" within your application. You are advised not to edit those files directly.

The VTScada installer offers WebView2 as an option during installation. Ensure that WebView2 is installed on your VTScada workstation in order to use the Report Studio, and to generate PDFs of reports built using the Report Studio. For the VTScada Internet Clients (VIC), WebView2 should be installed on the machine running on the VIC in order to display report previews in the Report Studio. For workstations without internet access, WebView2 can be downloaded directly from Microsoft. Refer to notes on this topic within the description of the Web Browser Widget

As noted elsewhere, VTScada should not be run under an account that has Windows Administrator privileges. This remains true when running as a service. One of the problems you will encounter if attempting to do so is that WebView2, required in order to generate a PDF report, will not run when VTScada is running as a service and either of the following is true:
- VTScada is running as the "Local System" account.
- VTScada is running under an account that is part of the Administrators group.

Saving, Deploying and Cloning

The following section assumes AutomaticDeploy is enabled (as it is by default.)

New reports can be Saved by clicking the Save button visible in the home ribbon up top. Saving a report commits it to an application. It will become accessible to all privileged users on all machines. The Save button will change into a Deploy button. Changes to a report can be deployed by clicking the Deploy button or else they will periodically auto-deploy every three hours.

Cloning a report creates a duplicate report that is not automatically saved. When you click Clone, you will be advised that a new report will be created, it will not be automatically saved, and unsaved changes to the current report will be saved before cloning. Cloning a report is a great way to generate a one-off, ad-hoc report to be immediately discarded after use.

You might decide to create a series of very similar reports. A quick way to do this is to re-open the first and then use the Clone button. Edit the new report as needed and then save it as a new report.
You can also create parameterized reports so that the same report can be run several times with differing stations or other tags.


Add a Line Chart to Reports

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Add a line chart to your report to display trends over time. Line charts are supported in all output types except CSV. Tag Query Data Sets can be plotted in relation to time (The X-axis can only be time based.)

The chart will display information from a Tag Query Data Set configured either in the chart itself or from a table component.

The chart will only show within the reporting period up until the last data point retrieved. This prevents confusion if there is a discrepancy between the time of the last data point and the end of the reporting period.

The default chart icon displays an unnamed line chart, unnamed axis, sample key and a sample plot line.

An example of how the line chart appears in the Report Studio.
Preview your report to see how the chart appears with your current configurations and real data.

Add a Line Chart to your Report Studio Canvas

In the Report Studio, drag a line chart onto the canvas. You can delete the chart by clicking on the chart to open a configuration panel on the right and then clicking the trash can icon to the right of the Line Chart Properties panel title.

If the Line Chart element is not selected then hovering your cursor over the chart highlights four major configurable elements. The chart as a whole (try hovering over "Title" at the top), the Y-axis along the left-hand side, the X-axis along the bottom and the plot area in the center. Click on each area to open a new panel of options to the right.

Properties for the Chart as a Whole

Set the span of time between each record entry, the size of the chart as it appears in your report, the title, and the caption formats.

Time per Record

Set the record frequency by time (in seconds) between each data point. This is used for consistent data aggregation from row to row for all queries in the table. Neither 0, nor "Raw data" are an option here. If raw data is needed, select that option when defining your Tag Queries.

The following table of typical values may be helpful:

Time per Record (sec) | Equals
900 | 15 minutes
3600 | 1 hour
86400 | 1 day
604800 | 1 week

Width x Height or Scale to Fit

Set the width and height of the chart in pixels. The chart default is 600 x 400. When Scale to Fit is enabled the height and widget will be set such that the aspect ratio is maintained while consuming as much width as possible. In a XLSX Closed Birth certificate for Sparkplug Edge Nodes output type, the chart will grow to the size of the widest static component. This takes advantage of the scalable property of the SVG Closed Death certificate for Sparkplug Edge Nodes image being rendered such that, at any size, the image will always appear correct and accurate.

Left-Center-Right Justified

Specify where the chart will appear laterally in your report.

Background Color and Border Color

This "Background color" specifies the color of the margins of the report. The "Border Color" specifies the color of the very edge around the outside of the report. The defaults are white for the background and black for the border. To change the background color of the plot area, see the Appearance panel.

Title, Title Font & Title Color

Specify the title that will appear at the top of the line chart (Leave blank to have no title). Select a Font Style tag and open the color selector to change the font and color. The default is "Title" in MediumFont, black.

Legend Font, Legend Color & Hide Legend

The legend, at the bottom of the chart, displays each plot line with a label. Select a Font Style tag and open the color selector to change the font and color of the text. The plot line color and style will match the plot line as it is illustrated in the chart. The default font is ReportFont in black. Enabling Hide Legend will remove the legend from the chart completely.

Y-Axis

This panel contains options for the Y-axis of the line chart. Title text, font and color. Auto scaling, scale min and max. Precision, Number of ticks, Tick label font and color.

Title, Title Font & Color

Set the title of the Y-axis (Leave blank to have no title). Select a Font Style tag and open the color selector to change the font and color of the Y-Axis title. The default is "Title" in ReportFont, black.

Auto Scaling or Setting a Minimum & Maximum

Minimum and Maximum refer to the scale of the Y-axis. Select a range manually or enable auto scaling to override the manual setting. Auto scaling will automatically determine the range based on the range of the selected Data Set. The default range is 0 to 100.

Precision

Select how many decimal places appear after the decimal point. Default 0.

Number of Ticks, Tick Label Font & Color

Select how many graduations by which to divide the plot area along the Y-axis. The minimum number is 2 (for the minimum and maximum range values). Select a Font Style tag and open the color selector to change the font and color of the number values that appear next to each tick.

X-Axis

Configure settings for the X-Axis incluing the Title, Title font and color, The format of the X-Axis scale labels, Number of ticks, tick label font and color.

Title, Title Font & Color

Set the title of the X-axis (Leave blank to have no title). Select a Font Style tag and open the color selector to change the font and color of the X-Axis title. The default is "Title" in ReportFont, black.

Format

Select a parameterized phrase to generate the time scale labels.

Number of Ticks, Tick Label Font & Color

Select how many graduations by which to divide the plot area along the X-axis. The minimum number is 2 (for the minimum and maximum range values). Select a Font Style tag and open the color selector to choose the font and color of the date/time values that appear next to each tick. If your values overlap, consider choosing a shorter format or increasing the width.

Selecting a Data Set

Configure tag queries into selectable data sets to plot on your line chart.

Select << Click to Add >> to see a list of Tag Query Data Sets you have already made and the option to create a new one. Multiple Data Sets can be plotted on the same chart. Use the arrows on the right to move items on the Data Set list up or down. Select an item on the Data Set list and click on the [ x ] button to remove it. You can also copy Data Sets from this panel.

Once a Data Set is created or selected, you can modify it exactly as you would when configuring Data Sets in a typical Report Studio table.

Appearance Panel

Configure the appearance of elements in the plot area.

Background Color and Border Color

This "Background color" specifies the color of the plot area of the report. The "Border Color" specifies the color of the very edge around the outside of the plot area of the report. The defaults are white for the background and gray (<FF7D7D7D>) for the border.

Horizontal & Vertical Grid Color

Grid color refers to the color of the horizontal and vertical graduations that appear if more than 2 ticks are configured for the X-axis or Y-axis. The default color is a light gray (<FFD1D1D1>)

Pens

If this section is left blank, VTScada will select colors for each pen in the chart. Select << Click to Add >> to expand your options, noting that pen properties are applied in the same order as tags appear in the Data Set.

Add pens to configure the color, line style and width, or add a marker at each plot point.

As new pens are added, the Report Builder will automatically select a color that is distinct from the other pens. Use the tool shown in the preceding image to change the color, style, and width as desired for each successive pen added to the chart. Line style and width will be inherited from the last pen added.

Your tags might have display properties configured for use in the Historical Data Viewer. Note that those properties are not used by the Report Builder.

Enabling Show Markers will add a dot on the plot line at each data point. Markers are especially helpful in cases where only a single data point is retrieved. Without a marker, a single data point will not visibly render.


Calculations & Operations Columns

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

The Report Studio Calculations data set will perform operations using other data sets in your report, constants or parameters. There are three categories: consolidation, summarization and basic operations. The properties panel will change as you go, adding and removing fields depending on the options you have selected.

To configure your Calculations data set, you may first need to configure other data sets, such as a tag query data set, to bring in values to reference and you may need to add or manage report parameters. As data sets and parameters are added to your report, they become options in your Calculations data cell properties.

About Operations

What are the options and what do they do?

Consolidation →

Consolidation is a means to combine multiple columns into a single column. This works on a per row basis.

Think of a Tag Query data set that returns 4 tags. It displays four columns of data. Each Consolidation-type calculation adds an additional column with a value consolidated from those 4 values.

There are several consolidation types:

  • Total - The sum of all the values in the row
  • Minimum - The lowest of all the values in the row
  • Maximum - The highest of all the values in the row
  • Average - All the values in the row added together and divided by the number of values.
  • Median - The middle value of all the values sorted by size.
  • Range - The highest value minus the smallest value in the row.
  • Standard Deviation - How much the values of the set deviate from the average.
  • Count - Counts how many columns with valid entries are in the set.

This example includes one of each of the available consolidation types. A row of equipment values from a Tag Query are highlighted in yellow. Because I added 8 calculations, there are eight additional columns displaying values calculated from the four pump values of the same row.

Summarization ↓

Summarization is a means to combine a column of data into a single value to display in additional columns. This operation works on a per column basis.

Think of a Tag Query data set that returns 4 tags. It displays four columns of data. Summarization takes all the values from a whole column and applies a calculation. The result is displayed in four columns (one output column per input column) with the value repeated for each cell .

This example includes one summarization calculation. There are four additional columns. One column for each Tag Query value. The result of the calculation repeats in every row of the column.

Generally, a summarization calculation data set is used as input to another calculation.
You can display it in a report (as in this example) but you may find a summary row more suitable for report display purposes.]

There are several summarization types:

  • Total - The sum of all the values in the column
  • Minimum - The lowest of all the values in the column
  • Maximum - The highest of all the values in the column
  • Average - All the values in the column added together and divided by the number of values.
  • Median - The middle value of all the values sorted by size.
  • Range - The highest value minus the smallest value in the column.
  • Standard Deviation - How much the values of the set deviate from the average.
  • Count - Counts how many rows (with valid entries) are in the column.

Basic Operations

Math functions you may want to apply to data in your report. For example, use a calculation data set to add a column to show a percentage or a unit conversion.

In this report, calculation data sets are used to convert imperial values to metric.

Possible operations include:

  • Add - Add a value with another value ( + )
  • Subtract - Subtract a value with another value ( - )
  • Multiply - Multiple a value with another value ( * )
  • Divide - Divide a value by another value ( / )
  • Modulus - Divide one value with another and return the remainder. ( % )
  • Exponent - Raise the first value to the power of the second. ( Pow )

Setup for Calculation configuration

Calculation drop lists are populated with data sets and parameters that are already configured in your report. It is recommended that you start with the other columns to be displayed in your report, data sets that query values to be used in your calculations, and add parameters if you want to include parameterized calculations in your report.

Creating a Calculation data set

To create a Calculation Data Set you have two options:

  1. Add a column to the table component. Click the [+] that appears in the new Data Cell Properties pane.
  2. Click the [+] on the bottom-left below the Data Set Manager.

Either of these options will present you with a New Data Set dialog. Choose a name and select "Calculation" as the type.

This is how the cell properties appear by default. As fields are configured, relevant settings will become available.

Calculation Data Cell Properties

Delete the column

Click the trash can icon in the header of the Data Cell Properties panel. Note that deleting the column removes it from the table but does not remove the Data Set definition.

Create or Select a Data Set

For every column you want to add to your report, you'll be making a Data Set. Data Sets may not always appear in reports. You can maintain a collection to easily swap values in and out of reports or reference Data Sets using other Data Sets.

You're likely to accumulate a lot of them, so it is a best practice to give them a descriptive name.

  • Click the [+] button to create a new Data Set or use the droplist to select an existing Calculation Data Set
  • To Rename, Copy or Delete a Data Set, access it's properties via the Data Set Manager.

Step A - When choosing Consolidate or Summarize

Operation - A drop list for specifying consolidate, summarize, or a basic math operation. If you choose "consolidate" or "summarize" the next two fields will be "Data" and either "Consolidation" or "Summary". As a quick reminder, consolidate works on a per row basis, and summarize works on a per column basis.

Data - A drop list of options populated by the Data Columns configured in other Data Sets within the report. As you add additional steps, the results of previous steps also become available as options.

Consolidation/Summary - Select the type. Total, Minimum, Maximum, Average, Median, Range, Standard Deviation, Count.

Step A - When choosing a basic math operation

Operation - Basic math operations include add, subtract, multiply, divide, modulus and exponent.

Selecting a math operation changes the latter two fields:

This configuration gives us Step A = Data 1 + Data 2.

Data 1/Data 2 - Change the input type by clicking the arrow next to the disc icon. Choose from Data Set, Constant or Parameter.

Click the plus button [ + ] under the step to add another step. Use the arrow buttons to change the order of the Steps. As you add additional steps, former step results become available as Data options. In Step C, for example, in the Data Set type droplist, you would see the available Data Sets and also Step A, Step B as options. The result of Step C will not be available to Step A.

Configure Column Settings

A column is added to "Data Columns" for each step you configure and displays in your report left-to-right in the same order they appear in the Data Columns list top-to-bottom. Use the arrows to change the order or use [ x ] to remove Steps that you do not wish to display in your report. Steps that are listed in Data Columns will become available in the Data drop lists of other Calculations data sets.

You cannot move a step above a step that references it. If you have steps A, B, C, D and use the result of B as an input in C, you will not be able to move C above B.

Summary Suppression

Summary Suppression is used when you have added a summary row to the table but the value doesn't make sense for this data set. For example, summing daily high temperature is not a helpful metric.

Another example of where you might use summary suppression is a pump report that includes a data column for flow characteristics, and a column for pump run time. The first Data Set might be summarized with a Range. The second might be summarized with a total. In this case, you would add two summary rows to your report and suppress them in the opposing data sets.

Using Calculations for multi-step math operations

Use a Calculation Data Set to perform basic math operations to convert units. In this example, we have an I/O and Calculations tag that reads the temperature in imperial units and we want to convert to metric units for a report.

With this Data Set configured, the result of Step B will also become available as an input option in other Calculation Data Sets.

Combining Operation and Data types

Let's say you have a report of the flow activity for a couple of pumps and you'd like to add an extra column displaying their combined output as a percentage of flow capacity.

The output might look something like this:

A basic table entitled "Flow Metrics 2026-01-23". It has four columns, Time, Pump 1, Pump 2, and % of Flow Capacity. There is a summary row displaying averages.

You have already configured:

  • The title from a text component
  • A formatted table component, with a configured Time per Record
  • A Time column, showing the time of each entry.
  • Using a Tag Query data set, you've included both pumps in your report.
  • The flow capacity is adjustable, so you've added and linked a tag-type parameter.
  • A summary row to show averages.

All you have left to do, is add an additional column and add and configure a Calculation data set.

Here is a complete example:

Pictured here is a report canvas with a table component. The final column is highlit and it's data cell properties are visible. They are descibred as follows:

Step A

For the first step, we want to get the total per row. The Operation for Step A is Consolidate. The previously configured Tag Query data set "Pump Flow.Average" is available in the Data droplist, and the Consolidation type will be "Total".

Step B

Next we want to determine what fraction of flow capacity was taken up at each time entry. This is a basic math operation, Divide. Data 1 is a Data Set type so we can select the result of the first step, and that is divided by whatever value is stored in our parameter "FlowCapacity".

Step C

Finally, to display the fraction as a percent, we need to multiply it by 100. Step C is another basic math operation, Multiply. Data 1 is a Data Set type so we can select the result of Step B and Data 2 is a Constant type with the numeric entry, "100".

Data Columns

We don't want to display Step A or Step B in my report, so we have used the [ x ] button under Data Columns to remove those Steps. With Step C highlighted, we can configure the header and increase the precision to show decimal places.


Adding Notes to Reports

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

All tables start with a single column. Click the [+] bar to the right to add more.
Note that a tag query that includes multiple tags or calculations will generate as many columns as needed to display the result of the query.

Retrieve information from Notebook tags to include in reports. Notes may provide important context for developing data in reports. Note data column options include Note ID information, the operator associated with the note, original timestamp, last updated timestamp, and the name of the Notebook tag.

All tables start with a single column. To get started with a Notes Data Set, click + to the right of the column. A new column will appear, highlighted blue. In the Data Cell Properties panel, find the "Data Set" droplist and click the [+] to the right. A dialog will appear prompting for a Name and Type. Choose a name and from the Type droplist, select "Notes". The Data Cell properties pane will change to reflect the options available for the Notes Data Set.

Data Cell Properties for Notes Data Set include a delete button, Data Set selector, Data Set adder, Tag Selector, Data Columns, and filter options.

In this example, Operator Notes have been selected and the data column Tag Name is open for configuration

Data Set Properties - Notes Data Set

In the Data Cell Properties panel for Notes data set you will find the following options:

Delete the column

The trash can icon in the header of the Data Cell Properties panel deletes the column. Note that deleting the column removes it from the table but does not remove the Data Set definition. (You can delete Data Sets from the Data Set Manager).

Data Set

For every column you want to add to your report, you'll be making a Data Set. Data Sets may not always appear in reports. You can maintain a collection to easily swap values in and out of reports or reference Data Sets using other Data Sets.

You're likely to accumulate a lot of them, so it is a best practice to give them a descriptive name.

This field gives you the option to perform the following actions:

  • Select an existing Data Set, perhaps one that you have created previously.
  • Click the plus button [+] to create a new Data Set with a name of your choosing.

Set a Tag Hierarchy Context [Optional]

Context can be used in two ways:

  • As a filter, limiting tag selection to those below a parent tag.
  • As a parameter, allowing the same report to be run for multiple contexts or stations.

Setting a context for a tag query column.

For a Note data set, you may find it totally unnecessary to use a Context tag as a filter. The Notebook tag may exist at the / root of your hierarchy. Skip straight to the 'Tag Selector' button to open a tag selector dialog showing only Notebook tags by default. In most applications, you will see what you're looking for.

To use Context as a parameter, you must first create a parameter. Refer to Define Parameterized Reports. Note that a value must be assigned to the parameter for use in the Report Studio before you can continue with further steps. Proceed to tag selection as usual. When operators run the report, they will be prompted to select a station or other parent tag to use for that instance of the report. Use Report Tags to predefine a choice for the parameter.

Select a Notebook tag

You have the option of selecting a tag from the tag browser or selecting a report parameter. When using the Tag Selector, remember to use the 'Select Tag' or 'Add Query' buttons to add your selections before clicking OK.

Data Columns

Data columns are the Notebook Tag data points that will be included in the report. There are a few listed by default, you can add others by scrolling down and clicking the <<Click to Add>> tool when it appears. Remove data columns by selecting the column you wish to remove and clicking x. The columns will appear on the report in the order that they are listed here. Rearrange them by selecting a data column and using the arrow buttons to change the order. There must always be at least one data column for every Data Set.

  • Operator- The username that was logged in to the application when the note was submitted.
  • Original Timestamp- The timestamp from when the note was submitted. Recommended when displaying 'Whole Thread'.
  • Last Updated- The timestamp from the most recent comment left on a note.
  • Note- The contents of the note, the message.
  • Tag Name- The name of the notebook tag.
  • Note ID- All notes, including comments, have their own GUID (Globally Unique Identifier).
  • Parent Note ID- The GUID Closed Globally Unique Identifier. of the parent note. This value appears with note entries that are 'comments' nested under parent notes.

Filters

Narrow down the notes that appear in a report by configuring Filter settings. Some filters can be configured by text string or parameter. You can add and manage report parameters from the Parameter section in the ribbon. Add, modify and delete parameters from here, and optionally configure default values.

The icon on the left manages parameters. The icon on the right manages their values.

  • Note- Text or Parameter. Narrow down notes by a fragment of text or custom parameter. You can also make this case sensitive and choose whether or not to include comments.
  • Operator- Text or Parameter. Narrow down notes by Operator.
  • Display- Droplist. "Note Only" (default) only includes parent notes, not comments. "Whole Thread" displays all notes including comments. With "Whole Thread" selected, comments will appear under their parent note. Threads are coalesced this way to make it easier to see how events unfolded. Including the "Original Timestamp" data column is recommended. The parent note will have a timestamp sequential to the report record timestamps, but comments may have been added to the parent note at any time. Original Timestamp will show when subsequent comments were actually submitted.

Maximum Records

Optionally, set a maximum record limit for notes that appear within a report.

You cannot add Notes data set with a pivot table. Existing Notes columns will be dropped if you switch to a Pivot configuration. You may include Notes in a Transpose table, they will appear grouped together in relation to the location of the row on the canvas.

Sample Report with Notes

The same report includes a Timestamp column that shows one record per minute over a custom timespan, a Tag Query column displaying data from I/O & Calculations tags, and Notes from the Operator Notes default Notebook tag.

The Notes dataset has been configured to display the Whole Thread and include data columns "Tag Name", "Original Timestamp" and "Note".

The second note is a comment that was added to the"Good morning..." parent note. Notice how the Original Timestamp is out of sync with the Date column in the report? Threads are coalesced to keep the conversation together. Including Original Timestamp preserves the timeline.


Report Studio Outputs and Formats

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Reports generated in Report Studio are available in several output formats including HTML, Screen Display, Excel XLSX File, PDF File, CSV File, and to Print. The available Report Destination settings will change depending on the Output Type selected.

This Output Type selector serves as a quick reference for options. HTML, Screen, XLSX, PDF, CSV or print.

This Output Type selector serves as a quick reference for available formats and destinations

HTML

A file name and path must be specified before the report will run. You have the option of opening the result with your default browser immediately, or of simply generating the file silently.

When emailing a report in HTML format, images and line charts present in the report are attached in the report. Those attachments are referenced to show them in the email. This approach is compatible with Apple Mail, Gmail and many other email servers. To disable this setting, click the "Options" and deselect "Attach Drawings When Emailed".

The image displays a dialog with a single checkbox, "Attach Drawings When Emailed". Apply or Cancel to close dialog without changes.

Screen Display

The resulting report will be created using the HTML format, but saved to a temporary file that is used only to display that report on your screen.

Excel XLSX File

A file name and path must be specified before the report will run. You have the option of opening the result with your default browser immediately, or of simply generating the file silently.

An Options button appears if Excel XLSX File is selected as the Output Type.

You have the option to convert all values to text. This means all numeric values will be converted to text strings.

For a standard Excel XLSX output:

  • A header row is included in addition to the title row.
  • Formatting consists of the header & title rows being displayed with a bold font.
  • The worksheet will be named automatically using a timestamp.
  • Will be saved to a file on disk. You must provide the name and folder location for the file.
  • May also be sent to an email address, as an attached file.

Sample Excel report

PDF File

A file name and path must be specified before the report will run. You have the option of opening the result with your default browser immediately, or of simply generating the file silently.

You will be prompted for landscape or portrait mode when running each report if the Options option is selected.

If preserve background is selected, colors associated with the cells will be printed. Deselect in order to save ink and make text easier to read.

CSV File

Images and line charts are not rendered in a CSV output. A file name and path must be specified before the report will run. You may automatically open the report when it's complete, email the report or click Options to open the Options dialog.

From the CSV File Options dialog:

Custom CSV Separator

Allows you to replace the default comma separator with something else.

Include BOM

When enabled, the CSV file will include a byte-order-marker Closed Prefix that indicates the byte ordering used when the text was written.

Render Text Component

Render the text inside the text component in a CSV file.

Render Table Titles

Render table titles in the CSV file.

Printer

Reports configured in the Report Studio can be printed from the Reports Page or using a Report Tags.

To automatically print reports on a scheduled basis or to apply a time offset to a printed report, you must use a Report tag.

Printing is not available when running as a service.

Printing is not available from the Anywhere Client, but email is. See: Email Setup for Alarms and Reports

Printing from the Reports Page

You can configure reports in the reports page, in the Report Studio or using a report tag.

From Report Type, select the configuration that you saved in the Report Studio.

Change the Report Destination settings Output Type to Printer. The options will change once Printer is selected. VTScada will automatically detect the selection of printers that are available. These will be displayed in the drop-down. Click "Options" to select the printed orientation or change the "Preserve Background" setting:

Select orientation and background settings

Click the Run Report button at the bottom of the page to print your report.

The Browse button is only enabled when configuring Non- Report Studio ad hoc reports in the Reports page via the VIC Closed VTScada Internet Client. Allows you to connect to an application over the Internet with many of the features of a full VTScada workstation.. The browse button will show resources available to the thin client for printing to local machines. The default printer option will not work for a thin client unless the server also has the same default printer name.

Using the Run Report button will always be local, whereas triggered reports can be configured to run on specific workstation(s) or server lists. This may cause confusion for operators, without tag browser access, if they try to generate a report and expect it to behave the same way it does when it is triggered. (ex. It may print on a different printer).

To align report generation behavior, add a button for the configured Report tag:

Configure a report tag to trigger by tag value and use a Momentary button to set the value of that tag to 1. When the operator wants to run off a quick report, they will have a specific button for that.

Printing from a Report Tag

See: Report Tags.

When configuring your Report Tag, select the Report Type in the ID tab.

Configure your printer settings from the Destination tab. Once you have changed the destination to "Printer" the options will change to match:

The Report Tag will automatically detect available printers from the machine that the report would presently be generated on.

The report Generation Mode is configurable from the Report Tag's Trigger tab. This setting will determine which printers are listed in the Destination tab. If the generation mode is set to Server List and the primary machine for the service or server changes when the report is run, the report will run and printer from a different machine.

All Workstations is selected by default. A list of printers on the local machine will be shown. All workstations will attempt to find a printer of that name, and will print to each workstation where a printer of that name can be found.

If a specific server list or service is selected, then we will query the current primary machine of that server or service.

If a target workstation is specified, that machine will be queried for its printers.

Printing from the Reports Page will typically happen from the local machine. If the printer was selected via the Browse button when configuring a Standard Report, then it will try to use the VIC local machine.

You can select multiple destinations from one Output Type. For example, you could create a local HTML file and email the same report in the same generation cycle.
The way this works, is that VTScada generates the same report multiple times in the formats most suitable for your selections. If you choose to save the report locally and also email the report, VTScada is generating two versions of the same report and the process takes approximately twice as long.
During this process, the progress dialog will have a step count.

Related information:

The Report Studio

Report Tags

Email Setup for Alarms and Reports


Create Transaction Logger Reports

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

The Transaction Data Set provides access to data relating to Transaction Logger tags. Transaction Logger tags are used to record a collection of historical values as a single transaction that is stored in the historian. Previously, this data was commonly accessed through ODBC connections.

You must link to a valid Transaction Logger tag before you can configure the Data Columns.

To Create or Edit a Transaction Data Set

To create a Transaction Data Set you have two options:

  1. Add a column to the table component. Click the [+] that appears in the new Data Cell Properties pane.
  2. Click the [+] on the bottom-left below the Data Set Manager.

Either of these options will present you with a New Data Set dialog. Choose a name and select "Transaction" as the type.

Transaction Data Cell Properties include the name of the Data Set, the Transaction Logger tag linked to the set, 4 possible Data Columns, settings for each Data Column (as they are highlighted in turn), a maximum record setting defaulted to 10000 and Summary Suppression options.

Timestamp and All Remaining appear as default Data Columns. Select <<Click to Add>> for more options.

Transaction Logger Data Cell Properties

Delete the column

Click the trash can icon in the header of the Data Cell Properties panel. Note that deleting the column removes it from the table but does not remove the Data Set definition.

Create or Select a Data Set

For every column you want to add to your report, you'll be making a Data Set. Data Sets may not always appear in reports. You can maintain a collection to easily swap values in and out of reports or reference Data Sets using other Data Sets.

You're likely to accumulate a lot of them, so it is a best practice to give them a descriptive name.

  • Click the [+] button to create a new Data Set or use the droplist to select an existing Transaction Data Set
  • To Rename, Copy or Delete a Data Set, access it's properties via the Data Set Manager.

Select a Valid Logger

Logger can be used in two ways:

  • Link to a specific Transaction Logger tag.
  • As a parameter, allowing the same report to be run for multiple contexts.

Setting a context for a tag query column.

To use Logger as a parameter, you must first create a parameter. Refer to Define Parameterized Reports. Note that a value must be assigned to the parameter for use in the Report Studio before you can continue with further steps. When operators run the report, they will be prompted to select a Transaction Logger tag to use for that instance of the report. Use Report Tags to predefine a choice for the parameter.

Add Data Columns

Data Column options will be enabled after a valid Transaction Logger tag is selected as the Logger.

Add as many data columns as needed for each tag in the Data Set by clicking the <<Click to Add>> tool at the bottom of the list. There must always be at least one data column for every Data Set.

With a configured Transaction Data Set, you can retrieve values from specific child tags and other Transaction Logger data such as ID, timestamp and the name of the transaction tag that did the transaction.

The All Remaining Data Column is a catch-all for all unselected options (which is helpful if you don't want to manually select all children).

A unique property of a Transactions Data Set is the requirement to specify the Data Type. Data is retrieved from the historian rather than the current tag's history. There is no guarantee that a child tag that is now numeric wasn't previously a string. This allows users to control the formatting for the data they expect to retrieve.

Use the arrow buttons to change the order Data Columns appear in. Use the [ x ] button to remove Data Columns.

Summary Suppression

Summary Suppression is used when you have added a summary row to the table but the value doesn't make sense for this data set. For example, summing daily high temperature is not a helpful metric.

Another example of where you might use summary suppression is a pump report that includes a data column for flow characteristics, and a column for pump run time. The first Data Set might be summarized with a Range. The second might be summarized with a total. In this case, you would add two summary rows to your report and suppress them in the opposing data sets.

Data Column Reference for Transactions

  • Timestamp - The time when the value was recorded. A display format that includes milliseconds is recommended. Can be specified as a Timestamp or a String.
  • All Remaining - All Transaction Logger tag data recorded to the historian table such as the values of child tags present at the time of the transaction and all other data column values. Can be specified as Numeric, String or Timestamp.
  • TransactionID - The Transaction ID. Data Type must be String.
  • TransactionLogger - The name of the transaction tag that did the transaction.

Maximum Records

Optionally, set a maximum record limit for notes that appear within a report.


Transpose Tables

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Converting the default Table component to a transposed Table changes the table rows to columns and the columns to rows. Use a transposed Table for reports that have few rows and many columns. This configuration is suitable for reports with a few timestamps and many tags.

Here is an example of a report featuring a lot of pumps with just two timestamps using the default Table component:

The table has been cut off for display purposes. This table would not make a suitable .pdf or printed report.

Here is the same Data Set using a transposed Table:

We can now see all of the tags included in the tag query.

Transposed tables may also be used in batch processes where there are only a few batches and few or no additional steps but there are a large number of parameters such as ingredients:

This simplified report was generated using a recipe data set for a single step recipe that had run three times within the selected time span.

Creating a Transposed Table

Drag a Table Component from the Pallet onto the Canvas and click the top left corner to open Table Properties. Convert the table to a Transposed table by checking the box next to "Transpose Table"

Table Properties contains parameters for time per record, pivot or transpose configurations and visual settings.

The Table component appearance changes when Transpose Table is enabled. Instead of appearing as a column, it now appears as a row.

Use the Preview button at the top of the Report Studio to see how your data is represented in this configuration and to assist in tweaking your configurations.

Click the + at the bottom of the Table component to add Data Sets or click the + to the right of the Table component to add column summaries.

It is possible to enable Pivot Table and Transpose Table at the same time. Enabling Pivot Table would display parent tag names as row labels and child tag names as column labels. Enabling Transpose Table would then cause the parent tag names to appear as column labels and the child tag names to appear as row labels.

Related information:

The Report Studio


Tag Selector Dialog

The Tag Selector is used by the Historical Data Viewer (HDV) and SQL View Tag. Its purpose is described by its name: to select a group of tags for use with any of these data viewing tools.

The top half of this tool holds the Tag Selection list, showing all the tags available for selection. This list can be shortened by filters that you choose to apply. The lower half shows the Selected tags or Queries. While it is common to select individual tags, don't overlook the flexibility that a query provides. These build in flexibility by automatically including tags created later that also match the saved filter.

Typical Tag Selector.
Save Group, Delete Group and Plot are shown only when opened from the HDV.

Add individual tags

Tags shown in the Tag Selection list can be added to the Selected Tags list by either of two methods:

  • Double-click on a tag to add it to the list
  • Click once on the tag, then once on the Select Tag button near the bottom of the dialog.

Remove a tag or query from the selection

Tags can be removed from the Tag Selection list either one at a time or all at once. To remove everything from the list of Selected Tags, click the Remove All button.

To remove a single tag or query from the selection:

  1. If the tag selector dialog is not open, click the Tag Selector button to open it.
  2. Select the tag to be removed from the Selected Tags list (see image).

  3. Remove it by either double-clicking on the tag, or clicking on the Remove button.
  4. [Optional] If working with an HDV group, click, Save Group.

For the Historical Data Viewer only:
Removing a pen from the HDV display (as opposed to the Tag Selection List) does not affect a saved group.


Pivot Tables

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

Create a report table that displays parent names as row labels and child tag names as column labels. This comes in handy when displaying information for a large number of tags that have a common taxonomy and common names such as multiple pump device tags nested under a number of station tags.

The table displays a pumping station starts report with rows labeled Station 1 to 4 and columns labeled Pump 1 Starts to Pump 4 Starts.

Notice that Station 3 only has two pumps and Station 4 only has three. Therefore some cells are left blank on the table.

Creating a Pivot Table

Create a new report with a table. Table Properties should open in the component properties pane on the right. If you have navigated away, you can always find your way back by clicking the top-left cell on the table component. In the Table Properties pane, under Time per Record, enable the setting labeled "Pivot Table". Your table is now a pivot table.

The Date label will disappear from the table component and the first column will display row labels.

It is possible to enable Pivot Table and Transpose Table at the same time. Enabling Pivot Table would display parent tag names as row labels and child tag names as column labels. Enabling Transpose Table would then cause the parent tag names to appear as column labels and the child tag names to appear as row labels.

Configuring Pivot Table Data Cells

The default column, Row Label, will display the row labels specified later on. Leave the Data Set as the default, "Row Labels" and add a column B.

In the Data Cell Properties of column B, Create a new Data Set. Once named, the Data Cell Properties will change. The type should say "Tag Query".

Select a context tag (optional). This context tag can be an ancestor shared by every tag that you intend to include in the report.

Click the Tag Selector button to open the tag selector.

Using Queries and Wildcards

The key to easily scalable and complete reports featuring common, sequential groupings is using a strategic query. Instead of filtering and adding tags one at a time, you can type a query in a filter field and 'Add Query' to include all tags that meet the query criteria. For groups of tags, where each layer of the tag tree features the same name denoted with a sequential number or letter, using a query is a time-saver that will also capture changes to your tag tree. Take the following example:

Unseen are all the IO tags nested under each pump.

If you were to expand this tag tree fully, you would see common IO tags nested under sequentially named pumps, nested under sequentially named stations, nested under a jurisdiction, nested under one common context tag. Every pump in this example has a status tag with the shortname "Running". To create the Bedford Pumping Stations Start Report displayed above, I selected NS\Bedford as my context tag and used the following query in the tag selector:

Station ?\Pump ?\Running

The wildcard * (star or asterisk) is a placeholder for any number of alternative characters.

The wildcard ? (question mark) is a placeholder for a single character. If you had tags running into the double digits, you might have to add a second query using "??" instead.

This configuration captures all of the status tags named Running nested under any numbered pump, from all of my numbered stations nested under my selected context tag.

Select one or more Data Columns and configure the Header parameters...

Configure your Row Label parameters at the bottom of the Data Cell Properties Panel...

Format row and column labels

There are three parameterized phrases that are especially relevant for configuring Pivot Tables:

%[AncestorShortName]

This parameter takes just a shortname from the tag name, specified by level.

The table displays a pumping station starts report with rows labeled Station 1 to 4 and columns labeled Pump 1 Starts to Pump 4 Starts.

In the provided example, the full tag name of the top-most entry is NS\Bedford\Station 1\Pump 1\Running.

The Data Column header parameter is %[AncestorShortName] %[DataColumn] with the AncestorShortName level set to the default 1. One step up in the tag name is "Pump 1", and next to this the selected Data Column.

The Row Label parameter is %[AncestorShortName] with the level set to 2. Two steps removed in the tag name is "Station 1".

%[AncestorRelativeName]

This parameter displays a portion of the full tag name from a specified ancestor level up to, but not including, the selected as the context of the query.

In the provided example, the full tag name of the top-most entry is NS\Bedford\Station 1\Pump 1\Flow Rate. The specified level is 2 and the selected context tag is NS.

%[AncestorDescription]

The configured description of an ancestor tag specified by level. This is the description from the tag properties ID tab.

Related information:

The Report Studio


Deprecated PLC Alarm (OGS)

The PLC Alarm Tag was developed in the Oil and Gas Solutions layer. That legacy version of the tag is now deprecated. Customers who were using it should consider updating their applications to use the replacement version.

Should I update my PLC alarm tags, or continue to use the deprecated version?

The deprecated version of the PLC alarm tag is not supported and may have functional problems. For this reason, we recommend upgrading to the current version. It is possible to continue using the deprecated version until you are ready to update to the newer version.

Features available only in the legacy PLC Alarm tag:

  • Trip alarms
  • Pulse Acknowledging
  • Alarm Pop-ups
  • Explicit Owner Tags and Contribution Types

    (the basic contribution of alarm information of the tag is passed along implicitly to the "Associated Tag")
  • Custom Alarm Sounds
  • Reset and Latch bit control
  • Custom bitwise inversion of all read addresses

Legacy features, not supported by either version:

  • Alarm Suppression (P_SuppressedAddr, P_WrSuppressAddr, P_WrUnSuppressAddr)
  • Alarm Delay (Supplying an alarm delay duration using the right-click menu)

Features available only in the replacement PLC Alarm tag:

  • Reporting and control of the Disabled/Shelved/Acked status of the PLC alarm from the Alarm Page for Custom and Allen Bradley CIP PLC alarms
  • Display of the tag description on the alarm page.
  • Display of useful setpoints/values of PLC alarm tags on the alarm page.
  • No graphical glitches in the alarm tag properties dialog.
  • The ability to configure shelving durations for alarms
  • Consistent right-click functionality of the alarm records.
  • Functional delays for alarms
  • Individual control of security for the PLC alarm tag
  • The ability to mark the data from the tag as being Questionable
  • The ability to set an alarm’s Setpoint, Priority, Deadband, Delay, and Alarm condition (for digital alarms) in the PLC directly.
  • Custom alarm priority/severity mapping between VTS and the PLC
  • Custom display options for the tag, such as using an associated tag for displaying information on the alarm page, units, and style settings tags
  • Integration with the higher performance situational awareness widgets

To Continue Using the Deprecated PLC Alarm Tag:

Perform the following steps in each application for which you would like to continue using the deprecated PLC alarm tag.

  1. Add a Property containing the following information:

  2. Repeat this process, adding the following properties:
Property Name | Section | Value
PLCAlarm | RenamedVariables | LegacyPLCAlarm
PLCAlarmConfig | RenamedVariables | LegacyPLCAlarmConfig
PLCAlarmCommon | RenamedVariables | LegacyPLCAlarmCommon

  3. Restart the application.

You should be able to continue using the deprecated PLC Alarm tag. The warning should not reappear.

Update to the Current Version of the PLC Alarm Tag

Perform the following steps in each application for which you would like to update the PLC alarm tags.

These instructions assume that Microsoft Excel is installed on your workstation.

  1. Ensure your application's language is set to English.

  2. Add a Property containing the following information:
    (This is necessary in order to export the existing tags.)

  3. Restart the application.
    The application will now be using the Legacy PLC alarm tag, allowing you to export the legacy parameters.
  4. Open the Application Configuration dialog.
  5. Open the Export, Synchronize page
  6. Select the export options, "Mark empty sheets as hidden", "Exclude automatically created tags".
  7. Export the tag database, paying attention to your choice of destination folder.
  8. Using Windows File Explorer, navigate to the destination folder.
  9. Make a copy of the exported tag database.
    (It is always advisable to have a backup. You may wish to save incremental backups as you work through the following procedure.)

Do the following within the Excel workbook, created in the previous set of steps.

The columns you will insert and modify must be placed after the Export Info column and before the Tag_Start_Condition column. Other than that restriction, the order of the columns does not matter.

  1. Navigate to the PLCAlarm sheet.
  2. Delete the following columns, which represent features not supported in the new PLC Alarm tag:

P_LAlarmAddr

P_SuppressedAddr

P_WrSuppressAddr

P_WrUnSuppressAddr

ResetAddr

Trip

Delay

AlarmSound

OwnerTag

ContributionType

PopUp

PulseAck

  3. Insert a Column titled “PLCType”.
    Refer to the earlier note about column placement.
  4. For every row that has AB CIP PLC alarm blocks, enter the following as the PLCType:
    Allen Bradley CIP PLC
  5. For all other alarm block types, enter the following as the PLCType:
    Custom PLC
  6. In the AlarmType column, perform the following replacements:
Current Value | Replace With
AB-Digital Alarm | Digital Alarm
AB-HiHi Alarm | High High Alarm
AB-Hi Alarm | High Alarm
AB-Lo Alarm | Low Alarm
AB-LoLo Alarm | Low Low Alarm
AB-PosROC Alarm | Positive Rate of Change Alarm
AB-NegROC Alarm | Negative Rate of Change Alarm
  7. For any rows that now have “Custom PLC" as the PLCType, populate the AlarmType Column with the appropriate alarm type from the list above (e.g. Low Alarm or Digital Alarm)
  8. Perform the following replacements of column titles:
Current Title | Replace With
DeviceTag | I/O Device Name
P_AlarmAddr | ActiveAddress
P_AckAddress | AckedAddresss
P_WrAckAddress | AckAddress
P_DisabledAddr | DisabledAddress
P_WrDisableAddr | DisableAddress
P_WrEnableAddr | EnableAddress
P_ShelvedAddr | ShelvedAddress
P_WrShelveAddr | ShelveAddress
P_WrUnshelveAddr | UnshelveAddress
P_TimerAddr | DelayAddress
ScanInterval | ScanRate
InvertInput | InvertAddrBits
DelayUnits | PLCDelayInSec
Priority | PriorityParm
AlmBlkName | AlarmBlockName
  9. (This step is conditional. If the following does not apply, skip to step 10)
    -> If using any Custom PLC alarm tags
    OR
    -> If using the AlarmBlockName parameter
    Then...
    For each Custom PLC alarm tag, ensure that the *Address columns (P_AlmAddr, P_AckAddress, etc.) do not contain that tag’s AlarmBlockName. For each address that contains the text of that tag's AlarmBlockName as a prefix, either delete that tag's AlarmBlockName parameter to store this information in the addresses or delete the alarm block name prefix in the address columns. (This can be done with find and replace in the applicable cells.)

    The final address is a combination of the AlarmBlockName and the address, so ensure that any necessary delimiters are contained in the alarm block name or the addresses.
  10. As appropriate for your tags:
    Set the value of InvertAddrBits to 1 to invert the alarm condition, or either 0 or blank for normal behavior.
  11. For every cell in the column PLCDelayInSec that has the value 1000, replace the 1000 with 0.
  12. (Optional) To configure additional settings in the tag and take advantage of the new features of the PLC alarm tag, insert the following columns:
Column | Data Type
SecurityBit | String
Questionable | Boolean
Associated Tag

String

Set every cell to *Numeric, which will link to the parent numeric tag.
This column is recommended in order to retain default linking.

StyleTag

String

Optionally, set every cell to *Style Settings, which will link to the default System Style tag.

DisplayHookInfo | Boolean
Units

String

Must be a phrase ID for the desired units

TripOptions Set as 2 to add the digital state to the alarm message.
Set as 0 otherwise.
PriorityMap String
Comma separated values of numeric severities in the PLC
ValueAddress String
Address to the alarm trigger value
SetpointAddress

String

Address to the alarm setpoint

PriorityAddress

String

Address to the alarm priority

DeadbandAddress

String

Address to the alarm deadband

ConditionAddress

String

Address to the alarm condition

  13. Save and close the Excel spreadsheet.

  14. If your application contains any custom tag types that contain a PLC alarm tag as a child, there are additional steps to be taken here. Repeat the steps from 7 in the preceding block (export to Excel) through to 13, for each of the custom types with PLC alarm tag children, exporting the excel spreadsheet from the Manage Types tab of the application configuration dialog.

  15. Delete the application setting added in Step 2 of the first set of steps.
    This will cause the application to use the upgraded PLC Alarm tag.
  16. Restart the application.
    (A warning will remind you that you have legacy PLC Alarm tags.)
  17. Sync the changes to the tags in the Excel spreadsheet (Export, Synchronize).

You should not see the warning about deprecated PLC alarm tags on your next restart. You can continue to use the updated PLC alarm tag.


BSAP Driver Tags

Not counted towards your tag license limit.

The BSAP driver enables communications between VTScada and RTUs using the BSAP communication protocol.

Closed Related Application properties

The following property settings hold additional configuration parameters for your BSAP driver:

BSAPRestartTime - BSAP Driver restart time. Defaults to 15 seconds.

BSAPRBEScanRate - BSAP Driver RBE scan rate. Defaults to 300 seconds.

BSAPRBEScanSlice - BSAP Driver RBE scan slice. Defaults to 1.

BSAPRBEMsgFrmt - BSAP Driver RBE message format. Defaults to 1.

BSAPRBEStopXmit - BSAP Driver RBE Stop Transmit setting. Defaults to 0.

BSAPRBEWaitMsgTO - BSAP Driver RBE wait message timeout. Defaults to 300 seconds.

BSAPMaxFrameSize - BSAP Driver IBP maximum frame size. Defaults to 1000 bytes.

BSAPMsgSendTimeOut - BSAP Driver IBP message send timeout. Defaults to 0.5 seconds.

BSAPUnAckMsgCount - BSAP Driver IBP unacknowledged message count. Defaults to 15.

BSAPTimeSyncTimeOut - BSAP Driver time synch timeout. Defaults to 60 seconds.

BSAPUDPRetryDelay - BSAP Driver UDP retry delay. Defaults to 10 seconds.

Closed BSAP Driver properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Closed BSAP Driver properties RTU Configuration tab

Local Address

Local address of level 0 RTU (1 - 127).

Global Address

Global address of the level 1 - 7 RTU - must be invalid for level 0 RTU

Time Sync Port Number

Time synchronization UDP port number.

Time Sync Frequency

Time synchronization frequency in seconds.

RTU Polling Time

Period between subsequent polls by the BSAP network manager of the level 0 RTU which may have other reachable RTU's via radio or other means. Note that the Network Manager communicates on a given port and all RTU's using that port use the same network Manager. Therefore if an RTU tag changes this value it will be updated in all the RTU drivers associated with that port. This is so that on a restart of the Network Manager, which can be started by a different driver tag, the driver would see the changed value.

Download Security

Used to attach a security privilege to the download functions on the driver. The user must have this privilege in their VTScada account to perform download functions.

Driver Service Name

The RPC service name to be used by this driver. Leave blank if unsure of using the same service as all other BSAP drivers.

Closed BSAP Driver properties Communications Configuration tab

Connection Time Limit

Connection timeout for the network manager making a connection to a level 0 RTU. Note that the Network Manager communicates on a given port and all RTU's using that port use the same network Manager. Therefore if an RTU tag changes this value it will be updated in all the RTU drivers associated with that port. This is so that on a restart of the Network Manager, which can be started by a different driver tag, the driver would see the changed value.

RTS Key Off Delay

Key off delay for radio operation.

Local RTU Time Limit

Response timeout limit for level 0 RTU.

Data Read Time Limit

Read response time out limit for RTU response.

RBE Time Limit

Timeout limit to wait for a response for status request message from the RBE manager task in the RTU

Retries

Number of driver retries on failure before an error is logged. Note that the Network Manager communicates on a given port and all RTU's using that port use the same network Manager. Therefore if an RTU tag changes this value it will be updated in all the RTU drivers associated with that port. This is so that on a restart of the Network Manager, which can be started by a different driver tag, the driver would see the changed value.

Hold

If selected driver data will remain at the last known value on communications failure. If unselected data will be blanked or made Invalid.

Closed BSAP Driver properties NRT Closed Node Routing Table Configuration tab

The configuration of a BSAP driver's node routing table:

Global Address Calculation

A Network 3000 node determines its global address and its UP/DOWN mask as follows.

The calculation uses the node's local address, level number, level shift count, level bit mask and the global address of the node's local master. The NRT Closed Node Routing Table trickles down from the network master to all nodes on the net-work. A master passes an exact copy of its NRT to each of its slaves. Each slave then uses the procedure described following to construct its NRT which it then passes to each of its slaves. Both the NRT global ad-dress field and UP/DOWN mask starts off as zero (i.e. the network master's global address and UP/DOWN mask are by definition zero). As the NRT is distributed each node determines its global address and UP/DOWN mask and fills in the appropriate field in the NRT. Therefore the global address of a node is the concatenation of the local addresses of all previous local masters that the NRT has traveled to, from the network master to that node.

The following steps illustrate the calculation of a node's global address.

  1. Increment level number
  2. Node's local address shifted left Level_Shift_Count times
  3. Result from step 1 is OR'ed in with the current NRT Global address (i.e. local master's global address)
  4. Result from step 2 is now placed in the NRT Global address field (i.e. now it is the node's global address)

The following steps illustrate the calculation of a node's UP/DOWN mask.

  1. Node's Level_Bit_Mask shifted left Level_Shift_Count times
  2. Result from step 1 is OR'ed in with the current NRT UP/DOWN mask (i.e. local master's UP/DOWN mask).
  3. Result from step 2 is now placed in the NRT UP/DOWN mask field (i.e. now it is the node's UP/DOWN mask).
Closed BSAP Driver Tag Widgets

The following widgets are available to display information about your BSAP driver tags:

Comm Indicator Widget

Comm Messages Button Widget

Show Statistics Button Widget

BSAP Driver Addressing

The I/O tag addressing consists of a text-based tag name with a prefix as follows:

I/O Reads:

I/O Read Prefix | Function
RDB | Read Database
PTP | Point to Point
RBE | Report by Exception

I/O Writes:

I/O Write Prefix | Function
DIG | Digital I/O Tags
ANA | Analog I/O Tags
STR | String I/O Tags


Best Practices for Tags

Tags are identified using four parts: name, area, description and placement in the tag hierarchy. You are advised to use all four. (Equipment type is also available as an identifier but applies only to I/O and Calculation tags and may have a very specific purpose.) The following rules and recommendations will help you keep your tags well organized, even if their numbers run into the hundreds of thousands.

Plan your tag structures carefully

It's helpful to group tags according to their purpose in your application. Whether it be by state, zone, station, mechanism or controller, there is always a logical way to organize tags. In particular, make use of Context tags as a parent to group tags that relate to one another. Instructions are provided in: Design Your Own Tags

For large applications (many thousand tags) you might need extra Alarm Databases, in which case those should be the parent for a group.

When viewing a child tag, you will also see the parent names. The current tag's name, excluding its parents, is called the "short name". The full name (parents + current tag) is usually just called the "name".

Tag naming (See also: Naming Rules)

  • The name of a context (the parent of a hierarchy) should be specific, such as "Site A" or "Mixer 1".
  • The name of a tag describing an I/O address should either use a standard such as ISA-5.1 - Instrumentation Symbols and Identification, or it should be generic. "Flow Rate" rather than "Site A Flow Rate".
  • Do not repeat information in a child tag name that exists in a parent name.
    For example, if the tag measures flow within a pump, just name it Flow.
    \Station 1\Primary Pump\Flow
    ...is better than...
    \Station 1\Station 1 Primary Pump\Station 1 Primary Pump Flow
  • VTScada allows spaces within names but some installations may prefer to avoid them.
  • Keep full tag names shorter by using flatter hierarchies. Sibling tags that share a parent can link automatically where there is no eligible ancestor tag or conflict. Port tags, driver tags and I/O could share a parent context tag.
  • Tag names must be no longer than 64 characters in length

This rule refers only to the tag's immediate name, not its full name, which may include a lengthy list of parent tags.

  • Full tag names must be no longer than 253 characters in length

This rule refers to the tag's full name, which may include many parent tags.

  • Tag names must not duplicate other named items (reserved words).
    • You cannot name a tag "TagBrowser" or "Test", since those names are used elsewhere in VTScada.
    • A tag may not be named "Value" or "Area" since those are the names of tag properties.
    • Tag names may not duplicate Type names - you cannot name a tag "Calculation" or "Analog Status".
    • Tag names may not duplicate any function names. Refer to Function Reference.
    • In general, it is safest to avoid using common words unless you add a prefix or suffix.
  • Valid tag name characters include:
    • Any combination of alphanumeric characters (i.e. A through Z, and 0 through 9)
    • Spaces, except at the beginning or end of the name.
      (Some installations choose to avoid spaces as they can cause confusion. For example, "A B" looks like "A B" but the second has two spaces and is therefore a different name.)
    • Period
      (Legal but discouraged.)
    • Symbols other than those listed below.
      (Underscore _ and dash - characters are used in place of spaces at installations where spaces are avoided.)
  • Invalid tag name characters include:
    • Backslash (\ which used to separate parent names)
    • Forward slash (/)
    • Colon (:)
    • Asterisk (*)
    • Question mark (?)
    • Double quotes (")
    • Less than (<)
    • Greater than (>)
    • Vertical bar (|)
    • Leading spaces
    • Trailing spaces
  • Tag names cannot be purely numeric.

"51" is not a valid tag name but "Station 51" is.
An interesting side effect of this rule is that you cannot name a tag "E1" or similar because this is a valid numeric expression: ("E1" == "0E1" == "zero exponent one").

In the event that you have entered an invalid tag name, VTScada will notify you with a warning dialog and will clear the Name field so that you can try again.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Use the Area property to help organize tags

The Area property, although not required, is strongly recommended. It helps you filter your tags for reports and other tag selection dialogs so that you can locate tags quickly, especially in larger applications where there are thousands of tags.

Add Areas: To define a new area, type the name in the area field of a tag's properties dialog. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended because a typo or misspelling will result in a second area being created.

Remove Areas: There is no tool to remove an area name from VTScada because such a tool is unnecessary. An area definition will exist if any tag uses it and will stop existing when no tag uses it, following the next re-start. (The equipment property of an I/O tag works the same way.)

When working with Parent-Child tag structures, the area property of all child tags will automatically match the area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow-ish to indicate that you have applied an override.

If you are using child tags, note that their area will automatically be the same as the nearest parent with an explicitly configured area. You can override this if a child tag should have a different area value than its parent. If you decide to remove your override, right-click on the Area property and select "Inherit from parent" from the menu that opens.

Roster tags, which control the list of operators to be contacted in the event of an alarm, are linked to tag areas. All tags sharing an area will use a matching roster. Roster Tags

Filtering rules can prevent tags with certain areas from starting on named workstations. Tag Area Filtering

Areas can also be associated with user groups to restrict configuration access to part of an application when users are connecting over the Internet from a VTScada Thin Client. Realm Filtering

Note that for Modem tags that are to be used with the Alarm Notification System, it is required that the area field be left blank.

In I/O and Calculation tags, use the Equipment Type to help filter or display tags

As an example, if you set the Equipment Type to "Pump" for all digital I/O tags that indicate the running state of your pumps, then in the Reports page, the Pump Activity Report will filter for and find just these tags.

There is no tool to remove an equipment type from VTScada because such a tool is unnecessary. An equipment type definition will exist if any tag uses it and will stop existing when no tag uses it, following the next re-start.

Any tag that has been assigned an equipment type will use the labels and display characteristics defined for that type in a Style Settings tag. (Note that this may override the default style for the tag such as "digitals" or "analogs".) You can then use the I/O Multi-Text widget to display those labels. Equipment types may also be useful for filtering tag selection, such as in reports.

You are free to create as many equipment types as you need, and you may do so from within either an I/O tag on the ID tab or a Style Settings tag on the Equipment tab. The instructions are the same in both cases:

  1. Place the cursor in the Equipment Type field.
    (It does not matter whether the field is blank or shows an existing type.)
  2. Type the name of your new equipment type.
  3. Press the [tab] or [Enter] key on the keyboard.
  4. Click the Apply button.
    The new type is saved.
    If the field had shown an existing type before you started, it is not changed.

The Equipment Type of an I/O and Calculations tag is a powerful feature when used with care. Do not assign Equipment Types casually, without a clear plan for how you intend to use this feature.

Write a clear description

Tags should be given a description that identifies the tag using plain language. The tag description appears throughout VTScada in tool tips, and in the Tag Browser, to help users determine the tag's name and its function. The Alarm Notification System will identify alarms using the description rather than the name (subject to your configuration choices), therefore it is vital that you provide a clear, unambiguous description for tags that are alarmed. This is especially important if using a naming standard that creates cryptic names such as "26PHDL\VC-0001\FCVY1".

Help Search Key

Used only by those who have developed their own Compiled Help Module (CHM) documentation. To see this system in action, right-click on any tag, as drawn on any page. The pop-up menu will include a Help option. Select that and you'll be reading VTScada's documentation about the selected tag. You could be reading your own documentation instead.

This is not commonly done. Refer to Custom Help Files in the reference topics at the end of the VTScada documentation for further information and other options.


DDE Client

Not counted towards your tag license limit.

The DDE client enables tags to read from and write to a local or network DDE server.

Related information:

Best Practices for Tags

Use VTScada as a DDE Server - How to access VTScada data from a DDE client program.

VTScada as a Local DDE Client - How VTScada can read from (and write to) a DDE server program.

VTScada as a Network DDE Client - Information provided for backward compatibility.

Reference Notes:

The DDE acronym represents the term Dynamic Data Exchange, an inter-process communication system built into the Windows® operating systems. DDE enables two running applications to share the same data. For example, DDE makes it possible to insert a spreadsheet chart into a document created with a word processor. Whenever the spreadsheet data changes, the chart in the document changes to match.

The version bit of your VTScada installation (32-bit versus 64-bit) must match that of your operating system in order for DDE features to work.

DDE can also enable VTScada to accept data from another application, such as a chart, word processing document or spreadsheet. To do so, VTScada uses its DDE Client tag.

The application that supplies the data is called the server, while the program that accepts the data is called the client. VTScada can act as either a DDE client or a DDE server. The sections that follow provide instructions for configuring dynamic data exchange from an outside application to VTScada, and from VTScada to an outside application.

VTScada DDE functionality is deprecated as of version 12.0.00 and should not be used in new applications. Extreme care is advised for its continued use. Special configuration is required to run, please reference Use VTScada as a DDE Server.

DDE Client properties ID tab

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

  • Filter for particular tag groups when searching in the tag browser
  • Link dial-out alarm rosters to Alarm tags having a particular area
  • Limit the number of tags loaded upon startup.
  • Filter the alarm display to show only certain areas.
  • Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

DDE Client properties Local DDE tab

The Local DDE tab of the DDE Client tag properties folder is used to set the application name for and a topic supported by the DDE server.

DDE driver Local DDE tab

DDE Application Name

The DDE Application Name field enables you to enter the DDE program name. For example, "Excel".

DDE Topic Name

The DDE Topic Name field enables you to enter the name of a topic supported by the DDE server. If the application is Excel, this would be the name of the workbook file. For example: "MySpreadsheet.xlsx".

DDE Client properties Network DDE tab

The Network DDE tab of the DDE Client tag properties folder is used to set the name of the computer on which the DDE server is running, and the share name that identifies the DDE server on the computer.

DDEShare is based on NetDDE. For security reasons, Microsoft stopped distributing this product for versions of Windows following XP. If you choose, you may still be able to find and install NetDDE for your version of Windows. The instructions for doing so are beyond the scope of this document.

DDE driver Network DDE tab

DDE Computer Name

The DDE Computer Name field enables you to enter the name of the server on which your DDE share (specified in the DDE Share Name field) was created (e.g. Station9).

DDE Share Name

The DDE Share Name field enables you to enter the name of the DDE share you created on the server specified in the DDE Computer Name field. You must add the .OLE extension to the name of the DDE share (e.g. DDEShare$.OLE).

Note: Unlike the Modicon, Allen-Bradley, and Omron Host Link drivers, the configuration folder and common routines for the DDE Client cannot be customized.

Closed DDE Client Tag Widgets

The following widgets are available to display information about your application’s DDE Client tags:

Comm Indicator Widget

Color Line Widget

Equipment / Status Color Indicator

Indicator Light Widget

LCD 5x7 Matrix Widget

LCD 7 Segment Widget

Multi-Color Widget

Multi-Text Widget

Numeric Value Widget

Plot Data Widget


OPC Server Error Codes

Error Code (Decimal) | Meaning
0 | No Error
1 | Failed to load OPC Automation DLL
2 | Connection request to OPC Server failed
3 | OPCGroups object not retrieved
4 | Failed to add I/O Group to OPC Server
5 | OPC Server Status is unavailable
6 | OPC Server is not in running state
7 | OPC thread heartbeat fail
8 | Unknown error
9 | Maximum internal error


Diagnostic Utilities

In general, the diagnostic utilities are useful to:

  • Programmers when writing VTScada script code.
  • Customers when directed to use a tool by VTScada support staff, in order to diagnose a problem.

These tools are designed to be functional, rather than user-friendly. Most utilities are not listed in the VAM by default, but can be added using the Find Existing option of the Add Application Wizard.

The most versatile and powerful of VTScada's diagnostic utilities is the Source Debugger. Start here when attempting to diagnose performance issues or debug code.

Coordinates Application - Small window showing the coordinates of the cursor within any VTScada window.

Debugger Utility - Early version of the Source Debugger. Rarely used now.

Instance Count Application - Counts the number of instances of all modules in all running applications.

Memory Tracer Application - Can be used to trace high memory usage to specific modules.

RPC Timing Utility - Monitor the time required by server-to-server messages.

Test Framework Application - Use to run tests that you have created to prove that your script code is working properly.

Thread List Application - Shows a list of all threads in use by VTScada.

Trace Viewer Application - Monitor inter-server communications, device driver communication, or SOAP messages.

Trace VTScada Actions Application - Monitor actions of selected VTScada services.


Bar Graph Widget

This widget can include any set of numeric tags, but cannot be linked to a tag.

* Does not use the Style Settings tag.

This widget is used to display the values of a set of tags in the form of a two-dimensional bar graph. The graph updates continuously with changing values.

The properties dialog for the Bar Graph widget:

Tags & Colors

Use the + button to select all the numeric tags that should be included in the graph. Each defaults to the color black; you will need to select appropriate colors as you add the tags.

Use the - button to remove a tag from the set and the arrows to adjust the order.

Font

Select the font to use for labels and legends.

Label Color

Sets the color of all text used for labels, unless you choose to color labels to match segments.

Bar Outline Color

Defaults to transparent.

Grid Outline Color

Draws a bounding line around the full graph. Defaults to black.

Grid Background Color

The background color of the graph portion of the widget. Defaults to transparent.

Grid Line Color

The color to use for marker lines within the grid. Defaults to gray.

Expected Range

If an analog I/O tag has been configured with an expected range, it will be shown on top of the matching bar using this color.

Show Labels

When selected, labels are shown outside the chart, beside each matching segment. Content and color of the labels depend on the following selections:

Show Axis Scale

No scale is shown unless selected.

If selected, then a single scale is shown, spanning from the minimum scaled value of all the selected tags to the maximum scaled value of the tags.

Extra space is always provided above the full scale range, but not below.

Show Legend

Controls whether a legend is shown below the bar graph. The legend cannot be moved elsewhere.

Tag names or descriptions are shown depending on the next selection.

Use Tag Descriptions

Applies to both labels and legends. If not selected, tag names are shown instead. For this case, the immediate (short) name of the tag is always shown. Names of parent tags are shown or not according to the following parameter:

Name Depth

Relevant only when Use Tag Descriptions is not selected (tag names are shown rather than descriptions). Minimum value of 1.

This controls how many of each tag's parents are included in the label.

Digits After Decimal

Applies to both labels and the legend. Defaults to 0 digits following the decimal.

Sort Order

Bars are shown in the order that tags are entered in the selection list unless otherwise configured by this parameter which sets the sort order by name, ascending or descending.

Show Values

Controls whether values are displayed with each bar.

Color Values to Match Bars

When selected, values (if displayed) are shown with the same color that was selected for the matching bar. Otherwise values are shown in same color being used for the labels.

Use Dynamic Range

When selected, the scale will continuously vary to match the largest current value of any of the tags in the selection set.

Draw Left to Right

Vertical bars are drawn by default. Select this option to draw the graph as horizontal bars.

Bar Width (%)

Defaults to 80%. The minimum value is 1% and the maximum is 99%. Space is allotted for each bar by dividing the width of the widget by the number of bars (tags) displayed. This parameter controls the space shown between each bar by restricting the colored area to a percentage of it's width.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:

Analytics\Charts and Graphs


Bristol Communication Messages Dialog

The Comm Messages button will display the following information about a Bristol driver tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Bristol BSAP/IBP Driver


Bristol Driver Statistics Dialog

The Show Stats button will display the following information about a Bristol driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Stats for Identifies the station for which these statistics have been gathered.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Dt The Response time - that is, the time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Related information:

Bristol BSAP/IBP Driver


Bristol Network Communication Messages Dialog

The Comm Messages button will display the following information about a Bristol Network tag in response to a left-click.

Displays the full driver name and version.

Data may be displayed in any of the 4 types shown.

Number Transmitted and Received provides a running count of messages in each direction.

Transmit & Receive display communications data using the data type selected above. The Index helps locate each byte within a message.

The Hold Data button will freeze the display. Otherwise the dialog updates continuously as messages are transmitted.

If you have the protocol information for the device, you can interpret each of the transmitted and received bytes to determine their meaning. The basic information that can be obtained from the Communication Messages window is that communications are proceeding as normal as long as bytes appear in both the Transmit and Receive columns.

If bytes appear in the Transmit column but not in the Receive column, VTScada is trying to poll the PLC for data (sending a read request) but the PLC is not responding. In this case it is wise to check the properties of the tag to make sure all settings are correct.

Related information:

Bristol Network Communication Messages Dialog

Trihedral and VTScada are registered trade marks of Trihedral Engineering Limited
© Trihedral Engineering Limited 1987- 2026 All rights reserved.


Bristol Network Statistics Dialog

The Show Stats button will display the following information about a Bristol Network tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Driver Type Identifies the driver.

Stats for Identifies the station for which these statistics have been gathered.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

Dt The Response time - that is, the time between successive messages. The Response time is typically used to determine how fast data is being transferred for drivers that request data at regular intervals.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess A message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time The time of the last reported error.

Error Date The date of the last reported error.

Error Owner The address at which the last error occurred.

Error Station The address of the station at which the last error occurred.

Related information:

Bristol Network Statistics Dialog

Trihedral and VTScada are registered trade marks of Trihedral Engineering Limited
© Trihedral Engineering Limited 1987- 2026 All rights reserved.


Campbell Driver Pointers Widget

* Does not use the Style Settings tag.

Used by: Campbell Scientific Driver.

The Campbell Pointers widget creates a button that operators may press to display the status of the sample table reads. Values are for display only, not for configuration. A button allows the operator to clear the local (to the dialog) copy of the last pointer read.

The properties dialog for this widget. The only user-configurable option is the label for the button.

Widget Folders:

Tag Types\I/O Devices (Drivers)\PLCs and RTUs\Campbell Scientific Array Driver\

Related information:

Choices for Operator Interaction


CIP Driver Statistics Dialog

The Show Stats button will display the following information about a CIP driver tag.

Driver Name The name of the driver (within the driver's code) for which statistics are being displayed.

Version The version number and date that this driver was created.

Counts The number of successful communications since the system started.

Timestamp The time of the last successful communication.

Date Stamp The date of the last successful communication.

dt The Response time - that is, the time between a request for information and the message being received.

Error The error number (code) for the current error.

Error Mess A message describing the type of communications error that has occurred.

Last Error The error number (code) for the last error that occurred.

Last Error Mess The message describing the type of communications error that last occurred.

Error Count The number of errors that have occurred since the system started.

Error Time Time when the last error message was recorded.

Error Date Date when the last error message was recorded.

Error Info Further details regarding the message.


Flow Meter Site Draw Widget

Used by: Flow Computer, POC-DV8, POC-Lufkin SAM Well Manager, POC-Unico, Weatherford

* Does not use the Style Settings tag.

The Flow Meter Site Draw widget is used to display a site icon, indicating the current state of the linked tag. Optionally, this can also be used as a navigational tool, opening a selected page in response to an operator's click.

The properties dialog for the Flow Meter Site Draw object:

Use Theme Color

Select to use the application's theme color with the associated site page.

Text Color

Assign the color to be use for the foreground text color within the page.

Click action

This widget can do any of the following in response to an operator's click:

  • Nothing.
  • Open the default Site Page as a pop-up window.
  • Open a custom page. Note that this page should take a Flow Computer tag as a parameter.

Disable Options

Disable selected operator-interaction features of this widget.

See: Operator Interaction Controls

Widget Folders:


Certificate Error Messages

The following errors may occur when a certificate is being trusted as part of the validity checks. These error messages are displayed when moving certificates from the Untrusted store to the Trusted store.

Error Message | Meaning | Solution
The server name does not match the certificate | The name of the server presenting the certificate is not found in the 'Subject' or 'Subject Alternative' names. | Create a new certificate with the server name set as the Common Name or included in the Subject Alternative Name list.
The EKU (Enhanced Key Usage) must permit Server Authentication | The certificate does not include the required EKU for Server Authentication (i.e. 1.3.6.1.5.5.7.3.1, see EKU is a text value or an array of text values that define Extended Key Usages (sometimes called Enhanced Key Usages) that the keys are intended for. The text values are Object Identifiers (OIDs). Commonly used ones include: for more information). | Create a certificate with the correct EKU value of 1.3.6.1.5.5.7.3.1(accessible from the EKU list).
The certificate has expired or is not yet valid | The certificate is outside its valid date range (expired or not yet valid). | Renew the certificate if expired, or create a new certificate with a valid start date.

EKU is not a value directly accessible from the VTScada UI, it is simply provided here as a potential cause for error.


Licensing

The following is a summary. For detailed information about VTScada licensing, refer to https://www.vtscada.com/software-licensing.

License Classes

The following is a brief guide to the various classes of license. Contact Trihedral Engineering for detailed descriptions of each class. License terms may change. In the event of a difference between the following and the current license terms, the current terms will have priority.

Development Licenses

Anyone who is creating applications will need a development license. (See following note about VTScadaLIGHT.)

Runtime Licenses

An installation with a runtime license may run an application, but has limited ability to modify or further develop that application.

To check whether a license is Runtime or Development / Configuration, refer to the page within App. Config. -> Information

Demo Keys

Trihedral Engineering provides demo keys to customers who wish to evaluate the software before purchase and to students attending our courses (*). These enable all features, but will shut down after a few hours of continuous use and will expire at the end of 60 or 90 days. (* Students who have a development license should use that, not the demo key.)

A customer who starts to create an application using a demo key, then purchases a development license, can continue to build their application using the development license. No further development work should be done under a demo license.

An application created or edited using a demo key must be run once under a development license before it can be used on a workstation with a runtime license.

Changes made to the application using a demo license cannot be applied via ChangeSet to copies of the application running a licensed copy of VTScada. This rule applies to both development licenses and runtime licenses.

License Features

Your license key determines which of the following features are enabled:

Development Runtime version | Runtime only version
VTScadaLIGHT version1 | SupportPlus period
Alarm Notification System1 | Remote Data Access
OPC Server* | Application Version Control
Remote Configuration | Redundancy Capability1
Server Capability1 | Custom Installation
Remote Idea Studio |

Your license key also determines the extent of the following features:

Number of I/O tags Number of allowed Thin Client1 connections

VTScadaLIGHT Installations

1 VTScadaLIGHT installations are any that are installed without a license key. The same installation file is used as with a paid installation. Note the following limitations:

  • A maximum of 50 I/O across all running applications.
    (Unlimited tags that do not perform input or output.)
  • A maximum of one Thin Client connection.
  • A VPN is required for Thin Client access.
  • VTScadaLIGHT installations can be servers for other VTScadaLIGHT workstations but applications that run on full VTScada workstations (development or runtime license) cannot be networked with workstations that have VTScadaLIGHT installed.
  • The Alarm Notification system cannot be enabled.
  • A maximum of 10 free VTScadaLIGHT installations. OEMs or Integrators who need additional application license packs should contact Trihedral for pricing.
  • The VTScadaLIGHT download does not include the VTScada ODBC driver, which is needed to query VTScada data using a 3rd party ODBC-compatible reporting tool.


Hook for Form Timestamps

You can specify a timestamp for the form widgets without using the Date Time Selector widget by using the hook module GetFormTimeStampHook(FormStruct, Timestamp, PageObj)

By using this hook module, you can create a custom date picker or return a custom timestamp based on specialized time offset calculations. The current Form widget options for Time Offset and Time Unit are limited to predefined configurations. GetFormTimestampHook can add custom logic, including using Month and Year tags.

Parameter Details:

  • FormStruct has a TimeOffset field that the hook should use. It is the offset from the associated timestamp in seconds.

  • Timestamp - This will be the Timestamp on the Date Time Selector, if one is present.

  • PageObj - The form page.

Procedure

The module can reside either directly in the Page or in the AppRoot.

Create a module called "GetFormTimestampHook".

The module must take the three parameters: FormStruct, Timestamp, PageObj.

  • The hook module must be stable in steady state.

  • If FormStruct is Invalid, the hook module should return the relative timestamp.

  • The Timestamps returned by the hook module must be in UTC.

  • Clicking the submit button should not log an event in the following cases:

    • On a page with only a submit button.

    • On a page with a submit button and a form widget that is unlinked and not included in a form.

    • On a page with a submit button and a form widget that is unlinked and included in a form.

  • Clicking the submit button should log an event in the following cases:

    • On a page with a submit button and a form widget that is linked to a tag and included in a form.

    • On this page, if a Date Time Selector is added, then the Description column on the logged event should say "Form submitted " and mention the date and time, specified on the Date Time Selector.

    • If no Date Time Selector is present on the page, then the Description column would simply say "Form submitted".

    • The Name and Area columns in the logged event will correspond to the values entered in the Event Name and Event Area fields in the Submit button's config panel. If Event Name and Event Area are not provided, the Name will default to the page’s translated title, and the Area will be set to "Forms".

Examples:

<
{=========== GetFormTimestampHook ==========================}
{ Called when the submit button is clicked. This module will be called once   }
{ for every widget on the page that is included in the form. This module         }
{ should return a timestamp based on the properties of the FormEntry           }
{ structure.                                                                                                        }
{==========================================================}
GetFormTimestampHook
(
  FormEntry           { Structure of form data related to the widget            };
  Timestamp          { Timestamp drawn on the page                                };
  PageObj              { Object of page                                                        };
)

[
  PROTECTED FormMonth;
  PROTECTED FormYear;
  PROTECTED DateInDays;
  PROTECTED DateInSeconds;
  PROTECTED LocalOffset;
]

GetFormTimestamp [
  FormMonth = Scope(\VTSDB, "MonthOfForm").Value;
  FormYear  = Scope(\VTSDB, "YearOfForm" ).Value;

  If Watch(1, FormEntry, Timestamp, PageObj, FormYear, FormMonth);
  [
    LocalOffset   = PickValid(FormEntry.TimeOffset, 0);
    DateInDays    = DateNum(1, FormMonth, FormYear);
    DateInSeconds = (DateInDays * 86400) + LocalOffset;
    Return(ConvertTimeStamp(DateInSeconds, 0 { Local time }, TRUE, Invalid { UTC }));

  ]
]

{ End of GetFormTimestampHook }
>


CIPMaxNumberofSessions

Deprecated.

Set the maximum numbers of CIP Connections a user can select within the Rockwell Driver Tag.

If the number of CIP connections multiplied by the maximum CIP packet size of 476 is greater than 16K, then you may need to use the configuration property, TCPIPPortMaxXmtLen to increase the TCP/IP port's buffer size.”

Section: System

Default: CIPMaxNumberofSessions = 128


DNP3DefaultNoScan

Controls whether addresses without a suffix are treated as event-based polling or standard polling.

New applications from 12.1.39 onwards have this property set to 1. Legacy applications will have it undefined, which is the same as 0. You can choose to update your legacy application by adding this property.

For existing applications, addresses without a suffix will always use standard polling. To use event-based polling, :NS is required.

Addresses without a suffix

Polling will be event-based, unless the object itself does not support events, such as Time and Date, File Transfer.
New data is returned by Class polling or unsolicited messages whenever the value in the device changes beyond the constraints of deadband and debounce settings..

Addresses with :DR

Will use the standard VTScada interval-based polling, returning the current value of the point.

Addresses with :NS

Treated the same as addresses with no suffix.

Section: Application

Default: DNP3DefaultNoScan = 1

*No restart required (Settings.Dynamic property)


PageWinOpt

This is a page variable, found only in the source code of a VTScada page. It is not a setting and will be ignored if added to your Settings.Dynamic or Settings.Startup file. (New developers frequently ask about this variable, therefore it is described in this section for sake of easier discovery.)

The PageWinOpt variable overrides the Style parameter options used for windowed pages. (Refer to the Window function for a description of the style parameter options.) Note that bits are counted from right to left and that examples you may see in pages often exclude the unset bits to the left of the highest numbered bit being set.

Related information:

Working with Pages

Window


ReportMaxDataSets

The maximum number of Data Sets that you can save in a report.

Section: System

Default: ReportMaxDataSets = 30

*No restart required (Settings.Dynamic property)

Related information:

Data Sets


AlignmentParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper of ParameterEdit which makes for easy addition of a ParameterEdit control to a panel for selecting tags
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | ParameterEdit | ColorParameterEdit | NumericParameterEdit |TagParameterEdit | TextParameterEdit
Format: | \AlignmentParameterEdit(Left, Bottom, Right, Top, ParmVal, ParmDef, Title, PtrWaitClose, DialogRoot, PTypeIdx, TitleWidth, ShowDrawnTagProperty, ID[, IsVAlign ])
Parameters: |
Left
Required. Any numeric expression for the left edge of the object.
Bottom
Required. Any numeric expression for the bottom edge of the object.
Right
Required. Any numeric expression for the right edge of the object.
Top
Required. Any numeric expression for the top edge of the object.
ParmVal
Required. The parameter value to be altered.
Typically, one element of the array of Parms passed to the panel.
ParmDef
Required. The parameter defining structure.
Typically, one element of the array of parameter definition structures.
Title
The title to display
PtrWaitClose
Wait to close
Typically provided by the panel module.
DialogRoot
Root dialog calling this control
Typically provided by the panel module.
PTypeIdx
Index of the Parameter type selection
TitleWidth
Optional, number of pixels allotted for the width of the title.
ShowLinkedTagProperty
Optional Boolean. Set true to show "Linked Tag Property". Defaults to TRUE
ID
Focus ID
IsVAlign
Optional. TRUE to display VAlign instead of HAlign. Default is FALSE
Comments:

...

Example:

 {***** HorizontalAlignment *****}
  ParmEditObj[2] = AlignmentParameterEdit(0 + Space                        { Placement coordinate                          },
                                          PEBottom[1] + Space + TabHt      { Placement coordinate                          },
                                          #PanelWd - Space                 { Placement coordinate                          },
                                          PEBottom[1] + Space              { Placement coordinate                          },
                                          Parms[#HorizAlign]               { The Parameter value to alter                  },
                                          ParmDefs[#HorizAlign]            { The code pointer to the parameter             },
                                          GetPhrase("HorizAlignmentLabel") { The title to display                          },
&(SubWaitClose[2])               { Wait to close                                 },
                                          DialogRoot                       { Root dialog calling this control              },
                                          0                                { Index of the Parameter type selection         },
                                          TitleWidth                       { Width alloted for the Title                   },
                                          Invalid                          { True to show "Drawn Tag Property"
                                                                             Default = TRUE                                },
                                          1                                { Focus ID                                      },
                                          FALSE                            { Optional flag, TRUE to display VAlign instead
                                                                             of HAlign. Default = FALSE                    });


ColorParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper of ParameterEdit which makes for easy addition of a ParameterEdit control to a panel for selecting colors
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | ParameterEdit | NumericParameterEdit | TagParameterEdit | TextParameterEdit
Format: | \ColorParameterEdit(Left, Bottom, Right, Top, ParmVal, ParmCodePtr, Title, PtrWaitClose, DialogRoot, PTypeIdx, TitleWidth, ShowLinkedTagProperty, ID[, ShowStyleSettings, StyleSettings, StyleColorName, DisableAlpha])
Parameters: |
Left
Required. Any numeric expression for the left edge of the object.
Bottom
Required. Any numeric expression for the bottom edge of the object.
Right
Required. Any numeric expression for the right edge of the object.
Top
Required. Any numeric expression for the top edge of the object.
ParmVal
Required. The parameter value to be altered.
Typically, one element of the array of Parms passed to the panel.
ParmCodePtr
Required. The code pointer to the parameter.
Typically, one element of the array of parameter definition structures.
Title
The title to display
PtrWaitClose
Wait to close
Typically provided by the panel module.
DialogRoot
Root dialog calling this control
Typically provided by the panel module.
PTypeIdx
Index of the Parameter type selection
TitleWidth
The number of pixels allotted for the width of the title.
ShowLinkedTagProperty
Optional Boolean. Set true to show "Linked Tag Property". Defaults to TRUE
ID
Focus ID
ShowStyleSettings
Optional. True to show "Style Settings" def = TRUE
StyleSettings
Optional. StyleSettings tag object
StyleColorName
Optional. Name of the StyleSettings color to use
DisableAlpha
Optional. Flag for disabling alpha field
Comments:

Be careful when setting “ShowStyleSettings” that the color being edited is related to style setting tags.

Example:

{***** Color *****}
ParmObj[4] = ColorParameterEdit(0 + Space   { Placement coordinate                     },
               PEBottom[4] + Space + TabHt  { Placement coordinate                     },
               #PanelWd - Space             { Placement coordinate                     },
               PEBottom[4] + Space          { Placement coordinate                     },
               Parms[#Color]                { The Parameter value to alter             },
               ParmDefs[#Color]             { The code pointer to the parameter        },
               GetPhrase("TextLabel")       { The title to display                     },
               &(SubWaitClose[4])           { Wait to close                            },
               DialogRoot                   { Root dialog calling this control         },
               0                            { Index of the Parameter type selection    },
               TitleWidth                   { Width allotted for the Title             },
               TRUE                         { True to show "Drawn Tag Property";
                                               default = TRUE                          },
               1                            { Focus ID                                 },
               FALSE                        { True to show "Style Settings" def = TRUE });


DrawQRCode

(Engine-Level Function)

Description: | Draw a QRCode at a given location.
Returns: | Graphic
Usage: | Steady State only.
Function Groups: | Graphics
Related to: | | GenerateQRCode |
Format: | DrawQRCode(QRCode[, XOff, YOff, Size, Color, Space])
Parameters: |
QR Code
QRCode returned from GenerateQRCode (array)
XOff
X coordinate. Default = 0 (left)
YOff
Y coordinate. Default = 0 (top)
Size
Square size in pixels. Default = 6
Color
Dark square color. Default = 0 (black)
Space
Space between squares. Default = 0
Comments:

Waits for a valid QRCode returned from GenerateQRCode. Draws a 5x5 grid for the QR code. Squares are drawn 25 at a time to preserve performance.

The default color is black. The colored squares are drawn, the white spaces are not drawn, the background color fills in the negative space.

Examples:

Steady-state example

Main [
  Code = System.GenerateQRCode("https://www.vtscada.com/" { Input }, 2 { Error correction level });
  System.DrawQRCode(Code, 300, 300, Size, Color, Space);
]

Script example

Init [
  If 1 Main;
  [
    Code = System.GenerateQRCode("https://www.vtscada.com/" { Input }, 2 { Error correction level });
  ]
]

Main [
  System.DrawQRCode(Code, 300, 300, Size, Color, Space);
]


GenerateQRCode

(Engine-Level Function)

Description: | Returns a 2D array which represents a QR code for a given string.
Returns: | Array
Usage: | Script or steady state.
Function Groups: | Array
Related to: | | DrawQRCode |
Format: | GenerateQRCode(Input[, ECL])
Parameters: |
Input
Buffer for which to generate the QR code
ECL
Error Correction Level, 0 to 3. Default = 0
Comments:

GenerateQRCode will encode any string, so long as that string is shorter than the maximum length for its type.

The maximums will be lower if a non-zero error correction level is selected. With an ECL of 0, the maximums are:

Type | Definition | Maximum
Numerics | 0 - 9 | 7089 characters
Alphanumerics | 0 - 9, A - Z, Some special characters. | 4296 characters
Binaries | All ascii characters | 2953 characters.

A higher ECL will allow more of the QR code to be obscured while still correctly scanning. The level must be an integer, 0 to 3 inclusive.

This function will return metadata even if the returned array is invalid.
The returned metadata includes Error, Mode, Version, ECL, Bytes, Dimension, Mask, and Penalty.

If GenerateQRCode returns Invalid, check the error code.
There are two possible errors:

1 = Bad parameters.
2 = Too many characters.

Examples:

Steady-state example

Main [
  Code = System.GenerateQRCode("https://www.vtscada.com/" { Input }, 2 { Error correction level });
  System.DrawQRCode(Code, 300, 300, Size, Color, Space);
]

Script example

Init [
  If 1 Main;
  [
    Code = System.GenerateQRCode("https://www.vtscada.com/" { Input }, 2 { Error correction level });
  ]
]

Main [
  System.DrawQRCode(Code, 300, 300, Size, Color, Space);
]


TagParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper of ParameterEdit which makes for easy addition of a ParameterEdit control to a panel for selecting tags
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | ParameterEdit | ColorParameterEdit | NumericParameterEdit | TextParameterEdit | DurationParameterEdit
Format: | \TagParameterEdit(Left, Bottom, Right, Top, ParmVal, ParmCodePtr, Title, PtrWaitClose, DialogRoot, PTypeIdx, TitleWidth, ShowLinkedTagProperty, ID[, TagType, DefaultText, MissingText, TagObj] )
Parameters: |
Left
Required. Any numeric expression for the left edge of the object.
Bottom
Required. Any numeric expression for the bottom edge of the object.
Right
Required. Any numeric expression for the right edge of the object.
Top
Required. Any numeric expression for the top edge of the object.
ParmVal
Required. The parameter value to be altered.
Typically, one element of the array of Parms passed to the panel.
ParmCodePtr
Required. The code pointer to the parameter.
Typically, one element of the array of parameter definition structures.
Title
Required. The title to display
PtrWaitClose
Wait to close
Typically provided by the panel module.
DialogRoot
Root dialog calling this control
Typically provided by the panel module.
PTypeIdx
Index of the Parameter type selection
TitleWidth
Number of pixels allotted for the width of the title.
ShowLinkedTagProperty
Set true to show "Linked Tag Property". Defaults to TRUE
ID
Focus ID
TagType
Optional. Tag type or group
DefaultText
Optional text to display in place of "No tag selected"
MissingText
Optional text to display in place of "--Missing--"
TagObj
Optional. [OUT] Resolved tag object
Comments:

...

Example:

ParmEditObj[0] = TagParameterEdit(0 + Space       { Placement coordinate                          },
                    EditHt + Space + TitleSpace   { Placement coordinate                          },
                    #PanelWd - Space              { Placement coordinate                          },
                    Space + TitleSpace            { Placement coordinate                          },
                    Parms[#FontParm]              { The Parameter value to alter                  },
                    ParmDefs[#FontParm]           { The code pointer to the parameter             },
                    GetPhrase("FontLabel")        { The title to display                          },
                    &(SubWaitClose[0])            { Wait to close                                 },
                    DialogRoot                    { Root dialog calling this control              },
                    Invalid                       { Index of the Parameter type selection         },
                    TitleWidth                    { Width alloted for the Title                   },
                    TRUE                          { True to show "Drawn Tag Property";
                                                    default = TRUE                                },
                    1                             { Focus ID                                      },
                    "FontValue"                   { Tag type or group                             },
                    GetParmPhrase("NoPointLabel", #SYSTEM_STYLE) { Text to display in place of No tag selected   },
                    GetParmPhrase("NoPointLabel", #SYSTEM_STYLE) { Text to display in place of --Missing--       });


TextParameterEdit

(VTScada-Layer function. Must be called with a leading backslash.)

Description: | Wrapper of ParameterEdit which makes for easy addition of a ParameterEdit control to a panel for selecting text.
Returns: | Self
Usage: | Steady State only.
Function Groups: | Basic Module, Variable
Related to: | ParameterEdit | ColorParameterEdit | NumericParameterEdit | TagParameterEdit
Format: | \TextParameterEdit(Left, Bottom, Right, Top, ParmVal, ParmCodePtr, Title, PtrWaitClose, DialogRoot, PTypeIdx, TitleWidth, ShowDrawnTagProperty, ID[, Translate, ToolTitleWidthOut, Description, NLines])
Parameters: |
Left
Required. Any numeric expression for the left edge of the object.
Bottom
Required. Any numeric expression for the bottom edge of the object.
Right
Required. Any numeric expression for the right edge of the object.
Top
Required. Any numeric expression for the top edge of the object.
ParmVal
Required. The parameter value to be altered.
Typically, one element of the array of Parms passed to the panel.
ParmCodePtr
Required. The code pointer to the parameter.
Typically, one element of the array of parameter definition structures.
Title
The title to display
PtrWaitClose
Wait to close
Typically provided by the panel module.
DialogRoot
Root dialog calling this control
Typically provided by the panel module.
PTypeIdx
Index of the Parameter type selection
TitleWidth
The number of pixels allotted for the width of the title.
ShowDrawnTagProperty
Boolean. Set true to show "Drawn Tag Property". Defaults to TRUE
ID
Focus ID
Translate

Optional. Controls how translation should be handled:

0 - Use text as it is entered

1 - Use PhraseID Wrapped in GetPhrase() (Default)

2 - Use PhraseID not wrapped in GetPhrase()

ToolTitleWidthOut
Optional. [OUT] Width of ParmEdit's tool and title
Description
Optional text describing this parameter
NLines
Optional. Height of the edit field; defaults to 2 lines
Comments:

...

Example:

 { Label }
PEObj[0] = TextParameterEdit(2*Space,
                             2*EditHt,
                             #PanelWd,
                             0,
                             Parms.ButtonLabel,
                             ParmDefs.ButtonLabel,
                             GetPhrase("LabelLabel"),
                             &SubWaitClose[0],
                             DialogRoot,
                             0,
                             TitleWd,
                             TRUE,
                             1 { FID },
                             0 { Use text as it is entered },
                             Invalid,
                             Invalid,
                             1 { NLines });